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

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、SIGTERM100-199SuperLink 相关200-249ServerApp 相关250-299ClientApp 相关300-399SuperNode 相关400-499SuperExec 相关500-599Flower 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 apps 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( codeExitCode.SIMULATION_MISSING_EXTRA, event_typeexit_event, event_details{success: False}, )这段代码的逻辑非常清晰只有当backend_name ray时才会触发检查——即默认的模拟后端。通过importlib.util.find_spec(ray)探测当前 Python 环境中是否存在ray模块。如果探测不到就调用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 apps 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 [ ray2.55.1; python_version 3.11 and python_version 3.13, ray2.55.1; python_version 3.13 and python_version 3.15 and sys_platform ! win32, ]从这份声明可以看出两个关键事实flwr[simulation]的实质就是安装ray因此把flwr[simulation]加入应用依赖后importlib.util.find_spec(ray)的检查就会通过退出码 701 不再出现。Ray 的版本与平台约束非常严格当前仓库锁定ray2.55.1并且要求 Python 版本在3.11且3.15的区间内对于 Python3.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 syncFlower 官方文档特别强调除非启用了自动运行时依赖安装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 OSPython combination supports ray. )这段代码说明当启用自动运行时依赖安装时Flower 会尝试为应用自动安装pyproject.toml中声明的依赖如果安装完成后ray依然不可用框架会将其归类为RuntimeDependencyInstallationError运行时依赖安装失败并提示检查OS 与 Python 组合是否支持 Ray——这正好对应上文提到的ray依赖声明中平台与版本条件的限制如果未启用自动安装或自动安装不可用则必须手动执行pip install -e .之类的安装命令。实战排查清单遇到退出码 701 时可以按以下顺序快速定位检查声明确认应用的pyproject.toml是否包含flwr[simulation]或带版本号的flwr[simulation]...。参考 701 退出码文档 中的标准写法。检查安装在应用目录下执行pip show ray或python -c import ray确认ray是否真实存在于当前环境中若缺失手动安装依赖后重试。检查环境兼容性确认 Python 版本处于3.11 python 3.15且 Python3.13时不在 Windows 上运行否则即使声明依赖也无法安装ray。检查后端配置如果你显式指定了非 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考