你想在不重建任何内容的情况下，将 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 费率会发生变化，因此请以目录为权威依据。