> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# 路由

> auto 路由和 tier

`model` 支持两种用法：传入 `model: "auto"` 由 JoyToken 自动选择最终模型和 provider（推荐），或直接传入模型目录中的具体模型 ID，将请求固定到指定模型。

## 常用写法

| 目标       | 请求写法                                |            |             |
| -------- | ----------------------------------- | ---------- | ----------- |
| 智能路由（推荐） | `model: "auto"`                     |            |             |
| 指定档位     | `model: "auto"` + \`tier: "economy" | "standard" | "premium"\` |
| 指定模型     | `model: "<模型目录中的 modelName>"`       |            |             |

## 智能路由

用户只需传入 `model: "auto"`，即可启动 JoyToken 智能路由引擎。系统结合多维请求特征、语义规则与大模型复核，识别系统设定、工具意图、上下文和用户诉求，判断任务类型及复杂度，并匹配相应的路由策略。

对于复杂请求，系统自动生成任务计划，完成任务拆解、模型与档位匹配及结果聚合；简单请求则直接进行单模型择优。

在策略约束下，系统从持续扩展的在线模型与能力资源池中，综合质量、成本、时延和实时成功率进行智能调度，并通过自动熔断、流量切换与跨档兜底，保障服务质量与连续性。

```json
{
  "model": "auto",
  "messages": [
    { "role": "user", "content": "用一句话总结这张工单。" }
  ]
}
```

```bash
curl -X POST "$JOY_TOKEN_API_BASE_URL/openai/v1/chat/completions" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "用一句话总结这张工单。" }]
  }'
```

## 指定模型

把 `GET /api/v1/models` 返回的 `modelName` 作为请求的 `model` 传入。此时 JoyToken 跳过打分和路由，直接把请求发给该模型。

```json
{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "用一句话总结这张工单。" }
  ]
}
```

```bash
curl -X POST "$JOY_TOKEN_API_BASE_URL/openai/v1/chat/completions" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{ "role": "user", "content": "用一句话总结这张工单。" }]
  }'
```

## 档位

`tier` 用于收窄 `auto` 请求的候选范围；不传则由 JoyToken 自行决定。

| 档位         | 适合场景           |
| ---------- | -------------- |
| `economy`  | 成本优先、批处理、低风险任务 |
| `standard` | 默认平衡档          |
| `premium`  | 高质量或关键评估任务     |

## 编排模式（多任务规划）

对于复杂请求，JoyToken 可能以编排模式处理单个 `model: "auto"` 请求：先生成任务计划（plan），用选定的子模型逐个执行任务，最后汇总出最终答案。你无需显式开启，由网关根据请求自动决定。

### 如何识别

| 信号                          | 说明                                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `plan`（顶层）                  | 有序任务列表，仅编排模式返回                                                                                  |
| `choices[].message.content` | 变为各任务输出的 JSON 数组（含 `content` 和 `title`），而非单一字符串                                                 |
| `metadata`（数组）              | 每个任务一条，含保留任务 `__planner__` 和 `__final__`                                                        |
| 流式 planning 事件              | 首先发出一个 `orchestration.phase` 为 `planning` 的 chunk，携带有序的 `plan`，其后紧跟 `__planner__` 的 metadata 事件 |
| 流式任务 chunk                  | 每个任务的正文 chunk 都携带 `orchestration` 字段（`task_id`、`task_seq`、`task_status`、`title`）                |
| 流式 `metadata` 事件            | 每个任务在其正文之后各发出一个独立 metadata 事件（值为单个对象，而非数组）                                                      |

### 任务生命周期

| 字段            | 说明                                                                  |
| ------------- | ------------------------------------------------------------------- |
| `task_id`     | 任务标识；`__planner__` 和 `__final__` 为保留值                               |
| `task_seq`    | 执行顺序；`0` 为规划器                                                       |
| `task_status` | 任务状态，如 `DONE`                                                       |
| `tag`         | 任务角色，如 `orchestration`、`search`、`reasoning`、`writing`、`aggregation` |
| `title`       | 可读的任务标题                                                             |

> **Warning**
>
> 编排模式下每个任务单独计费（每个任务一条 `metadata`/`billing`），且可能使用不同子模型。渲染前请先将 `choices[].message.content` 按 JSON 解析，并对所有任务 metadata 的 `billing.credits_used` 求和。

## 确认路由结果

| 信号                 | 说明                 |
| ------------------ | ------------------ |
| `metadata.model`   | JoyToken 最终模型      |
| `metadata.tier`    | 实际计费/路由档位          |
| `metadata.billing` | Credits 和 token 消耗 |

## 常见排查

| 现象                       | 优先检查                              |
| ------------------------ | --------------------------------- |
| tier 不允许                 | API Key 策略是否允许该 tier              |
| 没有候选模型                   | tier、模型黑名单、钱包和 Key 预算             |
| IP 不允许                   | 服务端出口 IP 是否在白名单                   |
| `auto` 失败                | 策略、tier、余额过滤后是否还有候选模型             |
| 传入具体模型名被拒绝               | 模型名是否与目录完全一致，以及 API Key 策略是否允许该模型 |
| 指定模型返回 `model_exhausted` | 模型名是否与目录完全一致，以及该模型是否有上游容量         |
| 指定模型时 `tier` 不生效         | 正常现象：指定模型始终按模型自身档位计费              |