1 line
3.8 KiB
JSON
1 line
3.8 KiB
JSON
{"repo": "bryant24hao/clawputer", "files": {"docs/api-integration.md": {"db282f19769face0536d8586dd1f3b1f43d6b490": {"t": 1785674088.4421208, "n": 2516, "h": "ff70df7e2cd78e21", "c": "# API 接入踩坑记录\n\n## 演变历程\n\n```\nAnthropic 直连 → skyapi 代理 → Kimi K2.5 (moonshot.cn)\n```\n\n每次切换都踩了不同的坑，记录如下。\n\n## 1. Anthropic 直连\n\n**配置**：\n- Endpoint: `https://api.anthropic.com/v1/messages`\n- Auth: `x-api-key` header\n- Format: Anthropic Messages API\n\n**问题**：HTTP -1（TLS 连接失败）\n\n**原因**：硬编码的 ISRG Root X1 证书可能与 api.anthropic.com 的证书链不匹配。\n\n**解决**：`client.setInsecure()` 跳过证书验证。对于 hobby 项目可接受，生产环境需要正确的 CA 证书。\n\n## 2. skyapi.org 代理\n\n**配置**：\n- Endpoint: `https://api.skyapi.org/v1/messages`\n- Auth: 同 Anthropic 格式\n- Key: 第三方代理 key（非 `sk-ant-` 格式）\n\n**问题**：\n1. 域名拼写坑：`skypeapi.org`（错）→ `skyapi.org`（对）\n2. HTTP 403：API Key 被拒（代理 key 格式不同）\n3. HTTP 500：服务端错误，可能不支持流式或模型名不对\n\n**教训**：第三方代理的兼容性不确定，排查成本高。\n\n## 3. Kimi K2.5 (最终方案)\n\n**配置**：\n- Endpoint: `https://api.moonshot.cn/v1/chat/completions`\n- Auth: `Authorization: Bearer sk-xxx`\n- Format: OpenAI 兼容格式\n- Model: `kimi-k2.5`\n\n**踩坑过程**：\n\n### 坑 1：域名\n\n```\napi.moonshot.ai ← 错（401）\napi.moonshot.cn ← 对\n```\n\nMoonshot 的国内域名是 `.cn`，不是 `.ai`。\n\n### 坑 2：模型名\n\n```\nkimi-k2-0711 ← 404\nmoonshot-v1-8k ← 404（旧模型可能已下线）\nkimi-k2.5 ← 正确\n```\n\n### 坑 3：Thinking Mode\n\nKimi K2.5 **默认开启 thinking mode**。响应结构：\n\n```json\n{\n \"choices\": [{\n \"message\": {\n \"content\": \"\", // 可能为空！\n \"reasoning_content\": \"思考过程...\" // 实际内容在这里\n }\n }]\n}\n```\n\n当 `max_tokens` 太小（如 80），思考过程用完所有 token，`content` 为空字符串。\n\n**解决方案**：\n1. `max_tokens` 提高到 1024\n2. 解析时 fallback：`content` 为空则读 `reasoning_content`\n3. 超过 200 字符截断（屏幕小）\n\n### 坑 4：响应慢\n\nESP32 上 HTTPS 请求本身就慢（TLS 握手），加上 Kimi thinking mode，一次请求可能要 10-20 秒。\n\n**解决**：\n- `client.setTimeout(60)` — WiFiClientSecure 60 秒超时\n- `http.setTimeout(60000)` — HTTPClient 60 秒超时\n\n## API 格式对比\n\n### Anthropic Messages API\n\n```json\nPOST /v1/messages\nHeaders: x-api-key, anthropic-version\n{\n \"model\": \"claude-3-5-haiku-20241022\",\n \"system\": \"...\",\n \"messages\": [{\"role\": \"user\", \"content\": \"...\"}]\n}\nResponse: { \"content\": [{\"text\": \"...\"}] }\n```\n\n### OpenAI 兼容格式（Kimi/通用）\n\n```json\nPOST /v1/chat/completions\nHeaders: Authorization: Bearer xxx\n{\n \"model\": \"kimi-k2.5\",\n \"messages\": [\n {\"role\": \"system\", \"content\": \"...\"},\n {\"role\": \"user\", \"content\": \"...\"}\n ]\n}\nResponse: { \"choices\": [{\"message\": {\"content\": \"...\"}}] }\n```\n\n**关键区别**：\n- Auth header 不同（`x-api-key` vs `Authorization: Bearer`）\n- system message 位置不同（顶层字段 vs messages 数组第一条）\n- 响应结构不同（`content[0].text` vs `choices[0].message.content`）\n\n## 流式 vs 非流式\n\n最初设计了 SSE 流式解析（Anthropic 格式），但在代理和 Kimi 上不稳定。当前使用**非流式**请求：简单可靠，代价是等待时间稍长，回复一次性显示。\n\n未来优化：可以重新启用流式（`stream: true`），逐 token 显示回复，体验更好。\n"}}}} |