推荐资源 & 避坑指南

📚 推荐学习资源

Python 入门

资源	类型	适合阶段	评价
《Python Crash Course》	书	Week 1	从 JS/TS 转 Python 的最佳入门书，前 10 章一周搞定
Python 官方教程	文档	Week 1	权威但枯燥，当字典查
Real Python	网站	全程	高质量 Python 教程，有免费有付费

FastAPI

资源	类型	评价
FastAPI 官方文档	文档	必看！写得非常好，跟着 Tutorial 敲一遍就行
FastAPI 中文文档	文档	官方中文翻译
FastAPI 源码	GitHub	作者的代码质量极高，学习 Pydantic 用法

AI / LLM 基础

资源	类型	评价
DeepLearning.AI - LangChain Course	Coursera 课程	Andrew Ng 出品，免费旁听，概念讲得清楚
Prompt Engineering Guide	网站	Prompt 速查手册，用到的时候翻
AI Actuality	YouTube	技术向的 AI 新闻和教程

LangChain / LangGraph

资源	类型	评价
LangChain 官方 Getting Started	文档	动手教程，跟着做
LangGraph 官方 Tutorials	文档	重点看！图编排的最佳实践
LangChain Cookbook	GitHub	各种场景的代码模板

RAG

资源	类型	评价
RAG From Scratch	YouTube	从零手写 RAG 的好视频
ChromaDB 官方文档	文档	本地向量库，API 简单
Sentence Transformers	文档	Embedding 模型，支持中文

Agent 进阶（Month 3+）

资源	类型	评价
LangSmith	平台	Agent 可视化调试和追踪
AutoGen	GitHub	微软的多 Agent 框架
CrewAI	GitHub	另一个多 Agent 框架

实用工具

工具	用途
SiliconFlow	国内 LLM API（免费额度够用）
Deepseek	另一个国内 LLM
ChromaDB	本地向量数据库
Docker Desktop	容器化部署
Railway	免费云部署
Postman	API 测试

🚨 避坑指南（Month 1-3 真实踩过的坑）

🔴 致命坑（直接报错）

坑	现象	原因	解决方案
异步混用 sync/async	`run method is not supported with async db`	底层 DB 是 async 实现却调用了同步方法	统一用 `arun()` / `astream()` 全套异步链路
Python 版本不匹配	导入报语法错误	项目要求 3.11+，但装了 3.10	检查 `.python-version`，确保 `python --version` ≥ 3.11
导入路径错	`ModuleNotFoundError: No module named 'app'`	`PYTHONPATH` 没设对	在项目根目录运行，或设 `PYTHONPATH=.`
PowerShell 执行策略	激活 .venv 报错	Windows PowerShell 默认禁止执行脚本	`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

🟠 中度坑（运行但效果不对）

坑	现象	原因	解决方案
Agent 输出不治理	中间步骤（thinking、tool 调用）全部暴露给用户	LangGraph 默认展示中间事件	用框架的 `show_members_responses=False` 或只取最终节点输出
Agent 陷入循环	LLM 反复调用同一个工具不结束	工具返回格式有问题，LLM 没拿到预期结果	检查工具的返回值，加 `recursion_limit`
RAG 检索不准	明明有相关文档但搜不到	chunk 太大/太小、Embedding 模型不匹配	调 `chunk_size`（推荐 300-800），中文内容用中文 Embedding 模型
流式输出不流	等了几秒然后整块吐出	Nginx/Cloudflare 缓冲、没设置 SSE header	加 `X-Accel-Buffering: no`，Nginx 配 `proxy_buffering off`
多轮对话没记忆	每次对话都像新开始	`thread_id` 每次都不一样	前端要保存 session_id 并在每次请求传回
工具描述写得差	Agent 不会调用该工具	`@tool` 的 docstring 对工具能力描述不清楚	把工具的功能、参数都写在 docstring 里，让 LLM 看懂

🟡 轻度坑（体验不好）

坑	现象	原因	解决方案
uv 在本机不可用	`os error 267` 缓存目录重命名失败	企业透明加密策略拦截	用 pip 代替 uv，绕开加密层
pip install 慢	下载依赖很慢	网络原因	`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple` 用清华镜像
ChromDB 持久化失败	重启后向量库数据丢失	没指定 `persist_directory` 或目录没写权限	确保传了 `persist_directory=./chroma_db` 且目录可写
Prompt 改了没效果	重启后还是旧 Prompt	代码里硬编码了 Prompt 字符串	把 Prompt 存成 `.txt` 文件或配置项，git 管理
LangChain 方法名记不住	不断试不存在的方法名	API 更新快，版本差异大	先看 `.venv\Lib\site-packages\langgraph\__init__.py` 确认导出了什么

🛡 加密层/杀软排查经验

这是你项目环境的特殊情况，记录下来避免以后再踩。

先查实际运行的驱动服务：Get-CimInstance Win32_SystemDriver | Where-Object { $_.PathName -match '加密|安全|DLP|EDR' }
任务管理器无进程 ≠ 未运行：端控/DLP 以驱动形态存在，没有用户态进程
判断拦截按进程还是按路径：
- 换缓存路径测试（换 UV_CACHE_DIR 到其他盘）
- 二进制改名对照（改 uv.exe 名字看表现）
"加排除后成功" ≠ 排除项起效：必须在排除项在位的状态下复现失败，才能定因果
元数据大小差 512 字节 = 透明加密文件头特征

🧪 调试方法论

场景	推荐做法
Agent 行为不符合预期	打开 LangSmith（免费）可视化追踪每一步，看 LLM 到底返回了什么
工具调用不正常	在 `@tool` 函数里加日志，打印入参和返回值
RAG 检索不准	单独测试 `retriever.invoke(question)` 看返回了什么文档
LLM 返回格式不对	强制用 `response_format`（OpenAI）或加 JSON 格式约束
性能慢	用 LangSmith 看哪一步耗时最长，Embedding 是常见瓶颈
线上 Bug 难复现	记录每次对话的完整 messages 和 trace_id，方便回溯