> ## 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 的路由引擎。

Routing Studio 是 Theo 面向每個客戶的路由層。你只需描述用戶提出請求的方式,Theo 的路由引擎就會讓分類器傾向於選擇正確的模式——完全不需要你去維護一個獨立的"偏好"對象。規則直接掛在每個 API 密鑰上:打開密鑰,添加應該觸發規則的詞語,選擇目標,然後保存即可。

**路由規則**會將一組關鍵詞(或者,對於高級用戶,一段原始正則表達式)映射到某個 Theo 引擎。規則的執行發生在 Theo 全局意圖分類器之前,因此在存在歧義時,你所在領域的規則會優先生效。路由引擎會把這些規則疊加在其全局級聯邏輯之上,並且永遠不會讓它們繞開 Theo 的安全鎖(隱身模式、代理模式),也不會讓上游供應商名稱泄露到你客戶看到的界面中。

除了規則之外,你還可以配置:

* **少樣本示例(Few-shot examples)** — 注入到分類器系統提示詞中的"提示詞 / 預期模式"配對(每次請求最多 8 條)。
* **置信度下限覆蓋(Confidence-floor overrides)** — 針對每種模式,替換 Theo 全局 `0.85` 的提升下限。降低下限可以讓意圖提升更容易發生;提高下限則會更保守。

大多數團隊只需要在密鑰頁面上編輯規則即可。共享規則集是面向高級用戶的功能,適用於需要跨多個密鑰共用的規則列表,或作為團隊默認值使用的場景。

## 在密鑰上編輯規則

打開 [`api.hitheo.ai/dashboard/keys`](https://api.hitheo.ai/dashboard/keys),找到要調優的 API 密鑰,點擊 **Routing** 標籤。面板中直接內置了你所需要的一切:

* **繼承上下文(Inherited context)** — 如果沒有為該密鑰設置按密鑰規則,面板會告訴你該密鑰當前繼承的是團隊默認值、你的個人默認值,還是什麼都沒有繼承。
* **規則(Rules)** — 每條規則對應一行。每一行都有一個關鍵詞標籤輸入框、一個目標下拉框,以及一個 Gentle(寬鬆)/ Balanced(平衡)/ Strict(嚴格)切換開關。空狀態下提供幾個一鍵式起始模板(定價問題、客戶投訴、法律審查、照片與圖片請求),以及供高級用戶使用的空白規則標籤。
* **更多選項(More options)** — 每一行上的一個小箭頭圖標可以展開備註字段、原始正則表達式文本框、可選的 Theo 引擎指定,以及用於精細控制的原始置信度滑塊。
* **試用提示詞(Try a prompt)** — 一旦你開始編輯,就會出現一個緊湊的輸入框。輸入一段示例客戶提示詞,面板會渲染出一行差異對比(`基線模式 → 應用規則後的模式`),讓你在保存之前就能準確看到會發生哪些變化。

點擊 **Save changes(保存更改)** 將規則寫入該密鑰。點擊 **Clear per-key rules(清除按密鑰規則)** 可以完全刪除這些規則,回退到繼承的默認值。

### 高級:手寫正則表達式

標籤編輯器會將關鍵詞映射為 API 內部使用的同一個 `pattern` 字符串。如果要用原始 ECMAScript 正則表達式(前瞻、錨點、捕獲組)編寫規則,請展開該行的 **More options** 箭頭,在 pattern 文本框中編輯。粘貼正則表達式會自動將該行切換為高級模式,這樣我們就不會悄悄地重寫你的表達式;如果加載某個密鑰時發現它的 pattern 無法在標籤編輯器中往返還原,該行會默認以高級模式打開。

## ContractIQ ——完整實操演示

ContractIQ 是一個虛構的法律科技工具。它的用戶會粘貼合同條款,並要求 Theo 對其進行分析。如果沒有任何規則,"look at this clause"(看看這條條款)會被路由到 `fast`(簡短回覆);而在密鑰上設置一條規則後,它會被路由到 `think`(深度分析)。

### 1. 在 API 密鑰上設置規則

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/$KEY_ID/routing-rules \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "rules": [
        {
          "pattern": "\\\\b(clause|provision|indemnity|warranty)\\\\b",
          "target_mode": "think",
          "confidence": 0.92,
          "description": "Contract terms get the analytical engine."
        }
      ],
      "examples": [
        { "prompt": "Look at this clause", "expected_mode": "think" },
        { "prompt": "Compare these two indemnity sections", "expected_mode": "think" }
      ]
    }'
  ```

  ```typescript SDK theme={null}
  await theo.routingRules.set(keyId, {
    rules: [
      {
        pattern: "\\\\b(clause|provision|indemnity|warranty)\\\\b",
        target_mode: "think",
        confidence: 0.92,
        description: "Contract terms get the analytical engine.",
      },
    ],
    examples: [
      { prompt: "Look at this clause", expected_mode: "think" },
      { prompt: "Compare these two indemnity sections", expected_mode: "think" },
    ],
  });
  ```
</CodeGroup>

響應確認了規則已在該密鑰上生效:

```json theme={null}
{
  "key_id": "22222222-2222-4222-8222-222222222222",
  "rules": [
    {
      "id": "r_a4b8c01x9y",
      "pattern": "\\\\b(clause|provision|indemnity|warranty)\\\\b",
      "target_mode": "think",
      "confidence": 0.92,
      "description": "Contract terms get the analytical engine."
    }
  ],
  "examples": [...],
  "active": true,
  "shared_binding": null
}
```

`active: true` 字段確認了這些規則目前正在驅動該密鑰上的補全請求。要刪除這些規則並回退到繼承的默認值,向同一個端點發送 `DELETE` 請求即可(或者在 SDK 中調用 `theo.routingRules.clear(keyId)`)。

### 2. 發送一次補全請求

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/completions \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Look at this indemnity clause", "mode": "auto", "stream": true }'
```

SSE 的 `meta` 事件現在會攜帶一個 `customer_preference` 字段,用於確認觸發了某條規則:

```json theme={null}
{
  "routing": {
    "requested_mode": "auto",
    "resolved_mode": "think",
    "promoted": true,
    "reason": "customer_preference",
    "explanation": "Routing Studio rule matched: \"indemnity clause\".",
    "customer_preference": {
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
```

只要你的規則驅動了路由決策,playground 就會在路由記錄的提升原因旁渲染一個綠色標籤。

### 3. 在上線前測試變更

使用測試端點,分別在啓用與不啓用該偏好的情況下重放同一個固定提示詞:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://www.hitheo.ai/api/v1/routing-preferences/$PREF_ID/test" \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "prompt": "Compare these two warranty sections", "mode": "auto" }'
  ```

  ```typescript SDK theme={null}
  const diff = await theo.routingPreferences.test(pref.id, {
    prompt: "Compare these two warranty sections",
    mode: "auto",
  });
  console.log(diff.baseline.resolved_mode);         // "fast"
  console.log(diff.with_preference.resolved_mode);  // "think"
  ```
</CodeGroup>

這兩段數據都符合與你生產環境調用方所收到的相同 `routing` 遙測結構——這份差異對比是對你的調優效果的一次精確、確定性的預覽。

#### 測試尚未保存的草稿

控制台的測試台會重放你當前正在編輯的草稿——它絕不會要求你先保存。如果你是在 API 之上構建自己的界面,可以攜帶完整的草稿正文,請求不帶 id 的 `POST /api/v1/routing-preferences/test` 路由。響應結構與按 id 請求的路由相同;不會持久化任何內容。

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/routing-preferences/test \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Look at this clause",
    "mode": "auto",
    "draft": {
      "name": "ContractIQ Legal (draft)",
      "rules": [
        { "pattern": "\\b(clause|provision)\\b", "target_mode": "think", "confidence": 0.92 }
      ],
      "examples": []
    }
  }'
```

## 優先級順序

Routing Studio 位於 Theo 更廣泛的路由引擎之內。完整的級聯順序如下,首個匹配項獲勝:

1. **代理鎖(Agentic locks)**(`insurance_*`、`data_extraction`)——永不被提升。
2. **附件 → vision** — 非媒體調用方攜帶的圖片附件會路由到 `vision`。
3. **技能獨佔覆蓋(Skill exclusive override)** — 設置了 `intensity: 100` 和 `modelPreference` 的技能優先生效。
4. **Routing Studio 規則** — 你的規則在這一步觸發。
5. **意圖分類器(Intent classifier)** — 運行時會注入你的少樣本示例,並使用你按模式設置的置信度下限覆蓋。
6. **隱身族保持(Stealth family preservation)** — 來自 `stealth_*` 調用方的提升會保持在隱身族內部。
7. **對話提示(Conversation hint)** — 當調用方使用 `auto` 時,回退到上一輪的產出物類型。
8. **請求的模式(Requested mode)** — 默認值。

你的規則**無法**繞開代理族鎖(法律/醫療/數據提取等模式),也**無法**繞開隱身族隔離。如果某條規則為隱身調用方指定了一個與隱身模式不兼容的目標模式,該模式會被靜默地重新映射為對應的隱身版本。

## 置信度下限覆蓋

只有當置信度 ≥ `0.85`(`PROMOTION_CONFIDENCE_FLOOR`)時,分類器才會提升調用方的模式。對於分類器在較低置信度下也經常判斷正確的專業領域,可以降低該下限:

```json theme={null}
{
  "name": "Legal Default",
  "confidence_floor_overrides": {
    "think": 0.65
  }
}
```

而對於誤提升代價較高的領域,則應提高該下限:

```json theme={null}
{
  "name": "Cost-Sensitive",
  "confidence_floor_overrides": {
    "image": 0.95,
    "video": 0.95
  }
}
```

所有值都會在服務端被限制在 `[0.5, 0.99]` 區間內——無論取哪一端,都無法徹底關閉這個下限機制。

## 品牌安全契約

每一個由客戶編寫的字段——名稱、描述、規則 pattern、規則描述、示例提示詞——都會被掃描是否包含上游供應商名稱(Claude、OpenAI、Anthropic、Gemini、fal.ai 等),一旦發現就會在校驗階段被拒絕。Theo 的界面始終以 Theo 的身份呈現。你的客戶永遠不會看到底層的模型提供方。

同樣的掃描也會應用於 Routing Studio 的輸出——你的調用方收到的 `customer_preference` 數據塊,保證不包含任何供應商名稱。

## 限制

| 限制項 | 取值 |
| - | - |
| 每個偏好的規則數 | 50 |
| 每個偏好的示例數 | 30 |
| 注入分類器的示例數 | 8(按優先級從高到低) |
| Pattern 長度 | 512 字符 |
| 示例提示詞長度 | 1024 字符 |
| 置信度範圍 | `[0.5, 0.99]`(限制區間) |
| 測試提示詞長度 | 4096 字符 |
| 緩存 TTL | 5 分鐘(Redis) |

## 團隊作用域 vs. 個人作用域

創建時傳入 `scope: "team"`,可以將該偏好的作用域設為你當前所在的組織。團隊偏好會成為組織默認值的候選項;擁有團隊配置權限的團隊管理員可以對其進行管理。如果沒有團隊綁定,密鑰會依次繼承:所屬作用域的默認值 → 用戶的個人默認值 → 無偏好。

```typescript theme={null}
await theo.routingPreferences.create({
  name: "ACME Legal Default",
  scope: "team",
  is_default: true,
  rules: [...],
});
```

在第二個團隊偏好上設置 `is_default: true` 會返回 `409 conflict`——每個作用域最多隻能有一個默認值。

## 常見模式

* **領域詞彙偏置。** 對於明確的關鍵詞("policy""claim""rune")使用規則;對於表達方式("draft me a response to this complaint" → `think`)使用示例。
* **成本控制。** 為個人密鑰提高 `image`/`video` 的下限;團隊密鑰則保留默認值。
* **速度偏置。** 降低 `fast` 的下限,並添加類似 `{ prompt: "thanks!", expected_mode: "fast" }` 的示例,避免簡短回覆被升級為 `think`。

## 按密鑰規則 vs. 共享規則集——如何選擇

如果你只是在調優一兩個密鑰,直接在密鑰頁面上編輯規則即可。控制台會隱藏除規則編輯器本身之外的一切——無需創建"偏好",也無需配置綁定。

在以下情況下,可以選擇使用共享規則集:

* 你希望一份規則列表能夠覆蓋多個 API 密鑰(例如團隊中每個密鑰都使用同一套法律詞彙)。
* 你希望有一個團隊默認值,新建密鑰可以自動繼承它。
* 你在通過腳本進行批量修改,更傾向於在源代碼管理中一次性編寫規則,而不是在各個密鑰之間重複維護。

在底層實現上,按密鑰端點和共享規則集端點都會寫入同一張 `routing_preferences` 表;唯一的區別在於這一行記錄是以某個特定密鑰命名(不會出現在共享列表中),還是帶有客戶自定義的名稱。

## 後續步驟

* [`/api/v1/routing-preferences` 參考文檔](/api-reference/routing-preferences/list-preferences) — 每個端點的完整請求/響應結構。
* [Routing Studio SDK 參考文檔](/sdk-reference/routing-studio) — `theo.routingPreferences.*`、`theo.routingRules.*` 以及按密鑰綁定的輔助方法。
* [引擎路由與回退](/core-concepts/model-routing) — Routing Studio 在 Theo 更廣泛的路由引擎中所處的位置。


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