# 07 · LLM 对话

本节讲怎么接 LLM、两条协议（OpenAI 兼容 / Anthropic）的差别、常见错误码、长什么样。

## 1. 配置文件在哪里

存在 `~/.live2D/live2d.conf.json` 里，但**改完必须重启**（见 §5.1）。

```jsonc
{
  "llm_provider": "openai",         // "openai" 或 "anthropic"
  "llm_model": "gpt-4o-mini",
  "llm_api_key": "sk-...",
  "llm_base_url": "https://api.openai.com"
}
```

**修改入口**：桌宠 → 工具栏 ⚙ → 配置中心 → 「🤖 LLM 对话设置」区。

## 2. 两条协议对照

| 项 | OpenAI 兼容 | Anthropic |
|---|---|---|
| **端点** | `POST {base_url}/v1/chat/completions` | `POST {base_url}/v1/messages` |
| **鉴权 Header** | `Authorization: Bearer <key>` | `x-api-key: <key>` + `anthropic-version: 2023-06-01` |
| **system 消息位置** | `messages: [{role:"system", content:...}]` | 提到顶层 `system: "..."` 字段 |
| **messages[0] 限制** | 无 | 必须是 `user`（后端有兜底，强制补一条） |
| **max_tokens** | 可选（默认 1024） | **必填**（默认 1024） |
| **响应** | `choices[0].message.content` | `content[*].text`（按 type 过滤） |
| **多模态** | `content: [{type:"text"}, {type:"image_url", image_url:{url:"data:..."}}]` | `content: [{type:"text"}, {type:"image", source:{type:"base64", media_type, data}}]` |
| **请求超时** | 180 秒 | 180 秒 |
| **代理** | `no_proxy()`（不走 HTTP_PROXY） | `no_proxy()`（不走 HTTP_PROXY） |

> 💡 **OpenAI 兼容** = 任何实现同一协议的服务：OpenAI 官方、Azure OpenAI、OpenRouter、DeepSeek、Moonshot、智谱 GLM（兼容端点）、自部署 vLLM / Ollama（`/v1` 端点）、LM Studio 等。

## 3. 常用 Base URL + Model 速查

| 服务 | Provider 选项 | Base URL | 常用 Model |
|---|---|---|---|
| OpenAI 官方 | `openai` | `https://api.openai.com` | `gpt-4o-mini`, `gpt-4o`, `o1-mini` |
| Anthropic Claude | `anthropic` | `https://api.anthropic.com` | `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022` |
| DeepSeek | `openai` | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Moonshot | `openai` | `https://api.moonshot.cn/v1` | `moonshot-v1-8k`, `moonshot-v1-32k` |
| 智谱 GLM | `openai` | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash`, `glm-4` |
| Ollama（本地） | `openai` | `http://localhost:11434/v1` | 任何已 pull 的模型 |
| LM Studio（本地） | `openai` | `http://localhost:1234/v1` | 加载的模型 |
| 自部署 vLLM | `openai` | 你的 URL | 部署时定的名字 |

> ⚠️ **如果你在走代理（clash-verge / sing-box 等），且 LLM 端点是内网 / Tailscale IP**，注意 `no_proxy()` 已在代码里强制加上，但**你自己的系统环境变量**如果有错可能让请求出问题。详细见 [09-常见问题FAQ.md](09-常见问题FAQ.md)。

## 4. 错误码

LLM 返回非 2xx 时，会在气泡里显示一条 `system` 错误，格式：`[<状态码>] <友好前缀>: <API 原始消息>`。

### 4.1 OpenAI 兼容
| 状态码 | 含义 |
|---|---|
| 401 | API key 无效或未授权 |
| 403 | API key 权限不足 |
| 404 | API 端点或模型不存在（检查 base_url 和 model 名） |
| 429 | 请求频率超限或余额不足 |
| 5xx | API 服务异常 |
| 60s | "请求超时"（注意：实际超时是 180s，错误文案是历史遗留） |
| connect | "无法连接到 API 服务" |

### 4.2 Anthropic
| 状态码 | 含义 |
|---|---|
| 401 | API key 无效或未授权 |
| 403 | API key 权限不足 |
| 404 | 模型不存在 |
| 429 | 请求频率超限 |
| 529 | 服务过载（Overloaded） |
| 5xx | 服务异常 |

## 5. 关键限制

### 5.1 改完配置必须重启 ⚠️

LLM 客户端（`OpenAiProvider` / `AnthropicProvider`）在 `main()` 里**一次性创建**：
```rust
let llm_provider: Arc<dyn LLMProvider> = match provider_kind.as_str() {
    "anthropic" => Arc::new(AnthropicProvider::new(...)),
    _ => Arc::new(OpenAiProvider::new(...)),
};
```

这个 `Arc` 整个进程生命周期里都是同一个对象。`get_llm_status` 读到的是**磁盘最新配置**，但实际请求的还是启动时的 provider。

**所以**：
- 改了 provider / model / api_key / base_url **任何一项** → 重启软件
- 在配置中心保存时按钮会变绿显示「✅ 已保存」，但**状态点变色**和**实际能用**是**两回事**

### 5.2 流式输出不支持 ❌
当前是**整段返回**：等 LLM 全推完才一次性显示。
- 小模型（< 3B）体验还行
- 大模型（7B+、Claude Sonnet 等）会有一段"静默"等待期
- 输入框会一直 disabled，底部出现"桌宠正在思考…"

### 5.3 max_tokens 硬编码 = 1024
对话回复超过 1024 token 会被截断。**当前版本没有 UI 让你改这个**。

### 5.4 多模态（图片）支持
- **支持**：发截图给 LLM 看 → 见 [04-桌宠窗口使用.md §4](04-桌宠窗口使用.md)
- **JPEG 预览优先**（不是 PNG 原图，节省 10× 体积）
- **只支持 image_url 形式**（OpenAI）/ **image base64 形式**（Anthropic），不支持音频/视频

### 5.5 思考块（DeepSeek / QwQ / o1）
LLM 回复里含 `<think>...</think>` 时**自动折叠**为可点开的小标签。详细见 [05-聊天功能.md §3.2](05-聊天功能.md)。

### 5.6 动作标签（`[MOTION: xxx]`）
**当前版本不再注入**动作标签指令进 system prompt。
- 历史：2026-06-12 曾经让 LLM 在回复末尾附 `[MOTION: idle]` 等
- 当前：脑里不再加这个 prompt，LLM 不会主动回动作标签
- 情绪仍然通过**事件注入**（interact / praise 等）驱动模型动作

### 5.7 RAG 记忆的真相
- 架构上**有** RAG（SQLite + 向量索引）
- 实际 **embedder 是 `DummyEmbedder`**（基于 hash 的伪 384 维向量）— **不是真实语义嵌入**
- 所以"长期记忆"功能**当前没意义**：检索结果随机性强，不实用
- 状态：架构已就位，等接入真实 embedder 才能用

> 💡 如果你接的是 OpenAI 兼容服务，**可以让你的 LLM 端点自带 embedding 能力**（如支持 `/v1/embeddings`），把 `dummy` 换成真实调用即可——但这是改源码的事，本手册不展开。

### 5.8 base_url 末尾 `/v1` 处理
- OpenAI 兼容：自动剥末尾的 `/` 和 `/v1`，请求时统一拼 `{base}/v1/chat/completions`
- Anthropic：只剥末尾 `/`
- 举例：填 `https://api.deepseek.com/v1` 和 `https://api.deepseek.com` 都对

## 6. 多模态请求超时 = 180 秒

- 普通对话：理论几秒-几十秒
- 多模态（截图）请求：图片 base64 上传 + 视觉编码 + 文本生成，**实测 30-90 秒很常见**
- 如果 LLM 端点很慢，可以把图片压得更小（[04-桌宠窗口使用.md §4.3](04-桌宠窗口使用.md)），但不能改超时

## 7. 自部署网关的兼容性提示

某些自部署 OpenAI 兼容网关**严格校验 `detail` 字段**。代码**已主动不传** `detail` 字段（默认行为是 OpenAI 官方默认 `auto`），所以兼容性好。

如果你的网关还报 `invalid image detail: auto (2013)`，**前端清缓存**（关掉重开），确认版本是 **2026-06-14 之后**。

---

下一步：[08-数据存储与备份.md](08-数据存储与备份.md)。