Skip to main content
这将帮助您开始使用 OpenRouter 聊天模型。OpenRouter 是一个统一的 API,通过单个端点提供来自多个提供商(OpenAI、Anthropic、Google、Meta 等)的模型访问。
API 参考有关所有功能和配置选项的详细文档,请参阅 ChatOpenRouter API 参考
有关可用模型的完整列表,请访问 OpenRouter 模型页面

概览

集成详情

可序列化PY 支持下载量版本
ChatOpenRouter@langchain/openrouterNPM - DownloadsNPM - Version

模型功能

设置

要通过 OpenRouter 访问模型,您需要创建一个 OpenRouter 帐户,获取 API 密钥,并安装 @langchain/openrouter 集成包。

凭据

前往 OpenRouter 密钥页面注册并生成 API 密钥。完成后,设置 OPENROUTER_API_KEY 环境变量:
export OPENROUTER_API_KEY="your-api-key"
要启用模型调用的自动追踪,请设置您的 LangSmith API 密钥:
# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

安装

LangChain OpenRouter 集成位于 @langchain/openrouter 包中:
npm install @langchain/openrouter @langchain/core

实例化

现在我们可以实例化我们的模型对象并生成聊天补全:
import { ChatOpenRouter } from "@langchain/openrouter";

const model = new ChatOpenRouter({
  model: "anthropic/claude-sonnet-4.5",
  temperature: 0,
  maxTokens: 1024,
  // other params...
});

调用

const aiMsg = await model.invoke([
  {
    role: "system",
    content:
      "You are a helpful assistant that translates English to French. Translate the user sentence.",
  },
  {
    role: "user",
    content: "I love programming.",
  },
]);
console.log(aiMsg.content);
J'adore la programmation.

流式传输

const stream = await model.stream("Write a short poem about the sea.");
for await (const chunk of stream) {
  process.stdout.write(typeof chunk.content === "string" ? chunk.content : "");
}

工具调用

OpenRouter 使用与 OpenAI 兼容的工具调用格式。您可以描述工具及其参数,并让模型返回一个 JSON 对象,其中包含要调用的工具和该工具的输入。

绑定工具

使用 ChatOpenRouter.bindTools,您可以将 Zod 模式、LangChain 工具或原始函数定义作为工具传递给模型。在底层,这些被转换为 OpenAI 工具模式并在每次模型调用中传递。
import { ChatOpenRouter } from "@langchain/openrouter";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(async ({ location }) => `Sunny in ${location}`, {
  name: "get_weather",
  description: "Get the current weather in a given location",
  schema: z.object({
    location: z
      .string()
      .describe("The city and state, e.g. San Francisco, CA"),
  }),
});

const modelWithTools = new ChatOpenRouter({
  model: "openai/gpt-4o",
}).bindTools([getWeather]);

const aiMsg = await modelWithTools.invoke(
  "What is the weather like in San Francisco?"
);
console.log(aiMsg.tool_calls);
[
  {
    name: 'get_weather',
    args: { location: 'San Francisco, CA' },
    id: 'call_abc123',
    type: 'tool_call'
  }
]

严格模式

传递 strict: true 以保证模型输出与工具定义中提供的 JSON Schema 完全匹配:
const modelWithStrictTools = new ChatOpenRouter({
  model: "openai/gpt-4o",
}).bindTools([getWeather], { strict: true });
有关绑定工具和工具调用输出的更多信息,请参阅工具调用文档。

结构化输出

ChatOpenRouter 通过 .withStructuredOutput() 方法支持结构化输出。根据模型功能自动选择提取策略:
  • jsonSchema — 原生 JSON Schema 响应格式(当模型支持时使用)
  • functionCalling — 将模式包装为工具调用(默认回退)
  • jsonMode — 要求模型以 JSON 格式响应,没有严格的模式约束
当多模型路由处于活动状态(models 列表或 route: "fallback")时,该方法始终回退到 functionCalling,因为请求时的实际后端模型功能未知。
import { ChatOpenRouter } from "@langchain/openrouter";
import { z } from "zod";

const model = new ChatOpenRouter({ model: "openai/gpt-4.1" });

const movieSchema = z.object({
  title: z.string().describe("The title of the movie"),
  year: z.number().describe("The year the movie was released"),
  director: z.string().describe("The director of the movie"),
  rating: z.number().describe("The movie's rating out of 10"),
});

const structuredModel = model.withStructuredOutput(movieSchema, {
  name: "movie",
  method: "jsonSchema",
});
const response = await structuredModel.invoke(
  "Provide details about the movie Inception"
);
console.log(response);
{
  title: 'Inception',
  year: 2010,
  director: 'Christopher Nolan',
  rating: 8.8
}
您可以将 strict: truejsonSchemafunctionCalling 方法一起传递,以强制执行精确的模式遵守:
const strictModel = model.withStructuredOutput(movieSchema, {
  name: "movie",
  method: "jsonSchema",
  strict: true,
});

多模态输入

OpenRouter 支持对接受它们的模型进行多模态输入。可用的模态取决于您选择的模型 — 有关详细信息,请查看 OpenRouter 模型页面
并非所有模型都支持所有模态。有关特定模型的支持情况,请查看 OpenRouter 模型页面

图像输入

使用列表内容格式将图像输入与文本一起提供。
import { ChatOpenRouter } from "@langchain/openrouter";
import { HumanMessage } from "@langchain/core/messages";

const model = new ChatOpenRouter({ model: "openai/gpt-4o" });

const message = new HumanMessage({
  content: [
    { type: "text", text: "Describe this image." },
    {
      type: "image_url",
      image_url: {
        url: "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
      },
    },
  ],
});
const response = await model.invoke([message]);

Token 使用情况元数据

调用后,可以在响应的 usage_metadata 属性上获得 Token 使用情况信息:
const aiMsg = await model.invoke("Tell me a joke.");
console.log(aiMsg.usage_metadata);
{
  input_tokens: 12,
  output_tokens: 25,
  total_tokens: 37
}
当底层提供商在其响应中包含详细的 Token 细分时,它们会自动显示:
  • output_token_details.reasoning — 用于内部思维链推理的 Token
  • input_token_details.cache_read — 从提示缓存提供的输入 Token
流式传输时,从最后一个块聚合 Token 使用情况:
import { AIMessageChunk } from "@langchain/core/messages";
import { concat } from "@langchain/core/utils/stream";

const stream = await model.stream("Tell me a joke.");
let finalMsg: AIMessageChunk | undefined;
for await (const chunk of stream) {
  finalMsg = finalMsg ? concat(finalMsg, chunk) : chunk;
}
console.log(finalMsg?.usage_metadata);

提供商路由

OpenRouter 上的许多模型由多个提供商提供服务。provider 参数让您可以控制哪些提供商处理您的请求以及如何选择它们。

排序和过滤提供商

使用 order 设置首选提供商序列。OpenRouter 按顺序尝试每个提供商,如果其中一个不可用,则回退到下一个:
const model = new ChatOpenRouter({
  model: "anthropic/claude-sonnet-4.5",
  provider: {
    order: ["Anthropic", "Google"],
    allow_fallbacks: true,
  },
});
要仅限制对特定提供商的请求,请使用 only。要排除某些提供商,请使用 ignore
const onlyModel = new ChatOpenRouter({
  model: "openai/gpt-4o",
  provider: { only: ["OpenAI", "Azure"] },
});

const ignoreModel = new ChatOpenRouter({
  model: "meta-llama/llama-4-maverick",
  provider: { ignore: ["DeepInfra"] },
});

按成本、速度或延迟排序

默认情况下,OpenRouter 在提供商之间进行负载平衡,优先考虑较低的成本。使用 sort 更改优先级:
const fastModel = new ChatOpenRouter({
  model: "openai/gpt-4o",
  provider: { sort: "throughput" },
});

const lowLatencyModel = new ChatOpenRouter({
  model: "openai/gpt-4o",
  provider: { sort: "latency" },
});

数据收集策略

如果您的用例要求提供商不存储或训练您的数据,请将 data_collection 设置为 "deny"
const model = new ChatOpenRouter({
  model: "anthropic/claude-sonnet-4.5",
  provider: { data_collection: "deny" },
});

按量化过滤

对于开放权重模型,您可以限制特定精度的路由:
const model = new ChatOpenRouter({
  model: "meta-llama/llama-4-maverick",
  provider: { quantizations: ["fp16", "bf16"] },
});

组合选项

提供商选项可以组合在一起:
const model = new ChatOpenRouter({
  model: "openai/gpt-4o",
  provider: {
    order: ["OpenAI", "Azure"],
    allow_fallbacks: false,
    require_parameters: true,
    data_collection: "deny",
  },
});
有关完整选项列表,请参阅 OpenRouter 提供商路由文档

多模型路由

OpenRouter 支持跨多个模型路由请求。传递 models 数组和可选的 route 策略:
const model = new ChatOpenRouter({
  model: "openai/gpt-4o",
  models: ["openai/gpt-4o", "anthropic/claude-sonnet-4.5"],
  route: "fallback",
});

插件

OpenRouter 支持扩展模型功能的插件。通过 plugins 参数传递插件配置:
const model = new ChatOpenRouter({
  model: "openai/gpt-4o",
  plugins: [
    { id: "web", max_results: 5 },
  ],
});
可用的插件包括 web(网络搜索)、file-parser(PDF 解析)、moderationauto-routerresponse-healing

应用归属

OpenRouter 支持通过 HTTP 标头进行应用归属。通过构造函数参数设置这些:
const model = new ChatOpenRouter({
  model: "anthropic/claude-sonnet-4.5",
  siteUrl: "https://myapp.com",
  siteName: "My App",
});

API 参考

有关所有 ChatOpenRouter 功能和配置的详细文档,请参阅 ChatOpenRouter API 参考 有关 OpenRouter 平台、模型和功能的更多信息,请参阅 OpenRouter 文档