1. 横向联邦 MNIST 实验：从数据孤岛到全局模型
联邦学习（Federated Learning）是一种让多个参与方在不共享原始数据的前提下，协作训练同一个全局模型的分布式机器学习方法。它的核心承诺是"数据不出本地，只交换模型参数"。横向联邦学习是其中最直观的一类：各参与方拥有相同的数据特征（比如都是 28x28 的灰度图），但样本不同（各自持有不同批次的图片）。这正好对应"多家医院都有年龄、病史字段，但患者不同"的真实场景。
这篇文章面向刚接触联邦学习的开发者，用 MNIST 手写数字数据集把整条链路跑通：启动 3 个客户端，每个客户端只用自己的本地数据训练，把参数更新上传到中心服务器做加权聚合（FedAvg），再观察每一轮全局精度的变化。你会得到可复制的环境配置、聚合脚本和验证动作，最后能亲眼确认各客户端的原始数据从未离开本地目录。
适合谁：会一点 Python、装过 PyTorch、想搞明白"联邦"到底比"集中式"多了哪几步的人。整篇不需要 GPU，CPU 上跑 3 个客户端、每客户端几千条样本，几分钟就能看到精度曲线往上走。
在动手之前，先把工具链准备好。联邦学习实验里最容易被忽略的不是算法，而是"多进程/多客户端如何统一管理模型调用与密钥"。我这次把模型侧的调用统一走 TaoToken 的 Key，这样后面无论扩到 5 个还是 10 个客户端，鉴权和模型标识都不用改来改去。
2. TaoToken 前置：统一 Key 与模型接入准备
TaoToken 是一个模型调用聚合平台，你可以把它理解成"一个 Key 打通多种模型"的入口。对联邦学习实验来说，它的价值在于：当你想在聚合服务器上挂一个"模型质量评估"或"参数异常检测"的辅助模型时，不需要为每个客户端单独申请一套凭证，统一用同一个 Key 和 Base URL 就能调用。
先做三件事。
第一，拿到 API Key。访问控制台创建密钥：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console创建后在 API Keys 页面复制，形如sk-xxxxxxxx。这个 Key 只用于服务端调用，不要写进客户端本地训练脚本里明文分发。
第二，确认接入地址。API 基址是：
https://taotoken.net/api注意这个地址不带任何查询参数，直接作为 OpenAI 兼容的base_url使用。
第三，选模型 ID。在模型对话页面可以查看当前可用模型列表：
https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=models把 Key、Base URL、Model ID 这三件套记下来，后面配置里会反复用到。如果你打算长期跑编码类或 Agent 类任务，可以顺带了解 Coding Plan：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan接入文档在这里，遇到参数格式问题优先查它：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc注意：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}", train=True, download=True, transform=tf) return DataLoader(ds, batch_size=64, shuffle=True) 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(), lr=cfg["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", train=False, download=True, transform=tf) loader = DataLoader(ds, batch_size=256) 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(f"Round {r+1} 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(f"client {client_id} reads from ./data/client_{client_id}")输出只会出现各自的目录名，不会出现其他客户端的路径。你还可以把data/client_1临时改名，再跑一次，会发现只有 client_1 报错，其他两个照常训练——这证明客户端之间没有数据依赖。
如果你想用 TaoToken 的模型对话能力做辅助验证，比如让模型解释某一轮精度波动，可以调用：
https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=models把每轮精度贴进去问"为什么第 2 轮到第 3 轮提升变缓"，模型会给出学习率衰减、样本分布等角度的分析。这一步不是必须的，但对理解曲线很有帮助。
5. 本篇常见错排查：401、local proxy failed 与 choices 报错
跑联邦实验时，报错往往不在算法本身，而在调用链路上。下面几个是我实际遇到过的。
401 Unauthorized：Key 没填对或带了多余空格。检查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 Key，Base URL 填https://taotoken.net/api，不要混用 OAuth 流程。Claude Code 的接入参考：
https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claudecode聚合后精度不升反降：检查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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan需要新建更多 Key 做环境隔离时，回到控制台：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console参数格式或端点细节以接入文档为准：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc最后给一个实用技巧：把每轮的global_state存成文件，命名带轮次，比如global_round_3.pt。这样精度异常时可以回滚到上一轮，对比两次聚合的差异，比从头重跑省时间。联邦学习的调试，本质上就是"让每一轮的变化都可追溯"。
)
