LangChain / Core components / Models

核心组件

模型

复制页面

大型语言模型（LLM）是强大的人工智能工具，能够像人类一样理解和生成文本。它们用途广泛，可以编写内容、翻译语言、总结和回答问题，而无需为每项任务进行专门训练。

除了文本生成，许多模型还支持：

• 工具调用 - 调用外部工具（如数据库查询或API调用）并在响应中使用结果。
• 结构化输出 - 模型的响应被限制为遵循定义的格式。
• 多模态 - 处理并返回文本以外的数据，如图像、音频和视频。
• 推理 - 模型执行多步推理以得出结论。

模型是智能体的推理引擎。它们驱动智能体的决策过程，决定调用哪些工具、如何解释结果以及何时提供最终答案。

您选择的模型的质量和功能直接影响智能体的基线可靠性和性能。不同的模型擅长不同的任务------有些更擅长遵循复杂指令，有些擅长结构化推理，还有一些支持更大的上下文窗口以处理更多信息。

LangChain的标准模型接口使您可以访问许多不同的提供商集成，这使得可以轻松地试验和切换模型，以找到最适合您用例的模型。

有关特定提供商的集成信息和功能，请参阅提供商的聊天模型页面。

LangSmith跟踪每个模型调用，因此您可以比较提供商、检查工具路由和调试故障。按照跟踪快速入门进行设置。

我们还建议您设置LangSmith Engine，它会监控您的跟踪、检测问题并提出修复建议。

基本用法

模型可以通过两种方式使用：

• 与智能体一起使用 - 在创建智能体时可以动态指定模型。
• 独立使用 - 可以直接调用模型（在智能体循环之外），用于文本生成、分类或提取等任务，而无需智能体框架。

相同的模型接口在两种上下文中都适用，这为您提供了灵活性，可以从简单的开始，并根据需要扩展到更复杂的基于智能体的工作流。

初始化模型

在LangChain中开始使用独立模型的最简单方法是使用init_chat_model从您选择的聊天模型提供程序初始化一个（示例如下）：

OpenAI | Anthropic | Azure | Google Gemini | AWS Bedrock | HuggingFace | OpenRouter

👉 阅读OpenAI聊天模型集成文档

pip install -U "langchain[openai]"

import os
from langchain.chat_models import init_chat_model

os.environ["OPENAI_API_KEY"] = "sk-..."

model = init_chat_model("gpt-5.5")
response = model.invoke("为什么鹦鹉会说话？")

有关更多详细信息，请参阅init_chat_model，包括如何传递模型参数。

支持的提供商和模型

LangChain通过专门的集成包支持所有主要的模型提供商。每个提供商包都实现相同的标准接口，因此您可以在不重写应用程序逻辑的情况下切换提供商。新的模型名称立即生效------无需更新LangChain------因为提供商包直接将模型名称传递给提供商的API。

浏览支持的提供商的完整列表，或参阅提供商和模型，了解提供商、包和模型名称如何在LangChain中协同工作的概念性概述。

关键方法

Invoke（调用）

模型接收消息作为输入，并在生成完整响应后输出消息。

Stream（流式）

调用模型，但在生成时实时流式传输输出。

Batch（批处理）

批量向模型发送多个请求，以实现更高效的处理。

除了聊天模型，LangChain还支持其他相关技术，如嵌入模型和向量存储。有关详细信息，请参阅集成页面。

参数

聊天模型接受可用于配置其行为的参数。支持的完整参数集因模型和提供商而异，但标准参数包括：

model（模型）

string，必需

您想与提供商一起使用的特定模型的名称或标识符。您也可以使用"："格式在单个参数中同时指定模型及其提供商，例如"openai:o1"。

api_key（API密钥）

string

向模型提供商进行身份验证所需的密钥。这通常在您注册访问模型时颁发。通常通过设置环境变量来访问。

temperature（温度）

number

控制模型输出的随机性。较高的数字使响应更具创造性；较低的数字使响应更具确定性。

max_tokens（最大令牌数）

number

限制响应中的令牌总数，有效控制输出的长度。

timeout（超时）

number

在取消请求之前等待模型响应的最长时间（以秒为单位）。

max_retries（最大重试次数）

number，默认值："6"

如果由于网络超时或速率限制等问题导致请求失败，系统将重新发送请求的最大尝试次数。重试使用带有抖动的指数退避。网络错误、速率限制（429）和服务器错误（5xx）会自动重试。客户端错误如401（未授权）或404不会重试。对于在不可靠网络上的长时间运行智能体任务，考虑增加到10-15。

使用init_chat_model，将这些参数作为内联**kwargs传递：

model = init_chat_model(
    "claude-sonnet-4-6",
    # 传递给模型的关键字参数：
    temperature=0.7,
    timeout=30,
    max_tokens=1000,
    max_retries=6,  # 默认值；对于不可靠网络增加此值
)

连接弹性

LangChain聊天模型使用指数退避自动重试失败的API请求。默认情况下，模型对网络错误、速率限制（429）和服务器错误（5xx）最多重试6次。客户端错误如401（未授权）或404不会重试。

您可以在创建模型时调整max_retries和timeout，然后将该实例传递给create_agent、create_deep_agent或独立调用：

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "google_genai:gemini-3.5-flash",
    max_retries=10,  # 对于不可靠网络增加（默认值：6）
    timeout=120,  # 秒；对于慢速连接增加
)

对于在不可靠网络上的长时间运行智能体图，考虑更高的max_retries（例如10-15）和一个检查点器，以便在故障发生时保留进度。

每个聊天模型集成可能有用于控制提供商特定功能的额外参数。

例如，ChatOpenAI有use_responses_api来决定是使用OpenAI Responses API还是Completions API。

要查找给定聊天模型支持的所有参数，请前往聊天模型集成页面。

调用

必须调用聊天模型才能生成输出。有三种主要的调用方法，每种方法适用于不同的用例。

Invoke（调用）

调用模型最直接的方法是使用带有单个消息或消息列表的invoke()。

单个消息

response = model.invoke("为什么鹦鹉有色彩鲜艳的羽毛？")
print(response)

可以向聊天模型提供消息列表以表示对话历史。每条消息都有一个角色，模型使用该角色来指示谁在对话中发送了消息。

有关角色、类型和内容的更多详细信息，请参阅消息指南。

字典格式

conversation = [
    {"role": "system", "content": "您是一个将英语翻译成法语的有用助手。"},
    {"role": "user", "content": "翻译：我喜欢编程。"},
    {"role": "assistant", "content": "J'adore la programmation."},
    {"role": "user", "content": "翻译：我喜欢构建应用程序。"}
]

response = model.invoke(conversation)
print(response)  # AIMessage("J'adore créer des applications.")

消息对象

from langchain.messages import HumanMessage, AIMessage, SystemMessage

conversation = [
    SystemMessage("您是一个将英语翻译成法语的有用助手。"),
    HumanMessage("翻译：我喜欢编程。"),
    AIMessage("J'adore la programmation."),
    HumanMessage("翻译：我喜欢构建应用程序。")
]

response = model.invoke(conversation)
print(response)  # AIMessage("J'adore créer des applications.")

如果调用的返回类型是字符串，请确保您使用的是聊天模型而不是LLM。传统的文本补全LLM直接返回字符串。LangChain聊天模型以"Chat"为前缀，例如ChatOpenAI（/oss/integrations/chat/openai）。

Stream（流式）

大多数模型可以在生成输出内容时进行流式传输。通过逐步显示输出，流式传输显著改善了用户体验，特别是对于较长的响应。

调用stream()返回一个迭代器，该迭代器在生成时产生输出块。您可以使用循环实时处理每个块：

基本文本流式传输 | 流式传输工具调用、推理和其他内容

for chunk in model.stream("为什么鹦鹉有色彩鲜艳的羽毛？"):
    print(chunk.text, end="|", flush=True)

与invoke()在模型生成完整响应后返回单个AIMessage不同，stream()返回多个AIMessageChunk对象，每个对象包含输出文本的一部分。重要的是，流中的每个块都设计为通过求和聚合成完整消息：

构造AIMessage

full = None  # None | AIMessageChunk
for chunk in model.stream("天空是什么颜色的？"):
    full = chunk if full is None else full + chunk
    print(full.text)

# The
# The sky
# The sky is
# The sky is typically
# The sky is typically blue
# ...

print(full.content_blocks)
# [{"type": "text", "text": "天空通常是蓝色的..."}]

结果消息可以与使用invoke()生成的消息相同的方式处理------例如，它可以聚合到消息历史中，并作为对话上下文传递回模型。

流式传输仅当程序中的所有步骤都知道如何处理块流时才有效。例如，一个不具备流式传输能力的应用程序是那种需要先将整个输出存储在内存中然后才能处理的应用程序。

高级流式传输主题

Batch（批处理）

对一组独立请求进行批处理可以显著提高性能并降低成本，因为处理可以并行进行：

批处理

responses = model.batch([
    "为什么鹦鹉有色彩鲜艳的羽毛？",
    "飞机是如何飞行的？",
    "什么是量子计算？"
])
for response in responses:
    print(response)

此部分描述了聊天模型方法batch()，它在客户端并行化模型调用。

它不同于推理提供商（如OpenAI或Anthropic）支持的批处理API。

默认情况下，batch()只返回整个批处理的最终输出。如果您想在每个单独输入完成生成时接收其输出，您可以使用batch_as_completed()流式传输结果：

在完成时生成批处理响应

for response in model.batch_as_completed([
    "为什么鹦鹉有色彩鲜艳的羽毛？",
    "飞机是如何飞行的？",
    "什么是量子计算？"
]):
    print(response)

使用batch_as_completed()时，结果可能按顺序到达。每个结果都包含输入索引，以便在需要时匹配以重建原始顺序。

使用batch()或batch_as_completed()处理大量输入时，您可能希望控制最大并行调用数。这可以通过在RunnableConfig字典中设置max_concurrency属性来实现。

具有最大并发数的批处理

model.batch(
    list_of_inputs,
    config={
        'max_concurrency': 5,  # 限制为5个并行调用
    }
)

有关支持属性的完整列表，请参阅RunnableConfig参考。

有关批处理的更多详细信息，请参阅参考。

工具调用

模型可以请求调用执行任务的工具，例如从数据库获取数据、搜索网络或运行代码。工具是以下内容的配对：

• 一个模式，包括工具的名称、描述和/或参数定义（通常是JSON模式）
• 要执行的函数或协程。

您可能听说过"函数调用"这个术语。我们在此与"工具调用"互换使用。

以下是用户和模型之间的基本工具调用流程：

[用户] -> "旧金山和纽约的天气怎么样？"
[模型] -> 分析请求并决定所需的工具
[模型] -> get_weather("San Francisco"), get_weather("New York")
[工具] -> 旧金山天气数据, 纽约天气数据
[模型] -> 处理结果并生成响应
[模型] -> "旧金山：72°F 晴朗，纽约：68°F 多云"

要使您定义的工具可供模型使用，您必须使用bind_tools绑定它们。在后续调用中，模型可以根据需要选择调用任何绑定的工具。

一些模型提供商提供可以通过模型或调用参数启用的内置工具（例如ChatOpenAI、ChatAnthropic）。有关详细信息，请查看相应的提供商参考。

有关创建工具的其他选项和详细信息，请参阅工具指南。

绑定用户工具

from langchain.tools import tool

@tool
def get_weather(location: str) -> str:
    """获取某个地点的天气。"""
    return f"{location} 天气晴朗。"


model_with_tools = model.bind_tools([get_weather])

response = model_with_tools.invoke("波士顿的天气怎么样？")
for tool_call in response.tool_calls:
    # 查看模型进行的工具调用
    print(f"工具: {tool_call['name']}")
    print(f"参数: {tool_call['args']}")

绑定用户定义的工具时，模型的响应包括执行工具的请求。当独立于智能体使用模型时，由您来执行请求的工具并将结果返回给模型，以供后续推理使用。当使用智能体时，智能体循环将为您处理工具执行循环。

下面，我们展示一些可以使用工具调用的常见方式。

• 工具执行循环
• 强制工具调用
• 并行工具调用
• 流式工具调用

结构化输出

可以请求模型以匹配给定模式的格式提供其响应。这对于确保输出易于解析并用于后续处理非常有用。LangChain支持多种模式类型和强制执行结构化输出的方法。

要了解结构化输出，请参阅结构化输出。

Pydantic | TypedDict | JSON Schema

Pydantic模型提供最丰富的功能集，具有字段验证、描述和嵌套结构。

from pydantic import BaseModel, Field

class Movie(BaseModel):
    """带有详细信息的电影。"""
    title: str = Field(description="电影的标题")
    year: int = Field(description="电影上映的年份")
    director: str = Field(description="电影的导演")
    rating: float = Field(description="电影的评分（满分10分）")

model_with_structure = model.with_structured_output(Movie)
response = model_with_structure.invoke("提供关于电影《盗梦空间》的详细信息")
print(response)  # Movie(title="Inception", year=2010, director="Christopher Nolan", rating=8.8)

结构化输出的关键考虑因素

• 方法参数 ：某些提供商支持不同的结构化输出方法：
  • 'json_schema'：使用提供商提供的专用结构化输出功能。
  • 'function_calling'：通过强制遵循给定模式的工具调用来导出结构化输出。
  • 'json_mode'：某些提供商提供的'json_schema'的前身。生成有效的JSON，但模式必须在提示中描述。
• 包含原始内容 ：设置include_raw=True以同时获取解析输出和原始AI消息。
• 验证：Pydantic模型提供自动验证。TypedDict和JSON Schema需要手动验证。

有关支持的方法和配置选项，请参阅提供商的集成页面。

• 示例：消息输出与解析结构并列
• 示例：嵌套结构

高级主题

模型配置文件

模型配置文件需要langchain>=1.1。

LangChain聊天模型可以通过profile属性公开支持的功能和能力的字典：

model.profile
# {
#   "max_input_tokens": 400000,
#   "image_inputs": True,
#   "reasoning_output": True,
#   "tool_calling": True,
#   ...
# }

请参阅API参考中的完整字段集。

模型配置文件数据的大部分由models.dev项目提供支持，这是一个提供模型能力数据的开源项目。这些数据通过额外的字段进行了扩充，以便与LangChain一起使用。这些扩充随着上游项目的发展而保持同步。

模型配置文件数据允许应用程序动态地处理模型能力。例如：

• 摘要中间件可以根据模型的上下文窗口大小触发摘要。
• create_agent中的结构化输出策略可以自动推断（例如，通过检查对本地结构化输出功能的支持）。
• 模型输入可以根据支持的模式和最大输入令牌数进行门控。
• Deep Agents代码过滤交互式模型选择器，仅显示其配置文件报告支持工具调用和文本I/O的模型，并在选择器详细信息视图中显示上下文窗口大小和能力标志。

更新或覆盖配置文件数据

模型配置文件是测试版功能。配置文件的格式可能会发生变化。

多模态

某些模型可以处理并返回非文本数据，如图像、音频和视频。您可以通过提供内容块向模型传递非文本数据。

所有具有底层多模态能力的LangChain聊天模型都支持：

• 跨提供商标准格式的数据（请参阅我们的消息指南）
• OpenAI聊天补全格式
• 特定提供商原生的任何格式（例如，Anthropic模型接受Anthropic原生格式）

有关详细信息，请参阅消息指南的多模态部分。

某些模型可以在响应中返回多模态数据。如果被调用来这样做，生成的AIMessage将具有多模态类型的内容块。

多模态输出

response = model.invoke("创建一张猫的图片")
print(response.content_blocks)
# [
#     {"type": "text", "text": "这是一张猫的图片"},
#     {"type": "image", "base64": "...", "mime_type": "image/jpeg"},
# ]

有关特定提供商的详细信息，请参阅集成页面。

推理

许多模型能够执行多步推理以得出结论。这涉及将复杂问题分解为更小、更易于管理的步骤。

如果底层模型支持，您可以呈现此推理过程，以更好地理解模型如何得出最终答案。

流式推理输出 | 完整推理输出

for chunk in model.stream("为什么鹦鹉有色彩鲜艳的羽毛？"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text)

根据模型的不同，您有时可以指定它应该投入推理的努力程度。同样，您可以请求模型完全关闭推理。这可能采取推理的"层级"形式（例如，'low'或'high'）或整数令牌预算。

有关详细信息，请参阅相应聊天模型的集成页面或参考。

本地模型

LangChain支持在您自己的硬件上本地运行模型。这对于数据隐私至关重要、您想调用自定义模型或想避免使用基于云的模型所产生的成本的情况非常有用。

Ollama是在本地运行聊天和嵌入模型的最简单方法之一。

提示缓存

许多提供商提供提示缓存功能，以减少重复处理相同令牌的延迟和成本。您可以在三个级别启用缓存：

• 隐式提供商缓存：如果请求命中缓存，提供商会自动传递成本节省，无需任何配置。示例：OpenAI和Gemini。
• 提供商级别显式控制 ：提供商允许您手动指示缓存点以获得更大的控制权或保证成本节省。这些反映底层提供商/API行为。示例：
  • ChatOpenAI（通过prompt_cache_key）
  • Anthropic内容块cache_control
  • Gemini
  • AWS Bedrock cachePoint块
• LangChain中间件 ：对于智能体，中间件允许LangChain优化稳定系统提示和工具内容的缓存。示例：
  • Anthropic的AnthropicPromptCachingMiddleware
  • AWS Bedrock的BedrockPromptCachingMiddleware

提示缓存通常在高于最小输入令牌阈值时才会启用。有关详细信息，请参阅提供商页面。

缓存使用情况将反映在模型响应的使用元数据中。

服务器端工具使用

某些提供商支持服务器端工具调用循环：模型可以在单次对话回合中与网络搜索、代码解释器和其他工具交互并分析结果。

如果模型在服务器端调用工具，响应消息的内容将包括表示工具调用和结果的内容。访问响应的内容块将以提供商无关的格式返回服务器端工具调用和结果：

使用服务器端工具调用进行调用

from langchain.chat_models import init_chat_model

model = init_chat_model("gpt-5.4-mini")

tool = {"type": "web_search"}
model_with_tools = model.bind_tools([tool])

response = model_with_tools.invoke("今天有什么积极的新闻？")
print(response.content_blocks)

结果

[
    {
        "type": "server_tool_call",
        "name": "web_search",
        "args": {
            "query": "今天积极新闻",
            "type": "search"
        },
        "id": "ws_abc123"
    },
    {
        "type": "server_tool_result",
        "tool_call_id": "ws_abc123",
        "status": "success"
    },
    {
        "type": "text",
        "text": "以下是今天的一些积极新闻...",
        "annotations": [
            {
                "end_index": 410,
                "start_index": 337,
                "title": "文章标题",
                "type": "citation",
                "url": "..."
            }
        ]
    }
]

这代表单次对话回合；不需要像客户端工具调用那样传入关联的ToolMessage对象。

有关可用工具和使用详情，请参阅给定提供商的集成页面。

速率限制

许多聊天模型提供商对在给定时间段内可以进行的调用次数施加限制。如果达到速率限制，您通常会从提供商那里收到速率限制错误响应，并且需要等待才能发出更多请求。

为了帮助管理速率限制，聊天模型集成接受一个rate_limiter参数，该参数可以在初始化时提供，以控制发出请求的速率。

初始化和使用速率限制器

基础URL和代理设置

您可以为实现OpenAI Chat Completions API的提供商配置自定义基础URL。

model_provider="openai"（或直接使用ChatOpenAI）针对官方OpenAI API规范。来自路由器和代理的提供商特定字段可能不会被提取或保留。

对于OpenRouter和LiteLLM，优先使用专用集成：

• 通过ChatOpenRouter的OpenRouter（langchain-openrouter）
• 通过ChatLiteLLM / ChatLiteLLMRouter的LiteLLM（langchain-litellm）

自定义基础URL | HTTP代理配置

对数概率

某些模型可以配置为通过设置logprobs参数来返回令牌级别的对数概率，表示给定令牌的可能性：

model = init_chat_model(
    model="gpt-5.5",
    model_provider="openai"
).bind(logprobs=True)

response = model.invoke("为什么鹦鹉会说话？")
print(response.response_metadata["logprobs"])

令牌使用情况

许多模型提供商在调用响应中返回令牌使用信息。当可用时，此信息将包含在相应模型生成的AIMessage对象上。有关更多详细信息，请参阅消息指南。

某些提供商API，特别是OpenAI和Azure OpenAI聊天补全，要求用户在流式上下文中选择接收令牌使用数据。有关详细信息，请参阅集成指南的流式使用元数据部分。

您可以使用回调或上下文管理器跟踪应用程序中跨模型的聚合令牌计数，如下所示：

回调处理器 | 上下文管理器

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import UsageMetadataCallbackHandler

model_1 = init_chat_model(model="gpt-5.4-mini")
model_2 = init_chat_model(model="claude-haiku-4-5-20251001")

callback = UsageMetadataCallbackHandler()
result_1 = model_1.invoke("你好", config={"callbacks": [callback]})
result_2 = model_2.invoke("你好", config={"callbacks": [callback]})
print(callback.usage_metadata)
{
    'gpt-5.4-mini': {
        'input_tokens': 8,
        'output_tokens': 10,
        'total_tokens': 18,
        'input_token_details': {'audio': 0, 'cache_read': 0},
        'output_token_details': {'audio': 0, 'reasoning': 0}
    },
    'claude-haiku-4-5-20251001': {
        'input_tokens': 8,
        'output_tokens': 21,
        'total_tokens': 29,
        'input_token_details': {'cache_read': 0, 'cache_creation': 0}
    }
}

调用配置

调用模型时，您可以通过config参数使用RunnableConfig字典传递额外配置。这提供了对执行行为、回调和元数据跟踪的运行时控制。

常见配置选项包括：

使用配置调用

response = model.invoke(
    "讲个笑话",
    config={
        "run_name": "joke_generation",      # 此次运行的自定义名称
        "tags": ["humor", "demo"],          # 用于分类的标签
        "metadata": {"user_id": "123"},     # 自定义元数据
        "callbacks": [my_callback_handler], # 回调处理器
    }
)

这些配置值在以下场景中特别有用：

• 使用LangSmith跟踪进行调试
• 实现自定义日志记录或监控
• 在生产环境中控制资源使用
• 跟踪跨复杂管道的调用

关键配置属性

有关所有支持属性，请参阅完整的RunnableConfig参考。

可配置模型

您还可以通过指定configurable_fields创建运行时可配置的模型。如果您不指定模型值，则'model'和'model_provider'默认将是可配置的。

from langchain.chat_models import init_chat_model

configurable_model = init_chat_model(temperature=0)

configurable_model.invoke(
    "你叫什么名字",
    config={"configurable": {"model": "gpt-5-nano"}},  # 使用GPT-5-Nano运行
)
configurable_model.invoke(
    "你叫什么名字",
    config={"configurable": {"model": "claude-sonnet-4-6"}},  # 使用Claude运行
)

具有默认值的可配置模型 | 声明式使用可配置模型

动态模型选择

动态模型在运行时根据当前状态和上下文进行选择。这可以实现复杂的路由逻辑和成本优化。

要使用动态模型，使用@wrap_model_call装饰器创建中间件，该装饰器修改请求中的模型：

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse


basic_model = ChatOpenAI(model="gpt-5.4-mini")
advanced_model = ChatOpenAI(model="gpt-5.5")

@wrap_model_call
def dynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:
    """根据对话复杂性选择模型。"""
    message_count = len(request.state["messages"])

    if message_count > 10:
        # 对于较长的对话使用高级模型
        model = advanced_model
    else:
        model = basic_model

    return handler(request.override(model=model))

agent = create_agent(
    model=basic_model,  # 默认模型
    tools=tools,
    middleware=[dynamic_model_selection]
)

使用结构化输出时，不支持预先绑定的模型（已调用bind_tools的模型）。如果您需要带有结构化输出的动态模型选择，请确保传递给中间件的模型不是预先绑定的。

有关模型配置详细信息，请参阅模型。有关动态模型选择模式，请参阅中间件中的动态模型。

通过MCP将这些文档连接到Claude、VSCode等，以获得实时答案。

在GitHub上编辑此页面或提交问题。