TensorFlow 官方双塔 Uplift 模型库从架构到训练、评估与导出的完整实践指南【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models本文为技术导读Uplift增益建模用于量化某个干预对单个个体的增量影响是推荐与营销场景中估计个体处理效应ITE的核心方法。本篇基于 TensorFlow 官方仓库official/recommendation/uplift模块下的 README完整讲解该 Uplift Modeling Library 的双塔Two Tower网络架构、构建与训练代码、损失函数与评估指标的设计并结合仓库源码剖析前向计算、true logits 选择与 uplift 预测的底层实现。读完本文你能够独立用 Keras 搭建、编译、训练一个双塔 uplift 模型并理解每个组件在源码中的调用关系。Uplift Modeling Library 的定位与模块划分Uplift modeling is a predictive modeling technique that models the incremental impact of a treatment on an individual——Uplift 建模是一类预测建模技术其目标不是预测用户会不会转化而是预测施加某个干预treatment如发券、推送、降价之后该个体的行为相比不施加干预control会增量改变多少。官方 README 对该库的定位如下提供一套完整的工具链用于构建build、训练train、评估evaluate和导出exportuplift 模型全部基于 TensorFlow 2 实现所有组件以**模块化modular**方式构建能够与 TFX、TensorFlow TransformTFT、TensorFlow Model AnalysisTFMA等其他 TF 生态系统良好集成使用Keras作为建模框架即模型层、网络、损失、指标全部是标准 Keras 对象可以直接配合model.compile()、model.fit()等 API 使用。从源码结构看库被划分为四个关键目录位于 official/recommendation/uplift目录内容关键文件layers/与 uplift 建模相关的 Keras 层layers/uplift_networks/two_tower_uplift_network.py、layers/encoders/concat_features.py、layers/heads/two_tower_logits_head.py、layers/uplift_networks/two_tower_output_head.pymodels/包含训练、评估、推理全部逻辑的 Keras 模型models/two_tower_uplift_model.pymetrics/uplift 建模使用的 Keras 指标metrics/treatment_fraction.py、metrics/uplift_mean.py、metrics/label_mean.py、metrics/label_variance.pylosses/uplift 建模使用的 Keras 损失losses/true_logits_loss.pyREADME 同时指向一个交互式教程 uplift_modeling_intro.ipynb演示如何在大规模数据上使用本库构建、训练和评估 uplift 模型。双塔 Uplift 网络架构初始版本聚焦于遵循**双塔 uplift 网络架构Two Tower Uplift Network**的模型族。该架构借鉴了因果推断/处理效应估计领域的多篇相关工作参考文献见文末。架构总览如下图源自 README 中引用的 two_tower_uplift_network.svgREADME 定义了七个核心组成部分下面逐一说明Inputs输入从特征名到特征张量的映射dict[str, Tensor]。张量支持多种类型例如tf.Tensor、tf.SparseTensor和tf.RaggedTensor。这一约束在源码中由类型别名types.DictOfTensors见 types.py 中的TensorType tf.Tensor | tf.SparseTensor | tf.RaggedTensor来体现。Backbone主干网络可训练网络将输入编码为控制臂control与处理臂treatment之间共享的 embedding。Control Treatment Feature Encoders特征编码器可训练网络分别将 control 侧 / treatment 侧的专属特征编码为 embedding。Control Treatment Feature Combiners特征组合器将 backbone 的共享 embedding 与 control/treatment 专属 embedding组合起来的方法。Control Tower控制塔可训练网络可含零个或多个隐藏层仅从 control 样本中学习。Treatment Tower处理塔可训练网络可含零个或多个隐藏层仅从 treatment 样本中学习。Logits Headlogits 头计算 control 与 treatment 两组 logits。训练时control 样本的梯度只从 control logits 流回treatment 样本的梯度只从 treatment logits 流回——这是双塔架构保证每座塔只学习自己那一侧数据的关键机制。源码中的前向流程TwoTowerUpliftNetwork.call上述架构图在源码 two_tower_uplift_network.py 的call()方法中有逐行对应的实现其前向计算顺序为对应源码 L145–L177shared_embedding self._backbone(inputs)backbone 接收整个特征字典产出共享 embedding若提供了control_feature_encoder则先对专属特征编码再用control_input_combiner组合[shared_embedding, control_feature_encoding]否则直接用共享 embedding 作为控制塔输入treatment 侧同理control_embedding self._control_tower(...)、treatment_embedding self._treatment_tower(...)两座塔各自产出 embeddingcontrol_logits, treatment_logits self._logits_head((control_embedding, treatment_embedding))logits 头一次性接收两个塔的输出返回两组 logits打包为types.TwoTowerNetworkOutputs含shared_embedding、control_logits、treatment_logits返回。源码还体现了一条重要的构造约束_validate_encoder_combiner_layers()要求编码器与组合器必须成对出现——只提供control_feature_encoder而不提供control_input_combiner或反过来会抛出ValueError错误信息中建议Consider using tf_keras.layers.Concatenate() as a combiner layer。treatment 侧同理。也就是说编码器/组合器是可选的但一旦启用必须两者兼备。另外两个值得注意的实现细节序列化支持TwoTowerUpliftNetwork通过tf_keras.utils.register_keras_serializable(packageUplift)注册并在get_config()/from_config()中序列化全部 8 个子层因此整个网络可以随模型一起被保存、加载和导出——这是 README 中integrate well with TFX/TFMA 等 TF 生态系统承诺的具体体现。Logits 头的层间约束layeringtwo_tower_logits_head.py 中的TwoTowerLogitsHead除control_head、treatment_head外还支持layering_config提供三种塔间耦合方式对应源码中的LayeringMethod枚举NONE默认两塔完全独立LOGIT_SUMtreatment_logits tf.stop_gradient(control_logits)用停止梯度的 control logits 校正 treatment logitsLINEAR_LAYERINGtreatment_embedding stop_gradient(control_embedding) * W其中W是一个可学习的 CxT 权重矩阵C为 control embedding 维度T为 treatment embedding 维度可用LinearLayeringConfig配置其kernel_initializer默认glorot_uniform与kernel_regularizer。同时该层在call()中强制校验 control 与 treatment logits形状必须一致否则抛出ValueError——这一点与 types.py 中TwoTowerNetworkOutputs的文档约定control/treatment logits 的 shape 和 dtype 必须相同相互呼应。完整实战示例构建并训练双塔 Uplift 模型README 给出了可直接运行的完整用法示例这里原样保留并补充逐段注释# 1. 创建双塔 uplift 网络。 uplift_network two_tower_uplift_network.TwoTowerUpliftNetwork( # Backbone把共享特征编码为 control/treatment 共用的 embedding。 backboneencoders.concat_features.ConcatFeatures( feature_names[shared_feature_1, shared_feature_2] ), # Treatment 侧专属特征编码器control 侧可省略两塔将直接消费共享 embedding。 treatment_feature_encoderencoders.concat_features.ConcatFeatures( feature_names[treatment_feature_1, treatment_feature_2] ), # 编码器必须搭配组合器这里用简单拼接。 treatment_input_combinertf.keras.layers.Concatenate(), # Treatment 塔任意可训练网络0 个或多个隐藏层。 treatment_towertf.keras.Sequential([ tf.keras.layers.Dense(64, activationrelu), tf.keras.layers.Dropout(0.1), ]), # Control 塔可以有不同的深度与宽度。 control_towertf.keras.Sequential([ tf.keras.layers.Dense(128, activationrelu), tf.keras.layers.Dropout(0.1), tf.keras.layers.Dense(32, activationrelu) ]), # Logits 头分别用两个 Dense(1) 产出 control/treatment logits。 logits_headtwo_tower_logits_head.TwoTowerLogitsHead( control_headtf.keras.layers.Dense(1), treatment_headtf.keras.layers.Dense(1), ), ) model two_tower_uplift_model.TwoTowerUpliftModel( # 关键指明输入字典中处理指示特征的名字 # 该特征必须可转为布尔张量FalsecontrolTruetreatment。 treatment_indicator_feature_nameis_treatment, uplift_networkuplift_network, ) # 2. 编译并训练模型。 model.compile( optimizertf.keras.optimizers.Adagrad(learning_rate0.05), losstrue_logits_loss.TrueLogitsLoss(tf.keras.losses.mean_squared_error), metrics[ treatment_fraction.TreatmentFraction(), uplift_mean.UpliftMean(), label_mean.LabelMean(), label_variance.LabelVariance(), ] ) model.fit(dataset, epochs10)各参数要点结合源码文档字符串核对TwoTowerUpliftModel的treatment_indicator_feature_name指定输入字典中代表处理指示的特征名。该张量必须在训练和评估时存在缺失会触发train_step/test_step抛出的ValueError见 two_tower_uplift_model.py 的_assert_treatment_indicator_in_data因为损失计算依赖由它选出的 true logits推理predict时则不需要。inverse_link_fn可选把 logits 换算为预测值的函数缺省为恒等映射。例如分类任务可传 sigmoid。TrueLogitsLoss(loss_fn)把任意标准 Keras 损失如mean_squared_error、categorical_crossentropy套在 true logits 上额外 kwargs如from_logitsTrue会透传给内部loss_fn。训练输出与 true logits 的生成机制真正决定每个样本用哪座塔的输出的逻辑在 two_tower_output_head.pyTwoTowerOutputHead由TwoTowerUpliftModel内部持有并作为其call()的唯一入口uplift 预测uplift treatment_predictions - control_predictions。注意 uplift 是预测值之差经过inverse_link_fn换算后的量而非 logits 之差。true logits 选择当输入中存在处理指示特征时源码先将其tf.cast为布尔再用tf.where(is_treatment, treatment_logits, control_logits)逐样本选出真实 logits同时得到true_predictions输出类型从TwoTowerPredictionOutputs升级为TwoTowerTrainingOutputs多含true_logits、true_predictions、is_treatment三个字段见 types.py。梯度流向由于损失只作用于true_logitscontrol 样本的梯度天然只经过 control logits 分支回传treatment 样本只经过 treatment 分支——README 中Logits Head一条描述的梯度行为正是由此实现。一个防御性细节源码在tf.where之前调用utils.expand_to_match_rank(is_treatment, ...)将指示张量扩维到与 logits 相同的秩。源码注释解释了动机若is_treatment形状为(3,)而 logits 为(3, 1)tf.where的广播会得到形状(3, 3)的错误结果对齐秩后结果才是(3, 1)。推理输出TwoTowerUpliftModel.predict_step()会把输出展开为普通字典键为keys.TwoTowerOutputKeys中的control_predictions、treatment_predictions、uplift方便下游服务直接按名取用。Backbone 输入层ConcatFeatures编码器README 示例中 backbone 与 treatment encoder 均使用ConcatFeaturesconcat_features.py其行为值得明确输入是完整特征字典只挑取feature_names中列出的特征沿最后一个维度拼接tf.concat(features, axis-1)SparseTensor通过tf.sparse.to_dense、RaggedTensor通过to_tensor()统一稠密化后拼接build()阶段校验缺特征抛ValueError所有特征除最后一维外形状必须兼容否则抛ValueError。这意味着不同特征名集合的多个ConcatFeatures实例可以并行工作于同一个输入字典——backbone 吃共享特征encoder 吃专属特征天然契合双塔的输入组织方式。损失与指标面向 uplift 场景的评估体系TrueLogitsLoss可组合的损失包装器true_logits_loss.py 中的TrueLogitsLoss继承自 Keras 的LossFunctionWrapper其call()实现极简但关键def call(self, y_true, y_pred): # y_pred 为 TwoTowerTrainingOutputs return super().call(y_true, y_pred.true_logits)即把任意损失函数作用于true_logits按样本选出的 control 或 treatment logits之上。默认reduction为Reduction.AUTO可传SUM等其余 kwargs如from_logits透传给底层loss_fn。源码文档字符串中给出了两类用法独立调用构造TwoTowerTrainingOutputs后直接loss(y_true, y_pred)以及model.compile(loss...)用法与上文示例一致。四个内置指标整体 分组切片README 示例编译时注册的四个指标在 metrics/ 目录下都有对应实现且均要求y_pred是TwoTowerTrainingOutputs否则抛TypeError并支持sample_weight加权TreatmentFractiontreatment_fraction.py计算处理组样本占比本质是对is_treatment求Mean。训练时用于监控数据集是否近似随机分组例如 A/B 实验期望接近 0.5是诊断选择偏差的第一道信号。UpliftMeanuplift_mean.py输出整体以及按处理组切分的 uplift 均值三个标量结果名为uplift/mean、uplift/mean/control、uplift/mean/treatment。内部基于TreatmentSlicedMetric见 metrics/treatment_sliced_metric.py实现切片sample_weight也会按is_treatment切分后参与加权。LabelMeanlabel_mean.py输出label/mean、label/mean/control、label/mean/treatment即真实标签在整体与两组内的均值。对比两组标签均值可以直接观察观测到的处理效应与uplift/mean对照即可检查模型学到的 uplift 是否与数据中的组间差异方向一致。LabelVariancelabel_variance.py输出label/variance及两组的方差基于自定义Variance指标metrics/variance.py实现用于监控标签分布随训练的稳定性。从源码结构看这类整体 control/treatment 切片的组合模式是该库指标设计的统一范式TreatmentSlicedMetric作为通用切片容器因此扩展新的切片指标时只需复用它。集成到 TF 生态序列化与导出该库面向生产工作流设计的第二个证据是全链路可序列化TwoTowerUpliftNetwork、TwoTowerOutputHead、TwoTowerLogitsHead、TwoTowerUpliftModel、TrueLogitsLoss、ConcatFeatures以及上述指标均注册在 Keras 的Uplift序列化包中register_keras_serializable各自实现了get_config()/from_config()。TwoTowerUpliftModel.get_config()额外持久化treatment_indicator_feature_name、序列化后的uplift_network与inverse_link_fn因此整个模型可以用标准 Keras 的save_model/load_model流程存取并重建——这正是 README 声称能与 TFX、TFT、TFMA 良好集成的底层原因。使用时的两个适用前提需要牢记训练与评估数据必须携带处理指示特征如is_treatment可转为布尔且 control 样本为 False、treatment 样本为 True推理数据则不需要该特征模型自动返回预测输出两组 logits 的 shape/dtype 必须一致TwoTowerLogitsHead运行时校验两组预测同理否则tf.where选择逻辑与 uplift 差值计算无法成立。小结official/recommendation/uplift提供了一条完整的 uplift 建模链路以TwoTowerUpliftNetwork双塔架构为核心backbone 共享表示 两塔各自学习 logits 头以TwoTowerUpliftModel封装训练/评估/推理三种模式以TrueLogitsLoss与整体切片指标族完成监督与诊断并以全量 Keras 序列化支撑 TFX 生态集成。继续深入可参考架构与用法总览official/recommendation/uplift/README.md大规模数据训练教程official/recommendation/uplift/uplift_modeling_intro.ipynb网络与输出头实现two_tower_uplift_network.py、two_tower_output_head.py模型与损失实现two_tower_uplift_model.py、true_logits_loss.py指标与测试用例metrics/、models/two_tower_uplift_model_test.py参考文献Johansson, Fredrik, Uri Shalit, and David Sontag. Learning representations for counterfactual inference.International conference on machine learning. PMLR, 2016.Shalit, Uri, Fredrik D. Johansson, and David Sontag. Estimating individual treatment effect: generalization bounds and algorithms.International conference on machine learning. PMLR, 2017.Johansson, Fredrik D., et al. Learning weighted representations for generalization across designs.arXiv preprint arXiv:1802.08598(2018).Hassanpour, Negar and Russell Greiner. CounterFactual Regression with Importance Sampling Weights.International Joint Conference on Artificial Intelligence(2019).Hassanpour, Negar and Russell Greiner. Learning Disentangled Representations for CounterFactual Regression.International Conference on Learning Representations(2020).【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考