[LangChain] v1.0 新版架构 Quick Start 踩坑指南 - M-T

📅 发布时间：2026/6/22 20:20:14

LangChain 学习笔记 001

概览：精读 LangChain 核心概念（Chain、Agent、Tool、Memory），跑通官方 Quick Start。

一、LangChain 是什么

LangChain 是一个专门用于开发 LLM 应用的框架，将各个不同的 LLM 接口进行抽象包装，统一使用一套规则，并提供从模型调用到智能体编排的完整工具链。

⚠️ 注意：LangGraph 是 LangChain 生态的独立扩展库，不是 LangChain 本身的一个层级。下文"编排层"单独列出，不归属于 LangChain 架构内部。

二、LangChain 架构

2.1 核心层

抽象接口：对不同 LLM 的接口进行统一封装，屏蔽底层差异
消息格式：定义标准消息类型（见下文"消息类型体系"）
序列化：统一 I/O 格式
LCEL（LangChain Expression Language）：组件组合方式，通过管道符 | 将各组件串联

# LCEL 示例：管道符背后是 Runnable 接口
chain = prompt | llm | output_parser

每个组件都实现了 invoke / stream / batch 三种调用方式。

2.2 集成层

不仅集成 LLM 模型，还集成：

数据库（PostgreSQL、Redis 等）
文档加载器（PDF、HTML 等）
向量数据库（Pinecone、ChromaDB 等）
外部工具（搜索引擎、API 等）

2.3 应用层

大多数开发者在这一层调用已配置好的高级功能：

Chain

预定义的工作流程，如 RetrievalQA、ConversationalRetrievalChain。
检索组件是 LLM 通过 RAG 模式链接外部知识体系的重要组成部分。

Agent

具备推理和工具使用能力的智能体。将语言模型与工具相结合，创建能够推理任务、决定使用哪些工具并迭代地寻找解决方案的系统。

⚠️ 重要说明：在 LangChain 中创建 Agent（如 create_react_agent）相当于 initialize agent，只是配置可用工具和推理方式。若需要完整的执行循环，旧版需配合 AgentExecutor 包装，现代推荐做法是在 LangGraph 中进行编排（将 agent 作为一个 node，配合条件边和状态机完成完整流程）。

Tool

高级封装工具，扩展外部能力的接口，支持自定义工具。

Memory

对话历史管理和上下文维护，实现有状态的连续交互。

类型	说明
`ConversationBufferMemory`	保存完整对话历史（旧版，已软性弃用）
`VectorStoreRetrieverMemory`	通过向量数据库实现长期记忆
LangGraph Checkpointer	现代推荐方式，如 `MemorySaver`，实现状态持久化

⚠️ 现状说明：LangChain 内置 Memory 模块在新版本中已软性弃用。现代做法：

短期记忆：直接将 messages history 注入 prompt

长期记忆：使用 LangGraph 的 checkpointer 做状态持久化

三、LangGraph 编排层（独立库）

LangGraph 是 LangChain 生态的扩展，用于替代旧版 AgentExecutor，提供更灵活的控制流。

State Graph：基于状态机的工作流定义
持久化状态：支持长时间运行的复杂任务
多代理协作：多个 AI 代理协同工作的框架
循环和条件：支持 if-else、for、while 等控制流

典型用法：将 LangChain Agent 作为一个 node 嵌入 LangGraph，再添加条件边、工具节点，完成完整流程编排。

四、消息类型体系

理解 Agent 工作原理的关键。

消息类型	说明
`HumanMessage`	用户输入
`AIMessage`	模型输出，可携带 `tool_calls` 字段表达工具调用意图
`ToolMessage`	工具执行结果，回传给模型
`SystemMessage`	系统提示词

Agent Loop 本质：模型输出带 tool_calls 的 AIMessage → 执行工具 → 以 ToolMessage 回传 → 模型继续推理 → 直到输出最终答案。

五、Quick Start 实践记录

5.1 安装顺序

pip install langchain
pip install langchain-openai   # 或其他具体集成

5.2 OpenAI vs ChatOpenAI 的区别

类	适用模型	支持工具调用
`OpenAI`	纯文本补全模型（如 `gpt-3.5-turbo-instruct`）	❌ 无 `bind_tools`
`ChatOpenAI`	对话补全模型（如 `gpt-4o`, `gpt-3.5-turbo`）	✅ 支持

踩坑：使用旧版 OpenAI 类创建 Agent 时报错，原因是该类不支持工具绑定（bind_tools）。需切换为 ChatOpenAI。

5.3 更换为本地 Ollama 模型

无 OpenAI quota 时，改用本地 Ollama。因为在 Docker 中运行并暴露端口，需额外传入 base_url：

from langchain_ollama import ChatOllamallm = ChatOllama(model="...",   # 模型名称需写全，如果有参数需要写上base_url="http://localhost:11434"
)

确认模型名称：
docker exec -it ollama ollama list

5.4 Agent 只表达意图，不自动执行

现象：Agent 返回"我想调用 get_weather"，程序即结束，工具未被执行。

原因：LangChain 的 create_agent 封装只负责让模型完成推理、表达工具调用意图（Intent），不负责执行工具。执行循环需要额外层：

旧版方式：用 AgentExecutor 包装 agent，由它驱动执行循环
现代推荐：在 LangGraph 中将 agent 作为 node，配合 ToolNode 和条件边完成完整执行流程

六、总结：组件关系

用户输入↓
Agent（LLM 推理，基于 HumanMessage + SystemMessage）↓ 输出 AIMessage（携带 tool_calls）
Tool 执行↓ 返回 ToolMessage
Agent 继续推理（Memory 贯穿全程）↓
最终输出

[LangChain] v1.0 新版架构 Quick Start 踩坑指南 - M-T