OpenRouter 推出专用 LangChain 集成包，支持 400+ 模型与自动故障切换

你想在不重建任何内容的情况下，将 OpenRouter 的 400 多个模型集成到你现有的 LangChain 应用中。该集成现在有了一个专用包：PyPI 上的 `langchain-openrouter` 和 npm 上的 `@langchain/openrouter`，但许多旧教程仍在教授使用 `ChatOpenAI` 加 `base_url` 覆盖的方法。本指南将介绍当前的实现路径。

当你将 LangChain 链指向 ChatOpenRouter 时，我们的路由层会自动处理提供商负载均衡、故障规避以及跨提供商故障转移。你的链代码永远不会看到重试过程，未完成的请求也不会产生任何费用。LangChain 的文档涵盖了相关参数；本指南还将介绍这些参数背后的路由行为。

快速入门：5 分钟内在 LangChain 应用中集成 OpenRouter

通过三个步骤实现模型调用：安装、认证、调用。

OpenRouter 是一个模型路由器，背后是一个兼容 OpenAI 的 API：一个端点，400 多个模型，70 多个提供商。ChatOpenRouter 可以像任何其他 LangChain 聊天模型一样，嵌入到任何链或智能体中。模型字符串是唯一与 OpenRouter 相关的部分。

步骤 1：安装和认证

安装 `langchain-openrouter` 并将你的密钥放入环境变量中。在 `openrouter.ai/settings/keys` 生成一个密钥。

pip install -U langchain-openrouter export OPENROUTER_API_KEY="sk-or-..."

使用 `-U` 标志。该包处于测试阶段，更新迭代很快；请始终拉取最新版本。ChatOpenRouter 会自动从环境中读取 `OPENROUTER_API_KEY`。如果你以不同方式管理密钥，也可以将其作为 `api_key` 显式传递。

步骤 2：实例化和调用

from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter( model="anthropic/claude-sonnet-4.5", temperature=0, max_tokens=1024, max_retries=2, )

response = model.invoke("Summarize this support ticket in one sentence.") print(response.content)

`temperature`、`max_tokens` 和 `max_retries` 的行为与在任何 LangChain 聊天模型上完全一致。`model` 参数是我们以 `provider/model` 格式表示的 slug。

如果你想在连接 LangChain 之前确认密钥是否有效，该端点可以直接使用 OpenAI 聊天格式进行通信：

curl https://openrouter.ai/api/v1/chat/completions \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-4.5", "messages": [{"role": "user", "content": "Summarize this support ticket in one sentence."}] }'

相同的密钥，相同的模型字符串，相同的响应格式。ChatOpenRouter 是该端点的一个类型化 LangChain 封装器。

步骤 3：TypeScript

TypeScript 的实现路径与 `@langchain/openrouter` 相同：

import { ChatOpenRouter } from '@langchain/openrouter';

const model = new ChatOpenRouter('anthropic/claude-sonnet-4.5', { temperature: 0.8, });

const response = await model.invoke('Summarize this support ticket in one sentence.'); console.log(response.content);

使用 `npm install @langchain/openrouter` 进行安装。当前版本位于 npm 上。

完整的设置细节可在 OpenRouter 的 LangChain 集成页面以及 LangChain 的 ChatOpenRouter 参考文档中找到。

选择一个模型：`provider/model` 字符串

模型参数是 OpenRouter 的 slug，格式为 provider/model，切换模型只需修改一个字符串。你的链中其他所有内容都不变：提示词、工具定义和输出都保持原样。

今天设置 model="anthropic/claude-sonnet-4.5"，明天改成 openai/gpt-5-mini 或 deepseek/deepseek-r1，你的链完全保持不变。

从 openrouter.ai/models 获取当前的 provider/model 字符串。该页面显示哪些模型可用、哪些提供商提供这些模型，以及每个模型的每 token 价格。本指南中的 slug 仅为示例；模型目录才是真实信息来源。

对于 LangChain 智能体，有一种简写方式可以完全跳过构造函数：

from langchain.agents import create_agent

agent = create_agent(model="openrouter:anthropic/claude-sonnet-4.5")

openrouter:provider/model 前缀告诉 create_agent 通过 ChatOpenRouter 进行解析。同样是单字符串切换，只是向上抽象了一层。

流式响应

使用 stream_events 在模型生成 token 时实时获取它们。异步变体 astream_events 在异步链中执行相同操作。

流式调用的每 token 费率与非流式调用相同。你使用流式是为了用户体验，而不是为了账单。

for event in model.stream_events( "Explain provider routing in three sentences.", version="v3" ): if event["event"] == "on_chat_model_stream": print(event["data"]["chunk"].text, end="", flush=True)

传入 version="v3" 以获取当前事件架构。异步形式与 astream_events 配合异步 for 循环相同：

async for event in model.astream_events( "Explain provider routing in three sentences.", version="v3" ): if event["event"] == "on_chat_model_stream": print(event["data"]["chunk"].text, end="", flush=True)

usage_metadata 可在最终聚合的消息上获取，因此无需发起第二次调用即可读取 token 计数。

工具调用与结构化输出

使用 bind_tools 进行工具调用，使用 with_structured_output 获取类型化响应。两者都接受 strict=True 以强制遵循架构。strict 适用于 function_calling 和 json_schema 方法，但不适用于 json_mode。

使用 Pydantic 架构绑定工具

from pydantic import BaseModel, Field

class GetWeather(BaseModel): """Get the current weather for a city.""" city: str = Field(description="City name, e.g. 'Lisbon'")

model_with_tools = model.bind_tools([GetWeather], strict=True) result = model_with_tools.invoke("What's the weather in Lisbon?") print(result.tool_calls)

strict=True 使模型遵循工具架构，而不是即兴生成参数。

获取结构化输出

with_structured_output 将架构绑定到整个响应：

class TicketSummary(BaseModel): sentiment: str priority: int summary: str

structured = model.with_structured_output(TicketSummary, method="json_schema") summary = structured.invoke("Customer is furious the export button is broken again.") print(summary.priority, summary.summary)

默认方法是 function_calling。传入 method="json_schema" 可在模型支持的情况下使用原生 JSON 架构强制机制。

并非所有模型都支持所有方法；请查看模型目录了解每个模型的能力。在 provider 对象中设置 require_parameters: true（将在下一部分介绍）可将请求保留在能够遵循你所传参数的提供商上。

提供商路由与回退

ChatOpenRouter 通过 `openrouter_provider` 和 `route` 暴露了我们的路由层，因此单个链可以在提供商宕机时继续运行，而无需在应用中编写额外的弹性代码。

以下是您发起调用时的默认行为。我们根据价格对服务于您所选模型的提供商进行负载均衡，并自动避开过去 30 秒内发生过故障的提供商，将其余提供商作为实时备用。您的链代码永远不会看到重试过程。最终无法完成的请求不会产生费用。

使用 `openrouter_provider` 指定提供商

model = ChatOpenRouter( model="anthropic/claude-sonnet-4.5", openrouter_provider={ "order": ["Anthropic", "Google"], "allow_fallbacks": True, "data_collection": "deny", "sort": "throughput", }, )

`order` 设置您的提供商偏好。`allow_fallbacks: True` 允许我们在首选提供商不可用时回退到其他提供商。`sort` 接受 `"throughput"` 或 `"latency"`，适用于速度比价格更重要的情况。`data_collection: "deny"` 会避开那些使用您的提示词进行训练的提供商。`only` 和 `ignore` 分别用于指定或排除特定提供商。`require_parameters: True` 确保请求仅发送给支持您所传确切参数的提供商。

完整的提供商对象参考文档位于 openrouter.ai/docs/guides/routing/provider-selection。

跨模型故障转移，而不仅仅是跨提供商

提供商故障转移默认开启；`route="fallback"` 可显式声明此行为。若要同时故障转移到不同模型，请通过 `model_kwargs` 传入一个 `models` 数组，我们会按顺序依次尝试每个模型：

model = ChatOpenRouter( model="anthropic/claude-sonnet-4.5", route="fallback", model_kwargs={ "models": [ "anthropic/claude-sonnet-4.5", "openai/gpt-5-mini", "google/gemini-3-flash-preview", ], }, )

`models` 不是一个命名的构造函数参数，因此它位于 `model_kwargs` 中，后者会将额外参数原封不动地转发给 API。如果主模型无法处理请求，我们会尝试下一个提供商，然后是数组中的下一个模型。将数组与 `openrouter_provider` 中的 `sort: {by, partition: "none"}` 配对使用，可以对所有列出的模型进行全局端点排序，而不是按单个模型排序。

您的 LangChain 链指向一个 ChatOpenRouter，我们将请求分发到多个提供商，并且您只需为成功执行的运行付费。

推理、多模态、缓存与可观测性

以上每一项都对应一个构造函数或请求参数。

推理

使用 `reasoning` 参数设置推理预算：

model = ChatOpenRouter( model="anthropic/claude-sonnet-4.5", reasoning={"effort": "high", "summary": "auto"}, )

`effort` 的取值范围从 `xhigh` 向下依次为 `high`、`medium`、`low`、`minimal`，直至 `none`。推理 token 数量会出现在 `usage_metadata.output_token_details.reasoning` 中，因此您可以精确了解思考过程所消耗的成本。

多模态输入

图像、音频、视频和 PDF 输入通过 HumanMessage 内容块传递，这与 LangChain 处理多模态模型的方式一致。支持哪些模态取决于具体模型；请查阅目录了解各模型的能力。

提示词缓存

在消息内容块上放置一个 `cache_control: {"type": "ephemeral"}` 断点即可启用缓存。缓存读取情况会体现在 `usage_metadata.input_token_details.cache_read` 中，这样你就能看到每次调用的节省量。提示词缓存指南涵盖了成本方面的内容。

可观测性

传入一个 `session_id`（最长 256 个字符）来对相关请求进行分组，并传入一个 `trace` 对象用于按请求记录元数据。我们会将这两者转发到你配置的 Broadcast 目标，因此追踪信息会落入你现有的技术栈中，无需额外埋点。

这些都不需要更改你的链式结构；它们是在你已构建的任何内容之上叠加的构造函数或请求参数。

常见问题及解决方法

有四个问题经常出现，每个都有对应的解决方法。

Beta 包的版本兼容性

`langchain-openrouter` 是近期推出的 Beta 包，因此需要当前版本的 LangChain。它与旧版 LangChain 不向后兼容。请锁定 PyPI 上的版本，同时升级你的 LangChain，并且不要从旧教程中复制版本锁定信息。

ChatOpenAI + base_url 模式

如果你使用的是早于专用包推出的旧版 LangChain，那么将 ChatOpenAI 的 `base_url` 指向 `https://openrouter.ai/api/v1` 并配合你的 OpenRouter 密钥仍然有效。当你无法升级时可以使用此方法。对于当前版本的 LangChain，专用的 ChatOpenRouter 包能提供更简洁的方式来访问提供商路由、推理和结构化输出，但如果你当前的配置运行正常，也无需急于迁移。

模型每次都返回相同的答案

如果模型持续返回相同的响应，这几乎总是温度或缓存行为导致的，而非缺陷。请设置一个非零的温度值，并检查提示词缓存是否处于激活状态。

按模型区分的参数支持

并非所有模型都支持你能传入的每一个参数。如有疑问，请在 `openrouter_provider` 中设置 `require_parameters: true`，这样我们只会路由到接受你参数的提供商，或者先查看目录中的模型页面。

统一使用 ChatOpenRouter 包，从 PyPI 或 npm 固定版本，并从 openrouter.ai/models 获取最新的模型字符串。只需设置一次 `openrouter_provider`，你链中的每次调用都会继承跨提供商故障转移，仅对成功运行的调用计费。

常见问题

OpenRouter 和 LangChain 是同一个东西吗？

不是。它们是互补关系而非竞争关系。OpenRouter 是一个模型提供商和路由器，位于一个兼容 OpenAI 的 API 之后，为你提供来自 70 多个提供商的 400 多个模型。LangChain 是你构建链和智能体的编排框架。你通过 ChatOpenRouter 将 OpenRouter 作为 LangChain 中的一个模型来使用。

如何在 LangChain 中使用 OpenRouter？

安装 `langchain-openrouter`，设置 `OPENROUTER_API_KEY`，并实例化 `ChatOpenRouter(model="provider/model")`。然后像使用任何 LangChain 聊天模型一样调用 `.invoke(...)`、`.stream_events(...)`、`.bind_tools(...)` 或 `.with_structured_output(...)`。该包处于测试阶段；请从 PyPI 或 npm 固定版本。TypeScript 路径使用 `@langchain/openrouter`，结构相同。

LangChain 是否支持 OpenRouter 的工具调用和结构化输出？

是的。使用 `model.bind_tools([...])` 处理工具，使用 `model.with_structured_output(Schema, method="json_schema")` 处理类型化响应，两者都设置 `strict=True` 以强制执行模式。这些是当前 ChatOpenRouter 包上的一等方法，取代了旧版 ChatOpenAI 路径上较旧的 JSON 模式变通方案。

我可以在 LangChain 中设置提供商路由或回退吗？

可以。传入 `openrouter_provider={...}` 来引导提供商，并使用 `model_kwargs={"models": [...]}` 在模型之间进行故障转移。提供商故障转移默认开启：OpenRouter 会进行价格负载均衡，并路由避开在过去 30 秒内发生过故障的提供商。失败的请求不计费；你只需为成功运行的调用付费。

我仍然需要 `ChatOpenAI + base_url` 模式吗？

不在当前的 LangChain 上。专用的 ChatOpenRouter 包是当前路径，能更清晰地访问提供商路由、推理和结构化输出。ChatOpenAI 覆盖方式（将 base_url 指向 https://openrouter.ai/api/v1 并配合你的 OpenRouter 密钥）仍可作为该包出现之前旧版 LangChain 的回退方案。

我可以使用哪些模型？

目录中 400 多个模型中的任意一个，通过提供商/模型标识符即可使用。请查看 openrouter.ai/models 获取当前字符串、各模型能力及定价。可用模型和每 token 费率会发生变化，因此请以目录为权威依据。