模型

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

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

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

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

您选择的模型的质量和能力直接影响代理的可靠性和性能。不同模型在不同任务上表现出色——有些更擅长遵循复杂指令，有些更擅长结构化推理，有些支持更大的上下文窗口以处理更多信息。

LangChain 的标准模型接口为您提供对众多不同提供商集成的访问，这使得实验和切换模型以找到最适合您用例的模型变得非常容易。

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

基本用法

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

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

同一模型接口在两种上下文中均适用，这为您提供了从简单开始并根据需要扩展到更复杂基于代理的工作流程的灵活性。

初始化模型

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

OpenAI

👉 阅读 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("openai:gpt-4.1")

import os
from langchain_openai import ChatOpenAI

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

model = ChatOpenAI(model="gpt-4.1")

Anthropic

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

pip install -U "langchain[anthropic]"

import os
from langchain.chat_models import init_chat_model

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

model = init_chat_model("anthropic:claude-sonnet-4-5")

import os
from langchain_anthropic import ChatAnthropic

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

model = ChatAnthropic(model="claude-sonnet-4-5")

Azure

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

pip install -U "langchain[openai]"

import os
from langchain.chat_models import init_chat_model

os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"

model = init_chat_model(
    "azure_openai:gpt-4.1",
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"],
)

import os
from langchain_openai import AzureChatOpenAI

os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"

model = AzureChatOpenAI(
    model="gpt-4.1",
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"]
)

Google Gemini

👉 阅读 Google GenAI 聊天模型集成文档

pip install -U "langchain[google-genai]"

import os
from langchain.chat_models import init_chat_model

os.environ["GOOGLE_API_KEY"] = "..."

model = init_chat_model("google_genai:gemini-2.5-flash-lite")

import os
from langchain_google_genai import ChatGoogleGenerativeAI

os.environ["GOOGLE_API_KEY"] = "..."

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite")

AWS Bedrock

👉 阅读 AWS Bedrock 聊天模型集成文档

pip install -U "langchain[aws]"

from langchain.chat_models import init_chat_model

# 请按照此处的步骤配置您的凭据：
# https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html

model = init_chat_model(
    "anthropic.claude-3-5-sonnet-20240620-v1:0",
    model_provider="bedrock_converse",
)

from langchain_aws import ChatBedrock

model = ChatBedrock(model="anthropic.claude-3-5-sonnet-20240620-v1:0")

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

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

关键方法

方法	说明
Invoke	模型接受消息作为输入，并在生成完整响应后输出消息。
Stream	调用模型，但实时流式传输生成的输出。
Batch	将多个请求批量发送给模型，以实现更高效的处理。

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

参数

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

参数	类型	必填	说明
`model`	string	是	您想使用的特定模型的名称或标识符。
`api_key`	string	否	用于向模型提供商进行身份验证的密钥。通常在注册访问模型时颁发。通常通过设置环境变量访问。
`temperature`	number	否	控制模型输出的随机性。值越高，响应越具创造性；值越低，响应越确定性。
`timeout`	number	否	在取消请求之前等待模型响应的最大时间（秒）。
`max_tokens`	number	否	限制响应中的令牌总数，有效控制输出长度。
`max_retries`	number	否	如果因网络超时或速率限制等问题而失败，系统将重新发送请求的最大尝试次数。

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

model = init_chat_model(
    "anthropic:claude-sonnet-4-5",
    # 传递给模型的 Kwargs：
    temperature=0.7,
    timeout=30,
    max_tokens=1000,
)

信息
每个聊天模型集成可能具有用于控制提供商特定功能的额外参数。例如，ChatOpenAI 具有 use_responses_api 以决定是否使用 OpenAI Responses 或 Completions API。
要查找给定聊天模型支持的所有参数，请转到聊天模型集成页面。

调用

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

Invoke

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

response = model.invoke("为什么鹦鹉有五颜六色的羽毛？")
print(response)

可以向模型提供消息列表以表示对话历史。每条消息都有一个角色，模型用它来指示对话中谁发送了消息。有关角色、类型和内容的更多详细信息，请参阅消息指南。

from langchain.messages import HumanMessage, AIMessage, SystemMessage

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_core.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。")

Stream

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

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

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

for chunk in model.stream("天空是什么颜色？"):
    for block in chunk.content_blocks:
        if block["type"] == "reasoning" and (reasoning := block.get("reasoning")):
            print(f"推理：{reasoning}")
        elif block["type"] == "tool_call_chunk":
            print(f"工具调用块：{block}")
        elif block["type"] == "text":
            print(block["text"])
        else:
            ...

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

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

# 天空
# 天空是
# 天空通常
# 天空通常是蓝色
# ...

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

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

警告
流式传输仅在程序的所有步骤都知道如何处理块流时才有效。例如，无法流式传输的应用程序是需要先将整个输出存储在内存中才能处理的情况。

高级流式传输主题

“自动流式传输”聊天模型

LangChain 通过在某些情况下自动启用流式传输模式来简化从聊天模型进行流式传输，即使您未显式调用流式传输方法。这在您使用非流式传输的 invoke 方法但仍希望流式传输整个应用程序（包括聊天模型的中间结果）时特别有用。

例如，在 LangGraph 代理中，您可以在节点内调用 model.invoke()，但如果在流式传输模式下运行，LangChain 将自动委托给流式传输。

工作原理

当您 invoke() 一个聊天模型时，如果 LangChain 检测到您正在尝试流式传输整个应用程序，它将自动切换到内部流式传输模式。对于使用 invoke 的代码，结果是相同的；然而，在聊天模型流式传输时，LangChain 将负责在 LangChain 的回调系统中调用 on_llm_new_token 事件。

回调事件允许 LangGraph 的 stream() 和 astream_events() 实时显示聊天模型的输出。

流式传输事件

LangChain 聊天模型还可以使用 astream_events() 流式传输语义事件。

这简化了基于事件类型和其他元数据的过滤，并在后台聚合完整消息。请参阅以下示例。

async for event in model.astream_events("你好"):

    if event["event"] == "on_chat_model_start":
        print(f"输入：{event['data']['input']}")

    elif event["event"] == "on_chat_model_stream":
        print(f"令牌：{event['data']['chunk'].text}")

    elif event["event"] == "on_chat_model_end":
        print(f"完整消息：{event['data']['output'].text}")

    else:
        pass

输入：你好
令牌：你
令牌：好
令牌：！
令牌：我
令牌：能
令牌：如
...
完整消息：你好！今天我能如何帮助您？

提示
请参阅 astream_events() 参考，了解事件类型和其他详细信息。

Batch

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

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

注意
本节描述的是聊天模型方法 batch()，它在客户端并行化模型调用。
它不同于推理提供商支持的批量 API，例如 OpenAI 或 Anthropic。

默认情况下，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 个并行调用
    }
)

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

工具调用

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

架构，包括工具的名称、描述和/或参数定义（通常是 JSON 架构）
要执行的函数或协程

注意
您可能会听到“函数调用”一词。我们将此与“工具调用”互换使用。

要使您定义的工具可供模型使用，您必须使用 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])  # [!code highlight]

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

绑定用户定义的工具时，模型的响应包括请求执行工具。当将模型与代理分开使用时，您需要执行请求的操作并将结果返回给模型以用于后续推理。请注意，当使用代理时，代理循环将为您处理工具执行循环。

下面展示了一些使用工具调用的常见方法。

工具执行循环

当模型返回工具调用时，您需要执行工具并将结果传递回模型。这会创建一个对话循环，模型可以使用工具结果生成其最终响应。LangChain 包含代理抽象来为您处理此协调。

以下是一个简单示例：

# 将（可能多个）工具绑定到模型
model_with_tools = model.bind_tools([get_weather])

# 步骤 1：模型生成工具调用
messages = [{"role": "user", "content": "波士顿的天气怎么样？"}]
ai_msg = model_with_tools.invoke(messages)
messages.append(ai_msg)

# 步骤 2：执行工具并收集结果
for tool_call in ai_msg.tool_calls:
    # 使用生成的参数执行工具
    tool_result = get_weather.invoke(tool_call)
    messages.append(tool_result)

# 步骤 3：将结果传递回模型以获取最终响应
final_response = model_with_tools.invoke(messages)
print(final_response.text)
# "波士顿当前天气为 72°F，晴朗。"

每个由工具返回的 ToolMessage 包含一个与原始工具调用匹配的 tool_call_id，帮助模型将结果与请求相关联。

强制工具调用

默认情况下，模型可以根据用户输入自由选择使用哪个绑定的工具。但是，您可能希望强制选择工具，确保模型使用特定工具或给定列表中的任何工具：

model_with_tools = model.bind_tools([tool_1], tool_choice="any")

model_with_tools = model.bind_tools([tool_1], tool_choice="tool_1")

并行工具调用

许多模型支持在适当时并行调用多个工具。这允许模型同时从不同来源收集信息。

model_with_tools = model.bind_tools([get_weather])

response = model_with_tools.invoke(
    "波士顿和东京的天气怎么样？"
)

# 模型可能会生成多个工具调用
print(response.tool_calls)
# [
#   {'name': 'get_weather', 'args': {'location': 'Boston'}, 'id': 'call_1'},
#   {'name': 'get_weather', 'args': {'location': 'Tokyo'}, 'id': 'call_2'},
# ]

# 执行所有工具（可以使用 async 并行执行）
results = []
for tool_call in response.tool_calls:
    if tool_call['name'] == 'get_weather':
        result = get_weather.invoke(tool_call)
    ...
    results.append(result)

模型根据请求操作的独立性智能地确定何时适合并行执行。

提示
大多数支持工具调用的模型默认启用并行工具调用。某些模型（包括 OpenAI 和 Anthropic）允许您禁用此功能。要执行此操作，请设置 parallel_tool_calls=False：

model.bind_tools([get_weather], parallel_tool_calls=False)

流式传输工具调用

在流式传输响应时，工具调用通过 ToolCallChunk 逐步构建。这允许您在生成工具调用时查看它们，而不是等待完整响应。

for chunk in model_with_tools.stream(
    "波士顿和东京的天气怎么样？"
):
    # 工具调用块逐步到达
    for tool_chunk in chunk.tool_call_chunks:
        if name := tool_chunk.get("name"):
            print(f"工具：{name}")
        if id_ := tool_chunk.get("id"):
            print(f"ID：{id_}")
        if args := tool_chunk.get("args"):
            print(f"参数：{args}")

# 输出：
# 工具：get_weather
# ID：call_SvMlU1TVIZugrFLckFE2ceRE
# 参数：{"lo
# 参数：catio
# 参数：n": "B
# 参数：osto
# 参数：n"}
# 工具：get_weather
# ID：call_QMZdy6qInx13oWKE7KhuhOLR
# 参数：{"lo
# 参数：catio
# 参数：n": "T
# 参数：okyo
# 参数："}

您可以累积块以构建完整的工具调用：

gathered = None
for chunk in model_with_tools.stream("波士顿的天气怎么样？"):
    gathered = chunk if gathered is None else gathered + chunk
    print(gathered.tool_calls)

结构化输出

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

Pydantic

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)

TypedDict

TypedDict 提供使用 Python 内置类型的更简单替代方案，适用于不需要运行时验证的情况。

from typing_extensions import TypedDict, Annotated

class MovieDict(TypedDict):
    """一部带有详细信息的电影。"""
    title: Annotated[str, ..., "电影标题"]
    year: Annotated[int, ..., "电影上映年份"]
    director: Annotated[str, ..., "电影导演"]
    rating: Annotated[float, ..., "电影评分，满分 10 分"]

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

JSON Schema

为了获得最大控制或互操作性，您可以提供原始 JSON 架构。

import json

json_schema = {
    "title": "Movie",
    "description": "一部带有详细信息的电影",
    "type": "object",
    "properties": {
        "title": {
            "type": "string",
            "description": "电影标题"
        },
        "year": {
            "type": "integer",
            "description": "电影上映年份"
        },
        "director": {
            "type": "string",
            "description": "电影导演"
        },
        "rating": {
            "type": "number",
            "description": "电影评分，满分 10 分"
        }
    },
    "required": ["title", "year", "director", "rating"]
}

model_with_structure = model.with_structured_output(
    json_schema,
    method="json_schema",
)
response = model_with_structure.invoke("提供关于电影《盗梦空间》的详细信息")
print(response)  # {'title': 'Inception', 'year': 2010, ...}

注意
结构化输出的关键考虑因素：
方法参数：某些提供商支持不同的方法（'json_schema'、'function_calling'、'json_mode'）
'json_schema' 通常指提供商提供的专用结构化输出功能
'function_calling' 通过强制工具调用遵循给定架构来派生结构化输出
'json_mode' 是某些提供商提供的 'json_schema' 的前身——它生成有效的 JSON，但架构必须在提示中描述
包含原始：使用 include_raw=True 以同时获取已解析的输出和原始 AI 消息
验证：Pydantic 模型提供自动验证，而 TypedDict 和 JSON Schema 需要手动验证

示例：消息输出与解析结构并存

返回原始 AIMessage 对象与解析表示一起以访问响应元数据（如令牌计数）可能很有用。为此，在调用 with_structured_output 时设置 include_raw=True：

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, include_raw=True)  # [!code highlight]
response = model_with_structure.invoke("提供关于电影《盗梦空间》的详细信息")
response
# {
#     "raw": AIMessage(...),
#     "parsed": Movie(title=..., year=..., ...),
#     "parsing_error": None,
# }

示例：嵌套结构

架构可以嵌套：

from pydantic import BaseModel, Field

class Actor(BaseModel):
    name: str
    role: str

class MovieDetails(BaseModel):
    title: str
    year: int
    cast: list[Actor]
    genres: list[str]
    budget: float | None = Field(None, description="预算（百万美元）")

model_with_structure = model.with_structured_output(MovieDetails)

from typing_extensions import Annotated, TypedDict

class Actor(TypedDict):
    name: str
    role: str

class MovieDetails(TypedDict):
    title: str
    year: int
    cast: list[Actor]
    genres: list[str]
    budget: Annotated[float | None, ..., "预算（百万美元）"]

model_with_structure = model.with_structured_output(MovieDetails)

支持的模型

LangChain 支持所有主要模型提供商，包括 OpenAI、Anthropic、Google、Azure、AWS Bedrock 等。每个提供商提供具有不同功能的各种模型。有关 LangChain 中支持的模型完整列表，请参阅集成页面。

高级主题

多模态

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

提示
所有具有底层多模态功能的 LangChain 聊天模型都支持：
跨提供商标准格式的数据（请参阅我们的消息指南）
OpenAI 聊天完成格式
特定于该提供商的任何格式（例如，Anthropic 模型接受 Anthropic 原生格式）

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

提示
并非所有 LLM 都是平等的！
某些模型可以作为其响应的一部分返回多模态数据。如果调用它们这样做，则生成的 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)

response = model.invoke("为什么鹦鹉有五颜六色的羽毛？")
reasoning_steps = [b for b in response.content_blocks if b["type"] == "reasoning"]
print(" ".join(step["reasoning"] for step in reasoning_steps))

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

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

本地模型

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

Ollama 是本地运行模型的最简单方法之一。请参阅集成页面上的本地集成完整列表。

提示缓存

许多提供商提供提示缓存功能，以减少对相同令牌重复处理的延迟和成本。这些功能可以是隐式或显式：

隐式提示缓存： 如果请求命中缓存，提供商将自动传递成本节省。示例：OpenAI 和 Gemini（Gemini 2.5 及以上）。
显式缓存： 提供商允许您手动指示缓存点以获得更大控制或保证成本节省。示例：ChatOpenAI（通过 prompt_cache_key）、Anthropic 的 AnthropicPromptCachingMiddleware 和 cache_control 选项、AWS Bedrock、Gemini。

警告
提示缓存通常仅在超过最小输入令牌阈值时才会启用。请参阅提供商页面以了解详细信息。

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

服务器端工具使用

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

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

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-4.1-mini")

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

response = model_with_tools.invoke("今天有什么正面新闻？")
response.content_blocks

[
    {
        "type": "server_tool_call",
        "name": "web_search",
        "args": {
            "query": "positive news stories today",
            "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 参数，以控制发出请求的速率。

初始化和使用速率限制器

LangChain 内置（可选）InMemoryRateLimiter。此限制器是线程安全的，可以由同一进程中的多个线程共享。

from langchain_core.rate_limiters import InMemoryRateLimiter

rate_limiter = InMemoryRateLimiter(
    requests_per_second=0.1,  # 每 10 秒 1 个请求
    check_every_n_seconds=0.1,  # 每 100 毫秒检查是否允许发出请求
    max_bucket_size=10,  # 控制最大突发大小。
)

model = init_chat_model(
    model="gpt-5",
    model_provider="openai",
    rate_limiter=rate_limiter  # [!code highlight]
)

警告
提供的速率限制器只能限制每单位时间的请求数。如果您还需要根据请求大小进行限制，它将无济于事。

基础 URL 或代理

对于许多聊天模型集成，您可以配置 API 请求的基础 URL，这允许您使用具有 OpenAI 兼容 API 的模型提供商或使用代理服务器。

基础 URL

许多模型提供商提供 OpenAI 兼容的 API（例如，Together AI、vLLM）。您可以通过指定适当的 base_url 参数使用 init_chat_model 与这些提供商一起使用：

model = init_chat_model(
    model="MODEL_NAME",
    model_provider="openai",
    base_url="BASE_URL",
    api_key="YOUR_API_KEY",
)

注意
使用直接聊天模型类实例化时，参数名称可能因提供商而异。请查看相应的参考以了解详细信息。

代理配置

对于需要 HTTP 代理的部署，某些模型集成支持代理配置：

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-4o",
    openai_proxy="http://proxy.example.com:8080"
)

注意
代理支持因集成而异。请查看特定模型提供商的参考以了解代理配置选项。

对数概率

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

model = init_chat_model(
    model="gpt-4o",
    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="openai:gpt-4o-mini")
model_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")

callback = UsageMetadataCallbackHandler()
result_1 = model_1.invoke("你好", config={"callbacks": [callback]})
result_2 = model_2.invoke("你好", config={"callbacks": [callback]})
callback.usage_metadata

{
    'gpt-4o-mini-2024-07-18': {
        '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-3-5-haiku-20241022': {
        'input_tokens': 8,
        'output_tokens': 21,
        'total_tokens': 29,
        'input_token_details': {'cache_read': 0, 'cache_creation': 0}
    }
}

上下文管理器

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

model_1 = init_chat_model(model="openai:gpt-4o-mini")
model_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")

with get_usage_metadata_callback() as cb:
    model_1.invoke("你好")
    model_2.invoke("你好")
    print(cb.usage_metadata)

{
    'gpt-4o-mini-2024-07-18': {
        '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-3-5-haiku-20241022': {
        'input_tokens': 8,
        'output_tokens': 21,
        'total_tokens': 29,
        'input_token_details': {'cache_read': 0, 'cache_creation': 0}
    }
}

调用配置

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

常见配置选项包括：

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

这些配置值在以下情况下特别有用：

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

关键配置属性

属性	类型	说明
`run_name`	string	在日志和跟踪中标识此特定调用。不由子调用继承。
`tags`	string[]	由所有子调用继承的标签，用于在调试工具中过滤和组织。
`metadata`	object	用于跟踪额外上下文的自定义键值对，由所有子调用继承。
`max_concurrency`	number	在使用 `batch()` 或 `batch_as_completed()` 时控制最大并行调用数。
`callbacks`	array	用于在执行期间监控和响应事件的处理程序。
`recursion_limit`	number	链的最大递归深度，以防止复杂管道中的无限循环。

提示
请参阅完整的 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-5"}},  # 使用 Claude 运行
)

具有默认值的可配置模型

我们可以创建具有默认模型值的可配置模型，指定哪些参数是可配置的，并为可配置参数添加前缀：

first_model = init_chat_model(
        model="gpt-4.1-mini",
        temperature=0,
        configurable_fields=("model", "model_provider", "temperature", "max_tokens"),
        config_prefix="first",  # 当链中有多个模型时很有用
)

first_model.invoke("你叫什么名字")

first_model.invoke(
    "你叫什么名字",
    config={
        "configurable": {
            "first_model": "claude-sonnet-4-5",
            "first_temperature": 0.5,
            "first_max_tokens": 100,
        }
    },
)

以声明方式使用可配置模型

我们可以在可配置模型上调用声明性操作，如 bind_tools、with_structured_output、with_configurable 等，并以与常规实例化聊天模型对象相同的方式链接可配置模型。

from pydantic import BaseModel, Field

class GetWeather(BaseModel):
    """获取给定位置的当前天气"""
    location: str = Field(..., description="城市和州，例如 San Francisco, CA")

class GetPopulation(BaseModel):
    """获取给定位置的当前人口"""
    location: str = Field(..., description="城市和州，例如 San Francisco, CA")

model = init_chat_model(temperature=0)
model_with_tools = model.bind_tools([GetWeather, GetPopulation])

model_with_tools.invoke(
    "2024 年洛杉矶和纽约哪个更大", config={"configurable": {"model": "gpt-4.1-mini"}}
).tool_calls

[
    {
        'name': 'GetPopulation',
        'args': {'location': 'Los Angeles, CA'},
        'id': 'call_Ga9m8FAArIyEjItHmztPYA22',
        'type': 'tool_call'
    },
    {
        'name': 'GetPopulation',
        'args': {'location': 'New York, NY'},
        'id': 'call_jh2dEvBaAHRaw5JUDthOs7rt',
        'type': 'tool_call'
    }
]

model_with_tools.invoke(
    "2024 年洛杉矶和纽约哪个更大",
        config={"configurable": {"model": "claude-sonnet-4-5"}},
).tool_calls

[
    {
        'name': 'GetPopulation',
        'args': {'location': 'Los Angeles, CA'},
        'id': 'toolu_01JMufPf4F4t2zLj7miFeqXp',
        'type': 'tool_call'
    },
    {
        'name': 'GetPopulation',
        'args': {'location': 'New York City, NY'},
        'id': 'toolu_01RQBHcE8kEEbYTuuS8WqY1u',
        'type': 'tool_call'
    }
]