Temporal Multi-Interest Retrieval with Anchored Calibration
在线作品集 · 一页式案例 · 简历与面试材料 · 完整本地演示
Public release note: this repository uses a sanitized single-root history. Raw datasets, processed rows, checkpoints, per-user artifacts, deployment bundles, and FairJob-derived model weights are intentionally excluded. The committed reports are aggregate/audit evidence from documented private runs; cloning this public snapshot does not reproduce those GPU runs by itself.
面向短视频场景的可复现两阶段推荐系统。项目基于 KuaiRec 2.0，从偏置曝光日志出发，覆盖时间切分、全库召回、多目标排序、近全观测校准、偏差诊断、Bad Case 分析和可部署推理工作台。
项目不以“复刻一个模型”为目标，而是回答一个更接近工业推荐的问题：
在偏置曝光日志上表现更好的推荐器，能否在近全观测用户-视频矩阵中仍保持可信表现？
KuaiRec 内部的召回、重排、校准和分群选择仍以 Dev 为准。一次性 Final 审计中，Ranking Final 成功；原 KuaiRec Big Retrieval 在诊断阶段因 NameError: name 'warm_item' is not defined 失败并永久保留，未重跑，因此 reserved small-matrix final 未执行。
项目另行完成了独立的 KuaiRand-1K External Final：模型在标准策略日志上重新训练，并在物理隔离的随机曝光 holdout 上按冻结协议仅评测一次。TRACE 的预注册主指标 NDCG@10 为 0.39118，高于 Single-interest 的 0.38531；差值为 +0.00587，paired-user 95% CI 为 [-0.00983, 0.02312]。该结果说明 TRACE 在本次外部评测中主指标最高，但区间跨 0，不能宣称统计显著提升。项目不宣称 SOTA，也不将离线结果包装成线上 A/B 收益。
面向“搜广推”岗位，仓库进一步增加了三条独立证据泳道：Amazon ESCI 候选搜索排序、Criteo FairJob 广告点击/公平审计，以及 Hillstrom 历史随机营销实验和 uplift 分析；同时实现稳定分桶、事件契约、SRM、CUPED、Holm 校正与功效/MDE。KuaiRec、ESCI、FairJob、Hillstrom 不共享用户或线上请求，页面明确标记为 DEV RECOMMENDATION、OFFLINE SEARCH、OFFLINE FAIR ADS 和 HISTORICAL RCT，不能描述成同一生产漏斗。
- TRACE 多兴趣召回：将严格时序历史编码为 4 条兴趣路由，使用时间衰减注意力和低温 smooth-max 兴趣匹配缓解单向量兴趣稀释。
- 偏差感知评测：同时报告整体、严格冷启动、暖尾、覆盖率、流行度集中度和按用户 bootstrap 置信区间。
- Anchored Calibration：仅在
small_matrix的 anchor-train 用户上拟合低容量校准器，在互斥 anchor-dev 用户上选参；缺失行始终视为未观测，而不是负例。 - 约束式多样性重排：Balanced 策略在质量、暖尾损失和 Gini 约束下选择；激进冷探索仅保留为非默认权衡案例。
- 多目标排序：比较 Logistic、Shared-Bottom、MMoE、启发式 inverse-popularity SNIPS 和层级一致性 MMoE，按 Dev NDCG 选择并受双任务 LogLoss 门禁约束。
- 实验完整性：自然日 as-of 协议、确定性采样、三种子复现、来源校验、产物哈希、Test 一次性审计和禁止覆盖。
- Post-Final 归因：固定六模型 × 三种子 Dev-only 消融，按用户 cluster bootstrap，并对兴趣路由有效秩、塌缩余弦和候选路由利用率做无标签诊断；不重跑或改写任何 Final。
- 独立外部评测：在 KuaiRand-1K 随机曝光数据上执行预注册、哈希绑定、append-only 的 External Final，同时报告点估计和 paired-user bootstrap 置信区间。
- 搜索排序实验：在 ESCI 人工相关性标签上比较 candidate-order、BM25、TF-IDF/SVD Dense 与线性 Pairwise LTR，Train 内切 Dev 选正则，固定 Test 按 Query cluster bootstrap。
- 公平感知广告排序：在 Criteo FairJob 107 万条真实曝光上训练 protected-attribute-unaware DeepFM，执行 Dev-only Platt 校准、公平惩罚 Pareto 选择、随机展示排序和 user-cluster bootstrap；公平 λ 未泛化时冻结回退 λ=0。
- 历史随机实验与 uplift：在 Hillstrom 64,000 行三臂 RCT 上报告 visit/conversion/spend 的 ITT、置信区间和六项 Holm 校正，并在标签盲哈希 Test 上评估 S/T learner 的 AUUC、Qini 与策略价值。
- A/B 工程层：实现跨进程 SHA-256 稳定分桶、互斥实验层、assignment/exposure/outcome 事件契约、SRM、CUPED、固定周期推断和 MDE；用 A/A 与已知合成效应验证实现，不冒充真实流量。
- 可演示部署：CPU 默认的 FastAPI 服务、模型注册表、缓存、结构化日志、健康检查和响应式推荐工作台。
- 并发生命周期安全：writer-preferring reader/writer guard 让普通推荐保留一致的运行时快照，激活模型会等待读请求完成；离线并发契约测试不冒充线上 SLA。
| 泳道 | 数据与协议 | 当前可引用证据 | 不能声称 |
|---|---|---|---|
| 推荐 | KuaiRec 三种子 Dev + 独立 KuaiRand External Final | TRACE Dev NDCG@20 +15.14%、Recall@50 +41.50%；External Final 主指标点估计最高但 CI 跨 0 | 线上推荐收益、External 显著提升 |
| 搜索 | Amazon ESCI 派生的固定 commit/SHA 转换镜像；Train 内切 Dev、固定 Test | 8,850 Query 上 LTR NDCG@10 0.80175，BM25 0.78427；delta +0.01748，95% paired CI [0.01545, 0.01960] | 全库召回、官方 parquet 原始字节、线上搜索 uplift |
| 广告排序 | Criteo FairJob 107 万条历史职位广告；用户隔离 Dev/Test | DeepFM Test ROC-AUC 0.69863、PR-AUC 0.01868；NLL 较常数先验 -0.001672，95% CI [-0.002483, -0.000935] | 非零公平 λ 提升、eCPM/竞价/预算、线上收入 |
| 广告实验 | Hillstrom 64,000 行历史三臂随机邮件实验 | Mens/Womens Visit ITT 分别 +7.659pp/+4.523pp；六项 ITT 经 Holm 后均拒绝零效应 | 本项目真实投放、线上收入提升 |
| A/B 工程 | 20,000 单元离线 dry run | SRM p=0.6714；A/A CI 含 0；已知 +4pp 合成效应恢复为 +4.372pp；20,000 assignment 全量重算 | 已上线实验、真实业务显著性 |
Uplift 的点估计必须与 bootstrap CI 一起解释；某个 Qini 为正不自动等于稳定收益。完整协议、数据来源、运行命令和口径见 SGR_EXPERIMENTS.md。
- Dev E2E 完整级联相对 Single-interest 将 NDCG@20 提升 71.12%、Recall@50 提升 131.56%，但 NDCG@10 回退 3.19%、Coverage@50 下降 22.89%。
- 参数匹配的 Monotonic MMoE 将 complete/valid 层级冲突降为 0；其 NDCG@10 为 0.697241，较原规则选中的 mmoe_snips 低约 0.54%，因此保留为 Dev Pareto 候选而不事后替换 frozen 模型。
- FAISS 在真实 10,728 物品目录上通过 Recall@200=100% 门禁但慢于 exact； 在百万级合成目录上 Recall@200 平均 99.08%，总延迟约加速 1.48 倍。
- 单机 CPU 未缓存 HTTP 压测为 33.1 QPS、P95 139.0 ms、0% 错误率。
完整协议、命令和限制见 TRACE-Rec V2 优化验收。
召回采用 3 个正式随机种子，指标先在 user-day 内聚合，再对用户等权平均。
| 对比 | 指标 | Baseline | Candidate | 相对变化 | 95% CI（绝对变化） |
|---|---|---|---|---|---|
| Single-interest -> TRACE | NDCG@20 | 0.009481 | 0.010917 | +15.14% | [0.001154, 0.001724] |
| Single-interest -> TRACE | Recall@50 | 0.020497 | 0.029004 | +41.50% | [0.007948, 0.009114] |
| Single-interest -> TRACE | Strict-cold Recall@50 | - | - | +64.72% | 见正式报告 |
| TRACE raw -> Balanced | NDCG@20 | 0.010917 | 0.010989 | +0.66% | [0.000047, 0.000097] |
| TRACE raw -> Balanced | Recall@50 | 0.029004 | 0.029399 | +1.36% | [0.000332, 0.000459] |
需要同时披露的权衡：TRACE 相对 Single-interest 的 Coverage@50 下降 10.71%；Balanced 相对 raw TRACE 的暖尾 Recall@50 绝对变化为 -0.000709。完整数字和口径见 retrieval_dev_summary.md、diversity_rerank_dev.md 与 dev_cohort_badcase.md。
Anchor-dev 上，popularity_decile 校准将观测对 Brier 从 0.615326 降至 0.190285；该任务的观测二值 NDCG@20 为 0.706650。它与时间召回 Dev 的分母和任务不同，不能横向比较。
LogQ 被保留为正式负结果，而不是从报告中删除。这一点用于展示项目具备实验否证能力，而不只是挑选正向数字。
在历史冻结之后，新增了严格锁定的 6 models × 3 seeds Dev diagnostic： 配置、模型顺序、输出路径、2,000 次 user-cluster bootstrap 均受 trace_attribution_dev_v1.json 约束；3 份 源报告与 18 份 checkpoint/逐用户工件由 SHA-256 绑定，并由 verify_trace_attribution_dev.py 只读复算。
- 完整多兴趣 TRACE 相对 Single-interest：NDCG@20 +0.001436 [+0.001140, +0.001730]，Recall@50 +0.008507 [+0.007955, +0.009067]，两个指标在全部三个种子均为正。
- 时间衰减：Recall@50 +0.016169 [+0.015363, +0.016971] 且三个种子同向； NDCG@20 的三种子平均区间为正，但有一个种子方向相反，不能把它包装成无条件稳定增益。
- smooth-max 相对 mean pooling 在两个指标上均三种子同向；但相对 hard max 的 retrieval 指标反而更低。hard max 的有效路由数 1.293、pairwise cosine² 0.714，相比 smooth-max 的 1.772 / 0.437 显示更明显的 route collapse， 因而这是 Dev 上的 retrieval–route-diversity 权衡，不是事后替换 frozen serving 模型的理由。
- diversity regularizer 的 full-minus-ablation 三种子方向不一致，三种子平均反而偏向 ablation；这一反结果被保留，不声称该正则带来独立 retrieval 增益。
完整可核验数据、方向一致性表与边界见 trace_attribution_dev_v1.md、 trace_attribution_dev_v1.json 和 trace_attribution_dev_v1_verification.json。 它们均为 post_final_dev_diagnostic，不读取 Test、不是线上 A/B、也不是新的 Final。 只读 verifier 会要求本地存在已哈希的 checkpoint 与逐用户工件；这些大文件不纳入 Git，因此缺少工件的克隆会诚实失败，而不会仅凭摘要伪造通过。
排序正式 Dev 使用 4,000,000/9,199,872 条确定性分层 Train 样本和全部 1,510,371 条 Dev 曝光。Dev 选择的 mmoe_snips 相对 Logistic 将 complete-play NDCG@10 从 0.662111 提升至 0.701055（+5.88%）；valid-play LogLoss 从 0.685406 回退至 0.692954，仍在预冻结门禁内，必须随主结果一起披露。
| 阶段 | 状态 | 可引用结果 |
|---|---|---|
| KuaiRec Big Retrieval Test | failed，永久保留且未重跑 | 无 Test 模型指标；事故见 retrieval_final_incident.md，未来代码路径的防复发加固见 RETRIEVAL_FINAL_REPAIR.md |
| KuaiRec Reserved small-matrix Test | not run | 依赖成功的 Big Retrieval report/checkpoint，因此未创建审计 |
| KuaiRec Ranking Test | complete | 1,820,563 行；complete-play NDCG@10 0.724157，LogLoss 0.527606 |
| KuaiRand-1K External Retrieval Final | complete | TRACE NDCG@10 0.39118；Single-interest 0.38531；delta +0.00587，95% CI [-0.00983, 0.02312] |
KuaiRec 的机器可读状态见 final_results_summary.json，审计可读汇总见 final_results_summary.md。失败的 Retrieval report 中 models 为空，不包含可引用 Test 指标。KuaiRand-1K 结果见 External Final Summary；它是独立外部评测证据，不是对 KuaiRec 失败审计的修复、重试或替代，也不是网页默认 serving 模型。
KuaiRec 2.0
|-- big_matrix: 偏置曝光日志
| |-- 自然日时间切分与严格历史快照
| |-- TRACE 全库召回
| |-- Balanced 约束重排
| `-- 多任务排序
|
`-- small_matrix: 近全观测敏感性视角
|-- anchor-train 拟合校准器
|-- anchor-dev 选择方法与正则
`-- reserved final-test 一次性评测
模型注册表 -> FastAPI -> 推荐工作台 / OpenAPI / 健康检查 / JSONL 日志
独立证据扩展：
Amazon ESCI -> BM25 / Dense / Pairwise LTR -> 固定 Test 报告
Criteo FairJob -> DeepFM / calibration / fairness audit -> 用户隔离 Test 报告
Hillstrom RCT -> ITT / uplift -> 历史随机实验报告
A/B dry run -> 稳定分桶 / 事件契约 / SRM / CUPED / MDE
四条公开数据证据 -> `/api/experiments/sgr` -> 搜广推证据工作台
详细设计见 ARCHITECTURE.md，数据和指标契约见 EXPERIMENT_PROTOCOL.md。
Python 要求为 3.10-3.12。原始数据不进入 Git；先按 data/raw/README.md 准备 KuaiRec 2.0，并核对 data/checksums.json。
快速开始只用于环境与 smoke 验证。完整的 Dev-only 重建顺序、三个正式种子、预计耗时和禁止事项见 DEV_REPRODUCTION.md；该流程不包含任何 finalizer 或保留集命令。
Windows：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev,serve]"
.\run_project.ps1 audit
.\run_project.ps1 test
.\run_project.ps1 prepare
.\run_project.ps1 retrieval-smoke
.\run_project.ps1 ranking-prepare
.\run_project.ps1 ranking-smoke
.\run_project.ps1 serve搜广推扩展的真实离线报告（数据文件保持在 .tmp，不进入 Git）：
python scripts\download_esci.py --source metarank-mirror
python scripts\run_esci_search.py --formal --data-source metarank-mirror --bootstrap-samples 1000
python scripts\download_fairjob.py
python scripts\run_fairjob_ads.py --formal --device cuda
python scripts\run_hillstrom_ab.py --formal
python scripts\run_ab_dry_run.pyLinux：
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e '.[dev,serve]'
bash ./run_project.sh audit
bash ./run_project.sh test
bash ./run_project.sh prepare
bash ./run_project.sh retrieval-smoke
bash ./run_project.sh ranking-prepare
bash ./run_project.sh ranking-smoke
bash ./run_project.sh serve服务默认运行在 http://127.0.0.1:8040，API 文档位于 http://127.0.0.1:8040/api/docs。完整演示路径、Docker 启动和页面说明见 DEMO.md。
推荐工作台默认使用“并排对比”，以同一用户、日期和 Top-K 分别执行 Raw TRACE 与 Balanced，再比较正式 ranker 后的最终 Top-K overlap、每侧替换项、共同项名次变化、冷物品数和兴趣路由覆盖。最终结果完全一致是合法分支，页面会解释自适应权重或共享 ranker 的影响。该诊断只描述一次请求，不是离线评测、全局 Coverage/Gini、显著性检验或线上收益。
项目一至三的知枢 AI 页面可提供项目四独立工作台导航，但两套系统没有数据、模型或请求调用链；项目四仍需在 8040 单独启动，不能描述为“四项目全链路”。
Docker Desktop 4.82.0 / Engine 29.6.1 已在 Windows + WSL2 上完成 trace-rec:v2.2.0 真实验收：镜像以 UID 10001 非 root 运行，从独立 ZIP 恢复目录启动的 release Compose 健康，真实 20 条推荐、MMoE 排序和第二次请求缓存均通过。证据见 deployment_v220_verification.json；旧版 deployment_verification.json 继续保留。Compose 默认只绑定 127.0.0.1；服务器部署时可显式设置 SHORTREC_BIND_HOST=0.0.0.0。
若只分发 Python wheel，页面静态资源会随 shortrec 包安装；配置、模型、处理后数据和报告仍应作为外部部署资产提供。将 SHORTREC_ROOT 指向包含 configs/、artifacts/、data/processed/ 和 reports/ 的部署目录，然后运行 shortrec-serve --device cpu。完整仓库启动脚本会自动使用仓库根目录，无需设置该变量。
最终 wheel 路径、SHA-256、隔离安装结果和部署边界见 RELEASE.md。跨电脑资产包、镜像导入和自动恢复流程见 DEPLOY_OTHER_MACHINE.md。
configs/ 实验、冻结配置与服务注册表
data/ 原始数据说明和本地处理产物
artifacts/ 本地 checkpoint 与逐用户结果，不进入 Git
reports/ 机器可读 JSON 和面试可读 Markdown 报告
scripts/ 数据、训练、评测、冻结和服务入口
src/shortrec/ 核心算法、评估、完整性与 serving 包
tests/ 单元、契约、泄漏防护和 API 测试
docs/ 架构、协议、部署与面试材料
references/ 固定版本的官方来源说明
- 官方归档 MD5 与固定来源 SHA-256 校验。
- 训练、Dev、Test 采用自然日边界；同日事件不会进入严格历史特征。
- Test 不参与模型、阈值、正则、重排权重或校准方法选择。
small_matrix缺失用户-物品对不会被补成负例。- inverse-popularity 权重仅称为因果启发式，不称为真实 propensity 或无偏 IPS。
- Caption/text 内容来自数据发布时的静态快照，实验假设其语义在上传时可获得；动态播放、点赞、评论等行为字段未作为静态内容使用。
- 置信区间包含 0 时不写“稳定提升”或“显著提升”。
- 最终 Test 审计记录一旦创建，即使执行失败也不允许静默重跑。
测试计数按时间和执行环境分层，不能互相替代：
- v2.2.0 Docker release：249/249 PASS（见 RELEASE.md，固定镜像/恢复资产环境）。
- post-release retrieval hardening candidate：263/263 PASS（历史候选快照，不是当前源码计数）。
- 历史 source-only 基线：348/348 PASS（当时工作树快照）。
- 当前 source-only 工作树：365/365 PASS，增加了 TRACE Dev attribution/verifier、safe incomplete-run resume、serving lifecycle reader/writer contract 与机器可读 evidence contract 测试。
当前回归覆盖 Raw/Balanced 最终 Top-K 配对诊断、Retrieval incident、防复发 cohort/AST/历史哈希门禁、External Final 冻结与完整性、E2E 级联、单调排序、 ANN、部署契约及推荐/激活并发安全。上述加固只保护未来代码路径，不改变历史 failed 状态。 推荐/激活 reader-writer lifecycle 的机器可读离线证据见 serving_lifecycle_evidence.json； 它验证并发契约，不声称线上流量、SLA 或跨进程 rollout 安全。
可直接引用、但必须携带评测范围的数字整理在 resume_metrics.md。推荐的项目描述、三分钟演示和常见追问见 RESUME_INTERVIEW.md。
项目代码采用 MIT License。KuaiRec 数据及派生数据遵循其原始许可，不由本项目重新授权。第三方研究参考、固定提交和许可边界见 THIRD_PARTY_NOTICES.md。