Flower v1.14.0 版本解读flwr stop 命令、CLI JSON 输出与 OIDC 认证基础设施【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flowerFlower v1.14.0发布于 2024-12-20围绕flwr命令行工具的运行管理能力展开新增flwr stop命令用于停止已提交的 run并为flwr run、flwr ls、flwr stop三个命令提供--format json输出便于接入自动化工具同时首次引入基于 OIDC 的用户认证扩展点。读完本文你可以正确停止一个正在运行的 Flower App掌握 JSON 输出中各字段的含义理解 StopRun 在 SuperLink 侧的完整调用链并知道如何把依赖已移除Client.context属性的旧代码迁移到client_fn(context: Context)签名。一、v1.14.0 变更概览本版本的完整变更清单见 v1.14.0 更新日志。主要特性可归为四类类别要点新特性flwr stop命令run/ls/stop命令支持--format jsonOIDC 用户认证扩展点生态FedRep baseline 迁移到flwr run启动方式模拟教程系列改版为 Flower Apps 流程健壮性ServerApp↔SuperLink、ClientApp↔SuperNode、SuperLink↔Simulation 三类连接的网络可靠性提升flwr new在 Windows 上的 UTF-8 修复不兼容变更移除Client与NumPyClient的context属性此外还包含文档改进新增 Microsoft Azure 虚拟机部署指南、CI/CD 基础设施更新、缺陷修复与通用维护下文逐项结合源码展开。二、flwr stop命令停止已提交的 Run2.1 用法根据 changelog 的说明该命令支持两种写法flwr stop run-id flwr stop run-id [app] [federation]第二种形式是遗留兼容写法。命令的语义是指令 SuperLink 终止指定 run。需要特别注意ServerApp与ClientApp进程不会因此被瞬间中断它们会在下一次与 SuperLink 通信时获知 run 已停止然后优雅地自行退出。这种软停止设计避免了强杀进程可能遗留的任务队列脏状态。2.2 CLI 侧实现实现入口在 stop.py。stop函数L41-L91的核心步骤进入cli_output_handler上下文管理器确定是否以 JSON 模式输出调用migrate对遗留参数旧式位置参数app/federation做兼容迁移通过read_superlink_connection读取 SuperLink 连接配置可选位置参数superlink指定连接名用init_http_client_from_connection构建ControlHttpClient经 Control API 发送StopRunRequest(run_idrun_id)成功时打印 Run {run_id} successfully stopped.若使用--format json额外向 stdout 输出{success: true, run-id: id}失败则抛出ClickException见 stop.py L94-L118。--format选项定义为Literal[default, json]默认值CliOutputFormat.DEFAULTstop.py L59-L66。该常量定义于 constant.pyCliOutputFormat仅有default与json两个取值且禁止实例化保证只作为常量使用。2.3 SuperLink 侧的 StopRun 调用链SuperLink 端的处理分三层1. 请求路由。Control API 提供两个等价入口gRPC 服务的 ControlServicer.StopRun 与 HTTP 路由 router.py 中的 stop_run挂载在/v1/control前缀下二者最终都收敛到 control_handlers.py 的stop_run处理函数。2. 处理器校验。control_handlers.stop_run依次执行从 LinkState 查询 run 记录不存在则抛出RUN_ID_NOT_FOUND错误通过_validate_federation_membership_in_request校验当前账号是否为该 run 所属联邦的成员未授权则拒绝若 run 状态已是FINISHED抛出RUN_ALREADY_FINISHED错误最后调用state.stop_run(run_id)将其布尔返回值封装为StopRunResponse(success...)。3. 状态迁移与清理。抽象方法 LinkState.stop_run 约定停止 run 并清理 run 级消息与对象当至少一个未完成任务迁移为 stopped 时返回True。内存实现 InMemoryLinkState.stop_run 给出了具体步骤找到 run 的主任务primary task对其执行finish_task(primary_task_id, SubStatus.STOPPED, )主任务的停止会级联停止其全部任务随后cleanup_run(run_id)清理该 run 的消息与对象。基于 SQL 的 SqlLinkState.stop_run 逻辑一致只是持久化到 SQLite 后端。测试佐证。control_servicer_test.py 断言调用StopRun后run 状态变为RunStatus(Status.FINISHED, SubStatus.STOPPED, )且delete_objects_in_run被调用一次以清理 run 级对象。另有权限测试L1979-L1995非联邦成员发起的StopRun会被FEDERATION_NOT_FOUND错误拒绝联邦成员则成功并得到相同的 FINISHED/STOPPED 状态。三、CLI JSON 输出--format jsonv1.14.0 为flwr run、flwr ls、flwr stop三个命令统一增加了--format json标志目的是让 CLI 输出可被解析方便与其他工具集成如 CI 脚本、日志收集。3.1 统一的输出机制三个命令都复用 utils.py 中的两个工具cli_output_handler上下文管理器。请求 JSON 格式时将 stdout/stderr 重定向到内存缓冲区吞掉面向人的进度日志保证输出流只含 JSON异常也会统一处理在 JSON 模式下将错误序列化为 JSON 结构输出print_json_to_stdout通过sys.__stdout__把 JSON 直接打印到系统真实 stdout绕过上面的重定向确保 JSON 负载即使在输出被捕获的场景下也能到达终端或管道。3.2flwr ls的 JSON 字段结构ls.py 是 JSON 输出最完整的示例。ls支持--run-id查看单个 run垂直详情表与--limit限制列表条数两个选项--limit最小值为 1且与--run-id互斥L109-L113 直接抛ValueError。人类可读视图展示 Run ID、Federation、App、Status、Elapsed、Status Changed 等列启用--format json时数据由_to_jsonL279-L324序列化为如下结构{ success: true, runs: [ { run-id: 123, federation-id: ..., fab-id: account/app, fab-name: app, fab-version: v1.0.0, fab-hash: ..., status: running, status-details: , elapsed: ..., pending-at: YYYY-MM-DD HH:MM:SSZ, starting-at: ..., running-at: ..., finished-at: ..., network-traffic: { inbound-bytes: 0, outbound-bytes: 0, total-bytes: 0 }, compute-time: { serverapp-seconds: 0, clientapp-seconds: 0, total-seconds: 0 } } ] }按ls的 docstring 约定所有时间戳遵循 ISO 8601 UTC格式为YYYY-MM-DD HH:MM:SSZ。状态文本形如finished:stopped_get_status_styleL139-L163会解析其中的子状态用于着色completed 绿色、failed 红色、stopped 黄色starting/running 蓝色pending 灰色——从源码结构看finished:stopped正是flwr stop停止 run 后在列表中呈现的状态。3.3 选项定义的一致性在 run.py 与 stop.py 的参数定义中--format选项统一为case_sensitiveFalse帮助文本 Format output using default view or json取值大小写不敏感三个命令默认值均为default。四、OIDC 用户认证基础设施Flower 自 v1.9 起支持 SuperNode 认证SuperNode 与 SuperLink 之间的互相认证v1.14.0 则增加了基于 OpenID ConnectOIDC的用户认证初始扩展点为后续的账号登录、联邦与权限功能打底。从源码结构看该功能落在三层常量层。constant.py 新增AuthnType取值为NOOP与OIDC用于声明认证类型认证插件层。auth_plugin.py 定义了 SuperLink 侧认证插件契约get_login_details()返回 OIDC 设备授权流程所需的登录详情authn_type、device_code、verification_uri_complete、expires_in、interval组装逻辑见 control_handlers.py 的 get_login_detailsget_auth_tokens(device_code)则用设备码换取账号凭证get_auth_tokens处理见 L1420 附近默认实现 noop_auth_plugin.py 返回空的 device_code未启用 OIDC 的部署不受影响协议层。GetLoginDetailsRequest/Response、GetAuthTokensRequest消息对贯穿 Control APIgRPC 拦截器与 HTTP 路由层均覆盖这两个调用可在 control_account_auth_interceptor_test.py 与 router_test.py 中看到以authn_typeoidc和 device-code 请求验证完整登录链路的测试用例。changelog 明确称其为 initial extension points即本版本只开放接口与流程骨架具体 IdP 接入是后续版本的事。五、本版本其他改进5.1 FedRep baseline 迁移到flwr run本版本启动将 baselines 从旧式start_simulation迁移到通过flwr run启动的工作FedRep 因其效果突出成为首个迁移对象对应代码位于 baselines/fedrep。新建 baseline 可以从flwr new模板起步采用flwr run兼容格式贡献指引见 how-to-contribute-baselines.rst。5.2 模拟教程系列改版examples/flower-simulation-step-by-step-pytorch 已更新新版演示如何通过flwr run创建并运行 Flower App覆盖自定义策略、ClientApp 与 ServerApp 之间的 metrics 传递、全局模型 checkpoint 创建、将 metrics 记录到 Weights Biases 等环节。5.3 连接可靠性与 Windows 修复ServerApp↔SuperLink、ClientApp↔SuperNode、SuperLink↔Simulation 三类连接对网络问题的抗扰性提升。从源码结构看重试与心跳基础设施位于 grpc_retry.py、heartbeat.py 等 supercore 模块本版本沿上述三类连接做了加固flwr new通过设置 UTF-8 编码在 Windows 上正确创建与传输文件解决了跨平台编码兼容问题。5.4 其他维护工作示例与flwr new模板更新移除不必要的numpy依赖、升级mlx版本、增强认证示例文档改进docstring 更新、拼写修正、新增贡献指引并引入自动同步机制保证翻译源文本常新本版本还新增了 Microsoft Azure 虚拟机上部署 Flower 的入门指南基础设施与 CI/CD 更新、缺陷修复、通用改进涉及 PR 众多清单以 changelog 原文为准。六、不兼容变更移除context属性由于Context已可以作为参数传入client_fn与server_fnv1.14.0 正式移除了Client和NumPyClient上的context属性——该特性已废弃数个版本现在是移除时点。当前代码库中的正确用法client_fn签名为def client_fn(context: Context)并返回 Client 实例调用处为client client_fn(context)见 message_handler.py L95-L98ClientApp源码中对client_fn的同样签名约束与提示见 client_app.pyNumPyClient定义位于 compat/client/numpy_client.py。如果从 v1.13.x 升级凡是依赖client.context的代码需要改为在client_fn内部直接使用作为参数传入的context同时确保 Flower 框架版本升级到 v1.14.0 及以上。七、小结Flower v1.14.0 的主题是运行期的运维工程化flwr stop补齐了 run 生命周期管理的最后一块启动、列表、停止--format json为run/ls/stop提供了机器可读接口使 Flower CLI 可以被 CI 流水线与自动化脚本直接包装OIDC 扩展点则启动了用户认证能力。对使用者而言升级时的唯一硬性动作是处理Client.context属性移除带来的签名调整。以上行为均基于当前仓库的实际代码文中给出了对应的源码文件路径与行号可直接查证。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考