09 · 常见问题与排错手册

本篇不用按顺序读,遇到问题时当字典查。前半部分教你"排错方法论"(学会它,大部分问题不用查表),后半部分是按症状分类的速查表,覆盖三个项目实测最常见的坑。

一、排错方法论:三步定位法

第 1 步:读懂 Traceback(90% 的答案就在报错里)

Python 报错时打印的一大段红字叫 Traceback,从下往上读:

Traceback (most recent call last):
  File "main.py", line 12, in <module>          ← 调用链起点
    agent = get_trip_planner_agent()
  File "app/agents/trip_planner_agent.py", line 164, in __init__   ← 出错前最后经过你的代码的地方
    self.amap_tool = MCPTool(...)
  File ".../hello_agents/tools/mcp_tool.py", line 88, in __init__  ← 框架内部(一般不是你的锅)
    ...
FileNotFoundError: [Errno 2] No such file or directory: 'uvx'     ← ★最后一行:错误类型+原因

读法口诀:

最后一行告诉你"什么错"(FileNotFoundError: uvx 找不到 → uv 没装或不在 PATH)
从下往上找到第一个属于你项目的文件,那就是"哪里触发的"(上例是 trip_planner_agent.py 第 164 行)
中间穿过框架源码的行,通常只是"路过",别急着怀疑框架有 bug

常见错误类型速记:

最后一行开头	大概率原因
`ModuleNotFoundError`	包没装,或装错了虚拟环境
`FileNotFoundError`	路径/命令不存在(.env 没建、uvx 没装、工作目录不对)
`KeyError` / `AttributeError: 'NoneType'`	拿到的数据缺字段——常见于 LLM 输出不合格或 API 返回错误结构
`json.JSONDecodeError`	字符串不是合法 JSON——LLM 输出解析失败
`ValidationError`(pydantic)	数据结构不符合模型定义,看它列出的具体字段
`ConnectionError` / `TimeoutError`	网络:地址错、服务没起、代理/防火墙
`401 Unauthorized` / `AuthenticationError`	API Key 错误或过期
`429` / `RateLimitError`	触发限流,稍等或降低并发

第 2 步:确定问题在哪一段

三个项目的链路都是:前端 → 后端 → Agent/框架 → 外部服务(LLM/高德/搜索)。二分法定位:

后端 /docs 页面直接调接口,绕开前端。/docs 里就能复现 → 前端无辜,查后端;/docs 里正常 → 查前端(F12 控制台 + Network 面板)
后端里再看终端日志打印到了哪一步(项目一每个 Agent 步骤都有打印;项目二有 loguru 日志;项目三有对话日志 python view_logs.py tail)
怀疑外部服务时,写 5 行的最小脚本单测它(比如第 02 篇的 test.py 单测 LLM 连通性)

第 3 步:最小复现

把出问题的一步从项目里抠出来,写成独立小脚本复现。能复现 → 盯着这一小段解决;不能复现 → 问题在上下文(环境变量、工作目录、并发),对比两边差异。

提问的智慧:向别人(或 AI)求助时,贴上完整 Traceback + 你执行的命令 + 你已排除的可能性,而不是一句"报错了跑不起来"。

二、环境与安装类

Q:command not found: uv / uvx 刚装完没重开终端(装完必须开新终端);或 PATH 没配上。macOS/Linux 检查 ~/.local/bin 是否在 PATH:echo $PATH。Windows 重开 PowerShell。

Q:requires-python >=3.10 或装依赖时各种版本冲突 Python 版本太老。python3 --version 确认 ≥3.10;uv 用户可直接 uv venv --python 3.12 让 uv 帮你下对应版本。

Q:ModuleNotFoundError: No module named 'hello_agents',但我明明装了 装进了 A 环境,运行时用的 B 环境。检查:which python(Windows: Get-Command python)是否指向项目的 .venv。最稳的办法:统一用 uv run python main.py 跑,永远不会用错环境。PyCharm 用户检查右下角解释器是否选了项目 .venv。

Q:pip install / uv pip install 卡住或超时 换国内源:uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。npm 同理换 npmmirror(见第 02 篇)。

Q:git clone GitHub 超时 用加速前缀:git clone https://ghfast.top/https://github.com/datawhalechina/hello-agents.git,或开代理。

Q:端口被占用 Address already in use 上一个后端没关干净。找到并杀掉: macOS/Linux lsof -i :8000 拿到 PID 后 kill <PID>;Windows netstat -ano | findstr 8000 后任务管理器结束进程。或干脆换端口启动。

三、LLM 调用类(三个项目通用)

Q:401 Unauthorized / Invalid API key Key 抄错(首尾多空格/引号)、Key 过期、或 Key 和 BASE_URL 不是同一家(拿 DeepSeek 的 Key 打 ModelScope 的地址)。对照第 02 篇的表格,三件套必须同源:

LLM_MODEL_ID / LLM_API_KEY / LLM_BASE_URL   ← 三者必须来自同一服务商

Q:404 Not Found 或 model not found 模型名写错。ModelScope 要写全称 Qwen/Qwen2.5-72B-Instruct(带组织前缀);DeepSeek 是 deepseek-chat。另一个 404 来源:BASE_URL 少了或多了路径,注意有的服务商要 /v1 结尾、有的不要,以各家文档为准。

Q:改了 .env 不生效 后端要重启才会重新读 .env(--reload 只监听代码文件不监听 .env);确认 .env 和启动目录的相对位置(项目三是 backend/.env,项目二是 backend/.env 而启动在 backend/src——它内部处理了,但你自己写脚本时要注意 load_dotenv() 找的是当前工作目录)。

Q:429 Too Many Requests 免费额度限流。项目二并发跑多个任务最容易触发——降低任务数(改规划提示词)或加并发限制(第 06 篇练习 4 的 Semaphore),或换个额度更宽的服务商。

Q:回复是英文/格式跑偏/JSON 老是解析失败 换更强的模型(7B 换 72B 立竿见影);把 temperature 调低;检查提示词里的 JSON 模板是否被你改坏。记住链路:解析失败 ≠ 代码 bug,大概率是模型输出质量问题——项目一会静默走 fallback 计划(景点名是"北京景点1"就是这个信号)。

四、项目一(旅行助手)专属

Q:启动时卡在"创建共享MCP工具"或报 FileNotFoundError: 'uvx' 容器/环境里没有 uv。pip install uv 或确认 requirements 装全。首次启动 uvx amap-mcp-server 要联网下载该包,慢是正常的,耐心等或先手动跑一次 uvx amap-mcp-server --help 预热缓存。

Q:景点搜出来是编的/后端日志显示工具调用失败 后端 .env 的 AMAP_API_KEY 填成了 JS API 的 Key。后端要 Web服务 Key。去高德控制台核对 Key 所属的服务平台类型。

Q:前端地图空白/控制台报 INVALID_USER_SCODE 前端 .env 的 Key 填成了 Web服务 Key(和上一条正好相反),或 JS API Key 配置了安全密钥但没一起配置。前端要 Web端(JS API) Key。

Q:生成计划要好几分钟,是不是卡死了? 四个 Agent 串行 + 每个都要调 LLM,1~3 分钟正常。盯后端终端:步骤 1→2→3→4 在推进就没卡。想提速做第 05 篇练习 4(并发化前三步)。

Q:返回的行程全是"北京景点1"这种占位名 走了 _create_fallback_plan 兜底 = 第四步的 JSON 解析失败了。往上翻日志找"解析响应失败"前后的原始输出,通常是模型没按模板输出 JSON,参考"LLM 调用类"最后一条。

五、项目二(深度研究)专属

Q:uv sync 报错 确认在 backend/ 目录执行(要有 pyproject.toml 和 uv.lock);uv 版本太老就 uv self update。

Q:搜索永远 0 结果,任务全部 skipped DuckDuckGo 在部分网络环境不可达。方案一:挂代理;方案二:申请 Tavily Key,.env 改 SEARCH_API='tavily' + TAVILY_API_KEY=tvly-xxx。

Q:前端一直转圈,收不到任何事件 先 F12 → Network → 找 stream 请求:状态是不是 200、EventStream 标签里有没有事件进来。有事件但页面不动 → 前端解析问题;请求都没发出去 → 检查前端 API 地址;发了但 pending → 后端卡住,看后端日志到哪一步。

Q:本地直连正常,套了 Nginx 后打字机效果消失/一次性蹦出全部 Nginx 默认缓冲响应。SSE 的 location 必须加 proxy_buffering off;(见第 08 篇)。

Q:报告是英文的 规划/总结/报告的提示词在 src/prompts.py,在相应 instructions 里加一句"必须使用中文撰写"。

六、项目三(赛博小镇)专属

Q:首次启动卡在下载模型/报 Connection to huggingface.co timed out 记忆系统首次运行要从 HuggingFace 下载本地 embedding 模型(约 90MB)。设置国内镜像后重启:export HF_ENDPOINT=https://hf-mirror.com(Windows PowerShell: $env:HF_ENDPOINT="https://hf-mirror.com";建议写进 ~/.zshrc 永久生效)。

Q:游戏里按 E 没反应/对话发不出去 分层排查:① 后端起了吗(http://localhost:8000/docs 能开吗);② scripts/config.gd 里的地址对吗;③ Godot 编辑器下方"输出"面板有没有红色报错(HTTP 错误都会打在这)。

Q:NPC 回复"当前为模拟模式,请配置API_KEY" 后端没读到 LLM_API_KEY。确认 backend/.env 存在且填了值,重启后端,启动日志应有"✅ LLM初始化成功"而不是警告。

Q:NPC 把三个人的记忆混在一起了/记忆不生效 每个 NPC 的记忆独立存在 backend/memory_data/<NPC名>/memory.db。删掉某个目录 = 该 NPC 失忆重开。记忆检索有 min_importance=0.3 门槛,闲聊内容重要性低,检索不到是设计如此,不是 bug。

Q:好感度一直不变 好感度更新依赖 LLM 情感分析(analyze_and_update_affinity),模型太弱时判定全是 neutral。换强一点的模型,或用 PUT /npcs/张三/affinity?affinity=90 先手动验证"好感度→说话风格"链路是通的,再排查分析环节。

Q:Godot 打开项目报版本错误 项目要求 Godot 4.2+,3.x 完全不兼容。下载 4.x 标准版(非 .NET 版)。

七、前后端联调类(通用)

Q:浏览器控制台报 "blocked by CORS policy" 后端 CORS 白名单没包含前端实际地址。检查后端 CORS_ORIGINS 配置和前端真实端口(Vite 端口被占时会自动换成 5174!)。开发阶段图省事可先 ["*"] 全放行。

Q:接口返回 422 Unprocessable Entity 请求体不符合 Pydantic 模型。响应体里写得非常具体:哪个字段、什么错(missing / not a valid integer…)。对照后端 schemas.py/models.py 修正前端发送的字段名和类型。

Q:前端页面空白 F12 控制台看第一条红色报错:资源 404 → 构建/路径问题;Cannot read properties of undefined → 后端返回的数据结构和前端预期不符,去 Network 面板看真实响应体。

Q:Network 里请求是 (failed) net::ERR_CONNECTION_REFUSED 后端根本没起,或端口不对。先起后端,再刷新前端。

八、Docker/部署类

Q:容器里 Connection refused,本机直跑却正常 容器里的 localhost 是容器自己。容器互访要用 compose 服务名(如 http://backend:8000);容器访问宿主机用 host.docker.internal(Docker Desktop)。

Q:改了代码,重新 docker compose up 没变化 镜像没重建。带上 --build:docker compose up -d --build。

Q:容器起来秒退 docker compose logs backend 看崩溃原因,九成是 .env 没注入(env_file 路径错)或 CMD 里模块路径不对。

Q:云服务器部署后外网访问不了 按序检查:① 服务在跑(docker compose ps);② 服务器本机 curl http://localhost 通;③ 云控制台安全组放行 80 端口(最常漏的一步);④ 用 http://IP 而不是 https://(没配证书前)。

结语:这套文档学完之后

到这里,9 篇文档 + 3 个项目全部完成。你已经具备:用 uv 管理 Python 项目、读懂并改造多 Agent 系统、FastAPI + 前端联调、Docker 部署上线的完整能力闭环。

接下来的建议路线:

回到官方教材补理论:《Hello-Agents》的高级篇(记忆、上下文工程、通信协议、评估)会让你知其所以然
做自己的项目:把三个项目的零件重新组合——比如"带记忆的旅行助手"、"能深度研究的游戏 NPC"
参与开源:给 datawhalechina/hello-agents 提 Issue/PR,是最好的进阶方式

下一篇(面试前必读):10 · 进阶知识补全与面试指南

返回目录:README