LLMs 是强大的人工智能工具,能够像人类一样理解和生成文本。它们功能多样,足以用于撰写内容、翻译语言、总结信息以及回答问题,而无需为每项任务进行专门的训练。 除了文本生成,许多模型还支持:
  • 工具调用 - 调用外部工具(如数据库查询或 API 调用)并在其响应中使用结果。
  • 结构化输出 - 模型的响应被限制为遵循定义好的格式。
  • 多模态 - 处理并返回文本以外的数据,如图像、音频和视频。
  • 推理 - 模型执行多步推理以得出结论。
模型是 智能体 的推理引擎。它们驱动智能体的决策过程,决定调用哪些工具、如何解释结果以及何时提供最终答案。 您选择的模型的质量和能力直接影响智能体的基线可靠性和性能。不同的模型擅长不同的任务——有些更擅长遵循复杂指令,有些擅长结构化推理,还有一些支持更大的上下文窗口以处理更多信息。 LangChain 的标准模型接口使您可以访问许多不同的提供商集成,这使得试验和切换模型以找到最适合您用例的模型变得容易。 有关提供商特定集成信息和功能,请参阅提供商的 聊天模型页面。
LangSmith 会跟踪每次模型调用,以便您可以比较提供商、检查工具路由并调试故障。请按照 跟踪快速入门 进行设置。我们建议您还设置 LangSmith Engine,它会监控您的跟踪、检测问题并提出修复建议。

基本用法

模型可以通过两种方式使用:
  1. 与智能体一起使用 - 在创建 智能体 时,可以动态指定模型。
  2. 独立使用 - 可以在不依赖智能体框架的情况下,直接调用模型(在智能体循环之外)来完成文本生成、分类或提取等任务。
相同的模型接口在这两种情况下都适用,这为您提供了灵活性,可以从简单开始,然后根据需要扩展到更复杂的基于智能体的工作流程。

初始化模型

在 LangChain 中开始使用独立模型的最简单方法是使用 initChatModel 来从您选择的 聊天模型提供商 初始化一个模型(示例如下):
👉 阅读 OpenAI 聊天模型集成文档
有关更多详细信息,包括如何传递模型 参数 的信息,请参阅 initChatModel。

支持的提供商和模型

LangChain 通过专用的集成包支持所有主要的模型提供商。每个提供商包都实现了相同的标准接口,因此您可以更换提供商而无需重写应用程序逻辑。新的模型名称可以立即使用——无需更新 LangChain——因为提供商包会将模型名称直接传递给提供商的 API。 浏览 支持提供商的完整列表,或参阅 提供商和模型 以了解提供商、包和模型名称在 LangChain 中如何协同工作的概念概述。

核心方法

调用

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

流式传输

调用模型,但实时流式输出其生成的内容。

批处理

将多个请求批量发送到模型,以实现更高效的处理。
除了聊天模型,LangChain 还为其他相关技术提供支持,例如嵌入模型和向量存储。有关详细信息,请参阅 集成页面。

参数

聊天模型接收可用于配置其行为的参数。支持的完整参数集因模型和提供商而异,但标准参数包括:
string
required
您要与提供商一起使用的特定模型的名称或标识符。您也可以使用 ’:’ 格式在单个参数中同时指定模型和其提供商,例如 ‘openai:o1’。
string
与模型提供商进行身份验证所需的密钥。这通常在您注册访问模型时签发。通常通过设置 来访问。
number
控制模型输出的随机性。较高的数值使响应更具创造性;较低的数值使它们更具确定性。
number
限制响应中的 总数,有效地控制输出可以有多长。
number
等待模型响应的最大时间(以秒为单位),超过此时间将取消请求。
number
default:"6"
系统在请求因网络超时或速率限制等问题失败时,尝试重新发送请求的最大次数。重试使用带有抖动的指数退避。网络错误、速率限制 (429) 和服务器错误 (5xx) 会自动重试。客户端错误(如 401(未授权)或 404)不会重试。对于在不可靠网络上运行的长时间 智能体 任务,请考虑将此值增加到 10–15。
使用 initChatModel 时,将这些参数作为内联参数传递:
使用模型参数初始化

连接弹性

LangChain 聊天模型会自动使用指数退避重试失败的 API 请求。默认情况下,对于网络错误、速率限制 (429) 和服务器错误 (5xx),模型最多重试 6 次。客户端错误(如 401(未授权)或 404)不会重试。 您可以在创建模型时调整 maxRetries 和 timeout,然后将该实例传递给 createAgent、createDeepAgent 或单独调用:
对于在不可靠网络上运行的长时间运行的智能体图,考虑使用更高的 max_retries(例如 10–15)和 检查点,以便在故障后保留进度。
每个聊天模型集成可能有额外的参数用于控制特定于提供商的功能。例如,ChatOpenAI 有 use_responses_api 来决定是使用 OpenAI Responses 还是 Completions API。要查找给定聊天模型支持的所有参数,请前往 聊天模型集成 页面。

调用

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

调用

调用模型最直接的方式是使用 invoke(),传入单条消息或一个消息列表。
单条消息
可以向聊天模型提供一个消息列表来表示对话历史。每条消息都有一个角色,模型使用该角色来指示对话中是谁发送的消息。 有关角色、类型和内容的更多详细信息,请参阅 消息 指南。
对象格式
消息对象
如果您的调用返回类型是字符串,请确保您使用的是聊天模型而不是 LLM。旧式的文本补全 LLM 直接返回字符串。LangChain 聊天模型以 “Chat” 为前缀,例如 ChatOpenAI。

流式传输

大多数模型可以在生成输出内容的同时对其进行流式传输。通过逐步显示输出,流式传输显著改善了用户体验,特别是对于较长的响应。 调用 stream() 会返回一个 ,该迭代器在生成时输出数据块。您可以使用循环实时处理每个块:
与 invoke() 在模型完成生成完整响应后返回单个 AIMessage 不同,stream() 返回多个 AIMessageChunk 对象,每个对象包含输出文本的一部分。重要的是,流中的每个块设计为通过求和聚合成完整消息:
构造 AIMessage
生成的消息可以与使用 invoke() 生成的消息同等对待——例如,可以将其聚合到消息历史记录中,并作为对话上下文传回模型。
流式传输仅在程序中的所有步骤都知道如何处理数据块流时才有效。例如,一个不具备流式处理能力的应用程序需要在处理之前将整个输出存储在内存中。
LangChain 聊天模型还可以使用 [streamEvents()][BaseChatModel.streamEvents] 流式传输语义事件。这简化了基于事件类型和其他元数据的过滤,并将在后台聚合完整消息。请参阅下面的示例。
有关事件类型和其他详细信息,请参阅 streamEvents() 参考。
LangChain 通过在某些情况下自动启用流式模式来简化聊天模型的流式传输,即使您没有显式调用流式传输方法。当您使用非流式 invoke 方法但仍想流式传输整个应用程序(包括来自聊天模型的中间结果)时,这尤其有用。例如,在 LangGraph 智能体 中,您可以在节点内调用 model.invoke(),但如果运行在流式模式下,LangChain 会自动委派给流式传输。

工作原理

当您 invoke() 一个聊天模型时,如果 LangChain 检测到您试图流式传输整个应用程序,它将自动切换到内部流式模式。就使用 invoke 的代码而言,调用的结果是相同的;然而,当聊天模型正在流式传输时,LangChain 将负责在 LangChain 的回调系统中调用 on_llm_new_token 事件。回调事件允许 LangGraph stream() 和 streamEvents() 实时展示聊天模型的输出。

批处理

将一组独立的请求批量发送到模型可以显著提高性能并降低成本,因为处理可以并行进行:
批处理
使用 batch() 处理大量输入时,您可能希望控制最大并行调用数。这可以通过在 RunnableConfig 字典中设置 maxConcurrency 属性来完成。
带最大并发数的批处理
有关支持属性的完整列表,请参阅 RunnableConfig 参考。
有关批处理的更多详细信息,请参阅 参考。

工具调用

模型可以请求调用执行任务的工具,例如从数据库获取数据、搜索网络或运行代码。工具是以下内容的配对:
  1. 一个模式(schema),包括工具的名称、描述和/或参数定义(通常是 JSON schema)
  2. 一个函数或 用于执行。
您可能会听到术语“函数调用”。我们将其与“工具调用”互换使用。
以下是用户和模型之间的基本工具调用流程: 要使您定义的工具可供模型使用,必须使用 bindTools 绑定它们。在后续的调用中,模型可以根据需要选择调用任何已绑定的工具。 一些模型提供商提供 ,可以通过模型或调用参数启用(例如 ChatOpenAI、ChatAnthropic)。请查阅相应的 提供商参考 以获取详细信息。
有关创建工具的详细信息和其他选项,请参阅 工具指南。
绑定用户工具
当绑定用户定义的工具时,模型的响应包含一个执行工具的 请求。当在 智能体 之外单独使用模型时,需要由您来执行请求的工具并将结果返回给模型以用于后续推理。当使用 智能体 时,智能体循环将为您处理工具执行循环。 下面,我们展示了一些使用工具调用的常见方式。
当模型返回工具调用时,您需要执行工具并将结果传回模型。这会创建一个对话循环,模型可以使用工具结果来生成其最终响应。LangChain 包含 智能体 抽象,为您处理这种编排。这是一个简单示例,展示如何做到这一点:
工具执行循环
工具返回的每个 ToolMessage 都包含一个 tool_call_id,与原始工具调用匹配,帮助模型将结果与请求关联起来。
默认情况下,模型可以根据用户的输入自由选择使用哪个已绑定的工具。但是,您可能希望强制选择某个工具,确保模型使用特定工具或给定列表中的 任何 工具:
许多模型在适当时支持并行调用多个工具。这使得模型可以同时从不同来源收集信息。
并行工具调用
模型根据请求操作的独立性,智能地确定何时适合并行执行。
大多数支持工具调用的模型默认启用并行工具调用。一些模型(包括 OpenAI 和 Anthropic)允许您禁用此功能。要这样做,请设置 parallel_tool_calls=False:
当流式传输响应时,工具调用通过 ToolCallChunk 逐步构建。这允许您在工具调用生成时看到它们,而不是等待完整响应。
流式传输工具调用
您可以累积块以构建完整的工具调用:
累积工具调用

结构化输出

可以要求模型以符合给定模式的格式提供其响应。这对于确保输出可以被轻松解析并在后续处理中使用非常有用。LangChain 支持多种模式类型和强制执行结构化输出的方法。
要了解结构化输出,请参阅 结构化输出。
zod schema 是定义输出模式的首选方法。请注意,当提供 zod schema 时,模型输出还将使用 zod 的 parse 方法根据该 schema 进行验证。
结构化输出的关键注意事项:
  • 方法参数:一些提供商支持不同的方法('jsonSchema'、'functionCalling'、'jsonMode')
  • 包含原始数据:使用 includeRaw: true 同时获取解析后的输出和原始 AIMessage
  • 验证:Zod 和标准 Schema 对象提供自动验证,而 JSON Schema 需要手动验证
  • 标准 Schema:任何实现 标准 Schema 规范的 schema 库都受支持,并在运行时进行验证
有关支持的方法和配置选项,请参阅您提供商的集成页面。
将原始的 AIMessage 对象与解析后的表示形式一起返回,以访问响应元数据(如 token 使用量)可能很有用。为此,在调用 with_structured_output 时设置 include_raw=True:
模式可以嵌套:

高级主题

模型配置文件

模型配置文件需要 langchain>=1.1。
LangChain 聊天模型可以通过 profile 属性公开一个包含支持功能和能力的字典:
完整的字段集请参考 API 参考文档。 大部分模型配置文件数据由 models.dev 项目提供支持,这是一个提供模型能力数据的开源计划。这些数据为了用于 LangChain 而增加了额外的字段。这些增补内容随着上游项目的发展而保持一致。 模型配置文件数据允许应用程序动态地适应模型能力。例如:
  1. 摘要中间件 可以根据模型的上下文窗口大小触发摘要。
  2. createAgent 中的结构化输出策略可以自动推断(例如,通过检查对原生结构化输出功能的支持)。
  3. 模型输入可以根据支持的模态和最大输入 token 数量进行限制。
  4. Deep Agents Code 将交互式模型切换器过滤到其配置文件报告支持 tool_calling 和文本 I/O 的模型,并在选择器详细信息视图中显示上下文窗口大小和功能标志。
如果模型配置文件数据缺失、陈旧或不正确,可以进行更改。选项 1(快速修复)您可以使用任何有效的配置文件实例化聊天模型:
选项 2(修复上游数据)数据的主要来源是 models.dev 项目。这些数据在 LangChain 集成包 中与额外的字段和覆盖项合并,并随这些包一起发布。可以通过以下过程更新模型配置文件数据:
  1. (如果需要) 通过向其 GitHub 仓库 提交拉取请求来更新 models.dev 中的源数据。
  2. (如果需要) 通过向 LangChain 集成包 提交拉取请求来更新 langchain-<package>/profiles.toml 中的额外字段和覆盖项。
模型配置文件是一项测试版功能。配置文件的格式可能会发生变化。

多模态

某些模型可以处理并返回非文本数据,例如图像、音频和视频。您可以通过提供内容块将非文本数据传递给模型。
所有底层支持多模态能力的 LangChain 聊天模型都支持:
  1. 跨提供商标准格式的数据(参见我们的消息指南)
  2. OpenAI 聊天补全 格式
  3. 任何该特定提供商原生的格式(例如,Anthropic 模型接受 Anthropic 原生格式)
详情请参阅消息指南的多模态部分。 可以在其响应中返回多模态数据。如果这样调用,生成的 AIMessage 将包含具有多模态类型的内容块。
多模态输出
有关特定提供商的详细信息,请参阅集成页面。

推理

许多模型能够进行多步推理以得出结论。这涉及将复杂问题分解为更小、更易管理的步骤。 如果底层模型支持, 您可以展示此推理过程,以更好地理解模型是如何得出最终答案的。
根据模型的不同,您有时可以指定其应投入推理的努力程度。同样,您也可以请求模型完全关闭推理。这可能表现为分类的“层级”(例如 'low' 或 'high')或整数 token 预算。 有关详细信息,请参阅您各自聊天模型的集成页面或参考文档。

本地模型

LangChain 支持在您自己的硬件上本地运行模型。这对于数据隐私至关重要、您希望调用自定义模型或希望避免使用基于云的模型所产生的成本的情况非常有用。 Ollama 是本地运行聊天和嵌入模型最简单的方法之一。

提示缓存

许多提供商提供提示缓存功能,以减少对相同 token 重复处理的延迟和成本。您可以在三个级别启用缓存:
  • 隐式提供商缓存: 如果请求命中缓存,提供商会自动传递成本节省,无需配置。示例:OpenAI 和 Gemini。
  • 提供商级别显式控制: 提供商允许您手动指定缓存点以获得更大的控制权或保证成本节省。这些反映了底层提供商/API 的行为。示例:
提示缓存通常仅在超过最低输入 token 阈值时启用。有关详细信息,请参阅提供商页面。
缓存使用情况将反映在模型响应的使用量元数据中。

服务器端工具使用

一些提供商支持服务器端工具调用循环:模型可以在一个对话轮次中与网络搜索、代码解释器和其他工具交互并分析结果。 如果模型在服务器端调用工具,响应消息的内容将包含表示工具调用和结果的内容。访问响应的内容块将以提供商无关的格式返回服务器端工具调用和结果:
这代表一个单独的对话轮次;不需要像客户端工具调用那样传递关联的 ToolMessage 对象。 有关可用工具和使用详细信息,请参阅您给定提供商的集成页面。

基本 URL 和代理设置

您可以为实现 OpenAI 聊天补全 API 的提供商配置自定义基本 URL。
model_provider="openai"(或直接使用 ChatOpenAI)针对的是官方 OpenAI API 规范。路由器和代理的提供商特定字段可能无法提取或保留。对于 OpenRouter 和 LiteLLM,请使用专用集成:
许多模型提供商提供 OpenAI 兼容的 API(例如 Together AI、vLLM)。您可以通过指定适当的 base_url 参数将 initChatModel 用于这些提供商:
当使用直接聊天模型类实例化时,参数名称可能因提供商而异。有关详细信息,请检查相应的参考文档。

对数概率

某些模型可以通过设置 logprobs 参数来配置,以返回表示给定 token 可能性的 token 级对数概率:

Token 使用量

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

调用配置

当调用模型时,您可以通过 config 参数使用 RunnableConfig 对象传递额外的配置。这为执行行为、回调和元数据跟踪提供了运行时控制。 常见的配置选项包括:
使用配置调用
这些配置值在以下情况下特别有用:
  • 使用 LangSmith 进行调试追踪
  • 实现自定义日志记录或监控
  • 在生产环境中控制资源使用
  • 在复杂管道中跟踪调用
string
在日志和追踪中标识此特定调用。不会被子调用继承。
string[]
由所有子调用继承的标签,用于在调试工具中进行过滤和组织。
object
用于跟踪额外上下文的自定义键值对,由所有子调用继承。
number
控制使用 batch() 时并行调用的最大数量。
CallbackHandler[]
用于监控和响应执行期间事件的处理器。
number
链的最大递归深度,以防止复杂管道中的无限循环。
有关所有支持的属性,请参阅完整的 RunnableConfig 参考文档。

动态模型选择

动态模型在 根据当前的 和上下文进行选择。这支持复杂的路由逻辑和成本优化。 要使用动态模型,请使用 wrapModelCall 创建中间件,该中间件修改请求中的模型:
有关中间件和高级模式的更多详细信息,请参阅中间件文档。
有关模型配置详细信息,请参阅模型。有关动态模型选择模式,请参阅中间件中的动态模型。