企业官网建设流程全解析

• 人工智能
• 机器学习
• 联邦学习
• 深度学习
• 分布式训练
• 隐私计算
• 密码学

导读

本文围绕 examples/pipeline/hetero_nn 目录下的官方 Pipeline 示例，系统讲解在 FATE 2.0 中如何通过 FATE-Pipeline 搭建纵向联邦神经网络（Hetero NN）任务，并重点剖析两种隐私保护策略——FedPass（自适应混淆）与SSHE（同态加密结合安全共享）——在聚合层中的配置方式与底层实现。读完本文，你将掌握从数据上传、Pipeline 任务编排、模型与训练参数配置到结果评估的完整实操链路，并能根据业务场景在 FedPass 与 SSHE 之间做出合理选型。

一、Hetero NN Pipeline 示例总览

1.1 示例任务构成

examples/pipeline/hetero_nn目录下提供了两类纵向联邦神经网络任务的 Pipeline 脚本，其任务类型由 README.md 明确列出：

两个脚本都是**二分类（binary）**任务，使用相同的乳腺肿瘤数据集（guest 侧breast_hetero_guest.csv、host 侧breast_hetero_host.csv），区别在于聚合层的隐私保护方案不同。用户可以直接以一行命令运行任意一个 Pipeline 作业：

python ${pipeline_script}

例如：

python test_nn_binary_fedpass.py python test_nn_binary_sshe.py

脚本默认从../config.yaml读取集群参与方配置，也可以通过--config参数指定其他配置文件，通过--namespace指定数据在 FATE 中的命名空间。

1.2 配套的测试套件与数据配置

该目录下的 hetero_nn_testsuite.yaml 是供 FATE-Test 测试框架使用的套件配置，其中定义了：

• 数据上传配置（data段）：将 breast_hetero_guest.csv 以guest_0角色、breast_hetero_host.csv 以host_0角色上传到 FATE；
• 任务映射（tasks段）：hetero-nn-binary-sshe与hetero-nn-binary-fedpass分别映射到两个测试脚本。

数据段的元数据配置直接决定了上传到 FATE 的表的格式，其中几个关键项说明如下：

注意：hetero_nn_testsuite.yaml中的namespace为experiment，而测试脚本中 Reader 组件读取时使用namespace=f"experiment{namespace}"，两者通过脚本的--namespace参数保持一致（默认空字符串时即为experiment）。

1.3 参与方配置

两个脚本默认读取 examples/pipeline/config.yaml，其参与方声明如下：

parties: guest: - '9999' host: - '10000' - '9999' arbiter: - '10000' data_base_dir: "" # path to project base where data is located

在示例脚本中，仅使用第一个 guest（9999）和第一个 host（10000）；FedPass 脚本额外配置了 arbiter（10000）。data_base_dir用于指定数据所在的项目根目录，为空时表示数据路径直接使用相对仓库根目录的路径。

二、FedPass 任务：test_nn_binary_fedpass.py 深度解析

2.1 FedPass 策略原理

FedPass 是一种不依赖同态加密与安全共享的隐私保护策略，其核心思想是把"私人护照（private passports）"嵌入神经网络，实现自适应混淆（adaptive obfuscation）。具体做法是在网络中插入 passport layer，该层利用模型参数与私人护照动态调整 scale 因子与 bias 项，再经过自编码器与平均化处理，从而混淆前向的隐藏特征与反向传播的梯度。其特性在 doc/2.0/fate/components/hetero_nn.md 中被归纳为三点：

• 隐私保护：攻击者在没有护照的情况下极难从输出反推输入；
• 保持模型性能：混淆参数通过反向传播随模型一起优化，相比固定混淆方式性能更优；
• 速度接近明文训练：无需同态加密或安全共享，训练速度几乎与明文训练相当。

在 FATE 2.0 中，FedPass 策略可同时作用于guest 的 top model与host 的 bottom model（host 通过agglayer_arg配置，guest 通过top_arg配置）。

2.2 脚本结构与任务编排

test_nn_binary_fedpass.py的完整 Pipeline 由 5 个任务组成，编排顺序如下：

reader_0（Reader 读取双方数据） → psi_0（PSI 样本对齐） → hetero_nn_0（训练） → hetero_nn_1（用训练好的模型预测） → evaluation_0（AUC 评估）

pipeline.add_tasks([reader_0, psi_0, hetero_nn_0, hetero_nn_1, evaluation_0]) pipeline.compile() pipeline.fit()

其中：

• reader_0：Reader组件分别读取 guest 的breast_hetero_guest表与 host 的breast_hetero_host表（命名空间experiment{namespace}）；
• psi_0：PSI组件对双方数据做隐私求交，产出共同样本集合output_data；
• hetero_nn_0：以train_data为输入执行训练，输出output_model；
• hetero_nn_1：以test_data为输入、input_model=hetero_nn_0.outputs['output_model']加载训练好的模型执行预测，输出test_output_data；
• evaluation_0：Evaluation组件在 guest 侧以auc为指标，同时评估训练输出与测试输出的效果：

evaluation_0 = Evaluation( 'eval_0', runtime_parties=dict(guest=guest), metrics=['auc'], input_datas=[hetero_nn_1.outputs['test_output_data'], hetero_nn_0.outputs['train_output_data']] )

作业结束后通过pipeline.get_task_info("eval_0").get_output_metric()[0]["data"]获取并打印评估结果。

2.3 训练超参与优化器配置

两个脚本都通过TrainingArguments（源自 HuggingFace transformers 的训练参数体系）配置训练过程：

training_args = TrainingArguments( num_train_epochs=1, per_device_train_batch_size=16, logging_strategy='epoch' )

• num_train_epochs：训练轮数（FedPass 示例为 1，SSHE 示例也为 1）；
• per_device_train_batch_size：单设备批大小（FedPass 为 16，SSHE 为 256）；
• logging_strategy：日志输出策略，'epoch'表示每轮输出一次（SSHE 示例还额外设置了log_level='debug'）。

从 hetero_default_runner.py 的实现看，training_args最终会传入transformers.TrainingArguments，且output_dir由 runner 自动接管为组件输出目录，同时支持 checkpoint 断点续训（resume_from_checkpoint）。

2.4 Guest 与 Host 的模型配置

FedPass 示例通过get_config_of_default_runner分别为 guest 与 host 构造 runner 配置。

Guest 侧（持有标签与 10 个特征）：

guest_conf = get_config_of_default_runner( bottom_model=nn.Linear(10, 10), top_model=Sequential( nn.Linear(10, 1), nn.Sigmoid() ), training_args=training_args, optimizer=optim.Adam(lr=0.01), loss=nn.BCELoss() )

guest 同时拥有 bottom model（Linear(10, 10)，负责处理自身 10 维特征）与 top model（Linear(10, 1) + Sigmoid，负责输出二分类概率），损失函数采用二分类交叉熵BCELoss。

Host 侧（无标签，持有 20 个特征，聚合层启用 FedPass）：

host_conf = get_config_of_default_runner( bottom_model=nn.Linear(20, 20), optimizer=optim.Adam(lr=0.01), training_args=training_args, agglayer_arg=FedPassArgument( layer_type='linear', in_channels_or_features=20, hidden_features=20, out_channels_or_features=10, passport_mode='single', passport_distribute='gaussian' ) )

host 只有 bottom model（Linear(20, 20)），其输出经过 FedPass 聚合层后再与 guest 侧特征融合。FedPassArgument的参数说明（默认值见 hetero_nn_model.py 中的FedPassArgumentdataclass）：

两个侧别配置完成后，通过HeteroNN组件绑定数据并下发各自的 runner 配置：

hetero_nn_0 = HeteroNN('hetero_nn_0', train_data=psi_0.outputs['output_data']) hetero_nn_0.guest.task_parameters(runner_conf=guest_conf) hetero_nn_0.hosts[0].task_parameters(runner_conf=host_conf)

get_config_of_default_runner生成的就是 runner 的runner_conf字典，其中模型（bottom/top）、聚合层、优化器、损失函数、训练参数均以可序列化配置形式表达，从而可在 guest/host 间分别下发。

三、SSHE 任务：test_nn_binary_sshe.py 深度解析

3.1 SSHE 策略原理

SSHE（Secure Sharing + Homomorphic Encryption）策略同时使用同态加密与安全共享来保护模型与数据的隐私：guest 与 host 聚合层的权重被拆分为两部分，分别与协作方共享，使得任何一方都无法单独获知对方聚合层权重的完整信息。其设计思想来源于论文When Homomorphic Encryption Marries Secret Sharing: Secure Large-Scale Sparse Logistic Regression and Applications in Risk Control。

从源码实现看（agg_layer.py），SSHE 聚合层在set_context时通过SSHENeuralNetworkAggregatorLayer初始化聚合模型，权重wa（host 侧）与wb（guest 侧）以**共享形式（share）**在双方之间分布，并使用独立的SSHENeuralNetworkOptimizerSGD优化器（学习率即layer_lr）更新聚合层参数。训练时，guest 侧调用self._agg_layer.step()推进聚合层自己的优化器，host 侧同理，聚合层参数不会以明文暴露给任何一方。

3.2 与 FedPass 示例的差异

test_nn_binary_sshe.py的 Pipeline 编排与 FedPass 版本基本一致（Reader → PSI → HeteroNN 训练/预测 → Evaluation），核心差异集中在聚合层的配置上：

Guest 侧（bottom modelLinear(10, 10)，top modelLinear(10, 1) + Sigmoid，聚合层使用 SSHE）：

guest_conf = get_config_of_default_runner( bottom_model=nn.Linear(10, 10), top_model=Sequential(nn.Linear(10, 1), nn.Sigmoid()), training_args=training_args, optimizer=optim.Adam(lr=0.01), loss=nn.BCELoss(), agglayer_arg=SSHEArgument( guest_in_features=10, host_in_features=10, out_features=10 ) )

Host 侧（bottom modelLinear(20, 10)，聚合层使用 SSHE）：

host_conf = get_config_of_default_runner( bottom_model=nn.Linear(20, 10), optimizer=optim.Adam(lr=0.01), training_args=training_args, agglayer_arg=SSHEArgument( guest_in_features=10, host_in_features=10, out_features=10 ) )

SSHEArgument的参数说明（默认值同样来自 hetero_nn_model.py）：

需要特别指出的是，SSHE 示例的 guest 与 host 都配置了 bottom model 与聚合层，即双方底层特征都先经过各自 bottom model 提取，再由 SSHE 聚合层融合；而 FedPass 示例中只有 host 的聚合层采用 FedPass，guest 的 top model 直接基于自身特征输出。两种策略对模型结构的约束不同，配置时需注意匹配。

3.3 验证数据的使用差异

SSHE 示例在训练时额外提供了验证集：

hetero_nn_0 = HeteroNN( 'hetero_nn_0', train_data=psi_0.outputs['output_data'], validate_data=psi_0.outputs['output_data'] )

而 FedPass 示例的hetero_nn_0只传入train_data。验证集的语义对应HeteroNN组件的validate_data参数（见下文组件签名），可在训练过程中进行验证评估。

四、Hetero NN 组件与底层调用链

4.1 HeteroNN 组件的接口定义

Pipeline 中的HeteroNN组件最终对应 python/fate/components/components/hetero_nn.py 中由@cpn.component(roles=[GUEST, HOST])注册的组件，它暴露两类算子：

• train：输入train_data（guest/host）、可选validate_data，参数包括runner_module（默认hetero_default_runner）、runner_class（默认DefaultRunner）、runner_conf（runner 参数字典）、source（自定义 runner 脚本目录路径），输出train_output_data与output_model，并支持warm_start_model热启动；
• predict：输入test_data与input_model，输出test_output_data。

@hetero_nn.train() def train( ctx: Context, role: Role, train_data: cpn.dataframe_input(roles=[GUEST, HOST]) | cpn.data_directory_input(), validate_data: cpn.dataframe_input(roles=[GUEST, HOST], optional=True) | cpn.data_directory_input(optional=True), runner_module: cpn.parameter(type=str, default="hetero_default_runner", ...), runner_class: cpn.parameter(type=str, default="DefaultRunner", ...), runner_conf: cpn.parameter(type=dict, default={}, desc="the parameter dict of the NN runner class"), source: cpn.parameter(type=str, default=None, desc="path to your runner script folder"), ... ): train_procedure(...)

这里runner_conf正是get_config_of_default_runner生成的配置字典；source参数则允许用户传入自定义 runner 脚本目录，实现完全自定义的训练逻辑。

4.2 组件执行流程

component_utils.py 中的train_procedure与predict_procedure是组件的实际执行引擎，其关键步骤为：

1. 加载 runner：若source为None，从默认位置fate.components.components.nn.runner.{runner_module}加载runner_class；否则从source目录加载自定义 runner，并要求加载的类必须是NNRunner的子类；
2. 准备上下文：通过ctx.sub_ctx创建子上下文并注入 runner；
3. 解析数据：将DataframeReader/DataDirectoryReader统一解析为训练/验证数据；
4. 执行训练：runner.train(...)，并在训练后自动对训练集（及验证集）执行预测，输出带数据集类型标记（TRAIN_SET/VALIDATE_SET/TEST_SET）的结果 DataFrame；
5. 保存模型元数据：将runner_module、runner_class、runner_conf、source序列化写入模型输出目录。预测阶段则从模型元数据中恢复 runner 配置，加载保存的模型状态后对新数据预测。

这解释了为何hetero_nn_1能以input_model=hetero_nn_0.outputs['output_model']无缝完成加载与预测——模型目录中不仅保存了权重，还保存了可完整重建训练环境的 runner 配置。

4.3 DefaultRunner 的分侧装配逻辑

hetero_default_runner.py 中的DefaultRunner是上述两个示例默认使用的 runner，它在train()中根据当前角色走不同的装配分支：

• guest 侧（guest_setup）：加载 bottom/top 模型，解析agglayer_arg_conf（经parse_agglayer_conf还原为StdAggLayerArgument/FedPassArgument/SSHEArgument），构造HeteroNNModelGuest，再创建HeteroNNTrainerGuest；训练前通过_check_label强制校验 guest 数据集必须包含标签；
• host 侧（host_setup）：只加载 bottom 模型，且有两个强约束：
  • 明文聚合层（StdAggLayerArgument）在 host 侧不被允许（Plaintext agglayer is not supported in Hetero-NN Pipeline Host party）；
  • 必须显式配置隐私保护聚合层，否则直接抛错（A aggregate layer for privacy preserving is needed in the Hetero-NN pipeline Host party, please set the agglayer config: use fedpass alone in host, or configure sshe layers for guest&host）。

这两个校验意味着：在 Pipeline 模式下，纵向联邦神经网络的 host 侧强制要求启用 FedPass 或 SSHE 中的一种隐私保护策略，这是保证纵向联邦安全性的底线约束。

4.4 模型与聚合层的运行时行为

HeteroNNModelGuest与HeteroNNModelHost（hetero_nn_model.py）是封装 top/bottom 模型与聚合层的容器：

• 前向：guest 侧若存在 bottom model，先计算自身 bottom 输出b_out，经聚合层融合 host 特征后送入 top model；host 侧仅计算 bottom 输出并送入聚合层。聚合层支持sum与concat两种合并方式（merge_type），见 agg_layer.py 的AggLayerGuest._forward；
• 反向：guest 侧的backward(loss)将误差经聚合层回传至各 host；host 侧的backward()接收聚合层误差，以backward_loss（sum(z * error)）构造代理损失完成 bottom model 的梯度回传；
• 隐私策略分发：FedPassArgument在序列化时标记agg_type="fed_pass"，SSHEArgument标记agg_type="hess"，StdAggLayerArgument标记agg_type="std"，parse_agglayer_conf据此还原对应的聚合层实现；
• GPU 约束：SSHE 聚合层在非 CPU 设备上会直接抛出SSHEAggLayerGuest is not supported on GPU（guest 与 host 侧均有此检查），因此SSHE 策略只能运行于 CPU；FedPass 策略则支持单 GPU 训练（见 doc/2.0/fate/components/hetero_nn.md 中 "Support single GPU training" 的说明，以及 hetero_nn_tutorial.md 中 "SSHE layer is incompatible with GPU training" 的明确提示）。

4.5 Trainer 层：基于 HuggingFace Trainer 的联邦训练

HeteroNNTrainerGuest/HeteroNNTrainerHost（hetero_nn.py）继承自HeteroTrainerBase（trainer_base.py），而HeteroTrainerBase本身构建于 HuggingFaceTrainer之上，因此TrainingArguments的字段语义与 transformers 完全一致。Trainer 的关键覆写包括：

• compute_loss：兼容(features, labels)与纯(labels,)两种输入格式（后者对应 guest 只有标签、特征全部来自 host 的场景）；
• training_step：计算 loss 后调用model.backward(loss)，将梯度经联邦通道回传，实现独立前向与独立反向（这是 FATE 2.0 Hetero NN 框架的标志性能力）；
• 初始化时若检测到模型需要 MPC（model.need_mpc_init()，即聚合层为SSHEAggLayer*），会自动执行ctx.mpc.init()完成 MPC 协议环境初始化。

五、运行结果与验证

作业完成后，评估组件在 guest 侧计算 AUC，示例脚本将其打印到控制台：

result_summary = pipeline.get_task_info("eval_0").get_output_metric()[0]["data"] print(f"result_summary: {result_summary}")

Evaluation组件的metrics=['auc']指定评估指标，input_datas同时传入训练集与测试集的预测结果，便于对比模型在两类数据上的判别能力。此外，HeteroNN的训练输出（train_output_data）与测试输出（test_output_data）本身都是带有数据集类型标记的 FATE DataFrame，可被下游组件继续消费。

六、FAQ 与实战注意事项

1. Host 侧必须配置隐私保护聚合层：Pipeline 模式下DefaultRunner.host_setup会强制校验，未配置或误用明文聚合层（StdAggLayerArgument）都会抛错。推荐在 host 单独使用FedPassArgument，或在 guest 与 host 两侧对称配置SSHEArgument。
2. SSHE 与 GPU 不兼容：若训练环境包含 GPU，SSHE 聚合层会在前向时抛出异常；FedPass 支持单 GPU 训练。选择策略前应先确认运行环境。
3. Guest 必须有标签：runner 在训练前会检查 guest 数据集has_label，纵向联邦中标签只允许出现在 guest 侧。
4. 数据命名空间一致性：测试套件上传数据使用namespace: experiment，脚本读取时使用experiment{namespace}，运行时通过--namespace对齐，避免"表不存在"的错误。
5. SSHE 需要双方维度对齐：SSHEArgument中的guest_in_features/host_in_features/out_features必须在 guest 与 host 两侧配置一致，否则聚合层无法正确融合双方特征。
6. 自定义模型/数据集：HeteroNN组件的source参数支持指定自定义 runner 脚本目录，runner 的dataset_conf、optimizer_conf、loss_conf等均支持按配置装载，可参照 hetero_nn_tutorial.md 中本地实验（不经 FATE-Pipeline、使用fate.arch.launchers.multiprocess_launcher.launch直接运行）的方式快速验证模型与算法改动。

七、进一步阅读

• 组件文档：doc/2.0/fate/components/hetero_nn.md（SSHE 与 FedPass 策略的原理、特性与架构图）
• 本地实验教程：doc/2.0/fate/ml/hetero_nn_tutorial.md（不依赖 FATE-Flow 的本地 Hetero NN 开发与调试方法，含表格数据 SSHE 示例与图像数据 FedPass 示例的完整代码）
• 测试用例：python/fate/ml/nn/test（test_hetero_nn_sshe.py、test_fedpass_tabular.py、test_fedpass_lenet.py、test_fedpass_alexnet.py等覆盖了 SSHE 与 FedPass 的算法级验证）
• 组件实现：python/fate/components/components/hetero_nn.py、hetero_default_runner.py
• 模型与聚合层实现：hetero_nn_model.py、fedpass/agg_layer.py、sshe/agg_layer.py

• 人工智能
• 机器学习
• 联邦学习
• 深度学习
• 分布式训练
• 隐私计算
• 密码学