| layout | default |
|---|---|
| title | LangChain Tutorial Zero |
| description | 一套面向初学者的中文 AI 辅助编程教程：用任务卡、苏格拉底式 prompt、可执行参考与卡点日志学习 LangChain、LangGraph 和 LangSmith。 |
| image | /assets/og-tutorial-zero.png |
| last_modified_at | 2026-07-11 |
LangChain Tutorial Zero 面向刚接触 AI 应用开发的中文学习者。你不会从复制完整答案开始，而会沿着 16 篇任务卡，在自己的 _scratch/ 里动手、对照、解释，再把卡点留下来。
English summary. A Chinese, beginner-oriented learning system for LangChain, LangGraph, and LangSmith. Sixteen guided lessons pair Socratic AI prompts with hands-on tasks, executable references, self-checks, and a learning journal.
$ goal 理解 StateGraph，不复制完整答案$ ask-ai 先用“地铁线路图”类比，只问我一个问题
✓ build _scratch/my_graph.py ✓ compare final/02_langgraph/01_simple_graph.py ✓ explain 为什么条件边决定下一站
→ journal: 写下卡点与“原来如此”时刻
- 01类比先建立角色直觉
- 02补代码只填关键一格
- 03自检解释为什么
- 04日志留下迁移线索
地铁类比 Prompt 是目的地说明，模型客户端是把这张说明送进模型、再把回复带回来的列车。
哪一个名字应该填进模型客户端的位置？llm = _____(
model="qwen-plus"
)
reply = llm.invoke("用一句话介绍你自己")先选择一个答案；这里只检查角色判断，不会调用外部模型。
正确答案是 ChatOpenAI。启用 JavaScript 后可以体验选择、自检与日志解锁。
官方文档擅长告诉你 API 是什么，却默认你已经理解 Agent、State、Trace 等上下文；聊天机器人又很容易直接交付一段完整代码，让“能运行”掩盖“没理解”。
教程把 AI 放在“陪练”位置。它可以换类比、拆小问题、提供候选根因，但关键代码、差异判断和学习日志由学习者完成。
先说清概念在解决什么问题，再把实现拆成 3–5 个可回答的小步骤。
自己的代码只写进 _scratch/；任务卡提供约束，不直接交付完整答案。
对照 final/ 时先判断差异是否影响结果，再由学习者自己修正。
把“原来如此”、有效 prompt 和未解决问题写入 journal，变成下一次可复用的经验。
“周”是内容分组，不是完成承诺。每篇的分钟数是仓库中的学习节奏估算，真实耗时取决于 Python 基础、网络和 API 权限。
公开证据区分当前静态检查与 2026-05-29 的历史 API 实测；需要外部凭证的行为不会被本站构建冒充为已重新验证。
- Build当前静态契约 · Verified课程数量、页面结构、链接、Python 语法与发布门禁在本轮重新检查。
- History外部 API 跑批 · Observed 2026-05-2914 个入口的历史结果为 12 PASS / 1 PARTIAL / 1 SKIP，保留环境与凭证限制。
- External当前模型服务状态 · Unknown未在 Pages 构建中重新调用收费 API，因此不声称今天仍全部可运行。
历史记录逐项列出耗时、输出与限制。PARTIAL 来自本机 SSL 环境，SKIP 来自 embedding 权限；本次前端重构没有把它们重新宣称为通过。
查看真实运行记录 Compatibilityrequirements.txt 固定 LangChain 1.3.2、LangGraph 1.2.2 与 LangSmith 0.8.7；迁移原因保留在测试档案。
Pages 发布前会核对课程数量、元数据、唯一 H1、内部链接，并对全部参考 Python 文件执行语法编译检查。
CI · source + rendered output- 先跑参考，描述自己观察到的输入与输出。
- 挖空关键步骤，在
_scratch/写自己的版本。 - 故意制造一个错误，再解释它暴露的机制。
- 对照 final，自检并写下卡点日志。
先读 HOW_TO_LEARN_WITH_AI.md，理解为什么不直接向 AI 要完整代码。
按 SETUP.md 建立虚拟环境与本地 .env；真实 API Key 不进入仓库。
从 01_hello_llm.md 开始，把自己的实现写进 _scratch/。
面向框架初学者，不代替 Python 基础；至少应能阅读函数、列表、字典与异常信息。
示例固定在仓库声明的 1.x 版本，不承诺跟随 LangChain 最新 API；升级需要重新跑批。
完整运行依赖 DashScope、LangSmith、网络与模型权限；API 费用、延迟和可用性不由本仓库控制。
站点展示契约、内部链接和 Python 语法检查均可在不提供 API Key 的情况下运行：
bundle install
JEKYLL_ENV=production bundle exec jekyll build
ruby scripts/check-showcase.rb --built _site
bundle exec htmlproofer _site --disable-external --no-enforce-https \
--swap-urls '^/langchain-langgraph-langsmith-tutorial:'
python3 -m compileall -q final
bash -n scripts/smoke-test.sh需要模型与 LangSmith 凭证的 14 个入口由 bash scripts/smoke-test.sh 执行。它会调用外部服务、产生时延或费用，因此不属于 Pages 构建；运行前请先按 SETUP.md 配置本地 .env。历史结果见 docs/test-runs.md。
- 教程卡点：提交 Issue，说明在哪一步、预期什么、实际发生什么。
- 新的兼容性错误：补充 debug recipes 与复现条件。
- 真正有效的学习 prompt：补充 prompt cheatsheet。
- 完成 4 周后：从 7 个开放挑战 里选一个继续构建。
本项目使用 MIT License。