HelloMeng
← Back to 文字
AI 应用开发课程 · 月份 1 · 附录

常见报错排查

Published2025.10.11 Words 815 Reading ~ 3 min

本文来自《AI 应用开发课程》月份 1 课程文档，已整理为网站文章版本。

1. command not found: uv

现象

终端执行 uv --version 时报错。

常见原因

  • 没安装 uv
  • 安装后终端环境变量还没刷新

排查步骤

  1. 先执行 brew install uv
  2. 关闭并重新打开终端
  3. 再执行 uv --version

2. ModuleNotFoundError

现象

运行 Python 代码时找不到某个包。

常见原因

  • 依赖没有安装
  • 没进入正确的虚拟环境
  • 项目解释器选错了

排查步骤

  1. 执行 uv sync
  2. 执行 uv run python -c "import 包名"
  3. 检查编辑器当前解释器是否为项目虚拟环境

3. 401 Unauthorized

现象

调用 DeepSeek API 时鉴权失败。

常见原因

  • API Key 写错
  • 环境变量没有正确加载
  • 请求头格式错误

排查步骤

  1. 检查 .env 中的 DEEPSEEK_API_KEY
  2. 确认代码确实读取到了环境变量
  3. 确认请求头中包含 Authorization: Bearer <key>

4. 404 Not Found 或模型不存在

常见原因

  • base_url 写错
  • 模型名写错
  • 使用的接口路径与 SDK 版本不匹配

排查步骤

  1. 检查 DEEPSEEK_BASE_URL
  2. 检查模型名称配置
  3. 先用最小示例请求验证，再接入你的项目封装

5. 422 Unprocessable Entity

现象

调用 FastAPI 接口时返回 422。

本质

请求数据和接口定义的 Pydantic 模型不匹配。

排查步骤

  1. 看接口的请求模型字段
  2. 检查字段名、类型、是否必填
  3. 打开 FastAPI 自动生成的 OpenAPI 文档核对

6. RuntimeError: asyncio.run() cannot be called from a running event loop

常见原因

  • 在已经有事件循环的环境中重复调用 asyncio.run
  • 在 FastAPI 或某些交互环境里误用同步入口方式

处理建议

  • 脚本入口用 asyncio.run
  • 框架内部直接使用 await
  • 不要在异步函数里再套 asyncio.run

7. 流式输出没有任何内容

常见原因

  • 没有正确遍历流式返回对象
  • 流式数据片段拼接逻辑有误
  • 前端或客户端没有按流式方式消费

排查步骤

  1. 先打印每个 chunk
  2. 确认 chunk 中的实际字段名
  3. 先在终端脚本验证流式逻辑，再接入 FastAPI

8. Tool Calling 一直失败

常见原因

  • 工具定义和实际执行函数不一致
  • 参数 schema 与函数参数不匹配
  • 模型返回的工具名程序未注册

排查步骤

  1. 打印模型返回的工具调用内容
  2. 检查注册表中的工具名
  3. 检查参数字段是否对齐
  4. 先只保留一个最简单的工具验证最小闭环

9. pytest 没发现测试

常见原因

  • 文件名不符合 test_*.py
  • 函数名不符合 test_*
  • 项目目录结构不规范

排查步骤

  1. 检查测试文件命名
  2. 执行 uv run pytest -q
  3. 如果测试仍未发现，检查当前工作目录

10. 什么时候应该先停下来排错

满足以下任一条件，应立即停下来排错，不要继续堆代码：

  • 接口定义和实际返回结构不一致
  • 你已经不清楚当前运行的是哪份代码
  • 同一个错误重复出现 3 次以上
  • 你正在复制更多代码试图“碰运气解决”
✦ Fin ✦