✦ YangYang
随记

API调用故障排查笔记

·10 min read

API 调用故障排查笔记

更新时间：2026-08-12

这次遇到过的主要问题

1. 页面报 timeout，但后端接口其实返回正常

表现：

  • 小程序页面提示超时
  • 但后端日志里能看到 GET /api/review-insights 200 OK

结论：

  • 不能只看前端提示
  • 要以“后端有没有收到请求、有没有正常返回”为准

这次的关键日志：

1
2
INFO:app.main:review_insights:done records=7 elapsed_ms=1.8
INFO:     127.0.0.1:62034 - "GET /api/review-insights HTTP/1.1" 200 OK

说明回顾接口本身没有超时

2. 接口 200，但实际上没有调用到 AI

表现：

  • 页面有内容
  • 但内容像模板，不像 AI 真正生成

根因：

  • 接口虽然返回了
  • 但走的是 fallback，而不是 DeepSeek

这次后来专门加了标记：

1
review_insights:done records=7 ai_used=False

经验：

  • HTTP 200 不等于 AI 生效
  • 要额外区分“接口成功”和“模型真的调用成功”

3. .env 里明明写了 API_KEY，代码却读不到

表现：

  • BASE_URL、MODEL 能读到
  • API_KEY 读不到
  • 后端日志出现：
1
WARNING:app.ai:chat:missing_api_key base=https://api.deepseek.com model=deepseek-chat

根因：

  • .env 文件第一行带 BOM
  • 实际解析出来的键名不是 API_KEY
  • 而是 \ufeffAPI_KEY

验证方式：

1
python -c "from dotenv import dotenv_values; from pathlib import Path; cfg = dotenv_values(Path(r'D:\WeChatProjects\server\.env')); print(list(cfg.keys()))"

这次实际查到的是：

1
['\ufeffAPI_KEY', 'BASE_URL', 'MODEL', 'EMBEDDING_API_KEY', 'EMBEDDING_BASE_URL', 'EMBEDDING_MODEL']

解决方式：

  • 把 server/.env 重新保存成 UTF-8 无 BOM

验证修复是否生效：

1
2
cd D:\WeChatProjects\server
python -c "from dotenv import load_dotenv; from pathlib import Path; import os; load_dotenv(Path('.env')); print(bool(os.getenv('API_KEY')), os.getenv('BASE_URL'), os.getenv('MODEL'))"

正确结果应类似：

1
True https://api.deepseek.com deepseek-chat

4. 真机调试失败，因为还在请求 127.0.0.1

表现：

  • 开发者工具里能用
  • 真机调试全部失败
  • 控制台里请求地址还是：
1
http://127.0.0.1:8000/api/...

根因：

  • 在电脑上，127.0.0.1 指当前电脑
  • 在真机上，127.0.0.1 指手机自己

解决方式：

  • 改成电脑的局域网 IP

这次电脑实际可用 IP：

1
192.168.0.XXX

所以真机调试应该请求：

1
http://192.168.0.XXX:8000

后端启动也必须用：

1
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

5. 配置明明修好了，但运行结果还是旧的

表现：

  • 本地单独测试函数已经成功
  • 页面里仍然像旧逻辑

根因：

  • 旧的 uvicorn 进程或 reload 子进程没彻底退出

解决方式：

  1. 先停掉后端
  2. 确认没有残留 Python 进程
  3. 再重新启动

检查方式：

1
Get-Process python | Select-Object Id, ProcessName, Path

如果还有旧进程，要先停掉再重启

6. WXSS/WXML/JS 编译报乱码

表现：

  • 小程序编译报：
1
unexpected `�` at pos 1

根因：

  • 文件开头带 BOM
  • 或者文件被 Windows/终端错误编码写坏

处理方式：

  • 统一保存成 UTF-8 无 BOM
  • 尤其是：
    • .env
    • .wxss
    • .wxml
    • .js

这次最终确认打通的调用链

回顾页

成功日志：

1
2
3
INFO:httpx:HTTP Request: POST https://api.deepseek.com/chat/completions "HTTP/1.1 200 OK"
INFO:app.ai:chat:ok model=deepseek-chat elapsed_ms=5359.4
INFO:app.main:review_insights:done records=7 ai_used=True elapsed_ms=5372.6

说明：

  • 回顾页已经真实调用了 DeepSeek
  • 不再只是 fallback

问问页

成功日志：

1
2
3
4
INFO:httpx:HTTP Request: POST https://api.voyageai.com/v1/embeddings "HTTP/1.1 200 OK"
INFO:app.ai:embed:remote_ok model=voyage-4-lite count=1 elapsed_ms=1066.7
INFO:httpx:HTTP Request: POST https://api.deepseek.com/chat/completions "HTTP/1.1 200 OK"
INFO:app.ai:chat:ok model=deepseek-chat elapsed_ms=1499.6

说明：

  • 问问页已经真实调用了 Voyage Embedding
  • 也真实调用了 DeepSeek 聊天

标准排查顺序

以后再遇到 API 调用问题，建议按这个顺序查

第 1 步：看请求有没有打到后端

看 uvicorn 终端里是否出现：

  • GET /api/...
  • POST /api/...

如果根本没有，优先查：

  • 请求地址
  • 端口
  • 服务是否启动
  • 真机是否还在访问 127.0.0.1

第 2 步：看接口返回状态

重点看：

  • 200 OK
  • 4xx
  • 5xx

第 3 步：看有没有真正调用外部模型

重点看：

  • chat:ok
  • chat:missing_api_key
  • chat:failed
  • embed:remote_ok
  • embed:remote_failed

第 4 步：确认是不是 fallback

重点看：

  • ai_used=True
  • ai_used=False

第 5 步：验证 .env 是否真的生效

不要只看文件内容，要直接跑：

1
python -c "from dotenv import load_dotenv; from pathlib import Path; import os; load_dotenv(Path('.env')); print(bool(os.getenv('API_KEY')))"

第 6 步：检查文件编码

如果是：

  • .env
  • .js
  • .wxml
  • .wxss

出现奇怪乱码、首字符报错、变量读不到，都要怀疑 BOM 或编码

第 7 步：彻底重启服务

不要默认热更新一定可靠

实用命令备忘

启动后端

1
2
cd D:\WeChatProjects\server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

验证 .env 里的聊天配置是否读到

1
2
cd D:\WeChatProjects\server
python -c "from dotenv import load_dotenv; from pathlib import Path; import os; load_dotenv(Path('.env')); print(bool(os.getenv('API_KEY')), os.getenv('BASE_URL'), os.getenv('MODEL'))"

验证当前代码看到的聊天 / embedding 配置

1
2
cd D:\WeChatProjects\server
python -c "from app.ai import _chat_cfg, _embed_cfg; k,b,m=_chat_cfg(); ek,eb,em=_embed_cfg(); print('chat_has_key=', bool(k)); print('chat_base=', b); print('chat_model=', m); print('embed_has_key=', bool(ek)); print('embed_base=', eb); print('embed_model=', em)"

查电脑局域网 IP

1
ipconfig

查是否有残留 Python 进程

1
Get-Process python | Select-Object Id, ProcessName, Path

总结

  1. 页面超时，不一定是后端超时
  2. 接口 200，不一定真的用了 AI
  3. .env 有值，不等于运行时真的读到了
  4. 真机失败，第一时间先看请求 URL
  5. Windows 下 BOM 和编码问题非常高频
  6. 热更新不可靠时，要彻底重启进程