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