82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 子模块：Reco Engine（推荐引擎编排）｜Spec
|
||
|
||
## 1. 目标描述
|
||
|
||
实现推荐的主编排器（Orchestrator）：
|
||
|
||
- 输入用户画像 + 历史集合 + 场景参数。
|
||
- 调用 `Content Repository` 拉取候选。
|
||
- 执行统一 Pipeline：Candidate → Hard Filter → Soft Scoring → Rerank/Freqcap → Fallback Ladder。
|
||
- 输出推荐句子与 `meta`（可观测字段），供 API 或 Celery 上层直接下发。
|
||
|
||
---
|
||
|
||
## 2. 输入 / 输出定义
|
||
|
||
### 2.1 输入
|
||
|
||
- `scene`: `feed | push | widget`
|
||
- `user_profile`: 客户端问卷画像（V1.2）
|
||
- `already_recommended_ids`: `List[str|int]`
|
||
- `touched_or_viewed_ids`: `List[str|int]`
|
||
- `k`: int（feed 默认 30；push/widget 默认 1）
|
||
- `now`: 时间戳
|
||
- （可选）`constraints`：黑名单 author/template、最大候选量上限等
|
||
|
||
### 2.2 输出
|
||
|
||
- `items: List[RecommendedItem]`（长度 ≤ k）
|
||
- `content_id`、`text`、`final_score`
|
||
- `fallback_level_final`
|
||
- `explanations`（可选，便于调参/排查）
|
||
- `meta: RecoMeta`
|
||
- `candidate_pool_size_raw`
|
||
- `candidate_pool_size_after_hard_filter`
|
||
- `candidate_pool_size_after_dedup`
|
||
- `candidate_pool_size_after_freqcap`
|
||
- `fallback_level_final`
|
||
- `served_k`
|
||
- `empty_reason`（served_k=0 必填）
|
||
- `missing_fields`（need/context/emotion 的缺失情况）
|
||
- `scene`、`conf_U`
|
||
|
||
---
|
||
|
||
## 3. 缺失字段判定（必须与客户端契约一致）
|
||
|
||
- `U.need` 为空对象 `{}` 或不存在 → 视为缺失
|
||
- `U.context` 为空对象 `{}` 或不存在 → 视为缺失
|
||
- `U.emotion_score` 为 `null`/不存在 → 视为缺失
|
||
|
||
当缺失明显或 `conf_U` 偏低时：
|
||
|
||
- Push：必须启用不确定性惩罚 `P_uncertainty`，并自动降个性化（限制 `personalization_power` 上限）。
|
||
- 任意场景：候选生成至少按 **L1** 处理（降个性化，增加通用安全占比）。
|
||
|
||
---
|
||
|
||
## 4. Fallback Ladder（回退梯度，必须实现）
|
||
|
||
- L0：正常召回配比
|
||
- L1：放宽匹配 + `personalization_power ≤ 0.5`
|
||
- L2：回退通用池 + `personalization_power = 0`
|
||
- L3：仅安全池（白名单/安全池）
|
||
|
||
触发条件（任一满足即可回退）：
|
||
|
||
- 候选池为空 / Hard Filter 清空 / 去重清空 / 频控清空
|
||
- served_k < k（feed 可允许部分不足，但需记录并可继续回退补齐，具体由实现配置）
|
||
|
||
每次回退必须更新 meta 中的候选规模与触发原因。
|
||
|
||
---
|
||
|
||
## 5. 验收标准（可验证）
|
||
|
||
- **稳定性**：任意输入（包括画像字段缺失、历史集合为空/很大）不报错，返回结构稳定。
|
||
- **回退可观测**：当候选不足时能逐级回退，且 `fallback_level_final` 与 `empty_reason` 正确。
|
||
- **去重生效**：输出不包含 `already_recommended_ids` 与 `touched_or_viewed_ids` 中的 content_id。
|
||
- **风险优先**：Hard Filter 始终优先执行（尤其 `block_health_medical` 必挡）。
|
||
- **跨调用复用**：同一引擎既可被 FastAPI API 调用，也可被 Celery 任务调用（无框架耦合）。
|
||
|