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 标志。该包处于 beta 阶段且迭代很快，请始终拉取最新版本。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 Chat 格式：

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 字符串

model 参数是 OpenRouter 以 provider/model 形式表示的 slug，切换模型只需改一个字符串。你的链路中其他任何东西都不用动：提示词、工具定义和输出都保持原样。

今天设置 model="anthropic/claude-sonnet-4.5"，明天把它改成 openai/gpt-5-mini 或 deepseek/deepseek-r1，你的链路依然完全保持原样。

拉取当前provider/model字符串，来自openrouter.ai/models。该页面展示了哪些模型可用、哪些提供商提供这些模型，以及每个模型每 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" 以获取当前的事件 schema。异步形式与之相同，只需使用 astream_events 和一个 async 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 以强制遵循 schema。strict 适用于 function_calling 和 json_schema 方法，不适用于 json_mode。

使用 Pydantic schema 绑定工具

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 使模型遵循工具 schema，而不是即兴编造参数。

获取结构化输出

with_structured_output 将 schema 绑定到整个响应：

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-schema 强制约束。

并非每个模型都支持每种方法；请查看 模型目录 了解各模型的能力。在 provider 对象中设置 require_parameters: true（接下来会介绍）可将请求保持在遵循你所发送参数的 provider 上。

Provider 路由与回退

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"明确说明了这一点。若要同时故障转移到不同的模型，请传入一个models数组，通过model_kwargs然后我们会按顺序依次尝试每个模型：

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。如果主提供商无法处理该请求，我们会尝试下一个提供商，然后是数组中的下一个模型。将该数组与sort: {by, partition: "none"}中的openrouter_provider搭配使用，以在所有列出的模型之间全局地对端点进行排序，而不是按单个模型排序。

你的 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 包能更简洁地访问提供商路由、推理和结构化输出，但如果你当前的配置运行正常，就没有迁移的紧迫性。

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

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

各模型参数支持情况

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

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

常见问题

OpenRouter 和 LangChain 是同一个东西吗？

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

如何将 OpenRouter 与 LangChain 一起使用？

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

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

支持。使用 model.bind_tools([...]) 处理工具，使用 model.with_structured_output(Schema, method="json_schema") 处理类型化响应，两者都配合 strict=True 来强制实施 schema。这些是当前 ChatOpenRouter 包中的一等方法，取代了旧版 ChatOpenAI 路径上较早的 JSON-schema 变通方案。

我能否从 LangChain 设置提供方路由或回退？

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

我还需要 ChatOpenAI + base_url 这种模式吗？

在当前的 LangChain 上不需要。专用的 ChatOpenRouter 包才是当前的做法，它能更干净地访问提供商路由、推理和结构化输出。而 ChatOpenAI 覆盖方式——将 base_url 指向 https://openrouter.ai/api/v1 并配上你的 OpenRouter 密钥——对于早于该包的旧版 LangChain 来说，仍可作为后备方案使用。

我可以使用哪些模型？

目录中 400+ 个模型中的任何一个，通过 provider/model slug 即可使用。请查看 openrouter.ai/models 获取当前的字符串、各模型的能力和定价。可用模型和每 token 费率会变化，因此请以目录为准。