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

# 引擎路由与回退

> Theo 如何为每个任务选择最佳引擎，并处理故障。

Theo 不依赖单一模型。引擎路由器会根据已解析的模式，为每个任务选择最优引擎，并在主引擎不可用时自动进行故障转移。

## 引擎表

|| 模式 | 引擎 ID | 说明 |
||------|-----------|-------------|
|| fast / auto | `theo-1-flash` | 快速、轻量的补全 |
|| think | `theo-1-reason` | 深度推理与分析 |
|| code | `theo-1-code` | 生产级代码生成 |
|| image | `theo-1-create` | 图像生成 |
|| video | `theo-1-motion` | 视频生成 |
|| research | `theo-1-research` | 多步骤网络研究与综合 |
|| roast | `theo-1-edge` | 无过滤的幽默 |
|| genui | `theo-1-genui` | 生成式 UI 组件 |
|| domain analysis | `theo-1-analyze` | 特定领域分析（业务、运营等） |
|| data extraction | `theo-1-extract` | 文档 OCR 与结构化数据提取 |

Theo 可访问 300 多个模型，并会为每个引擎自动选择最合适的一个。

## 自动故障转移

每个引擎都内置了故障转移机制。当主模型不可用或质量表现低于阈值时，Theo 会自动路由到备用模型——你永远不会看到损坏的响应。故障转移过程是透明的，并会记录在审计跟踪中。

## 响应中的引擎 ID

API 响应始终使用 Theo 品牌的引擎标识符：

```json theme={null}
{
  "model": {
    "id": "theo-1-reason",
    "label": "Theo Reason",
    "engine": "theo-core"
  }
}
```

## 技能引擎偏好

技能可以通过其清单中的 `enginePreference` 字段推荐首选引擎。当某个技能的首选引擎与模式默认值不同时，Theo 会优先使用该技能指定的引擎（如果可用）。

## 按客户覆盖阶段（路由工作室）

在技能独占覆盖与全局意图分类器之间，路由引擎会查询调用方所绑定的 **路由工作室偏好**——这是客户自定义的一组规则包，包含关键词规则、少样本示例，以及按模式设置的置信度下限覆盖。这些偏好让你的业务领域可以在存在歧义的提示词上占优，而无需重新训练全局分类器。

匹配顺序如下，先匹配者优先：

1. 代理型锁定（`insurance_*`、`data_extraction`）——永不被提升。
2. 附件 → 视觉。
3. 技能独占覆盖（intensity 为 100 且带 `modelPreference` 的技能）。
4. **路由工作室规则。** 客户自定义规则的快速路径。
5. 意图分类器（结合客户的少样本示例与按模式设置的置信度下限）。
6. 隐身系列保持。
7. 会话提示（针对 `auto` 调用方）。
8. 请求的模式。

客户规则无法绕过隐身或代理型系列锁定。当某条规则针对隐身调用方指向一个与隐身模式不兼容的模式时，引擎会静默地将其重新映射为对应的隐身等效模式。

当某个偏好参与了解析结果时，`routing` 块会携带一个 `customer_preference` 字段，其中包含该偏好的 id、名称、命中的规则 id（如果有），以及注入分类器的少样本示例数量：

```json theme={null}
{
  "routing": {
    "reason": "customer_preference",
    "customer_preference": {
      "id": "<uuid>",
      "name": "ContractIQ Legal",
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
```

完整的 ContractIQ 演示流程请参阅[路由工作室指南](/guides/routing-studio)，`theo.routingPreferences.*` 与 `theo.keys.setRoutingPreference()` 的用法请参阅 [SDK 参考](/sdk-reference/routing-studio)。

## Playground 中的路由回执

每次补全都已经在 SSE 的 `meta` 与 `done` 事件中包含一个结构化的 `routing` 块：

```json theme={null}
{
  "routing": {
    "requested_mode": "fast",
    "resolved_mode": "image",
    "promoted": true,
    "reason": "intent_promotion",
    "explanation": "Detected an image generation intent in a text-mode caller.",
    "classification": {
      "mode": "image",
      "confidence": 0.93,
      "used_fast_path": true,
      "reasoning": "Keyword 'draw me' matched image-generation pattern."
    },
    "image_routing": {
      "resolved_engine": "theo-1-rapid",
      "auto_selected": true,
      "quality": "standard"
    }
  }
}
```

Playground 会将其渲染为每条助手回复下方的内联 **路由回执**：一行简洁的 `请求 → 解析` 结果、一个在路由引擎覆盖调用方模式时出现的 `Promoted` 标记、引擎给出的 `explanation`，以及一个可点击展开的面板，用于展示分类器置信度、技能覆盖、锁定的系列以及图像子引擎。一条由四个圆点组成的流水线（CRL → Skill → Route → Dispatch）会高亮出主导本次决策的阶段。

这与你自己的应用通过接口接收到的数据完全相同——将你的 SDK 指向 `meta` 事件的 `routing` 字段，即可在你的产品中呈现同样的展示效果。

## 检查引擎可用性

```bash theme={null}
curl https://www.hitheo.ai/api/v1/models \
  -H "Authorization: Bearer $THEO_API_KEY"
```

返回完整的引擎注册表，包含状态与可用性信息。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.