Product Experimentation with Uplift Modeling: Targeting Your LLM Feature Rollout to Users Who Actually Benefit (Python Implementation)

ITE(i) = Y_i(1) - Y_i(0)

CATE(x) = E[Y(1) - Y(0) | X = x]

pip install numpy pandas scikit-learn matplotlib scipy

git clone https://github.com/RudrenduPaul/product-experimentation-causal-inference-genai-llm.git
cd product-experimentation-causal-inference-genai-llm
python data/generate_data.py --seed 42 --n-users 50000 --out data/synthetic_llm_logs.csv

import pandas as pd
import numpy as np

df = pd.read_csv("data/synthetic_llm_logs.csv")
print(df.shape)
print(df[["engagement_tier", "opt_in_agent_mode", "task_completed"]].head(10))

# 按层级的启用率
print("\n按参与层级的启用率:")
print(df.groupby("engagement_tier").opt_in_agent_mode.mean().round(3))

# 粗略平均处理效应：处理组减对照组
naive_ate = (
    df[df.opt_in_agent_mode == 1].task_completed.mean()
    - df[df.opt_in_agent_mode == 0].task_completed.mean()
)
print(f"\n粗略平均处理效应（处理组 - 对照组）: {naive_ate:+.4f}")
print(f"处理组用户数: {(df.opt_in_agent_mode == 1).sum():,}")
print(f"对照组用户数: {(df.opt_in_agent_mode == 0).sum():,}")

(50000, 16)
  engagement_tier  opt_in_agent_mode  task_completed
0          medium                  0               0
...

按参与层级的启用率:
engagement_tier
heavy     0.647
light     0.120
medium    0.353
Name: opt_in_agent_mode, dtype: float64

粗略平均处理效应（处理组 - 对照组）: +0.2106
处理组用户数: 13,451
对照组用户数: 36,549

# 按层级的简单差距（存在混淆但方向有用）
print("按层级处理组与对照组完成率对比:")
for tier in ["light", "medium", "heavy"]:
    sub = df[df.engagement_tier == tier]
    t_rate = sub[sub.opt_in_agent_mode == 1].task_completed.mean()
    c_rate = sub[sub.opt_in_agent_mode == 0].task_completed.mean()
    print(f"  {tier:8s}: treated={t_rate:.3f}, control={c_rate:.3f}, "
          f"diff={t_rate - c_rate:+.3f}")

按层级处理组与对照组完成率对比:
  light   : treated=0.551, control=0.455, diff=+0.096
  medium  : treated=0.745, control=0.670, diff=+0.075
  heavy   : treated=0.891, control=0.824, diff=+0.067

from sklearn.linear_model import LinearRegression
import pandas as pd
import numpy as np

# 构建特征矩阵：query_confidence + engagement_tier虚拟变量
X_full = pd.get_dummies(
    df[["query_confidence", "engagement_tier"]],
    drop_first=False
).astype(float)

feature_cols = X_full.columns.tolist()
print("特征列:", feature_cols)

X_all = X_full.values
treated_mask = df.opt_in_agent_mode == 1
control_mask = ~treated_mask

X1 = X_all[treated_mask]    # 处理组用户特征
Y1 = df[treated_mask].task_completed.values
X0 = X_all[control_mask]    # 对照组用户特征
Y0 = df[control_mask].task_completed.values

# 在每个组别上拟合独立模型
m1 = LinearRegression().fit(X1, Y1)   # 处理组结果模型
m0 = LinearRegression().fit(X0, Y0)   # 对照组结果模型

# CATE = mu_1(x) - mu_0(x)
cate_t = m1.predict(X_all) - m0.predict(X_all)
df["cate_tlearner"] = cate_t

print(f"\n平均CATE (T-learner): {cate_t.mean():+.4f}")
print("\n按参与层级划分的平均预测CATE:")
print(df.groupby("engagement_tier").cate_tlearner.mean().round(4))

特征列: ['query_confidence', 'engagement_tier_heavy', 'engagement_tier_light', 'engagement_tier_medium']

平均CATE (T-learner): +0.0847

按参与层级划分的平均预测CATE:
engagement_tier
heavy     0.0665
light     0.0954
medium    0.0744
Name: cate_tlearner, dtype: float64

以下是具体实现方式：你将参与层级编码为独热编码列，同时将查询置信度保留为连续特征。分别训练两个线性回归模型：m1学习已参与用户的任务完成条件期望，m0学习未参与用户的相同指标。对于任意具有特征x的用户，预测的CATE值为m1(x) - m0(x)。

输出结果验证了朴素差距的结论方向，但显著提升了估计精度。所有50,000名用户的平均CATE值为+0.0847，接近真实值+0.08。各层级排序为轻度(+0.0954) > 中度(+0.0744) > 重度(+0.0665)。此前+0.2106的朴素ATE隐藏了轻度用户与重度用户之间1.4倍的差异，这个差异就是你的分群信号。

T-learner有一个重要注意事项需要说明：当某一臂样本量远小于另一臂（此处为13,451个处理组 vs 36,549个对照组）时，小样本臂训练的模型可能出现更高方差。在50,000总样本量下，线性回归对此处理得相对合理。下一步的X-learner将直接解决这种不平衡问题。

## 第2步：X-learner（处理不平衡处理臂）

X-learner通过利用大样本臂来估计小样本臂的CATE，从而改进T-learner。它通过为每个用户计算插补处理效应来实现：使用跨臂模型预测的反事实结果，再与实际观测结果进行差分。

该方法包含四个步骤：

- 在每个臂上拟合结果模型m0和m1（与T-learner相同）。

- 对处理组用户：计算D1 = Y1 - m0(X1)，即每个处理组用户实际达成结果与对照模型预测的未处理结果之间的差异。

- 对对照组用户：计算D0 = m1(X0) - Y0，即每个对照组用户在处理下预测结果与实际达成结果之间的差异。

- 拟合两个tau回归器（每个臂一个），然后使用倾向得分作为权重进行组合。根据(Künzel等)：tau(x) = g(x)*tau_1(x) + (1 - g(x))*tau_0(x)，其中g(x)是倾向得分。当g(x)较低（该特征区域处理用户较少时），来自大对照组的tau_0获得更大权重；当g(x)较高时，tau_1获得更大权重。

# 比较 T-learner 与 X-learner
print("\n按参与层级比较 T-learner 与 X-learner:")
comp = df.groupby("engagement_tier")[["cate_tlearner", "cate_xlearner"]].mean().round(4)
print(comp)

平均 CATE（X-learner）：+0.0847

按参与层级预测的平均 CATE：
engagement_tier
heavy     0.0665
light     0.0954
medium    0.0744
Name: cate_xlearner, dtype: float64

T-learner 与 X-learner 按参与层级比较：
                 cate_tlearner  cate_xlearner
engagement_tier
heavy                   0.0665         0.0665
light                   0.0954         0.0954
medium                  0.0744         0.0744

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

# 按预测 CATE 降序排列用户
df_sorted = df.sort_values("cate_tlearner", ascending=False).copy()
n = len(df_sorted)

# 计算每个百分位截断处的观察到的提升率
top_ks = np.arange(0.01, 1.01, 0.01)
qini_vals = []

for k in top_ks:
    top_n = max(1, int(k * n))
    sub = df_sorted.iloc[:top_n]
    treated_sub = sub[sub.opt_in_agent_mode == 1]
    control_sub  = sub[sub.opt_in_agent_mode == 0]
    if len(treated_sub) > 0 and len(control_sub) > 0:
        uplift = (treated_sub.task_completed.mean()
                  - control_sub.task_completed.mean())
    else:
        uplift = np.nan
    qini_vals.append(uplift)

# 绘图
fig, ax = plt.subplots(figsize=(8, 4.5))
ax.plot(top_ks * 100, qini_vals, linewidth=2, label="T-learner Qini")
ax.axhline(naive_ate, color="gray", linestyle="--",
           label=f"Naive ATE = {naive_ate:.4f}")
ax.set_xlabel("前 k% 用户（按预测 CATE 排序）")
ax.set_ylabel("前 k 组的观察到的提升率")
ax.set_title("Qini 曲线：T-learner 排名与观察到的提升率")
ax.legend()
plt.tight_layout()
plt.savefig("qini_curve.png", dpi=140)
print("Saved qini_curve.png")

# 打印选定百分位的值
print("\n选定截断点的 Qini 值：")
for target_k in [10, 20, 30, 50, 70, 100]:
    idx = target_k - 1
    print(f"  前 {target_k:3d}%: 观察到的提升率 = {qini_vals[idx]:.4f}")

Saved qini_curve.png

选定截断点的 Qini 值：
  前  10%: 观察到的提升率 = 0.0895
  前  20%: 观察到的提升率 = 0.1018
  前  30%: 观察到的提升率 = 0.0959
  前  50%: 观察到的提升率 = 0.0966
  前  70%: 观察到的提升率 = 0.1454
  前 100%: 观察到的提升率 = 0.2106

# 首先检查CATE分布
print("CATE分布（T-learner）:")
print(pd.Series(df.cate_tlearner).describe().round(4))
print()

# 绘制CATE分布
fig, ax = plt.subplots(figsize=(8, 4))
ax.hist(df.cate_tlearner, bins=50, edgecolor="white", linewidth=0.5)
ax.axvline(0.085, color="red", linestyle="--", label="阈值 = 0.085")
ax.axvline(df.cate_tlearner.mean(), color="gray", linestyle=":",
           label=f"平均CATE = {df.cate_tlearner.mean():.4f}")
ax.set_xlabel("预测CATE（T-learner）")
ax.set_ylabel("用户数量")
ax.set_title("预测CATE分布")
ax.legend()
plt.tight_layout()
plt.savefig("cate_distribution.png", dpi=140)
print("已保存cate_distribution.png")

# 应用部署规则
threshold = 0.085
selected = df[df.cate_tlearner >= threshold].copy()
suppressed = df[df.cate_tlearner < threshold].copy()

print(f"\n部署阈值: CATE >= {threshold}")
print(f"被选中部署的用户数量: {len(selected):,} ({100*len(selected)/len(df):.0f}%)")
print(f"被抑制的用户数量:           {len(suppressed):,} ({100*len(suppressed)/len(df):.0f}%)")
print()
print("选中组的层级构成:")
print((selected.groupby("engagement_tier").size() / len(selected)).round(3))
print()
print(f"选中组的平均预测CATE:   {selected.cate_tlearner.mean():.4f}")
print(f"被抑制组的平均预测CATE: {suppressed.cate_tlearner.mean():.4f}")

CATE分布（T-learner）:
count    50000.0000
mean         0.0847
std          0.0126
min          0.0515
25%          0.0731
50%          0.0897
75%          0.0963
max          0.1021
Name: cate_tlearner, dtype: float64

已保存cate_distribution.png

部署阈值: CATE >= 0.085
被选中部署的用户数量: 27,203 (54%)
被抑制的用户数量:           22,797 (46%)

选中组的层级构成:
engagement_tier
light    1.0
dtype: float64

这里发生了什么：在设置阈值之前，你需要检查完整的CATE分布。所有50,000名用户的平均CATE为+0.0847，标准差为+0.0126。将阈值设为+0.085（略高于平均值+0.0847）时，会选中27,203名用户（54%）。

所选群体的层级构成是100%轻度用户：使用线性模型和这些特征时，每个层级的CATE范围在阈值处没有重叠。轻度用户的预测CATE都在+0.0807到+0.1021之间。中度用户的预测CATE在+0.0592到+0.0812之间。0.085的阈值清晰地将两者分隔开。

所选群体的预测平均CATE（+0.0955）比被抑制群体（+0.0719）高出33%。这种集中度就是分层上线的价值：你将AI摘要部署给最可能受益的54%用户，对预测收益较小的中度和重度用户保持克制，并收集两组数据以每季度优化阈值。

图2：来自50,000用户合成数据集的各层级CATE分布。上图显示了每个参与层级的平滑核密度估计曲线：轻度用户（蓝色）聚集在最高的预测CATE区域，重度用户（绿色）聚集在最低区域。下图显示了每个层级的平均CATE及95%自助法置信区间，同时以天真ATE（+0.2106）作为参考线。所有三个层级的置信区间都明显低于天真ATE，证实平均值受到了选择偏差的干扰。

上线规则可直接映射到功能标志系统：

这里发生了什么：你将CATE计算封装成一个函数，该函数的行为与真实的功能标志服务在请求时的运行方式一致。一个查询置信度中等的重度用户会得到show feature=False和CATE=+0.0667，低于0.085阈值。相同查询置信度的轻度用户会得到show feature=True和CATE=+0.0955。一个置信度较低的中度用户则会低于+0.0681阈值。

这些输出与领域故事一致：AI摘要帮助那些难以在会话间保持上下文的用户，而参与层级是衡量这种困难的强代理指标。

## 第5步：自助法置信区间

以上 CATE 估计值均为点估计，未包含不确定性量化。在基于这些估计值构建部署规则前，你需要了解这些估计值在用户群体不同样本中的稳定性。

以下是实现过程：对完整的 50,000 用户数据集进行 500 次有放回重采样，每次重采样后重新拟合 T-learner 模型，并计算自助法迭代中平均 CATE 的分布。该分布的 2.5% 和 97.5% 分位数即为每个估计值的 95% 置信区间。

需要关注这些置信区间的三个要点：首先，总体均值置信区间（+0.0744，+0.0951）包含真实值 +0.08，验证了估计器的有效性；其次，轻度用户层级的置信区间（+0.0781，+0.1125）比重度用户层级（+0.0483，+0.0842）更宽，这与轻度用户最低的参与率（12%）导致的样本量不足相一致；第三，各层级置信区间尾部未完全分离：轻度用户的下限（+0.0781）刚超过重度用户的上限（+0.0842），表明轻度用户效应大于重度用户的排序是稳定的，但差距并不显著。

对于需要差异化部署的商业决策，这种稳定性已足够支撑决策。在监管或临床场景中，可能需要更大样本量。

## 当提升建模失效时

CATE 模型看似具有吸引力，因为它能生成连续的个性化评分。在部署基于 CATE 的策略前，有四种失效模式需要特别关注。

### 1. 稀疏分段（重叠违反）

对于轻度用户，CATE 的估计值基于您 13,451 名接受治疗用户中的 12%，即约 1,614 人。这一规模足以检测层级平均效果，但不足以在细粒度特征值下可靠估计个体层级效果。

当治疗组在特征空间的某个区域覆盖率较低时，该区域的 CATE 估计值会存在较高方差。模型会返回平滑预测，但其背后的实证支持可能较弱。

在依据排名采取行动前，请检查高 CATE 用户的特征分布，并验证每个区域中是否存在治疗组和对照组观测值。

### 2. 尾部外推（重叠假设违反）

线性回归会在训练范围外进行平滑外推。如果模型为某个特征值落在某组训练数据完全缺失区域的用户分配了 CATE 预测值，该估计值将缺乏实证支持。

重叠假设的失效是静默发生的：模型会返回一个数值，但该区域的 P(T=1|X=x) 接近 0 或 1，导致 CATE 无法识别。

请同时检查倾向得分与 CATE 预测值，并在倾向得分超出 [0.05, 0.95] 范围时对估计值进行截断或标记。

### 3. 小 k 值下的 Qini 噪声

在极小 k 值（前 5% 或更少）时，Qini 曲线会出现显著噪声。当评估组仅包含几百名用户时，该组内的治疗用户数量可能过少，导致观察到的提升效果被抽样噪声主导。

应基于 20% 至 50% 的 Qini 范围进行发布决策，该范围内的信号更稳定。在观察性场景中，大 k 值下的高 Qini 值（如本教程中前 70% 的 +0.1454）可能反映选择偏差，掩盖了真实的 CATE 信号。在解读提升值前，请检查每个 top-k 组的层级构成。

### 4. CATE 模型过拟合

此处对治疗组使用线性回归模型时，有 13,451 个观测值和 4 个特征，这是一个较为宽松的条件。如果您用梯度提升替代线性回归并增加 30 个特征，可能会将治疗效应的估计值过度拟合到训练噪声中。CATE 预测值在训练集上会表现出显著异质性，但在验证集上会向全局均值回归。只有当 CATE 模型在验证集上的提升效果优于层级平均值时，其复杂度才值得存在。在使用该模型构建发布规则前，请在验证数据集上进行评估。

## 下一步行动

上述实现未使用外部提升库，以便您能清晰看到每一步的具体计算过程。在生产环境中，causalml 和 econml 提供了更强大的估计器实现：基于树的 T-学习器、双重稳健 X-学习器，以及通过分离训练样本和估计样本以降低过拟合风险的诚实因果森林。这两个库都遵循您在此处构建的相同概念结构。

causalml 包含生产级 Qini 曲线计算功能和 AUUC（提升曲线下的面积）指标，该指标可将 Qini 曲线压缩为单一比较数值。在 A/B 测试框架中进行提升模型比较时，AUUC 是标准的排行榜指标。

需要特别指出的一个结构性限制：本教程假设了 SUTVA（每个用户的结局仅取决于其自身的治疗状态）。在基于工作空间的 AI 产品中，这一假设通常不成立。同一工作空间内的用户共享共同环境，对一个用户的治疗可能通过共享输出、改变响应模式或改变工作空间动态影响其队友。

当您怀疑存在此类干扰时，能够将组内相关性传播到CATE估计中的DR-learner变体可以提供更现实的不确定性边界。标准的T-learner和X-learner将所有观测视为独立，这在工作区级因素起作用时会低估不确定性。

本教程的配套代码库位于github.com/RudrenduPaul/product-experimentation-causal-inference-genai-llm/tree/main/08_uplift_modeling。克隆该仓库，使用--n-users 50000 --seed 42生成数据集，并运行uplift_demo.py以复现本教程的所有结果。

ATE是您决定是否构建某个功能所需的数值。CATE是您决定谁先获得该功能所需的数值。将治疗集中在预测响应最强的54%用户上进行分段发布，比将同一功能推广给所有人能产生更显著的效果。统一发布是一种策略选择。请基于充分信息做出决策。

我是应用AI/ML和营销测量科学领域的领导者，拥有15年以上在财富50强公司构建和扩展应用AI及机器学习产品的经验。我专长于因果推理、实验、自主代理AI系统以及企业AI战略，这些技术已成功应用于零售媒体网络（RMN）、广告、广告技术、营销技术、消费品（CPG）和电子商务领域。我是Springer Nature、Elsevier、ICML（顶级AI/ML会议）和IEEE的出版作者，也是领先AI/ML和分析出版物的常驻贡献者（个人观点）。

如果本文对您有帮助，请分享它。

免费学习编程。freeCodeCamp的开源课程已帮助超过40,000人成为开发者。立即开始

ADVERTISEMENT