LangChain：概述与安装

你要做的不只是「调一次 OpenAI API」，而是把大语言模型（large language model，LLM）、提示词、工具、检索结果拼成一条可复用的流水线。手写脚本很快会变成：messages 格式不统一、换模型要改一堆代码、工具 schema 与执行脱节。LangChain 把这类重复劳动收成一套 Python 抽象——模型、消息、可组合链（LCEL，LangChain Expression Language）——让你专注业务逻辑。

段末注释：LangChain 在本教程系列中指 Python 包生态（langchain、langchain-core 及各类 langchain-* 集成包），侧重能力层；带环、检查点、审批的编排见 LangGraph 概述。

1. 一句话定位

维度	内容
角色	LLM 应用的能力层：统一消息类型、模型接口、工具绑定、链式组合
输入 → 输出	常见为 `list[BaseMessage]` 或 prompt 变量 → `AIMessage` / `str` / 结构化对象
典型入口	`ChatModel.invoke()`、LCEL 管道 `\|`、`bind_tools()`
与 LangGraph	节点内部常用 LangChain；复杂控制流（环、持久化、HITL）交给 LangGraph

出现背景：LangChain 约 2022 年起将各厂商 LLM API 抽象为统一接口；2025 年 LangChain v1 将旧版 Chain/AgentExecutor 等迁入 langchain-classic，主包聚焦 Agent 与 LCEL。本系列示例按 v1 + 拆分包 写法；若你维护 2024 年前的代码，需对照官方迁移指南。

2. LangChain 在 Agent 栈中的位置

用户 / API
    ↓
LangGraph（可选）—— 图编排、checkpoint、interrupt
    ↓
LangChain —— ChatModel、Prompt、Tool、Retriever、LCEL
    ↓
厂商 SDK / 本地推理 —— OpenAI、Anthropic、Ollama…

层级	解决的问题	本目录是否专讲
Agent 通用概念（ReAct、选型）	为什么要工具、怎么评估	见 `02.开发-16.Agent开发/`
LangChain	怎么调模型、怎么绑工具、怎么串链	是
LangGraph	多步失败重试、会话恢复、人工审批	见 `02.开发-16.Agent-Langgraph/`
RAG 业务架构	切分、召回、评测	见 `02.开发-15.RAG/`
LlamaIndex	私有数据索引、QueryEngine、检索当工具	见 `02.开发-16.Agent-LlamaIndex/`

3. 包拆分地图（安装前必读）

LangChain 是多包 monorepo，按需安装，不必一次装全站。

PyPI 包	职责	是否几乎必装
`langchain-core`	消息、Runnable、Tool 接口等基础抽象	是（通常作为依赖自动安装）
`langchain`	v1 主包：Agent 创建、高层工具	是
`langchain-openai`	OpenAI / Azure OpenAI Chat、Embedding	按模型选
`langchain-anthropic`	Claude 系列	按模型选
`langchain-community`	暂无独立 partner 包的集成（部分 Loader、VectorStore）	按需
`langchain-text-splitters`	文档切分	RAG 场景按需
`langchain-classic`	旧版 `LLMChain`、`AgentExecutor` 等	仅维护 legacy 代码时

LangGraph 是独立包 langgraph，与 langchain 版本需兼容；图编排教程在姊妹目录，本篇只点到为止。

本系列已在专篇标题标注 （弃用） 的 API（文件名不变以免断链）：

旧 API	替代
`RunnableWithMessageHistory`	LangGraph checkpointer（`thread_id`）；可选 Store
`langgraph.prebuilt.create_react_agent`	`langchain.agents.create_agent`（`prompt` → `system_prompt`）

LLMChain / AgentExecutor 等 classic 表面见迁移专篇，不单独把迁移文标成弃用。

4. 环境与安装

4.1 要求

Python 3.10+（v1 要求；勿用 3.9 及以下）
推荐虚拟环境：venv / conda / uv

版本锚点（检索于 2026-08-18 PyPI）：

包	当时最新稳定版	备注
`langchain`	1.3.15	依赖 `langchain-core>=1.5.4,<2.0` 与 `langgraph>=1.2.11,<1.3.0`
`langchain-core`	1.5.6	消息、Runnable、Tool 等抽象
`langgraph`	1.2.11	图编排；与主包 1.3.x 配套

安装仍用 pip install -U langchain ...；专篇若行为依赖小版本，在该篇标明「验证于 x.x.x」。

4.2 最小安装（OpenAI 示例）

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -U langchain langchain-openai

其他厂商示例：

1 2	pip install -U langchain-anthropic # Claude pip install -U langchain-ollama # 本地 Ollama

4.3 环境变量

1 2	export OPENAI_API_KEY="sk-..." # 勿提交到 Git # export ANTHROPIC_API_KEY="..."

4.4 验证安装

1	python -c "import langchain; import langchain_core; print('ok', langchain.__version__)"

无报错即基础环境可用。版本号随发行变化，正文专篇会标注「验证于 x.x.x」。

4.5 常见安装问题

现象	处理
`ModuleNotFoundError: langchain.chains`	你在 v1 环境跑旧教程；改 import 或 `pip install langchain-classic`
`ModuleNotFoundError: langchain_openai`	未装 partner 包：`pip install langchain-openai`
与 LangGraph 版本冲突	同环境 `pip install -U langchain langgraph`，查阅 LangGraph 安装说明

5. 核心抽象（读专篇前的最小概念）

5.1 消息（Messages）

对话单元统一为 BaseMessage 子类：

类型	角色	典型用途
`SystemMessage`	system	角色与约束
`HumanMessage`	user	用户输入
`AIMessage`	assistant	模型回复；可含 `tool_calls`
`ToolMessage`	tool	工具执行结果；须带 `tool_call_id`

5.2 Runnable 与 LCEL

实现了 invoke / stream 的对象都可参与 LCEL 管道，用 | 连接：

1	prompt \| model \| output_parser

数据从左向右流；每段输入/输出类型在编译期可检查（详见专篇 LangChain-04-链-LCEL与Runnable）。

5.3 一次调用的数据流（直觉）

1. 构造 messages 或 prompt 变量
2. ChatModel.invoke(...) 或 chain.invoke(...)
3. 得到 AIMessage（含 content，或 tool_calls）
4. 若有 tool：执行工具 → ToolMessage 回填 → 再 invoke
5. 可选：output_parser 转为 str / Pydantic 对象

6. 最小可运行示例

本系列默认接本地 Ollama（OpenAI 兼容 /v1）。先 ollama serve，再 ollama pull qwen3.5:9b。云厂商只需去掉 base_url，改用环境变量里的 API Key。

1	pip install -U langchain langchain-openai

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 本地 Ollama；云端改为 ChatOpenAI(model="gpt-4o-mini") 并设置 OPENAI_API_KEY
model = ChatOpenAI(
    model="qwen3.5:9b",
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    temperature=0,
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "只回答事实，一句话，不要解释。"),
    ("human", "{province}的省会是哪座城市？"),
])
chain = prompt | model | StrOutputParser()

print(chain.invoke({"province": "浙江"}))
# 预期形态：含「杭州」（真实模型措辞会变）

要点：

ChatPromptTemplate 把 {province} 填进 messages。
| 把 prompt → model → parser 连成一条链；invoke 得到字符串。
换模型只改构造器，链结构不变。

重要配置参数（ChatModel 入门）

参数	类型 / 默认值	功能说明	作用与影响	参考起点	配置指导
`model`	str，必填	指定 Chat 模型 ID	决定能力与价格	`gpt-4o-mini` / 厂商文档	原型用小模型；上线前评测再换
`temperature`	float，视厂商	控制生成随机性	越高越发散	0～0.3（事实类）	工具调用、结构化输出宜偏低
`max_tokens`	int，可选	限制回复 token 上限	过小截断 JSON/tool	1024～4096	工具场景留足长度
`timeout`	float，可选	单次请求超时秒数	过短误杀、过长占连接	30～120	长文档加大
`api_key`	str，可选	厂商鉴权	缺失则无法调用	环境变量优先	勿硬编码进仓库

完整参数见专篇 LangChain-01-模型-ChatModel。

7. 推荐阅读顺序

配合 LangChain-00.知识点索引使用。已知 Agent 原理、只缺「需求 → 函数」时，直接打开函数应用速查。

阶段	专篇主题	你会获得什么
0	函数应用速查	按任务抄到类/方法与一行用法
1	ChatModel、Messages	会调模型、会拼对话
2	PromptTemplate	可复用提示词与变量
3	LCEL 与 Runnable	会串管道、会 stream
4	Tool / bind_tools	模型能「动手」
5	Retriever、Embedding	接私有知识（RAG 能力层）
6	Memory（新项目用 LangGraph checkpoint；`RunnableWithMessageHistory` 已弃用）	多轮上下文
7	Structured Output	稳定 JSON / Pydantic
8	`create_agent`（勿用已弃用的 `create_react_agent`）	快速 Agent 原型
9+	LangGraph 目录	环、checkpoint、HITL

若你完全没接触过 Agent 概念，建议并行阅读 02.开发-16.Agent开发/ 中 Agent-10-02 Tool Calling（原理层，非 LangChain API 专讲）。

8. 何时只用 LangChain、何时上 LangGraph

场景	建议
单次问答、一次检索+生成	LangChain Chain 足够
多步工具、失败要重试	考虑 LangGraph
进程重启后续跑、人工审批	LangGraph + checkpointer
线性 DAG、无环	LangChain LCEL 或 LangGraph 均可，选更简单的

9. 调试与观测（入门）

手段	用法
打印中间 messages	`invoke` 前后 `print` / 日志
Verbose	部分链支持 `chain.invoke(..., config={"verbose": True})`
LangSmith	设置 `LANGCHAIN_TRACING_V2=true` 与 `LANGCHAIN_API_KEY`；见追踪文档

10. 易踩坑

照抄 2024 旧文 import：v1 大量路径变更；以官方文档为准。
只装 langchain 不装 partner 包：ChatOpenAI 在 langchain-openai。
Tool 消息缺 tool_call_id：会导致下一轮模型上下文非法。
在 FastAPI 里用同步 invoke 阻塞事件循环：高并发应 ainvoke（专篇说明）。

小结

LangChain 提供统一消息、模型、工具、LCEL，是 Agent 应用的能力层。
安装按包拆分：langchain + 模型 partner 包；Python 3.10+。
先跑通 Prompt | Model | Parser，再读索引中的 Tool、RAG、Structured Output。
出现环、持久化、审批时，转到 LangGraph 目录。