联邦学习实验规范

面向研究复现与论文报告的统一实验设置约定。与知识地图的基线定义配套使用：报告结果前先明确「集中参考 / 明文协议参考 / 同预算实现」三组对照的身份，避免把额外资源误当成方法增益。

一句话原则

每个实验都要能回答：数据怎么划分、谁参与、跑了多少轮、报告哪些数、和谁比、预算是否相同。

使用方式与统一模板

各教学章节只定义“要破坏哪个假设、扫描哪个方法特有变量”；本页统一规定所有实验都要报告的配置、统计、系统成本和复现信息。设计实验时先填写：

字段	必须回答的问题
研究问题	哪个可证伪结论正在接受检验？
自变量	主动改变哪个数据、系统、安全或算法因素？
控制变量	哪些训练预算、模型、划分和硬件保持一致？
对照组	Local-only、集中参考、明文协议参考和同预算实现中哪些适用？
结果指标	哪个主指标判定结论，哪些效用、隐私、公平和系统指标解释原因？
独立重复	独立单位是什么，使用多少seed，如何报告不确定性？
失败判据	什么观测会推翻原假设或证明方法失效？

章节中的实验清单不能替代这张模板；反过来，模板也不能替代章节给出的领域特有扰动。

一、数据划分协议

• 横向（HFL）：
  • Pathological 划分：按标签把样本分给各客户端（例如每客户端只含1—2类标签），用于构造强标签异质性；必须注明这是受控合成划分，不直接代表真实场景；
  • Dirichlet 划分：用Dirichlet分布 按标签采样，越小通常表示标签分布越集中；报告采样方法、与实际生成的分布统计；
  • 自然划分：按真实用户、设备、机构、地区或时间边界划分；报告分组规则和各组规模，不能把Dirichlet合成划分称为“真实划分”；
  • 数据量长尾：客户端样本量按幂律分布，同时报告样本量加权与均匀加权两种聚合。
• 纵向（VFL）：明确共同样本比例、特征划分与标签方；报告实体对齐的错误匹配与漏匹配率（真实对齐存在噪声）。
• 迁移（FTL）：明确源域/目标域、域相似度度量（如 MMD）、对齐样本量与标签量。
• 异质性报告：至少报告一个量化指标（如标签分布差异、MMD 距离、样本量基尼系数），不能只说 "non-IID"。

二、训练配置报告

配置项	报告要求
本地步数 、批大小 、学习率	必报；扫参范围与最终值
参与率 、总轮数	必报；说明选择依据
随机种子	至少3个独立seed并报告mean ± std；需要显著性检验时应增加独立重复次数并说明检验功效限制
客户端选择	随机 / 速度优先 / 质量优先，说明是否与数据分布相关
优化器与调度	客户端与服务器两侧分别说明
硬件与实现	框架、版本、设备类型（CPU/GPU 型号）

三、评估与统计

• 核心指标：平均性能 + 最差群体性能（10% 分位或最差客户端/医院），单报平均会掩盖异质性下的退化；
• 分类与排序：除固定阈值指标外，按类别不平衡程度报告ROC-AUC或PR-AUC；说明阈值选择规则；
• 概率校准：报告Brier分数、ECE（期望校准误差）和必要的可靠性图；AUC衡量排序能力，不等于校准质量；
• 显著性：在足够多的独立seed上按seed配对检验并报告置信区间与效应量；不能把同一轮实验中的客户端或样本当作独立重复。独立重复过少时只报告描述性统计并声明证据有限；
• 消融矩阵：对声称产生增益的模块（如客户端筛选、梯度稀疏化、DP）分别移除，验证其独立贡献；
• 隐私实验：报告 、裁剪率、更新信噪比、成员推断攻击成功率；DP 实验必须注明保护单位（记录级/用户级/客户端级）。

四、通信与系统指标

• 通信量：报告总上行字节数与相对基线的降幅，说明是否含模型、梯度和掩码/密文开销；
• 墙钟时间：区分计算时间与通信时间，说明带宽与延迟假设；
• 带宽分档：在低速/高速网络两档分别报告，避免单一带宽结论；
• 能耗与内存：移动端场景报告峰值内存与能耗。

五、复现清单

1. 数据划分脚本与种子；
2. 训练配置（超参数网格与最终值）；
3. 代码与依赖版本（框架、CUDA、库）；
4. 基线实现来源（自实现 / 官方仓库 / 第三方实现，注明版本）；
5. 评价脚本与统计检验代码。

六、常见失分点（论文写作对照）

• 只报平均精度，不报最差群体 → 异质性方法无法体现价值；
• 基线缺「同预算」约束 → 方法增益可能来自更多轮数/更多计算；
• 隐私实验不说明保护单位 → 记录级与用户级的 不可比；
• 消融不完整 → 无法判断每个模块的独立贡献；
• 不报告随机种子 → 结果不可复现。

本页为规范清单而非实验结果；与「教学构造声明」一致，本专题内的数值示例不得作为规范验证的替代。

七、最小可复现实验：本地步数与客户端漂移

前六节回答“实验应该报告什么”，本节给出一个从命令、原始结果到结论边界都可检查的完整案例。它只使用 Node.js 标准库，不下载数据，也不依赖联邦学习框架。

npm run fl:experiment

命令会执行 experiments/federated-learning/fedavg-drift.mjs，并覆盖生成 experiments/federated-learning/results/fedavg-drift.json。JSON同时保存配置、每个seed的原始结果和汇总统计；正文表格只是其便于阅读的摘录。

7.1 研究问题与失败判据

研究问题：在客户端目标异质时，增大FedAvg本地步数能否用更少通信完成相同数量的本地更新？它是否会同时放大客户端漂移并损害尾部客户端？

将问题拆成三个可分别被否证的判断：

1. 若增大后末轮平均客户端漂移没有增加，则“多步本地训练放大漂移”在本设置下不成立；
2. 固定每客户端本地步数预算时，若通信轮数没有按减少，则脚本的预算控制或通信定义有误；
3. 若最差客户端指标没有下降，或不确定性不足以区分差异，则不能声称漂移已经造成尾部性能损害。

这里特意把“发生漂移”和“漂移造成显著效用损失”分开。前者是参数轨迹观测，后者需要性能差异与足够统计证据，不能从漂移值单独推出。

7.2 数据、模型与控制变量

项目	本实验设置
数据	10个合成客户端；每客户端160条训练样本和160条测试样本
异质性	客户端截距、特征尺度和特征均值随客户端变化，同时产生基础率与局部目标差异
模型	带截距的二元逻辑回归，共3个参数
优化	客户端全批量梯度下降，学习率0.2；所有客户端每轮参与；服务器按客户端均匀平均
独立重复	seed为11、23、37、53、71；同一seed下各方法复用完全相同的数据
主指标	客户端平均balanced accuracy、最差客户端balanced accuracy
解释指标	全局平均交叉熵、末轮本地模型到轮初全局模型的平均L2距离
通信估算	每轮每客户端上下行各3个Float64参数；不含序列化、身份、容错、安全聚合等协议开销

这是受控合成教学实验，而非真实医疗或设备数据。客户端同时存在特征与条件分布差异，因此结果不能直接外推为“所有标签偏斜都会如此”，也不能用于比较真实联邦框架的吞吐量。

7.3 两种公平比较视角

单独固定通信轮数或单独固定计算量都会回答不同问题，所以本实验同时报告两张表：

• 相同通信轮数：所有方法均通信40轮，观察每轮多做本地计算后的效果；总计算量并不相同。
• 相同本地计算量：每客户端均执行200步本地全批量更新，分别通信200、40、10轮；通信量不同。

通信量只是脚本定义下的理论记账值，不能替代真实网络测量。结果为5个seed的mean ± sample std；95%置信区间也保存在JSON中。5次重复只适合描述性判断，不据此宣称统计显著。

7.4 运行结果

固定通信40轮：

方法	每客户端累计本地步数	平均客户端BA	最差客户端BA	全局损失	末轮平均漂移	估算通信量
FedSGD / FedAvg	40	75.46% ± 1.42%	69.69% ± 3.34%	0.5592 ± 0.0124	0.0382 ± 0.0010	19,200 B
FedAvg	200	75.59% ± 1.29%	69.34% ± 3.10%	0.5480 ± 0.0167	0.1671 ± 0.0050	19,200 B
FedAvg	800	75.41% ± 1.49%	68.73% ± 3.98%	0.5486 ± 0.0171	0.5114 ± 0.0127	19,200 B

固定每客户端200步本地更新：

方法	通信轮数	平均客户端BA	最差客户端BA	全局损失	末轮平均漂移	估算通信量
FedSGD / FedAvg	200	75.52% ± 1.30%	69.60% ± 3.18%	0.5480 ± 0.0167	0.0362 ± 0.0012	96,000 B
FedAvg	40	75.59% ± 1.29%	69.34% ± 3.10%	0.5480 ± 0.0167	0.1671 ± 0.0050	19,200 B
FedAvg	10	75.41% ± 1.48%	68.65% ± 4.14%	0.5487 ± 0.0169	0.5112 ± 0.0128	4,800 B

脚本还把集中全批量梯度下降与全参与、的FedSGD作参数级核对；5个seed中的最大权重L2误差为，符合浮点舍入范围内的等价关系。

7.5 如何解读，而不是只看谁最高

1. 漂移判断成立：固定通信或固定计算时，末轮平均漂移都随单调增大；约为的14倍。
2. 通信—计算交换成立：固定200步本地更新时，与分别把估算通信量降至的与。
3. 平均性能没有形成可分离优势：三种设置的平均balanced accuracy十分接近，置信区间大量重叠；不能把最高的单个均值写成方法胜出。
4. 尾部损害只有方向性迹象：最差客户端均值从69.60%降至68.65%，但seed间方差较大且置信区间重叠。因此本实验支持“漂移增加”，不充分支持“尾部性能显著恶化”。
5. 固定通信表不能证明计算高效：实际用了的20倍本地更新；其损失更低不能脱离额外计算解释。

若要把第三个判断升级为更强证据，应预先确定最小关注效应，增加独立seed，并对同一seed下的方法差值做配对置信区间；还应扫描异质性强度，而不是只保留最容易展示结论的一档。

7.6 P3-B：异质性强度与配对证据

下面继续检验上一节留下的问题：漂移随异质性增强后，尾部性能是否必然下降？运行：

npm run fl:experiment:scan

扫描将客户端截距、特征尺度偏差和特征均值偏移同时乘以强度系数：时各客户端来自相同生成分布，严格复现P3-A设置。每档使用20个seed，并固定每客户端200步本地更新。对每个seed使用同一份数据计算“或减去”的配对差值；完整原始结果保存在 experiments/federated-learning/results/fedavg-heterogeneity-scan.json。

漂移的绝对均值与相对的配对差值：

异质性	漂移	漂移	漂移	漂移：（95% CI）
0	0.0082	0.0390	0.1288	+0.1206 [0.1119, 0.1293]
0.5	0.0212	0.0995	0.3155	+0.2943 [0.2855, 0.3030]
1.0	0.0368	0.1703	0.5218	+0.4849 [0.4752, 0.4947]
1.5	0.0495	0.2263	0.6752	+0.6257 [0.6134, 0.6381]

漂移关系很清楚，但性能关系并不相同。下表只列；balanced accuracy使用百分点差，正值表示更高，损失正值则表示更差。

异质性	平均BA百分点（95% CI）	最差客户端BA百分点（95% CI）	全局损失（95% CI）
0	+0.004 [-0.025, 0.033]	+0.067 [-0.073, 0.206]	+0.000006 [-0.000015, 0.000027]
0.5	+0.050 [-0.016, 0.116]	-0.098 [-0.404, 0.208]	-0.000008 [-0.000229, 0.000213]
1.0	+0.068 [-0.086, 0.222]	-0.299 [-0.937, 0.338]	+0.001055 [0.000390, 0.001720]
1.5	+1.006 [0.552, 1.460]	+3.462 [1.972, 4.952]	+0.004751 [0.003533, 0.005969]

配对结果的结论边界：

1. 异质性会放大多步本地训练的额外漂移：四档中的漂移差置信区间都远离0，并随增大。
2. 漂移增大不等于尾部指标必然下降：时最差客户端BA差值均无法与0分离；时反而观察到正差值。
3. 指标可能给出相反方向：时平均与最差balanced accuracy提高，但交叉熵显著增大。阈值分类表现和概率质量回答不同问题，不能挑一个指标宣布方法全面胜出。
4. 最高异质性结果不是FedAvg普遍优势：该合成生成器同时改变多个分布因素，且只使用逻辑回归、全参与和固定学习率。局部多步恰好改变决策边界的结果不能外推到其他数据与模型。
5. P3-A的克制结论得到加强：现有证据支持“漂移随本地步数和异质性增加”，但否定“更大漂移必然造成尾部性能下降”这一过强推断。

扫描脚本还执行两项回归检查：集中全批量训练与全参与FedSGD的最大参数L2误差为；的前5个seed与P3-A固定计算结果逐字段完全一致。

7.7 P3-C：FedProx约束漂移的收益与代价

P3-B说明漂移增大不必然导致性能下降，因此不能只看漂移值断言FedProx更好。本实验固定、10轮通信和每客户端200步本地更新，只改变近端强度：

npm run fl:experiment:fedprox

客户端每步使用：

其中在一轮本地训练期间保持为共同起点。是FedAvg回归基线；其结果与P3-B的逐字段完全一致。每个使用相同20个seed、相同数据、通信轮数、梯度评估次数和消息维度。FedProx每步还多一次维近端向量运算，因此这里只能称为同梯度预算，不能声称FLOPs完全相等。

预注册的全部都予以保留，不根据测试结果只展示最有利设置。完整结果位于 experiments/federated-learning/results/fedprox-sensitivity.json。

末轮平均客户端漂移：

异质性	FedAvg	FedProx	FedProx	FedProx
0	0.1288	0.1105	0.0690	0.0382
1.0	0.5218	0.4418	0.1600	0.0480
1.5	0.6752	0.5725	0.2057	0.0565

在下，相对FedAvg的配对差值如下。balanced accuracy仍使用百分点差；漂移与损失使用原量纲。

	漂移（95% CI）	全局损失（95% CI）	平均BA百分点（95% CI）	最差客户端BA百分点（95% CI）
0.1	-0.1027 [-0.1047, -0.1006]	-0.000650 [-0.000791, -0.000510]	-0.048 [-0.124, 0.028]	-0.097 [-0.442, 0.249]
1	-0.4695 [-0.4791, -0.4600]	-0.000413 [-0.002233, 0.001408]	-0.460 [-0.751, -0.169]	-2.033 [-3.669, -0.398]
5	-0.6187 [-0.6313, -0.6060]	+0.038655 [0.034482, 0.042828]	-0.978 [-1.434, -0.523]	-3.070 [-4.489, -1.651]

结果解读：

1. 近端项确实限制局部移动：所有异质性档、所有的漂移配对区间都低于0，且本设置下越大，漂移越小。
2. 限制漂移不是独立的最终目标：时，和显著降低平均与最差客户端balanced accuracy；更小的漂移没有转化成更好的分类指标。
3. 弱约束只显示有限收益：在和下略微降低交叉熵，但balanced accuracy差值无法与0分离。不能据此宣称它改善了尾部公平。
4. 强约束会阻碍给定轮数内的优化：在三档异质性下都明显压低漂移，同时显著增大全局损失；这是“模型不敢离开轮初起点”的代价。
5. 末轮全局更新幅度不能单独代表收敛速度：部分FedProx设置在第10轮仍有较大更新，而FedAvg已接近自身固定点。它说明轨迹所处阶段不同，不等于FedProx取得了更多有效进展。
6. 没有数据无关的最佳：本实验完整报告敏感性而不选冠军。真实调参必须使用独立验证数据，并给予FedAvg相当的学习率与训练预算搜索机会。

因此，本案例支持FedProx“通过近端项抑制客户端漂移”的机制判断，但不支持“FedProx在Non-IID下必然优于FedAvg”或“漂移越小越公平”的笼统结论。