# 14 - 推荐系统与 LLM 接入

OrangeRadio 的推荐采用"本地画像 + 上下文感知 + 可选 LLM 增强"的分层设计，数据始终保留在本地，保护隐私。

## 推荐系统分层

```
用户触发推荐
  │
  ▼
本地画像打分
  • 最近播放历史（听完/跳过/完整播放）
  • 偏好艺人、流派、BPM 区间
  • 当前时段与情绪场景
  │
  ▼
取 Top-N 候选
  │
  ▼
可选 LLM 语义重排（需自行配置 API Key）
  • 把画像 + 候选 + 场景交给 LLM
  • LLM 从候选里选 1 首最契合当前情绪的歌曲
  • 失败/未配置 → 回退本地打分 Top1
```

## 本地画像

- **播放行为**：完整听完、提前跳过、播放时长等，作为正负反馈。
- **BPM 偏好**：优先读取歌曲元数据中的 BPM，缺失时由本地音频分析补全。
- **时段/情绪**：根据当前时段和用户在"懂你模式"中选择的情绪标签，优先推荐匹配的歌曲。

## LLM 增强（可选）

- 支持 OpenAI 兼容协议（GLM、DeepSeek、通义千问等）和 MiniMax 类协议。
- API Key 仅保存在本地浏览器存储中，不经过服务器，也不提交到任何第三方服务之外。
- 未配置 LLM 时，推荐完全离线运行，仅依赖本地画像打分。

## 隐私说明

- 推荐计算完全在本地 Rust 层完成。
- 播放历史、画像数据、LLM 配置均存储在本地，不上传云端。
- 仅当用户主动配置 LLM 并触发推荐时，才会向对应 LLM 服务商发送请求。

## 覆盖音源

聚合搜索与推荐当前覆盖本地库、网易云、QQ 音乐、Spotify、酷狗、酷我、汽水、歌曲宝、网络电台、播客 RSS 等音源。登录类音源需先完成授权才会出现在推荐候选中。