LangChain Learning Path

第 10 章：综合实战与公开部署 ​

章节定位 ​

前九章已经分别覆盖了基础概念、链式调用、Prompt、RAG、Agent、LangGraph，以及评估与调试。这一章的任务，是把这些分散能力整合起来，做成一个真正可以公开展示、可以持续维护的项目。

对于这个学习路径来说，最后一章不是“再加一点新概念”，而是把 AI 学习助手 从课程样例升级为一个可部署的公开作品。

配套示例 ​

  • 目录：examples/chapter-10
  • 入口：examples/chapter-10/main.py
  • 依赖：examples/chapter-10/requirements.txt
  • 运行：cd examples/chapter-10 && python3 main.py

示例层级与边界 ​

  • 层级：更真实的工程版
  • 本章重点：从交付和部署准备度角度看整个项目是否站得住，而不是再讲一个新的 LangChain API。
  • 不要误判：示例只是帮助你检查公开发布前的基本结构，不会替代真实部署流水线、CI/CD 和运行时监控。

本章目标 ​

学完这一章，你应该能：

  • 组织一个完整的 LangChain 学习项目结构
  • 明确前端、后端、示例代码和文档的边界
  • 将文档站部署到 GitHub Pages
  • 认识到哪些能力适合静态站，哪些必须放到外部后端
  • 为公开分享和后续迭代建立稳定工程结构

前置知识 ​

你应该已经理解：

  • LangChain 基础抽象
  • 基础链式应用
  • RAG 流程
  • Tool Calling 和 Agent
  • LangGraph 工作流
  • 最小评估和观测思路

这一章会把这些内容汇聚成一个能对外发布的整体。

核心概念 ​

1. 什么叫“综合实战” ​

综合实战不是把所有功能硬塞进一个页面，而是围绕一个清晰目标，把合适的技术放进合适的位置。

对于本项目，综合实战的目标是：

  • 让学习者能按章节学习
  • 让学习者能看懂主项目如何演进
  • 让学习者能在 GitHub Pages 上访问成品

2. 为什么部署是课程的一部分 ​

很多教程停在“本地跑通”。但真正的工程能力是：

  • 让别人访问得到
  • 让内容长期可维护
  • 让结构能继续扩展

如果没有部署，课程就只停留在个人笔记阶段。

3. GitHub Pages 的边界 ​

GitHub Pages 适合托管静态内容，比如：

  • Markdown 文档
  • 静态站点
  • 教程页
  • 章节导航

它不适合直接托管需要密钥和后端状态的运行逻辑。因此，涉及模型调用、工具执行、密钥管理的部分，应该放在独立后端服务中。

4. 交付物思维 ​

最终项目不是一份文档，而是一组交付物：

  • 可访问的站点
  • 清晰的学习路径
  • 可运行的示例代码
  • 可复用的项目结构
  • 可继续迭代的后端接口

分模块讲解 ​

10.1 AI 学习助手 的最终形态 ​

建议把整个项目拆成四个层次：

  • 内容层：docs/，存放章节正文、路线图、FAQ
  • 示例层：examples/，存放每章最小可运行代码
  • 服务层：backend/，存放第二阶段的在线实验接口
  • 资源层：shared/，存放 prompts、datasets、diagram 资产

这种拆法的好处是边界清晰：

  • 文档负责“学什么”
  • 示例负责“怎么写”
  • 后端负责“怎么在线跑”
  • 资源负责“共用什么”

10.2 公开站点应该长什么样 ​

一个适合公开的学习站，首页至少应该回答：

  • 这是什么项目
  • 怎么开始
  • 学习顺序是什么
  • 主项目如何演进

推荐页面结构：

  • 首页
  • 学习路线图
  • 章节列表
  • 项目主线说明
  • FAQ
  • 更新日志

如果后续增加交互实验，再补：

  • 在线试验页
  • 参数调节页
  • 结果对比页

10.3 静态站与后端的职责分离 ​

第一阶段先把静态内容做好，原因很简单：

  • 最快上线
  • 最稳定
  • 最容易分享

第二阶段再引入后端，原因也同样明确：

  • 模型密钥不能暴露在前端
  • 需要执行真实检索和工具调用
  • 需要控制限流和配额

所以推荐架构是：

  • GitHub Pages 负责前端文档站
  • 独立后端负责 LangChain 运行
  • 前端通过 API 调用后端

10.4 一个最小可交付项目该包含什么 ​

如果只做最小可交付版本，建议至少完成：

  • 首页
  • 学习路线图
  • 前 4 章核心内容
  • 每章一个最小示例
  • 一个贯穿式主项目说明页
  • GitHub Pages 自动部署

这足够让读者理解你的学习方法，也足够作为公开作品展示。

最小示例说明 ​

下面这个示例不是完整站点代码，而是展示“项目交付物怎么组织”的最小思路。

text
langchain-learning-path/
├─ docs/
│  ├─ index.md
│  ├─ guide/
│  ├─ chapters/
│  ├─ project/
│  └─ faq/
├─ examples/
│  ├─ chapter-01/
│  ├─ chapter-02/
│  ├─ chapter-03/
│  └─ ...
├─ backend/
└─ shared/

你可以把它理解为一条最小流水线：

  1. 读 docs/ 学习
  2. 看 examples/ 跑代码
  3. 到 backend/ 体验在线实验
  4. 返回 docs/ 对照理解

这个结构简单，但足以支撑一个中长期学习项目。

本章实践 ​

建议你按下面顺序完成收尾工作。

任务 1：整理站点入口 ​

完善首页内容，让它明确展示：

  • 项目简介
  • 学习路径
  • 主项目
  • 章节入口

任务 2：补齐章节索引 ​

保证每章都有统一命名和统一结构，便于后续接入 VitePress。

任务 3：整理示例代码目录 ​

确保 examples/chapter-01 到 examples/chapter-04 至少有基本 README 或可运行说明。

任务 4：写部署说明 ​

在项目中补一份部署说明，至少写清楚：

  • 如何构建静态站
  • 如何发布到 GitHub Pages
  • 哪些部分需要外部后端

任务 5：预留后端扩展口 ​

即便第二阶段后端还没实现，也要先把目录和职责划好，避免以后重构成本太高。

常见坑 ​

1. 一开始就把项目做得太重 ​

综合项目最容易失败的原因不是技术不够，而是范围过大。先做能公开展示的最小版本。

2. 把所有逻辑都塞进静态站 ​

静态站只适合内容和展示。真实模型调用和密钥管理必须分离。

3. 文档和代码脱节 ​

如果章节写了很多，但示例代码没有对应，学习路径就会断掉。

4. 没有统一主线 ​

如果每章都是独立小例子，读者很难形成整体认知。AI 学习助手 必须贯穿始终。

5. 只管上线，不管维护 ​

公开发布之后，真正重要的是后续能不能持续修正文档、补充示例和迭代内容。

练习题 ​

  1. 试着用一句话描述你的 AI 学习助手 最终要解决什么问题。
  2. 把你的项目拆成“内容层、示例层、服务层、资源层”，分别写出每层的职责。
  3. 设计一个首页信息架构，要求用户 30 秒内看懂怎么开始学习。
  4. 思考一下：哪些功能适合放在 GitHub Pages，哪些必须放在独立后端。
  5. 给出你自己的最小可交付版本清单，控制在 5 个条目以内。

本章总结 ​

这一章的重点不是“再学一个新技术”，而是把整个课程变成一个真实可发布的项目。

当 AI 学习助手 具备清晰结构、可访问站点、统一章节模板和可扩展后端边界时，这个学习路径才真正完成了从“知识整理”到“工程交付”的跃迁。

学完本章，你现在应该会 ​

  • 把整个学习路径整理成一个可公开访问的最小交付版本
  • 说明内容层、示例层、服务层、资源层各自负责什么
  • 判断哪些能力适合继续放在静态站，哪些必须留给独立后端
  • 给 AI 学习助手 写出一个范围可控的最终交付清单

最小验收 checklist ​

  • [ ] 我能用一句话讲清楚这个项目最终要解决什么问题
  • [ ] 我已经梳理出站点入口、章节结构、示例目录和部署说明之间的关系
  • [ ] 我知道当前 phase 1 的交付边界在哪里，没有把后端能力混进静态站承诺里
  • [ ] 我能列出一个 5 项以内的最小可交付版本清单

建议你动手改一版 ​

  • 给首页草拟一版 30 秒内能看懂的入口信息架构
  • 选 1 到 2 章检查章节结构是否完全统一，提前为站点接入 VitePress 做准备
  • 写一个最短部署说明草稿，只覆盖静态站构建和 GitHub Pages 发布流程

卡住时先回看这里 ​

下一步 ​

如果你继续扩展这个项目，接下来最值得做的事情不是再加一堆新功能，而是：

  • 把 docs/ 接到 VitePress
  • 把 examples/ 里的示例补成可运行代码
  • 再把最核心的实验页接到独立后端

这样，整个学习站就会从设计稿变成一个真正可以长期使用的产品。