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

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

多模态输入

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

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

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

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

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

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);

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)

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

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)

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

如何在 LangChain 中使用 OpenRouter？

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)

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",
        ],
    },
)

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

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."}]
  }'

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

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

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

步骤 1：安装和认证

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

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

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

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)

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

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

ChatOpenAI + base_url 模式

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

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

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

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

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

Using OpenRouter With LangChain: ChatOpenRouter Setup Guide

使用 `openrouter_provider` 指定提供商

Flowchart of automatic fallback: the app calls OpenRouter, the primary provider fails on an outage, the request succeeds on the next provider, and only the successful run is billed with no markup

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

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

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

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

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

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

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

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

常见问题

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

常见问题及解决方法

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

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

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)

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

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

流式响应

使用 Pydantic 架构绑定工具

可观测性

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

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

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

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

Beta 包的版本兼容性

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

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

OpenRouter 和 LangChain 是同一个东西吗？

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

提供商路由与回退

提示词缓存

Diagram of a LangChain app with chains, agents, and a ChatOpenRouter constructor making one call into the OpenRouter routing layer, which load-balances, falls back automatically, and fans out to Anthropic, OpenAI, Google, Meta, and more providers

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

按模型区分的参数支持

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

工具调用与结构化输出

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

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

from langchain.agents import create_agent
agent = create_agent(model="openrouter:anthropic/claude-sonnet-4.5")

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

我可以使用哪些模型？

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

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

步骤 2：实例化和调用

步骤 3：TypeScript

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

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

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

获取结构化输出

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

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

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

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

推理

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

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

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

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

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

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

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