文档 · 生产实践
故障排查
按现象排查常见问题。
返回 404 Not Found+
OpenAI SDK 的 Base URL 要以 /v1 结尾；Anthropic SDK 的 Base URL 不带 /v1。另外检查模型 ID 是否拼写正确。
返回 401 Unauthorized+
检查 API Key 是否完整，前后有没有多余的空格或换行；请求头格式是否为 Authorization: Bearer <key>。Anthropic 格式使用 x-api-key。
返回 403 或提示余额不足+
在控制台查看账户余额，以及该 Key 是否已停用或设置了限制。
提示模型不存在+
模型 ID 区分大小写，以模型目录为准；也可以调用 GET /v1/models 查看当前 Key 可用的模型。
请求很慢或超时+
推理模型思考时间较长。使用流式输出，把客户端超时设为 300 秒以上，并检查输出上限是否过大。
流式内容一次性到达+
通常是中间的反向代理在缓冲响应。关闭缓冲（如 Nginx 的 proxy_buffering off），并确认客户端按行读取。
400：Unsupported parameter+
推理模型通常不接受 temperature、max_tokens 等参数：去掉采样参数，改用 max_completion_tokens。
输出被截断+
finish_reason 为 length（Anthropic 为 stop_reason: max_tokens）说明达到了输出上限，请调大。
JSON 解析失败+
使用 JSON 输出，并检查输出是否因长度上限被截断。
模型看不到图片+
确认模型带「视觉理解」能力；图片 URL 必须公网可访问，否则改用 base64。
自查命令
用下面的命令确认地址与密钥是否可用（-i 会显示响应头和状态码）：
curl -sS -i https://<your-endpoint>/v1/models \
-H "Authorization: Bearer $API_KEY"仍无法解决时，请记录请求时间、模型、状态码和响应体，通过控制台联系我们。