60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
# 子模块：Integration（FastAPI API + Celery Worker）｜Spec
|
||
|
||
## 1. 目标描述
|
||
|
||
将推荐引擎对外暴露为两种调用方式，满足“API 与任务两者都需要”的集成要求：
|
||
|
||
- **FastAPI**：同步请求/响应式获取推荐结果（客户端直接请求）。
|
||
- **Celery**：后台任务式生成推荐（用于 Push/Widget 的定时或批处理）。
|
||
|
||
两种方式都必须调用同一套 `Reco Engine`，确保行为一致、便于回归测试。
|
||
|
||
---
|
||
|
||
## 2. 输入 / 输出定义
|
||
|
||
### 2.1 API 输入（HTTP Request）
|
||
|
||
- `scene`: `feed | push | widget`
|
||
- `k`（可选；默认按场景）
|
||
- `user_profile`（客户端问卷画像，V1.2）
|
||
- `already_recommended_ids`（数组）
|
||
- `touched_or_viewed_ids`（数组）
|
||
- （可选）`now`（用于可测试性；生产可不传，由服务端生成）
|
||
|
||
### 2.2 API 输出（HTTP Response）
|
||
|
||
- `items`: 推荐句子列表
|
||
- `meta`: RecoMeta（候选规模、回退层级、empty_reason 等）
|
||
|
||
### 2.3 Celery 任务输入/输出
|
||
|
||
任务输入与 API 输入等价，但建议仅传必要字段并保持 payload 小（避免 Redis 膨胀）：
|
||
|
||
- 允许只传 `user_profile` 与历史集合；若历史集合很大，建议传引用 ID（后续演进）。
|
||
|
||
任务输出：
|
||
|
||
- 可选择“不存结果”（默认忽略结果）并在任务内部将推荐结果写入下游（如消息队列/推送系统/DB）。
|
||
- 或返回 `items/meta`（仅用于开发调试）。
|
||
|
||
---
|
||
|
||
## 3. 关键约束
|
||
|
||
- API 与 Celery **不得复制推荐逻辑**：只能调用 `Reco Engine`。
|
||
- 输入合法性：
|
||
- 不因字段缺失而报错（画像允许缺失/跳过）。
|
||
- `already_recommended_ids/touched_or_viewed_ids` 允许为空数组。
|
||
- 可测试性：
|
||
- 允许注入 `now`（或在 header/参数中提供），便于确定性测试。
|
||
|
||
---
|
||
|
||
## 4. 验收标准（可验证）
|
||
|
||
- **API 可用**：给定合法请求体可返回推荐结果与 meta。
|
||
- **任务可用**：Celery worker 能消费任务并成功调用推荐引擎（至少跑通 ping → reco 的调用链）。
|
||
- **一致性**：相同输入下，API 与任务调用返回结果一致（忽略时间戳字段差异时）。
|
||
|