LangChain

知识库简介

本知识库分为两层：先用 00-初学者路线/ 从零建立组件、LCEL、模型与消息、工具、检索、状态、LangGraph 和测试的完整工程路线；再按需查阅官方文档译文与案例。框架 API 变化快，学习重点是稳定的输入输出契约和控制边界，而不是背诵某个版本的导入路径。

既有文件是按固定日期获取的官方文档译文与参考层；00-初学者路线/ 是面向从零学习者的新讲解层。两层分开，便于保留来源和许可，也便于在依赖升级时只复核代码边界。

当前版本基线

2026-07-22 复核时，PyPI 当前发布为 langchain 1.3.14（2026-07-16）、langgraph 1.2.9（2026-07-10）与 langchain-core 1.5.0（2026-07-21）。这些数字只描述本次资料快照，不表示三个包可以脱离解析器任意组合；新项目应在隔离环境中安装、生成锁文件并运行测试。课程中固定 langchain-core==1.4.9 的 LCEL、检索和 create_agent 练习保留已验证的教学合同，不能仅因最新 core 已变更就盲目替换。既有官方译文获取于 2026-05-07，可能早于当前 API，适合作为参考层而非无需复核的复制粘贴来源。

冻结参考层不是可直接执行的教程

01-Learn.md 以及编号 01–06 下的既有译文保留原始来源、日期和许可，用于概念定位与历史对照。先走 00-初学者路线/；需要复制其中的导入、模型 ID、provider 参数或生产部署做法时，先回到链接的当前官方文档和项目 lockfile 复核。尤其不要把 RAG、SQL、Deep Agents 或多 Agent 参考页中的示意代码当作已完成授权、评测或生产验证。

Bedrock 模型生命周期

旧译文中的 anthropic.claude-3-5-sonnet-20240620-v1:0 已进入 legacy/退役迁移窗口；示例已改为当前 AWS model card 中的 anthropic.claude-sonnet-4-6。Bedrock 的模型 ID、区域可用性和 bedrock_converse 支持仍需在目标账户用 AWS 模型目录 重新核对，不能把笔记中的 ID 当作永久保证。

在总路线中的位置

本库位于“框架实践”阶段。基础 LCEL 与模型单元只要求下方列出的 Python、HTTP/JSON 和 LLM API 概念；进入工具、RAG 或状态图单元时，再分别补齐 Tool Calling、检索与 Agent 状态能力。这里是按模块的推荐衔接，不把 LangChain 或任何一门上游完整课程设为所有 Agent/RAG 角色的硬前置；当流程确实需要显式分支、持久状态、暂停恢复或精细编排时，再下沉到 LangGraph。

学习目标

• 理解 LangChain、LangGraph、langchain-core Runnables（LCEL）与 Deep Agents 的职责边界。
• 能用 LCEL 组合确定性步骤，并判断普通 Python、Runnable、Agent 与状态图各自适用的场景。
• 能用消息、模型、工具和结构化输出描述一个最小 Agent 循环。
• 能把检索器接入生成流程，并区分短期状态与长期记忆。
• 能判断何时需要 LangGraph 的检查点、interrupt 和显式状态图。
• 能为工具权限、失败恢复、离线评测和生产观测设计边界。

前置知识

• Python 函数、类型提示、虚拟环境和异常处理。
• HTTP/JSON 与 LLM API 的基本概念；不要求已有 LangChain 经验。
• 涉及真实模型时需自行选择提供商并使用环境变量；本路线不包含真实密钥。

推荐学习顺序

1. 组件地图、环境与 LCEL 最小调用：建立产品、版本和组合边界。
2. 模型、消息、Prompt 与结构化输出：掌握输入输出契约。
3. Tools 与 Agent 循环：理解模型如何请求外部动作。
4. Retrieval 与 RAG 组件：把私有知识接入应用。
5. Memory、State 与 Persistence：正确保存短期和长期信息。
6. LangGraph 边界、审批、恢复与评测：进入显式编排。
7. 项目：离线工具代理骨架：不用依赖或密钥验证核心循环。
8. 项目：无密钥 create_agent 运行时合同：在真实 LangChain harness 中验证消息、工具结果和失败关闭边界。
9. 项目：LangGraph 可恢复审批流：在真实 runtime 中验证 SQLite 检查点、interrupt 与跨进程恢复。
10. 测试、评测与升级清单：把原型变成可回归的工程资产。

• 00-目录.md：当前目录文档
• 01-Learn：Learn 入口页译文（来源：https://docs.langchain.com/oss/python/learn）
• LICENSE-LangChain-docs.md：LangChain docs MIT License
• 文档索引校验：https://docs.langchain.com/llms.txt

01-Conceptual Overviews

• 01-LangChain vs LangGraph vs Deep Agents：理解 LangChain、LangGraph 和 Deep Agents 的差异以及适用场景。 来源：https://docs.langchain.com/oss/python/concepts/products
• 02-Providers and Models：理解 LangChain 如何用统一 API 对接不同提供商的模型。 来源：https://docs.langchain.com/oss/python/concepts/providers-and-models
• 03-Component Architecture：了解 LangChain 组件架构。 来源：https://docs.langchain.com/oss/python/langchain/component-architecture
• 04-Memory：理解线程内和线程间交互的持久化。 来源：https://docs.langchain.com/oss/python/concepts/memory
• 05-Context：学习如何为 AI 应用提供完成任务所需的信息和工具。 来源：https://docs.langchain.com/oss/python/concepts/context
• 06-Graph API：了解 LangGraph 的声明式图构建 API。 来源：https://docs.langchain.com/oss/python/langgraph/graph-api
• 07-Functional API：以单个函数形式构建 agents。 来源：https://docs.langchain.com/oss/python/langgraph/functional-api

02-LangChain

• 01-Semantic Search：用 LangChain 组件构建基于 PDF 的语义搜索引擎。 来源：https://docs.langchain.com/oss/python/langchain/knowledge-base
• 02-RAG Agent：用 LangChain 构建 RAG 代理。 来源：https://docs.langchain.com/oss/python/langchain/rag
• 03-SQL Agent：构建能查询数据库并支持人工审查的 SQL 代理。 来源：https://docs.langchain.com/oss/python/langchain/sql-agent
• 04-Voice Agent：构建可听可说的语音代理。 来源：https://docs.langchain.com/oss/python/langchain/voice-agent

03-LangGraph

• 01-Custom RAG Agent：用 LangGraph 原语构建可细粒度控制的 RAG 代理。 来源：https://docs.langchain.com/oss/python/langgraph/agentic-rag
• 02-Custom SQL Agent：直接用 LangGraph 实现 SQL 代理以获得最大灵活性。 来源：https://docs.langchain.com/oss/python/langgraph/sql-agent

04-Multi-agent

• 01-Subagents Personal Assistant：构建可委派给子代理的个人助手。 来源：https://docs.langchain.com/oss/python/langchain/multi-agent/subagents-personal-assistant
• 02-Handoffs Customer Support：构建使用 handoffs 的客户支持工作流。 来源：https://docs.langchain.com/oss/python/langchain/multi-agent/handoffs-customer-support
• 03-Router Knowledge Base：构建把查询路由到专门代理的多源知识库。 来源：https://docs.langchain.com/oss/python/langchain/multi-agent/router-knowledge-base
• 04-Skills SQL Assistant：构建按需逐步加载专门技能的 SQL 助手。 来源：https://docs.langchain.com/oss/python/langchain/multi-agent/skills-sql-assistant

05-Deep Agents

• 01-Data Analysis：构建分析数据文件、生成可视化并分享结果的 Deep Agent。 来源：https://docs.langchain.com/oss/python/deepagents/data-analysis
• 02-Deep Research：构建带子代理委派的多步骤网络研究代理。 来源：https://docs.langchain.com/oss/python/deepagents/deep-research
• 03-Content Builder：构建带品牌记忆、技能、子代理和图像生成能力的内容写作代理。 来源：https://docs.langchain.com/oss/python/deepagents/content-builder

06-Additional Resources

• 01-LangChain Academy：官方课程和练习；站内 Learn 侧栏会跳转到 Academy 外部站点，因此仅保留外部链接，不抓取正文。
• 02-Case Studies：查看团队如何在生产中使用 LangChain 和 LangGraph。 来源：https://docs.langchain.com/oss/python/langgraph/case-studies
• 03-Get Help：连接 LangChain 社区、学习资源和支持渠道。 来源：https://docs.langchain.com/oss/python/langchain/get-help

动手实践或项目入口

• 每篇初学者笔记都有设计练习；综合入口是 离线工具代理骨架。
• 00-初学者路线/examples/offline_agent_loop.py 只用 Python 标准库，模拟“模型提出工具调用→执行器校验→工具返回→模型生成最终回答”的循环。
• 00-初学者路线/examples/lcel_no_key.py 是不需要模型密钥的 LCEL 组合示例；基础环境不常驻安装 langchain-core，但已在隔离的 langchain-core==1.4.9 环境真实运行。
• 00-初学者路线/examples/test_offline_agent_loop.py 对离线循环执行确定性单元测试，不访问网络。
• 00-初学者路线/examples/retrieval_layer_b/ 固定 langchain-core==1.4.9 与 Python 3.11 兼容的 NumPy 2.4.6；17 项测试验证稳定 ID、metadata、检索前 tenant filter、InMemory raw cosine score 与 Retriever invoke/batch，不把透明教学 Embedding 当成真实语义质量。
• 00-初学者路线/examples/langchain_layer_b/ 用锁定的 langchain==1.3.14、langchain-core==1.4.9、langgraph==1.2.9 真实运行 create_agent；8 项测试覆盖成功、未知工具、严格 schema 拒绝、版本漂移失败关闭，并在 normal、-O、-W error 和 -O -W error 四种模式运行。其 scripted model 有意绕过 provider schema 转换，不能替代真实 provider smoke test。
• 00-初学者路线/examples/langgraph_layer_b/ 直接运行 langgraph==1.2.9 与 SQLite checkpointer，10 项测试覆盖跨进程 interrupt/resume、thread_id 规范化、版本/状态合同守卫与节点重放；它不需要模型凭据，也不承诺外部副作用 exactly-once。
• 需要真实模型的 LangChain 示例仍应在独立 venv 中安装并锁定项目版本；没有提供商凭据时，不应声称模型端到端已运行。

掌握标准

• 能解释 create_agent 适合的高层场景，以及何时改用 LangGraph。
• 能区分真实 LangChain runtime 合同与 provider schema、模型质量、授权和网络集成证据。
• 能解释 LCEL 的 RunnableSequence、RunnableParallel 与 invoke/batch/stream 契约，不把旧版 LLMChain 教程当作 v1 首选入口。
• 能为工具定义清晰输入、错误和权限边界。
• 能区分消息历史、运行状态、检查点和长期记忆。
• 能设计一个带检索、引用、人工审批、恢复和离线评测的最小应用。

与其他知识库的关系

• Agentic Design Patterns 先回答模式选择；本库再把模式映射到 LangChain/LangGraph 组件。
• Tool Calling（含 Function Calling） 解释协议与执行器边界；本库展示如何映射到 @tool 与 Agent 循环。
• RAG 解释检索质量和生成评测；本库负责组件装配，不替代 RAG 原理。
• CrewAI 更突出 Crew 角色协作与 Flow 事件流程；两者不应仅凭示例代码长短选型。
• RAG、Tool Calling 和评测知识库提供独立原理；框架不会替代数据质量、权限和测试设计。

主要参考资料

• LangChain 官方 v1 变化、v1 迁移指南、版本策略（核对日期：2026-07-21）
• LangChain 官方 Agents、Models、Tools、Structured output、Retrieval、Agent Evals（核对日期：2026-07-21）
• LangChain Core Runnables API Reference、Runnable.pipe（核对日期：2026-07-14）
• LangGraph 官方 Overview、Persistence、Interrupts、Test（核对日期：2026-07-21）
• PyPI: langchain、PyPI: langchain-core、PyPI: langgraph（版本快照核对日期：2026-07-22）
• 既有参考层许可说明；既有译文的获取日期仍以各文件 frontmatter 为准。