常见错误解决方案
快速定位和解决大模型API使用中的常见问题,让您的应用稳定运行
故障排除更新时间:2024年12月重要
🔍 快速诊断工具
# 快速诊断脚本
curl -X POST https://api.n1n.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "test"}],
"max_tokens": 10
}' -w "\n\nHTTP Status: %{http_code}\nTime: %{time_total}s\n"
# 检查点:
# 1. HTTP Status应该是200
# 2. 响应时间应该在几秒内
# 3. 返回JSON格式的响应错误分类与解决方案
401 Unauthorized - 认证失败
错误信息
{
"error": {
"message": "Invalid authentication credentials",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
常见原因
- •API密钥错误或已过期
- •密钥前后有空格或特殊字符
- •使用了错误的API端点
- •Authorization header格式错误
解决方案
- 1. 检查API密钥是否正确,注意不要包含多余的空格
- 2. 确认密钥格式:
Bearer YOUR_API_KEY - 3. 在控制台重新生成新的API密钥
- 4. 确认使用正确的API端点URL
# 正确的认证头格式
headers = {
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json"
}429 Too Many Requests - 速率限制
错误信息
{
"error": {
"message": "Rate limit reached. Please retry after 20 seconds.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
速率限制类型
RPM限制
每分钟请求数限制
TPM限制
每分钟Token数限制
解决方案
import time
import random
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(
stop=stop_after_attempt(5),
wait=wait_exponential(multiplier=1, min=4, max=60)
)
def api_call_with_retry():
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello"}]
)
return response
except RateLimitError as e:
# 从响应头获取重试时间
retry_after = e.response.headers.get("Retry-After", 60)
print(f"Rate limited. Waiting {retry_after} seconds...")
time.sleep(int(retry_after))
raise # 让retry装饰器处理重试- • 实现指数退避重试策略
- • 使用请求队列控制并发
- • 优化Token使用量
- • 考虑升级到更高的使用层级
Request Timeout - 请求超时
常见场景
- •生成长文本内容时超时
- •网络延迟导致的超时
- •模型处理复杂任务超时
解决方案
# 调整超时设置
import httpx
client = OpenAI(
api_key="YOUR_API_KEY",
timeout=httpx.Timeout(60.0, connect=5.0), # 60秒超时
max_retries=3 # 自动重试
)
# 使用流式响应避免超时
stream = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=messages,
stream=True # 流式响应
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")- • 增加客户端超时时间
- • 使用流式响应处理长内容
- • 减少max_tokens参数
- • 分批处理大任务
400 Bad Request - 参数错误
常见参数错误
模型不存在
错误:model_not_found
解决:检查模型名称拼写,使用支持的模型
消息格式错误
错误:invalid_message_format
解决:确保messages数组格式正确
Token超限
错误:context_length_exceeded
解决:减少输入长度或使用支持更长上下文的模型
# 正确的请求格式
{
"model": "gpt-3.5-turbo", // 正确的模型名
"messages": [
{
"role": "system", // 可选:系统消息
"content": "You are a helpful assistant."
},
{
"role": "user", // 必需:用户消息
"content": "Hello"
}
],
"temperature": 0.7, // 范围:0-2
"max_tokens": 150, // 根据模型限制设置
"stream": false // 是否流式响应
}500 Internal Server Error - 服务器错误
错误特征
- •通常是临时性错误
- •可能由服务器负载过高引起
- •重试通常能解决问题
解决方案
# 智能重试策略
def safe_api_call(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}]
)
return response
except APIError as e:
if e.status_code >= 500 and attempt < max_retries - 1:
# 服务器错误,等待后重试
wait_time = (2 ** attempt) + random.uniform(0, 1)
print(f"Server error, retrying in {wait_time:.1f}s...")
time.sleep(wait_time)
else:
raise
return None- • 实施自动重试机制
- • 使用指数退避策略
- • 考虑使用备用端点
- • 监控服务状态页面
高级调试技巧
完整的错误处理和日志记录
import logging
import json
from datetime import datetime
from openai import OpenAI, APIError, RateLimitError, AuthenticationError
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(levelname)s - %(message)s',
handlers=[
logging.FileHandler('api_errors.log'),
logging.StreamHandler()
]
)
class APIErrorHandler:
def __init__(self, client):
self.client = client
self.error_stats = {
'auth_errors': 0,
'rate_limits': 0,
'timeouts': 0,
'server_errors': 0,
'other_errors': 0
}
def handle_error(self, error, context=None):
"""统一的错误处理"""
error_info = {
'timestamp': datetime.now().isoformat(),
'error_type': type(error).__name__,
'error_message': str(error),
'context': context
}
if isinstance(error, AuthenticationError):
self.error_stats['auth_errors'] += 1
logging.error(f"认证错误: {error}")
return {
'retry': False,
'message': '请检查API密钥配置',
'action': 'CHECK_API_KEY'
}
elif isinstance(error, RateLimitError):
self.error_stats['rate_limits'] += 1
retry_after = error.response.headers.get('Retry-After', 60)
logging.warning(f"速率限制: 等待{retry_after}秒")
return {
'retry': True,
'wait_time': int(retry_after),
'message': f'速率限制,{retry_after}秒后重试',
'action': 'WAIT_AND_RETRY'
}
elif isinstance(error, APIError):
if error.status_code >= 500:
self.error_stats['server_errors'] += 1
logging.error(f"服务器错误: {error}")
return {
'retry': True,
'wait_time': 5,
'message': '服务器错误,稍后重试',
'action': 'RETRY_WITH_BACKOFF'
}
else:
self.error_stats['other_errors'] += 1
logging.error(f"API错误: {error}")
return {
'retry': False,
'message': f'请求错误: {error}',
'action': 'CHECK_REQUEST'
}
else:
self.error_stats['other_errors'] += 1
logging.error(f"未知错误: {error}")
return {
'retry': False,
'message': f'未知错误: {error}',
'action': 'CONTACT_SUPPORT'
}
def get_statistics(self):
"""获取错误统计"""
return self.error_stats
def safe_call(self, func, *args, **kwargs):
"""安全执行API调用"""
max_retries = kwargs.pop('max_retries', 3)
retry_count = 0
while retry_count < max_retries:
try:
result = func(*args, **kwargs)
logging.info(f"API调用成功")
return result
except Exception as e:
retry_count += 1
error_response = self.handle_error(e, {
'function': func.__name__,
'retry_count': retry_count,
'args': str(args)[:100]
})
if not error_response['retry'] or retry_count >= max_retries:
raise
wait_time = error_response.get('wait_time', 2 ** retry_count)
logging.info(f"等待{wait_time}秒后重试...")
time.sleep(wait_time)
raise Exception(f"达到最大重试次数: {max_retries}")
# 使用示例
client = OpenAI(api_key="YOUR_API_KEY")
error_handler = APIErrorHandler(client)
try:
response = error_handler.safe_call(
client.chat.completions.create,
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello"}],
max_retries=5
)
print(response)
except Exception as e:
print(f"最终失败: {e}")
print(f"错误统计: {error_handler.get_statistics()}")问题诊断清单
基础检查
- API密钥是否正确?
- 使用正确的API端点?
- 请求格式是否正确?
- 网络连接是否正常?
代码检查
- 错误处理是否完善?
- 重试机制是否实现?
- 超时设置是否合理?
- 日志记录是否完整?
🆘 需要更多帮助?
如果问题仍未解决,请通过以下方式获取技术支持
📧 邮件支持
support@n1n.ai
24小时内回复
💬 在线客服
工作日 9:00-18:00
实时技术支持
📚 开发者社区
技术交流群
互助解决问题