本文基于 LangChain Python 最新官方文档整理，适合第一次接触 LangChain 的开发者。
文档核对日期：2026 年 7 月。

前言

大语言模型可以完成问答、翻译、摘要和代码生成，但在真实项目中，我们通常还需要让模型具备以下能力：

  • 按照固定模板组织提示词；

  • 调用搜索、数据库、计算器等外部工具；

  • 记住同一轮对话中的历史信息；

  • 返回可以被程序直接处理的结构化数据；

  • 将多个处理步骤组合成完整应用。

LangChain 的作用，就是为这些需求提供统一的开发框架。

当前 LangChain v1 的核心定位是构建 AI Agent。官方将 Agent 概括为“模型加运行框架”，开发者可以组合模型、工具、提示词、记忆和中间件，快速构建自己的 AI 应用。

一、LangChain 是什么

LangChain 是一个用于开发大语言模型应用的开源框架。

它并不是一个大语言模型，也不提供模型本身，而是帮助开发者连接和组织：

用户输入
   ↓
提示词 Prompt
   ↓
大语言模型 Model
   ↓
工具 Tools / 数据库 / 搜索服务
   ↓
Agent 决策
   ↓
最终结果

LangChain 支持 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Hugging Face、Ollama 等主流模型提供商。

不同模型提供商通过独立的集成包接入，但它们实现了相同的标准接口，因此更换模型时通常不需要重写整个业务流程。

LangChain 生态中的几个名词

项目 主要用途
LangChain 快速构建模型应用和 Agent
LangGraph 构建复杂、可控制的工作流和 Agent 流程
Deep Agents 提供规划、文件系统、子 Agent 等高级能力
LangSmith 调试、追踪、测试和评估大模型应用

对于新手而言，建议先学习 LangChain，再根据项目复杂度学习 LangGraph。

二、LangChain v1 有哪些变化

网上很多 LangChain 教程基于 0.x 版本，可能会看到以下写法：

from langchain.chains import LLMChain
from langchain.agents import initialize_agent
from langgraph.prebuilt import create_react_agent

这些写法不适合作为当前新项目的首选方案。

在 LangChain v1 中：

  1. create_agent 成为构建 Agent 的标准入口；

  2. 原来的部分旧功能被移动到 langchain-classic；

  3. 模型、工具、消息和 Agent 的命名空间更加精简；

  4. 官方推荐通过独立 provider 包接入不同模型。

create_agent 已经取代 langgraph.prebuilt.create_react_agent，成为当前 LangChain 官方推荐的 Agent 构建方式。

因此，在查阅教程时要注意发布时间和 LangChain 版本。

三、安装 LangChain

1. Python 版本要求

当前 LangChain Python 要求：

Python 3.10+

建议使用 Python 3.11 或 Python 3.12，并创建独立虚拟环境。官方安装文档明确要求 Python 3.10 及以上版本。

2. 创建虚拟环境

Windows：

python -m venv .venv
.venv\Scripts\activate

Linux 或 macOS：

python3 -m venv .venv
source .venv/bin/activate

3. 安装基础依赖

本文以 OpenAI 模型为例：

pip install -U langchain langchain-openai

也可以使用带可选依赖的安装方式：

pip install -U "langchain[openai]"

LangChain 主框架和模型集成包是分开维护的。使用 OpenAI 时需要安装 langchain-openai；使用其他模型时，则需要安装对应的 provider 包。

查看安装结果：

pip show langchain
pip show langchain-openai

四、配置模型 API Key

不要直接把真实 API Key 写入源代码，更不要上传到 GitHub。

Windows PowerShell

$env:OPENAI_API_KEY="你的API-Key"

Linux 或 macOS

export OPENAI_API_KEY="你的API-Key"

也可以在 Python 中临时设置：

import os

os.environ["OPENAI_API_KEY"] = "你的API-Key"

最后一种方式只适合本地测试，生产环境应使用环境变量或密钥管理服务。

官方文档同样推荐通过 OPENAI_API_KEY 等环境变量配置模型凭证。

五、第一次调用大语言模型

LangChain 当前推荐使用 init_chat_model 快速初始化聊天模型。

新建 01_model.py：

from langchain.chat_models import init_chat_model


model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

response = model.invoke("请用一句话解释什么是 LangChain。")

print(response.content)

运行：

python 01_model.py

可能得到类似结果：

LangChain 是一个用于连接大语言模型、提示词、工具和外部数据的应用开发框架。

这里的模型名称应替换为当前账号实际可以使用的模型。

代码解释

model = init_chat_model("openai:gpt-5.5")

模型名称采用：

提供商:模型名称

这种格式。

例如：

"openai:gpt-5.5"
"google_genai:gemini-2.5-flash-lite"

模型名称会直接传递给对应的模型提供商，因此模型提供商发布新模型后，通常不需要等待 LangChain 主包更新。

invoke() 返回的不是普通字符串

model.invoke() 返回的是消息对象，而不是 Python 字符串。

response = model.invoke("你好")

print(type(response))
print(response.content)

常用属性包括：

response.content
response.content_blocks
response.response_metadata
response.usage_metadata

其中：

  • content：模型生成的主要内容；

  • content_blocks：标准化后的内容块；

  • usage_metadata：Token 使用情况；

  • response_metadata：模型响应元数据。

LangChain v1 增加了标准内容块接口，用于统一不同模型提供商的文本、推理、工具调用等内容。

六、理解消息 Messages

聊天模型接收的不是单个字符串，而是一组带角色的消息。

常见角色包括：

角色 作用
system 设置模型身份、规则和行为
user 用户输入
assistant 模型历史回复
tool 工具执行结果

示例：

from langchain.chat_models import init_chat_model


model = init_chat_model("openai:gpt-5.5")

messages = [
    {
        "role": "system",
        "content": "你是一名 Python 入门老师，回答需要简洁并提供示例。",
    },
    {
        "role": "user",
        "content": "什么是 Python 列表？",
    },
]

response = model.invoke(messages)

print(response.content)

通过 system 消息，可以限制模型的角色、回答风格和输出规则。

七、使用 Prompt Template 管理提示词

如果每次都手动拼接字符串，代码会变得难以维护。

LangChain 提供了 ChatPromptTemplate，用于创建可复用的聊天提示词模板。

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


model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

prompt = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "你是一名专业的{role}，请使用适合初学者的语言回答。",
        ),
        (
            "user",
            "请介绍一下{topic}，并提供一个简单示例。",
        ),
    ]
)

messages = prompt.invoke(
    {
        "role": "Python 教师",
        "topic": "列表推导式",
    }
)

response = model.invoke(messages)

print(response.content)

模板中的：

{role}
{topic}

属于动态变量。

程序运行时，LangChain 会把变量替换成实际值。

ChatPromptTemplate 的主要作用是以程序化方式创建和管理聊天模型提示词。

八、使用管道符组合调用链

LangChain 中的很多组件都实现了统一的 Runnable 接口，可以使用 | 管道符进行组合。

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


model = init_chat_model(
    "openai:gpt-5.5",
    temperature=0,
)

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "你是一名计算机基础课程老师。"),
        ("user", "请用通俗的语言解释：{question}"),
    ]
)

chain = prompt | model

response = chain.invoke(
    {
        "question": "什么是 RESTful API？",
    }
)

print(response.content)

执行过程相当于：

输入字典
  ↓
Prompt Template
  ↓
生成消息列表
  ↓
Chat Model
  ↓
AIMessage

使用管道符后，不需要分别调用每一个组件。

九、流式输出

普通 invoke() 会等待模型生成完整答案后一次性返回。

聊天程序通常更适合使用流式输出：

from langchain.chat_models import init_chat_model


model = init_chat_model("openai:gpt-5.5")

for chunk in model.stream("请介绍一下 Python 装饰器。"):
    print(chunk.content, end="", flush=True)

执行时，内容会逐步打印出来。

除了 invoke() 和 stream()，LangChain 模型还提供 batch()，可以批量处理多个请求。官方模型接口将 invoke、stream 和 batch 列为三个基础调用方法。

批量调用示例：

questions = [
    "什么是变量？",
    "什么是函数？",
    "什么是类？",
]

responses = model.batch(questions)

for response in responses:
    print(response.content)
    print("-" * 30)

十、什么是 Tool

大语言模型本身并不能直接：

  • 查询实时天气；

  • 访问公司数据库；

  • 读取业务系统；

  • 执行订单；

  • 发送邮件；

  • 调用第三方接口。

Tool 可以把普通 Python 函数包装成模型能够理解和调用的工具。

模型会根据：

  1. 工具名称；

  2. 参数类型；

  3. 函数说明；

  4. 当前用户问题；

判断是否需要使用工具。

官方文档将 Tool 定义为具有明确输入和输出的可调用函数，模型可以根据对话上下文决定何时调用以及传入什么参数。

创建第一个工具

from langchain.tools import tool


@tool
def calculate_total(price: float, count: int) -> float:
    """计算商品总价。

    Args:
        price: 商品单价
        count: 商品数量
    """
    return price * count

工具的类型注解非常重要：

price: float
count: int

LangChain 会根据类型注解生成工具参数结构。

函数注释同样重要，它会告诉模型这个工具应该在什么情况下使用。官方要求工具函数提供类型注解，并建议使用清晰、简洁的 docstring。

十一、使用 create_agent 构建 Agent

Agent 可以根据用户问题自主判断：

  1. 是否调用工具；

  2. 调用哪个工具；

  3. 传递什么参数；

  4. 是否继续调用其他工具；

  5. 何时返回最终答案。

创建 02_agent.py：

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def calculate_total(price: float, count: int) -> float:
    """计算商品总价。

    Args:
        price: 商品单价
        count: 商品数量
    """
    return price * count


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[calculate_total],
    system_prompt=(
        "你是一名购物助手。"
        "遇到总价计算问题时必须使用工具，"
        "最后使用中文回答用户。"
    ),
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "一本书 39.8 元，购买 6 本需要多少钱？",
            }
        ]
    }
)

print(result["messages"][-1].content)

可能输出：

购买 6 本需要 238.8 元。

Agent 的内部执行过程大致如下：

用户提出问题
    ↓
模型分析问题
    ↓
模型决定调用 calculate_total
    ↓
工具返回 238.8
    ↓
工具结果交给模型
    ↓
模型组织最终回答

当前官方快速入门同样使用 create_agent，并通过 model、tools 和 system_prompt 三个核心参数创建 Agent。

十二、为 Agent 添加多个工具

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def add(a: float, b: float) -> float:
    """计算两个数字的和。"""
    return a + b


@tool
def multiply(a: float, b: float) -> float:
    """计算两个数字的乘积。"""
    return a * b


@tool
def get_course_price(course_name: str) -> dict:
    """查询课程价格。"""
    prices = {
        "Python": 199,
        "Java": 229,
        "LangChain": 299,
    }

    return {
        "course": course_name,
        "price": prices.get(course_name),
    }


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[add, multiply, get_course_price],
    system_prompt="你是一名课程销售助手，请根据需要调用工具。",
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "LangChain 课程多少钱？购买 3 份一共多少钱？",
            }
        ]
    }
)

print(result["messages"][-1].content)

模型可能依次调用：

get_course_price
multiply

这就是 Agent 与普通模型调用最大的区别：普通模型只生成内容，Agent 可以通过工具执行操作。

工具可以返回字符串，也可以返回字典等结构化对象。当后续推理需要读取具体字段时，官方建议返回字典。

十三、为 Agent 添加短期记忆

默认情况下，两次独立调用之间不会自动共享对话历史。

例如：

用户：我的名字叫小明。
用户：我叫什么名字？

如果两次请求没有使用相同的对话线程，Agent 可能无法回答第二个问题。

LangChain 的短期记忆以线程为单位保存对话状态。添加短期记忆需要：

  1. 配置 checkpointer；

  2. 为同一段对话设置相同的 thread_id。

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


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    checkpointer=InMemorySaver(),
    system_prompt="你是一名友好的中文助手。",
)

config = {
    "configurable": {
        "thread_id": "user-1001",
    }
}

result1 = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "你好，我叫小明，我正在学习 LangChain。",
            }
        ]
    },
    config=config,
)

print(result1["messages"][-1].content)

result2 = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "我叫什么名字？正在学习什么？",
            }
        ]
    },
    config=config,
)

print(result2["messages"][-1].content)

可能输出：

你叫小明，正在学习 LangChain。

thread_id 的作用

同一个 thread_id：

"user-1001"

表示属于同一段对话。

换一个线程：

config2 = {
    "configurable": {
        "thread_id": "user-1002",
    }
}

就会创建一段新的独立对话。

官方文档说明，短期记忆属于 Agent 状态的一部分，通过 checkpointer 保存，并通过线程隔离不同会话。

需要注意，InMemorySaver 只适合开发和演示。程序关闭后，内存中的数据会消失。生产环境应使用数据库持久化方案。

十四、结构化输出

在业务项目中，我们通常不希望模型返回一段难以解析的自然语言：

小明今年 20 岁，他的邮箱是 xiaoming@example.com。

更希望得到结构化对象：

{
  "name": "小明",
  "age": 20,
  "email": "xiaoming@example.com"
}

LangChain 可以结合 Pydantic 定义输出结构。

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class UserInfo(BaseModel):
    """用户信息。"""

    name: str = Field(description="用户姓名")
    age: int = Field(description="用户年龄")
    email: str = Field(description="用户邮箱")


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    response_format=UserInfo,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "提取用户信息："
                    "小明今年20岁，邮箱是xiaoming@example.com。"
                ),
            }
        ]
    }
)

user = result["structured_response"]

print(user)
print(user.name)
print(user.age)
print(user.email)

可能输出：

name='小明' age=20 email='xiaoming@example.com'
小明
20
xiaoming@example.com

通过 response_format 传入数据模型后，LangChain 会根据模型能力自动选择 provider 原生结构化输出或工具调用策略，最终结果位于：

result["structured_response"]

官方结构化输出支持 Pydantic、dataclass、TypedDict 和 JSON Schema。

十五、综合案例：智能学习助手

下面把模型、工具、Agent 和记忆组合起来，实现一个简单的学习助手。

from langchain.agents import create_agent
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver


COURSES = {
    "Python": {
        "level": "入门",
        "hours": 30,
        "description": "学习Python语法、函数、面向对象和常用库。",
    },
    "LangChain": {
        "level": "进阶",
        "hours": 20,
        "description": "学习模型调用、Prompt、Tool、Agent和记忆。",
    },
    "FastAPI": {
        "level": "进阶",
        "hours": 18,
        "description": "学习使用Python开发RESTful API。",
    },
}


@tool
def search_course(course_name: str) -> dict:
    """查询指定课程的信息。

    Args:
        course_name: 课程名称，例如 Python、LangChain 或 FastAPI
    """
    course = COURSES.get(course_name)

    if course is None:
        return {
            "found": False,
            "message": f"没有找到课程：{course_name}",
        }

    return {
        "found": True,
        "name": course_name,
        **course,
    }


@tool
def calculate_study_days(total_hours: int, hours_per_day: int) -> int:
    """根据课程总时长和每天学习时长计算所需天数。

    Args:
        total_hours: 课程总小时数
        hours_per_day: 每天学习小时数
    """
    if hours_per_day <= 0:
        raise ValueError("每天学习时长必须大于0")

    return (total_hours + hours_per_day - 1) // hours_per_day


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[search_course, calculate_study_days],
    checkpointer=InMemorySaver(),
    system_prompt=(
        "你是一名编程学习规划助手。"
        "查询课程信息时必须调用search_course工具；"
        "计算学习天数时必须调用calculate_study_days工具；"
        "回答要清晰、简洁，并适合编程初学者。"
    ),
)

config = {
    "configurable": {
        "thread_id": "student-001",
    }
}

result1 = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "我想学习 LangChain，每天可以学习2小时。",
            }
        ]
    },
    config=config,
)

print(result1["messages"][-1].content)

result2 = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "我刚才准备每天学习多长时间？",
            }
        ]
    },
    config=config,
)

print(result2["messages"][-1].content)

这个案例包含四个核心部分：

create_agent       创建 Agent
tools              为 Agent 提供外部能力
system_prompt      约束 Agent 的行为
checkpointer       保存同一线程的对话状态

十六、常见错误及解决方法

1. 找不到 langchain_openai

错误：

ModuleNotFoundError: No module named 'langchain_openai'

解决：

pip install -U langchain-openai

注意导入名称使用下划线：

from langchain_openai import ChatOpenAI

安装包名称使用连接符：

langchain-openai

2. Python 版本过低

错误可能表现为依赖安装失败、类型语法错误或导入异常。

检查版本：

python --version

当前 LangChain 要求 Python 3.10 及以上。

3. API Key 无效

常见错误：

401 Unauthorized
Incorrect API key

检查环境变量：

import os

print(os.getenv("OPENAI_API_KEY"))

不要把完整密钥打印到日志中。

4. 模型不存在或没有权限

错误：

model_not_found

原因可能包括：

  • 模型名称拼写错误；

  • 当前账号没有模型权限；

  • 模型已经下线；

  • 使用了错误的 provider；

  • provider 集成包没有安装。

可以把：

"openai:gpt-5.5"

替换为自己账号实际可用的模型。

5. 直接打印 response 得到复杂对象

错误写法：

response = model.invoke("你好")
print(response)

建议：

print(response.content)

Agent 的返回值则是状态字典：

result = agent.invoke(...)

print(result["messages"][-1].content)

6. 工具始终没有被调用

可能原因：

  • 工具函数没有清晰的 docstring；

  • 参数没有类型注解；

  • 工具描述与用户问题不匹配；

  • system prompt 没有说明工具使用规则；

  • 模型本身不支持工具调用。

建议写法：

@tool
def get_order(order_id: str) -> dict:
    """根据订单编号查询订单状态。

    Args:
        order_id: 需要查询的订单编号
    """

不要只写：

@tool
def run(data):
    """处理数据。"""

工具描述越模糊，模型越难判断何时调用。

7. 从旧教程复制代码后无法导入

例如：

from langchain.chains import LLMChain

当前 LangChain v1 已精简主命名空间，部分旧功能被移动到 langchain-classic。新项目应优先使用：

prompt | model

或者：

from langchain.agents import create_agent

不要在没有版本说明的情况下直接复制早期 LangChain 教程。

十七、LangChain 的学习路线

建议按照下面的顺序学习：

第一阶段：模型调用
    ├── init_chat_model
    ├── invoke
    ├── stream
    └── batch

第二阶段：提示词
    ├── Messages
    ├── ChatPromptTemplate
    └── Prompt 与模型组合

第三阶段：Agent
    ├── @tool
    ├── create_agent
    ├── 工具调用
    └── Agent 状态

第四阶段：数据与记忆
    ├── 短期记忆
    ├── 结构化输出
    ├── Embedding
    ├── Vector Store
    └── RAG

第五阶段：生产实践
    ├── LangSmith
    ├── Middleware
    ├── Human-in-the-loop
    ├── LangGraph
    └── 部署与评估

RAG 是什么

RAG，全称 Retrieval-Augmented Generation，即检索增强生成。

它通常包含：

原始文档
  ↓
文档切分
  ↓
Embedding 向量化
  ↓
存入向量数据库
  ↓
根据问题检索相关内容
  ↓
把检索结果交给大模型
  ↓
生成有资料依据的回答

官方 LangChain 教程将 Embedding 和 Vector Store 作为构建语义搜索与 RAG 应用的重要抽象。

十八、总结

通过本文，我们学习了 LangChain 的主要基础内容：

  1. LangChain 是连接模型、提示词、工具和数据的应用开发框架；

  2. 当前 LangChain v1 使用 create_agent 作为标准 Agent API；

  3. 不同模型通过独立 provider 包接入；

  4. init_chat_model 可以快速初始化聊天模型；

  5. invoke、stream 和 batch 是基础调用方式；

  6. ChatPromptTemplate 用于管理动态提示词；

  7. @tool 可以将 Python 函数转换为 Agent 工具；

  8. InMemorySaver 和 thread_id 可以实现短期记忆；

  9. response_format 可以获得结构化输出；

  10. 后续可以继续学习 RAG、LangGraph 和 LangSmith。

一个最小 LangChain Agent 可以概括为：

from langchain.agents import create_agent


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    system_prompt="你是一名中文助手。",
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "你好，请介绍一下自己。",
            }
        ]
    }
)

print(result["messages"][-1].content)

学习 LangChain 时，最重要的一点是注意版本差异。当前新项目应以 LangChain v1 官方文档中的 init_chat_model、create_agent、Tool、Memory 和 Structured Output 为主，不要继续照搬早期版本的 API。

Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

Google能索引，AI却抓不到

很多技术团队有个错觉：只要Google能正常收录，内容就没问题。但现实是，你的页面在Google搜索结果里好好的，在ChatGPT、Perplexity、Claude的答案里却像从未存在过一样。

avatar MCP技术社区
cover

Windows 下部署 New API 中转站全过程实录（含 6 个真实踩坑）

avatar MCP技术社区

初识智能体

在过去两年中，几乎所有人都体验过大语言模型（如 ChatGPT、Claude、DeepSeek）的强大能力：写周报、润色邮件、解答编程疑难。被动响应：你问一句，它答一句。如果你的 Prompt 没有写清楚约束条件，它无法主动追问或修正目标。知行脱节：大模型能用流畅的文字告诉你“如何部署一个高可用 K8s 集群”，但它无法替你登录服务器敲下命令、查看报错日志并自动回滚。信息孤岛：大模型的知识止步于预

avatar MCP技术社区