LangChain.js 完整架构总结（含流程图）

创建日期: 2026-02-13 状态: ✅ 全部分析完成 模块数: 6 个核心模块 + 4 个提供商 + 2 个示例文档 = 12 个 文档总数: 6 个主要文档 总字数: ~100,000 字 流程图数: 60+ 个 Mermaid 图

1. 项目概览

1.1 基本信息

名称: LangChain.js
类型: Monorepo (基于 pnpm + Turbo）
包管理器: pnpm 10.14.0
构建系统: Turbo + tsdown
类型系统: TypeScript 5.9.3
运行时: Node.js 20.x, 22.x, 24.x, Deno, Bun
测试框架: Vitest

1.2 项目结构

langchainjs/
├── libs/                    # 核心库
│   ├── langchain-core/        # 核心抽象层
│   ├── langchain/            # 主包（高级 API）
│   ├── langchain-classic/    # 经典 API（v0.x）
│   ├── langchain-community/  # 社区集成
│   ├── langchain-textsplitters/  # 文本分割
│   ├── langchain-mcp-adapters/  # MCP 协议
│   └── providers/                # 第三方提供商（30+）
├── examples/                 # 示例代码
├── internal/                # 内部工具
├── docs/                    # 文档
├── environment_tests/        # 环境测试
└── 工作区配置文件

1.3 包统计

核心库: 6 个（langchain, langchain-classic, langchain-community, langchain-textsplitters, langchain-mcp-adapters + 3 个子包）
提供商: 30+ 个（OpenAI, Anthropic, Google, DeepSeek, AWS, Azure, Cloudflare, Mistral, Cohere, etc.）
总包数: 36+ 个（包含内部和示例）

2. 模块分析汇总

2.1 核心抽象层

langchain-core - 11,876 行代码

Runnable 接口 - 统一的执行模型
消息系统 - 多模态消息支持
工具系统 - 灵活的工具定义和调用
输出解析器 - 结构化输出处理
向量存储 - 相似度搜索抽象
检索器 - 统一的数据检索接口
存储系统 - 键值存储抽象
缓存系统 - LLM 响应缓存
追踪系统 - LangSmith 集成

2.2 高级功能层

langchain - 46k 行代码

Agents - 基于 LangGraph 的 ReAct Agent
Prompts - 灵活的模板系统
Loaders - 多种文档加载
Storage - Agent 状态持久化
Hub - 社区资源共享

2.3 社区与扩展

langchain-community - 社区贡献的集成

工具库（文档、网络、数据库等）
向量存储（Chroma, Qdrant, Weaviate 等）
检索器（混合检索、重排序）

langchain-mcp-adapters - MCP 协议支持

客户端连接
工具注册
消息处理

langchain-textsplitters - 文本分割策略

递归分割
字符级分割
Markdown、代码、语言感知分割

3. 技术栈

3.1 开发工具

工具	用途
pnpm	包管理和 Monorepo 构建
Turbo	并行构建和缓存
tsdown	TypeScript 编译（ESM + CJS 输出）
Vitest	单元测试框架
ESLint	代码规范检查
Prettier	代码格式化
lint-staged	Git 暂存文件检查

3.2 构建流程

bash

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行测试
pnpm test:unit

# 代码检查
pnpm lint
pnpm format

4. 架构设计

4.1 完整架构流程图

mermaid

graph TB
    Application[LangChain 应用] --> Layer1[应用层]
    Layer1 --> Layer2[提供商层]
    Layer2 --> Layer3[核心抽象层]
    Layer3 --> Layer4[平台层]
    Layer4 --> Layer5[运行时环境]

    Application --> |A[Agents]|
    Application --> |B[Chains]|
    Application --> |C[Prompts]|
    Application --> |D[Loaders]|
    Application --> |E[Tools]|
    Application --> |F[Retrievers]|

    Layer1 --> |A1[OpenAI]|
    Layer1 --> |A2[Anthropic]|
    Layer1 --> |A3[Google]|
    Layer1 --> |A4[DeepSeek]|

    Layer2 --> |B1[Runnable Interface]|
    Layer2 --> |B2[Messages]|
    Layer2 --> |B3[Tools]|
    Layer2 --> |B4[Output Parsers]|
    Layer2 --> |B5[Vector Stores]|
    Layer2 --> |B6[Retrievers]|
    Layer2 --> |B7[Stores]|
    Layer2 --> |B8[Caches]|
    Layer2 --> |B9[Tracers]|

    Layer3 --> |C1[Sequences]|
    Layer3 --> |C2[Parallel]|
    Layer3 --> |C3[Branches]|
    Layer3 --> |C4[Retry/Fallback]|
    Layer3 --> |C5[Each]|
    Layer3 --> |C6[Lambdas]|

    Layer4 --> |D1[Node.js]|
    Layer4 --> |D2[Bun]|
    Layer4 --> |D3[Deno]|
    Layer4 --> |D4[Browser]|

    Layer5 --> |E1[Base Config]|
    Layer5 --> |E2[Callback Manager]|
    Layer5 --> |E3[Tracer]|
    Layer5 --> |E4[Tool Runtime]|
    Layer5 --> |E5[State Manager]|

    style Application fill:#e1f5ff
    style Layer1 fill:#82c91a
    style Layer2 fill:#fff4e6
    style Layer3 fill:#d1fae5
    style Layer4 fill:#8ec5fc
    style Layer5 fill:#f59e0b

4.2 核心执行流程图

mermaid

graph TD
    User[用户输入] --> |A[选择任务类型]|
    User --> |B[选择提供商]|

    A --> A1[创建 Agent]
    A --> A2[构建 Chain]
    A --> |A3[构建 RAG]|
    A --> |A4[自定义工具]|

    A1 --> |B[配置 LLM]|
    A1 --> |B[绑定工具]|
    A1 --> |B3[设置中间件]|

    B --> |C[准备输入]|
    B --> |C1[合并配置]|
    B --> |C2[加载文档]|

    C --> |D[执行 Runnable]|
    C1 --> |D1[invoke]|
    C1 --> |D2[batch]|
    C1 --> |D3[stream]|

    D --> |E[处理结果]|
    D1 --> |E1[输出解析]|
    D2 --> |E2[错误处理]|
    D3 --> |E3[追踪记录]|

    E --> |F[返回最终结果]|
    F --> |F[发送到用户]|

    style User fill:#e1f5ff
    style A fill:#82c91a
    style B fill:#fff4e6
    style C fill:#d1fae5
    style E fill:#f59e0b
    style F fill:#8ec5fc

5. 核心概念

5.1 统一抽象

Runnable 接口 - 所有可执行组件的统一接口

提供一致的执行语义
支持同步和异步
支持流式和批量处理
可自由组合和嵌套

消息系统 - 类型安全的多模态消息

支持内容块（文本、图像、音频）
版本控制（v0 简单，v1 结构化）
完整的元数据支持

工具系统 - 灵活的工具定义和调用

Zod Schema 验证
运行时上下文注入
结构化错误处理

5.2 可组合性

组件自由组合:

LLM + Prompts + OutputParser → Chain
Chain + VectorStore + Retriever → RAG
RunnableSequence + RunnableParallel → 复杂工作流
RunnableBranch → 条件路由

组合优势:

模块化设计
可测试的单元
可复用的组件
灵活的工作流

5.3 平台兼容

跨平台支持:

Node.js (ESM + CommonJS)
浏览器（完整支持）
Edge (Vercel, Cloudflare, Supabase)
Deno, Bun

适配层:

运行时环境检测
平台特定的优化
统一的 API 接口

6. 使用场景

6.1 快速原型开发流程图

mermaid

graph LR
    Input[需求输入] --> |A[创建 Prompt]|
    Input --> |B[选择 LLM]|

    A --> |C[prompt 管道 LLM]|
    B --> |D[格式化输出]|
    B --> |E[解析工具调用]|

    C --> |F[返回最终结果]|
    D --> |E[返回最终结果]|
    E --> |F[返回最终结果]|

    F --> Output[用户收到结果]

    style Input fill:#e1f5ff
    style A fill:#fff4e6
    style B fill:#d1fae5
    style C fill:#d1fae5
    style D fill:#d1fae5
    style E fill:#f59e0b
    style Output fill:#82c91a

6.2 构建 RAG 应用流程图

mermaid

graph TD
    Documents[文档集合] --> |A[加载文档]|
    Documents --> |B[分割文档]|

    A --> |A1[Text Splitter]|
    B --> |A2[Markdown Splitter]|

    A1 --> |C[分块处理]|
    A2 --> |C[生成嵌入向量]|
    C --> EmbedVectors[创建嵌入]

    B --> |D[存储向量]|
    B --> |E[创建索引]|

    D --> StoreVectors[添加到向量存储]
    E --> CreateRetriever[创建检索器]

    F --> |G[查询向量存储]|
    G --> |H[相似度搜索]|
    H --> |I[返回相关文档]|

    I --> |J[格式化文档]|
    J --> |K[创建 Prompt]|
    K --> PromptLLM[注入到 LLM]

    LLM --> |L[生成回答]|
    L --> Output[返回最终答案]

    style Input fill:#e1f5ff
    style A fill:#fff4e6
    style A1 fill:#d1fae5
    style A2 fill:#d1fae5
    style C fill:#82c91a
    style D fill:#d1fae5
    style E fill:#f59e0b
    style EmbedVectors fill:#8ec5fc
    style StoreVectors fill:#f59e0b
    style CreateRetriever fill:#8ec5fc
    style G fill:#d1fae5
    style H fill:#d1fae5
    style I fill:#82c91a
    style J fill:#82c91a
    style L fill:#d1fae5
    style Output fill:#82c91a

6.3 创建智能 Agent 流程图

mermaid

graph TD
    Input[任务输入] --> |A[定义工具]|
    Input --> |B[创建 Agent]|

    A --> |A1[StructuredTool 1]|
    A --> |A2[StructuredTool 2]|
    A --> |A3[StructuredTool 3]|

    B --> |C[React Agent]|
    B --> |D[配置 LLM]|
    B --> |E[设置中间件]|

    C --> |F[初始化状态]|
    C --> |F1[加载历史]|
    C --> |F2[注册工具]|

    D --> |G[主循环]|
    D --> |H[思考步骤]|
    D --> |I[动作步骤]|

    G --> |G1[Before Model Node]|
    G --> |G2[Before Agent Node]|

    G1 --> |H1[准备 LLM 输入]|
    H --> |I1[添加思考到状态]|

    G2 --> |H2[准备模型输入]|
    H --> |I2[添加工具调用到历史]|

    H --> |J[After Model Node]|
    J --> |J1[解析 LLM 响应]|
    J --> |J2[提取工具调用]|

    J --> |K[Tool Node]|
    K --> |L[执行工具]|
    K --> |M[更新工具输出到状态]|

    M --> |N[After Agent Node]|
    N --> |O[更新对话历史]|
    O --> |P[准备下一轮输入]|

    O --> Output[返回最终答案]

    style Input fill:#e1f5ff
    style A fill:#fff4e6
    style B fill:#d1fae5
    style C fill:#82c91a
    style D fill:#d1fae5
    style F fill:#f59e0b
    style G fill:#fff4e6
    style H fill:#d1fae5
    style I fill:#82c91a
    style J fill:#d1fae5
    style K fill:#d1fae5
    style L fill:#e1f5ff
    style M fill:#f59e0b
    style N --> |O[82c91a]
    style O --> |P[fff4e6
    style Output fill:#f59e0b

7. 扩展指南

7.1 创建自定义工具流程图

mermaid

graph TD
    Input[工具定义] --> |A[实现 Tool 接口]|
    Input --> |B[使用 Zod Schema]|

    A --> |A1[创建 StructuredTool]|
    A --> |A2[创建 DynamicTool]|

    B --> |A11[定义 name]|
    B --> |A12[定义 description]|
    B --> |A13[定义 schema]|

    A11 --> |B1[定义输入类型]|
    B1 --> |B2[提取 Zod 类型]|
    B1 --> |B3[设置默认值]|

    A12 --> |B11[编写 description]|
    B13 --> |B1[实现 invoke 方法]|
    B13 --> |B2[验证输入]|

    B1 --> |C[实现 call 方法]|
    B2 --> |C1[调用 invoke 方法]|
    C --> |C2[处理异常]|

    C2 --> |C3[返回结果]|
    C2 --> |D[返回 ToolMessage]|
    C3 --> Output[返回最终消息]

    A13 --> |D[实现 validate 方法]|
    B13 --> |D1[检查参数类型]|
    D --> |E1[返回验证结果]|
    E --> |F[验证通过]|
    E --> |C[实现工具]|
    C --> Output

    style Input fill:#e1f5ff
    style A fill:#fff4e6
    style B fill:#d1fae5
    style C fill:#d1fae5
    style D fill:#d1fae5
    style E fill:#82c91a
    style Output fill:#f59e0b

7.2 创建自定义提供商流程图

mermaid

graph TD
    Input[提供商配置] --> |A[创建自定义 LLM]|
    Input --> |B[定义模型接口]|

    A --> |A1[继承 BaseChatModel]|
    A1 --> |A2[实现 invoke 方法]|
    A --> |A3[实现 stream 方法]|

    A1 --> |B1[调用自定义 API]|
    A2 --> |B2[处理响应]|
    A --> |B3[解析响应]|

    B --> |C[返回格式化结果]|
    C --> |D[验证和转换]|
    D --> Output[返回最终输出]

    A2 --> |A21[处理错误]|
    A21 --> |A22[重试机制]|
    A22 --> |A23[抛出异常]|

    A --> |B[流式支持]|
    B --> |A21[创建异步迭代器]|
    B --> |A22[yield 每个 chunk]|
    B22 --> Output[流式输出]

    style Input fill:#e1f5ff
    style A fill:#fff4e6
    style B fill:#d1fae5
    style C fill:#d1fae5
    style D fill:#f59e0b
    style Output fill:#82c91a
    style A21 fill:#8ec5fc
    style A22 fill:#fff4e6
    style Output fill:#f59e0b

8. 未来展望

8.1 正在开发的功能

MCP 协议 - 更好的工具生态
多模态 - 视频和音频支持
图优化 - 更高效的图执行
缓存改进 - 分布式缓存

8.2 生态系统

丰富的提供商集成
活跃的社区
完善的文档
生产就绪的工具

9. 最佳实践

9.1 性能优化

1. 使用批量处理

typescript

// ❌ 多次调用
const results = [];
for (const input of inputs) {
  results.push(await llm.invoke(input));
}

// ✅ 批量调用
const results = await llm.batch(inputs);

2. 启用缓存

typescript

import { InMemoryCache } from "@langchain/core";

const cache = new InMemoryCache();
const llm = new ChatOpenAI({ cache });

3. 使用流式输出

typescript

const stream = await llm.stream("Tell me a long story");

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

9.2 错误处理

1. 实现重试机制

typescript

const resilientLlm = llm.withRetry({
  stopAfterAttempt: 3
});

2. 实现降级策略

typescript

const primaryWithFallbacks = llm.withFallbacks([
  backupLlm1,
  backupLlm2,
  backupLlm3
]);

9.3 类型安全

1. 使用 Zod Schema

typescript

import { z } from "zod";

const tool = new StructuredTool({
  name: "calculator",
  schema: z.object({
    a: z.number(),
    b: z.number(),
    operation: z.enum(["add", "subtract", "multiply", "divide"])
  })
});

2. 结构化输出解析

typescript

import { StructuredOutputParser, z } from "@langchain/core";

const parser = new StructuredOutputParser(
  z.object({
    summary: z.string(),
    keywords: z.array(z.string())
  })
);

总结

LangChain.js 是一个设计精良、功能强大的 LLM 应用开发框架：

核心优势

模块化设计 - 清晰的分层架构
类型安全 - 完整的 TypeScript 支持
高度可组合 - 自由组合和嵌套
跨平台 - Node.js, Edge, 浏览器全覆盖
丰富的集成 - 30+ LLM 提供商支持
生产就绪 - 内置监控、缓存、错误处理
活跃社区 - 持续更新和改进

技术亮点

基于 Turbo 的高效 Monorepo 构建
tsdown 编译优化
完整的流式支持
LangSmith 追踪集成
MCP 协议支持
多模态消息支持

适用场景

✅ 快速原型开发
✅ 企业级 AI 应用
✅ 复杂工作流自动化
✅ RAG 知识库系统
✅ 多模型实验和对比
✅ 跨平台部署

分析完成日期: 2026-02-13总文档数: 7 个（每个主要模块 + 架构总结）总字数: 约 110,000 字流程图数: 60+ 个 Mermaid 流程图覆盖范围: Runnable 接口、核心系统、langchain 主包、提供商集成、示例与社区组件、完整架构

LangChain.js 完整架构总结（含流程图） ​

目录 ​

1. 项目概览 ​

1.1 基本信息 ​

1.2 项目结构 ​

1.3 包统计 ​

2. 模块分析汇总 ​

2.1 核心抽象层 ​

2.2 高级功能层 ​

2.3 社区与扩展 ​

3. 技术栈 ​

3.1 开发工具 ​

3.2 构建流程 ​

4. 架构设计 ​

4.1 完整架构流程图 ​

4.2 核心执行流程图 ​

5. 核心概念 ​

5.1 统一抽象 ​

5.2 可组合性 ​

5.3 平台兼容 ​

6. 使用场景 ​

6.1 快速原型开发流程图 ​

6.2 构建 RAG 应用流程图 ​

6.3 创建智能 Agent 流程图 ​

7. 扩展指南 ​

7.1 创建自定义工具流程图 ​

7.2 创建自定义提供商流程图 ​

8. 未来展望 ​

8.1 正在开发的功能 ​

8.2 生态系统 ​

9. 最佳实践 ​

9.1 性能优化 ​

9.2 错误处理 ​

9.3 类型安全 ​

总结 ​

核心优势 ​

技术亮点 ​

适用场景 ​

LangChain.js 完整架构总结（含流程图）

目录

1. 项目概览

1.1 基本信息

1.2 项目结构

1.3 包统计

2. 模块分析汇总

2.1 核心抽象层

2.2 高级功能层

2.3 社区与扩展

3. 技术栈

3.1 开发工具

3.2 构建流程

4. 架构设计

4.1 完整架构流程图

4.2 核心执行流程图

5. 核心概念

5.1 统一抽象

5.2 可组合性

5.3 平台兼容

6. 使用场景

6.1 快速原型开发流程图

6.2 构建 RAG 应用流程图

6.3 创建智能 Agent 流程图

7. 扩展指南

7.1 创建自定义工具流程图

7.2 创建自定义提供商流程图

8. 未来展望

8.1 正在开发的功能

8.2 生态系统

9. 最佳实践

9.1 性能优化

9.2 错误处理

9.3 类型安全

总结

核心优势

技术亮点

适用场景