1. 横向联邦 MNIST 实验从数据孤岛到全局模型联邦学习Federated Learning是一种让多个参与方在不共享原始数据的前提下协作训练同一个全局模型的分布式机器学习方法。它的核心承诺是数据不出本地只交换模型参数。横向联邦学习是其中最直观的一类各参与方拥有相同的数据特征比如都是 28x28 的灰度图但样本不同各自持有不同批次的图片。这正好对应多家医院都有年龄、病史字段但患者不同的真实场景。这篇文章面向刚接触联邦学习的开发者用 MNIST 手写数字数据集把整条链路跑通启动 3 个客户端每个客户端只用自己的本地数据训练把参数更新上传到中心服务器做加权聚合FedAvg再观察每一轮全局精度的变化。你会得到可复制的环境配置、聚合脚本和验证动作最后能亲眼确认各客户端的原始数据从未离开本地目录。适合谁会一点 Python、装过 PyTorch、想搞明白联邦到底比集中式多了哪几步的人。整篇不需要 GPUCPU 上跑 3 个客户端、每客户端几千条样本几分钟就能看到精度曲线往上走。在动手之前先把工具链准备好。联邦学习实验里最容易被忽略的不是算法而是多进程/多客户端如何统一管理模型调用与密钥。我这次把模型侧的调用统一走 TaoToken 的 Key这样后面无论扩到 5 个还是 10 个客户端鉴权和模型标识都不用改来改去。2. TaoToken 前置统一 Key 与模型接入准备TaoToken 是一个模型调用聚合平台你可以把它理解成一个 Key 打通多种模型的入口。对联邦学习实验来说它的价值在于当你想在聚合服务器上挂一个模型质量评估或参数异常检测的辅助模型时不需要为每个客户端单独申请一套凭证统一用同一个 Key 和 Base URL 就能调用。先做三件事。第一拿到 API Key。访问控制台创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后在 API Keys 页面复制形如sk-xxxxxxxx。这个 Key 只用于服务端调用不要写进客户端本地训练脚本里明文分发。第二确认接入地址。API 基址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的base_url使用。第三选模型 ID。在模型对话页面可以查看当前可用模型列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels把 Key、Base URL、Model ID 这三件套记下来后面配置里会反复用到。如果你打算长期跑编码类或 Agent 类任务可以顺带了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入文档在这里遇到参数格式问题优先查它https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc注意TaoToken 是模型调用入口不是数据存储服务。联邦学习里各客户端的原始 MNIST 数据始终留在本地磁盘TaoToken 只承担模型侧调用不接触你的训练样本。环境依赖方面装好 PyTorch 和 requests 即可pip install torch torchvision requestsMNIST 数据集第一次运行会自动下载到./data。为了模拟数据不出本地我们给每个客户端分配一个独立目录例如client_0/data、client_1/data、client_2/data各自只读取自己目录下的分片。3. 可复制配置三客户端目录与聚合脚本这一节给出完整可跑的代码结构。目录长这样fed_demo/ ├── server.py ├── client.py ├── config.json └── data/ ├── client_0/ ├── client_1/ └── client_2/先写config.json把 TaoToken 三件套和联邦参数集中管理{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: gpt-4o-mini }, federated: { num_clients: 3, rounds: 5, local_epochs: 1, lr: 0.01, batch_size: 64 } }client.py负责本地训练。关键点是它只从自己目录读数据训练完把state_dict返回不返回任何样本。import copy, json, torch import torch.nn as nn import torch.optim as optim from torchvision import datasets, transforms from torch.utils.data import DataLoader class Net(nn.Module): def __init__(self): super().__init__() self.fc nn.Sequential( nn.Flatten(), nn.Linear(784, 128), nn.ReLU(), nn.Linear(128, 10) ) def forward(self, x): return self.fc(x) def load_local_data(client_id): tf transforms.Compose([transforms.ToTensor()]) ds datasets.MNIST(f./data/client_{client_id}, trainTrue, downloadTrue, transformtf) return DataLoader(ds, batch_size64, shuffleTrue) def local_train(global_state, client_id, cfg): model Net() model.load_state_dict(global_state) loader load_local_data(client_id) opt optim.SGD(model.parameters(), lrcfg[lr]) loss_fn nn.CrossEntropyLoss() model.train() for _ in range(cfg[local_epochs]): for x, y in loader: opt.zero_grad() loss loss_fn(model(x), y) loss.backward() opt.step() return model.state_dict(), len(loader.dataset)server.py做 FedAvg 聚合按各客户端样本数加权平均参数。import json, copy, torch from client import Net, local_train def fed_avg(states, sizes): total sum(sizes) avg copy.deepcopy(states[0]) for k in avg: avg[k] sum(states[i][k] * (sizes[i] / total) for i in range(len(states))) return avg def evaluate(state): from torchvision import datasets, transforms from torch.utils.data import DataLoader tf transforms.Compose([transforms.ToTensor()]) ds datasets.MNIST(./data/client_0, trainFalse, downloadTrue, transformtf) loader DataLoader(ds, batch_size256) model Net(); model.load_state_dict(state); model.eval() correct 0 with torch.no_grad(): for x, y in loader: correct (model(x).argmax(1) y).sum().item() return correct / len(ds) if __name__ __main__: cfg json.load(open(config.json))[federated] global_state Net().state_dict() for r in range(cfg[rounds]): states, sizes [], [] for cid in range(cfg[num_clients]): s, n local_train(global_state, cid, cfg) states.append(s); sizes.append(n) global_state fed_avg(states, sizes) acc evaluate(global_state) print(fRound {r1} global acc {acc:.4f})跑起来python server.py三个客户端会依次在各自目录训练服务器聚合后打印全局精度。整个过程没有任何一行代码把client_x的图片传给服务器。4. 验证请求与成功结果观察每轮精度变化启动后你应该看到类似输出Round 1 global acc 0.8213 Round 2 global acc 0.8907 Round 3 global acc 0.9124 Round 4 global acc 0.9258 Round 5 global acc 0.9331精度逐轮上升说明参数聚合确实在起作用。如果第一轮就接近 0.9可能是数据分片太均匀如果一直卡在 0.1 附近多半是学习率或聚合权重写错了。验证数据不出本地最直接的办法在local_train里加一行打印确认读取路径。print(fclient {client_id} reads from ./data/client_{client_id})输出只会出现各自的目录名不会出现其他客户端的路径。你还可以把data/client_1临时改名再跑一次会发现只有 client_1 报错其他两个照常训练——这证明客户端之间没有数据依赖。如果你想用 TaoToken 的模型对话能力做辅助验证比如让模型解释某一轮精度波动可以调用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels把每轮精度贴进去问为什么第 2 轮到第 3 轮提升变缓模型会给出学习率衰减、样本分布等角度的分析。这一步不是必须的但对理解曲线很有帮助。5. 本篇常见错排查401、local proxy failed 与 choices 报错跑联邦实验时报错往往不在算法本身而在调用链路上。下面几个是我实际遇到过的。401 UnauthorizedKey 没填对或带了多余空格。检查config.json里的api_key确认是sk-开头且没有换行。如果用的是环境变量确认export TAOTOKEN_KEY...后重新开终端。local proxy failed / connection refused这类报错通常是本地网络配置问题。先确认base_url写的是https://taotoken.net/api没有多写/v1或结尾斜杠。然后用 curl 做最小验证curl https://taotoken.net/api/models \ -H Authorization: Bearer sk-你的Key返回 JSON 列表说明链路通返回 401 说明 Key 问题超时说明网络层需要检查。reading choices 报错KeyError: choices说明返回体不是标准对话结构常见原因是模型 ID 写错或者请求发到了非对话端点。确认model_id与模型列表里的一致请求路径是/chat/completions。OAuth 相关报错如果你在 Claude Code 或类似工具里配置注意区分 API Key 模式和 OAuth 模式。用 TaoToken 时走 API KeyBase URL 填https://taotoken.net/api不要混用 OAuth 流程。Claude Code 的接入参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode聚合后精度不升反降检查fed_avg里的权重是不是用了样本数。如果三个客户端样本数差异大等权平均会让小客户端拖后腿。另外确认local_epochs不要设太大本地过拟合会破坏全局收敛。客户端数据串了确认datasets.MNIST的root参数用的是f./data/client_{client_id}而不是统一的./data。这是最容易犯的错一旦写错三个客户端读的是同一份数据联邦就退化成集中式了。6. 从实验到落地把统一 Key 用在长期联邦任务上跑通 5 轮 MNIST 只是起点。真实场景里客户端数量可能上百轮次可能上千这时候统一 Key 统一 Base URL的价值就体现出来了你不需要为每个客户端维护一套凭证聚合服务器上的辅助模型异常检测、参数质量评分、日志分析都走同一个入口。如果你打算把这类实验做成长期任务比如每天定时跑一轮联邦训练并记录精度可以了解 Coding Plan 的额度方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan需要新建更多 Key 做环境隔离时回到控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole参数格式或端点细节以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后给一个实用技巧把每轮的global_state存成文件命名带轮次比如global_round_3.pt。这样精度异常时可以回滚到上一轮对比两次聚合的差异比从头重跑省时间。联邦学习的调试本质上就是让每一轮的变化都可追溯。