企业官网建设流程全解析

Flower 模拟引擎退出码 701 SIMULATION_MISSING_EXTRA：成因排查与在 pyproject.toml 中的标准修复方案

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower

导读

本篇文章围绕 Flower 框架（Friendly Federated AI Framework）模拟引擎（Simulation Engine）的退出码 701SIMULATION_MISSING_EXTRA展开，结合 退出码官方文档 与框架源码，说明该错误出现的根本原因、在源码中触发的位置、以及如何通过为应用声明flwr[simulation]额外依赖来彻底修复。读完本文，你将掌握模拟后端依赖的声明方式、Ray 依赖的版本与平台约束、以及运行时依赖自动安装机制对该错误的影响，从而在本地开发与云端部署 Flower 应用时快速定位并解决此类启动失败问题。

退出码 701 是什么

退出码 701SIMULATION_MISSING_EXTRA的含义非常直接：运行模拟（Simulation）所需的额外依赖缺失（Extra dependencies required for simulation are missing）。

在 Flower 框架中，退出码由 framework/py/flwr/supercore/exit/exit_code.py 中的ExitCode类统一集中管理。从源码注释可以看到，Flower 的退出码按组件分区间编排：

• 0-99：成功与优雅退出（如SIGINT、SIGTERM）
• 100-199：SuperLink 相关
• 200-249：ServerApp 相关
• 250-299：ClientApp 相关
• 300-399：SuperNode 相关
• 400-499：SuperExec 相关
• 500-599：Flower CLI 相关
• 600-699：通用退出码
• 700-799：模拟（Simulation）相关退出码
• 800-899：任务进程相关

其中700是SIMULATION_EXCEPTION（模拟运行中未处理异常），701即SIMULATION_MISSING_EXTRA，同属模拟引擎的故障类别。源码中对应定义如下：

# Simulation exit codes (700-799) SIMULATION_EXCEPTION = 700 SIMULATION_MISSING_EXTRA = 701

同时，EXIT_CODE_HELP字典为 701 提供了面向用户的简短帮助文本：

ExitCode.SIMULATION_MISSING_EXTRA: """ Extra dependencies required for simulation are missing. To use simulation with the Ray backend, add `flwr[simulation]` to the app's `pyproject.toml` dependencies, then install the dependencies manually unless automatic runtime dependency installation is enabled. """

也就是说，当你以 Ray 作为模拟后端启动 Flower 模拟时，如果环境中找不到 Ray 包，Flower 会立即终止进程并以 701 退出。

该错误在源码中的触发位置

要真正理解这个错误，需要回到模拟引擎的入口实现。Flower 的模拟运行器位于 framework/py/flwr/simulation/run_simulation.py，其中_run_simulation函数在启动阶段会做一次前置依赖检查：

# Exit early if the `ray` dependency is missing if backend_name == "ray": if importlib.util.find_spec("ray") is None: flwr_exit( code=ExitCode.SIMULATION_MISSING_EXTRA, event_type=exit_event, event_details={"success": False}, )

这段代码的逻辑非常清晰：

1. 只有当backend_name == "ray"时才会触发检查——即默认的模拟后端。
2. 通过importlib.util.find_spec("ray")探测当前 Python 环境中是否存在ray模块。
3. 如果探测不到，就调用flwr_exit()以退出码 701 终止进程，并上报success: False的遥测事件。

flwr_exit 的退出输出格式

flwr_exit定义于 framework/py/flwr/supercore/exit/exit.py，它会在终端中输出如下结构的诊断信息：

Exit Code: 701 Extra dependencies required for simulation are missing. To use simulation with the Ray backend, add `flwr[simulation]` to the app's `pyproject.toml` dependencies, then install the dependencies manually unless automatic runtime dependency installation is enabled. For more information, visit: <帮助页 URL>

从实现上看，非成功退出码（code >= 100）会被判定为错误，日志级别设为ERROR，进程以系统退出码1结束，并在末尾附加指向对应退出码文档页的链接。这也是为什么你能在日志中同时看到清晰的错误描述和文档指引。

标准修复方案：在 pyproject.toml 中声明 flwr[simulation]

根据 701 退出码文档，修复方法是在应用的pyproject.toml依赖中，将flwr连同simulation额外依赖（extra）一起声明：

[project] dependencies = [ "flwr[simulation]", ]

simulation extra 实际会安装什么

simulation并不是一个空的标签，它在框架自身的 framework/pyproject.toml 中被定义为：

[project.optional-dependencies] simulation = [ "ray==2.55.1; python_version >= '3.11' and python_version < '3.13'", "ray==2.55.1; python_version >= '3.13' and python_version < '3.15' and sys_platform != 'win32'", ]

从这份声明可以看出两个关键事实：

1. flwr[simulation]的实质就是安装ray，因此把flwr[simulation]加入应用依赖后，importlib.util.find_spec("ray")的检查就会通过，退出码 701 不再出现。
2. Ray 的版本与平台约束非常严格：当前仓库锁定ray==2.55.1，并且要求 Python 版本在>=3.11且<3.15的区间内；对于 Python>=3.13的情况，Windows 平台（sys_platform == 'win32'）并不支持，会被条件表达式排除。因此，如果应用运行在不满足条件的 Python 版本或操作系统上，即使声明了flwr[simulation]也可能无法真正获得ray依赖，此时需要先调整运行环境。

仓库内的真实示例也印证了这一用法，例如 examples/advanced-pytorch/pyproject.toml 中声明：

dependencies = [ "flwr[simulation]>=1.28.0", # ... ]

在 examples/federated-vae/pyproject.toml、examples/fedrag/pyproject.toml、examples/custom-mods/pyproject.toml 等示例中也都采用了相同的flwr[simulation]声明模式。

修复后的安装与重试

修改完pyproject.toml后，需要执行安装步骤：

pip install -e . # 或者使用 uv uv sync

Flower 官方文档特别强调：除非启用了自动运行时依赖安装（automatic runtime dependency installation），否则必须手动安装应用依赖后再重试。这一提示与框架源码中的行为是一致的。

运行时依赖自动安装与 701 的关系

在 Flower 的模拟应用中，framework/py/flwr/simulation/app.py 负责从 FAB 安装应用并决定是否自动安装依赖。源码中有一段针对该错误的重要补充逻辑：

if runtime_dependency_install: # ... 自动安装应用依赖 ... if backend_name == "ray" and importlib.util.find_spec("ray") is None: # Surface unsupported Ray/Python/platform combinations as dependency # installation failures instead of missing simulation extras. raise RuntimeDependencyInstallationError( "Runtime dependency installation completed, but `ray` is not " "available. Ensure your OS+Python combination supports `ray`." )

这段代码说明：

• 当启用自动运行时依赖安装时，Flower 会尝试为应用自动安装pyproject.toml中声明的依赖；
• 如果安装完成后ray依然不可用，框架会将其归类为RuntimeDependencyInstallationError（运行时依赖安装失败），并提示检查OS 与 Python 组合是否支持 Ray——这正好对应上文提到的ray依赖声明中平台与版本条件的限制；
• 如果未启用自动安装（或自动安装不可用），则必须手动执行pip install -e .之类的安装命令。

实战排查清单

遇到退出码 701 时，可以按以下顺序快速定位：

1. 检查声明：确认应用的pyproject.toml是否包含"flwr[simulation]"（或带版本号的flwr[simulation]>=...）。参考 701 退出码文档 中的标准写法。
2. 检查安装：在应用目录下执行pip show ray或python -c "import ray"，确认ray是否真实存在于当前环境中；若缺失，手动安装依赖后重试。
3. 检查环境兼容性：确认 Python 版本处于3.11 <= python < 3.15，且 Python>=3.13时不在 Windows 上运行，否则即使声明依赖也无法安装ray。
4. 检查后端配置：如果你显式指定了非 Ray 的模拟后端，701 不会触发；只有backend_name == "ray"（默认值）才会执行前置检查，见 run_simulation.py 中的条件判断。

延伸阅读

• 退出码 700SIMULATION_EXCEPTION与 701 同属模拟引擎故障区间，定义于 exit_code.py。
• 全部退出码文档收录在 framework/docs/source/ref-exit-codes 目录，并通过 framework/docs/source/ref-exit-codes-dir.rst 汇入框架参考文档的 reference.rst 索引。
• 模拟引擎的完整入口与 FAB 加载流程参见 framework/py/flwr/simulation/app.py，其 CLI 入口flwr-simulation在 framework/pyproject.toml 的[project.scripts]中注册。

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower