langchain-masterclass

<p align="center"> <h1 align="center">LangChain 大师课</h1> <p align="center">一个全面、实践为主的课程，教你掌握 LangChain 生态系统 — 从第一个模型调用到智能代理。</p> </p> <div align="center"> [](https://www.python.org/) [](https://www.langchain.com/) [](LICENSE) </div> <div align="center"> []() []() []() []() </div> --- ## 目录 - [介绍](#-介绍) - [特点](#-特点) - [课程路线图](#-课程路线图) - [先决条件](#-先决条件) - [安装](#-安装) - [配置](#%EF%B8%8F-配置) - [运行实验](#%EF%B8%8F-运行实验) - [课程大纲](#-课程大纲) - [获得的技能](#-获得的技能) - [展示的最佳实践](#-展示的最佳实践) - [故障排除/常见问题](#-故障排除--常见问题) - [贡献](#-贡献) - [致谢](#-致谢) - [许可证](#-许可证) --- ## 🦜 介绍 **LangChain 大师课** 是一门结构化、以代码为先导的课程，教你如何使用 LangChain 生态系统构建复杂的 AI 应用。每个概念都基于一个自成体系的 Python 实验 — 没有幻灯片，没有空洞的理论讲解。 该仓库涵盖 18 个模块和 100+ 个独立的实验，带你从绝对基础（调用聊天模型）一直到构建可以调用实时 API、查询数据库、通过模型上下文协议发现工具并跨多步骤工具链推理的自主代理。每个实验都可以作为一个独立的脚本执行，只需一条命令即可运行。 ### 目标受众 本课程适用于 **学生、Python 开发人员、后端工程师和 AI 实践者**，他们希望构建真正的 LangChain 应用 — 而不仅仅是复制粘贴示例代码。无论你是转向 AI 工程、深化现有的 LangChain 技能集，还是构建 RAG 和代理系统所需的知识基础，本课程都提供了一条清晰、实用的路径。 | 受众 | 为什么适合 | |----------|---------------------| | **学生** | 将学术理论与行业标准的 AI 工程相结合 | | **Python 开发人员** | 熟悉 Python；希望在技能集中添加 AI/LLM 功能 | | **后端工程师** | 构建包含 LLM 驱动功能的 API 或服务 | | **AI/ML 实践者** | 了解理论；希望获得 LangChain 实现的实践经验 | | **数据工程师** | 对 RAG 管道、文档处理和语义搜索感兴趣 | ### 有什么不同？ 与专注于单个功能或直接从 LangChain 文档中借用示例的教程仓库不同，本课程从头开始构建每个概念，使用一致的代码库、共享的帮助程序实用程序和逐渐增加的挑战。**模型工厂** 抽象层使你可以仅需更改 `.env` 文件中的两行代码，就可以用 OpenAI、Anthropic Claude、Google Gemini、Ollama 或 HuggingFace 等运行每个实验。 --- ## ✨ 特点 - 📦 **18 个渐进模块** — 从你的第一个模型调用到完整的自主代理 - 🧪 **100+ 个可运行的实验** — 每个概念都是一个独立的可执行的 Python 脚本 - 🔌 **多提供商支持** — OpenAI、Anthropic、Google Gemini、Ollama、HuggingFace 等 - 🧬 **结构化输出** — Pydantic、TypedDict 和 JSON 模式驱动的提取 - 🗄️ **向量数据库** — InMemoryVectorStore、Chroma 和 FAISS，每个都有完整的 CRUD 支持 - 📚 **检索增强生成（RAG）** — 从基本管道到对话式聊天机器人和代理 RAG - 🔗 **模型上下文协议（MCP）** — 本地和远程工具发现和聚合 - 🤖 **代理** — 自定义代理循环、ReAct 风格的代理、SQL 代理和 RAG 代理 - ⚡ **异步、流式处理** — 使用 token-by-token 交付的非阻塞管道 - 📡 **回调** — 日志记录、成本跟踪和实时事件钩子 --- <p align="center"> 💡 如果你觉得这个仓库有帮助，请不要忘记给它 **加星（🌟）** — 这也能帮助其他人发现它！ </p> --- ## 📚 课程路线图 | 模块 | 主题 | 学习技能 | |--------|-------|----------------| | [`01_models`](./01_models) | 模型和嵌入 | ChatModel、温度、max_tokens、停止序列、多模态（图像输入）、LLM 缓存、嵌入向量、嵌入维度 | | [`02_prompts`](./02_prompts) | 提示工程 | 消息类型（系统/人类/AI/工具/聊天）、PromptTemplate、ChatPromptTemplate、多变量提示、少样本提示、基于长度的示例选择 | | [`03_chains`](./03_chains) | LCEL 链 | 简单的 LCEL 链、链中的输出解析器、多步骤顺序链、批量执行、顺序与批量性能基准测试 | | [`04_runnables`](./04_runnables) | LCEL 可执行单元 | RunnableSequence、管道运算符 `\|`、RunnableParallel、RunnableBranch、RunnableLambda（动态路由）、RunnablePassthrough、`.assign()`、备用链、运行时 ConfigurableField 和 ConfigurableAlternatives | | [`05_output_parsers`](./05_output_parsers) | 输出解析器 | StrOutputParser、CommaSeparatedListOutputParser、JsonOutputParser、XMLOutputParser、PydanticOutputParser、自定义 BaseOutputParser | | [`06_structured_output`](./06_structured_output) | 结构化输出 | JSON 模式绑定、TypedDict 模式、Pydantic 模式、嵌套 Pydantic 模型、`with_structured_output()` | | [`07_async_streaming`](./07_async_streaming) | 异步和流式处理 | `ainvoke`、`astream`（token-by-token）、`astream_events`（v2 事件过滤，基于运行名称） | | [`08_callbacks`](./08_callbacks) | 回调 | StdOutCallbackHandler、OpenAI token 和成本跟踪、自定义同步 BaseCallbackHandler、自定义异步 AsyncCallbackHandler | | [`09_memory`](./09_memory) | 内存和持久性 | 无状态聊天（演示遗忘）、手动消息列表、RunnableWithMessageHistory、SQLite via SQLChatMessageHistory、JSON 文件自定义历史、`trim_messages`、交互式内存聊天机器人、交互式 SQLite 聊天机器人 | | [`10_document_loaders`](./10_document_loaders) | 文档加载器 | TextLoader、CSVLoader、PyPDFLoader、WebBaseLoader、DirectoryLoader、SQLDatabaseLoader、WikipediaLoader | | [`11_text_splitters`](./11_text_splitters) | 文本分割器 | CharacterTextSplitter、RecursiveCharacterTextSplitter、TokenTextSplitter（tiktoken）、MarkdownHeaderTextSplitter、语言感知代码分割器、SemanticChunker | | [`12_document_transformers`](./12_document_transformers) | 文档转换器 | HTML 清洁和标签提取与 BeautifulSoupTransformer、语义重复过滤与 EmbeddingsRedundantFilter | | [`13_vector_stores`](./13_vector_stores) | 向量存储 | InMemoryVectorStore（CRUD）、Chroma（持久化，CRUD）、FAISS（保存/加载，CRUD）、相似性搜索类型（标准、MMR、得分、阈值） | | [`14_retrievers`](./14_retrievers) | 检索器 | WikipediaRetriever、VectorStoreRetriever、BM25Retriever、EnsembleRetriever（混合）、MultiQueryRetriever、ContextualCompressionRetriever（LLM 提取器）、ParentDocumentRetriever、MultiVectorRetriever（摘要索引）、FlashRank 重新排序 | | [`15_rag`](./15_rag) | RAG 管道 | 基本 RAG（PDF ingestion）、Wikipedia RAG（LCEL）、RAG + 消息历史 + 查询重写、RAG + Pydantic 引用、对话式 RAG 聊天机器人（CLI）、长上下文重新排序 | | [`16_tools`](./16_tools) | 工具和工具包 | DuckDuckGo/Wikipedia/PythonREPL/Requests 内置工具、`@tool` 装饰器、StructuredTool、BaseTool 类、手动工具调用循环、FileManagementToolkit、自定义 BaseToolkit、检索工具 | | [`17_mcp`](./17_mcp) | 模型上下文协议（MCP） | FastMCP 服务器、`@mcp.tool()`、STDIO 传输、MultiServerMCPClient、本地和远程（Streamable HTTP）工具发现、多服务器聚合 | | [`18_agents`](./18_agents) | 代理 | 自定义代理推理循环与工具调度、`create_agent`（内置 ReAct 风格）、`create_sql_agent`（自然语言转 SQL）、MCP 驱动的代理通过 `MultiServerMCPClient`、通过 `create_retriever_tool` 的检索工具 RAG 代理 | --- ## 📋 先决条件 - **Python 3.10 或更高版本** - **基本的 Python 熟练度**（函数、类、装饰器、`async/await`） - **熟悉 REST API 和 JSON**（在工具实验中使用） - **至少一个 LLM API 密钥**（OpenAI、Anthropic、Google）— 或 [Ollama](https://ollama.com) 安装 - **不需要先前的 LangChain 经验** --- ## 🚀 安装 ### 1. 克隆仓库 ```bash git clone https://github.com/zainulabidin1/langchain-masterclass.git cd langchain-masterclass ``` ### 2. 创建并激活虚拟环境 ```bash python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate ``` ### 3. 安装所有依赖项 ```bash pip install -r requirements.txt ``` ### 4. 配置环境 ```bash # macOS / Linux / Windows (PowerShell) cp .env.example .env # Windows (CMD) copy .env.example .env ``` 然后打开 `.env` 并填写您的凭证（参见下面的[配置](#%EF%B8%8F-配置)）。 --- ## ⚙️ 配置 所有配置都位于项目根目录的 `.env` 文件中。两个最重要的设置是 `LLM_MODEL_PROVIDER` 和 `LLM_MODEL_NAME`。 ```env # 选择您的 LLM 提供商："openai"、"google"、"ollama"、"anthropic"、"huggingface" LLM_MODEL_PROVIDER="ollama" LLM_MODEL_NAME="gpt-oss:120b-cloud" # 选择您的嵌入提供商："openai"、"google"、"ollama"、"huggingface" EMBEDDINGS_MODEL_PROVIDER="ollama" EMBEDDINGS_MODEL_NAME="nomic-embed-text" # API 密钥 - 只需填写您计划使用的密钥 OPENAI_API_KEY="" ANTHROPIC_API_KEY="" GOOGLE_API_KEY="" HUGGINGFACEHUB_API_TOKEN="" # 如果没有运行 Ollama，请留空 OLLAMA_BASE_URL="" # 标识您的请求发送到外部服务（例如 Wikipedia、WebBaseLoader） # 一些 API 拒绝或限制没有 User-Agent 的请求 - 可以保留默认值 USER_AGENT="LangChainMasterClass/1.0" ``` ### `_common/model_factory.py` 如何工作 `_common/model_factory.py` 模块是整个课程的骨架。它在启动时从环境中读取 `LLM_MODEL_PROVIDER` 和 `LLM_MODEL_NAME`，并公开三个工厂函数： | 函数名 | 返回值 | 备注 | |----------|---------|-------| | `get_chat_model(**kwargs)` | `BaseChatModel` | 支持 OpenAI、Google、Ollama、Anthropic、HuggingFace | | `get_embedding_model(**kwargs)` | `Embeddings` | 支持 OpenAI、Google、Ollama、HuggingFace | 所有 `**kwargs` 都直接转发到底层提供商类，因此您可以传递 `temperature`、`max_tokens`、`streaming` 或任何提供商特定的参数而无需修改工厂。这就是为什么每个实验都可以覆盖模型行为（例如 `get_chat_model(temperature=0.9)`）而无需触及提供商配置。 **实际上，每个实验都以相同的方式开始： ```python from _common.model_factory import get_chat_model # 整个代码库根据您的 .env 文件自动适应 model = get_chat_model(temperature=0) response = model.invoke("Hello, LangChain!") ``` 在 `.env` 中将 `LLM_MODEL_PROVIDER` 从 `ollama` 切换到 `openai` 或 `anthropic`，而无需更改任何代码 - 每个实验（而非代码更改）都运行在不同的提供商上。 --- ## ▶️ 运行实验 每个实验都是一个自包含的 Python 脚本。要运行任何实验，请激活您的虚拟环境并直接执行文件： ```bash # 示例：从模块文件夹运行 cd 01_models python lab_01_chat_model.py # 示例：从项目根目录运行 python 01_models/lab_01_chat_model.py ``` ### 推荐进度 按顺序完成模块。在每个模块中，实验按顺序编号（`lab_01`、`lab_02` 等），每个实验引入一个特定概念，后续实验在此基础上构建。 > **提示：** 如果您是 LangChain 的新手，请从 [模块 1](./01_models) （模型）开始并遵循路线图表从上到下。如果您已经熟悉 LCEL 和结构化输出，请直接跳转到 [模块 9](./09_memory) （内存）。 --- ## 🧩 课程 每个模块包括一个目的声明、实验的实验室分解和“关键 API”摘要。 📖 **请参阅 [课程大纲](CURRICULUM.md) 以获取完整的模块按模块的实验分解** 有关快速概述，请参阅上面的 [课程路线图](#-课程路线图) 表。 --- ## 🎓 获得的技能 完成本课程后，您将能够： - 构建和实现跨多个提供商的 LLM 管道，可以在 OpenAI、Anthropic、Google 和 Ollama 之间切换 - 使用 LCEL 组合复杂的数据转换和推理管道，使用并行、顺序、条件和备用模式 - 使用 Pydantic 模式、TypedDict 和 JSON 通过原生模型函数调用 API 从非结构化文本中提取结构化数据 - 使用 Python 的 async 生态系统构建非阻塞、token 流式 AI 服务 - 使用自定义回调进行日志记录、成本跟踪和实时 WebSocket 交付来仪器 LLM 管道 - 实现多会话、多后端对话内存（内存、SQLite、自定义 JSON） - 将文档从 PDF、数据库、Web 和文件系统摄入语义向量存储 -） - 设计和评估检索系统，使用向量搜索、BM25、混合集成、多查询、上下文压缩、父文档、多向量和交叉编码器重新排序策略 - 构建生产就绪的 RAG 管道，具备查询重写、引用提取和长上下文缓解功能 - 定义和组合工具，使用三种不同的抽象级别 (`@tool`、`StructuredTool`、`BaseTool`)，并将它们组织成可重用的工具包 - 建立 FastMCP 服务器，动态发现本地 STDIO 和远程 Streamable HTTP 传输协议上的工具，并在单个 `MultiServerMCPClient` 后面聚合多个 MCP 服务器 - 从头构建自主代理，并利用 LangChain 内置的代理构造器，包括 SQL 代理和 MCP 驱动的代理 --- ## ✅ 最佳实践 - **基于 LCEL 的组合**：每个管道都使用 `|` 管道运算符或显式 Runnable 包装器，而不是遗留链类 - **提供商抽象**：`model_factory.py` 防止在所有实验室中锁定提供商 - **Pydantic 结构化输出**：用字段描述定义的模式驱动准确的模型提取 - **会话范围内存**：`RunnableWithMessageHistory` 配合单独的 `session_id` 键正确隔离用户 - **令牌预算管理**：`trim_messages()` 集成到 `RunnablePassthrough.assign()` 中，在长对话中保护上下文窗口 - **故障转移弹性**：`.with_fallbacks()` 在主要提供商不可用时防止硬故障 - **检索精度**：子块索引 + 父文档返回的 `ParentDocumentRetriever` 平衡搜索准确性与完整上下文 - **质量排名**：在广泛的向量检索之后应用 FlashRank 交叉编码器排名以提高最终结果的相关性 - **引用接地**：使用 Pydantic 强制的引用和逐字引用字段消除幻觉引用 - **延迟加载**：`DirectoryLoader.lazy_load()` 避免将整个语料库加载到内存中 - **跨平台路径**：`path_helper.py` 仅使用 `pathlib.Path` 从不硬编码字符串 --- ## ❓ 故障排除/常见问题 **运行实验室时出现 `ModuleNotFoundError`** 您的虚拟环境未激活，或者依赖项未安装到其中。重新运行 `source .venv/bin/activate`（适用于 mac/linux）或 `.venv\Scripts\activate`（适用于 windows），然后运行 `pip install -r requirements.txt`。请参阅[安装](#-安装)以获取详细信息。 **OpenAI、Anthropic 或 Google 来自 `openai`、 `anthropic` 或 `google` 的 `AuthenticationError` / `401` 错误** `.env` 中的相应 API 密钥丢失、为空或无效。请仔细检查您是否复制了 `.env.example` 到 `.env`（不仅仅是编辑示例），并且在密钥周围没有多余的引号或空格。 **当 `LLM_MODEL_PROVIDER="ollama"` 时，出现连接被拒绝或超时错误** Ollama 未运行，或未在预期主机/端口上提供服务。使用 `ollama serve` 启动它，如果您不在 `localhost` 上运行，请检查 `.env` 中的 `OLLAMA_BASE_URL`。 **实验室挂起或在使用 `LLM_MODEL_PROVIDER="ollama"` 时非常缓慢** 本地模型受硬件限制。尝试较小的模型或使用 ollama 云托管。 **结构化输出/工具调用实验室中的 `NotImplementedError` 或模式验证错误** 并非所有模型都支持原生结构化输出或函数/工具调用 - 这是模型限制，而不是实验室中的错误。如果您遇到这种情况，请将 `.env` 中的 `LLM_MODEL_NAME` 切换到具有原生工具调用支持的模型（例如 `gpt-4o-mini`、`claude-*` 或 Ollama 显式标记为工具使用的模型，例如 `llama3.1` 或 `qwen2.5`），而不是较小的通用模型。 **多模态/图像输入实验室中的错误或乱码响应** 并非所有模型都接受图像输入 - 文本模型将错误退出或静默忽略图像。请确保 `LLM_MODEL_NAME` 设置为具有视觉能力的模型（例如 `gpt-4o`、`claude-*`、`gemini-*` 或 Ollama 视觉模型，例如 `llama3.2-vision`）。 **嵌入和聊天模型提供商不必匹配** `LLM_MODEL_PROVIDER`/`LLM_MODEL_NAME` 和 `EMBEDDINGS_MODEL_PROVIDER`/`EMBEDDINGS_MODEL_NAME` 是独立配置的 - 例如，您可以使用 Anthropic Claude 聊天，同时使用本地 Ollama 模型进行嵌入。 仍然卡住了？打开一个问题，附上实验室编号、您的 `.env` 提供商设置（删减您的密钥）和完整的错误跟踪日志。 --- ## 🤝 贡献 欢迎并感谢您的贡献。有用的贡献方式： - 🐛 **错误修复** - 实验室抛出错误、导入错误、API 调用过时 - ✏️ **错别字/清晰度修复** - 更正解释、注释或文档 - 🧪 **新实验室** - 现有模块的额外示例，或当前实验室未涵盖的边缘情况 - 🌍 **翻译** - README 的本地化版本 - 💡 **新模块** - 尚未涵盖的主题提案（首先打开问题讨论范围） 请参阅 [CONTRIBUTING](CONTRIBUTING.md) 获取设置详细信息、编码约定和 PR 流程。 --- ## 🙏 致谢 如果没有开源社区的优秀工作，本课程将不复存在： - [**LangChain**](https://github.com/langchain-ai/langchain) 和 [**LangGraph**](https://github.com/langchain-ai/langgraph) - 课程构建的所有框架和抽象 - [**模型上下文协议**](https://modelcontextprotocol.io) - 支持 MCP 模块的开放标准 - [**Ollama**](https://ollama.com/) 、 [**HuggingFace**](https://huggingface.co/) 和其他模型提供商 - 整个实验室中使用的模型和 API - 更广泛的 **开源 Python 和 AI 社区**，其库（FAISS、Chroma、FlashRank 等）使这些实验室成为可能 --- ## 👤 作者 由 **Zain** 构建和维护 [](https://www.linkedin.com/in/zainulabidin1/) --- ## 📄 许可证 该项目根据 MIT 许可证授权。有关详细信息，请参阅 [LICENSE](LICENSE)。 --- <p align="center"> ⭐ 如果这对您有帮助，请给仓库加星以帮助更多人发现它。 </p>