> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型智能路由

> AIHubMix 智能路由：把模型名填 auto，网关按请求内容自动选出最优模型，支持成本优先 / 质量优先 / 低延迟策略，按实际命中模型计费，客户端代码零改动。

> 一个 `model=auto`，把"选哪个模型"交给网关。

**智能路由（LLM Router）** 会按请求内容，从**平台数百个模型**中**实时优选**最合适的那一个。你只需把 `model` 填成 `auto`——不用挑模型、不用比价、不用跟踪模型迭代。

<Note>
  按**实际命中的模型**计费，无附加费，客户端代码零改动。命中了哪个模型写在响应头与响应体里（见 [如何确认实际命中的模型](#如何确认实际命中的模型)），完全可追溯。
</Note>

## 适用场景

* **按请求内容自动分发**：根据prompt，自动分配最合适的模型——尤其适合 agent / 应用里需要多次调用模型、又难以预先为每一步写死选型的场景。
* **成本优化**：让简单任务自动落到更便宜、更快的模型（`auto` 默认成本优先）。
* **质量优化**：确保复杂请求被路由到能力更强的模型（`auto:quality_first`）。
* **低延迟场景**：agent 多轮循环、对话实时交互等对响应速度敏感的场景，优先选响应最快的模型（`auto:latency_critical`）。
* **统一入口、免选型**：不同类型的请求自动分发到各自最优的模型——不必维护"任务 → 模型"映射表，也不必持续跟踪模型迭代、手动比价换模型名。

***

## 快速开始

把 `model` 设为 `auto`，其余请求体和正常调用完全一致。base\_url 使用 `https://aihubmix.com/v1`。

<CodeGroup>
  ```bash curl theme={null}
  curl https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto",
      "messages": [
        { "role": "user", "content": "What is the meaning of life?" }
      ]
    }'
  ```

  ```python Python (openai SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="<AIHUBMIX_API_KEY>",
      base_url="https://aihubmix.com/v1",
  )

  resp = client.chat.completions.create(
      model="auto",  # 交给网关自动选模
      messages=[
          {"role": "user", "content": "What is the meaning of life?"},
      ],
  )

  print(resp.choices[0].message.content)
  print("实际命中的模型：", resp.model)  # 不是 "auto"，而是真实模型名
  ```

  ```javascript Node.js (openai SDK) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "<AIHUBMIX_API_KEY>",
    baseURL: "https://aihubmix.com/v1",
  });

  const resp = await client.chat.completions.create({
    model: "auto", // 交给网关自动选模
    messages: [
      { role: "user", content: "What is the meaning of life?" },
    ],
  });

  console.log(resp.choices[0].message.content);
  console.log("实际命中的模型：", resp.model); // 真实模型名
  ```
</CodeGroup>

<Tip>
  智能路由在请求进入上游**之前**完成解析，对流式（`stream: true`）与非流式请求一视同仁，无需额外参数；整个决策**仅增加约 1ms 开销**，对端到端延迟几乎无感。
</Tip>

***

## 如何确认实际命中的模型

**方式一 · AIHubMix 控制台「日志」**：在 [console.aihubmix.com/logs](https://console.aihubmix.com/logs) 里，每条请求都能直接看到实际命中、并据此计费的真实模型名。

**方式二 · 接口响应字段**：

* **响应体的 `model` 字段**回填的是真实命中模型（如 `gpt-5.5`），而不是 `auto`。
* **响应头**

| 响应头                                | 含义                          | 示例值                                                                |
| ---------------------------------- | --------------------------- | ------------------------------------------------------------------ |
| `X-Aihubmix-Router-Resolved-Model` | 实际命中、并据此计费的模型               | `gpt-5.5`                                                          |
| `X-Aihubmix-Router-Policy`         | 本次使用的策略                     | `cost_optimized`                                                   |
| `X-Aihubmix-Router-Dimension`      | 识别出的任务维度                    | `text.overall`                                                     |
| `X-Aihubmix-Router-Decision-Id`    | 本次决策的唯一 ID                  | `05dbad09-33c5-42de-…`                                             |
| `X-Aihubmix-Router-Reason`         | 决策简要说明（策略 / 维度 / 最高分 / 候选数） | `policy=cost_optimized dim=text.overall top=0.182 survivors=20/33` |
| `X-Aihubmix-Router-Fallback`       | **仅当**触发无候选兜底时出现            | `true`                                                             |

读取路由决策（curl 看响应头；SDK 用原始响应对象取 header）：

<CodeGroup>
  ```bash curl theme={null}
  curl -i https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto",
      "messages": [
        { "role": "user", "content": "What is the meaning of life?" }
      ]
    }' | grep -i "^x-aihubmix-router"
  ```

  ```python Python (openai SDK) theme={null}
  # 复用上面创建的 client；with_raw_response 才能拿到响应头
  raw = client.chat.completions.with_raw_response.create(
      model="auto",
      messages=[
          {"role": "user", "content": "What is the meaning of life?"},
      ],
  )

  print("命中模型：", raw.headers.get("x-aihubmix-router-resolved-model"))
  print("策略：", raw.headers.get("x-aihubmix-router-policy"))
  print("维度：", raw.headers.get("x-aihubmix-router-dimension"))

  completion = raw.parse()  # 解析为正常的 completion 对象
  print("body.model：", completion.model)
  ```

  ```javascript Node.js (openai SDK) theme={null}
  // 复用上面创建的 client；.withResponse() 才能拿到原始响应头
  const { data: completion, response } = await client.chat.completions
    .create({
      model: "auto",
      messages: [
        { role: "user", content: "What is the meaning of life?" },
      ],
    })
    .withResponse();

  console.log("命中模型：", response.headers.get("x-aihubmix-router-resolved-model"));
  console.log("策略：", response.headers.get("x-aihubmix-router-policy"));
  console.log("维度：", response.headers.get("x-aihubmix-router-dimension"));
  console.log("body.model：", completion.model);
  ```
</CodeGroup>

curl 实际输出（命中模型随线上 catalog 变化）：

```text theme={null}
x-aihubmix-router-decision-id: 05dbad09-33c5-42de-85b5-559fdb73eb4c
x-aihubmix-router-dimension: text.overall
x-aihubmix-router-policy: cost_optimized
x-aihubmix-router-reason: policy=cost_optimized dim=text.overall top=0.182 survivors=20/33
x-aihubmix-router-resolved-model: xiaomi-mimo-v2.5-pro
```

`reason` ：`survivors=20/33` 表示 33 个候选里有 20 个通过硬过滤进入打分，`top=0.182` 是胜出模型在候选池内归一化后的综合得分（能力 / 成本 / 延迟按策略加权）。

<Note>
  示例中的 `Resolved-Model` 取决于线上 catalog 的当前候选与价格，会随平台模型上下线而变化
</Note>

***

## 路由策略

不带后缀的 `auto` 使用默认策略 `cost_optimized`。你可以用 `auto:<策略>` 显式指定侧重：

| 策略写法                            | 侧重                    | 适用场景            |
| ------------------------------- | --------------------- | --------------- |
| `auto`（= `auto:cost_optimized`） | **成本优先**：能力达标就选最便宜    | 批量任务、对成本敏感      |
| `auto:balanced`                 | **均衡**：能力 / 成本 / 延迟兼顾 | 通用，不确定时的稳妥选择    |
| `auto:quality_first`            | **质量优先**：优先选能力最强      | 复杂推理、关键输出       |
| `auto:latency_critical`         | **低延迟优先**：优先选响应最快     | agent 循环、实时交互对话 |

策略是对模型按 **能力 / 成本 / 延迟** 的不同权重倾向。`auto` 先按你这次请求的内容圈定任务维度，再在该维度下 **平台数百个模型** 的候选池里，按所选策略实时择优——所以同一个策略，面对不同内容会命中不同模型。当前在池模型与各维度评分可通过[获取自动路由策略对应模型范围](/cn/api/RouterEndpoints/leaderboard)接口查询。下方「同一请求、不同策略 → 不同命中」实测表就是这一机制的直观体现；每次到底花落谁家，以响应头 / 控制台日志里的真实模型名为准。

指定策略只需把后缀加到 `model` 上：

<CodeGroup>
  ```bash curl theme={null}
  # 质量优先 + 代码任务
  curl -i https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto:quality_first",
      "messages": [
        { "role": "user", "content": "Write a Python function to reverse a linked list." }
      ]
    }' | grep -i "^x-aihubmix-router"
  ```

  ```python Python (openai SDK) theme={null}
  raw = client.chat.completions.with_raw_response.create(
      model="auto:quality_first",  # 质量优先
      messages=[
          {"role": "user", "content": "Write a Python function to reverse a linked list."},
      ],
  )

  print(raw.headers.get("x-aihubmix-router-resolved-model"))
  print(raw.headers.get("x-aihubmix-router-dimension"))
  ```

  ```javascript Node.js (openai SDK) theme={null}
  const { response } = await client.chat.completions
    .create({
      model: "auto:quality_first", // 质量优先
      messages: [
        { role: "user", content: "Write a Python function to reverse a linked list." },
      ],
    })
    .withResponse();

  console.log(response.headers.get("x-aihubmix-router-resolved-model"));
  console.log(response.headers.get("x-aihubmix-router-dimension"));
  ```
</CodeGroup>

**同一请求、不同策略 → 不同命中**（生产环境实测，同一句 `What is the meaning of life?`，都落 `text.overall` 维度）：

| 策略                         | 命中模型                    | top 得分 |
| -------------------------- | ----------------------- | :----: |
| `auto`（= `cost_optimized`） | `xiaomi-mimo-v2.5-pro`  |  0.182 |
| `auto:balanced`            | `claude-opus-4-6-think` |  0.488 |
| `auto:latency_critical`    | `claude-opus-4-6`       |  0.646 |
| `auto:quality_first`       | `claude-opus-4-6-think` |  0.758 |

> `latency_critical` 选了**非 `-think` 版本**——thinking 变体推理延迟更高，低延迟策略会主动避开它。可见策略权重真实作用于"能力 / 成本 / 延迟"的权衡，而不是只看能力。

> **内容也会改变结果**：把同样的 `auto:quality_first` 用在**代码任务**上（上面示例的请求），维度会从 `text.overall` 变为 `text.coding`、实测命中 `claude-opus-4-6-think`——策略与请求内容共同决定最终模型。

<Note>
  未知的策略后缀（如 `auto:fast`）会**回退到默认策略 `cost_optimized`**，不会报错。
</Note>

***

## 工作原理

收到 `model=auto` 后，网关分三步把"意图"变成"具体模型"：

<Steps>
  <Step title="提取请求特征">
    分析这次请求的输入 / 输出模态（文本、图片、文件）、内容意图（代码、数学、图片理解、视频理解、图表、语言、是否联网搜索等）、以及请求规模（预估输入 / 输出 token），归一为一个**任务维度**。例如：含代码的提问 → `text.coding`；带图片 → `vision`；普通文本 → `text.overall`。
  </Step>

  <Step title="硬过滤候选">
    把不满足**硬性约束**的模型直接排除：不支持所需输入 / 输出模态、上下文窗口装不下、被熔断摘除（见[可靠性与容错](#可靠性与容错)）、或不在你这把 Key 的可用模型范围内。
  </Step>

  <Step title="按策略加权评分">
    对通过过滤的候选，基于**业界权威基准**的模型能力评分、叠加实时价格与性能数据，按所选策略对"能力 / 成本 / 延迟"做三维加权评分，取得分最高的一个。最终模型名会写回请求与响应头。
  </Step>
</Steps>

打分示例（`quality_first` 策略下，同一候选池的 top 3，示例数据基于历史生产决策日志）：

| 候选模型                    |  能力分 | 相对成本 |    延迟   |    综合得分   |
| ----------------------- | :--: | :--: | :-----: | :-------: |
| `claude-opus-4-6-think` | 1504 |  220 |  1963ms | **0.758** |
| `claude-opus-4-6`       | 1498 |  220 |  822ms  |   0.721   |
| `claude-fable-5`        | 1510 |  484 | 11130ms |   0.600   |

> 注意 `claude-fable-5` 的**能力分最高**（1510），却因成本更高、延迟更大被综合得分压到第三。这正是加权评分的意义：不是"唯能力论"，而是按策略在能力 / 成本 / 延迟之间权衡。

<Note>
  `claude-fable-5` 为阶段性发布的预览基线模型（staged preview baseline），现已**退役下线（deprecated）**、不再对外提供服务；此处保留其历史评分，仅用于演示加权打分机制，实际请求不会再命中该模型。
</Note>

维度识别是自动的——智能路由内置 **30+ 细分任务维度**（代码 / 数学 / 图片 / 图表 / 长文 / 中文 / 联网…），远比"按模型族粗分流"精细。同样填 `auto`，不同内容会路由到不同维度：

| 你的请求                            | 识别维度                      |
| ------------------------------- | ------------------------- |
| 普通文本提问                          | `text.overall`            |
| 含代码、要求写 / 调试程序                  | `text.coding`             |
| 数学证明 / 求解                       | `text.math`               |
| 很长的提问（约 500+ token）             | `text.longer_query`       |
| 中文提问                            | `text.language.chinese`   |
| 图片输入 + "What is in this image?" | `vision.overall`          |
| 图片输入 + "OCR…" / "识别文字"          | `vision.ocr`              |
| 图片输入 + 图表 / 流程图                 | `vision.diagram`          |
| 开启联网搜索                          | `search.overall`          |
| 图像生成（`/v1/images/generations`）  | `text_to_image.overall`   |
| 图像编辑（`/v1/images/edits`，图入图出）   | `image_edit.single_image` |

这些维度名来自业界权威评测榜单对模型 **细分能力** 的拆解，`auto` 据此把每类请求送到该细分能力最强的模型。常见领域举例：

* **文本**：`text.coding`＝写 / 调代码、`text.math`＝数学求解、`text.longer_query`＝长文处理、`text.language.chinese`＝中文、`text.occupational.legal` / `text.occupational.medicine`＝法律 / 医疗等职业场景。
* **视觉**：`vision.ocr`＝识别图片中的文字、`vision.diagram`＝看懂图表 / 流程图、`vision.overall`＝通用看图理解。

<Tip>
  维度识别采用保守匹配（高精度、低误判）：长尾、模糊的请求会落到更通用的维度（如 `text.overall` / `vision.overall`），而不是被勉强归类，从而避免误路由。
</Tip>

<Note>
  **图片输入也走智能路由**：在 `/v1/chat/completions` 里带图片提问，会按图片任务路由到视觉能力强的模型。生产环境实测：「OCR 识别这张图」→ `vision.ocr`、命中 `qwen3.5-397b-a17b`；通用看图「What is in this image?」→ `vision.overall`、命中 `gpt-5.4-mini`。（这里指图片**理解**；图片**生成**走 `/v1/images/*` 接口，同样支持 `auto`，见 [FAQ](#常见问题-faq)。）
</Note>

***

## 评分榜单与模型池

各维度的模型评分榜单与当前在池模型，可在[智能路由介绍页](https://aihubmix.com/llm-router/auto)交互查看，也可通过免登录开放接口直接获取：[获取自动路由策略对应模型范围](/cn/api/RouterEndpoints/leaderboard)、[获取模型厂商图标](/cn/api/RouterEndpoints/vendors)。榜单展示口径与路由候选一致：仅展示当前可被正常路由的模型，分数为各维度内归一化的 0–100 值，并随模型池持续更新。

***

## 可靠性与容错

智能路由内置**多重容错**，保证 `auto` 路径**永不无故失败**：

<AccordionGroup>
  <Accordion title="熔断：自动摘除故障模型">
    网关对每个模型维护一个滑动窗口的失败率统计。当某模型在窗口内失败次数足够多、且失败率超过阈值时，会被临时摘除出候选池，冷却一段时间后自动恢复——避免把后续请求继续送给正在抽风的模型。失败信号来自**上游对该请求返回的错误**；网关自身的"无可用渠道"不计入（那不是模型本身的问题）。
  </Accordion>

  <Accordion title="无候选兜底：永不在 auto 上报 400">
    万一硬过滤把所有候选都排除了（例如某种模态组合暂时没有可用模型），网关不会直接报错，而是按输出类型分配一个兜底模型保证有响应，并在响应头加上 `X-Aihubmix-Router-Fallback: true` 让你知晓。
  </Accordion>

  <Accordion title="越权防线：受限 Key 不会被兜底绕过">
    如果你的 Key 限定了可用模型范围，智能路由（含兜底）选出的模型**始终**在该范围内。若范围内确实没有任何模型能服务这次请求，会明确返回 403，而不是静默使用范围外（可能更贵）的模型。
  </Accordion>
</AccordionGroup>

***

## 计费说明

**按实际命中的模型原价计费，智能路由本身不收取任何附加费。**

最终由哪个模型响应，就按那个模型的价格、能力和上下文限制计算——这个模型就是响应头 `X-Aihubmix-Router-Resolved-Model` 和响应体 `model` 字段里的值。换句话说，智能路由不会"偷偷用贵模型"：每一次命中都写在响应里，可逐条对账。

***

## 限制

* 智能路由目前面向**对话补全** `/v1/chat/completions` 与**图像生成 / 编辑** `/v1/images/*` 接口（详见 [FAQ：支持哪些接口](#常见问题-faq)）。

* `?router=off` 或请求头 `X-Router-Off` 会让 `model=auto` 直接返回 **400**——这是明确拒绝"既要 auto 又要关掉路由"的歧义用法，而不是静默忽略：

  ```bash theme={null}
  curl -i "https://aihubmix.com/v1/chat/completions?router=off" \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'
  # → HTTP/1.1 400 Bad Request
  # {"error":{"message":"auto requires router enabled; remove ?router=off / X-Router-Off", ...}}
  ```

* 候选集合随平台 catalog 动态变化：同一个 `auto` 在不同时间可能命中不同模型（这是设计使然，可通过响应头复盘）。当前候选范围可通过[获取自动路由策略对应模型范围](/cn/api/RouterEndpoints/leaderboard)接口查询。

***

## 和 OpenRouter / LiteLLM 的区别

"自动选模型"并非 AIHubMix 独有，OpenRouter 与 LiteLLM 都提供类似能力。差异主要在**接入成本**与**托管方式**：

| 差异点                                       | OpenRouter | LiteLLM | AIHubMix |
| ----------------------------------------- | :--------: | :-----: | :------: |
| 按请求内容自动选模                                 |      ✅     |    ✅    |     ✅    |
| 零配置、开箱即用（无需编写路由规则 / utterances）           |      ✅     |    ❌    |     ✅    |
| 平台托管，无需自建 / 自部署 proxy                     |      ✅     |    ❌    |     ✅    |
| 成本 / 质量 / 延迟多策略，一个参数切换                    |      ❌     |    ❌    |     ✅    |
| 命中决策可追溯（响应头含 dimension / policy / reason） |      ❌     |    ❌    |     ✅    |
| 按最终命中模型计费                                 |      ✅     |    ❌    |     ✅    |

***

## 常见问题 FAQ

**Q：智能路由支持哪些接口？**
A：目前 `model=auto` 支持 **OpenAI 兼容的对话补全接口** `/v1/chat/completions`，以及**图像生成 / 编辑接口**（`/v1/images/generations`、`/v1/images/edits`）。音频、`/v1/embeddings`、`/v1/rerank` 等接口暂不支持 `auto`，请直接指定具体模型。

**Q：智能路由支持图片输入吗？**
A：支持。在 `/v1/chat/completions` 里带图片（`image_url`）提问属于图片**理解**，会按图片任务路由到视觉能力强的模型——例如 `vision.ocr`（识别图片中的文字）、`vision.diagram`（看懂图表 / 流程图）、`vision.overall`（通用看图理解）等。图片**生成**同样支持 `auto`：在 `/v1/images/*` 接口把 `model` 填 `auto`，会按图像生成维度（如 `text_to_image.overall`）选模。

**Q：我怎么知道这次请求到底用了哪个模型？**
A：看响应头 `X-Aihubmix-Router-Resolved-Model`，或响应体的 `model` 字段——回填的都是真实模型名。见 [如何确认实际命中的模型](#如何确认实际命中的模型)。

**Q：智能路由会不会偷偷用贵模型？**
A：不会。默认策略 `cost_optimized` 是成本优先；而且每次命中的模型都写在响应里、按其原价计费，可逐条对账。见[计费说明](#计费说明)。

**Q：怎么控制 / 预估成本？**
A：三个手段叠加——① 默认 `auto`（`cost_optimized`）就是成本优先；② 用 **Key 的可用模型范围**把候选锁定在你接受的价位内，相当于给成本设上界；③ 每次命中按响应头 `Resolved-Model` 的模型原价计费，可逐条对账。需要更强能力时再显式用 `auto:quality_first`。

**Q：`auto` 和「模型映射 / 回退」有什么区别？**
A：[模型映射 / 回退](https://docs.aihubmix.com/cn/api/Model-Mapping-Fallback)是 **Key 级固定别名 + 失败时的有序兜底**（每次都同一个目标）；智能路由是**按每次请求内容动态选模**。前者解决"客户端只认某个名字 / 主模型挂了切备用"，后者解决"我不在乎是哪个，给我最合适的"。

**Q：能不能限定智能路由只在某几个模型里选？**
A：可以——通过 **Key 的可用模型范围**约束：智能路由只会在该 Key 允许的模型里选，越权模型不会被命中。

**Q：流式请求支持吗？**
A：支持。路由在请求进入上游前完成，对流式 / 非流式一视同仁。

**Q：为什么同一句话两次调用命中了不同模型？**
A：候选集合与价格随平台 catalog 动态变化，这是设计使然。用响应头里的 `Decision-Id` 与 `Resolved-Model` 即可复盘每一次决策；当前候选范围可通过[获取自动路由策略对应模型范围](/cn/api/RouterEndpoints/leaderboard)接口查询。

**Q：怎么让请求稳定命中同一个模型（比如想复用 prompt 缓存）？**
A：`auto` 是按当前 catalog 动态选模，不保证确定性。如果你需要稳定命中同一模型（例如依赖上游的 prompt 缓存、或要严格复现），请**直接指定具体模型名**，或用 **Key 把可用范围限定到单一模型**——这两种方式下命中是确定的。

***

## 相关资源

* [模型映射与回退](https://docs.aihubmix.com/cn/api/Model-Mapping-Fallback)：Key 级固定别名 + 失败兜底，与智能路由互补。
* [统一推理参数](https://docs.aihubmix.com/cn/api/unified-inference)：跨模型一致的请求参数。
* [AIHubMix 模型页](https://aihubmix.com/models)：查询模型名称、价格与 `Input Modalities`。
* [获取自动路由策略对应模型范围](https://docs.aihubmix.com/cn/api/RouterEndpoints/leaderboard)：免登录查询 30+ 路由维度中公开的 5 大类 23 个子维度评分与在池模型。