langchain 解读

项目信息

项目名称：langchain
项目描述：LangChain 是一个面向 AI Agent 工程化的开源框架平台，提供标准的模型接口、可组合组件和第三方集成，帮助开发者构建 LLM 驱动的应用程序和智能体。
项目地址：https://github.com/langchain/langchain
官方文档：https://langchain.com/docs

1. 项目概览

1.1 项目定位与核心价值

一句话定位：LangChain 是一个面向 AI Agent 工程化的开源框架平台，提供标准的模型接口、可组合组件和第三方集成，帮助开发者构建 LLM 驱动的应用程序和智能体。

解决的核心痛点：

模型碎片化与供应商锁定：不同 LLM 提供商有各自独立的 API，LangChain 通过统一的抽象接口（BaseChatModel、BaseEmbeddings 等）实现了模型的可互换性，开发者无需重写代码即可切换模型提供商。
AI 应用开发中的重复造轮子：LLM 应用需要处理提示词管理、对话历史、工具调用、结构化输出、缓存、速率限制等通用问题，LangChain 将这些模式标准化为可复用组件，避免每个项目从零开始。
从原型到生产的鸿沟：原型阶段的简易脚本难以扩展为生产级系统。LangChain 通过模块化、可组合的架构（LCEL — LangChain Expression Language），让开发者可以逐步演进应用，从简单链到复杂 Agent 工作流。

1.2 目标用户与使用场景

目标用户/开发者画像：

AI 工程师：需要快速构建和迭代 LLM 应用的专业开发者
企业开发团队：需要标准化 AI 集成和避免供应商锁定的大型组织
开源社区贡献者：通过合作伙伴包机制贡献第三方集成的开发者

核心业务场景：

场景一：智能 Agent 编排 — 创建能使用工具、规划步骤、调用子 Agent 的复杂 AI 智能体，如客服机器人、代码助手、数据分析 Agent
场景二：多模型 RAG 应用 — 构建基于检索增强生成的知识库问答系统，支持多种嵌入模型、向量数据库和 LLM 的组合
场景三：多提供商 API 统一接入 — 通过统一 API 接入 OpenAI、Anthropic、Ollama、DeepSeek 等 15+ 模型提供商，一套代码适配所有后端

1.3 核心技术亮点

技术亮点	说明
LCEL 管道组合	通过 `\|` 管道操作符实现声明式组件组合，支持同步/异步/流式/批处理四种调用模式
统一模型入口	`init_chat_model("openai:gpt-5.4")` 一行代码接入任何模型提供商
中间件架构	Agent 中间件系统支持横切关注点的可组合扩展（日志、权限、缓存等）
Pydantic v2 深度集成	所有数据结构基于 Pydantic，支持运行时验证和 JSON Schema 自动生成
LangGraph 底层引擎	Agent 基于 LangGraph 的 StateGraph 构建，支持中断/恢复、子图路由、持久化检查点

1.4 技术栈与选型对比

技术	选择	替代方案	权衡分析
构建工具	uv (uv.lock)	pip/poetry	更快解析速度，monorepo 友好，可编辑安装
数据验证	Pydantic v2	dataclasses/TypedDict	运行时验证 + JSON Schema + LLM function calling
图表引擎	LangGraph StateGraph	自研 FSM / LangChain Chain	有状态工作流、中断/恢复、持久化
编排模式	Runnable (LCEL)	函数管道/回调链	统一接口 + 管道组合 + 流式透传
类型检查	Mypy strict	Pyright/Pytype	最严格的类型安全 + Pydantic 插件
Lint/Format	Ruff (ALL rules)	flake8/black/isort	单工具覆盖所有 lint+format 需求
序列化	自定义 JSON + pickle fallback	Pickle / msgpack	可读性 > 性能，安全白名单机制

2. 整体架构设计

2.1 架构概述

架构概述：LangChain 采用分层单体仓库 + 接口-实现分离架构。

核心层 (langchain-core) 定义所有抽象接口和协议，实现层 (langchain) 提供面向用户的高层 API 和 Agent 工厂，合作伙伴层 (partners/) 通过独立包实现各模型提供商的具体集成。
整个系统基于 Runnable 可编排协议（LCEL）作为通用执行抽象，所有组件均可通过 | 管道操作符组合。

整体架构图：

text

+===================================================================+
|                    面向用户的高层 API 层                            |
|  +---------------------------+  +-----------------------------+   |
|  |    init_chat_model()      |  |     create_agent()          |   |
|  |  "openai:gpt-5.4"         |  |  model + tools + middleware |   |
|  +---------------------------+  +-----------------------------+   |
+==============================+====================================+
                               | (import & extend)
                               v
+===================================================================+
|                    langchain-core 核心抽象层                        |
|  +-------------+ +-------------+ +------------+ +-------------+  |
|  |  Runnable   | | BaseChatModel| |  BaseTool  | | BaseMessage |  |
|  |  (LCEL)     | | (Chat Model) | |  (Tools)   | | (Messages)  |  |
|  +------+------+ +------+------+ +-----+------+ +------+------+  |
|         |               |              |               |          |
|  +------v------+ +------v------+ +-----v------+ +------v------+  |
|  |RunnableLambda| |ChatOpenAI  | | @tool      | |AIMessage   |  |
|  |RunnableBranch| |ChatAnthropic| |StructuredTool|HumanMessage|  |
|  |RunnableMap   | |ChatOllama  | |            | |ToolMessage |  |
|  +--------------+ +-------------+ +------------+ +------------+  |
+===================================================================+
                               | (implements)
                               v
+===================================================================+
|                 合作伙伴集成层 (15+ 独立包)                          |
|  +----------+ +----------+ +----------+ +----------+              |
|  |  openai  | |anthropic | |  ollama  | |  groq    |  ...         |
|  +-----+----+ +----+-----+ +----+-----+ +----+-----+              |
|        |           |            |            |                     |
|  +-----v----+ +----v-----+ +----v-----+ +----v-----+              |
|  |ChatOpenAI| |ChatAnthr-| |ChatOllama| |ChatGroq  |              |
|  |Embeddings| |opic      | |Embeddings| |ChatGroq  |              |
|  |LLMs      | |LLMs      | |ToolCall- | |          |              |
|  |Tools     | |Tools     | |ing       | |          |              |
|  +----------+ +----------+ +----------+ +----------+              |
+===================================================================+
                               | (validated by)
                               v
+===================================================================+
|              标准测试套件 (standard-tests)                          |
|  +-------------------+  +---------------------+                   |
|  | Unit Tests        |  | Integration Tests   |                   |
|  | - ChatModels      |  | - ChatModels        |                   |
|  | - Embeddings      |  | - Embeddings        |                   |
|  | - Tools           |  | - VectorStores      |                   |
|  +-------------------+  +---------------------+                   |
+===================================================================+

分层职责说明

层	包	职责	示例
用户 API 层	`langchain`	面向开发者的高层接口	`init_chat_model()`, `create_agent()`
核心抽象层	`langchain-core`	所有接口和协议定义	`Runnable`, `BaseChatModel`, `BaseTool`
合作伙伴集成层	`langchain-openai`, `langchain-anthropic` 等	具体模型实现	`ChatOpenAI`, `ChatAnthropic`
标准测试层	`langchain-tests`	验证一致性	标准 ChatModel 测试套件

2.2 目录结构

shell

langchain/                                 # 【核心基建】LangChain AI Agent 框架单体仓库
├── libs/                                  # 【核心基建】所有子包根目录
│   ├── core/                              # 【核心基建】langchain-core — 基础抽象与协议层 (v1.4.1)
│   │   └── langchain_core/
│   │       ├── runnables/                 # 【核心基建】LCEL 可编排执行单元 (Runnable/chain/branch)
│   │       ├── language_models/           # 【核心基建】语言模型抽象 (BaseChatModel/ChatModelStream)
│   │       ├── messages/                  # 【核心基建】消息系统 (Human/AI/System/Tool/BlockTranslators)
│   │       ├── tools/                     # 【核心基建】工具定义与执行 (BaseTool/@tool/StructuredTool)
│   │       ├── prompts/                   # 【核心基建】提示词模板 (ChatPromptTemplate/PipelinePrompt)
│   │       ├── callbacks/                 # 【核心基建】回调管理器 (同步/异步/Streaming)
│   │       ├── tracers/                   # 【核心基建】追踪器 (RunCollector/EventStream/LogStream)
│   │       ├── output_parsers/            # 【核心基建】输出解析器 (Json/Pydantic/XML/OpenAI Tools)
│   │       ├── outputs/                   # 【核心基建】LLM 输出 (ChatGeneration/LLMResult/RunInfo)
│   │       ├── documents/                 # 【核心基建】Document 文档抽象 (BaseDocumentTransformer)
│   │       ├── document_loaders/          # 【核心基建】文档加载器基类 (BaseLoader/Blob)
│   │       ├── embeddings/                # 【核心基建】嵌入模型抽象 (Embeddings 接口)
│   │       ├── vectorstores/              # 【核心基建】向量存储抽象 (VectorStore 接口)
│   │       ├── indexing/                  # 【核心基建】索引与检索 API (RecordManager/IndexingResult)
│   │       ├── stores.py                  # 【核心基建】键值存储 (BaseStore/InMemoryStore)
│   │       ├── load/                      # 【核心基建】序列化 (Serializable/dumpd/dumps/load)
│   │       ├── utils/                     # 【工具集】工具函数 (pydantic/aiter/iter/function_calling)
│   │       ├── example_selectors/         # 【核心基建】示例选择器 (SemanticSimilarity/LengthBased)
│   │       ├── _api/                      # 【核心基建】API 标记装饰器 (beta/deprecated/path)
│   │       ├── _security/                 # 【核心基建】安全策略 (Policy/Transport)
│   │       ├── caches.py                  # 【核心基建】缓存抽象 (BaseCache/InMemoryCache)
│   │       ├── agents.py                  # 【核心基建】Agent 基础抽象
│   │       ├── chat_history.py            # 【核心基建】对话历史序列化/反序列化
│   │       ├── rate_limiters.py           # 【核心基建】速率限制器 (BaseRateLimiter/InMemoryRateLimiter)
│   │       ├── retrievers.py              # 【核心基建】检索器抽象 (BaseRetriever)
│   │       ├── structured_query.py        # 【核心基建】结构化查询 (Comparators/Operators/Visitors)
│   │       ├── env.py                     # 【工具集】环境变量读取
│   │       ├── sys_info.py                # 【工具集】系统信息打印
│   │       ├── globals.py                 # 【配置】全局设置 (debug/verbose/cache 等)
│   │       ├── exceptions.py             # 【核心基建】自定义异常
│   │       └── version.py                # 【配置】版本号
│   │
│   ├── langchain_v1/                      # 【核心基建】langchain — 面向用户的高层 API (v1.3.4)
│   │   └── langchain/
│   │       ├── agents/                    # 【业务模块】Agent 工厂与中间件系统
│   │       │   ├── factory.py            # 【业务模块】create_agent() — 基于 LangGraph StateGraph
│   │       │   ├── middleware/            # 【业务模块】中间件类型定义 (AgentMiddleware/AgentState)
│   │       │   ├── _subagent_transformer.py # 【业务模块】子 Agent 转换器
│   │       │   └── structured_output.py  # 【业务模块】结构化输出策略 (Tool/Provider/Auto)
│   │       ├── chat_models/               # 【业务模块】init_chat_model() — 统一模型入口
│   │       │   └── base.py               # 【业务模块】提供商注册表 + 可配置模型 (_ConfigurableModel)
│   │       ├── embeddings/                # 【业务模块】init_embeddings() — 统一嵌入入口
│   │       ├── messages/                  # 【业务模块】消息类型扩展
│   │       ├── rate_limiters/             # 【业务模块】速率限制器实现
│   │       └── tools/                     # 【业务模块】工具创建辅助
│   │
│   ├── langchain/                         # 【废弃】langchain-classic — 遗留包 (不再新增功能)
│   │
│   ├── partners/                          # 【业务模块】15 个第三方模型提供商集成
│   │   ├── openai/                        # 【业务模块】OpenAI (ChatOpenAI/Azure/Embeddings/Tools)
│   │   │   └── langchain_openai/
│   │   │       ├── chat_models/           # ChatOpenAI/AzureChatOpenAI (base: 5053行)
│   │   │       ├── embeddings/            # OpenAIEmbeddings/AzureOpenAIEmbeddings
│   │   │       ├── llms/                  # OpenAI LLM/AzureOpenAI LLM
│   │   │       ├── tools/                 # OpenAI 自定义工具
│   │   │       ├── output_parsers/        # OpenAI 工具输出解析
│   │   │       ├── middleware/            # OpenAI 内容审核中间件
│   │   │       └── data/                  # 模型档案 (_profiles.py)
│   │   ├── anthropic/                     # 【业务模块】Anthropic Claude (ChatAnthropic/LLMs/Tools)
│   │   ├── ollama/                        # 【业务模块】本地 Ollama 模型
│   │   ├── groq/                          # 【业务模块】Groq 快速推理
│   │   ├── mistralai/                     # 【业务模块】Mistral AI
│   │   ├── deepseek/                      # 【业务模块】DeepSeek 模型
│   │   ├── huggingface/                   # 【业务模块】HuggingFace 模型
│   │   ├── fireworks/                     # 【业务模块】Fireworks AI
│   │   ├── openrouter/                    # 【业务模块】OpenRouter 多模型路由
│   │   ├── xai/                           # 【业务模块】xAI Grok
│   │   ├── perplexity/                    # 【业务模块】Perplexity 在线搜索
│   │   ├── chroma/                        # 【业务模块】Chroma 向量数据库
│   │   ├── qdrant/                        # 【业务模块】Qdrant 向量数据库
│   │   ├── exa/                           # 【业务模块】Exa 搜索引擎
│   │   └── nomic/                         # 【业务模块】Nomic 嵌入模型
│   │
│   ├── standard-tests/                    # 【工具集】标准化测试套件 (langchain-tests)
│   │   └── langchain_tests/
│   │       ├── integration_tests/         # 【工具集】集成测试 (chat_models/embeddings/vectorstores/tools)
│   │       ├── unit_tests/                # 【工具集】单元测试 (chat_models/embeddings/tools)
│   │       ├── utils/                     # 【工具集】测试辅助 (pydantic 工具)
│   │       └── base.py                    # 【工具集】测试基类
│   │
│   ├── text-splitters/                    # 【工具集】文档分块 (langchain-text-splitters)
│   │   └── langchain_text_splitters/      # Markdown/Python/HTML/JSON/LaTeX/NLTK/Spacy 分块器
│   │
│   └── model-profiles/                    # 【工具集】langchain-profiles CLI (模型档案生成与刷新)
│
├── .github/                               # 【配置】CI/CD (PR 标签/测试/发布 工作流)
├── .vscode/                               # 【配置】VSCode 标准化设置
├── .claude/                               # 【配置】Claude Code 项目配置
├── AGENTS.md                              # 【配置】AI Agent 开发者指南
├── CLAUDE.md                              # 【配置】Claude Code 开发者指南
├── README.md                              # 【配置】英文项目说明
├── LICENSE                                # 【配置】MIT 开源许可证
├── CITATION.cff                           # 【配置】学术引用格式
├── .gitignore                             # 【配置】Git 忽略规则
├── .editorconfig                          # 【配置】跨编辑器编码规范
├── .pre-commit-config.yaml                # 【配置】Pre-commit 钩子 (ruff/mypy)
└── .mcp.json                              # 【配置】MCP 服务器定义 (docs/reference)

3. 模块依赖与调用关系

3.1 全局入口与核心路由

逻辑说明：用户通过 init_chat_model("openai:gpt-5.4") 入口指定模型，系统通过 _BUILTIN_PROVIDERS 注册表查找提供商的包名和类名，延迟导入对应的合作伙伴包，返回 BaseChatModel 实例。Agent 创建通过 create_agent() 使用 LangGraph 的 StateGraph 构建有状态工作流。

调用拓扑：

text

init_chat_model(model="openai:gpt-5.4")
  +-- _parse_model()                    ---> 解析 "provider:model" 格式
  +-- _get_chat_model_creator("openai") ---> 从 _BUILTIN_PROVIDERS 查找
       +-- importlib.import_module("langchain_openai")
       +-- getattr(module, "ChatOpenAI")
       +-- functools.partial(_call, cls=ChatOpenAI)
            +-- ChatOpenAI(model="gpt-5.4", **kwargs)
                 +-- extends BaseChatModel
                      +-- extends RunnableSerializable
                           +-- extends Runnable

create_agent(model, tools, middleware)
  +-- StateGraph(AgentState)
  +-- model.bind_tools(tools)          ---> 注入工具定义
  +-- middleware composition            ---> 中间件链 (inner-first)
  +-- ToolNode(tools)                   ---> 工具执行节点
  +-- graph.compile()                   ---> 编译为 Runnable

3.2 核心业务实体与关联

实体定义：

Runnable — 统一执行单元，所有组件（模型、工具、链、Agent）都是 Runnable
BaseChatModel — 聊天模型抽象，管理消息输入/输出、工具绑定、结构化输出
BaseTool — 工具定义，包含 args_schema、函数签名、描述
BaseMessage — 消息抽象，子类包括 HumanMessage、AIMessage、SystemMessage、ToolMessage
AgentState — Agent 状态图的状态定义，包含 messages、tools、middleware 上下文

实体引用拓扑：

text

[Runnable] 1 <--> 1 [RunnableConfig]
    ^
    |
    +-- [RunnableSerializable]
         ^
         |
         +-- [BaseChatModel] 1 -----> N [BaseTool] (via bind_tools)
         |       ^
         |       +-- ChatOpenAI    (implements)
         |       +-- ChatAnthropic (implements)
         |       +-- ChatOllama   (implements)
         |
         +-- [BaseTool] 1 -----> 1 [args_schema: Type[BaseModel]]
         |       ^
         |       +-- @tool (function-based)
         |       +-- StructuredTool (class-based)
         |
         +-- [StateGraph] 1 -----> N [AgentMiddleware]
                                      |
                                      +-- [wrap_model_call]
                                      +-- [wrap_tool_call]
                                      +-- [wrap_agent]

[BaseMessage] 1 -----> N [ToolCall]
    ^
    +-- HumanMessage
    +-- AIMessage 1 -----> N [ToolCall]
    +-- SystemMessage
    +-- ToolMessage 1 -----> 1 [tool_call_id]

4. 核心模块详解

模块一：Runnable 可编排协议 (LCEL)

模块名称：langchain_core.runnables — LangChain Expression Language 核心引擎
设计说明：Runnable 是 LangChain 最核心的设计模式，基于函数式编程思想。所有组件都实现 Runnable 接口，提供统一的 .invoke() / .stream() / .batch() / .ainvoke() / .astream() 方法。通过重载 Python 的 | (or) 操作符实现管道组合（chain | model | parser），支持同步/异步、批处理、流式输出、事件流等模式。使用了策略模式和适配器模式来处理不同类型的 Runnable（Lambda、Branch、Parallel、Fallback 等）。
内部结构图 (plainText)：

text

+----------------------------------------------------------+
|                     Runnable[Input, Output]               |
|  +invoke(input, config) -> Output                        |
|  +ainvoke(input, config) -> Awaitable[Output]            |
|  +stream(input, config) -> Iterator[Output]              |
|  +astream(input, config) -> AsyncIterator[Output]        |
|  +batch(inputs, config) -> list[Output]                  |
|  +astream_events(input, config) -> AsyncIterator[Event]  |
|  +__or__(other) -> RunnableSequence   (管道组合)         |
+---------------------------+------------------------------+
                            |
          +-----------------+------------------+
          |                 |                  |
+---------v--------+ +-----v--------+ +------v-----------+
| RunnableLambda   | |RunnableBranch| | RunnableParallel |
| (函数包装器)      | | (条件路由)    | | (并行执行)       |
+------------------+ +--------------+ +------------------+
          |
+---------v--------+
|RunnableSequence  |  (a | b | c = a.__or__(b).__or__(c))
+------------------+

辅助类：
+------------------+  +-------------------+  +-------------------+
|RunnableConfig    |  |RunnableWithFall-  |  |RunnableWith-      |
|(调用配置)         |  |backs (容错降级)    |  |MessageHistory     |
+------------------+  +-------------------+  +-------------------+

模块二：语言模型抽象层 (Language Models)

模块名称：langchain_core.language_models — 语言模型的标准化抽象
设计说明：BaseLanguageModel 是所有语言模型的基类。BaseChatModel 继承它并提供了完整的对话模型接口，包括工具调用（bind_tools）、结构化输出（with_structured_output）、模型档案（ModelProfile）等功能。该模块采用模板方法模式：基类定义了 _generate() / _stream() / _agenerate() / _astream() 抽象方法，子类只需实现这些方法，其他功能（缓存、回调、速率限制、重试）由基类自动提供。
内部结构图 (plainText)：

text

+----------------------------------------------------+
|              BaseLanguageModel[Input, Output]       |
|  +cache: BaseCache | None                          |
|  +rate_limiter: BaseRateLimiter | None             |
|  +profile: ModelProfile | None                     |
+---------------------------+------------------------+
                            |
                            v
+----------------------------------------------------+
|              BaseChatModel (核心聊天模型)            |
|  +bind_tools(tools) -> Runnable                     |
|  +with_structured_output(schema) -> Runnable         |
|  +_generate(messages) -> ChatResult    (抽象方法)    |
|  +_stream(messages) -> Iterator[ChatGenerationChunk]|
|  +model_profile -> ModelProfile                     |
+---------------------------+------------------------+
                            |
     +----------------------+-----------------------+
     |                      |                       |
+----v--------+  +----------v-------+  +----------v-------+
| ChatOpenAI  |  | ChatAnthropic   |  | ChatOllama       |
| (OpenAI)    |  | (Anthropic)     |  | (本地模型)        |
|             |  |                 |  |                   |
| _generate() |  | _generate()     |  | _generate()       |
| _stream()   |  | _stream()       |  | _stream()         |
+-------------+  +-----------------+  +-------------------+

模块三：工具系统 (Tools System)

模块名称：langchain_core.tools — 工具定义与执行框架
设计说明：BaseTool 是所有工具的基类，继承自 RunnableSerializable。工具通过 args_schema（Pydantic 模型）定义参数结构，支持自动从函数签名推断参数。@tool 装饰器将普通函数转换为 Tool 实例。工具系统深度集成了 LLM 的函数调用能力，自动生成 OpenAI/Anthropic 兼容的 tool schema。
内部结构图 (plainText)：

text

+--------------------------------------------------+
|           BaseTool (Runnable[Union[str, dict], Any]) |
|  +name: str                                       |
|  +description: str                                |
|  +args_schema: Type[BaseModel]                    |
|  +return_direct: bool                             |
|  +invoke(input, config) -> ToolOutput            |
+-------------------------+------------------------+
                          |
     +--------------------+---------------------+
     |                    |                     |
+----v----------+  +------v--------+  +--------v---------+
| @tool         |  |StructuredTool |  |BaseToolkit       |
| (函数装饰器)   |  |(类定义方式)    |  |(工具集分组)       |
|               |  |               |  |                   |
| 自动推断       |  | 显式声明      |  | get_tools()      |
| name/desc/    |  | name/desc/    |  | -> list[BaseTool] |
| args_schema   |  | args_schema   |  |                   |
+---------------+  +---------------+  +-------------------+

模块四：Agent 中间件系统 (Agent Middleware)

模块名称：langchain.agents — Agent 创建与中间件编排
设计说明：create_agent() 基于 LangGraph 的 StateGraph 构建 Agent 工作流。通过中间件（AgentMiddleware）模式实现横切关注点的可组合扩展。中间件可以拦截 wrap_model_call（模型调用前后）和 wrap_tool_call（工具调用前后）。支持 SubagentTransformer 用于子 Agent 编排。使用 Command 和 Send 实现 Agent 间的动态路由。
内部结构图 (plainText)：

text

+-------------------------------------------------------+
|                    create_agent()                      |
|  model: BaseChatModel                                 |
|  tools: Sequence[BaseTool]                            |
|  middleware: Sequence[AgentMiddleware]                 |
|  system_prompt: str | None                            |
+---------------------------+---------------------------+
                            |
                            v
+-------------------------------------------------------+
|                StateGraph(AgentState)                  |
|  +-- START -> agent_node (LLM call)                   |
|  +-- agent_node -> tools_node (conditional)           |
|  +-- tools_node -> agent_node                         |
|  +-- agent_node -> END                                |
+---------------------------+---------------------------+
                            |
                            v
+-------------------------------------------------------+
|             AgentMiddleware Chain                      |
|  wrap_model_call(state, handler):                     |
|    middleware_N(...middleware_2(middleware_1(handler)))|
|  wrap_tool_call(request, handler):                    |
|    middleware_N(...middleware_2(middleware_1(handler)))|
+-------------------------------------------------------+

模块五：合作伙伴包集成模式 (Partner Integration Pattern)

模块名称：libs/partners/ — 标准化第三方集成
设计说明：每个合作伙伴包遵循统一的集成模式：继承 BaseChatModel 实现提供商特定的聊天模型，实现 _generate() / _stream() 抽象方法，包含模型档案数据（data/_profiles.py），通过 standard-tests 验证一致性。包之间完全独立，各自管理依赖和版本。
内部结构图 (plainText)：

text

典型合作伙伴包结构 (以 anthropic 为例)：
+------------------------------------------+
|  langchain_anthropic/                    |
|  +-- __init__.py       # 公开导出        |
|  +-- chat_models.py    # ChatAnthropic   |
|  +-- llms.py           # AnthropicLLM    |
|  +-- _compat.py        # 向后兼容层       |
|  +-- _client_utils.py  # HTTP 客户端工具  |
|  +-- output_parsers.py # 输出解析         |
|  +-- middleware/       # 中间件扩展       |
|  +-- data/             # 模型档案         |
|  |   +-- _profiles.py  # ModelProfile[]   |
|  +-- experimental.py   # 实验性功能       |
+------------------------------------------+
              |
              | (验证一致性)
              v
+------------------------------------------+
|  standard-tests/langchain_tests/         |
|  +-- unit_tests/chat_models.py           |
|  +-- integration_tests/chat_models.py    |
+------------------------------------------+

5. 关键数据流程

场景一：基础 Chat Model 调用流程

场景说明：用户通过 init_chat_model 初始化一个可配置的聊天模型，然后调用 .invoke() 发送消息。系统经过提供商解析、延迟导入、模型实例化、回调管理、速率限制检查、缓存检查、实际 API 调用、结果后处理等步骤。
流转时序图 (Mermaid)：

场景二：Agent 工具调用流程

场景说明：用户创建一个带工具的 Agent，发送需要调用工具的请求。Agent 在模型推理和工具执行之间循环，直到模型决定不再需要调用工具。
流转时序图 (Mermaid)：

6. 接口与契约规范

6.1 核心内部模块契约 (Python 类型定义)

python

from collections.abc import AsyncIterator, Iterator, Sequence
from typing import Any, Generic, TypeVar
from pydantic import BaseModel

Input = TypeVar("Input", contravariant=True)
Output = TypeVar("Output", covariant=True)

class RunnableConfig(TypedDict, total=False):
    """Runnable 调用的通用配置"""
    tags: list[str]
    metadata: dict[str, Any]
    callbacks: Any
    max_concurrency: int | None
    recursion_limit: int
    configurable: dict[str, Any]
    run_name: str
    run_id: uuid.UUID

class Runnable(Generic[Input, Output], ABC):
    """统一可编排执行单元 — LCEL 核心协议"""

    def invoke(self, input: Input, config: RunnableConfig | None = None, **kwargs: Any) -> Output: ...
    async def ainvoke(self, input: Input, config: RunnableConfig | None = None, **kwargs: Any) -> Output: ...
    def stream(self, input: Input, config: RunnableConfig | None = None, **kwargs: Any) -> Iterator[Output]: ...
    async def astream(self, input: Input, config: RunnableConfig | None = None, **kwargs: Any) -> AsyncIterator[Output]: ...
    def batch(self, inputs: list[Input], config: RunnableConfig | None = None, **kwargs: Any) -> list[Output]: ...
    def __or__(self, other: Runnable[Output, T]) -> RunnableSequence[Input, T]: ...

class BaseChatModel(Runnable[LanguageModelInput, BaseMessage], ABC):
    """聊天模型标准接口"""

    model_name: str
    temperature: float | None
    max_tokens: int | None
    cache: BaseCache | None
    rate_limiter: BaseRateLimiter | None

    @abstractmethod
    def _generate(self, messages: list[BaseMessage], stop: list[str] | None = None,
                  run_manager: CallbackManagerForLLMRun | None = None, **kwargs: Any) -> ChatResult: ...

    def bind_tools(self, tools: Sequence[dict[str, Any] | type[BaseModel] | Callable | BaseTool],
                   **kwargs: Any) -> Runnable[LanguageModelInput, AIMessage]: ...

    def with_structured_output(self, schema: dict[str, Any] | type[BaseModel],
                               **kwargs: Any) -> Runnable[LanguageModelInput, dict[str, Any] | BaseModel]: ...

class BaseTool(Runnable[Union[str, dict[str, Any]], Any], ABC):
    """工具标准接口"""

    name: str
    description: str
    args_schema: type[BaseModel]
    return_direct: bool

    @abstractmethod
    def _run(self, *args: Any, **kwargs: Any) -> Any: ...
    async def _arun(self, *args: Any, **kwargs: Any) -> Any: ...

class AgentState(TypedDict, total=False):
    """Agent 状态图的状态定义"""
    messages: Required[Annotated[list[AnyMessage], add_messages]]
    tools: NotRequired[list[BaseTool]]
    middleware: NotRequired[list[AgentMiddleware]]

6.2 模型提供商注册契约

python

# 内置提供商注册表格式 (_BUILTIN_PROVIDERS)
# 每个条目映射 provider_name -> (package_module, class_name, factory_func)
ProviderRegistry: dict[str, tuple[str, str, Callable[..., BaseChatModel]]]

# 示例:
_BUILTIN_PROVIDERS = {
    "openai":     ("langchain_openai", "ChatOpenAI", _call),
    "anthropic":  ("langchain_anthropic", "ChatAnthropic", _call),
    "ollama":     ("langchain_ollama", "ChatOllama", _call),
    "deepseek":   ("langchain_deepseek", "ChatDeepSeek", _call),
    # ... 26+ providers
}

6.3 合作伙伴包标准合约

python

# 每个合作伙伴包必须：
# 1. 导出 ChatModel 类（继承 BaseChatModel）
# 2. 实现 _generate() 和 _stream() 方法
# 3. 提供模型档案数据（可选但推荐）

# 标准集成测试套件验证：
# - test_initialization()  — 模型可正确初始化
# - test_invoke()          — invoke 返回有效 AIMessage
# - test_stream()          — stream 返回有效 AIMessageChunk 序列
# - test_tool_calling()    — bind_tools + tool_choice 正确工作
# - test_structured_output() — with_structured_output 返回正确类型

7. 快速开始

7.1 环境配置

bash

# 安装所有依赖组
uv sync --all-groups

# 或仅安装特定组
uv sync --group test

7.2 开发命令

langchain 开发命令

$make test

# 运行单元测试

$uv run --group test pytest tests/unit_tests/test_specific.py

# 运行特定测试

$make lint

# Lint 检查

$make format

# 格式化代码

$uv run --group lint mypy .

# 类型检查

7.3 典型用例

基础使用：初始化聊天模型

python

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.4", temperature=0)
result = model.invoke("Hello, world!")

工具调用：定义和使用工具

python

from langchain.tools import tool

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

model_with_tools = model.bind_tools([search])

Agent 创建：构建完整 Agent

python

from langchain.agents import create_agent

agent = create_agent(
    model=model,
    tools=[search],
    system_prompt="You are a helpful research assistant."
)
result = agent.invoke({"messages": [{"role": "user", "content": "Latest LangChain news"}]})

✅核心结论

LangChain 的核心价值在于分层架构设计：langchain-core 定义抽象协议，langchain 提供高层 API，合作伙伴包实现具体集成
LCEL (Runnable 协议) 是贯穿整个框架的统一执行抽象，所有组件通过 | 管道操作符可组合
Agent 系统基于 LangGraph StateGraph 构建，中间件模式实现了横切关注点的可组合扩展
合作伙伴包模式通过标准化接口合约和测试套件，确保 15+ 第三方集成的一致性和可互换性

langchain 解读 ​

1. 项目概览 ​

1.1 项目定位与核心价值 ​

1.2 目标用户与使用场景 ​

1.3 核心技术亮点 ​

1.4 技术栈与选型对比 ​

2. 整体架构设计 ​

2.1 架构概述 ​

2.2 目录结构 ​

3. 模块依赖与调用关系 ​

3.1 全局入口与核心路由 ​

3.2 核心业务实体与关联 ​

4. 核心模块详解 ​

模块一：Runnable 可编排协议 (LCEL) ​

模块二：语言模型抽象层 (Language Models) ​

模块三：工具系统 (Tools System) ​

模块四：Agent 中间件系统 (Agent Middleware) ​

模块五：合作伙伴包集成模式 (Partner Integration Pattern) ​

5. 关键数据流程 ​

场景一：基础 Chat Model 调用流程 ​

场景二：Agent 工具调用流程 ​

6. 接口与契约规范 ​

6.1 核心内部模块契约 (Python 类型定义) ​

6.2 模型提供商注册契约 ​

6.3 合作伙伴包标准合约 ​

7. 快速开始 ​

7.1 环境配置 ​

7.2 开发命令 ​

7.3 典型用例 ​

langchain 解读

1. 项目概览

1.1 项目定位与核心价值

1.2 目标用户与使用场景

1.3 核心技术亮点

1.4 技术栈与选型对比

2. 整体架构设计

2.1 架构概述

2.2 目录结构

3. 模块依赖与调用关系

3.1 全局入口与核心路由

3.2 核心业务实体与关联

4. 核心模块详解

模块一：Runnable 可编排协议 (LCEL)

模块二：语言模型抽象层 (Language Models)

模块三：工具系统 (Tools System)

模块四：Agent 中间件系统 (Agent Middleware)

模块五：合作伙伴包集成模式 (Partner Integration Pattern)

5. 关键数据流程

场景一：基础 Chat Model 调用流程

场景二：Agent 工具调用流程

6. 接口与契约规范

6.1 核心内部模块契约 (Python 类型定义)

6.2 模型提供商注册契约

6.3 合作伙伴包标准合约

7. 快速开始

7.1 环境配置

7.2 开发命令

7.3 典型用例