上一篇把策略选择、执行回执和迟到结果写成决策级事件账本,并预告如何把这些事件拼成可复核的离线回放数据集。现在面对的难题不是估计器公式,而是数据:同一决策可能有多次投递、多个结果事件和迟到修订;一次普通的 SQL join 就能把一行变成五行,悄悄改变样本权重。
本篇只解决一个核心问题:**怎样从事件流确定性地构造“一条决策对应一条分析行”的策略回放表?**关键是先写清分析单位与结果定义,再按稳定 ID 去重、分层聚合、按决策时点连接特征,并检查行数和动作概率等不变量。回放表让估计器有正确输入,但它本身不证明因果识别假设成立。
01 从事件流到分析行#
决策日志是事件(event)而非一张天然整齐的训练表。一次请求可能产生 decision、execution_attempt、execution_receipt 和若干 outcome。这些记录通过 decision_id 关联,事件自身用 event_id 去重;多个结果是否合成一个标签,要由结果定义和观察窗决定。
flowchart LR
D[决策事件<br/>decision_id + action + propensity] --> K{按决策键分组}
X[特征快照引用<br/>决策时可用] --> K
E[执行事件<br/>attempt / receipt] --> A[按序解析最终执行事实]
A --> K
Y[结果事件<br/>event_id + event_time] --> W[按结果口径、窗口、水位聚合]
W --> K
K --> V[检查唯一性、覆盖率、概率与时间边界]
V --> R[回放行<br/>一条决策 × 一个结果定义]
Y -.无效键/迟到/重复.-> Q[隔离区与诊断计数]mermaid这里有两个不同的键:event_id 标识一次上报,确保重试不被重复计算;decision_id 标识一次策略决策,保证最终分析行不因多个子事件被复制。若把用户 ID 当主键,同一用户多次请求会被压成一条;若把结果事件直接连到决策而不先聚合,多次点击会复制该决策的动作和倾向概率。
02 先冻结“这一行代表什么”#
示例目标定为每次合格决策在 7 天内是否至少产生一次确认转化。一行键为 (decision_id, outcome_spec_id);outcome_spec_id 固定转化事件、归因规则、7 日观察窗、去重逻辑和版本。若要研究转化次数或金额,必须换结果定义,不能把同一行的任意事件数直接当作同一个标签。
目标回放表每行包含:决策 ID 与时间、决策时特征向量、候选动作及顺序、日志策略概率、分配动作、实际执行动作与状态、结果值或未知状态、标签水位和源事件版本。对 个决策、 个特征、 个动作,常见形状是 、、、、。P0[i,j] 必须与第 j 个稳定动作 ID 对齐,不能依赖不受控的数组顺序。
设决策 的时间是 ,结果观察窗长度为 ,标签管道延迟保护为 ,评估快照截点为 。只有同时满足
才把“窗口内没看到转化”解释为 ; 是上游对结果事件已完整处理到的水位(watermark)。否则结果为 unknown,不能偷写为零。正向事件则还需满足事件时间在 内、且在快照截点前已入库。水位落后于时钟时,日历上看似成熟也未必完整。
03 手算:一次 join 怎样把样本权重放大#
评估截点为 10 月 20 日 12:00,结果窗 7 天,保护延迟 1 天,结果水位已到 10 月 19 日:
| decision_id | 决策时间 | 动作 / 日志概率 | 执行事件 | 结果事件 | 正确回放行 |
|---|---|---|---|---|---|
| d1 | 10 月 1 日 09:00 | 提醒 / 0.60 | delivered 一条 | 两条转化上报,event_id 不同 | 一行,(“至少一次”) |
| d2 | 10 月 8 日 09:00 | 不提醒 / 0.40 | 一次重试回执 | 无转化事件 | 一行,(窗口与水位均成熟) |
| d3 | 10 月 19 日 09:00 | 提醒 / 0.50 | 回执未到 | 无事件 | 一行,(未成熟) |
| — | — | — | — | 一条找不到决策键的孤儿事件 | 隔离并计数,不造新决策 |
若直接把 d1 的转化明细表 join 到决策表,会得到两行 d1 加一行 d2、一行 d3,样本数从 3 变成 4;d1 在估计中被隐式加权两次。先按结果定义将 d1 的两条事件折叠为“至少一次”,再左连接回决策表,才保持一个决策一行。d3 的空结果不是零:它的 7 日窗尚未关闭。
04 构造步骤与不变量#
1. 固定数据截点、结果定义、观察窗和动作词典版本
2. 验证 decision_id 唯一;对 event_id 精确去重,冲突重复直接报错
3. 按决策键和生产者序号解析执行回执;保留分配动作与实际执行动作两列
4. 从 feature_ref 取回不可变快照,验证 available_at <= decision_at
5. 过滤时间窗与入库截点内的结果事件,按 outcome_spec 折叠为一条标签
6. 以决策表为左表连接,输出一决策一行;未成熟标签保留 unknown
7. 检查行数、重复键、孤儿率、回执率、标签完整率、概率向量与时间水位
8. 保存源 revision、聚合协议和每项诊断,失败行进入隔离区而不是静默丢弃text至少守住这些结构性不变量:
- 回放行数等于符合资格的决策数(每个
outcome_spec_id单独计算)。 (decision_id, outcome_spec_id)唯一;决策事件里的动作与特征快照没有因子事件数量增加而复制。- 所有特征值在决策时可用;结果事件发生时间位于观察窗内,入库时间不晚于评估截点。
- 每行选择概率有限、在
[0,1]内、对候选动作求和为 1,且被日志策略选中的分配动作概率大于 0。 - 孤儿事件、重复冲突、执行缺失、标签未知和被隔离记录各有计数与原因。
覆盖率高不等于无偏。比如只有 70% 回执被连接上,若缺失集中于高延迟设备,剩余行可能不是原决策群体的代表。报告总分母,并按动作、时间、平台和关键预先定义分组检查缺失;不要只公布最终成功连接的百分比。
05 Python 最小实现:输入事件,输出决策级回放行#
下面的标准库实现处理一个二元“7 日内至少一次转化”定义。输入是四个版本化来源的轻量内存示例:决策行、特征快照、执行回执、结果事件;输出以 decision_id 为键的一行字典,以及孤儿事件计数。它演示连接与成熟判定,不替代生产流处理引擎。
from collections import defaultdict
from datetime import datetime, timedelta
from math import isclose, isfinite
def instant(value):
dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
if dt.utcoffset() is None:
raise ValueError("时间必须带时区")
return dt
def unique_events(events):
"""同 event_id 且内容完全相同才可视为安全重试。"""
by_id = {}
for event in events:
key = event["event_id"]
if key in by_id and by_id[key] != event:
raise ValueError(f"event_id 内容冲突: {key}")
by_id[key] = event
return list(by_id.values())
def build_replay(decisions, feature_snapshots, executions, outcomes,
as_of, outcome_watermark, horizon_days=7, lag_days=1):
cutoff = instant(as_of)
watermark = instant(outcome_watermark)
horizon = timedelta(days=horizon_days)
lag = timedelta(days=lag_days)
decision_by_id = {}
for row in decisions:
key = row["decision_id"]
if key in decision_by_id:
raise ValueError(f"decision_id 不唯一: {key}")
decision_by_id[key] = row
features_by_ref = {row["feature_ref"]: row for row in feature_snapshots}
if len(features_by_ref) != len(feature_snapshots):
raise ValueError("feature_ref 必须唯一且不可变")
exec_by_decision = defaultdict(list)
for event in unique_events(executions):
if event["decision_id"] in decision_by_id:
exec_by_decision[event["decision_id"]].append(event)
outcome_by_decision = defaultdict(list)
clean_outcomes = unique_events(outcomes)
for event in clean_outcomes:
if event["decision_id"] in decision_by_id:
outcome_by_decision[event["decision_id"]].append(event)
orphan_count = sum(
event["decision_id"] not in decision_by_id for event in clean_outcomes
)
replay = []
for decision_id, decision in decision_by_id.items():
decided_at = instant(decision["decision_at"])
snapshot = features_by_ref.get(decision["feature_ref"])
if snapshot is None:
raise ValueError(f"缺少特征快照: {decision_id}")
if instant(snapshot["available_at"]) > decided_at:
raise ValueError(f"特征在决策后才可用: {decision_id}")
actions = decision["candidate_actions"]
probs = decision["action_probabilities"]
if len(actions) == 0 or len(actions) != len(probs) or len(set(actions)) != len(actions):
raise ValueError(f"候选动作和概率映射无效: {decision_id}")
if any(not isfinite(p) or p < 0 or p > 1 for p in probs):
raise ValueError(f"动作概率超出 [0,1]: {decision_id}")
if not isclose(sum(probs), 1.0, rel_tol=0, abs_tol=1e-9):
raise ValueError(f"动作概率之和不为 1: {decision_id}")
chosen = decision["assigned_action"]
if chosen not in actions or probs[actions.index(chosen)] <= 0:
raise ValueError(f"所选动作与日志概率不匹配: {decision_id}")
# sequence 是执行生产者定义的单调序号;缺失回执保持显式 unknown。
receipts = sorted(exec_by_decision[decision_id], key=lambda e: e["sequence"])
if len({e["sequence"] for e in receipts}) != len(receipts):
raise ValueError(f"执行 sequence 冲突: {decision_id}")
final_receipt = receipts[-1] if receipts else None
window_end = decided_at + horizon
mature = cutoff >= window_end + lag and watermark >= window_end
in_window = [
event for event in outcome_by_decision[decision_id]
if decided_at <= instant(event["event_at"]) <= window_end
and instant(event["ingested_at"]) <= cutoff
]
label = int(bool(in_window)) if mature else None
replay.append({
"decision_id": decision_id,
"decision_at": decision["decision_at"],
"features": snapshot["values"],
"candidate_actions": actions,
"probabilities": probs,
"assigned_action": chosen,
"executed_action": final_receipt["executed_action"] if final_receipt else None,
"execution_status": final_receipt["status"] if final_receipt else "unknown",
"conversion_7d": label,
"label_status": "mature" if mature else "not_mature",
})
assert len(replay) == len(decisions)
assert len({row["decision_id"] for row in replay}) == len(replay)
return replay, {"orphan_outcomes": orphan_count}
as_of = "2026-10-20T12:00:00+08:00"
decisions = [
{"decision_id": "d1", "decision_at": "2026-10-01T09:00:00+08:00",
"feature_ref": "f1", "candidate_actions": ["none", "remind"],
"action_probabilities": [0.40, 0.60], "assigned_action": "remind"},
{"decision_id": "d2", "decision_at": "2026-10-08T09:00:00+08:00",
"feature_ref": "f2", "candidate_actions": ["none", "remind"],
"action_probabilities": [0.60, 0.40], "assigned_action": "none"},
{"decision_id": "d3", "decision_at": "2026-10-19T09:00:00+08:00",
"feature_ref": "f3", "candidate_actions": ["none", "remind"],
"action_probabilities": [0.50, 0.50], "assigned_action": "remind"},
]
features = [
{"feature_ref": f"f{i}", "available_at": row["decision_at"],
"values": [0.2 * i, float(i)]}
for i, row in enumerate(decisions, start=1)
]
executions = [
{"event_id": "e1", "decision_id": "d1", "sequence": 1,
"status": "delivered", "executed_action": "remind"},
{"event_id": "e2", "decision_id": "d2", "sequence": 1,
"status": "delivered", "executed_action": "none"},
]
outcomes = [
{"event_id": "y1", "decision_id": "d1", "event_at": "2026-10-03T10:00:00+08:00",
"ingested_at": "2026-10-03T10:01:00+08:00"},
{"event_id": "y2", "decision_id": "d1", "event_at": "2026-10-04T10:00:00+08:00",
"ingested_at": "2026-10-04T10:02:00+08:00"},
{"event_id": "orphan", "decision_id": "missing", "event_at": "2026-10-03T10:00:00+08:00",
"ingested_at": "2026-10-03T10:01:00+08:00"},
]
rows, diagnostics = build_replay(
decisions, features, executions, outcomes, as_of,
outcome_watermark="2026-10-19T00:00:00+08:00",
)
print([(r["decision_id"], r["conversion_7d"], r["label_status"]) for r in rows])
print(diagnostics)
# [('d1', 1, 'mature'), ('d2', 0, 'mature'), ('d3', None, 'not_mature')]
# {'orphan_outcomes': 1}python输入的决策表必须一决策一行;特征快照由不可变 feature_ref 唯一定位。执行回执先按事件 ID 去重,再依生产者的单调 sequence 取最终状态;不能按到达本机的顺序猜“最后一次”。结果事件先按 event_id 去重,最后按 decision_id 和固定观察窗聚合。输出 replay 长度与合格决策行数相同,孤儿事件单独计数。上例中特征值 values 是长度 的向量,所以三行整体可堆成 ;每行概率是 ,标签是 且允许 None。
生产管道还必须验证重复 event_id 的字段规范化规则、结果类型与货币单位、跨日时区语义和水位单调性。示例没有静默容忍冲突,也没有因缺少执行回执就删除决策。若标签到齐概率与动作、人群或系统状态有关,仅在成熟且有标签的行上计算仍可能选择偏差;需要报告缺失分层,或采用明确的删失/缺失处理并做敏感性分析。
06 执行动作和分配动作不能合并成一列#
日志策略概率通常描述系统分配或选择动作的分布。执行侧可能因安全规则、库存、超时或服务降级改变动作。保留 assigned_action 和 executed_action 两列,评估前先声明估计目标:
- 评估策略选择本身时,动作变量按设计定义为分配动作,执行失败是策略系统的一部分或独立结果。
- 评估实际收到干预的效果时,需要可靠曝光/执行事实;只筛选成功执行者可能引入执行选择偏差,通常不能直接沿用分配概率当作执行倾向。
- 若回退策略改变了动作分布,账本要记录实际生效策略路径和对应概率;无法还原时应标记不可评估,不能补造概率。
回放行的连接正确,只保证数据单位与字段语义明确。离线策略估计仍需上一系列讨论过的支持重叠、无未测混杂、结果定义和独立单位等条件;若日志策略对某动作概率为零,更多字段也补不出该动作的反事实反馈。
07 键盘可用的诊断清单#
按 Enter 或空格展开:回放表行数突然增加
先分来源记录连接前后的行数。按 decision_id 统计执行事件数、结果事件数和特征快照数;检查是否有一对多 join 未先聚合。再确认目标是“是否至少一次”还是次数/金额,防止不小心把不同归因单位相乘。最终键应是 (decision_id, outcome_spec_id),而不是结果事件 ID。
按 Enter 或空格展开:大量标签从 0 变成 unknown
比较评估截点 、结果水位 、决策时间、观察窗 和延迟保护 。先判断上游水位停滞还是样本确实尚未成熟;再按决策日和数据源报告成熟率。不要通过把 None 填成 0 来让报表完整。
按 Enter 或空格展开:同一动作的概率列与记录对不上
对每行打印稳定动作 ID 到概率的映射,而非只看裸数组;核对候选集 schema、赋值动作索引、服务回退前后概率版本和概率向量总和。目标动作无日志支持时,隔离的是识别问题,不是可用 SQL 修复的拼表问题。
HTML details/summary 可通过 Tab 聚焦、Enter 或空格展开,窄屏自然换行,也继承站点主题。上面的静态数据流、变量和文字诊断不依赖颜色或交互状态,因此离线阅读仍完整。
08 失败模式与方法边界#
| 失败 | 静默影响 | 检查与处置 |
|---|---|---|
| 结果明细直接连接决策 | 多次事件让单个决策重复加权 | 先按结果定义聚合,再执行左连接;核对唯一键 |
只用 decision_id 做事件去重 | 同一决策下合法的多个结果被误删 | 用 event_id 去重,按 outcome_spec 做归并 |
| 用当前特征表回填历史行 | 未来信息泄漏,重跑时输入漂移 | 只解析决策时快照引用;校验可用时间和摘要 |
| 用最后入库事件判执行状态 | 网络重试乱序会覆盖更权威状态 | 采用生产者单调序号或显式状态修订号 |
| 没看到结果就记为 0 | 未成熟样本被当作失败 | 同时检查观察窗、数据水位和截点,三态保留 |
| 静默丢掉孤儿/无效概率行 | 分母与覆盖率无法复核 | 逐类计数并隔离;保留原始来源 revision |
| 选择执行成功的行当作随机样本 | 按执行状态筛选可能改变估计目标 | 分开记录分配与执行,重述估计量并分析选择机制 |
| 连接无错就宣布可做因果评估 | 数据工程正确被误当成统计识别 | 单独审查重叠、混杂、结果缺失与聚类单位 |
回放行的摘要可用于核对生成输入是否变化,原始事件和快照则必须保存在有版本与权限控制的存储中。摘要不是备份、签名或可重建数据的替代品。若采用流处理系统,还需定义迟到事件重算策略、窗口修订版本和幂等写入边界;若数据量不大,批处理 SQL 也可以完成,但必须保持同一组连接不变量。
09 思考练习#
- 一个决策有 3 条执行状态和 4 条结果明细。分别设计“最终执行事实”和“7 日是否转化”的聚合规则,并说明哪些源列必须保留以便追溯。
- 某数据源水位只到决策后第 6 天,截点已过 10 天。7 日结果是否可记零?还缺哪个证据?
- 策略分配动作是提醒,但执行服务在 15% 请求上回退为不提醒。如何分别构造 ITT 与实际曝光分析表?为何不能把同一列概率直接用于两种目标?
相关工作#
- Li et al., A Contextual-Bandit Approach to Personalized News Article Recommendation ↗:将上下文、动作选择和后续反馈连成在线推荐的 bandit 记录。
- Dudík, Langford & Li, Doubly Robust Policy Evaluation and Learning ↗:给出基于日志动作概率和已观测结果的策略价值估计。
- Swaminathan & Joachims, Counterfactual Risk Minimization: Learning from Logged Bandit Feedback ↗:解释日志动作倾向如何进入离线学习目标。
- Sculley et al., Hidden Technical Debt in Machine Learning Systems ↗:分析反馈回路、数据依赖与生产 ML 系统的隐性耦合。
- Breck et al., The ML Test Score: A Rubric for ML Production Readiness and Technical Debt Reduction ↗:从数据验证、模型监控和生产就绪角度补充工程检查框架。
下一篇预告#
有了稳定的一决策一行回放表,还要回答策略在不同日志样本和目标人群上是否真的有足够支持。下一篇将把动作支持、有效样本量和权重尾部合成一份可执行的离线评估门槛,并说明何时应停止给出单点结论。