排障概览

遇到调用失败、响应变慢、模型不可用或回答质量异常时，可以先按下面的清单定位问题，再进入 FAQ 查看更具体的问答。

快速检查清单

• API Key 是否正确、有效且未泄露。
• Base URL 是否选择了合适接入点。
• 请求头是否包含正确认证信息。
• 请求体是否为合法 JSON。
• 模型是否存在、可用且具备目标能力。
• 是否触发 QPS、并发、上下文长度、输出长度或内容安全限制。
• 是否存在网络延迟、输入过长、模型计算复杂或非流式等待导致的慢请求。

常见状态码

慢请求排查

回答质量问题

常见原因包括 Prompt 模糊、缺少上下文、模型能力不匹配、实时信息缺失或任务过于复杂。可尝试：

• 明确任务目标、输出格式和限制条件。
• 补充业务背景、文档或实时数据。
• 切换更适合的模型。
• 对事实性结果引入搜索、引用或人工复核。

请求日志排查

控制台请求日志通常可按时间范围、API Key、模型和响应状态筛选。建议：

• 单次排查选择尽量精确的时间范围，数据量较大时分段查询。
• 本地日志记录请求 ID、状态码、模型、耗时、错误信息和调用方。
• 本地未记录请求 ID 时，可按请求时间、API Key、模型和响应状态在控制台反查。
• 提交工单时只提供请求 ID、时间、模型和错误摘要，不要提供完整 API Key。

重试和升级处理

• 429 和部分 5xx 可采用指数退避重试。
• 400、401、403 通常需要修正请求、密钥、认证状态或权限。
• 写操作重试前应确认业务幂等性，避免重复创建资源或重复扣费。
• 联系支持时保留请求 ID、时间、状态码、模型、错误信息和最小复现步骤。