LangChain 入门教程

发表于 2026-08-14 分类于 ai

基于 LangChain 1.x，从 create_agent、init_chat_model 到 checkpointer 记忆与最小 RAG，适合第一次接触新版 LangChain 的读者。

前言

LangChain 在 1.0 之后把主包收敛到 Agent 构建所需的核心能力，旧版链式 API 迁入 langchain-classic，并统一推荐用 create_agent 搭建智能体。
若你刚接触 LangChain，或正从 0.x 迁移，本文以 LangChain 1.x 为准，覆盖环境安装、统一模型初始化、Agent、对话记忆与最小 RAG。
示例默认走 OpenAI 兼容接口（含国内不少中转服务），密钥与模型名请按你实际环境替换。
下文需要 Python 3.10+，依赖与虚拟环境统一用 uv 管理；LCEL 链式写法仍可在 langchain-core 中使用，但多轮对话与 Agent 场景优先采用 1.x 推荐路径。

依赖

建议使用 Python 3.10 及以上。
在项目目录用 uv 初始化工程、创建虚拟环境并声明依赖（会写入 pyproject.toml 与 uv.lock）。

1
2
3

uv init
uv venv --python 3.12
uv add "langchain>=1.0,<2.0" langchain-openai langchain-community langchain-text-splitters faiss-cpu

后续运行示例脚本时，可直接 uv run python demo.py，一般不必手动 activate 虚拟环境。
若习惯激活，Windows 使用 .venv\Scripts\activate，macOS / Linux 使用 source .venv/bin/activate。

调用云端模型前，设置 API 密钥与可选的自定义 Base URL。

1
2
3

export OPENAI_API_KEY="sk-xxx"
# 可选：兼容 OpenAI 协议的中转或本地网关
export OPENAI_BASE_URL="https://your-gateway/v1"

若你的旧项目仍依赖 LLMChain、ConversationBufferMemory 等 API，执行 uv add langchain-classic 并改 import 路径，本文不展开迁移细节。

实现

核心概念

1.x 主包重点如下，后文示例都围绕它们展开。

Model：用 init_chat_model 统一初始化各厂商 Chat 模型。
Agent：用 create_agent 把模型、工具、系统提示词与中间件串成可执行智能体。
Tools：用 @tool 装饰普通函数，供 Agent 按需调用。
Memory：通过 checkpointer 按 thread_id 持久化会话，替代旧版 RunnableWithMessageHistory 的典型用法。
Retriever：文档切块、向量化与检索仍常用 langchain-community；简单 RAG 可用 LCEL 链或检索 Tool 接入 Agent。

最小调用

1.x 推荐用 init_chat_model 初始化模型，模型名可写 provider:model 形式。
model 请换成你账号可用的名称。

import os

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "openai:gpt-4o-mini",
    temperature=0.2,
    base_url=os.environ.get("OPENAI_BASE_URL"),
)
response = model.invoke("用一句话解释 LangChain 是做什么的。")

for block in response.content_blocks:
    if block["type"] == "text":
        print(block["text"])

1.x 新增 content_blocks，以统一结构读取各厂商返回的文本、推理块等内容；response.content 仍可用，但跨厂商时 content_blocks 更一致。

提示词链

单次问答、固定模板场景仍可用 LCEL（LangChain Expression Language）把提示词与模型用 | 连接。
底层组件来自 langchain-core，与 1.x 主包并存。

import os

from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是中文技术助手，回答要简洁。"),
    ("human", "{question}"),
])

model = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.environ.get("OPENAI_BASE_URL"),
)
chain = prompt | model

result = chain.invoke({"question": "LCEL 里的 | 表示什么？"})
print(result.content)

| 表示前一步输出作为后一步输入；复杂 Agent 编排则优先用 create_agent。

解析输出

链末端可加 StrOutputParser，直接得到字符串，避免手动访问 .content。

import os

from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("把下面主题扩写成一句 Slogan：{topic}")
model = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.environ.get("OPENAI_BASE_URL"),
)

chain = prompt | model | StrOutputParser()
print(chain.invoke({"topic": "开发者博客"}))

基础 Agent

create_agent 是 1.x 构建 Agent 的标准入口，内置 LangGraph 执行循环，支持工具调用与流式输出。
下面定义一个查询「天气」的示例工具。

from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """查询指定城市的天气（示例数据）。"""
    return f"{city} 今天晴，25°C。"

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[get_weather],
    system_prompt="你是 helpful 的中文助手，需要查天气时调用工具。",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "上海天气怎么样？"}]
})
print(result["messages"][-1].content)

Agent 的输入输出都以 messages 列表为中心；最后一条消息即模型回复。

对话记忆

1.x 的多轮记忆通过 checkpointer 实现：同一 thread_id 下的历史会自动带入后续调用。
示例使用内存版 InMemorySaver，上线请换数据库等持久化 checkpointer。

import os

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import InMemorySaver

model = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.environ.get("OPENAI_BASE_URL"),
)

agent = create_agent(
    model=model,
    tools=[],
    system_prompt="你是友好的助手，记得用户说过的话。",
    checkpointer=InMemorySaver(),
)

thread_config = {"configurable": {"thread_id": "demo-user-1"}}

r1 = agent.invoke(
    {"messages": [{"role": "user", "content": "我叫小明。"}]},
    thread_config,
)
print(r1["messages"][-1].content)

r2 = agent.invoke(
    {"messages": [{"role": "user", "content": "我叫什么？"}]},
    thread_config,
)
print(r2["messages"][-1].content)

第二次提问时，模型应能根据同线程历史回答「小明」。
对话过长时可加 SummarizationMiddleware 做摘要，避免撑爆上下文窗口。

最小 RAG

RAG 先检索文档片段再生成答案，适合私有知识库。
1.x 主包提供 init_embeddings 统一初始化嵌入模型；向量库仍用 langchain-community 的 FAISS 做本地原型。

准备文本、切分并构建向量索引。
嵌入模型名请按你的网关能力调整。

import os

from langchain.embeddings import init_embeddings
from langchain_community.vectorstores import FAISS
from langchain_text_splitters import RecursiveCharacterTextSplitter

docs = [
    "LangChain 1.x 用 create_agent 构建 Agent，旧版链式 API 在 langchain-classic。",
    "RAG 流程一般是：加载文档、切分、向量化、检索、再生成答案。",
    "FAISS 是常用的本地向量索引库，适合原型验证。",
]

splitter = RecursiveCharacterTextSplitter(chunk_size=80, chunk_overlap=10)
chunks = splitter.create_documents(docs)

embeddings = init_embeddings(
    "openai:text-embedding-3-small",
    base_url=os.environ.get("OPENAI_BASE_URL"),
)
vectorstore = FAISS.from_documents(chunks, embeddings)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

检索结果注入提示词，用 LCEL 链生成最终答案。

import os

from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

def format_docs(docs):
    return "\n\n".join(d.page_content for d in docs)

prompt = ChatPromptTemplate.from_template(
    "仅根据下列上下文作答；不知道就说不知道。\n\n上下文：\n{context}\n\n问题：{question}"
)

model = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.environ.get("OPENAI_BASE_URL"),
)

rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | model
    | StrOutputParser()
)

print(rag_chain.invoke("RAG 的典型步骤有哪些？"))

生产环境也可把检索封装成 @tool 再交给 create_agent，由 Agent 自行决定是否检索。

流式输出

对 LCEL 链或 Agent 均可流式消费增量结果。
下面演示链式调用的 stream。

import os

from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("写一首关于{topic}的四句短诗。")
model = init_chat_model(
    "openai:gpt-4o-mini",
    streaming=True,
    base_url=os.environ.get("OPENAI_BASE_URL"),
)
chain = prompt | model | StrOutputParser()

for chunk in chain.stream({"topic": "编程"}):
    print(chunk, end="", flush=True)
print()

Agent 场景可对 agent.stream(...) 按事件类型过滤 token 与工具调用，细节见官方流式文档。

验证

按下面顺序自检，确认 1.x 环境与代码路径正常。

在项目目录执行 uv tree | grep langchain，或 uv run python -c "import importlib.metadata as m; print(m.version('langchain'))"，确认主版本号为 1.x。
用 uv run python 运行「最小调用」脚本，终端应打印一句关于 LangChain 的中文说明。
运行「对话记忆」脚本，第二次问「我叫什么」应回答「小明」或同义表述。
运行 RAG 脚本，问题「RAG 的典型步骤有哪些」应提到切分、向量化、检索等关键词。

若报认证错误，优先检查 OPENAI_API_KEY 与 OPENAI_BASE_URL。
若报模型不存在，把示例里的 gpt-4o-mini、text-embedding-3-small 换成你网关支持的名称。
若旧代码 import 失败，检查是否应改用 langchain-classic 或新版 create_agent 路径。

扩展

入门后可沿这些方向继续深入。

Middleware：在 create_agent 中挂载 SummarizationMiddleware、HumanInTheLoopMiddleware 等，处理摘要、人工审批等场景。
langchain-classic：旧版 LLMChain、部分 Retriever 仍在此包，迁移项目执行 uv add langchain-classic。
检索 Tool 化：把 retriever 包成 @tool，与 Agent 工具循环统一编排。
可观测性：接入 LangSmith 记录每次 Agent 与链路的输入输出，便于调试提示词与检索质量。

总结

用 uv init + uv add 安装 langchain>=1.0,<2.0 等依赖，并配置 API 密钥与可选 Base URL。
用 init_chat_model 初始化模型，用 create_agent 构建带工具的 Agent，这是 1.x 最常用路径。
多轮对话给 Agent 配 checkpointer，同一 thread_id 即一条会话线程；上线勿只用内存 checkpointer。
简单 RAG 仍可用 init_embeddings + FAISS + LCEL；复杂场景可把检索做成 Tool 或接 Middleware。
旧版链式与记忆 API 在 langchain-classic，新项目优先 1.x 写法，迁移时对照官方 Migration Guide。