面向短视频信息流的多目标、去偏、全链路推荐系统项目。项目用于搜广推算法岗位作品集，覆盖真实曝光日志处理、向量召回、序列兴趣建模、多任务精排、随机曝光评测、约束重排、推理服务和交互式展示。
当前阶段：数据流水线、核心模型、强基线、三种子训练、完整候选评测、随机曝光评测、FAISS/FastAPI 和展示网站均已实现。网站可连接本地 FastAPI；API 不可用时只回退到明确标识的浏览器合成演示。证据页展示真实离线/本地结果，所有失败实验一并保留。
KuaiRand exposure logs
│
├─ Popular / ItemCF baseline
├─ Two-Tower + sampled softmax + logQ correction
│ └─ MBT-HSTU user encoder
│
└─ LR warm-start Wide + history features + factorized DCNv2/PLE residual
├─ engagement / long-view（最终主任务）
├─ like / follow / hate（保留诊断 head，最终 loss 权重为 0）
├─ validation-only stopping / calibration
└─ constrained MMR reranking
项目的序列前沿模块是 MBT-HSTU：基于 Meta HSTU 思想实现的轻量多行为时间感知序列编码器。每个历史 token 融合物品、行为向量、时间间隔和相对时间偏置，通过 SiLU pointwise attention 与门控聚合建模兴趣变化。最终精排则针对复杂模型弱于 LR 的问题，采用 LR 数值等价 warm-start + 零初始化深度残差 + 历史窗口统计 + task-specific user-item 因子交互。
这是 HSTU-inspired adaptation，不是 Meta 万亿参数生产系统或 M-FALCON 的复现。
KuaiRand 来自真实短视频推荐曝光日志，包含 12 类反馈、用户/视频特征和随机曝光数据。
主交付使用 KuaiRand-Pure：
- 27,285 个用户；
- 约 7,500 个随机候选池视频；
- 1,436,609 条标准曝光和 1,186,059 条随机曝光；
- 适合候选池内多任务建模与较少曝光偏差的独立评测。
KuaiRand-Pure 的标准行为序列经过候选池过滤，并不完整。因此项目不会把 Pure 实验描述为完整长序列推荐或全局无偏 OPE。
| 模块 | 实现 |
|---|---|
| 数据 | 官方 MD5 校验、Polars Lazy CSV→Parquet、固定日历切分、manifest、泄漏契约 |
| 召回 | Two-Tower、in-batch sampled softmax、logQ correction |
| 序列 | MBT-HSTU：行为 token、time-gap embedding、因果 mask、相对时间 bias |
| 精排 | LR warm-start Wide、因子化 DCNv2/PLE 残差、16 维 history-only 统计、双主任务 validation AUC 早停 |
| 去偏 | density-ratio 工具、SNIPS 权重、ESS；随机曝光独立测试协议 |
| 重排 | MMR、作者上限、类别上限、长尾 bonus、ILD/coverage |
| 服务 | FastAPI demo/trained 双模式、artifact SHA256、provenance、统一错误体 |
| 展示 | FastAPI 实时接入、API 状态/来源标识、浏览器合成 fallback、业务权重、多样性滑条、证据等级 |
- 完整 7,583 候选池、8,152 用户：ItemCF Recall@100 0.3373，MostPopular 0.2216（+52.2%）。
- 最终 LR warm-start 因子化 DCNv2/PLE 三种子：standard engagement/long-view AUC 0.7411±0.0015 / 0.7354±0.0011，相对稀疏 LR 分别提升 0.0050 / 0.0039；random-test AUC 提升 0.0151 / 0.0119。GAUC 与概率校准权衡见验证报告。
- 约束 MMR：ILD +1.20%、作者重复率 -23.0%，NDCG@20 -0.91%。
- 真实 7,583×128 item tower 向量的本地 FAISS IndexFlatIP：P95 0.211 ms，QPS 5,074。
- MBT-HSTU 未超过 ItemCF；RRF 融合在 validation 改善但锁定 test 下降 4.2%，未按 test 二次调参。
完整口径与失败分析见 docs/VERIFIED_RESULTS.md。
推荐使用已验证的 Conda 环境：Python 3.12 + PyTorch 2.11.0 CUDA 12.8。
.\scripts\setup_conda.ps1
conda activate flowrec-py312也可以从声明文件创建：
conda env create -f environment.yml
conda activate flowrec-py312当前开发机验证环境：RTX 5070 Ti Laptop GPU 12GB，CUDA compute capability 12.0。
下载脚本只使用官方 Zenodo 文件，并校验发布方 MD5：
.\scripts\download_kuairand.ps1
python -m flowrec.data --config configs/data/kuairand_pure.yaml固定时间切分：
- history：2022-04-08 至 2022-04-21；
- train：2022-04-22 至 2022-05-02；
- validation：2022-05-03 至 2022-05-05；
- test：2022-05-06 至 2022-05-08；
- standard 与 random 使用相同边界，random test 在最终评测前封存。
禁止进入模型的曝光后特征包括播放时长、评论区停留、作者主页停留和当前曝光标签。官方整月统计文件不会进入主实验，因为它会带来未来聚合泄漏。
先用真实 Parquet 做 GPU smoke test：
python -m flowrec.training retrieval --smoke `
--processed-dir data/processed/kuairand_pure `
--output-dir artifacts/retrieval_smoke `
--sample-limit 1024 `
--validation-sample-limit 256 `
--device cuda完整训练去掉 --smoke 和 sample limit。训练器支持 BF16、梯度累积、梯度裁剪、early stopping、best checkpoint 与带数据范围限制声明的 artifact metadata。
最终简历数字对应冻结配置 ranking_lr_factorized_history_low_lr.yaml，不是旧的五任务默认配置。完整流程包括：生成仅使用 history 窗口的 16 维特征、拟合 LR warm-start 产物、训练 3 个随机种子，并分别在 standard/random 锁定测试集评测。
.\scripts\run_final_ranking.ps1脚本执行时间较长。逐阶段调试时可按以下等价顺序运行单个种子：
python -m flowrec.training.history_features `
--config configs/training/history_features.yaml
python -m flowrec.evaluation.ranking_baseline_runner `
--config configs/evaluation/ranking_baseline.yaml
python -m flowrec.training ranking `
--processed-dir data/processed/kuairand_pure `
--output-dir artifacts/ranking_lr_factorized_history_low_lr_seed20260808 `
--config configs/training/ranking_lr_factorized_history_low_lr.yaml `
--train-sequence-features artifacts/ranking/history_features_v1/standard_train.npy `
--validation-sequence-features artifacts/ranking/history_features_v1/standard_validation.npy `
--device cuda `
--seed 20260808
python -m flowrec.evaluation.ranking_runner `
--config configs/evaluation/ranking_lr_factorized_history_final.yaml `
--checkpoint artifacts/ranking_lr_factorized_history_low_lr_seed20260808/best_ranking_model.pt `
--output artifacts/evaluation/ranking/lr_factorized_history_seed20260808_final.json `
--device cuda配置选择只能读取 validation。若需要复查选型阶段，使用 configs/evaluation/ranking_lr_factorized_history_validation.yaml 和 --validation-only；最终配置锁定后才运行上面的 final evaluation。种子固定为 20260808、42 和 3407，简历数字取三种子均值与标准差。
其他召回、重排强基线：
python -m flowrec.evaluation.retrieval_runner --max-users 0 `
--output artifacts/baselines/kuairand_pure_full.json
python -m flowrec.evaluation.reranking_runner `
--max-users 0 --output artifacts/evaluation/reranking_full.json默认模式使用确定性的合成用户/物品，只用于验证 API、前端接入和重排交互：
uvicorn flowrec.serving.app:app --host 127.0.0.1 --port 8000主要端点：
GET /api/v1/healthGET /api/v1/demo/usersPOST /api/v1/recommendPOST /api/v1/compareGET /api/v1/experiments（需要校验通过的 trained artifact）GET /docs
访问 GET /api/v1/health 可核对 configured_mode、实际 mode、artifact_ready 和数据集来源；所有响应还带有 X-FlowRec-Mode 与 request id。
trained serving 当前是 checksum-verified offline artifact replay，不会直接加载训练 checkpoint 或 FAISS index。它要求 artifacts/serving/ 中事先存在 schema 匹配且 SHA256 一致的：
artifact_manifest.jsoninference_payload.jsonevaluation_summary.json
仓库目前没有从 checkpoint 自动生成上述三件套的 exporter，因此请勿把现有 checkpoint/FAISS 产物描述成已接入在线推理。准备好合规产物后可显式启用严格 trained 模式：
$env:FLOWREC_SERVING_MODE = "trained"
$env:FLOWREC_SERVING_FALLBACK_TO_DEMO = "false"
$env:FLOWREC_SERVING_ARTIFACT_DIR = "artifacts/serving"
uvicorn flowrec.serving.app:app --host 127.0.0.1 --port 8000缺少或篡改 artifact 时严格模式启动失败；只有显式设置 FLOWREC_SERVING_FALLBACK_TO_DEMO=true 才会软降级，并在 health 中报告 status=degraded。configs/serving/*.yaml 是可由 ServingSettings.from_yaml() 显式加载的参考配置，直接运行全局 app 时以 FLOWREC_SERVING_* 环境变量为准。
先在终端一启动上面的本地 API，再在终端二配置前端地址：
npm ci
Copy-Item .env.example .env.local
npm run dev没有 lockfile 时才用 npm install 替代 npm ci。打开 http://localhost:3000 后，页面会展示 API 连接状态和响应 provenance：未配置或连接失败显示 LOCAL · SYNTHETIC；API 的 demo 模式显示 API · SYNTHETIC；仅当 trained + artifact_ready 且响应声明非合成时显示 API · OFFLINE ARTIFACT。后者仍是校验过的离线回放，不是实时模型推理或线上 A/B 结果。
展示端可以：
- 从 API 加载用户画像，或使用四种本地合成画像 fallback；
- 调整长播、点赞、关注和负反馈权重；
- 调节多样性强度与作者去重；
- 查看精排前排名、重排变化、召回来源和分数组成；
- 查看实验可信度、API 模式与模型边界声明。
公开部署时，只有另行部署 HTTPS FastAPI 才应在构建环境设置 VITE_FLOWREC_API_BASE_URL=https://<api-host>，并将网站的精确 HTTPS origin 加入 FLOWREC_SERVING_CORS_ORIGINS。该变量是公开的 build-time API 地址，不能存放密钥。若没有公网 API，公共站点保持静态/合成演示，真实数值仅来自冻结的离线证据页。
pytest tests_py -q
ruff check src tests_py
mypy src/flowrec
npm run build
node --test tests/rendered-html.test.mjsGPU smoke test 会实例化 MBT-HSTU 与 PLE，在 BF16 autocast 下完成前向和反向传播。发布验收要求 Python tests、Ruff、strict mypy、前端 lint/build/SSR 渲染全部通过；测试数量会随实现变化，以 CI/本地命令的最新输出为准。
- 召回：完整 eligible pool 上的 Recall@50/100、NDCG、MRR、catalog coverage；
- 排序：LogLoss、ROC-AUC、PR-AUC、GAUC、Brier、ECE；
- 稀疏任务：优先报告 PR-AUC、LogLoss 和 base rate；
- 重排：NDCG@20、ILD、类别/作者覆盖率、重复率、长尾覆盖；
- 最终模型：已报告 3 个随机种子的均值与样本标准差；只有补做 user-level paired bootstrap 95% CI 后才声称统计显著；
- 服务：本地实测 P50/P95/QPS，绝不写成线上生产指标。
可以写入简历：公开真实曝光日志、候选池内召回、多目标排序、随机曝光独立评测、本地服务压测。
不能写入简历：线上 CTR 提升、A/B 实验、生产部署、完全消除曝光偏差、亿级训练、已知 propensity 的无偏 IPS。
建议跟踪源码、测试、配置、脚本、文档、前端资源、environment.yml、pyproject.toml、package-lock.json、.env.example 与 artifacts/.gitkeep。以下内容由 .gitignore 阻止进入公开仓库：
- KuaiRand 原始/中间/处理后数据；
- checkpoint、pickle、NumPy、Parquet 与下载压缩包；
artifacts/实验产物、MLflow/outputs；- Conda/venv、Python/Node 缓存、构建目录和真实
.env.*。
发布前执行：
git status --short
git diff --check
git ls-files | Select-String -Pattern "(^|/)(data/(raw|interim|processed)|artifacts/.+|\.env(\.|$))"
pytest tests_py -q
ruff check src tests_py
mypy src/flowrec
npm run lint
npm testgit ls-files 的检查只应命中 artifacts/.gitkeep 或 .env.example（若正则覆盖到它）；不得提交真实数据、模型权重、服务 artifact 或密钥。公开发布还应补齐与 pyproject.toml 中 MIT 声明一致的 LICENSE，再创建版本化 commit/tag。当前本地微基准和离线指标可随文档发布，不能随代码发布被描述为云端生产压测或线上收益。