OA0

OA0 是一个探索 AI 的社区

现在注册

已注册用户请登录

OA0 › 代码 › OpenRouter Agents SDK — 面向多模型路由的 Agent 开发工具

OpenRouter Agents SDK — 面向多模型路由的 Agent 开发工具

zephyr · 2026-04-19 11:00:23 · 4 次点击 · 0 条评论

OpenRouter Provider for Vercel AI SDK

OpenRouter 为 Vercel AI SDK 提供的 Provider，让你能够访问 OpenRouter 聊天和补全 API 上的 300 多个大型语言模型。

适用于 AI SDK v6 的安装

# 使用 pnpm
pnpm add @openrouter/ai-sdk-provider

# 使用 npm
npm install @openrouter/ai-sdk-provider

# 使用 yarn
yarn add @openrouter/ai-sdk-provider

(旧版) 适用于 AI SDK v5 的安装

# 使用 pnpm
pnpm add @openrouter/ai-sdk-provider@1.5.4

# 使用 npm
npm install @openrouter/ai-sdk-provider@1.5.4

# 使用 yarn
yarn add @openrouter/ai-sdk-provider@1.5.4

Provider 实例

你可以从 @openrouter/ai-sdk-provider 导入默认的 provider 实例 openrouter：

import { openrouter } from '@openrouter/ai-sdk-provider';

示例

import { openrouter } from '@openrouter/ai-sdk-provider';
import { generateText } from 'ai';

const { text } = await generateText({
  model: openrouter('openai/gpt-4o'),
  prompt: '为4个人写一份素食千层面食谱。',
});

支持的模型

此列表并非 OpenRouter 支持模型的最终清单，因为我们会不断向系统中添加新模型（并弃用旧模型）。你可以在此处找到 OpenRouter 支持的最新模型列表。

你可以在此处找到 OpenRouter 支持工具的最新模型列表。（注意：此列表可能包含与 AI SDK 不兼容的模型。）

嵌入 (Embeddings)

OpenRouter 支持用于语义搜索、RAG 流程和向量原生功能的嵌入模型。

基本用法

import { embed } from 'ai';
import { openrouter } from '@openrouter/ai-sdk-provider';

const { embedding } = await embed({
  model: openrouter.textEmbeddingModel('openai/text-embedding-3-small'),
  value: '阳光明媚的海滩日',
});

console.log(embedding); // 表示嵌入向量的数字数组

批量嵌入

import { embedMany } from 'ai';
import { openrouter } from '@openrouter/ai-sdk-provider';

const { embeddings } = await embedMany({
  model: openrouter.textEmbeddingModel('openai/text-embedding-3-small'),
  values: [
    '阳光明媚的海滩日',
    '城市里的雨天',
    '白雪皑皑的山峰',
  ],
});

console.log(embeddings); // 嵌入向量数组的数组

支持的嵌入模型

OpenRouter 支持多种嵌入模型，包括：
- openai/text-embedding-3-small
- openai/text-embedding-3-large
- openai/text-embedding-ada-002
- 以及 OpenRouter 上提供的更多模型

向 OpenRouter 传递额外请求体

有三种方式可以向 OpenRouter 传递额外的请求体：

通过 providerOptions.openrouter 属性：

```typescript
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

通过模型设置中的 extraBody 属性：

```typescript
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

通过模型工厂中的 extraBody 属性。

```typescript
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

Anthropic 提示词缓存

在使用 streamText 等函数时，你可以直接在消息中包含 Anthropic 特定的选项。OpenRouter provider 会在内部自动将这些消息转换为正确的格式。

基本用法

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
const model = openrouter('anthropic/<supported-caching-model>');

await streamText({
  model,
  messages: [
    {
      role: 'system',
      content:
        '你是一个播客摘要助手。你对内容注重细节且具有批判性。',
    },
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: '给定下面的文本主体：',
        },
        {
          type: 'text',
          text: `<LARGE BODY OF TEXT>`,
          providerOptions: {
            openrouter: {
              cacheControl: { type: 'ephemeral' },
            },
          },
        },
        {
          type: 'text',
          text: '列出演讲者？',
        },
      ],
    },
  ],
});

Anthropic Beta 功能

你可以通过 OpenRouter SDK 传递自定义请求头来启用 Anthropic 的 Beta 功能。

细粒度工具流式传输

细粒度工具流式传输允许在不缓冲的情况下流式传输工具参数，从而减少大型模式下的延迟。这在处理大型嵌套 JSON 结构时特别有用。

重要提示： 这是 Anthropic 的 Beta 功能。请确保在生产环境中使用前评估响应。

基本用法

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamObject } from 'ai';

const provider = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  headers: {
    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
  },
});

const model = provider.chat('anthropic/claude-sonnet-4');

const result = await streamObject({
  model,
  schema: yourLargeSchema,
  prompt: '生成一个复杂的对象...',
});

for await (const partialObject of result.partialObjectStream) {
  console.log(partialObject);
}

你也可以在请求级别传递请求头：

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { generateText } from 'ai';

const provider = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const model = provider.chat('anthropic/claude-sonnet-4');

await generateText({
  model,
  prompt: 'Hello',
  headers: {
    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
  },
});

注意： 细粒度工具流式传输是 Anthropic 模型特有的功能。当使用其他提供商的模型时，该请求头将被忽略。

用例：大型组件生成

此功能在流式传输大型嵌套 JSON 结构（如 UI 组件树）时特别有益：

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamObject } from 'ai';
import { z } from 'zod';

const componentSchema = z.object({
  type: z.string(),
  props: z.record(z.any()),
  children: z.array(z.lazy(() => componentSchema)).optional(),
});

const provider = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  headers: {
    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
  },
});

const model = provider.chat('anthropic/claude-sonnet-4');

const result = await streamObject({
  model,
  schema: componentSchema,
  prompt: '创建一个响应式仪表板布局',
});

for await (const partialComponent of result.partialObjectStream) {
  console.log('部分组件:', partialComponent);
}

用例

结构化输出的响应修复

该 provider 支持响应修复插件，它可以自动验证和修复 AI 模型返回的格式错误的 JSON 响应。这在配合 generateObject 或结构化输出使用时特别有用，因为它可以修复常见问题，如缺少括号、尾随逗号、Markdown 包装和混合文本。

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { generateObject } from 'ai';
import { z } from 'zod';

const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
const model = openrouter('openai/gpt-4o', {
  plugins: [{ id: 'response-healing' }],
});

const { object } = await generateObject({
  model,
  schema: z.object({
    name: z.string(),
    age: z.number(),
  }),
  prompt: '生成一个包含姓名和年龄的人物信息。',
});

console.log(object); // { name: "John", age: 30 }

请注意，响应修复仅适用于非流式请求。当模型返回不完美的 JSON 格式时，该插件会尝试修复响应，以便你收到有效、可解析的 JSON。

调试 API 请求

该 provider 支持调试模式，可以回显发送给上游提供商的请求体。这对于故障排除和理解请求处理方式非常有用。请注意，调试模式仅适用于流式请求。

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
const model = openrouter('anthropic/claude-3.5-sonnet', {
  debug: {
    echo_upstream_body: true,
  },
});

const result = await streamText({
  model,
  prompt: '你好，最近怎么样？',
});

// 调试数据在流的第一个块中可用，
// 并且在最终响应的 providerMetadata 中也可用
for await (const chunk of result.fullStream) {
  // 调试块具有空的 choices 并包含 debug.echo_upstream_body
  console.log(chunk);
}

调试响应将包含发送给上游提供商的请求体，其中敏感数据（用户 ID、base64 内容等）会被脱敏。这有助于你理解 OpenRouter 在将请求发送给模型提供商之前如何转换你的请求。

使用量统计

该 provider 支持 OpenRouter 使用量统计，允许你直接在 API 响应中跟踪令牌使用详情，而无需进行额外的 API 调用。

// 启用使用量统计
const model = openrouter('openai/gpt-3.5-turbo', {
  usage: {
    include: true,
  },
});

// 访问使用量统计数据
const result = await generateText({
  model,
  prompt: '你好，今天过得怎么样？',
});

// 提供商特定的使用量详情（在 providerMetadata 中可用）
if (result.providerMetadata?.openrouter?.usage) {
  console.log('成本:', result.providerMetadata.openrouter.usage.cost);
  console.log(
    '总令牌数:',
    result.providerMetadata.openrouter.usage.totalTokens,
  );
}

它还支持 BYOK（自带密钥）使用量统计，允许你在使用 OpenRouter 账户中提供商自己的 API 密钥时跟踪直通成本。

// 假设你已在 https://openrouter.ai/settings/integrations 设置了 OpenAI API 密钥

// 启用使用量统计
const model = openrouter('openai/gpt-3.5-turbo', {
  usage: {
    include: true,
  },
});

// 访问使用量统计数据
const result = await generateText({
  model,
  prompt: '你好，今天过得怎么样？',
});

// 提供商特定的 BYOK 使用量详情（在 providerMetadata 中可用）
if (result.providerMetadata?.openrouter?.usage) {
  const costDetails = result.providerMetadata.openrouter.usage.costDetails;
  if (costDetails) {
    console.log('BYOK 成本:', costDetails.upstreamInferenceCost);
  }
  console.log('OpenRouter 积分成本:', result.providerMetadata.openrouter.usage.cost);
  console.log(
    '总令牌数:',
    result.providerMetadata.openrouter.usage.totalTokens,
  );
}

项目地址：https://github.com/OpenRouterTeam/ai-sdk-provider

4 次点击 ∙ 0 人收藏

登录后收藏

0 条回复