LangChain v1.x 最新官方完整教程（六大核心组件全解析+生产级代码示例）

一、教程说明 & 官方架构总览

1.1 教程简介

本文基于 2026年 LangChain 官方最新稳定版（v1.x） 重写，完全对标官网 Concepts 权威定义，摒弃所有废弃 API、修正旧版概念错误。全文严格采用 LangChain 六大核心组件 标准体系，所有代码为生产级可直接运行写法，适配 Python3.9--3.12，适合入门学习、项目开发与面试备考。

1.2 LangChain 核心定位

LangChain 是面向大语言模型（LLM）的生产级AI应用编排框架，核心解决 LLM 无记忆、无外部知识、无法自主执行任务的短板，可快速搭建对话机器人、知识库问答（RAG）、智能Agent、自动化工作流等应用。

1.3 官方标准六大核心组件（全文统一标准答案）

LangChain 所有应用均由以下六大核心组件组合构建，为官网固定标准，无增减、无合并：

1. Models（模型组件） ：各类大模型、嵌入模型统一调用底座
2. Prompts（提示模板组件） ：标准化、可复用的提示词工程体系
3. Output Parsers（输出解析组件） ：非结构化文本转结构化数据
4. Memory（记忆组件） ：会话上下文存储与管理，实现多轮对话
5. Documents（文档组件） ：外部文件/网页数据加载、清洗、切片预处理
6. Retrieval（检索组件） ：向量召回、知识增强，含工具调用与Agent智能调度能力

1.4 官方四大核心依赖库

• langchain-core：底层核心抽象、LCEL语法、Runnable通用接口
• langchain：高阶业务能力、链式编排、通用应用封装
• langchain-community：第三方模型、向量库、文档加载器生态集成
• langgraph：官方工作流引擎，支撑复杂Agent循环、分支、状态持久化

二、环境搭建（官方标准安装配置）

2.1 依赖安装

# 核心框架
pip install langchain langchain-core langgraph
# 生态与模型适配
pip install langchain-community langchain-openai
# 工具依赖
pip install faiss-cpu python-dotenv pydantic

2.2 环境变量配置

项目根目录新建 .env 文件，统一管理密钥与配置：

OPENAI_API_KEY=你的密钥
OPENAI_BASE_URL=模型代理地址（可选）
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=你的LangSmith密钥
LANGCHAIN_PROJECT=LangChain-v1.x-Demo

三、六大核心组件详解 + 完整可运行代码

本章为教程核心，逐一对标官方定义，包含组件原理、核心作用、适用场景、生产级代码。

3.1 Models 模型组件（AI推理底座）

组件原理

Models 是 LangChain 最底层核心组件，统一全球所有大模型的调用协议，屏蔽不同厂商 API 差异，支持一键切换模型。v1.x 分为三类标准模型：对话模型、补全模型、嵌入模型。

核心分类

• ChatModel：对话模型（GPT-4o、DeepSeek、Qwen），官方首选，支持多角色、工具调用、流式输出
• LLM：文本补全模型，仅用于传统文本生成场景
• Embeddings：嵌入模型，用于文本向量化，支撑RAG检索场景

统一通用方法

所有模型通用：invoke()单次调用、stream()流式输出、batch()批量调用，同时支持异步方法。

代码示例

from dotenv import load_dotenv
import os
from langchain_openai import ChatOpenAI, OpenAI, OpenAIEmbeddings

load_dotenv()

# 1. 初始化对话模型（生产首选）
chat_model = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0.7,
    max_tokens=2048,
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),
    streaming=True
)

# 2. 初始化文本补全模型
llm = OpenAI(model="gpt-3.5-turbo-instruct", temperature=0.5)

# 3. 初始化嵌入模型
embedding = OpenAIEmbeddings()

if __name__ == "__main__":
    # 单次调用
    res = chat_model.invoke("简述LangChain六大核心组件")
    print("单次调用结果：", res.content)

    # 流式输出
    print("\n流式输出：")
    for chunk in chat_model.stream("Models组件的核心作用"):
        print(chunk.content, end="", flush=True)

3.2 Prompts 提示模板组件（提示工程标准化）

组件原理

Prompt 组件用于解决硬编码提示词不可复用、格式混乱、无法动态传参的问题。通过模板封装系统指令、用户问题、历史上下文，实现提示词统一管理、批量复用、动态渲染。

核心消息类型

• SystemMessage：系统角色，定义模型身份与行为规范
• HumanMessage：用户输入消息
• AIMessage：模型历史回复消息

代码示例

from langchain_core.prompts import ChatPromptTemplate

# 构建多角色可复用提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是LangChain技术专家，回答简洁专业，适配初学者"),
    ("human", "请详细讲解{component}的核心作用与使用场景")
])

# 动态传参渲染模板
format_prompt = prompt.format(component="Prompts提示模板组件")
print("渲染后提示词：\n", format_prompt)

# LCEL组合调用
chain = prompt | chat_model
res = chain.invoke({"component": "Output Parsers输出解析组件"})
print("\n模型回复：\n", res.content)

3.3 Output Parsers 输出解析组件（结构化输出）

组件原理

大模型默认输出非结构化自由文本，无法对接程序逻辑、数据库、前端渲染。Output Parsers 核心作用是约束并解析模型输出格式，将文本转为 JSON、列表、自定义对象等结构化数据，是业务落地的必备组件。

常用解析器

• JsonOutputParser：通用JSON解析
• PydanticOutputParser：强类型模型校验（生产首选）
• CommaSeparatedListOutputParser：列表解析

代码示例

from langchain_core.output_parsers import JsonOutputParser
from pydantic import BaseModel, Field
from typing import List

# 自定义结构化数据模型
class LangChainComponent(BaseModel):
    component_name: str = Field(description="组件名称")
    core_function: str = Field(description="核心功能")
    application_scene: List[str] = Field(description="适用场景")

# 初始化解析器
parser = JsonOutputParser(pydantic_object=LangChainComponent)

# 带格式约束的提示词
prompt = ChatPromptTemplate.from_messages([
    ("system", "严格输出JSON格式，无多余内容"),
    ("human", "介绍LangChain六大核心组件中的Memory组件：{format_instructions}")
]).partial(format_instructions=parser.get_format_instructions())

# 完整链路
chain = prompt | chat_model | parser
res = chain.invoke({})
print("结构化解析结果：\n", res)
print("适用场景：\n", res["application_scene"])

3.4 Memory 记忆组件（多轮对话上下文）

组件原理

LLM 无原生上下文记忆，单次请求相互独立。Memory 组件负责存储、管理、迭代对话历史，实现连续多轮对话。v1.x 废弃全局记忆，统一使用会话级隔离记忆，支持多用户并发、上下文持久化。

核心记忆类型

• ChatMessageHistory：完整会话记忆，存储全量对话
• SummaryMemory：摘要记忆，压缩历史消息，降低Token消耗
• EntityMemory：实体记忆，持久化关键信息

代码示例

from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_community.chat_message_histories import ChatMessageHistory

# 会话存储（生产可替换Redis/数据库）
session_store = {}

# 获取会话历史
def get_session(session_id: str) -> ChatMessageHistory:
    if session_id not in session_store:
        session_store[session_id] = ChatMessageHistory()
    return session_store[session_id]

# 基础对话链路
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是AI助手，记住用户对话信息，连贯回答"),
    ("human", "{input}")
])
base_chain = prompt | chat_model

# 包装会话记忆
memory_chain = RunnableWithMessageHistory(
    runnable=base_chain,
    get_session_history=get_session,
    input_messages_key="input"
)

# 多会话隔离测试
if __name__ == "__main__":
    memory_chain.invoke({"input": "我叫小明"}, config={"session_id": "user_001"})
    print("用户001提问结果：", memory_chain.invoke({"input": "我叫什么名字？"}, config={"session_id": "user_001"}).content)
    
    print("用户002提问结果：", memory_chain.invoke({"input": "我叫什么名字？"}, config={"session_id": "user_002"}).content)

3.5 Documents 文档组件（外部数据预处理）

组件原理

Documents 是官方独立核心组件，为 RAG 提供原始数据预处理能力。负责加载各类外部数据、清洗冗余内容、智能切片，将异构数据统一封装为标准 Document 对象，是所有知识库应用的前置基础。

核心能力

• 多源加载：支持TXT、PDF、网页、数据库、Excel等数百种数据源
• 标准化封装：统一 page_content 内容 + metadata 元数据结构
• 智能切片：解决长文本上下文溢出问题，适配模型输入窗口

代码示例

from langchain_core.documents import Document
from langchain_community.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter

# 1. 手动创建标准文档对象
doc = Document(
    page_content="LangChain六大核心组件：Models、Prompts、Output Parsers、Memory、Documents、Retrieval",
    metadata={"source": "官方文档", "version": "v1.x"}
)
print("标准文档内容：", doc.page_content)
print("文档元数据：", doc.metadata)

# 2. 加载本地文件
loader = TextLoader("test.txt", encoding="utf-8")
raw_docs = loader.load()

# 3. 智能文本切片
splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50,
    separators=["\n\n", "\n", "。"]
)
split_docs = splitter.split_documents(raw_docs)
print(f"\n切片后文档片段数量：{len(split_docs)}")

3.6 Retrieval 检索组件（知识增强+Agent调度）

组件原理

Retrieval 是六大组件最后一环，承接 Documents 预处理后的标准化文档，完成向量化存储、语义召回、知识增强问答。同时集成工具调用与智能Agent能力，支持模型自主调用外部工具、自主决策执行任务，是实现RAG知识库与自动化智能体的核心。

核心能力

• 向量检索：相似度匹配、MRR精准召回
• 工具扩展：自定义计算器、搜索、接口调用工具
• Agent自主执行：基于LangGraph实现思考-决策-工具调用循环

示例1：基础RAG检索问答

from langchain_community.vectorstores import FAISS
from langchain.chains import RetrievalQA

# 承接上文文档切片与嵌入模型
vector_db = FAISS.from_documents(split_docs, embedding)
retriever = vector_db.as_retriever(search_type="similarity", k=3)

# 构建RAG问答链路
rag_chain = RetrievalQA.from_chain_type(
    llm=chat_model,
    retriever=retriever,
    return_source_documents=True
)

# 问答测试
res = rag_chain.invoke("LangChain六大核心组件是什么？")
print("RAG问答结果：", res["result"])

示例2：Agent工具调用

from langchain.tools import tool
from langgraph.prebuilt import create_react_agent

# 自定义工具
@tool
def calculator(express: str) -> str:
    """数学计算工具，用于处理所有数学运算"""
    return str(eval(express))

# 创建官方标准Agent
agent = create_react_agent(chat_model, tools=[calculator])

# 自主执行任务
res = agent.invoke({"messages": [("human", "计算 256*18+720 的结果")]})
print("Agent执行结果：", res["messages"][-1].content)

四、LCEL 核心编排语法（v1.x官方标准）

4.1 语法简介

LCEL（LangChain Expression Language）是 v1.x 唯一官方组件组合语法，通过 | 管道符串联所有Runnable组件，替代老旧Chain写法，具备极简、异步、流式、可观测、可嵌套的优势。

4.2 通用链路模板

# 标准链路：提示词 -> 模型 -> 解析器
chain = ChatPromptTemplate.from_messages([
    ("system", "精简回答用户问题"),
    ("human", "{query}")
]) | chat_model | JsonOutputParser()

# 批量调用
res = chain.batch([{"query": "什么是LCEL"}, {"query": "什么是RAG"}])
print(res)

五、综合实战：带记忆+RAG结构化问答完整项目

整合六大核心组件，实现企业级轻量化知识库问答系统，支持多轮记忆、私有文档检索、结构化输出。

from dotenv import load_dotenv
import os
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader
from langchain_community.vectorstores import FAISS
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_community.chat_message_histories import ChatMessageHistory
from langchain_core.output_parsers import JsonOutputParser
from langchain_core.runnables import RunnableParallel, RunnablePassthrough

load_dotenv()

# 1. 初始化基础组件
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0, api_key=os.getenv("OPENAI_API_KEY"))
embeddings = OpenAIEmbeddings()
session_store = {}

# 2. 会话记忆
def get_session(sid):
    return session_store.setdefault(sid, ChatMessageHistory())

# 3. 文档处理（Documents组件）
loader = TextLoader("langchain_doc.txt", encoding="utf-8")
docs = loader.load()
split_docs = RecursiveCharacterTextSplitter(chunk_size=600, chunk_overlap=60).split_documents(docs)

# 4. 向量库与检索（Retrieval组件）
vector_db = FAISS.from_documents(split_docs, embeddings)
retriever = vector_db.as_retriever(k=3)

# 5. 提示模板（Prompts组件）
rag_prompt = ChatPromptTemplate.from_messages([
    ("system", "基于参考文档精准回答，结合上下文连贯回复：{context}"),
    ("human", "{question}")
])

# 6. LCEL链路编排
rag_chain = RunnableParallel(
    context=lambda x: retriever.invoke(x["question"]),
    question=RunnablePassthrough()
) | rag_prompt | llm

# 7. 包装记忆链路
chat_rag = RunnableWithMessageHistory(rag_chain, get_session, input_messages_key="question")

# 8. 项目调用
if __name__ == "__main__":
    result = chat_rag.invoke(
        {"question": "LangChain六大核心组件分别是什么？"},
        config={"session_id": "final_demo_001"}
    )
    print("最终问答结果：\n", result.content)

六、v1.x 版本核心升级总结

• 概念标准化：固定六大核心组件体系，彻底统一官方定义
• Agent架构升级：全量基于LangGraph驱动，支持循环、分支、状态持久化
• 记忆机制革新：废弃全局记忆，默认会话隔离，适配高并发生产场景
• API极简精简：淘汰大量冗余废弃API，开发门槛大幅降低
• 生产能力增强：原生支持结构化校验、链路追踪、异步流式调度

七、生产最佳实践

• 严格遵循六大组件分层逻辑：文档预处理→向量存储→检索增强→模型生成→结构化解析
• 生产场景必须使用 Pydantic 强类型解析，避免输出格式错乱
• 多用户场景统一使用会话级记忆，禁止全局静态记忆
• 长对话启用摘要记忆，长文档规范切片，控制Token消耗
• 生产环境开启LangSmith追踪，便于链路调试与问题排查