> ## 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.