Flower 基线深度解析：FedXGBllr —— 无梯度联邦 XGBoost 与可学习学习率（Gradient-less Federated Gradient Boosting Trees）

Flower 基线深度解析：FedXGBllr —— 无梯度联邦 XGBoost 与可学习学习率（Gradient-less Federated Gradient Boosting Trees）

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

本文以 Flower 框架基线baselines/hfedxgboost为研究对象，完整剖析论文Gradient-less Federated Gradient Boosting Trees with Learnable Learning Rates（Ma et al., 2023，arXiv:2304.07537）所提出的 FedXGBllr 算法在水平联邦学习场景下的复现实现：它如何摆脱梯度共享、如何用 1 层 CNN 把各客户端 XGBoost 树集成的输出「学习」出可学习的学习率，以及如何通过 Hydra 配置、Flower 模拟器与 WandB 完成从环境搭建、实验复现到超参数微调、新增数据集的完整闭环。读完本文，你将掌握该基线全部配置项的含义、逐条可复现的命令，以及其底层源码调用链。

一、背景与核心思想：为什么需要「无梯度」的联邦 XGBoost

XGBoost 在表格数据上以稳健性著称，而联邦学习（FL）要解决的核心矛盾正是「数据不出域」前提下的模型协同训练。现有水平联邦 XGBoost 工作大多依赖梯度共享（gradient sharing），这会带来两个问题：

1. 通信频率高：梯度按「节点（node）级」粒度共享，每个分裂节点的梯度都要跨客户端传输，通信轮次与通信开销巨大；
2. 隐私顾虑：梯度的共享间接暴露了本地数据的统计信息，存在隐私泄漏风险。

FedXGBllr 的创新在于完全不依赖梯度共享，转而让「聚合后的树集成」的学习率（learning rate）变得可学习——用一个极轻量的 1 层 CNN 对来自各客户端树集成的预测输出做加权组合学习，从而同时提升隐私性与通信效率。论文在多个分类与回归数据集上的实验表明，该方法能达到与 SOTA 方法相当的性能，同时将通信轮次与通信开销降低25x～700x（该数字来自论文摘要，本基线 README 引用原论文结论）。

本基线（baselines/hfedxgboost）正是对该算法的可复现实现，重点关注 a9a、cod-rna、ijcnn1、space_ga 四个数据集在论文 Table 2（联邦二分类）中的复现结果，并额外覆盖 abalone、cpusmall、YearPredictionMSD 三个回归数据集。

二、基线概览：实现了什么

2.1 数据集规模总览

所有数据集均来自 LIBSVM 官方源（见 dataset_preparation.py 中的下载逻辑），以 libsvm 稀疏格式存储，运行时自动下载，无需手动准备数据。

三、算法工作流程与源码级拆解

3.1 总体流水线：从数据划分到模拟启动

整个实验由 main.py 中的main(cfg)驱动，流程如下：

1. 打印解析后的 Hydra 配置（OmegaConf.to_yaml）；
2. 若centralized=True且dataset.dataset_name == "all"，调用run_centralized批量跑全部数据集（仅终端输出，不落盘）；否则用CentralizedResultsWriter将单数据集结果写入results_centralized.csv；
3. 若centralized=False（联邦模式），先根据use_wandb决定是否初始化 WandB；
4. 实例化EarlyStop早停器，通过load_single_dataset加载数据集，再经divide_dataset_between_clients将训练集 IID 切分给各客户端；
5. 通过 Hydrainstantiate装配自定义策略FedXgbNnAvg（见 strategy.py），并绑定serverside_eval作为服务端全局评估函数；
6. 构造client_fn返回FlClient，以FlServer作为服务端调用fl.simulation.start_simulation启动模拟；
7. 训练结束后由ResultsWriter.extract_best_res提取历史最佳结果与轮次，写入results.csv。

3.2 核心策略 FedXgbNnAvg：CNN 参数与树的分离式聚合

策略类FedXgbNnAvg继承自 Flower 内置的FedAvg，其aggregate_fit做了三件事（strategy.py）：

• 将各客户端返回的CNN 权重通过parameters_to_ndarrays反序列化后，用flwr.server.strategy.aggregate.aggregate做按样本数加权的平均（weights_results携带fit_res.num_examples）；
• 将各客户端的XGBoost 树集成（fit_res.parameters[1]）原样收集到trees_aggregated列表中——树本身不跨客户端融合，而是保留每棵树的原始结构，供 CNN 学习组合；
• 聚合后的参数以[parameters_aggregated, trees_aggregated]二元组形式返回，供服务端与客户端使用。

策略的evaluate直接复用evaluate_fn（即服务端全局评估serverside_eval），fraction_evaluate=0.0表示不做客户端联邦评估，完全依赖服务端在完整测试集上的全局评估（见 base.yaml）。

3.3 客户端 FlClient：用树输出训练 CNN

FlClient（client.py）的关键机制：

• get_parameters：从本地训练数据中取一份完整数据，调用fit_xgboost训练一棵含n_estimators_client棵树的 XGBoost 模型，并连同客户端 id 一起返回（(tree, int(self.cid))）；
• fit：接收服务端下发的全局 CNN 权重与聚合树列表，调用 utils.py 中的single_tree_preds_from_each_client——该函数把每个客户端树集成中的每一棵树单独抽取出来（single_tree_prediction使用 XGBoost 的iteration_range=(n_tree, n_tree+1)与output_margin=True得到单棵树边际输出），拼接成形状为(样本数, client_num × n_estimators_client)的特征矩阵，再作为 CNN 的输入；CNN 用 Adam（betas=(0.5, 0.999)，学习率来自clients.CNN.lr）按迭代次数（num_iterations个 batch）训练；
• evaluate：在本地验证集（由val_ratio控制比例）上评估 CNN。

值得注意的是，训练按「迭代/batch 数」而非「epoch」定义（train方法注释明确说明），这在客户端数据量不均时能保持一致更新量。

3.4 CNN 模型：可学习学习率的载体

CNN（models.py）结构极简：

• nn.Conv1d：输入通道 1，输出通道 64，卷积核大小与步长均为n_estimators_client（对每个客户端的树输出做下采样/整合）；
• nn.Linear(n_channel * client_num, 1)直连输出层；
• 二分类任务末层为Sigmoid（配合BCELoss），回归任务为Identity（配合 MSE）；
• 全连接层采用 kaiming_uniform_ 初始化。

正是这 1 层 CNN 学习出的权重，充当了「可学习的学习率」角色：它决定聚合树集成中各棵树预测的加权方式，从而替代了传统梯度传递。

3.5 服务端 FlServer：早停 + 全局评估

FlServer（server.py）继承fl.server.Server，扩展点包括：

• _get_initial_parameters：从随机一个客户端拉取初始 CNN 权重与树（get_parameters）；
• check_res_cen：每轮先执行fit_round完成聚合，再调用策略的evaluate做服务端全局评估，并驱动EarlyStop——若连续early_stop_patience_rounds轮 loss 无改善则提前终止（utils.py 中EarlyStop类实现）；
• serverside_eval：将聚合树作用于完整测试集，生成树输出特征，再用全局 CNN 权重推理得到测试 loss 与指标（Accuracy 或 MSE）。

四、实验配置详解：从集中式到联邦的完整参数体系

4.1 集中式基线：论文原始超参数

集中式模型（单机 XGBoost）使用论文原始超参数（配置文件：paper_xgboost_centralized.yaml）：

| 超参数 | 值 | | -- | -- | | n_estimators | 500 | | max_depth | 8 | | subsample | 0.8 | | learning_rate | 0.1 | | colsample_bylevel | 1 | | colsample_bynode | 1 | | colsample_bytree | 1 | | alpha | 5 | | gamma | 5 | | num_parallel_tree | 1 | | min_child_weight | 1 |

README 说明：除 abalone 与 cpusmall 外，这些集中式超参数在各数据集上表现良好；abalone/cpusmall 使用各自专属的微调配置（abalone_xgboost_centralized.yaml、cpusmall_xgboost_centralized.yaml）。

4.2 联邦实验：XGBoost + Adam（CNN）联合超参数

联邦模式下，XGBoost 模型与 Adam 优化器各自的超参数如下（README 原始值）：

| 超参数 | 值 | | -- | -- | | n_estimators | 500 / 客户端数 | | xgb max_depth | 8 | | xgb subsample | 0.8 | | xgb learning_rate | 0.1 | | xgb colsample_bylevel | 1 | | xgb colsample_bynode | 1 | | xgb colsample_bytree | 1 | | xgb alpha | 5 | | xgb gamma | 5 | | xgb num_parallel_tree | 1 | | xgb min_child_weight | 1 | | Adam 学习率 | 0.0001 | | Adam Betas | (0.5, 0.999) | | CNN 迭代次数 | 100 |

4.3 微调后的最终配置：24 个客户端配置文件

README 指出，上述原始超参数并非对所有数据集最优，因此针对以下对性能影响最大的超参数组进行了微调：

• n_estimators_client
• xgb max_depth
• Adam 学习率（CNN.lr）
• CNN 迭代次数（num_iterations）

微调后的最终值保存在clients/目录下的<dataset>_<n>_clients.yaml（3 个数据集 × 2/5/10 客户端 = 21 个），论文原始值保存在paper_<n>_clients.yaml（3 个），合计 24 个配置文件。

以 a9a_5_clients.yaml 为例，联邦配置的真实结构为：

n_estimators_client: 100 # 每客户端 XGBoost 树数（也用于 CNN 卷积核/步长） num_rounds: 30 # 服务器与客户端之间的通信轮数 client_num: 5 # 客户端数量 num_iterations: 500 # CNN 训练迭代（batch）数 xgb: max_depth: 8 # XGBoost 树深 CNN: lr: .0005 # Adam 学习率

4.4 全局配置 base.yaml 的关键默认值

base.yaml 是联邦与集中式实验共享的入口配置，默认dataset: cpusmall、clients: cpusmall_5_clients，主要默认项包括：

• centralized: False、use_wandb: False、show_each_client_performance_on_its_local_data: False；
• val_ratio: 0.0（默认不预留客户端验证集）、batch_size: "whole"；
• XGBoost 公共默认：learning_rate=.1、subsample=.8、各colsample*=1、alpha=5、gamma=5、num_parallel_tree=1、min_child_weight=1；
• 策略：fraction_fit=1.0（全部客户端参与训练）、fraction_evaluate=0.0、accept_failures=False；
• 运行环境：server.device="cpu"、client_resources每个客户端 1 CPU、0 GPU；
• run_experiment.num_rounds与fit_config.num_iterations均透传自clients.*配置。

4.5 任务配置：二分类与回归

数据集配置通过defaults引入任务模板。二分类任务模板 Binary_Classification.yaml 定义：

• task_type: "BINARY"，评估指标torchmetrics.Accuracy（binary），损失torch.nn.BCELoss，XGBoost 目标binary:logistic（XGBClassifier）；
• 回归模板 Regression.yaml 对应task_type: "REG"、MSE 指标与XGBRegressor。

数据集级配置（如 a9a.yaml）则声明dataset_name、train_ratio: .75与early_stop_patience_rounds: 10。

五、环境搭建：Poetry + pyenv

该基线使用 Poetry 管理依赖。假设已安装Poetry与pyenv，在 baselines/hfedxgboost 目录（即pyproject.toml所在目录）执行：

# 设定 Python 版本 pyenv local 3.10.6 # 让 Poetry 使用该版本 poetry env use 3.10.6 # 安装全部依赖 poetry install # 激活虚拟环境 poetry shell

激活环境后即可直接运行实验，数据集会在首次运行时自动下载（YearPredictionMSD 约 615MB，README 建议用下载管理器手动下载后放入对应目录）。

六、运行实验：集中式与联邦的完整命令

6.1 集中式基线

# 使用自定义超参数跑集中式模型： # 命令格式： # python -m hfedxgboost.main --config-name Centralized_Baseline \ # dataset=<数据集配置名> xgboost_params_centralized=<集中式超参配置名> # 示例：用微调后的超参数跑 cpusmall 集中式模型 python -m hfedxgboost.main --config-name Centralized_Baseline \ dataset=cpusmall xgboost_params_centralized=cpusmall_xgboost_centralized

6.2 联邦版本

# 通用格式：python -m hfedxgboost.main dataset=<数据集> clients=<客户端配置> # 示例：a9a 数据集、5 个客户端 python -m hfedxgboost.main dataset=a9a clients=a9a_5_clients

6.3 命令行覆盖任意参数

Hydra 支持在终端直接覆盖配置项，公式为folder=配置文件名 folder.参数名=新值：

# 示例：集中式 abalone，max_depth 改为 8，训练集比例改为 80% python -m hfedxgboost.main --config-name Centralized_Baseline \ dataset=abalone xgboost_params_centralized=abalone_xgboost_centralized \ xgboost_params_centralized.max_depth=8 dataset.train_ratio=.80

七、预期结果：复现论文 Table 1/2/3

7.1 Table 1：集中式评估

# 用论文原始配置跑全部数据集的集中式实验（输出对应 Table 1） python -m hfedxgboost.main --config-name centralized_basline_all_datasets_paper_config # 注意：与联邦实验不同，集中式结果只打印在终端，不会写入文件

7.2 Table 2：联邦二分类

# a9a 在 Table 2 的结果 python -m hfedxgboost.main --multirun \ clients=a9a_2_clients,a9a_5_clients,a9a_10_clients dataset=a9a # cod_rna 在 Table 2 的结果 python -m hfedxgboost.main --multirun \ clients=cod_rna_2_clients,cod_rna_5_clients,cod_rna_10_clients dataset=cod_rna # ijcnn1 在 Table 2 的结果 python -m hfedxgboost.main --multirun \ clients=ijcnn1_2_clients,ijcnn1_5_clients,ijcnn1_10_clients dataset=ijcnn1

7.3 Table 3：联邦回归

# 注意：表中的 MSE 结果通常出现在较早的 FL 轮次（而非最后一轮） # space_ga python -m hfedxgboost.main --multirun \ clients=space_ga_2_clients,space_ga_5_clients,space_ga_10_clients dataset=space_ga # abalone python -m hfedxgboost.main --multirun \ clients=abalone_2_clients,abalone_5_clients,abalone_10_clients dataset=abalone # cpusmall python -m hfedxgboost.main --multirun \ clients=cpusmall_2_clients,cpusmall_5_clients,cpusmall_10_clients dataset=cpusmall # YearPredictionMSD python -m hfedxgboost.main --multirun \ clients=YearPredictionMSD_2_clients,YearPredictionMSD_5_clients,YearPredictionMSD_10_clients dataset=YearPredictionMSD

README 明确提醒：Table 2 与 Table 3 使用的是不同于论文的微调后超参数（否则部分实验性能更差），且仍有部分结果与原论文存在差距——复现时应以本仓库配置与结果为准，不宜将数值差异视为复现失败。

八、超参数微调指南：WandB + CSV 双通道

8.1 用 WandB 自动化微调

1. 激活 poetry shell 并登录：poetry shell、wandb login；
2. 编辑 sweep.yaml 控制搜索方法与参数取值空间，然后在baselines/hfedxgboost/hfedxgboost目录下执行：

# 初始化 WandB sweep wandb sweep sweep.yaml # 若命令无错误运行，会返回一行 sweep agent 命令，形如： # wandb agent <你的 wandb 用户名>/flower-baselines_hfedxgboost_hfedxgboost/<sweep 名称>

sweep.yaml 的默认配置演示了随机搜索（method: random）的用法：固定dataset: cpusmall与clients: cpusmall_5_clients，对clients.n_estimators_client（取值 10/25/50/100/150/200/250）、clients.num_iterations（100/500）、clients.xgb.max_depth（4~8）、clients.CNN.lr（0.00001～0.001 连续区间）进行组合搜索。

8.2 回填最终配置

微调定稿后，将最终值写入<dataset>_<客户端数>_clients.yaml文件，方便后续使用者直接复现。

8.3 CSV 结果记录

utils.py 中内置两个结果记录类：

• ResultsWriter（联邦实验）：记录dataset_name、client_num、n_estimators_client、num_rounds、xgb_max_depth、cnn_lr、best_res、best_res_round_num、num_iterations到 results.csv；
• CentralizedResultsWriter（集中式实验）：记录完整 XGBoost 超参与result_train/result_test到 results_centralized.csv。

README 特别提醒：这两个类只记录「被认为重要」的超参数，若你关注其他参数，请自行扩展 writer 类的字段，尤其是脱离 WandB 做实验时。

九、扩展指南：如何新增一个数据集

当前代码尚未覆盖论文全部数据集。新增数据集需完成以下步骤：

9.1 添加下载逻辑

在 dataset_preparation.py 的download_data函数中增加对应分支（若已手动下载，直接返回文件路径即可），示意如下：

if dataset_name == "<你的数据集名>": DATASET_PATH = os.path.join(ALL_DATASETS_PATH, "<你的数据集名>") if not os.path.exists(DATASET_PATH): os.makedirs(DATASET_PATH) urllib.request.urlretrieve( "<数据集第一个文件的 URL>", f"{os.path.join(DATASET_PATH, '<第一个文件名>')}", ) urllib.request.urlretrieve( "<数据集第二个文件的 URL>", f"{os.path.join(DATASET_PATH, '<第二个文件名>')}", ) # 若两个文件分别为训练/测试文件，先返回训练文件路径再返回测试文件路径 return [ os.path.join(DATASET_PATH, "<第一个文件名>"), os.path.join(DATASET_PATH, "<第二个文件名>"), ]

该函数由 dataset.py 的load_single_dataset调用；若数据集是单个文件，datafiles_fusion会原样加载，多文件则自动拼接。

两个必须注意的坑：

• 若数据集文件以.bz2结尾，须在if条件内、return之前加入解压代码：

for filepath in os.listdir(DATASET_PATH): abs_filepath = os.path.join(DATASET_PATH, filepath) with bz2.BZ2File(abs_filepath) as fr, open(abs_filepath[:-4], "wb") as fw: shutil.copyfileobj(fr, fw)

• datafiles_fusion使用sklearn.datasets.load_svmlight_file解析数据，如果你的数据集是 CSV 等其他格式，必须改造datafiles_fusion以适配新格式。

9.2 添加配置（集中式）

• 在 utils.py 的dataset_tasks字典中，以「数据集名 → 任务类型（BINARY或REG）」的形式注册新数据集（名字须与download_data中一致）；
• 在dataset配置目录新建<your dataset>.yaml，内容模板：

defaults: - task: <任务类型配置名，Regression 或 Binary_Classification> dataset_name: "<你的数据集名，须与 download_data 中一致>" train_ratio: <训练数据占全量的比例> early_stop_patience_rounds: <早停器等待的轮数>

• 在xgboost_params_centralized目录新建同名超参配置文件，填写你为 XGBoost 选择的全部超参值；
• 若想直接用论文默认超参跑集中式，可跳过本步——论文原始值全部记录在paper_<n>_clients.yaml中。

9.3 添加配置（联邦）

在clients目录创建客户端配置，模板如下：

n_estimators_client: <XGBoost 与 CNN 使用的树数> num_rounds: <服务器与客户端的通信轮数> client_num: <客户端数量> num_iterations: <CNN 模型的迭代次数> xgb: max_depth: <整数> CNN: lr: <浮点数>

至此，新数据集即可同时参与集中式与联邦两类实验。

十、源码结构速查

结语

baselines/hfedxgboost完整展示了 FedXGBllr 算法在 Flower 框架下的落地路径：以「客户端本地 XGBoost + 服务端 CNN 学习聚合权重」替代梯度共享，既保留了 XGBoost 在表格数据上的强表达力，又显著压缩了通信成本。通过 Hydra 配置体系，你可以在 24 个现成客户端配置、7 个数据集与集中式/联邦两套流程之间自由切换，也可以借助 WandB 与 CSV 记录机制高效开展属于自己的超参数微调与数据集扩展——这正是将该论文从纸面推向可复现实验的关键价值所在。

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