LangChain 技术架构文档-夜雨聆风

LangChain 技术架构文档

属性	值
源码路径	`D:\ai\source-code\langchain`
主语言	Python
包管理	uv / pyproject.toml（Monorepo）
核心定位	LLM 应用编排框架：统一接口 + 可组合执行单元

1. 仓库结构

LangChain 采用 Monorepo，按职责拆成多个独立 PyPI 包，核心原则写在 langchain_core 模块文档中：接口定义在 core，第三方集成在 partners，业务编排在上层 langchain。

包	路径	职责
`langchain-core`	`libs/core/langchain_core/`	Runnable 协议、消息/模型/工具/向量库抽象、回调与序列化
`langchain`	`libs/langchain_v1/langchain/`	Agent 工厂、中间件、ChatModel 初始化
`langchain-*`	`libs/partners/{vendor}/`	各厂商 ChatModel、Embedding、VectorStore 实现
`langchain-text-splitters`	`libs/text-splitters/`	文档切分策略
`langchain-tests`	`libs/standard-tests/`	集成测试契约

Partners 集成列表（当前仓库）：anthropic、chroma、deepseek、exa、fireworks、groq、huggingface、mistralai、nomic、ollama、openai、openrouter、perplexity、qdrant、xai。

2. 分层架构

3. 核心协议：Runnable

Runnable 是 LangChain 的统一执行协议。所有可调用组件（模型、Prompt、Parser、Tool、Chain）均实现同一组方法，支持同步/异步、批处理、流式输出。

关键源码：libs/core/langchain_core/runnables/base.py

组合算子	语法	行为
`RunnableSequence`	`a \| b \| c`	顺序传递，前驱输出 = 后继输入
`RunnableParallel`	`{k: r}` 或 `RunnableParallel(...)`	同一输入并行 fan-out，返回 dict
`RunnableLambda`	`@chain` 装饰器	将函数升格为 Runnable，接入 tracing
`RunnableBinding`	`.bind()` / `.with_config()`	装饰器模式，保留流式/批处理能力
`RunnableBranch`	条件路由	按 predicate 选择分支
`RunnableWithFallbacks`	`.with_fallbacks([...])`	主 Runnable 失败时降级
`RunnableWithRetry`	`.with_retry(...)`	指数退避重试

3.1 invoke 执行路径

3.2 管道组合与流式传播

RunnableSequence 的流式语义：若链上所有组件实现 transform()，则 token 可逐块穿透；若中间存在阻塞组件（如需完整 prompt 才生成的 LLM），流式在阻塞点之后才开始。

4. 语言模型抽象

4.1 类层次

关键源码：libs/core/langchain_core/language_models/chat_models.py

BaseChatModel 继承 Runnable，因此模型调用自动具备：

invoke / stream / batch
Callback 注入（on_chat_model_start / on_llm_end）
LangSmith tracing 参数过滤
Tool binding（bind_tools()）
结构化输出（with_structured_output()）

4.2 ChatModel 单次调用时序

5. 消息与 Prompt 体系

消息类型统一为 BaseMessage，支持 content blocks（text / image / tool_call）。Prompt 模板渲染后产出 ChatPromptValue，作为 ChatModel 输入。

6. Tool 执行架构

BaseTool 继承 RunnableSerializable，通过 Pydantic 校验参数 schema，与 OpenAI function calling 格式互通。

关键源码：libs/core/langchain_core/tools/base.py

Tool 可通过 @tool 装饰器从普通函数生成，自动提取 docstring 作为 description、类型注解作为 args schema。

7. Agent 架构（LangChain v1）

LangChain v1 的 Agent 不再自研循环引擎，而是基于 LangGraph StateGraph 编译为有状态图。

7.1 create_agent 工厂

入口：libs/langchain_v1/langchain/agents/factory.py → create_agent()

参数	作用
`model`	ChatModel 实例或 `"provider:model"` 字符串
`tools`	BaseTool / callable / dict 列表
`middleware`	`AgentMiddleware` 链，拦截 model/tool 调用
`response_format`	结构化输出策略（ToolStrategy / ProviderStrategy）
`checkpointer`	LangGraph 状态持久化（对话恢复）
`interrupt_before/after`	Human-in-the-loop 中断点

7.2 Middleware 拦截链

内置 Middleware（libs/langchain_v1/langchain/agents/middleware/）：

Middleware	功能
`model_retry` / `tool_retry`	失败重试
`model_fallback`	模型降级
`human_in_the_loop`	人工审批 tool 调用
`summarization`	上下文超长时摘要
`tool_call_limit` / `model_call_limit`	调用次数上限
`pii`	PII 检测与脱敏
`context_editing`	动态裁剪上下文

8. RAG 与索引

8.1 组件关系

8.2 增量索引流程

index() API（libs/core/langchain_core/indexing/api.py）通过 RecordManager 追踪已索引文档指纹，实现 upsert / 删除过期记录。

9. 可观测性架构

关键源码：

libs/core/langchain_core/callbacks/manager.py — Run 生命周期管理
libs/core/langchain_core/tracers/ — LangSmith 导出
libs/core/langchain_core/runnables/config.py — RunnableConfig（tags、metadata、callbacks、run_id）

9.1 Run 树结构

每个 Run 携带 run_id、parent_run_id，形成树形 trace，可导出至 LangSmith。

10. 序列化与持久化

实现 Serializable 的组件可通过 dumps() / loads() 序列化为 JSON，用于 LangServe 部署或配置存储。

关键源码：

libs/core/langchain_core/load/serializable.py
libs/core/langchain_core/load/dump.py

序列化格式使用 lc 命名空间标识类型：{"lc": 1, "type": "constructor", "id": [...], "kwargs": {...}}。

11. Runnable 图可视化

Runnable.get_graph() 将组合链导出为 DAG，支持 ASCII / Mermaid / PNG 渲染。

关键源码：libs/core/langchain_core/runnables/graph.py、graph_mermaid.py

12. 典型调用模式对照

12.1 LCEL 链式调用

chain = prompt | model | output_parser
result = chain.invoke({"topic": "AI"})

12.2 Agent 调用

from langchain.agents import create_agent

agent = create_agent("openai:gpt-4o", tools=[search_tool])
result = agent.invoke({"messages": [("user", "查天气")]})

12.3 模式对比

13. 依赖关系总览

外部依赖	用途
`langgraph`	Agent 状态图引擎
`langsmith`	Trace 上报
`pydantic`	Schema 校验、Serializable
`langchain-protocol`	消息流事件协议

14. 关键文件索引

模块	文件路径	说明
Runnable 协议	`libs/core/langchain_core/runnables/base.py`	组合算子与 invoke 实现
Runnable 配置	`libs/core/langchain_core/runnables/config.py`	RunnableConfig、context vars
ChatModel	`libs/core/langchain_core/language_models/chat_models.py`	模型调用主逻辑
Tool	`libs/core/langchain_core/tools/base.py`	Tool schema 与执行
Callback	`libs/core/langchain_core/callbacks/manager.py`	Run 树管理
索引 API	`libs/core/langchain_core/indexing/api.py`	RAG 增量索引
序列化	`libs/core/langchain_core/load/dump.py`	dumps/loads
Agent 工厂	`libs/langchain_v1/langchain/agents/factory.py`	create_agent
Middleware	`libs/langchain_v1/langchain/agents/middleware/`	拦截器集合
图导出	`libs/core/langchain_core/runnables/graph.py`	Runnable DAG

15. 架构设计要点

接口与实现分离：langchain-core 零第三方依赖，集成全部外置到 partners。
Runnable 作为统一契约：组合（|）、批处理、流式、tracing 一次实现、处处可用。
Agent 委托 LangGraph：LangChain 专注 Middleware 与结构化输出，状态机由 LangGraph 承担。
Callback 树形传播：所有组件共享同一套可观测性钩子，无需侵入业务代码。
Serializable 可部署：Chain 可 JSON 化，支撑 LangServe 等运行时加载。