09 - 常见问题与故障排除
快速解决常见问题,提升开发效率
📋 本章概览
本章涵盖:
- 常见错误及解决方案
- API 调用问题
- 代码质量问题
- 性能问题
- 安全问题
- 社区资源
❓ 常见问题 FAQ
Q1: Codex 生成的代码不正确怎么办?
可能原因:
- 提示词不够清晰
- 缺少必要的上下文
- 任务过于复杂
- 使用了不适合的模型
解决方案:
1. 改进提示词:
❌ "写一个函数"
✅ "用 Python 写一个函数,接收整数列表,返回平均值,包含错误处理"
2. 提供上下文:
- 现有代码结构
- 技术栈和版本
- 预期的输入输出
3. 分解任务:
- 将大任务拆分为小任务
- 逐步实现
4. 升级模型:
- 简单任务 → gpt-4o-mini
- 复杂任务 → gpt-4o 或 o1
Q2: API 调用超时或失败
错误信息:
openai.error.Timeout: Request timed out
openai.error.RateLimitError: Rate limit exceeded
openai.error.APIError: Internal server error
解决方案:
import time
from openai import OpenAI, APIError, RateLimitError, Timeout
client = OpenAI(api_key="your-api-key")
def call_api_with_retry(
prompt: str,
max_retries: int = 3,
base_delay: int = 1
):
"""带重试的 API 调用"""
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": prompt}],
timeout=30 # 设置超时时间
)
return response.choices[0].message.content
except Timeout:
print(f"⏱️ 超时,重试 {attempt + 1}/{max_retries}")
time.sleep(base_delay * (2 ** attempt)) # 指数退避
except RateLimitError:
print(f"🚦 速率限制,等待...")
time.sleep(60) # 等待1分钟
except APIError as e:
print(f"❌ API 错误:{e}")
if attempt == max_retries - 1:
raise
time.sleep(base_delay * (2 ** attempt))
raise Exception(f"Failed after {max_retries} retries")
# 使用
result = call_api_with_retry("写一个冒泡排序")
Q3: 如何处理大型代码库?
问题:代码库太大,无法一次性提供给 AI
解决方案:
class CodebaseManager:
"""代码库管理器"""
def __init__(self, project_path: str):
self.project_path = project_path
self.index = self.build_index()
def build_index(self) -> dict:
"""构建代码库索引"""
index = {
"files": [],
"functions": {},
"classes": {},
"imports": {}
}
# 遍历项目文件
for file_path in self.get_python_files():
# 解析文件
analysis = self.analyze_file(file_path)
index["files"].append(file_path)
index["functions"].update(analysis["functions"])
index["classes"].update(analysis["classes"])
index["imports"].update(analysis["imports"])
return index
def get_relevant_context(self, query: str) -> str:
"""获取相关上下文"""
# 1. 向量搜索找到相关文件
relevant_files = self.search_files(query)
# 2. 提取相关代码片段
context = []
for file in relevant_files[:5]: # 只取前5个最相关的
content = self.read_file(file)
context.append(f"# {file}\n{content}")
# 3. 构建精简的上下文
return "\n\n".join(context)
def generate_with_context(self, query: str) -> str:
"""带上下文的代码生成"""
context = self.get_relevant_context(query)
prompt = f"""
项目上下文:
{context}
任务:
{query}
请基于上述上下文生成代码。
"""
return call_api(prompt)
# 使用
manager = CodebaseManager("/path/to/project")
result = manager.generate_with_context(
"添加用户注销功能"
)
Q4: 生成的代码有安全漏洞
常见漏洞:
- SQL 注入
- XSS 攻击
- 硬编码密钥
- 不安全的密码存储
预防措施:
def security_check(code: str) -> dict:
"""安全检查"""
issues = []
# 1. 检查 SQL 注入
if re.search(r'\.format\([^)]*\).*execute', code):
issues.append({
"type": "SQL Injection",
"severity": "高",
"description": "可能存在 SQL 注入风险",
"suggestion": "使用参数化查询"
})
# 2. 检查硬编码密钥
if re.search(r'(api_key|password|secret)\s*=\s*["\']', code):
issues.append({
"type": "Hardcoded Secrets",
"severity": "高",
"description": "检测到硬编码的密钥",
"suggestion": "使用环境变量"
})
# 3. 检查不安全的密码存储
if 'password' in code and not 'hash' in code:
issues.append({
"type": "Insecure Password Storage",
"severity": "高",
"description": "密码可能未加密存储",
"suggestion": "使用 bcrypt 或 argon2"
})
return {
"safe": len(issues) == 0,
"issues": issues
}
# 使用
code = """
def login(username, password):
query = f"SELECT * FROM users WHERE username='{username}'"
db.execute(query)
"""
result = security_check(code)
if not result["safe"]:
print("⚠️ 发现安全问题:")
for issue in result["issues"]:
print(f"- {issue['type']}: {issue['description']}")
print(f" 建议:{issue['suggestion']}")
让 AI 修复漏洞:
原始代码:
[粘贴有漏洞的代码]
请修复以下安全问题:
1. SQL 注入风险 - 使用参数化查询
2. 硬编码密钥 - 使用环境变量
3. 密码未加密 - 使用 bcrypt
修复后的代码:
Q5: 生成的代码性能差
问题分析:
# AI 生成的代码(性能差)
def find_duplicates(arr):
duplicates = []
for i in range(len(arr)):
for j in range(i+1, len(arr)):
if arr[i] == arr[j] and arr[i] not in duplicates:
duplicates.append(arr[i])
return duplicates
# 时间复杂度:O(n³)
优化提示词:
优化以下代码的性能:
[粘贴代码]
当前问题:
- 时间复杂度:O(n³)
- 处理 10000 个元素需要 > 10秒
优化目标:
- 降低时间复杂度到 O(n) 或 O(n log n)
- 处理 10000 个元素 < 100ms
要求:
- 分析当前算法的瓶颈
- 提出优化方案
- 实现优化后的代码
- 比较性能提升
AI 优化后:
def find_duplicates_optimized(arr):
"""
优化后的查找重复元素
时间复杂度:O(n)
空间复杂度:O(n)
"""
seen = set()
duplicates = set()
for item in arr:
if item in seen:
duplicates.add(item)
else:
seen.add(item)
return list(duplicates)
# 性能对比:
# 输入:10000 个元素
# 原始:~15秒
# 优化:~2ms
# 提升:7500倍
Q6: 无法使用 API(网络限制)
问题:国内访问 OpenAI API 受限
解决方案:
import os
# 方案 1:使用代理
os.environ['HTTP_PROXY'] = 'http://your-proxy:port'
os.environ['HTTPS_PROXY'] = 'http://your-proxy:port'
from openai import OpenAI
client = OpenAI(
api_key="your-api-key",
http_client=httpx.Client(proxies="http://your-proxy:port")
)
# 方案 2:使用国内镜像服务
client = OpenAI(
api_key="your-api-key",
base_url="https://api.mirror.com/v1" # 镜像地址
)
# 方案 3:使用替代服务
from anthropic import Anthropic # Claude(可直接访问)
client = Anthropic(api_key="your-api-key")
response = client.messages.create(
model="claude-4-sonnet",
messages=[{"role": "user", "content": "Hello"}]
)
Q7: 如何控制成本?
监控使用量:
class CostMonitor:
"""成本监控"""
def __init__(self, budget_daily: float = 10.0):
self.budget_daily = budget_daily
self.usage_today = 0.0
self.reset_time = datetime.now().date()
def track(self, model: str, input_tokens: int, output_tokens: int):
"""追踪使用"""
# 检查是否需要重置
if datetime.now().date() > self.reset_time:
self.usage_today = 0.0
self.reset_time = datetime.now().date()
# 计算成本
cost = self.calculate_cost(model, input_tokens, output_tokens)
self.usage_today += cost
# 检查预算
if self.usage_today > self.budget_daily:
raise BudgetExceededError(
f"Daily budget exceeded: ${self.usage_today:.2f} / ${self.budget_daily}"
)
# 警告
if self.usage_today > self.budget_daily * 0.8:
print(f"⚠️ 预算警告:已使用 {self.usage_today/self.budget_daily*100:.0f}%")
def report(self):
"""生成报告"""
return {
"date": self.reset_time,
"usage": f"${self.usage_today:.2f}",
"budget": f"${self.budget_daily:.2f}",
"remaining": f"${self.budget_daily - self.usage_today:.2f}"
}
# 使用
monitor = CostMonitor(budget_daily=10.0)
def call_api_monitored(prompt: str, model: str = "gpt-4o"):
"""带成本监控的 API 调用"""
# 估算 token 数量
input_tokens = len(prompt) // 4 # 粗略估算
try:
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
# 记录实际使用量
monitor.track(
model,
response.usage.prompt_tokens,
response.usage.completion_tokens
)
return response.choices[0].message.content
except BudgetExceededError as e:
print(f"❌ {e}")
print(f"今日使用情况:{monitor.report()}")
return None
# 定期查看报告
print(monitor.report())
🔧 故障排除指南
API 错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 401 | API Key 无效 | 检查 API Key 是否正确 |
| 429 | 速率限制 | 降低请求频率或升级套餐 |
| 500 | 服务器错误 | 稍后重试 |
| 503 | 服务不可用 | 等待服务恢复 |
调试技巧
import logging
# 启用详细日志
logging.basicConfig(level=logging.DEBUG)
# 记录请求和响应
def call_api_debug(prompt: str):
"""调试模式的 API 调用"""
print("\n" + "="*50)
print("📤 请求")
print("="*50)
print(f"提示词:\n{prompt}")
print(f"字符数:{len(prompt)}")
print(f"估算 tokens:{len(prompt) // 4}")
try:
start_time = time.time()
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": prompt}]
)
elapsed = time.time() - start_time
print("\n" + "="*50)
print("📥 响应")
print("="*50)
print(f"状态:成功")
print(f"耗时:{elapsed:.2f}秒")
print(f"使用 tokens:{response.usage.total_tokens}")
print(f"输入:{response.usage.prompt_tokens}")
print(f"输出:{response.usage.completion_tokens}")
print(f"\n生成内容:\n{response.choices[0].message.content}")
return response.choices[0].message.content
except Exception as e:
print("\n" + "="*50)
print("❌ 错误")
print("="*50)
print(f"类型:{type(e).__name__}")
print(f"信息:{str(e)}")
raise
# 使用
result = call_api_debug("写一个快速排序")
📚 社区资源
官方资源
社区
学习资源
💡 最佳实践提醒
开发阶段
✅ DO:
- 使用版本控制
- 编写测试
- 审查 AI 生成的代码
- 记录提示词模板
- 监控使用量和成本
❌ DON'T:
- 盲目信任 AI 代码
- 跳过测试
- 忽视安全问题
- 硬编码敏感信息
生产环境
✅ DO:
- 实施速率限制
- 添加错误处理
- 使用缓存
- 监控性能
- 定期审查代码质量
❌ DON'T:
- 直接部署未测试的代码
- 忽视错误日志
- 超出预算
🎯 总结
恭喜你完成了整个 Codex 教程系列!
你已经学会了:
- ✅ Codex 的基础知识和使用方法
- ✅ 核心特点和技术原理
- ✅ 高级功能(MCP、Skills、Agent)
- ✅ 最佳实践和优化技巧
- ✅ 实战案例和故障排除
下一步建议
实践项目
- 选择一个实际项目
- 应用所学知识
- 记录经验和教训
持续学习
- 关注 OpenAI 更新
- 探索新功能
- 分享经验
社区贡献
- 分享提示词模板
- 帮助其他开发者
- 贡献开源项目
感谢学习!祝你在 AI 辅助编程的旅程中取得成功!
👈 返回教程首页