173 lines
7.2 KiB
Markdown
173 lines
7.2 KiB
Markdown
# Rerank & Freqcap（重排 / 去重 / 频控）｜Tasks
|
||
|
||
> 对应计划：`spec_kit/Personalized Reco/modules/rerank-freqcap/plan.md`
|
||
>
|
||
> 本清单执行原则：
|
||
>
|
||
> - 本模块只做 **Dedup / Freqcap / Feed MMR 重排**，不做 Soft Scoring 与 Hard Filter。
|
||
> - V1 冷却窗口以“输入集合代表窗口内历史”为准（后续接入服务端历史再按天计算）。
|
||
|
||
---
|
||
|
||
## 0. 任务标记规则
|
||
|
||
- 用勾选框标记执行状态：
|
||
- `[ ]` 未开始
|
||
- `[x]` 已完成
|
||
- 每个任务都要求可独立验收（有明确产出/可运行的检查方式）。
|
||
|
||
---
|
||
|
||
## 1. 文档对齐（先把口径写死，避免实现漂移）
|
||
|
||
- [x] 1.1 校对 `modules/rerank-freqcap/spec.md` 与 `modules/rerank-freqcap/plan.md` 一致性
|
||
- **检查点**：
|
||
- 输入：`scene/scored_candidates/history/k/config` 字段与命名一致
|
||
- 输出：`ranked_items` 与 `meta` 字段集合一致
|
||
- 去重键：`sentence_key=content_id`、`author_key`、`template_key` 口径一致
|
||
- Feed：MMR λ=0.7 与 Sim 规则一致
|
||
- **验收**：两份文档不存在冲突描述，且“V1 冷却窗口语义”写清楚（集合代表窗口内历史）。
|
||
|
||
- [x] 1.2 在 `plan.md` 中补充/固定“标签构造策略”与“候选截断策略”（若后续要改再更新）
|
||
- **变更点**：
|
||
- 明确 `tags` 的 V1 定义：`stage + need_argmax + context_argmax`
|
||
- 明确 `top_n_for_mmr` 默认值与作用（性能兜底）
|
||
- **验收**：实现时不会出现“标签到底取哪些 key”的二义性。
|
||
|
||
---
|
||
|
||
## 2. 目录与骨架（与推荐子模块同级）
|
||
|
||
- [x] 2.1 新建目录 `server/app/features/personalized_reco/rerank_freqcap/`
|
||
- **包含**：
|
||
- `__init__.py`
|
||
- `types.py`（`ScoredCandidate`、`RerankConfig`、`RerankMeta`、`RerankResult`）
|
||
- `defaults.py`（按 scene 的默认参数：λ、cooldown_*、top_n_for_mmr）
|
||
- `utils.py`（ID 归一化、Jaccard、tag 构造等）
|
||
- `rerank.py`（主入口 `rerank_and_freqcap`）
|
||
- **验收**：可通过 `app.features.personalized_reco.rerank_freqcap.*` 正常 import。
|
||
|
||
---
|
||
|
||
## 3. 类型与接口（稳定契约，便于 reco-engine 调用）
|
||
|
||
- [x] 3.1 定义 `ScoredCandidate`（最小字段集合）
|
||
- **必须字段**：
|
||
- `content_id: int`
|
||
- `final_score: float`
|
||
- **建议字段**（用于多样性/频控）：
|
||
- `author_id: str | None`
|
||
- `template_id: str | None`
|
||
- `content_profile`（至少能取到 stage/need_suitability/context_suitability；缺失时需降级）
|
||
- **验收**：能承载 MMR 相似度计算所需数据；缺失字段不会导致异常。
|
||
|
||
- [x] 3.2 定义 `RerankConfig`（可调参）
|
||
- **字段**：
|
||
- Feed：`mmr_lambda`（默认 0.7）、`top_n_for_mmr`（默认 200）
|
||
- Push/Widget：`cooldown_sentence_days/cooldown_author_days/cooldown_template_days`（用于配置与可观测）
|
||
- **验收**：能从 scene 推导默认 config（或由调用方传入覆盖）。
|
||
|
||
- [x] 3.3 定义 `RerankMeta` 与 `RerankResult`
|
||
- **meta 必须字段**：
|
||
- `candidate_pool_size_after_dedup`
|
||
- `candidate_pool_size_after_freqcap`
|
||
- `missing_history_fields`
|
||
- **建议字段**：
|
||
- `freqcap_filtered_counts`（sentence/author/template）
|
||
- **验收**：字段集合固定；任何输入都能产出 meta（包括候选为空）。
|
||
|
||
---
|
||
|
||
## 4. 核心算法实现（V1 最小集合）
|
||
|
||
- [x] 4.1 实现历史 ID 归一化（避免 str/int 混用漏过滤）
|
||
- **规则**：
|
||
- `already_recommended_ids` / `touched_or_viewed_ids` 尽量转为 `int` 集合
|
||
- 转换失败的值忽略并记录 debug
|
||
- **验收**：单测覆盖 `["1", 2, "bad"]` 等混合输入，过滤结果正确且稳定。
|
||
|
||
- [x] 4.2 实现 Dedup（必做）
|
||
- **规则**：过滤 `content_id ∈ seen_ids` 的候选
|
||
- **产出**：`meta.candidate_pool_size_after_dedup`
|
||
- **验收**：输出不包含历史出现过的 `content_id`。
|
||
|
||
- [x] 4.3 实现 Freqcap（Push/Widget 必做；Feed 可选）
|
||
- **V1 策略**：
|
||
- 句子维度（必做）：同句硬过滤（使用 dedup 的 seen_ids 即可）
|
||
- 作者/模板维度（增强项）：
|
||
- 若提供 `recent_author_ids`：命中则硬过滤；否则在 `missing_history_fields` 记录 `author`
|
||
- 若提供 `recent_template_ids`：命中则硬过滤；否则在 `missing_history_fields` 记录 `template`
|
||
- **产出**：
|
||
- `candidate_pool_size_after_freqcap`
|
||
- `freqcap_filtered_counts`（建议）
|
||
- **验收**：在有/无 `recent_*_ids` 输入时行为一致且可解释。
|
||
|
||
- [x] 4.4 实现 Feed：tag 构造与相似度 `Sim`
|
||
- **tag 规则（V1 写死）**：
|
||
- `stage:<stage>`
|
||
- `need:<argmax_key>`（从 `need_suitability` 取最大值 key；为空则跳过）
|
||
- `context:<argmax_key>`（从 `context_suitability` 取最大值 key；为空则跳过）
|
||
- **Jaccard**：`|A∩B|/|A∪B|`，空集合时返回 0
|
||
- **Sim 累加规则**：
|
||
- 同 content_id → 1
|
||
- template_id 相同且非空 → +0.6
|
||
- author_id 相同且非空 → +0.3
|
||
- +0.1 * Jaccard(tags)
|
||
- clamp 到 `[0,1]`
|
||
- **验收**：单测覆盖缺失字段（无 author/template/tags）时仍能算出稳定 Sim。
|
||
|
||
- [x] 4.5 实现 Feed：MMR 选序列
|
||
- **规则**：
|
||
- Top1：按 `final_score` 最大
|
||
- 后续：按 `MMR(c)=λ*Rel(c)-(1-λ)*maxSim` 选择
|
||
- `Rel=final_score`
|
||
- **性能兜底**：先截断候选到 `top_n_for_mmr` 再做 MMR
|
||
- **验收**：
|
||
- Top1 恒等于最高分
|
||
- 候选足够时，序列不出现大量同作者/同模板紧邻重复（可用阈值断言）
|
||
|
||
- [x] 4.6 实现 Push/Widget：最终 TopK
|
||
- **规则**：dedup+freqcap 后按 `final_score` 降序取前 k 条
|
||
- **验收**：输出长度 ≤ k，且分数单调不增（允许相等）。
|
||
|
||
- [x] 4.7 实现主入口 `rerank_and_freqcap(...) -> RerankResult`
|
||
- **规则**：
|
||
- 三场景共用 dedup
|
||
- Feed：MMR；Push/Widget：TopK
|
||
- 必须输出 meta（即使 ranked_items 为空）
|
||
- **验收**：任何输入（含空候选）不抛异常，并输出稳定结构。
|
||
|
||
---
|
||
|
||
## 5. 单元测试（pytest，纯函数为主）
|
||
|
||
- [x] 5.1 新建测试文件 `server/tests/test_rerank_freqcap.py`
|
||
- **用例覆盖**：
|
||
- dedup：历史集合过滤正确（含 str/int 混用）
|
||
- freqcap：有/无 recent_author/template 的分支与 meta 缺失标记
|
||
- feed mmr：Top1=最高分；后续避免同作者/模板紧邻（构造数据断言）
|
||
- push/widget：TopK 输出正确
|
||
- **验收**：`pytest -q tests/test_rerank_freqcap.py` 通过。
|
||
|
||
---
|
||
|
||
## 6. 最终自检清单（合入前）
|
||
|
||
- [x] 6.1 文档一致性检查
|
||
- **验收**：`spec.md` / `plan.md` / 实现接口签名三者一致（尤其 meta 字段与默认参数）。
|
||
|
||
- [x] 6.2 回归检查（不影响已实施模块）
|
||
- **验收**：不修改 `content-repository` 与 `scoring` 的既有逻辑；仅新增 `rerank-freqcap` 模块与测试。
|
||
|
||
- [x] 6.3 全量测试通过
|
||
- **命令**（在 `server/`）：
|
||
- `pytest -q`
|
||
- **验收**：所有用例通过。
|
||
|
||
- [x] 6.4 全部完成后更新大规范 `overview.md`
|
||
- **变更点**：
|
||
- 将 `modules/rerank-freqcap/` 标记为“已实施”
|
||
- 增加一条变更记录（日期 + 交付物：plan/tasks/代码/测试）
|
||
- **验收**：`spec_kit/Personalized Reco/overview.md` 中模块状态与交付记录准确。
|
||
|