Flower 联合学习入门：使用 fastai 与 SqueezeNet 在 MNIST 上运行联邦训练（Quickstart Example）

Flower 联合学习入门：使用 fastai 与 SqueezeNet 在 MNIST 上运行联邦训练（Quickstart Example）

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

本指南基于 Flower 官方 quickstart 示例（examples/quickstart-fastai/README.md）展开，演示如何用 fastai——一个构建在 PyTorch 之上的高级深度学习库——在 MNIST 数据集上联邦训练 SqueezeNet v1.1 图像分类模型。读者将掌握 Flower 应用的完整生命周期：使用flwr new拉取项目模板、理解ClientApp/ServerApp的职责划分、用 Flower Datasets 完成数据分区与预处理，并分别以 Simulation Engine（模拟引擎）和 Deployment Engine（部署引擎）两种模式一键运行同一份代码。

示例概述：fastai + Flower 能做什么

fastai 为深度学习实践者提供了大量开箱即用的高层组件（数据加载器、Learner、指标与回调等），而 Flower 是一个友好的联邦 AI 框架，负责协调多客户端的数据不共享训练。本示例把两者结合：服务端维护一个全局 SqueezeNet v1.1 模型，多个模拟客户端各自持有 MNIST 的 IID 数据分片，通过 FedAvg 策略完成多轮参数聚合。

示例的技术要点：

• 模型：SqueezeNet v1.1（fastai.vision.all.squeezenet1_1）；
• 数据集：MNIST（ylecun/mnist），由 Flower Datasets（flwr_datasets）下载并按 IID 方式切分；
• 框架：fastai 2.8.7 + PyTorch，客户端训练采用 fastaiLearner；
• 聚合策略：服务端使用 Flower 内置FedAvg。

运行示例并不要求深度掌握 fastai，重点是理解如何把 Flower 适配到你自己的使用场景。

项目结构

通过flwr new拉取应用后，会生成一个名为quickstart-fastai的目录，其结构与当前仓库中的示例保持一致：

quickstart-fastai ├── fastai_example │ ├── client_app.py # 定义 ClientApp（训练 / 评估回调） │ ├── server_app.py # 定义 ServerApp（聚合策略与入口） │ └── task.py # 定义模型、训练与数据加载 ├── pyproject.toml # 项目元数据、依赖与应用配置 └── README.md

对应到当前仓库，源码位于 examples/quickstart-fastai/fastai_example/ 目录下，包含__init__.py、client_app.py、server_app.py与task.py四个模块；应用配置定义在 examples/quickstart-fastai/pyproject.toml 中。

环境搭建与项目初始化

安装 Flower 并拉取应用

先安装 Flower 框架本体：

pip install flwr

然后使用 Flower CLI 拉取官方发布的 quickstart 应用：

flwr new @flwrlabs/quickstart-fastai

该命令会以@flwrlabs/quickstart-fastai为模板生成上节所示的目录结构。如果你希望直接阅读当前仓库内的示例代码，也可以在examples/quickstart-fastai/目录下原地查看或拷贝使用。

安装依赖与本地包

进入项目目录后，安装pyproject.toml中声明的全部依赖，同时以可编辑模式安装fastai_example包：

pip install -e .

从 examples/quickstart-fastai/pyproject.toml 可以看到本示例锁定的依赖版本（示例快照，以仓库为准）：

dependencies = [ "flwr[simulation]>=1.36.0", "flwr-datasets[vision]>=0.6.1", "fastai==2.8.7", "torch==2.10.0", "torchvision==0.25.0", ]

其中flwr[simulation]额外带入了模拟运行所需的依赖，flwr-datasets[vision]提供带视觉能力的数据集工具，fastai与torch/torchvision则是模型训练与图像变换的运行时基础。

运行联邦训练

Flower 支持在同一份代码上以两种模式运行，无需修改任何业务逻辑：模拟模式（Simulation Engine）与部署模式（Deployment Engine）。对于刚接触 Flower 的用户，推荐先使用模拟模式，因为它需要手动启动的组件更少。默认情况下flwr run使用的就是 Simulation Engine。

模式一：使用 Simulation Engine（推荐入门）

在项目根目录执行：

flwr run . --stream

• .表示以当前目录作为 Flower App；
• --stream开启运行日志的流式输出，便于实时观察每个客户端与服务端的事件。

运行期间可以看到服务端启动、每个 SuperNode（模拟客户端）完成本地训练并上传模型更新、服务端按 FedAvg 聚合并下发新一轮全局模型等完整流程。

覆盖运行配置

pyproject.toml中定义的默认配置可以在命令行直接覆盖，例如把联邦轮数从默认值改为 5：

flwr run . --run-config num-server-rounds=5 --stream

--run-config接受key=value形式，可覆盖[tool.flwr.app.config]中声明的任意参数，具体可覆盖项见下文“运行配置解析”一节。

模式二：使用 Deployment Engine

模拟模式之外，同一应用也可以跑在真实的多进程/多机部署场景下。Deployment Engine 需要分别启动 SuperLink（服务端）与若干 SuperNode（客户端），再以flwr run连接。本示例文档建议参考 Flower 官方 how-to 指南了解部署引擎的启动方式，并进一步为你的联邦配置启用：

• TLS 加密通信：为 SuperLink 与 SuperNode 之间的 gRPC 通道启用证书；
• SuperNode 认证：通过密钥机制认证加入联邦的节点身份。

如果你已经熟悉 Deployment Engine，还可以借助 Docker 容器化部署：用官方镜像分别承载 SuperLink、SuperNode 与 ServerApp，从而把联邦的各个组件以独立服务的形式编排起来。当前仓库的 framework/docker/ 目录下提供了superlink、supernode、superexec等组件的 Dockerfile 示例，可作为容器化部署的参考起点。

源码级解析：数据、客户端与服务端

task.py：数据加载与分区

examples/quickstart-fastai/fastai_example/task.py 是数据层的核心，它通过 Flower Datasets 完成「下载—分区—变换—切分」全流程：

def load_data(partition_id, num_partitions): # Only initialize `FederatedDataset` once global fds if fds is None: partitioner = IidPartitioner(num_partitions=num_partitions) fds = FederatedDataset( dataset="ylecun/mnist", partitioners={"train": partitioner}, trust_remote_code=True, ) partition = fds.load_partition(partition_id, "train") # Resize and repeat channels to use MNIST, which have grayscale images, # with squeezenet, which expects 3 channels. pytorch_transforms = Compose( [Resize(224), ToTensor(), Lambda(lambda x: x.expand(3, -1, -1))] ) ...

几个值得注意的实现细节：

• 模块级缓存：fds作为模块级全局变量缓存FederatedDataset实例，避免每个回调重复初始化数据集；
• IID 分区：使用IidPartitioner(num_partitions=num_partitions)把 MNIST 训练集均匀切成num_partitions份，客户端partition_id决定取哪一份；这也意味着本示例模拟的是数据独立同分布（IID）场景；
• 通道适配：MNIST 是单通道灰度图，而 SqueezeNet 期望 3 通道输入，因此变换管线为Resize(224)（对齐 SqueezeNet 输入尺寸）→ToTensor()→Lambda(lambda x: x.expand(3, -1, -1))（把单通道复制扩展为 3 通道）；
• 内部数据切分：每个客户端拿到自己的分区后，再做两级切分：
  • 先train_test_split(test_size=0.2, seed=42)，留出 20% 用作联邦评估（testloader）；
  • 剩余 80% 再按train_size=0.75切分，得到 60% 训练集（trainloader）与 20% 验证集（valloader），两者都用于客户端的fit流程；
• DataLoader 定制：collate_fn把 Flower Datasets 返回的字典批次（{"image": ..., "label": ...}）转换为(images_tensor, labels_tensor)元组，以保持 fastai DataLoaders 期望的标准行为；三个 DataLoader 的batch_size均为 32。

client_app.py：训练与评估回调

examples/quickstart-fastai/fastai_example/client_app.py 定义了ClientApp，通过装饰器注册train与evaluate两个回调：

app = ClientApp() @app.train() def train(msg: Message, context: Context): # Load the model and initialize it with the received weights model = squeezenet1_1() model.load_state_dict(msg.content["arrays"].to_torch_state_dict()) ... learn = Learner( dls, model, loss_func=CrossEntropyLossFlat(), metrics=error_rate, ) with learn.no_bar(), learn.no_logging(): learn.fit(1) ...

核心流程为：从入站Message的ArrayRecord中恢复全局模型权重 → 依据context.node_config中的partition-id与num-partitions加载本客户端数据 → 构造 fastaiLearner（损失函数CrossEntropyLossFlat、指标error_rate）→learn.fit(1)本地训练 1 个 epoch → 把更新后的model.state_dict()与num-examples指标封装进回复Message。

evaluate回调结构与train对称：同样恢复权重并构建Learner，但改用learn.validate()在验证集上求损失与错误率，随后上报三项指标：

metrics = { "eval_loss": loss, "eval_acc": 1 - e_rate, # 由 error_rate 换算为准确率 "num-examples": len(valloader.dataset), }

整个示例的通信内容统一基于 Flower 的记录原语：ArrayRecord承载模型权重（与 PyTorchstate_dict互相转换）、MetricRecord承载标量指标、RecordDict作为外层容器。

server_app.py：服务端与 FedAvg 聚合

examples/quickstart-fastai/fastai_example/server_app.py 定义了ServerApp，其main入口读取运行配置、初始化全局模型并启动 FedAvg 策略：

app = ServerApp() @app.main() def main(grid: Grid, context: Context) -> None: fraction_train: float = context.run_config["fraction-train"] num_rounds: int = context.run_config["num-server-rounds"] global_model = squeezenet1_1() arrays = ArrayRecord(global_model.state_dict()) strategy = FedAvg(fraction_train=fraction_train) result = strategy.start( grid=grid, initial_arrays=arrays, num_rounds=num_rounds, ) if context.run_config["save-model"]: state_dict = result.arrays.to_torch_state_dict() torch.save(state_dict, "final_model.pt")

要点说明：

• 服务端模型同样通过ArrayRecord序列化后作为 FedAvg 的初始权重下发；
• strategy.start()接受grid（Flower 的节点编排抽象）、初始权重与轮数，内部负责「下发全局模型 → 收集客户端更新 → 按样本数加权平均 → 更新全局模型」的循环；
• 当运行配置save-model为true时，训练结束会把最终聚合权重保存为本地文件final_model.pt。

运行配置解析

示例的全部可调参数集中在 examples/quickstart-fastai/pyproject.toml 的[tool.flwr.app.config]段：

[tool.flwr.app.config] num-server-rounds = 3 fraction-train = 1.0 save-model = false

从源码看，num-server-rounds与fraction-train分别被 server_app.py 中的context.run_config读取并直接作用于 FedAvg 的聚合过程：fraction_train决定每轮采样客户端比例，num_rounds决定聚合循环次数；save-model仅在训练收尾阶段影响是否落盘权重。

同时，[tool.flwr.app.components]段把应用入口绑定到具体模块：

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

flwr run正是依据这两行配置找到ServerApp与ClientApp实例并启动相应运行模式的。

端到端测试佐证

当前仓库的框架测试体系中提供了与本文示例同源的端到端验证：framework/e2e/e2e-fastai/。该测试同样使用 fastai + MNIST 手写数字识别任务配合FedAvg策略，验证 Flower 框架与 fastai 的集成链路（其pyproject.toml将serverapp/clientapp指向e2e_fastai包，并默认使用local-simulation联邦配置、num-supernodes = 10）。这从侧面印证了本文示例所采用的技术栈（fastai、MNIST、FedAvg）正是 Flower 官方验证过的组合。

小结与延伸

本文完整复现了 fastai + Flower 联邦学习示例的搭建与运行路径：

1. pip install flwr安装框架，flwr new @flwrlabs/quickstart-fastai拉取应用，pip install -e .安装依赖；
2. 用flwr run . --stream以 Simulation Engine 一键运行，用--run-config覆盖轮数等参数；
3. 从源码层面理解task.py（IID 分区 + 通道适配 + 三级数据切分）、client_app.py（fastaiLearner训练与评估回调）与server_app.py（FedAvg 聚合与模型落盘）的协作关系。

在此基础上，可以继续探索的进阶方向包括：切换到 Deployment Engine 进行多进程/多机部署、为联邦启用 TLS 与 SuperNode 认证、通过 Docker 容器化编排各组件，以及把同样的ClientApp/ServerApp结构迁移到你自己的数据集与模型上——这正是 Flower 所倡导的「一套代码，两种运行模式」的开发体验。

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