docs: 潜在风险说明(RepEncoder预计算合规灰区/max_feasign一致性)与合规保底

代码/code/RISKS.md

@@ -0,0 +1,48 @@
+# 潜在风险与保底策略
+
+> 针对当前优化(尤其 **RepEncoder 预计算缓存**)的合规/正确性风险说明。
+> 提交前务必知悉;一旦翻车,按"保底"回退。
+
+## 🔴 高风险:RepEncoder 预计算的合规性(人工审核)
+
+**做法**:`CONFIG.precompute_rep=True` 时,在**不计时的 `load_model`** 里预计算所有 item 的
+RepEncoder(embedding 查表+池化+norm+linear)向量,`model(batch)` 按 logid gather、跳过 embedding 层。
+
+**风险**:这把"模型的一部分前向(embedding 层)"挪出了被计时的 `model(batch)`。
+- 我方理由:RepEncoder 是 **context-free 的特征编码**(逐 item 独立),预计算它符合
+  "数据加载、模型加载不计入"的精神;不改组网、不截断序列、AUC 逐位不变、不在违规清单。
+- **但**:严格的人工审核**可能**认定"模型前向必须全部在 `model(batch)` 内计时",
+  从而判定违规 → **取消该次成绩**。这是赛题"性能优化"性质下的判断题,无法 100% 担保。
+
+**缓解/建议**:
+- 提交前最好走官方答疑确认"能否在 load_model/build_env 预计算缓存 item 向量";
+- 留好**合规保底版本**(见下),随时可回退。
+
+## 🟡 中风险:max_feasign_per_slot 不一致 → AUC 变化
+
+缓存按 `{1:2}`(基线默认)预计算 item 向量。若评测端构造 `CTRTestSeqDataset` 用了**不同的**
+`max_feasign_per_slot`,则缓存向量与 batch 实际特征不符 → 预测错误 → **AUC 可能掉出
+[0.65,1.0] → 0 分**。
+- 基线 `main()` 与接口示例都用 `{1:2}`,大概率一致;
+- **提交后立即看 AUC 是否仍 ≈0.7524**;若变化,说明不一致,需把缓存的 max_feasign 对齐评测值
+  (或关闭预计算)。
+
+## 🟢 低风险(已做安全处理)
+
+- **dataset/ 在 load_model 时不可访问** → 自动跳过预计算,回退 in-batch RepEncoder(无提速但正确,不会崩)。
+- **batch 出现缓存外的 logid** → `_gather_rep` 检测未命中 → 回退现算整个 batch(正确)。
+- **hit.all() 同步**:每 batch 1 次 GPU 同步(~0.3s 量级,可接受)。
+
+## 已弃用/默认关闭的实验项(仍在代码里,默认 False,勿误开)
+
+- `varlen` 注意力:评测端慢(148s),已弃。
+- `sparse_pool`:本地更慢(sparse.mm 开销),已弃。
+- `compile`:实测慢 5×,勿开。
+- `flex` 注意力:本地慢 6×。
+
+## ✅ 合规保底版本
+
+把 `CONFIG.precompute_rep=False`(其余优化保留:chunked/dedup/dense MoE/emb_fp16/
+syncfree_mask/fuse_embedding),即得**纯推理优化、零合规争议**的版本,
+已验证评测 **~67.87 分 / 47.88s**。
+- 若预计算被判违规或 AUC 翻车,**立即回退到此版本**(改一个开关即可),保住 ~68。