Flower CLI 的 JSON 输出用 flwr run / list / stop 命令驱动自动化集成的完整指南【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文基于 Flower 官方文档 how-to-use-cli-json-output.rst 展开讲解 Flower 命令行工具flwr如何通过--format json选项将flwr run、flwr list、flwr stop三个核心命令的输出结构化为 JSON供脚本、CI 流水线和其他工具消费。读完本文你将掌握每个命令 JSON 输出的完整字段结构含错误情况下的输出约定、该功能在 SuperLink Control API 上的工作原理以及本地模拟场景address :local:下的适用边界并可直接在自动化场景中复制使用这些命令。适用前提JSON 输出依赖 SuperLink Control API根据原文档的说明JSON 输出目前仅对通过 SuperLink Control API 操作的命令可用。这包括两种场景远程 SuperLink如通过 SuperLink 连接配置指向的远端服务本地模拟场景中SuperLink 连接配置里标记为address :local:的托管本地 SuperLink。从源码看:local:是一个魔法地址值定义在 constant.py 中LOCAL_SUPERLINK_ADDRESS_MAGIC_VALUE :local:。当 CLI 读到该地址时init_http_client_from_connection会先调用 local_superlink.py 中的ensure_local_superlink在本地按需拉起一个 SuperLink 进程默认 HTTP API 端口为 39091可通过环境变量FLWR_LOCAL_SUPERLINK_HTTP_API_PORT调整随后所有 Control API 请求都会落到127.0.0.1上的这个本地实例——因此本地模拟与远程 SuperLink 在 CLI 这一侧走的是同一条 Control API 路径这也是二者都能输出 JSON 的原因。命令内部统一通过 utils.py 中的cli_output_handler上下文管理器处理输出格式。该管理器读取--format参数取值default或json由 constant.py 中CliOutputFormat类定义在 JSON 模式下会将stdout/stderr重定向到内存缓冲区从而保证程序运行期间的人类可读提示进度条、日志等不会污染 JSON 输出。flwr run 的 JSON 输出flwr run用于提交一个 Flower App 的运行。对本地 AppCLI 会先在本地构建 FABFlower App Bundle再经由 Control API 的StartRun请求启动运行。默认非 JSON输出大致如下$ flwr run . local --stream Starting local SuperLink on 127.0.0.1:39091... Successfully started run 1859953118041441032 ...加上--format json后返回结构化 JSON$ flwr run . local --format json { success: true, run-id: 1859953118041441032, fab-id: flwrlabs/myawesomeapp, fab-name: myawesomeapp, fab-version: 1.0.0, fab-hash: 014c8eb3, fab-filename: flwrlabs.myawesomeapp.1-0-0.014c8eb3.fab }flwr run的 JSON 输出包含以下字段success命令成功时为truerun-id已提交的 run IDfab-idFlower App 标识符fab-nameFlower App 名称fab-versionFlower App 版本fab-hashFAB 的短哈希前 8 位fab-filename构建出的 FAB 文件名。若命令失败JSON 输出将包含success: false与error-message字段。源码级实现payload 是如何拼装的在 run.py 中run命令定义--format选项Literal[default, json]默认CliOutputFormat.DEFAULT大小写不敏感主流程在cli_output_handler上下文内执行构建 FAB 并计算哈希对本地 App 调用build_fab_from_disk(app)随后用hashlib.sha256(fab_bytes).hexdigest()计算完整哈希并从 App 配置中提取fab-id与fab-version提交 StartRun 请求通过control_client.StartRun(req)向 SuperLink 发送StartRunRequest包含 FAB 的 proto 序列化、运行配置覆盖、联邦 ID 等组装 JSON payloadpayload 始终包含success、run-id、federation-id若 SuperLink 返回了note还会带上note字段。只有当运行的是本地 App而非account/app形式的远程 App时才追加fab-id、fab-name由fab-id取/后的部分、fab-version、fab-hashfab_hash[:8]即短哈希和fab-filename这五个 FAB 元数据字段——这正是文档示例中fab-hash只有 8 位的原因输出print_json_to_stdout(payload)将 JSON 直接写到sys.__stdout__绕开输出重定向确保即使 stdout 被捕获也能正常打印。从源码结构看对于远程 Appflwr run account/appJSON 输出中不会出现 FAB 相关字段此时使用空值占位的Fab脚本解析时应以fab-id等字段是否出现作为判断依据而非假定其必然存在。flwr list 的 JSON 输出flwr list从当前 SuperLink 连接查询运行列表。默认输出是一个带 Run ID、Federation、App、Status、Elapsed、Status Changed 列的终端表格。$ flwr list Listing all runs... ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Run ID ┃ Federation ┃ App ┃ Status ┃ Elapsed ┃ Status Changed ┃ ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩ │ 1859953118041441032 │ none/default │ flwrlabs/myawesomeapp1.0.0 │ finished:completed │ 55s │ 2024-12-16 11:13:28Z │ ├──────────────────────┼───────────────┼─────────────────────────────────┼────────────────────┼─────────┼──────────────────────┤ │ 14200740657011601420 │ none/default │ flwrlabs/myawesomeapp1.0.0 │ running │ 9s │ 2024-12-16 12:18:39Z │ └──────────────────────┴───────────────┴─────────────────────────────────┴────────────────────┴─────────┴──────────────────────┘加上--format json$ flwr list --format json { success: true, runs: [ { run-id: 1859953118041441032, federation-id: none/default, fab-id: flwrlabs/myawesomeapp, fab-name: myawesomeapp, fab-version: 1.0.0, fab-hash: 014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3, status: finished:completed, status-details: N/A, elapsed: 55.0, pending-at: 2024-12-16 11:12:33Z, starting-at: 2024-12-16 11:12:33Z, running-at: 2024-12-16 11:12:33Z, finished-at: 2024-12-16 11:13:28Z, network-traffic: { inbound-bytes: 12345, outbound-bytes: 6789, total-bytes: 19134 }, compute-time: { serverapp-seconds: 5.2, clientapp-seconds: 42.7, total-seconds: 47.9 } }, { run-id: 14200740657011601420, federation: none/default, fab-id: flwrlabs/myawesomeapp, fab-name: myawesomeapp, fab-version: 1.0.0, fab-hash: 014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3014c8eb3, status: running, status-details: N/A, elapsed: 9.0, pending-at: 2024-12-16 12:18:39Z, starting-at: 2024-12-16 12:18:39Z, running-at: 2024-12-16 12:18:39Z, finished-at: N/A, network-traffic: { inbound-bytes: 4567, outbound-bytes: 2345, total-bytes: 6912 }, compute-time: { serverapp-seconds: 0.6, clientapp-seconds: 8.1, total-seconds: 8.7 } } ] }说明上方示例忠实保留了原文档中的字段写法从 ls.py 的_to_json实现看当前代码对每条 run 统一输出federation-id键文档示例中第二条出现的federation为笔误解析脚本建议以federation-id为准。runs数组中每条记录包含run-idrun IDfederation-id联邦 IDfab-id/fab-name/fab-version/fab-hashFlower App 元数据注意此处fab-hash为完整 SHA-256 十六进制串与flwr run输出中的短哈希不同status当前运行状态如pending、starting、running、finished:completedstatus-details额外的状态详情文本无详情时为N/Aelapsed已运行时间秒pending-at/starting-at/running-at/finished-atrun 各阶段时间戳ISO 8601、UTCnetwork-traffic入站、出站与总字节数compute-timeServerApp、ClientApp 及总计算时间秒。单条运行详情视图要返回某个 run 的详情视图可指定--run-id$ flwr list --run-id 1859953118041441032 --format json返回结构相同顶层successruns数组只是runs中只有一条记录。源码级实现从 Control API 到 JSONflwr list的实现位于 ls.py核心链路为参数校验--run-id与--limit互斥同时提供会抛ValueError查询_list_runs通过stub.ListRuns(ListRunsRequest(limitlimit))拉取运行列表_display_one_run则以ListRunsRequest(run_idrun_id)查询单条格式化proto 响应经run_from_proto转为Run对象再由 run_utils.py 的format_runs按pending_at倒序整理为RunRow数据类。elapsed的计算规则是running_at到finished_at若已结束或到 SuperLink 返回的当前时间之差未进入running状态的 run 其elapsed为 0序列化_to_json将RunRow列表包装为{success: True, runs: [...]}其中total-bytes与total-seconds由代码现场相加得出而非来自 SuperLink 字段。默认表格视图中状态颜色finished:completed绿、finished:failed红、finished:stopped黄、starting/running蓝由_get_status_style决定这些展示逻辑不影响 JSON 输出但可用于理解status字段的取值形态状态:子状态。flwr stop 的 JSON 输出flwr stop按 run ID 停止一个已提交或正在运行的 run。默认输出$ flwr stop 1859953118041441032 Stopping run ID 1859953118041441032... Run 1859953118041441032 successfully stopped.加上--format json$ flwr stop 1859953118041441032 --format json { success: true, run-id: 1859953118041441032 }若命令失败JSON 输出同样包含success: false与error-message。实现见 stop.pystop命令通过stub.StopRun(StopRunRequest(run_idrun_id))向 SuperLink 发送停止请求当响应success为真时打印成功提示JSON 模式下额外输出{success: true, run-id: ...}否则抛出click.ClickException由统一错误处理转成 JSON 错误输出。错误输出约定success 与 error-message三个命令共享同一套错误输出机制这对编写健壮的自动化脚本至关重要。在 utils.py 中cli_output_handler作为上下文管理器工作进入时若为 JSON 模式调用redirect_output将sys.stdout、sys.stderr以及 Flower 日志控制台的输出流全部重定向到一个StringIO缓冲区——因此命令执行过程中的任何人类可读信息如 Starting local SuperLink on 127.0.0.1:39091...都不会混入 JSON退出时恢复输出若执行过程中发生异常且处于 JSON 模式则调用 logger.py 的print_json_error输出形如{ success: false, error-message: 被捕获的控制台信息\n异常信息 }print_json_error还会通过_remove_emojis剥除消息中的 emoji保证错误消息在程序化处理时干净可读。此外utils.py 的flwr_cli_exc_handler专门处理 Control API 层的传输与业务错误网络不可达会给出 Connection to the SuperLink is unavailable... 提示401 未授权会提示执行flwr loginSuperLink 返回的结构化 Flower 错误含错误码与消息会被格式化为对用户友好的文本。这些异常在 JSON 模式下同样最终落入error-message字段。因此自动化脚本可以只依赖一个解析约定解析 stdout 的 JSON先检查success字段为false时读取error-message。在自动化场景中的使用要点结合源码与文档可以在脚本中这样组织调用以 Python 为例的示意逻辑均基于上述实现提交flwr run app-path superlink-name --format json从返回 JSON 提取run-id用于后续轮询与停止若需本地 App 指纹可同时校验fab-hash与fab-filename轮询周期性执行flwr list --run-id run-id --format json注意--limit与--run-id不可同时使用检查runs[0].status进入finished:completed/finished:failed/finished:stopped即终态elapsed字段用于估算运行时长finished-at为N/A表示尚未结束止损超时或人工干预时执行flwr stop run-id --format json以success字段确认结果资源观测flwr list的 JSON 中network-trafficinbound/outbound/total 字节数与compute-timeServerApp、ClientApp 及总秒数可直接用于运行成本统计——从 run_utils.py 的RunRow定义看inbound 包含 SuperNode 到 SuperLink 的流量outbound 包含 SuperLink 到 SuperNode 的流量。两点适用边界提醒与原文档 note 一致JSON 输出当前仅覆盖经由 SuperLink Control API 操作的命令即远程 SuperLink 与address :local:的本地模拟场景且--format取值仅default与json两种大小写不敏感。小结--format json让flwr run、flwr list、flwr stop三个命令返回可被程序稳定解析的结构化输出成功与失败共用success字段失败时附带error-message三条命令的输出分别锚定在 run.py、ls.py、stop.py统一由 utils.py 的cli_output_handler/print_json_to_stdout/print_json_error保障stdout 只有 JSON的契约本地模拟:local:通过ensure_local_superlink自动拉起本地 SuperLink 后走相同的 Control API 路径因此与远程场景的输出结构一致原文档完整内容与字段说明见 how-to-use-cli-json-output.rstSuperLink 连接的配置文件读取逻辑可参考 flower_config.py 中的read_superlink_connection。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考