本文档描述推荐系统核心 API 的设计规范、请求格式与错误处理约定。适用于所有接入方。
[[toc]]
请求经过网关鉴权后进入推荐服务，从 Redis 读取实时特征，召回后送入排序模型，最终返回结果列表。
POST /v2/recommend根据用户 ID 和场景返回推荐列表，支持分页与过滤。
import requests
def get_recommendations(user_id: str, scene: str, top_k: int = 10):
url = "https://api.example.com/v2/recommend"
payload = {
"user_id": user_id,
"scene": scene,
"top_k": top_k,
"filters": {"category": "tech"}
}
resp = requests.post(url, json=payload,
headers={"Authorization": f"Bearer {TOKEN}"})
return resp.json()
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
item_id |
string | 推荐内容唯一 ID | "a1b2c3" |
score |
float | 模型置信度，范围 0–1 | 0.92 |
reason |
string | 推荐理由标签 | "热门内容" |
expires_at |
timestamp | 结果缓存失效时间 | 1732089600 |
最终排序分由三部分加权组成，其中相关性权重最高。
余弦相似度（行内公式）：\cos(\theta) = \frac{A \cdot B}
块级评分公式：
其中 为相关性得分， 为热门度， 为时效性衰减系数。
# .env — 不要提交到 Git
API_HOST=https://api.example.com
API_TOKEN=your_token_here
REDIS_URL=redis://localhost:6379/0
MODEL_VERSION=2.3
| 版本 | 日期 | 变更内容 |
|---|---|---|
| v2.3 | 2024-11-20 | 新增 filters 参数支持多维过滤 |
| v2.2 | 2024-09-05 | 排序模型升级，相关性提升 12% |
| v2.0 | 2024-06-01 | 重构接口，不兼容 v1.x |