46 lines
1.4 KiB
Markdown
46 lines
1.4 KiB
Markdown
# 子模块：Observability（可观测性与打点载荷）｜Spec
|
||
|
||
## 1. 目标描述
|
||
|
||
定义推荐模块的统一可观测载荷（meta/event），用于：
|
||
|
||
- 线上监控覆盖率、回退率、候选规模分布、过滤原因分布。
|
||
- 支撑调参（权重/回退阈值/频控窗口）与风险排查（Hard Filter 命中情况）。
|
||
|
||
---
|
||
|
||
## 2. 输入 / 输出定义
|
||
|
||
### 2.1 输入
|
||
|
||
- 推荐引擎内部各阶段统计信息：
|
||
- 候选生成数量、过滤后数量、去重后数量、频控后数量
|
||
- 回退层级与触发原因
|
||
- served_k
|
||
- 缺失字段情况、conf_U
|
||
|
||
### 2.2 输出
|
||
|
||
统一的 `RecoMeta`（返回给调用方；调用方负责上报/落库/打点）：
|
||
|
||
- `scene`
|
||
- `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 必填；枚举建议：`hard_filter_all | freqcap_all | pool_empty | unknown`）
|
||
- `conf_U`
|
||
- `missing_fields`：`{ need: boolean; context: boolean; emotion: boolean }`
|
||
- （可选）`risk_filtered_count_by_flag`：`{ flag: count }`
|
||
|
||
---
|
||
|
||
## 3. 验收标准（可验证）
|
||
|
||
- 每次推荐调用都能产出 `RecoMeta`，并随响应/任务结果返回（或被上层打点系统消费）。
|
||
- `served_k=0` 时 `empty_reason` 必不为空，且与实际清空阶段一致。
|
||
- `fallback_level_final` 能真实反映最终回退层级（用于回退率报表）。
|
||
|