Flower Baselines 贡献指南：基于 `flwr new` 模板从零构建可复现的联邦学习基线

Flower Baselines 贡献指南：基于flwr new模板从零构建可复现的联邦学习基线

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower

导读：本文以 baselines/dev/baseline/README.md 为骨架，系统讲解 Flower 社区贡献新联邦学习论文基线（Baseline）的完整流程——从模板初始化、pyproject.toml配置，到代码格式化、静态检查、单元测试与 PR 合入的规范，并深入剖析模板自带的可运行占位实现（PyTorch + CIFAR-10 + FedAvg 模拟），帮助研究者快速把论文实验封装成结构统一、一行命令即可复现的 Flower 基线。

背景：什么是 Flower Baseline，为什么需要统一模板

Flower Baselines 的目标是复现经典论文中的实验，让研究者能以更快的速度对比新策略、新数据集、新模型和新联邦流水线。为了让所有基线保持一致的目录结构、配置规范和质量门槛，Flower 提供了一个官方模板，并配套了格式化脚本与测试脚本。

在 baselines/docs/source/how-to-contribute-baselines.rst 中明确列出了三个基本要求：

1. 实验必须能用 Flower 运行；
2. 数据集应使用 Flower Datasets 下载与切分；
3. 必须能复现一篇论文的结果（优先使用 PyTorch，其他 ML 框架也欢迎）。

模板目录 baselines/dev/baseline 正是这一规范的落地载体：它既是新基线开发者的起始脚手架，也是贡献流程中所有脚本、测试、PR 检查的执行对象。

创建新基线：三步入库流程

按官方指南，贡献一个新基线只需三个步骤：

1. 获取 Flower 源码：Fork 仓库并克隆到本地；
2. 用模板创建基线：在baselines目录下运行flwr new @flwrlabs/baseline，会生成名为baseline的目录；随后重命名为你的基线名（例如mv baseline fedawesome），并按照模板内README.md的指引逐项填写；
3. 提交 Pull Request：git add .→ commit & push → 创建指向 Flowermain分支的 PR，与维护者协作完成合入。

其中第 2 步生成的模板并非空壳，而是自带一个可运行的 PyTorch + CIFAR-10 占位实现，你可以在flwr run .跑通之后再替换成论文所需代码。

模板结构全景

模板目录 baselines/dev/baseline 的完整结构如下：

baseline/ ├── LICENSE ├── README.md # 基线说明书（本文讲解的对象） ├── pyproject.toml # 依赖、格式检查配置、Flower App 声明 └── baseline/ ├── __init__.py ├── client_app.py # 客户端训练/评估入口 ├── dataset.py # 数据集加载与切分 ├── model.py # 模型定义与训练/测试函数 ├── server_app.py # 服务端策略与全局模型保存 ├── strategy.py # （占位，供自定义策略） └── utils.py # （占位，供工具函数）

这是一个标准的Flower 双层 App 结构：server_app.py暴露app（ServerApp 对象），client_app.py暴露app（ClientApp 对象），两者通过 pyproject.toml 中的[tool.flwr.app.components]被框架发现：

[tool.flwr.app.components] serverapp = "baseline.server_app:app" clientapp = "baseline.client_app:app"

可运行的占位实现解读

占位实现虽然简单，却完整演示了 Flower 新 API（Message/Context/RecordDict）的标准用法，是理解基线代码组织方式的绝佳范例：

• 服务端（baseline/server_app.py）：在@app.main()中从context.run_config读取num-server-rounds与fraction-train，初始化全局Net模型，构造FedAvg策略（fraction_evaluate=1.0、min_available_nodes=2），执行strategy.start(...)后将最终权重torch.save为final_model.pt；
• 客户端（baseline/client_app.py）：@app.train()从收到的Message中取出ArrayRecord反序列化为模型权重（to_torch_state_dict()），从context.node_config读取partition-id/num-partitions加载本地数据分片，训练后把权重与train_loss、num-examples打包成RecordDict返回；@app.evaluate()同理返回eval_loss、eval_acc；
• 数据集（baseline/dataset.py）：用IidPartitioner把 Hugging Face 上的uoft-cs/cifar10切分为num_partitions个 IID 分片，每个客户端内再做 80/20 的 train/test 划分（seed=42），并应用Normalize((0.5,0.5,0.5),(0.5,0.5,0.5))变换；
• 模型（baseline/model.py）：Net是 PyTorch 官方 60 分钟入门教程风格的轻量 CNN（2 个卷积层 + 3 个全连接层），训练用 SGD（lr=0.1, momentum=0.9）+ CrossEntropyLoss。

环境搭建与首次运行

创建虚拟环境并安装依赖

所有基线统一约定使用Python 3.12、pyenv与pyenv-virtualenv：

# 创建虚拟环境 pyenv virtualenv 3.12.12 <baseline-env-name> # 激活环境 pyenv activate <baseline-env-name> # 安装基线项目（-e 表示可编辑安装，改代码无需重装； # 但若在 pyproject.toml 中新增依赖，需重新执行本命令） pip install -e ".[dev]"

其中[dev]来自 pyproject.toml 的[project.optional-dependencies]，一次性装齐了isort、black、mypy、pylint、pytest、ruff等质量工具。

用占位代码跑通第一个模拟实验

不写任何新代码，模板就能直接运行——这既是自检也是熟悉 Flower App 执行方式的入口：

# 在包含 pyproject.toml 的目录下执行 flwr run .

flwr run会依据 pyproject.toml 中的联邦配置，启动默认的本地模拟：

[tool.flwr.federations] default = "local-simulation" [tool.flwr.federations.local-simulation] options.num-supernodes = 10 # 10 个虚拟 SuperNode options.backend.client-resources.num-cpus = 2 options.backend.client-resources.num-gpus = 0.0

用--run-config覆盖超参数

单次实验需要临时改参数时，不必修改pyproject.toml，直接通过命令行覆盖[tool.flwr.app.config]中已声明的键：

# 覆盖单个/多个超参数 flwr run . --run-config learning-rate=0.1,coefficient=0.123 # 或整体加载一个独立的 .toml 配置文件（文件中的键必须已在 pyproject.toml 中声明） flwr run . --run-config <my-big-experiment-config>.toml

模板默认声明的三个配置键见 pyproject.toml：

[tool.flwr.app.config] num-server-rounds = 3 fraction-train = 0.5 local-epochs = 1

格式化与测试：合入门槛的硬性检查

在开发基线过程中可随时运行格式化脚本；提交 PR 后，CI 会执行测试脚本，只有测试通过基线才能被合并。

自动格式化脚本

# 先回到 baselines 目录（即 flower/baselines） cd .. # 运行格式化脚本（能自动修复的问题会自动修复） ./dev/format-baseline.sh baseline

脚本 baselines/dev/format-baseline.sh 依次执行isort（import 排序）、black（代码风格，line-length 88）、ruff check --fix（lint 自动修复）。

质量检查与测试脚本

./dev/test-baseline.sh baseline

脚本 baselines/dev/test-baseline.sh 按序执行六类检查：

1. isort --check-only .：import 顺序检查；
2. black --check .：格式检查；
3. ruff check .：lint 检查（规则集D/E/F/W/B/ISC/C4/UP，docstring 遵循 numpy 约定）；
4. mypy .：类型检查（strict=false，对torch.*跳过 import 追踪）；
5. pylint ./baseline：静态分析（禁用了duplicate-code、too-few-public-methods等，允许max-args=10）；
6. pytest .：单元测试（无测试时返回码 5 视为通过）。

这些工具的版本与规则都锁定在 pyproject.toml 中，保证本地检查与 CI 完全一致。如果你在 PR 中被某些检查卡住，可以在 PR 评论区向 Flower 维护者求助。

README 撰写规范：一份合格的基线说明书要写什么

模板 README 的章节设计本身就是规范的最佳实践，逐项完成即可产出一份可索引、可复现的基线文档：

• YAML 元数据头：title、url（论文链接）、labels（4～10 个单词级标签，如system heterogeneity、image classification）、dataset（使用的数据集列表）。该元数据会在文件顶部生成一张表格，用于基线索引；
• 引用信息：Paper、Authors、Abstract；若复现该基线请同时引用论文原作者与 Flower 论文；
• About this baseline：What's implemented（用几句话说明复现了论文中的哪个实验）、Datasets（>10GB 的数据集需标注大小，推荐用 Flower Datasets 下载切分）、Hardware Setup（所用硬件、运行耗时、可复现的最小硬件配置）、Contributors；
• Experimental Setup：Task（被联邦化的主任务）、Model（模型细节，自建模型需给出论文中的位置）、Dataset（切分方式如 LDA α=0.1、客户端数量等，用表格呈现）、Training Hyperparameters（含默认值的超参表）；
• Environment Setup：逐步给出可完整复现的环境创建与安装命令；
• Running the Experiments：给出每个实验的精确命令 + 对应结果图表/表格（建议"一条命令配一张图"地成对展示，而非命令全部堆在前面）；需要更多配置时扩展[tool.flwr.app.config]或使用--run-config；绘图结果建议以 Jupyter notebook 或工具函数的形式提供，图表以.png格式存入与README.md同级的_static目录。

此外还需注意：完成填写后要删除模板中所有[!IMPORTANT]/[!NOTE]提示块、:warning:符号及其注释，并把标题同步到pyproject.toml的description字段。

从模板到正式基线：工作流总结

1. flwr new @flwrlabs/baseline生成模板 → 重命名目录；
2. 按 README 指引创建环境：pyenv virtualenv 3.12.12 <env>→pip install -e ".[dev]"；
3. 运行flwr run .验证占位实现可执行；
4. 将占位代码替换为论文实验实现，用--run-config或新增.toml覆盖配置；
5. 开发过程中随时执行./dev/format-baseline.sh <name>保持格式合规；
6. 提交前执行./dev/test-baseline.sh <name>通过全部六类检查；
7. 完善 README（元数据、实验设置、环境与运行命令、结果图表），清理模板提示块；
8. 提交 PR，等待 CI 的test-baseline.sh通过后合入。

借助这套标准化流程，任何人都能把自己论文中的联邦学习实验封装为「安装即复现、一条命令跑通」的 Flower Baseline，同时获得社区统一的格式、测试与文档质量保障。

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower