![Flower 框架退出码 [700] SIMULATION_EXCEPTION 详解：模拟运行时异常的含义、触发链路与排查指南](http://pic.xiahunao.cn/yaotu/Flower 框架退出码 [700] SIMULATION_EXCEPTION 详解：模拟运行时异常的含义、触发链路与排查指南)
Flower 框架退出码 [700] SIMULATION_EXCEPTION 详解模拟运行时异常的含义、触发链路与排查指南【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文是 Flower 框架官方退出码参考文档framework/docs/source/ref-exit-codes/700.rst的深度解读与实战扩展。退出码 700SIMULATION_EXCEPTION表示在运行 Flower 模拟Simulation时发生了未被捕获的异常是模拟任务失败时最常见的兜底退出码之一。读完本文你将理解 700 在退出码体系中的位置、它在源码中是如何被设置的、与 701/607/608 等相邻退出码的边界关系以及一套可落地的排查与修复流程。一、退出码 700 是什么在 Flower 框架中每个组件在退出进程时都会返回一个整数退出码用于向上层调度方如 SuperLink、SuperExec、命令行报告本次运行的结果。退出码定义集中在 exit_code.py 的ExitCode类中其中700-799 段专属于 Simulation模拟位于 exit_code.py# Simulation exit codes (700-799) SIMULATION_EXCEPTION 700 SIMULATION_MISSING_EXTRA 701官方文档对该退出码的定义为An unhandled exception occurred when running the simulation.运行模拟时发生了一个未被处理的异常。也就是说700 是一个通用兜底错误码当模拟进程的主流程抛出了异常而该异常又无法被归类为更具体的错误类型时Flower 统一以SIMULATION_EXCEPTION结束进程。所有退出码及其短帮助文本short help message的完整索引见 ref-exit-codes-dir.rst各组件退出码按如下区间划分区间归属组件示例0-99成功 / 信号退出0 SUCCESS100-199SuperLink101 SUPERLINK_LICENSE_INVALID200-249ServerApp200 SERVERAPP_STRATEGY_PRECONDITION_UNMET250-299ClientApp250 CLIENTAPP_COMMUNICATION_ERROR300-399SuperNode302 SUPERNODE_NODE_AUTH_KEY_INVALID400-499SuperExec402 SUPEREXEC_INVALID_EXECUTOR_CONFIG500-599FlowerCLI500 FLWRCLI_NODE_AUTH_PUBLIC_KEY_INVALID600-699通用多组件共享607 COMMON_APP_IMPORT_ERROR700-799Simulation700 SIMULATION_EXCEPTION800-899Task Process800 TASK_PROC_EXCEPTION二、源码视角700 是在哪里、如何被设置的只看退出码定义还不够理解 700 的关键在于它什么时候被触发。Flower 的模拟进程入口位于 framework/py/flwr/simulation/app.py其核心逻辑如下为便于阅读已精简# app.py 中的 run_flwr_simulation 主流程 exit_code ExitCode.SUCCESS # 第 174 行默认视为成功 try: # 1. 建立与 SuperLink 的 SimulationIo 连接、拉取任务输入 # 2. 启动心跳与日志上传 # 3. 安装 FABFlower App Bundle并安装应用依赖 # 4. 读取 pyproject.toml 配置加载 ClientApp / ServerApp # 5. 调用 _run_simulation 启动模拟 ... except Exception as ex: # 第 357 行捕获一切异常 exc_entity Simulation log(ERROR, %s raised an exception, exc_entity, exc_infoex) sub_status SubStatus.FAILED details fSimulation failed with exception: {str(ex)} # 默认退出码SIMULATION_EXCEPTION exit_code ExitCode.SIMULATION_EXCEPTION if isinstance(ex, ImportError): exit_code ExitCode.COMMON_APP_IMPORT_ERROR # 607 elif isinstance(ex, RuntimeDependencyInstallationError): exit_code ExitCode.COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR # 608 flwr_exit( codeexit_code, event_typeEventType.FLWR_SIMULATION_RUN_LEAVE, ... )从这段代码可以提炼出三个重要结论700 是兜底退出码主流程中任何未被专门分类的Exception都会被捕获并映射为 700同时将sub_status置为SubStatus.FAILED并把异常字符串写入details字段。同类异常会被升级为更精确的退出码若异常是ImportError应用导入失败则返回607若异常是RuntimeDependencyInstallationError依赖安装失败则返回608。这解释了为什么同样是模拟失败你可能会看到不同的退出码——它们都是模拟异常只是被归类到了更细的粒度。进程退出前会推送任务输出flwr_exit触发FLWR_SIMULATION_RUN_LEAVE事件并执行注册的on_exit处理器将sub_status、details、运行上下文等通过PushTaskOutput回传给 SuperLink。因此 700 出现时运行记录中通常同时带有 FAILED 状态和异常详情字符串这是排查的第一手数据。三、与相邻退出码的区分701 / 607 / 608700 常与以下三个邻居混淆先厘清边界能大幅缩短定位时间退出码名称触发条件解决要点700SIMULATION_EXCEPTION模拟主流程中的任意未分类异常查看日志中的具体异常栈701SIMULATION_MISSING_EXTRA模拟所需的可选依赖如 Ray缺失在pyproject.toml中声明flwr[simulation]607COMMON_APP_IMPORT_ERROR加载 ClientApp/ServerApp 时发生ImportError补全应用依赖后重试608COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR运行时安装应用依赖失败检查日志中的安装错误详情其中701与 700 同属 Simulation 段见 701.rst专门处理模拟必需的可选依赖缺失这一高频问题。其标准修复方式是在应用的pyproject.toml中声明dependencies [ flwr[simulation], ]然后重新安装应用依赖除非已启用自动运行时依赖安装并重试。可以推断模拟进程在 app.py 中还会主动检查 Ray 是否可用——当后端为ray但importlib.util.find_spec(ray)返回None时会抛出RuntimeDependencyInstallationError对应 608避免模拟启动到一半才发现缺少 Ray的尴尬。四、How to Resolve官方给出的三条排查路径原文档 700.rst 给出了三条排查步骤下面逐条展开1. 确保 SuperExec 环境依赖完整且配置正确退出码 700 的描述明确指出模拟任务由SuperExec环境负责启动。因此第一步不是改业务代码而是检查启动模拟的执行环境依赖是否齐全确认环境中安装了应用FAB所需的全部 Python 包。若使用模拟还应确认flwr[simulation]及其依赖尤其是 Ray可用Flower 官方在 how-to-run-simulations.rst 中提示Simulation Runtime 构建于 Ray 之上Flower 完整支持 Linux 与 macOSWindows 上 Ray 支持仍为实验性建议使用 WSL2。配置是否正确检查 SuperExec 的插件配置、executor 配置是否有效对应退出码 400-402 的范畴若配置本身非法会在进入模拟前就失败。版本是否匹配若模拟客户端与 SuperLink 之间存在运行时版本不兼容可能映射为 606RUNTIME_VERSION_INCOMPATIBLE升级 Flower 版本后重试。2. 审查模拟日志定位具体异常700 本身只是一个类别标签真正有价值的是日志中携带的异常栈与 details 字符串。排查建议在模拟进程日志中搜索Simulation raised an exception对应源码 app.py 中的log(ERROR, ...)及其后的exc_info堆栈关注details字段源码将其设置为fSimulation failed with exception: {str(ex)}该字符串会随PushTaskOutput回传给调度方可在运行记录中直接查看根据堆栈顶层异常类型分流处理例如ImportError/ModuleNotFoundError→ 缺少依赖参考 607 的语义处理Ray 相关异常连接失败、Actor 启动失败、资源不足→ 检查 Ray 集群状态与资源设置模型/数据加载异常 → 回到应用代码本身排查。3. 查阅模拟运行指南规避常见陷阱官方维护的 如何运行模拟 指南总结了大量实操细节与 FAQ其中与 700 直接相关的常见陷阱包括资源设置不当导致 OOMnum_cpus/num_gpus仅用于控制后端可创建的 worker 数量并不会真正限制单个ClientApp的内存使用。若 GPU 上触发 OOM官方建议先将num_gpus1让单个ClientApp独占 GPU用nvidia-smi观察 VRAM 占用后反推合理的num_gpus值使用 TensorFlow 时还应预先导出TF_FORCE_GPU_ALLOW_GROWTH1。多模拟共享资源同一台机器上并行多个模拟时各模拟互不知晓对方资源占用使用 GPU 时应通过CUDA_VISIBLE_DEVICES隔离。后端资源与硬件不匹配在多节点场景下可通过ray start --num-cpusN --num-gpusN显式声明节点可提供的资源避免模拟调度时因资源判定偏差而异常。ServerApp 的额外开销Simulation Runtime 只管理ClientApp若 ServerApp 本身如聚合后的全局模型评估也占用大量 CPU/GPU需在设置num_cpus/num_gpus时一并计入。五、典型排查流程可直接照做综合源码与官方文档当模拟任务以退出码 700 结束时推荐按以下顺序操作# 1. 确认模拟相关依赖已安装缺失时优先得到 701/608 pip install -U flwr # 若项目使用模拟后端 Ray确认其可用 python -c import ray; print(ray.__version__) # 2. 以更高日志级别重新运行模拟捕获完整堆栈 flwr run your-app --verbose先看日志定位Simulation raised an exception及异常堆栈判断是业务代码异常还是框架层异常再查依赖若堆栈指向ModuleNotFoundError对照应用的pyproject.toml补全依赖模拟场景确保声明了flwr[simulation]后调资源若异常与 Ray 或 OOM 相关参照上文 FAQ 调整num_cpus/num_gpus必要时为多节点模拟配置 Ray 集群确认环境核对 SuperExec 环境的 Python 版本、系统平台Linux/macOS 优先Windows 建议 WSL2与 Flower 版本一致性。六、小结退出码700 SIMULATION_EXCEPTION是 Flower 模拟运行失败时的通用兜底信号它表示模拟主流程抛出了未被分类的异常。通过 exit_code.py 可确认其定义与帮助文本通过 simulation/app.py 可还原其完整触发链路SUCCESS → 异常 → SIMULATION_EXCEPTION / 更精确的 607、608而官方 模拟运行指南 则提供了资源设置、多节点、OOM 等高频场景的规避方案。把握先看日志定位具体异常再对号入座选择修复路径这一原则绝大多数 700 问题都能在分钟级内解决。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flower 框架退出码 [700] SIMULATION_EXCEPTION 详解：模拟运行时异常的含义、触发链路与排查指南
Flower 框架退出码 [700] SIMULATION_EXCEPTION 详解模拟运行时异常的含义、触发链路与排查指南【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文是 Flower 框架官方退出码参考文档framework/docs/source/ref-exit-codes/700.rst的深度解读与实战扩展。退出码 700SIMULATION_EXCEPTION表示在运行 Flower 模拟Simulation时发生了未被捕获的异常是模拟任务失败时最常见的兜底退出码之一。读完本文你将理解 700 在退出码体系中的位置、它在源码中是如何被设置的、与 701/607/608 等相邻退出码的边界关系以及一套可落地的排查与修复流程。一、退出码 700 是什么在 Flower 框架中每个组件在退出进程时都会返回一个整数退出码用于向上层调度方如 SuperLink、SuperExec、命令行报告本次运行的结果。退出码定义集中在 exit_code.py 的ExitCode类中其中700-799 段专属于 Simulation模拟位于 exit_code.py# Simulation exit codes (700-799) SIMULATION_EXCEPTION 700 SIMULATION_MISSING_EXTRA 701官方文档对该退出码的定义为An unhandled exception occurred when running the simulation.运行模拟时发生了一个未被处理的异常。也就是说700 是一个通用兜底错误码当模拟进程的主流程抛出了异常而该异常又无法被归类为更具体的错误类型时Flower 统一以SIMULATION_EXCEPTION结束进程。所有退出码及其短帮助文本short help message的完整索引见 ref-exit-codes-dir.rst各组件退出码按如下区间划分区间归属组件示例0-99成功 / 信号退出0 SUCCESS100-199SuperLink101 SUPERLINK_LICENSE_INVALID200-249ServerApp200 SERVERAPP_STRATEGY_PRECONDITION_UNMET250-299ClientApp250 CLIENTAPP_COMMUNICATION_ERROR300-399SuperNode302 SUPERNODE_NODE_AUTH_KEY_INVALID400-499SuperExec402 SUPEREXEC_INVALID_EXECUTOR_CONFIG500-599FlowerCLI500 FLWRCLI_NODE_AUTH_PUBLIC_KEY_INVALID600-699通用多组件共享607 COMMON_APP_IMPORT_ERROR700-799Simulation700 SIMULATION_EXCEPTION800-899Task Process800 TASK_PROC_EXCEPTION二、源码视角700 是在哪里、如何被设置的只看退出码定义还不够理解 700 的关键在于它什么时候被触发。Flower 的模拟进程入口位于 framework/py/flwr/simulation/app.py其核心逻辑如下为便于阅读已精简# app.py 中的 run_flwr_simulation 主流程 exit_code ExitCode.SUCCESS # 第 174 行默认视为成功 try: # 1. 建立与 SuperLink 的 SimulationIo 连接、拉取任务输入 # 2. 启动心跳与日志上传 # 3. 安装 FABFlower App Bundle并安装应用依赖 # 4. 读取 pyproject.toml 配置加载 ClientApp / ServerApp # 5. 调用 _run_simulation 启动模拟 ... except Exception as ex: # 第 357 行捕获一切异常 exc_entity Simulation log(ERROR, %s raised an exception, exc_entity, exc_infoex) sub_status SubStatus.FAILED details fSimulation failed with exception: {str(ex)} # 默认退出码SIMULATION_EXCEPTION exit_code ExitCode.SIMULATION_EXCEPTION if isinstance(ex, ImportError): exit_code ExitCode.COMMON_APP_IMPORT_ERROR # 607 elif isinstance(ex, RuntimeDependencyInstallationError): exit_code ExitCode.COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR # 608 flwr_exit( codeexit_code, event_typeEventType.FLWR_SIMULATION_RUN_LEAVE, ... )从这段代码可以提炼出三个重要结论700 是兜底退出码主流程中任何未被专门分类的Exception都会被捕获并映射为 700同时将sub_status置为SubStatus.FAILED并把异常字符串写入details字段。同类异常会被升级为更精确的退出码若异常是ImportError应用导入失败则返回607若异常是RuntimeDependencyInstallationError依赖安装失败则返回608。这解释了为什么同样是模拟失败你可能会看到不同的退出码——它们都是模拟异常只是被归类到了更细的粒度。进程退出前会推送任务输出flwr_exit触发FLWR_SIMULATION_RUN_LEAVE事件并执行注册的on_exit处理器将sub_status、details、运行上下文等通过PushTaskOutput回传给 SuperLink。因此 700 出现时运行记录中通常同时带有 FAILED 状态和异常详情字符串这是排查的第一手数据。三、与相邻退出码的区分701 / 607 / 608700 常与以下三个邻居混淆先厘清边界能大幅缩短定位时间退出码名称触发条件解决要点700SIMULATION_EXCEPTION模拟主流程中的任意未分类异常查看日志中的具体异常栈701SIMULATION_MISSING_EXTRA模拟所需的可选依赖如 Ray缺失在pyproject.toml中声明flwr[simulation]607COMMON_APP_IMPORT_ERROR加载 ClientApp/ServerApp 时发生ImportError补全应用依赖后重试608COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR运行时安装应用依赖失败检查日志中的安装错误详情其中701与 700 同属 Simulation 段见 701.rst专门处理模拟必需的可选依赖缺失这一高频问题。其标准修复方式是在应用的pyproject.toml中声明dependencies [ flwr[simulation], ]然后重新安装应用依赖除非已启用自动运行时依赖安装并重试。可以推断模拟进程在 app.py 中还会主动检查 Ray 是否可用——当后端为ray但importlib.util.find_spec(ray)返回None时会抛出RuntimeDependencyInstallationError对应 608避免模拟启动到一半才发现缺少 Ray的尴尬。四、How to Resolve官方给出的三条排查路径原文档 700.rst 给出了三条排查步骤下面逐条展开1. 确保 SuperExec 环境依赖完整且配置正确退出码 700 的描述明确指出模拟任务由SuperExec环境负责启动。因此第一步不是改业务代码而是检查启动模拟的执行环境依赖是否齐全确认环境中安装了应用FAB所需的全部 Python 包。若使用模拟还应确认flwr[simulation]及其依赖尤其是 Ray可用Flower 官方在 how-to-run-simulations.rst 中提示Simulation Runtime 构建于 Ray 之上Flower 完整支持 Linux 与 macOSWindows 上 Ray 支持仍为实验性建议使用 WSL2。配置是否正确检查 SuperExec 的插件配置、executor 配置是否有效对应退出码 400-402 的范畴若配置本身非法会在进入模拟前就失败。版本是否匹配若模拟客户端与 SuperLink 之间存在运行时版本不兼容可能映射为 606RUNTIME_VERSION_INCOMPATIBLE升级 Flower 版本后重试。2. 审查模拟日志定位具体异常700 本身只是一个类别标签真正有价值的是日志中携带的异常栈与 details 字符串。排查建议在模拟进程日志中搜索Simulation raised an exception对应源码 app.py 中的log(ERROR, ...)及其后的exc_info堆栈关注details字段源码将其设置为fSimulation failed with exception: {str(ex)}该字符串会随PushTaskOutput回传给调度方可在运行记录中直接查看根据堆栈顶层异常类型分流处理例如ImportError/ModuleNotFoundError→ 缺少依赖参考 607 的语义处理Ray 相关异常连接失败、Actor 启动失败、资源不足→ 检查 Ray 集群状态与资源设置模型/数据加载异常 → 回到应用代码本身排查。3. 查阅模拟运行指南规避常见陷阱官方维护的 如何运行模拟 指南总结了大量实操细节与 FAQ其中与 700 直接相关的常见陷阱包括资源设置不当导致 OOMnum_cpus/num_gpus仅用于控制后端可创建的 worker 数量并不会真正限制单个ClientApp的内存使用。若 GPU 上触发 OOM官方建议先将num_gpus1让单个ClientApp独占 GPU用nvidia-smi观察 VRAM 占用后反推合理的num_gpus值使用 TensorFlow 时还应预先导出TF_FORCE_GPU_ALLOW_GROWTH1。多模拟共享资源同一台机器上并行多个模拟时各模拟互不知晓对方资源占用使用 GPU 时应通过CUDA_VISIBLE_DEVICES隔离。后端资源与硬件不匹配在多节点场景下可通过ray start --num-cpusN --num-gpusN显式声明节点可提供的资源避免模拟调度时因资源判定偏差而异常。ServerApp 的额外开销Simulation Runtime 只管理ClientApp若 ServerApp 本身如聚合后的全局模型评估也占用大量 CPU/GPU需在设置num_cpus/num_gpus时一并计入。五、典型排查流程可直接照做综合源码与官方文档当模拟任务以退出码 700 结束时推荐按以下顺序操作# 1. 确认模拟相关依赖已安装缺失时优先得到 701/608 pip install -U flwr # 若项目使用模拟后端 Ray确认其可用 python -c import ray; print(ray.__version__) # 2. 以更高日志级别重新运行模拟捕获完整堆栈 flwr run your-app --verbose先看日志定位Simulation raised an exception及异常堆栈判断是业务代码异常还是框架层异常再查依赖若堆栈指向ModuleNotFoundError对照应用的pyproject.toml补全依赖模拟场景确保声明了flwr[simulation]后调资源若异常与 Ray 或 OOM 相关参照上文 FAQ 调整num_cpus/num_gpus必要时为多节点模拟配置 Ray 集群确认环境核对 SuperExec 环境的 Python 版本、系统平台Linux/macOS 优先Windows 建议 WSL2与 Flower 版本一致性。六、小结退出码700 SIMULATION_EXCEPTION是 Flower 模拟运行失败时的通用兜底信号它表示模拟主流程抛出了未被分类的异常。通过 exit_code.py 可确认其定义与帮助文本通过 simulation/app.py 可还原其完整触发链路SUCCESS → 异常 → SIMULATION_EXCEPTION / 更精确的 607、608而官方 模拟运行指南 则提供了资源设置、多节点、OOM 等高频场景的规避方案。把握先看日志定位具体异常再对号入座选择修复路径这一原则绝大多数 700 问题都能在分钟级内解决。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考