Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
169 lines (129 loc) · 4.47 KB

TROUBLESHOOTING.md

File metadata and controls

169 lines (129 loc) · 4.47 KB
Raw

🔧 常见问题排查

跑教程时遇到报错？来这里找答案。按 Ctrl+F 搜报错关键词。

API Key 相关

❌ openai.AuthenticationError: Incorrect API key provided

原因：API Key 写错了，或者环境变量没有正确设置。
解决：
  1. 确认你已经申请了 API Key（DeepSeek / OpenAI / 通义千问等）
  2. 检查环境变量：
     Linux/Mac: echo $OPENAI_API_KEY
     Windows:   echo %OPENAI_API_KEY%
  3. 重新设置：
     Linux/Mac: export OPENAI_API_KEY="sk-你的key"
     Windows:   $env:OPENAI_API_KEY="sk-你的key"

❌ openai.APIConnectionError: Connection error

原因：网络连不上 API 服务器。
解决：
  1. 如果用的是 OpenAI 官方 → 国内可能被墙，试试换 DeepSeek：
     export OPENAI_BASE_URL="https://api.deepseek.com/v1"
  2. 如果用的是国内接口 → 检查 base_url 是否正确
  3. 检查是否需要代理：
     export HTTP_PROXY="http://127.0.0.1:7890"

❌ openai.RateLimitError

原因：API 调用太频繁，或者账户余额不足。
解决：
  1. 等几秒再试
  2. 检查 API 账户余额（登录平台查看）
  3. 如果用的是免费额度，可能用完了

依赖安装

❌ pip install 报错 / ModuleNotFoundError

原因：缺少 Python 包。
解决：
  1. 确认在项目目录下：
     cd agent-builder  （或 cd agent-builder-pro）
  2. 一次性安装所有依赖：
     pip install -r requirements.txt
  3. 如果某个包单独报错：
     pip install openai （基础版必要）
     pip install sentence-transformers （Pro 版 P3 必要）
     pip install gradio （Pro 版 P6 必要）

❌ sentence-transformers 下载模型卡住

原因：模型文件从 HuggingFace 下载，国内可能慢。
解决：
  1. 设置 HuggingFace 镜像：
     export HF_ENDPOINT="https://hf-mirror.com"
  2. 或者等一会儿——第一次下载约 80MB，之后不用再下
  3. 如果实在下载不了，P3 代码会自动降级为关键词匹配模式

代码运行

❌ 跑到一半报错 "finish_reason: length"

原因：LLM 的输出被 max_tokens 截断了。
解决：加大 max_tokens 参数，或者缩短问题。

❌ Agent 一直循环不停止

原因：LLM 反复调用工具，永远不说"完成了"。
解决：
  1. 这是 MAX_LOOPS 在保护你——它会在 N 轮后自动停止
  2. 检查 system prompt，确保告诉 Agent "完成任务后直接回答，不要继续调工具"

❌ Step 2 的 Agent 不调用工具

原因：工具描述不够清晰，LLM 不知道什么时候该用。
解决：检查 tools/ 目录下 TOOLS 的 description 字段，写得更具体。
  好的："当用户询问数学计算时使用此工具"
  差的："一个工具"

❌ ImportError: No module named 'tools'

原因：Python 找不到 tools 模块。
解决：
  1. 确保从项目根目录运行脚本（如 agent-builder/ 目录下）
  2. 不要用 cd tools/ && python ../step02_tool_system.py

❌ Windows 终端中文乱码

原因：CMD 或 PowerShell 编码问题。
解决：
  1. 使用 Windows Terminal（微软商店免费下载）
  2. 或在脚本开头加：
     import sys; sys.stdout.reconfigure(encoding='utf-8')

模型相关

❌ 模型不支持 Function Calling

报错特征：工具调用不生效，或 API 返回 400。
原因：某些模型（如 gpt-3.5-turbo-instruct）不支持 tools 参数。
解决：换成支持 Function Calling 的模型：
  推荐：gpt-4o-mini / gpt-3.5-turbo / deepseek-chat / qwen-turbo

❌ gpt-3.5-turbo 太贵

解决：换更便宜的模型。
  DeepSeek:  export OPENAI_BASE_URL="https://api.deepseek.com/v1"
             model="deepseek-chat"
  通义千问:  model="qwen-turbo"
  智谱:      model="glm-4-flash"
  本地模型:  export OPENAI_BASE_URL="http://localhost:11434/v1"

环境变量

❌ 每次开新终端都要重新设 OPENAI_API_KEY

解决：
  1. 写入 shell 配置文件（永久生效）：
     echo 'export OPENAI_API_KEY="sk-你的key"' >> ~/.bashrc
     source ~/.bashrc
  2. 或创建 .env 文件（需要 pip install python-dotenv）：
     echo 'OPENAI_API_KEY=sk-你的key' > .env
     代码里加：from dotenv import load_dotenv; load_dotenv()

还是解决不了？

  1. 复制完整报错信息
  2. 在 GitHub Issues 提问
  3. 或者直接问 AI："我跑 agent-builder 的 step01 时遇到这个错误：[粘贴报错]"