用途:把已有的普通或手工 PyTorch 训练代码转换成 NVFLARE 联邦训练作业,覆盖 torch.nn.Module、手写训练循环、state_dict 流程、数据加载器、检查点与指标循环。支持横向联邦、基于 Client API 的 FLModel 模型交换、recipe 的 aggregator= 钩子、验证与导出。
主要能力:按请求的联邦工作流选择 recipe,而非仅凭 PyTorch 选择;标准情形在明确要求 FedAvg 且识别为 PyTorch 时,直接运行 nvflare recipe show fedavg-pt --format json 并据此构建,fedavg-pt 需从 nvflare.app_opt.pt.recipes.fedavg 导入 FedAvgRecipe。编辑前先用 nvflare agent inspect source <path> --format json 加直接阅读做静态检查,不导入或执行用户训练模块。转换训练与评估为一对,初始化 FLARE、接收 FLModel、加载参数、评估收到的全局模型、训练,并回传含更新参数、指标和本轮实际完成的本地优化器步数的 FLModel(NUM_STEPS_CURRENT_ROUND)。检查点须用 torch.load(..., weights_only=True)。在 job.py 中按共享的构造器序列化规则补全 class_path 与完整参数,并接入 requested aggregator=、指标、张量传输、服务端卸载与执行设置。按阶梯验证:编译检查、recipe 构造、选定产物对应的最终完整运行路径,仅在选定导出产物路径时做导出与打包检查,遇首个失败即停止并报告产品错误。最后报告 recipe、变更文件、验证状态、指标与确切产物路径。
使用方式:需与共享的转换规范文档配合使用;标准 FedAvg 路由内联,常见场景不预加载全部参考文档,仅在对应阶段或例外情况加载客户端模板、模型交换、验证等参考。
限制:不适用于 PyTorch Lightning(应转至 nvflare-convert-lightning)、Hugging Face Trainer(转至 nvflare-convert-huggingface)、TensorFlow、XGBoost、scikit-learn、失败作业(转至 nvflare-diagnose-job)、无训练的联邦统计(转至 nvflare-fed-stats)或无 FLARE 意图的通用 PyTorch 调试。范围外:生产部署、Kubernetes、POC 生命周期、隐私/安全策略设计、recipe 或 Job API 之外的控制器/工作流重写、实验搜索,以及最小验证设置之外的数据分布实验。隐私保护请求(HE/加密聚合、差分隐私、隐私过滤器)需配置/部署策略,应另行路由。若同时涉及联邦统计与模型训练转换,应视为两个独立作业,不合并、不自动串联,先询问执行顺序。不得在 client.py 中修补框架中立的运行时模块或注册 FOBS 处理器;不得合成无源证据的指标语义;缺少评估但要求评估时询问或直接失败。站点分区、自定义聚合、来源真相边界与用户输入/授权遵循共享转换规范;依赖安装顺序亦按共享文档执行。