大模型常见报错代码速查
本文档整理了 DeepAgent 对接各大模型时常见的报错代码、原因及解决方案，供快速排查定位。
HTTP 状态码速查
OpenAI 常见报错
上下文长度超限
原因：输入内容超过了模型支持的最大上下文长度。
解决方案：
- 减少输入消息的历史轮次或长度
- 切换至支持更长上下文的模型（如 GPT-4o、GPT-4-Turbo）
- 对长文本进行摘要压缩后再传入
Token 配额用尽
原因：账户的 API 额度已用完或账户欠费。
解决方案：
- 检查 OpenAI 账户的计费状态
- 充值或等待下个计费周期
- 设置 Usage Limit 告警
内容审核拦截
原因：输入或输出内容触发了 OpenAI 的内容安全策略。
解决方案：
- 检查提问内容是否包含敏感词汇
- 调整提示词避免触发审核机制
速率限制
原因：每分钟请求数（RPM）或每分钟 Token 数（TPM）超过限制。
解决方案：
- 实现指数退避重试（首次等 1s，后续翻倍）
- 降低并发调用数
- 升级 API Tier 提高限额
DeepSeek 常见报错
模型服务繁忙
原因：DeepSeek 服务高峰期负载过高，请求被拒绝。
解决方案：
- 等待后重试，避开高峰时段
- 实现自动重试机制，增加重试间隔
余额不足
原因：DeepSeek 账户余额不足。
解决方案：登录 DeepSeek 开放平台进行充值。
模型暂不支持
原因：请求的模型名称不存在或已下线。
解决方案：核对 DeepSeek 官方文档中的可用模型列表，更新模型名称。
国内大模型常见报错
通义千问（阿里云 DashScope）
文心一言（百度千帆）
讯飞星火
智谱 AI（ChatGLM）
DeepAgent 侧常见报错
大模型调用工具失败
现象：AI员工仅返回一句话（如"我来为您查询xxx"），没有后续数据卡片或总结。
原因：
- 当前模型不支持工具调用（Tool Calling / Function Calling）
- 模型参数量不足，无法准确命中工具
解决方案：更换支持工具调用且参数量较大的模型。详见 大模型选型及切换。
嵌入模型调用失败
现象：问答持续 loading 转圈，学习数据卡在 Embedding 阶段。
原因：
- Embedding 模型配置错误或服务异常
- API Key 或模型名称配置不正确
- 网络连接异常
解决方案：
- 检查 Embedding 模型服务是否正常运行
- 确认 API Key 和模型名称配置正确
- 检查网络连通性
模型返回格式异常
现象：大模型返回的内容格式不符合预期，解析失败。
原因：
- 模型未按 JSON 模式返回
- 模型输出被截断
- max_tokens 设置过小导致输出不完整
解决方案：
- 增大 max_tokens 参数值
- 开启模型的 JSON 模式（如 OpenAI 的
response_format） - 在 Prompt 中明确输出格式要求
排查建议
-
开启 LangSmith 调试：通过 LangSmith 调试 查看完整的模型调用链路，定位具体报错节点。
-
查看 API 原始响应：使用 APIFox、Postman 等工具直接调用模型 API，获取完整的报错信息。参考 Nora问答错误排查 中的 curl 示例。
-
检查模型配置：进入 AI员工市场 → 管理后台 → 模型配置，确认模型名称、API Key、Base URL 等配置正确。
-
更换模型测试：当某个模型持续报错时，切换到其他可用模型验证是否为模型侧问题。