模型 API 报错：从 completion 无法解析说起
「API 返回的 completion 无法解析」是官方 FAQ 点名的报错，本质是服务商返回了空文本。以它为起点，把模型侧报错的排查清单列全。
completion 无法解析的官方排查步骤
按官方 FAQ 的顺序逐项做：
- 检查 API Key 是否仍有效——在服务商控制台看 Key 状态，删了或重置过就换新 Key
- 检查是否达到调用限制或配额——余额用尽、限流触发都是空回复的常见根因
- 检查网络连接——服务器能否访问服务商地址；境外服务商需要代理，代理配置见 Docker 部署
- 尝试 reset——群里发 /reset 重置会话上下文
- 降低最大对话次数设置——上下文过长可能触发服务商异常
- 切换同提供商的其他模型或换提供商——定位是单模型问题还是全局问题
按报错关键词的细分
| 现象关键词 | 多半是 | 动作 |
|---|---|---|
| 401 / unauthorized / invalid key | Key 错或失效 | 重填 Key，注意别带空格 |
| 429 / rate limit / throttle | 限流或配额尽 | 等窗口过、降频、充值 |
| 404 / model not found | 模型名写错 | 核对模型 ID，用测试模型按钮验证 |
| 超时 timeout | 网络不通 | 先测服务器 curl 服务商地址，再查代理 |
| 向量维度错误 | 嵌入模型换了 | 恢复原配置或重建知识库，见嵌入重排序 |
Base URL 的三个高频手滑
- 少了 /v1 结尾——很多服务商要求带，官方文档在 DeepSeek 接入一节专门提醒过
- 混用了对话地址和嵌入地址——两类模型的 API 地址可能不同
- 把网页地址当 API 地址——控制台首页地址不是接口地址，去接口文档页找
排障的姿势
- 每次改动后用模型旁的「测试模型」按钮验证，别到群里发消息试错
- 「日志」页里看真实请求与响应，报错原文比面板弹窗信息全
- 多个提供商时，用配置文件切换做二分定位：换提供商就好了 = 原服务商的问题；换提供商还坏 = 框架或网络的问题
- 仍然复现且排除自身配置问题的，到项目仓库提 Issue，附脱敏日志
预防性习惯：Key 定期轮换、余额设告警（服务商侧功能）、测试环境与生产环境用不同的 Key，炸一个不连坐。