1. FLGo 跑实验时算法和模型配置到底卡在哪FLGo 是一个轻量级的联邦学习框架能让你用几行代码就把 FedAvg、FedProx 这类算法跑起来也能自由替换 CNN、MLP 等模型结构适合做联邦学习实验的学生和算法工程师。但真正上手时很多人会卡在同一个地方算法和模型都写对了训练却跑不通或者跑出来的结果和预期对不上。原因往往不在算法本身而在运行配置这一层——config.toml里的 benchmark 参数、settings.json里的运行选项、模型初始化接口的写法任何一处对不上实验就会静默失败或者报一堆看不懂的错。更现实的问题是当你想在 FLGo 里接入一个远程模型服务来做对比实验或者让联邦训练过程中的某些环节调用统一的大模型 API 通道时Key 的管理会变得很乱。每个实验脚本里硬编码一个 Key换环境就要改一遍集群上跑多个任务时更是容易串。这篇就聚焦 FLGo 的算法与模型运行配置环节给出config.toml和settings.json的可复制骨架演示怎么通过 TaoToken 统一 Key 通道完成模型调用配置最后附上启动验证和报错排查的具体动作。目标很直接让你一次跑通算法与模型的组合不用在配置上反复试错。2. 前置准备TaoToken 统一 Key 通道与 FLGo 环境在动 FLGo 的配置之前先把 Key 通道这件事理清楚。TaoToken 提供的是统一的模型调用入口你只需要一个 Key就能在多个模型之间切换不用为每个模型单独申请和管理凭证。对 FLGo 这种需要反复跑不同算法、不同模型组合的实验场景来说这一点很实用——实验脚本里只引用一个环境变量换模型时改配置就行不用动代码。你需要先拿到 API Key。访问 https://taotoken.net/api-keys 创建然后把它写进环境变量不要硬编码在脚本里export TAOTOKEN_API_KEYsk-你的keyFLGo 本身的安装很简单用 pip 就行pip install flgo如果你要用 GPU 跑确认 PyTorch 版本和 CUDA 对得上。FLGo 对 PyTorch 的依赖比较直接装好 torch 之后 flgo 会自动识别设备。我试过在 CPU 和单卡环境上跑配置逻辑是一样的只是gpu参数要对应改。TaoToken 的 API 地址是 https://taotoken.net/api这个地址在后面的配置里会用到。注意 API 地址不带任何查询参数保持干净。模型对话入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 配置过程中遇到参数不确定的可以对照文档查。3. 可复制配置config.toml 与 settings.json 骨架FLGo 的运行配置分两层任务级的config.toml定义 benchmark 和数据划分运行级的settings.json定义训练超参和模型选择。下面给出可直接复制的骨架。先看config.toml它通常放在你的任务目录下[benchmark] name flgo.benchmark.mnist_classification para {} [partitioner] name IIDPartitioner para { num_clients 100 } [model] name cnn para {}这里benchmark.name决定数据集和默认模型partitioner决定客户端数据怎么分。IIDPartitioner 是均匀划分做基线实验最常用。如果你要换非独立同分布把 name 改成DirichletPartitionerpara 里加alpha 0.5。再看settings.json它定义训练过程{ num_rounds: 30, num_epochs: 1, batch_size: 8, learning_rate: 0.1, gpu: 0, algorithm: fedavg, model: cnn, api_base: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY }关键点在于api_base和api_key_env这两个字段。api_base指向 TaoToken 的统一入口api_key_env告诉 FLGo 从哪个环境变量读 Key。这样你的实验脚本里不需要出现任何明文 Key集群上跑多个任务时也不会串。如果你要在代码里直接初始化等价写法是import flgo import flgo.algorithm.fedavg as fedavg import os task ./flgo_exp config { benchmark: {name: flgo.benchmark.mnist_classification}, partitioner: {name: IIDPartitioner, para: {num_clients: 100}} } if not os.path.exists(task): flgo.gen_task(config, task_pathtask) option { num_rounds: 30, num_epochs: 1, batch_size: 8, learning_rate: 0.1, gpu: 0 } runner flgo.init(task, fedavg, optionoption) runner.run()这段代码跑的是 FedAvg 加默认 CNN。要换算法把fedavg换成fedprox就行要换模型在flgo.init里加model参数。4. 算法与模型接入从 FedAvg 到自定义模型FLGo 的算法接入靠flgo.init的第二个位置参数。内置算法都在flgo.algorithm下常用的有 fedavg、fedprox、fedopt 等。切换算法不需要改任务配置只改这一处import flgo.algorithm.fedprox as fedprox runner flgo.init(task, fedprox, optionoption) runner.run()模型接入稍微复杂一点因为 FLGo 把模型视为 benchmark 的一部分。每个 benchmark 的model子模块里放着适配该数据集的模型。MNIST 分类任务下有 cnn 和 mlp 两个可选。切换方式是在 init 时传model参数import flgo.benchmark.mnist_classification.model.cnn as cnn import flgo.benchmark.mnist_classification.model.mlp as mlp cnn_runner flgo.init(task, fedavg, optionoption, modelcnn) mlp_runner flgo.init(task, fedavg, optionoption, modelmlp)自定义模型时需要继承FModule并实现init_local_module和init_global_module两个接口。前者给客户端分配本地模型后者给服务器分配全局模型。经典横向联邦里只有 Server 持有全局模型所以init_global_module里判断一下类名即可from torch import nn from flgo.utils.fmodule import FModule class Model(FModule): def __init__(self): super().__init__() self.encoder nn.Sequential( nn.Conv2d(1, 32, 5, padding2), nn.ReLU(), nn.MaxPool2d(2), nn.Conv2d(32, 64, 5, padding2), nn.ReLU(), nn.MaxPool2d(2), nn.Flatten(1), nn.Linear(3136, 512), nn.ReLU(), ) self.head nn.Linear(512, 10) def forward(self, x): return self.head(self.encoder(x)) def init_local_module(object): pass def init_global_module(object): if Server in object.__class__.__name__: object.model Model().to(object.device) class MyCNN: init_local_module init_local_module init_global_module init_global_module然后在 init 时传modelMyCNN。FLGo 0.0.17 之后还提供了flgo.convert_model函数能把普通 nn.Module 快速转成可用的模型类省去手写两个接口的步骤model flgo.convert_model(Model) runner flgo.init(task, fedavg, optionoption, modelmodel)这一步的坑在于convert_model只做封装不改变模型结构如果你的 forward 里有自定义逻辑转换后要确认输入输出维度对得上。5. 验证请求与成功结果配置写完之后先做一次最小验证确认 Key 通道和 FLGo 都能正常工作。最直接的方式是跑一个短轮次的实验option {num_rounds: 2, num_epochs: 1, batch_size: 8, learning_rate: 0.1, gpu: 0} runner flgo.init(task, fedavg, optionoption) runner.run()如果一切正常终端会输出每轮的 loss 和 accuracy类似Round 1/2, Loss: 2.301, Accuracy: 0.112 Round 2/2, Loss: 2.289, Accuracy: 0.135同时任务目录下会生成record文件夹里面有训练日志和模型检查点。你可以用flgo.analysis里的工具画收敛曲线确认训练确实在推进。验证 TaoToken 通道是否生效可以在脚本里加一段独立的调用测试import os, requests api_key os.environ.get(TAOTOKEN_API_KEY) resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: fBearer {api_key}}, json{model: gpt-4o-mini, messages: [{role: user, content: ping}]} ) print(resp.status_code, resp.json()[choices][0][message][content][:50])返回 200 并且有内容输出说明 Key 通道没问题。这一步单独跑不要混在 FLGo 训练里方便定位问题。6. 本篇常见错排查跑 FLGo 配置时报错集中在几个地方。下面按现象列出来对照排查。报错一ModuleNotFoundError: No module named flgo.algorithm.xxx算法名拼错了或者你用的 FLGo 版本里没有这个算法。先确认版本pip show flgo。内置算法列表可以查接入文档 https://taotoken.net/doc 里的说明或者直接看flgo/algorithm目录。报错二KeyError: model或模型维度不匹配自定义模型的输出维度和数据集类别数对不上。MNIST 是 10 类你的 head 层输出必须是 10。另外确认init_global_module里确实给 Server 赋了模型否则服务器端拿不到全局模型。报错三requests.exceptions.ConnectionError或 401Key 没读到或者环境变量名写错了。检查echo $TAOTOKEN_API_KEY有没有输出。如果是在 Jupyter 里跑环境变量可能没继承用os.environ手动设一下。401 一般是 Key 无效去 https://taotoken.net/api-keys 重新生成一个。报错四训练跑完但 accuracy 一直是 0.1 左右学习率太大或者 batch_size 太小导致不收敛。MNIST 上 lr0.1 配 batch_size8 有时会震荡把 lr 降到 0.01 试试。另外确认 partitioner 的 num_clients 和实际客户端数一致不一致会导致部分客户端没数据。报错五GPU 显存不够gpu参数设了但显存不足。把 batch_size 调小或者改成gpu: -1用 CPU 跑。FLGo 默认会占满指定 GPU多任务并行时要注意错开。排查顺序建议先单独验证 Key 通道再跑最小轮次实验最后加算法和模型组合。这样出问题时能快速定位是配置层还是代码层。7. 下一步把配置固化下来配置跑通之后建议把config.toml和settings.json固化到任务目录里不要每次在脚本里手写。这样换算法和模型时只改配置文件代码保持不动。长期做联邦学习实验或者要跑 Agent 类任务的话可以考虑用 Coding Plan 来管理多个实验的 Key 和配额入口在 https://taotoken.net/coding-plan 。模型对话的调试入口在 https://taotoken.net/models 接入相关的参数细节查 https://taotoken.net/doc 。把 Key 通道和 FLGo 配置分开管理实验复现会省很多事。
