Auto Router

根据提示词自动选择最合适的模型

Auto Router 会根据你的提示词自动选择最合适的模型。它有两个版本：

• Auto（openrouter/auto）——由 NotDiamond 驱动。已弃用：很快会被下面的 Beta 路由器取代。
• Auto Beta（openrouter/auto-beta）——由 OpenRouter 自有的任务类型排名驱动：关于开发者在每类任务上实际依赖哪些模型的实时、社区范围用量数据。见 Auto Beta 如何工作、基准测试 以及 成本 / 质量权衡 调节项。

概述

不必手动挑选模型，让 Auto Router 分析你的提示词，并从一组精选的高质量选项中选择最优模型。路由器会考虑提示词复杂度、任务类型和模型能力等因素。

Auto Beta 如何工作

Auto Beta 依据证据路由：成千上万的开发者在总体上，对你提示词所代表的那类任务会持续使用什么。

1. 对任务分类。 一个快速、轻量的分类器会为每条提示词分配 ~30 种细粒度任务类型之一——例如 code:debugging、agent:multi_step_planning、qa_knowledge、math、customer_support 或 research_report。
2. 按真实世界支出占比排名。 对于该任务类型，Auto Beta 会查找 OpenRouter 社区在过去 7 天滚动窗口内实际把钱花在哪些模型上——即 排行榜页面 上的「支出占比（Share of Spend）」视图。这是实时信号：当开发者把工作负载迁移到新模型时，路由器会在几天内跟上，无需重新训练或人工挑选。
3. 应用你的成本 / 质量调节项。 cost_quality_tradeoff 设置会按成本筛选候选池，由你决定在多大程度上偏向更便宜的模型。
4. 使用回退进行路由。 存活下来的头部模型（按支出占比排序）会成为首选，并附带回退，同时遵守你的 allowed_models 限制和输出模态要求。如果分类或排行数据暂时不可用，路由器会优雅降级到默认模型集合——请求不会因为路由基础设施的短暂故障而失败。

当你通过 X-OpenRouter-Metadata: enabled 请求头选择加入时，openrouter_metadata.pipeline 中的 Auto Beta 路由器阶段会在 data.task_type 写入来自分类体系的任务类型标签，例如 code:debugging。分类不可用时该字段会缺失。

基准测试

我们在三种差异很大的工作负载上，将 Auto Beta 与当前的 Auto 路由器做了对比：GPQA Diamond（198 道博士水平科学题）、τ-bench Verified Airline（50 个带工具调用的多轮智能体客服任务），以及 DRACO（20 个跨 10 个领域的深度研究报告任务，由 LLM 评判）。Claude Opus 4.8 和 GLM 5.2 作为固定模型参考点，在 GPQA 和 τ-bench 上运行。cqt 即 cost_quality_tradeoff 设置：0 是高质量端，更高的值偏向更便宜的模型。下表在 cqt=0 和 cqt=7 下测得（Auto Beta 现在默认 cqt=9）。

Auto Beta 在所有项目上都胜出，而且任务越难差距越大：在每种设置下，它的 τ-bench 准确率都超过 Auto 的两倍，深度研究分数高出 ~2.5 倍。在质量优先设置下，它与对每一题都运行 Claude Opus 只相差几个百分点——而你不必知道哪一个模型最适合这项工作。

用法

将模型设为 openrouter/auto-beta（或已弃用的 openrouter/auto）：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  messages: [
    {
      role: 'user',
      content: '用简单的话解释量子纠缠',
    },
  ],
});

console.log(completion.choices[0].message.content);
// 查看实际选中了哪个模型
console.log('Model used:', completion.model);

响应

响应包含 model 字段，标明实际使用的模型：

{
  "id": "gen-...",
  "model": "anthropic/claude-sonnet-4.5",  // 被选中的模型
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 150,
    "total_tokens": 165
  }
}

会话粘性

Auto Router 会同时固定所选的 模型 和 模型服务提供商，使同一对话中的后续请求路由到同一位置。这保证对话内行为一致，并最大化 提示词缓存 命中。

粘性分两个层面：

• 隐式（自动）：OpenRouter 从你的消息推导出会话指纹（对第一条系统消息和第一条用户消息做哈希）。一旦模型服务提供商报告提示词缓存用量，该对话就会固定模型和模型服务提供商。无需配置。
• 显式（session_id）：当你包含 session_id 时，粘性会在第一次成功响应时生效——即使尚未观察到缓存用量。推荐用于希望从一开始就保持路由一致的多轮对话和智能体工作流。

两种情况下，缓存都会在 5 分钟 无活动后过期。每次成功请求都会重置计时器。如果已缓存的模型服务提供商返回错误，缓存不会更新，从而允许下一次请求重新路由。

关于粘性路由的工作方式、缓存键粒度以及 x-session-id 请求头的完整说明，见 模型服务提供商粘性路由。

使用 session_id 的示例

const completion = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  session_id: 'my-conversation-123',
  messages: [
    {
      role: 'user',
      content: '解释量子纠缠',
    },
  ],
});

// 使用相同 session_id 的后续请求会使用同一模型和同一模型服务提供商
const followUp = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  session_id: 'my-conversation-123',
  messages: [
    { role: 'user', content: '解释量子纠缠' },
    { role: 'assistant', content: completion.choices[0].message.content ?? '' },
    { role: 'user', content: '现在用五岁小孩能懂的方式解释' },
  ],
});

Auto Router 上的会话粘性

与使用固定模型不同，Auto Router 每次都会根据提示词选择不同的模型。会话粘性会同时固定 模型选择 和模型服务提供商。没有它，对话的每一轮都可能得到不同模型，导致行为不一致并浪费提示词缓存。

支持的模型

Auto Router 从一组精选的高质量模型中选择，包括：

• Claude Sonnet 4.5（anthropic/claude-sonnet-4.5）
• Claude Opus 4.5（anthropic/claude-opus-4.5）
• GPT-5.1（openai/gpt-5.1）
• Gemini 3.1 Pro（google/gemini-3.1-pro-preview）
• DeepSeek 3.2（deepseek/deepseek-v3.2）
• 以及其他表现顶尖的模型

确切的模型池可能随新模型可用而更新。

配置允许的模型

你可以使用 plugins 参数限制 Auto Router 能从哪些模型中选择。当你希望把路由限制在特定模型服务提供商或模型系列时，这很有用。

通过 API 请求

使用通配符模式筛选模型。例如，anthropic/* 匹配所有 Anthropic 模型：

const completion = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  messages: [
    {
      role: 'user',
      content: '解释量子纠缠',
    },
  ],
  plugins: [
    {
      id: 'auto-beta-router',
      allowed_models: ['anthropic/*', 'openai/gpt-5.1'],
    },
  ],
});

通过设置界面

你也可以在 路由设置 中配置默认允许的模型：

1. 前往 Settings > Routing（设置 > 路由）
2. 找到 Auto Router 部分
3. 在 Allowed Models（允许的模型）文本区输入模型模式，用逗号或换行分隔
4. 点击 Save（保存）

这些默认值配置的是 auto-router 插件，因此除非按请求覆盖，否则会应用到 openrouter/auto 请求。若要限制 openrouter/auto-beta 的模型，请在请求中于 id: 'auto-beta-router' 下发送 allowed_models。 若启用了 Prevent overrides（阻止覆盖），这些已保存的默认值优先，该插件的请求级 plugins 配置会被忽略。

模式语法

未配置任何模式时，Auto Router 使用全部受支持的模型。

排除模型

使用 excluded_models 阻止 Auto Router 为单次请求选择特定模型。它接受与上文 allowed_models 相同的通配符模式语法。排除在 allowed_models 之后应用，因此即使某个被排除的模型匹配了允许模式，也永远不会被选中。

例如，该请求允许 Anthropic 和 OpenAI 模型，但排除 GPT-4o。将 model 设为 openrouter/auto-beta 并使用 auto-beta-router 插件，或对 openrouter/auto 使用 auto-router 插件：

const completion = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  messages: [
    {
      role: 'user',
      content: '用简单的话解释量子纠缠',
    },
  ],
  plugins: [
    {
      id: 'auto-beta-router',
      allowed_models: ['anthropic/*', 'openai/*'],
      excluded_models: ['openai/gpt-4o'],
    },
  ],
});

在已弃用的 openrouter/auto 路由器上，当设置了 pin_model: true 时，被请求排除的模型不会从对话历史中重新固定。路由器会通过正常解析选择新模型。

将排除用于合规限制、成本上限，或对你的任务表现不佳的模型。如果限制之后没有符合条件的模型，请求会失败并返回 404 错误：No models match your request and model restrictions。

成本 / 质量权衡

使用 cost_quality_tradeoff 参数（整数，0–10）控制 Auto Router 在多大程度上为成本还是质量优化。已弃用： 请改用命名的 cost_tier 参数。该数字参数仍为兼容性保留，若两者同时提供则以它为准。

• 0 = 纯质量——始终选择能力最强的模型，不考虑成本
• 10 = 最大化成本优势——最便宜的模型胜出
• 中间值会持续混合质量和成本信号

Auto Beta（openrouter/auto-beta）的默认值是 9，已弃用的 openrouter/auto 是 7，在节省成本与较强输出质量之间取得平衡。

推荐的命名设置请使用 cost_tier 插件参数。在 Auto 上，它是 cost_quality_tradeoff 的简写；在 Auto Beta 上，它选择一段连续的成本百分位区间：

// openrouter/auto-beta
plugins: [{ id: 'auto-beta-router', cost_tier: 'medium' }]

// openrouter/auto（已弃用）
plugins: [{ id: 'auto-router', cost_tier: 'medium' }]

如果两个参数都提供，数字形式的 cost_quality_tradeoff 优先。

Auto Beta 中的工作方式

使用数字形式的 cost_quality_tradeoff 时，Auto Beta 相当于在你提示词所属任务类型的已排名候选池上施加成本百分位上限。每个候选模型对该任务都有一个平均每次生成成本；调节项只保留处于该成本分布某一百分位及以下的模型：

• 在 0 时，几乎整个池都符合条件（最高到成本分布的第 90 百分位），因此头部支出占比模型会胜出，无论价格如何。
• 在 Auto Beta 默认的 9 时，只有最便宜的约五分之一候选存活。
• 在 10 时，只剩下最便宜的十分之一。

当提供了 cost_tier 且没有数字形式的 cost_quality_tradeoff 时，Auto Beta 改为只保留档位区间内的模型。与数字封顶不同，档位会排除比所选区间更便宜的模型。每个区间都是经过钳制的按成本排序切片，因此每一个非空候选池至少贡献一个模型；存活模型仍按支出占比排名。

通过 API 请求

const completion = await openRouter.chat.send({
  model: 'openrouter/auto-beta',
  messages: [
    {
      role: 'user',
      content: '总结这段文字',
    },
  ],
  plugins: [
    {
      id: 'auto-beta-router',
      cost_quality_tradeoff: 3, // 偏向质量而非成本
    },
  ],
});

通过设置界面

你也可以在 路由设置 中设置默认权衡：

1. 前往 Settings > Routing（设置 > 路由）
2. 找到 Auto Router 部分
3. 调整 Cost / Quality Tradeoff（成本 / 质量权衡）滑块
4. 点击 Save（保存）

该默认值配置的是 auto-router 插件（openrouter/auto）；按请求提供的值会覆盖它。对于 openrouter/auto-beta，请在 id: 'auto-beta-router' 下按请求设置权衡。 若启用了 Prevent overrides（阻止覆盖），该已保存的默认值优先，该插件的请求级 plugins 配置会被忽略。

定价

你按最终选中的模型支付标准费率。使用 Auto Router 没有额外费用。

因为路由器可能选中高端模型，请求成本取决于它选了哪个模型。响应的 model 字段会标明所选模型，日志页面 会显示每次请求的 Token 数量和费用。

控制成本

使用这些控件把支出保持在预期范围内：

• cost_tier / cost_quality_tradeoff —— 选择路由器在多大程度上偏向更便宜的模型：cost_tier: 'low'（或较高的数字 cost_quality_tradeoff）选择最便宜的区间，而 max 等更高档位选择最贵、质量最高的模型。调节项筛选已排名的候选池；当任务分类或排行不可用时，路由器回退到默认模型集合，该调节项不会对其进行筛选。
• allowed_models / excluded_models —— 对可选模型的硬限制。这些模式会在每一条路由路径上强制执行，包括回退。请在与你的路由器匹配的插件 id 下发送它们（openrouter/auto-beta 对应 auto-beta-router）；在任何其他插件 id 下都会被忽略。
• provider.max_price —— 单次请求的价格上限。Auto Router 在模型服务提供商路由运行之前解析模型，因此所选模型的端点仍会按 max_price 筛选；如果没有端点满足该上限，请求会失败而不是超支。

使用场景

• 通用应用：当你不知道用户会发送什么类型的提示词时
• 成本优化：让路由器为更简单的任务选择高效模型
• 质量优化：确保复杂提示词被路由到能力足够的模型
• 实验：发现哪些模型最适合你的用例

限制

• 路由器需要 messages 格式（而不是 prompt）
• 支持流式输出
• 所有标准 OpenRouter 功能（工具调用等）都可与所选模型一起使用

相关

• Body Builder - 生成多个并行 API 请求
• 最新模型解析 - 始终指向某个模型系列的最新版本
• 模型回退 - 配置回退模型
• 模型服务提供商选择 - 控制使用哪些模型服务提供商