recommendations

推荐

通过 TasteRay API 提供个性化推荐。

目标

在进行推荐或审查与推荐相关的代码时——无论是 API 集成、上下文构建，还是呈现逻辑——你的目标是达到 10/10 的评分。

根据对本技能中原则和技巧的遵循程度，以 0-10 分为所有工作评分。以 X/10 的形式给出你的评估，并具体说明哪些做得好、哪些需要改进才能达到 10/10。

10/10 意味着工作：

• 体现核心原则（理解先于推荐）
• 在调用 API 之前构建丰富的上下文
• 以个性化解释呈现推荐
• 优雅地处理边缘情况（低置信度、速率限制、错误）
• 避免所有反模式

持续迭代，直到达到 10/10。

---

核心原则

理解先于推荐。

出色的推荐源于对一个人的深入了解——他们的偏好、约束、历史和上下文。在从对话中构建有意义的上下文之前，绝不要调用 API。

关键洞察：推荐的质量取决于为其提供依据的上下文。

---

API 概览

TasteRay 推荐 API 在多个垂直领域提供个性化推荐。

基础 URL

https://api.tasteray.com

身份验证

所有请求都需要在请求头中携带 API 密钥：

X-API-Key: your-api-key

核心端点

端点	方法	描述
/v1/recommend	POST	获取个性化推荐
/v1/explain	POST	获取单个条目的详细解释
/v1/usage	GET	查看配额和使用统计信息

参见：API 参考

---

推荐流程

每次推荐都遵循以下模式：

1. Build context from conversation
   ↓
2. Call POST /v1/recommend
   ↓
3. Interpret confidence scores
   ↓
4. Present with personalized explanations
   ↓
5. Iterate based on feedback

步骤 1：构建上下文

从对话中提取：

• preferences：明确的喜好/厌恶和品味模式
• profile：心理画像文本（来自 elicitation 技能）
• constraints：硬性要求（预算、饮食、地点等）
• history：他们过去喜欢或不喜欢的内容

步骤 2：调用 API

POST /v1/recommend
{
  "vertical": "movies",
  "context": {
    "preferences": ["dark comedies", "complex characters"],
    "profile": "Values authenticity and depth. Drawn to stories about outsiders...",
    "constraints": {"max_length_minutes": 120},
    "history": [
      {"item": "Parasite", "rating": 5},
      {"item": "The Lobster", "rating": 4}
    ]
  },
  "count": 5
}

步骤 3：解读置信度

分数	含义	操作
0.9+	高度匹配	以此作为首要推荐
0.7-0.9	良好匹配	自信地呈现
0.5-0.7	中度匹配	加入注意事项，解释为何可能不适合
<0.5	弱匹配	省略，或解释存在显著不确定性

步骤 4：呈现推荐

不要只是列出条目。让解释个性化：

差：

"根据你的偏好，我推荐《寄生虫》。"

好：

"鉴于你对角色复杂的黑色喜剧的喜爱，《寄生虫》会是一个强有力的选择。它带有你在《龙虾》中产生共鸣的那种局外人视角，但社会批判更加犀利。"

步骤 5：迭代

利用反馈进行优化：

• "不太对" → 询问缺少了什么
• "多讲讲 X" → 调用 /v1/explain
• "来点不一样的" → 调整约束条件并重新查询

---

上下文构建

推荐的质量完全取决于上下文的质量。

Preferences 数组

从对话中提取的明确品味陈述：

"preferences": [
  "dark comedies",
  "complex anti-heroes",
  "slow-burn narratives",
  "dislikes: jump scares",
  "dislikes: predictable endings"
]

提取模式：

• "我喜欢 X" → 正面偏好
• "我受不了 X" → 负面偏好（加上前缀 "dislikes:"）
• "类似 X 的东西" → 参照点
• "不要太 X" → 约束条件或负面偏好

Profile 文本

自由形式的心理画像。如果使用 elicitation 技能，请总结发现：

"profile": "Values authenticity over polish. Drawn to outsider narratives
and stories about people who don't fit in. Appreciates moral ambiguity
and complex characters who aren't clearly good or bad. Responds strongly
to themes of class and social hierarchy. Prefers films that trust the
audience's intelligence."

约束对象

用于筛选推荐的硬性要求：

领域	常见约束
电影	max_length_minutes、release_year_min、exclude_genres
餐厅	cuisine、price_range、location、dietary
产品	max_price、category、brand_exclude
旅行	budget、dates、accessibility、interests
职位	location、salary_min、remote、experience_level

历史记录数组

带有评分（1-5 分制）的过往条目：

"history": [
  {"item": "The Grand Budapest Hotel", "rating": 5},
  {"item": "Transformers", "rating": 1},
  {"item": "Moonlight", "rating": 4}
]

准则：

• 同时包含正面和负面示例
• 最多 50 个条目（API 限制）
• 越近期的条目权重越高
• 在可用时包含条目标识符（IMDB ID 等）

参见：上下文模式参考

---

各领域专属模式

电影与电视

关键上下文信号：

• 类型偏好（以及反偏好）
• 节奏偏好（慢热 vs. 动作密集）
• 年代偏好（经典、现代、当代）
• 语言/字幕接受度
• 他们寻求的情绪氛围

约束示例：

{
  "max_length_minutes": 120,
  "release_year_min": 2010,
  "exclude_genres": ["horror", "musical"],
  "languages": ["en", "fr"],
  "streaming_services": ["netflix", "hulu"]
}

餐厅

关键上下文信号：

• 菜系偏好与尝鲜意愿
• 价格敏感度
• 饮食限制（必须准确捕捉）
• 场合背景（约会之夜、商务、休闲）
• 氛围偏好

约束示例：

{
  "location": {"lat": 37.7749, "lng": -122.4194, "radius_miles": 5},
  "price_range": [2, 3],
  "dietary": ["vegetarian-options"],
  "open_now": true
}

产品

关键上下文信号：

• 使用场景与背景
• 质量与价格的权衡
• 品牌偏好与厌恶
• 功能优先级
• 审美偏好

约束示例：

{
  "max_price": 500,
  "category": "headphones",
  "brand_exclude": ["beats"],
  "features_required": ["noise-cancelling", "wireless"]
}

旅行

关键上下文信号：

• 旅行风格（冒险、放松、文化）
• 对陌生事物的适应程度
• 活动偏好
• 社交背景（独自、情侣、家庭）
• 过往目的地（喜欢和不喜欢）

约束示例：

{
  "budget_per_day": 200,
  "dates": {"start": "2024-06-01", "end": "2024-06-14"},
  "accessibility": ["wheelchair-accessible"],
  "climate": "warm",
  "visa_free_for": "US"
}

职位

关键上下文信号：

• 职业价值观与优先级
• 工作风格偏好
• 成长导向 vs. 稳定导向
• 文化契合信号
• 技能与经验水平

约束示例：

{
  "location": "San Francisco",
  "remote": "hybrid",
  "salary_min": 150000,
  "experience_level": "senior",
  "company_size": ["startup", "mid"]
}

---

呈现模式

你如何呈现推荐，与推荐什么同样重要。

基于置信度的呈现

高置信度（0.9+）：

"这对你来说非常匹配。[Item] 与你对 [specific trait] 的偏好高度一致。"

良好置信度（0.7-0.9）：

"[Item] 应该会很合适。它具有 [positive trait]，不过它 [caveat]，可能不完全是你在找的。"

中等置信度（0.5-0.7）：

"这个有点冒险，但 [Item] 可能会让你惊喜。它 [trait]，你虽然没有明确提到，但基于 [pattern]，你可能会喜欢。"

低置信度（<0.5）：

通常省略，或者说："如果你想冒险，[Item] 与你通常的偏好相当不同，但 [reason for including]。"

解释结构

对每条推荐，解释：

1. 匹配点 - 为什么它符合他们陈述的偏好
2. 关联 - 它与他们喜欢的条目有何关联
3. 注意事项 - 任何潜在的不匹配（如适用）

处理反馈

"告诉我更多" → 使用 /v1/explain 端点：

POST /v1/explain
{
  "vertical": "movies",
  "item": "Parasite",
  "context": { /* same context */ }
}

"不太对" → 提出澄清问题：

"那条推荐哪里没中？太 [X]？不够 [Y]？"

"来点完全不同的" → 调整方式：

"让我换个角度试试。如果我们抛开 [previous focus]，你现在到底想要什么？"

参见：呈现模式参考

---

与启发式引导的集成

启发式引导技能会构建心理画像。使用这些来提供更丰富的推荐。

从启发到画像

自我定义记忆揭示：

• 塑造品味的关键经历
• 在内容中引发共鸣的情绪模式
• 身份主题（能动性、共融、救赎）

价值观启发揭示：

• 应体现在推荐中的核心优先事项
• 是什么让某件事感觉“对”

图式检测揭示：

• 可能影响接受度的模式
• 需要谨慎处理的话题或主题

画像构建

启发之后，构建一个画像字符串：

"profile": "Core value: authenticity. Drawn to narratives about
self-reinvention (redemption themes in life story). Responds to
understated emotion over melodrama. Achievement-oriented but values
creative expression over status markers. Formative memory involves
finding belonging through shared creative work—look for collaborative
or community themes."

集成示例

1. 使用启发技能来理解这个人
2. 在画像文本中总结发现
3. 携带丰富上下文调用推荐 API
4. 呈现与其故事相连接的推荐

---

错误处理

速率限制

当超出限制时，API 会返回 429 Too Many Requests。

层级	请求数/分钟	请求数/天
免费	10	100
Pro	60	5,000
企业	300	无限制

处理方式：

• 检查 Retry-After 头以获取等待时间
• 如果达到限制，则将请求排队
• 考虑缓存频繁查询

认证错误

401 Unauthorized - API key 无效或缺失。

处理方式：

• 验证 API key 是否设置正确
• 检查 key 是否已过期
• 确保 key 具有适当的权限

服务器错误

500+ - 服务器端问题。

处理方式：

• 实现指数退避
• 具备回退行为（优雅降级）
• 记录日志以便调试

参见：API Reference 获取完整错误代码。

---

反模式

不要做的事：

空上下文调用

在未先构建上下文的情况下调用 API。

相反：在请求推荐之前，始终收集偏好、约束和历史记录。

原始转储

直接呈现 API 响应而不进行个性化。

相反：解读置信度分数，并构建与用户所述偏好相连接的解释。

过度自信的低分

将弱匹配（置信度 < 0.5）与强匹配以同样的自信程度呈现。

相反：要么省略低置信度推荐，要么明确说明其注意事项。

被忽略的约束

遗漏或记错已说明的约束（预算、饮食等）。

相反：明确捕获约束，并在每次 API 调用前验证。

上下文失忆

未在对话轮次之间保持上下文。

相反：在整个对话过程中累积偏好、历史和约束。

解释真空

只推荐而不解释原因。

相反：每条推荐都应包含与所述偏好相连接的个性化解释。

忽略反馈

未使用负面反馈来改进后续推荐。

相反：当某件事不理想时，询问哪里出了问题，并相应地调整上下文。

---

参考资料

详细指南：

• API Reference - 完整端点文档、参数、响应
• Context Patterns - 构建有效的推荐上下文
• Presentation Patterns - 置信度解读、解释结构

---

快速参考

最小可行请求

POST /v1/recommend
Headers: X-API-Key: your-key

{
  "vertical": "movies",
  "context": {
    "preferences": ["at least one preference"]
  },
  "count": 5
}

完整请求

POST /v1/recommend
{
  "vertical": "movies",
  "context": {
    "preferences": ["dark comedies", "complex characters"],
    "profile": "Values authenticity. Drawn to outsider narratives...",
    "constraints": {
      "max_length_minutes": 120,
      "release_year_min": 2010
    },
    "history": [
      {"item": "Parasite", "rating": 5, "id": "tt6751668"},
      {"item": "The Lobster", "rating": 4, "id": "tt3464902"}
    ]
  },
  "count": 5,
  "explain": true
}

置信度快速指南

分数	操作
≥0.9	作为主要推荐，强匹配
0.7-0.9	有把握地纳入
0.5-0.7	附带注意事项纳入
<0.5	省略或大量附加注意事项