# Auto Router

> 通过 Modelverse 自动为请求选择合适的文本模型

## 概览

Auto Router 是 Modelverse 的自动模型路由能力。调用方无需在每次请求中手动指定具体模型，只需要把 `model` 设置为 `auto`，Modelverse 会根据请求内容、任务类型、提示词复杂度、上下文长度、模型能力和成本偏好，从可用模型池中选择一个合适的模型完成本次生成。

Auto Router 使用 Modelverse 的 OpenAI Chat Completions 兼容接口，适合以下场景：

- 不想在业务代码中维护固定模型列表。
- 希望简单任务走更经济的模型，复杂任务走能力更强的模型。
- 希望在模型升级或模型池调整后，业务侧尽量少改代码。
- 希望保留 OpenAI 兼容的请求和响应格式。

## 接口地址

默认使用中国大陆接入点：

```text
https://api.modelverse.cn/v1/chat/completions
```

如有海外接入、低延迟或数据驻留要求，也可以按项目配置选择其他 Modelverse 接入点。请求路径保持一致，只需替换域名。

## 快速开始

把 `model` 设置为 `auto` 即可启用自动路由。

### TypeScript（fetch）

```typescript
const response = await fetch('https://api.modelverse.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <MODELVERSE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [
      {
        role: 'user',
        content: '请用通俗的方式解释量子纠缠',
      },
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
console.log('实际使用模型:', data.model);
```

### Python（requests）

```python
import json
import requests

response = requests.post(
    'https://api.modelverse.cn/v1/chat/completions',
    headers={
        'Authorization': 'Bearer <MODELVERSE_API_KEY>',
        'Content-Type': 'application/json',
    },
    data=json.dumps({
        'model': 'auto',
        'messages': [
            {
                'role': 'user',
                'content': '请用通俗的方式解释量子纠缠',
            }
        ],
    }),
)

data = response.json()
print(data['choices'][0]['message']['content'])
print('实际使用模型:', data['model'])
```

### Python（OpenAI SDK）

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url='https://api.modelverse.cn/v1',
    api_key=os.environ['MODELVERSE_API_KEY'],
)

response = client.chat.completions.create(
    model='auto',
    messages=[
        {
            'role': 'user',
            'content': '请用通俗的方式解释量子纠缠',
        }
    ],
)

print(response.choices[0].message.content)
print('实际使用模型:', response.model)
```

## 请求参数

Auto Router 复用 Chat Completions 的通用参数。常用字段如下：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定传 `auto`，表示启用自动路由。 |
| `messages` | array | 是 | OpenAI 兼容的消息列表。 |
| `stream` | boolean | 否 | 是否使用 SSE 流式响应。 |
| `temperature` | number | 否 | 采样温度，传入后会转发给实际执行模型。 |
| `top_p` | number | 否 | nucleus sampling 参数，传入后会转发给实际执行模型。 |
| `max_tokens` | number | 否 | 最大输出 token 数。 |
| `allowed_models` | array | 否 | 限制 Auto Router 的候选模型集合。仅支持精确模型名；为空或不传时使用全部可用候选模型。 |

## 响应格式

响应保持 Chat Completions 兼容格式。`model` 字段会返回本次实际被路由到的模型，便于日志追踪、成本分析和效果排查。

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 150,
    "total_tokens": 165
  }
}
```

流式调用时，响应仍按 SSE 分片返回。建议在最终日志中记录完整响应或最终聚合结果里的 `model` 字段，用于确认实际执行模型。

## 工作机制

Auto Router 的执行流程如下：

1. **解析请求**：读取 `messages`、上下文长度、任务意图和可选 `allowed_models` 配置。
2. **筛选候选模型**：根据账号权限、模型可用性、候选模型规则和任务需求得到候选集合。
3. **选择执行模型**：综合模型能力、质量偏好、成本偏好、上下文需求和服务状态选择模型。
4. **转发请求**：把原始 Chat Completions 请求转发给选中的模型。
5. **返回结果**：以 OpenAI 兼容格式返回结果，并在 `model` 字段中标明实际模型。

## 会话粘性

Auto Router 支持会话粘性。同一会话在短时间内连续请求时，会尽量保持同一模型和同一供应商，减少多轮对话中模型切换造成的风格波动，并提升缓存命中率。

会话粘性的规则：

- 系统会根据首条 `system` 消息和首条 `user` 消息生成会话指纹。
- 命中粘性缓存后，后续请求会优先沿用已选模型和供应商。
- 粘性缓存会在一段时间无请求后过期。
- 如果缓存中的模型或供应商不可用，系统会重新路由。

业务侧一般不需要额外处理会话粘性。建议在多轮对话中保持稳定的 `system` 消息和首轮用户意图，避免不必要地改变会话指纹。

## 支持模型

Auto Router 当前会在以下模型中选择。使用 `allowed_models` 限制候选集合时，请使用下列精确模型名。

| 模型 ID |
| --- |
| `claude-sonnet-4-6` |
| `claude-opus-4-6` |
| `claude-opus-4-7` |
| `claude-opus-4-8` |
| `claude-haiku-4-5-20251001` |
| `kimi-k2.6` |
| `kimi-k2.7-code` |
| `glm-5.2` |
| `deepseek-v4-flash` |
| `deepseek-v4-pro` |
| `MiniMax-M3` |
| `gpt-5.5` |
| `gpt-5.4-mini` |
| `gpt-5.4-nano` |
| `qwen3.7-plus` |
| `qwen3.7-max` |
| `gemini-3.5-flash` |
| `gemini-3.1-pro-preview` |

## 限制候选模型

可以通过顶层 `allowed_models` 参数限制 Auto Router 的候选模型集合。该能力适用于以下场景：

- 只允许在指定的一组模型内自动选择。
- 需要排除未完成业务验证的模型。
- 不同业务线希望使用不同模型池。
- 灰度上线新模型时，只让部分请求参与路由。

`allowed_models` 的处理规则：

- 字段不传时，使用账号有权限访问的全部 Auto Router 候选模型。
- 传空数组 `[]` 时，行为与不传一致。
- 传非空数组时，系统会取 `allowed_models` 与服务端 Auto Router 模型池的交集。
- 只支持精确模型名，不支持通配符匹配。
- 数组里的空字符串和重复模型会被忽略。
- 如果交集为空，或 API Key 没有候选模型权限，请求会失败。

### 请求示例

```typescript
const response = await fetch('https://api.modelverse.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <MODELVERSE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [
      {
        role: 'user',
        content: '请解释量子纠缠',
      },
    ],
    allowed_models: [
      'claude-sonnet-4-6',
      'deepseek-v4-pro',
      'glm-5.2'
    ],
  }),
});
```

### Python 示例

```python
response = requests.post(
    'https://api.modelverse.cn/v1/chat/completions',
    headers={
        'Authorization': 'Bearer <MODELVERSE_API_KEY>',
        'Content-Type': 'application/json',
    },
    data=json.dumps({
        'model': 'auto',
        'messages': [
            {
                'role': 'user',
                'content': '请解释量子纠缠',
            }
        ],
        'allowed_models': [
            'claude-sonnet-4-6',
            'deepseek-v4-pro',
            'glm-5.2',
        ],
    }),
)
```

### 匹配规则

`allowed_models` 当前按精确模型名匹配，不做前缀、供应商或通配符展开。

| 写法 | 是否支持 | 说明 |
| --- | --- | --- |
| `deepseek-v4-pro` | 支持 | 精确匹配一个候选模型。 |
| `glm-5.2` | 支持 | 精确匹配一个候选模型。 |
| `claude-sonnet-4-6` | 支持 | 精确匹配一个候选模型。 |
| `deepseek-*` | 不支持 | 不会按通配符展开。 |
| `*/claude-*` | 不支持 | 不会按供应商或模型名前缀匹配。 |

## 成本与质量权衡

当前 Auto Router 未暴露独立的成本质量权衡请求参数。路由策略由服务端统一配置，并结合候选模型集合、账号权限、模型可用性和请求内容进行选择。

如果业务需要更强的成本控制，建议通过 `allowed_models` 把候选集合限制在已评估的模型范围内；如果业务需要更稳定的质量表现，建议只放入已验证满足质量要求的模型。

## 在 cc-switch 中配置 Claude Code

本节适用于希望通过 [cc-switch](https://github.com/farion1231/cc-switch) 管理 Claude Code 供应商，并把 Claude Code 请求转发到 Modelverse Auto Router 的场景。

1.  在 cc-switch 中新增或编辑供应商，填写 Modelverse API Key。
    
2.  请求地址填写：
    
    ```text
    https://api.modelverse.cn/v1
    ```
    
    注意不要在末尾添加斜杠。
    
3.  展开高级选项，将 **API 格式** 选择为 **OpenAI Chat Completions（需开启路由）**。
    
4.  **认证字段** 选择 `ANTHROPIC_AUTH_TOKEN`，这样 cc-switch 会把该供应商的 API Key 写入 Claude Code 读取的认证环境变量。
    
    ![cc-switch 供应商配置](https://cdnv2.udelivrs.com/2026/07/0d6f38f06cc58c17691be8ce37d5ee06_1783478441975.png)
    
5.  在 **模型映射** 中，将 Claude Code 的模型角色统一映射到 Auto Router。
    
    | 模型角色 | 显示名称 | 实际请求模型 | 声明支持 1M |
    | --- | --- | --- | --- |
    | Sonnet | `auto` | `auto` | 按需勾选 |
    | Opus | `auto` | `auto` | 按需勾选 |
    | Fable | `auto` | `auto` | 不建议勾选 |
    | Haiku | `auto` | `auto` | 按需填写 |
    
    `显示名称` 只影响 Claude Code 的 `/model` 菜单展示；真正发给 Modelverse 的是 `实际请求模型`。这里填写 `auto` 后，Modelverse 会根据请求内容自动选择模型。
    
    ![cc-switch 模型映射](https://cdnv2.udelivrs.com/2026/07/84d0da93ae0d52466c22cb1b0738528d_1783478441988.png)
    
6.  如需限制 Auto Router 的候选模型，在 **本地代理请求覆盖** 中配置 Body 覆盖。
    
    Header 覆盖示例：
    
    ```json
    {
      "X-Provider": "cc-switch"
    }
    ```
    
    Body 覆盖示例：
    
    ```json
    {
      "allowed_models": [
        "kimi-k2.7-code",
        "glm-5.2"
      ]
    }
    ```
    
    `allowed_models` 只支持精确模型名。未配置或配置为空数组时，Auto Router 会使用当前账号可用的全部候选模型。
    
    ![cc-switch 请求覆盖](https://cdnv2.udelivrs.com/2026/07/9c8e489bf9b30324401b146b3faf992e_1783478441992.png)
    
7.  保存供应商配置后，返回 cc-switch 首页，开启 cc-switch 本地路由，并选择刚才配置的 UCloud 供应商。
    
    ![cc-switch 启用本地路由](https://cdnv2.udelivrs.com/2026/07/f2eac6739e8c744743b19437555e4b2c_1783478442006.png)
    
8.  新开终端执行：
    
    ```bash
    claude "你好"
    ```
    
    如果正常返回内容，说明 Claude Code 已通过 cc-switch 转发到 Modelverse Auto Router。也可以在 Claude Code 中执行 `/status`，确认当前环境变量和路由配置是否生效。

## 流式响应

Auto Router 支持 `stream: true`。路由只发生在请求开始阶段，后续 token 会从实际执行模型持续返回。

```bash
curl -N https://api.modelverse.cn/v1/chat/completions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "写一段 200 字的产品介绍"
      }
    ]
  }'
```

对于长回答、复杂推理或容易超时的请求，推荐使用流式响应。

## 使用建议

- 在生产日志中记录 `id`、`model`、`usage` 和业务请求标识，便于排查路由结果。
- 对质量敏感的核心链路，先通过 `allowed_models` 限定已验证模型池，再逐步放开范围。
- 对大批量低风险任务，可以提高 `cost_quality_tradeoff`，降低整体调用成本。
- 多轮对话保持稳定的首条 `system` 和首条 `user` 消息，以便更好利用会话粘性。
- 如果某个业务必须固定模型，不要使用 `auto`，直接传具体模型 ID。

## 常见问题

### 如何知道本次实际用了哪个模型？

查看响应中的 `model` 字段。该字段表示 Auto Router 实际选择并执行请求的模型。

### Auto Router 会改变请求格式吗？

不会。请求仍使用 Modelverse 的 Chat Completions 兼容格式。除 `model` 设置为 `auto` 和可选 `plugins` 配置外，其余参数按普通聊天补全请求使用。

### 限制候选模型后没有可用模型怎么办？

如果 `allowed_models` 规则过窄，或账号没有对应模型权限，请求可能失败。建议检查模型名称、通配符规则和 API Key 的模型权限。

### 可以和流式输出一起使用吗？

可以。设置 `stream: true` 即可。模型选择在请求开始时完成，后续按实际模型返回流式分片。

### 什么时候不建议使用 Auto Router？

如果业务需要完全固定的模型行为、固定供应商、固定价格策略或严格复现实验结果，建议直接指定具体模型 ID。