ContextQMD
Back to Gpt Academic

模型错误排查

docs/troubleshooting/model_errors.md

latest10.6 KB
Original Source

模型错误排查

在使用 GPT Academic 与大语言模型交互时，您可能会遇到各种错误提示。这些错误通常以 [Local Message] 开头显示在对话区域，表明请求未能成功完成。本文档将帮助您理解这些错误的含义，并提供相应的解决方案。

理解错误信息是解决问题的第一步。GPT Academic 的错误处理机制会将模型 API 返回的原始错误信息转换为更易理解的中文提示，同时保留关键的技术细节供排查使用。

快速诊断流程

当遇到模型调用错误时，建议按照以下顺序进行排查：

<div class="workflow-single"> <div class="workflow-header">错误诊断流程</div> <div class="workflow"> <ol class="workflow-steps"> <li><strong>确认错误类型</strong>

查看对话区显示的错误信息，识别是认证问题、额度问题还是网络问题。错误信息通常包含关键词如 "API key"、"quota"、"timeout" 等。</li>

<li><strong>检查基础配置</strong>

确认 config_private.py 中的 API 密钥配置正确，没有多余空格或引号嵌套。验证所选模型与配置的密钥匹配。</li>

<li><strong>验证网络连接</strong>

对于需要代理的服务（如 OpenAI），确认代理软件正常运行且配置正确。对于国产模型，确认网络可以正常访问对应平台。</li>

<li><strong>查阅错误详情</strong>

根据具体错误信息，在本文档中找到对应章节，按照指引解决问题。</li>

</ol> </div> </div>

认证与密钥错误

认证错误是最常见的问题类型，通常发生在首次配置或密钥过期时。这类错误的核心原因是系统无法使用您提供的凭证访问模型服务。

Incorrect API key（密钥错误）

当您看到 "Incorrect API key" 或 "API_KEY 无效" 的提示时，说明提供的 API 密钥无法通过服务商的验证。

这种情况最常见的原因是复制密钥时出现问题。API 密钥通常是一串以特定前缀开头的字符（如 OpenAI 的 sk-），在复制粘贴过程中可能会意外包含空格、换行符或其他不可见字符。另一个常见原因是密钥已被服务商撤销或过期。

python
# 正确的配置格式
API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 常见错误：包含多余空格
API_KEY = " sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "

# 常见错误：引号嵌套
API_KEY = "'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'"

???+ tip "排查建议" 1. 重新登录服务商平台，复制一个新的 API 密钥 2. 使用纯文本编辑器粘贴密钥，确保没有格式问题 3. 确认密钥前后没有多余的空格或换行 4. 检查配置文件的引号是否匹配

API key has been deactivated（密钥已停用）

此错误表明您的 API 密钥曾经有效，但现在已被服务商停用。可能的原因包括：账户长期未使用被自动清理、违反了服务商的使用条款、或者您主动在平台上删除了该密钥。

解决方法是登录对应平台的 API 管理页面，检查密钥状态。如果密钥确实已被停用，您需要创建一个新的密钥并更新配置。

账户状态错误

账户状态错误与密钥本身无关，而是涉及您在服务商平台上的账户整体状态。

Your account is not active（账户未激活）

这个错误通常出现在新注册账户尚未完成验证，或账户因某些原因被服务商暂停的情况下。

对于 OpenAI 账户，您可能需要完成手机号验证或绑定支付方式才能激活 API 访问权限。对于国产模型平台，可能需要完成实名认证。建议登录对应平台的控制台，查看是否有待完成的验证步骤或账户状态提示。

You exceeded your current quota（额度不足）

当您的 API 调用额度耗尽时，会收到此错误。不同服务商的额度机制有所不同：OpenAI 采用预充值模式，余额用完即停止服务；部分国产模型平台提供免费额度，超出后需要付费。

!!! warning "注意区分免费额度和付费额度" 许多平台为新用户提供免费体验额度，这些额度通常有使用期限。免费额度耗尽后，即使账户中有付费余额，也可能需要在平台上手动切换到付费模式。

解决此问题的方法包括：登录平台充值或购买额度、切换到有余额的其他 API 密钥、或者改用免费额度更充裕的替代模型（如通义千问）。

API2D 相关错误

如果您使用 API2D 等中转服务，可能会遇到特有的错误信息：

  • Bad forward key：表示 API2D 账户余额不足，需要充值
  • Not enough point：表示 API2D 点数不足，需要购买点数

这些错误的解决方式是登录 API2D 平台进行充值。

请求格式错误

请求格式错误通常与您发送给模型的内容有关，而非配置问题。

Reduce the length / Context length exceeded（内容过长）

这是使用过程中最常遇到的错误之一。每个模型都有上下文长度限制（以 Token 计算），当您的输入文本加上对话历史超过这个限制时，就会触发此错误。

GPT Academic 在遇到此错误时会自动尝试裁剪对话历史，释放部分空间。如果裁剪后仍然超限，通常是因为单次输入的文本本身就过长。

处理长文本的推荐做法是：将长文本分段处理，每次只发送一部分；或者使用函数插件区的批量处理功能（如 PDF 翻译、代码分析），这些插件会自动将长内容分割成合适的片段。

您也可以在配置中启用自动上下文裁剪功能：

python
AUTO_CONTEXT_CLIP_ENABLE = True  # 启用自动裁剪

???+ note "不同模型的上下文限制" | 模型 | 上下文长度 | |-----|-----------| | gpt-3.5-turbo | 16K tokens | | gpt-4 | 8K tokens | | gpt-4-turbo | 128K tokens | | qwen-max | 32K tokens | | deepseek-chat | 64K tokens |

如果您经常处理长文本，建议选择上下文窗口更大的模型。

bad_request（请求格式错误）

此错误表示发送给模型的请求不符合 API 规范。常见原因包括：输入内容包含模型不支持的特殊字符、消息格式不正确、或者使用了模型不支持的参数。

如果您在正常对话中遇到此错误，尝试简化输入内容，移除特殊符号或格式。如果问题持续出现，可能是插件或自定义功能的配置问题。

模型访问错误

Model does not exist（模型不存在）

当您请求的模型名称不在服务商的可用列表中时，会收到此错误。这通常有几种可能：

模型名称拼写错误是最常见的原因。OpenAI 的模型名称区分大小写，应使用小写形式如 gpt-4o 而非 GPT-4o。另一种情况是您的账户没有访问该模型的权限——某些高级模型（如早期的 GPT-4）需要单独申请访问权限。

python
# 正确的模型名称示例
LLM_MODEL = "gpt-4o"           # OpenAI
LLM_MODEL = "qwen-max"         # 通义千问
LLM_MODEL = "deepseek-chat"    # DeepSeek
LLM_MODEL = "glm-4"            # 智谱

如果您使用第三方中转服务，还需要确认该服务支持您请求的模型。

rate_limit（速率限制）

当短时间内发送过多请求时，API 服务商会暂时限制您的访问。这是一种保护机制，防止 API 被滥用。

遇到此错误时，最简单的解决方法是等待一分钟后重试。如果您需要进行大量批量处理，可以采取以下措施：

  • 降低并发数：在配置中减小 DEFAULT_WORKER_NUM 的值
  • 配置多个 API 密钥进行负载均衡：API_KEY = "sk-key1,sk-key2,sk-key3"
  • 在请求之间添加适当的延迟

网络连接错误

Connection timeout（连接超时）

超时错误表示请求发送后在规定时间内未收到响应。这可能是网络问题、代理配置问题，或者服务商端的拥堵。

对于访问 OpenAI 等海外服务，超时通常与代理配置有关。请确认：

  1. USE_PROXY 设置为 True
  2. 代理软件正在运行
  3. proxies 中配置的地址和端口与代理软件一致
python
USE_PROXY = True
proxies = {
    "http":  "http://127.0.0.1:7890",
    "https": "http://127.0.0.1:7890",
}

如果网络状况不佳，可以适当增加超时时间：

python
TIMEOUT_SECONDS = 60  # 默认为 30 秒
MAX_RETRY = 3         # 增加重试次数

!!! tip "国内用户建议" 如果您在国内且没有稳定的代理环境，强烈建议使用国产模型（如通义千问、DeepSeek、智谱 GLM），这些服务无需代理即可直接访问，稳定性更好。

system_busy（系统繁忙）

此错误表示模型服务端当前负载较高，无法处理您的请求。这种情况在热门模型发布初期或高峰时段较为常见。

解决方法是等待片刻后重试，或者临时切换到负载较低的备用模型。

错误信息速查表

下表汇总了常见错误及其快速解决方案：

错误关键词含义快速解决
Incorrect API key密钥无效重新复制密钥，检查格式
API key has been deactivated密钥已停用创建新密钥
account is not active账户未激活完成平台验证
exceeded your current quota额度不足充值或切换密钥
Model does not exist模型不存在检查模型名称拼写
reduce the length内容过长减少输入或清除历史
rate_limit请求频率超限等待后重试
timeout连接超时检查网络和代理
bad_request请求格式错误简化输入内容
authentication_error认证失败检查 API 密钥配置

获取更多帮助

如果按照上述指引仍无法解决问题，您可以：

  1. 查看完整错误信息：GPT Academic 会在错误提示中包含原始的错误详情，这些技术信息有助于定位问题根源。

  2. 搜索 GitHub Issues：访问 项目 Issues 页面 搜索类似问题，很可能其他用户已经遇到并解决了相同的问题。

  3. 加入社区讨论：QQ 交流群 610599535 有活跃的用户社区，可以获得实时帮助。

  4. 提交 Issue：如果确认是 Bug，请在 GitHub 提交 Issue，附上完整的错误信息、使用的模型、以及复现步骤。

相关文档