> ## 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 網關會在綁定到某個 API 密鑰的每次補全請求上強制執行這些策略。

網關護欄（Gateway Guardrails）讓你可以為任意 API 密鑰附加由策略驅動的安全、隱私和可靠性檢查。綁定的策略會在每次補全請求上觸發——包括 `/v1/completions`（流式與非流式）、`/v1/images`、`/v1/code`、`/v1/documents`、playground，以及嵌入式組件。

## 嚴格的選擇性啓用（opt-in）契約

**在你將策略綁定到某個 API 密鑰之前，護欄不會生效。** 新建的密鑰、所有現有密鑰，以及每一個通過 Clerk 會話發起調用的調用方，都會完全繞過護欄。系統不存在自動的組織級或用戶級默認策略——護欄是一個強制執行邊界，而不是路由偏好設置，因此網關永遠不會強制執行你沒有明確選擇啓用的東西。

這意味着：

* **現有 API 密鑰不受影響**，除非你明確綁定了策略。上線部署零風險。
* **沒有回退鏈。** 清除某個綁定（`policy_id: null`）會讓密鑰回到無強制執行的狀態。
* **每個密鑰一對一。** 一個密鑰最多隻能綁定一個策略；而一個策略可以綁定到任意數量的密鑰。

## 五種內置保護

每種保護都是一個純評估器：相同的輸入始終產生相同的輸出。它們都是廠商中立的，絕不會在面向客戶的字符串中提及上游提供商。

<AccordionGroup>
  <Accordion title="pii_redactor — 隱藏個人信息">
    在任何模型調用**之前**，從提示詞中清除電子郵件、電話號碼、美國社會安全號碼、符合 Luhn 校驗的信用卡號，以及形似駕照號碼的 ID。

    允許的判定結果：`redact`（默認）、`flag`（僅記錄日誌，提示詞保持不變）。

    階段：僅 `input`。

    ```json theme={null}
    { "guardrail_id": "pii_redactor", "phase": "input", "verdict": "redact" }
    ```
  </Accordion>

  <Accordion title="prompt_injection — 攔截越獄嘗試">
    捕獲典型的 OWASP-LLM01 模式：諸如"忽略之前的指令"、角色劫持、偽造的系統消息、提示詞竊取探測等。

    允許的判定結果：`deny`（默認——向調用方返回一個廠商中立的 422 錯誤）、`flag`。

    階段：僅 `input`。

    ```json theme={null}
    { "guardrail_id": "prompt_injection", "phase": "input", "verdict": "deny" }
    ```
  </Accordion>

  <Accordion title="json_repair — 始終返回有效的 JSON">
    檢測模型輸出中格式錯誤的 JSON。當判定結果為 `repair` 時，運行器會進行一次修復嘗試；如果無法生成有效的 JSON，則回退到原始緩衝區內容。

    允許的判定結果：`repair`（默認）、`flag`。

    階段：僅 `output`。

    配置：`{ "fenced": true }`（默認 `true`）——啓用後，評估器會先剝離一個圍欄式的 `json` 代碼塊再進行解析，以匹配最常見的大模型輸出形態。

    ```json theme={null}
    { "guardrail_id": "json_repair", "phase": "output", "verdict": "repair", "config": { "fenced": true } }
    ```
  </Accordion>

  <Accordion title="max_length — 限制輸入或輸出長度">
    將緩衝區截斷到配置的上限，並附加一個簡短的 `…[truncated]` 標記。

    允許的判定結果：`truncate`（默認）、`flag`。

    階段：`input` 和/或 `output`。

    配置（二選一）：

    * `{ "maxChars": 16000 }` —— 硬性字符數上限。
    * `{ "maxTokens": 4000, "charsPerToken": 4 }` —— 令牌數上限（默認每令牌 4 個字符）。

    ```json theme={null}
    { "guardrail_id": "max_length", "phase": "output", "verdict": "truncate", "config": { "maxTokens": 4000 } }
    ```
  </Accordion>

  <Accordion title="profanity — 保持內容乾淨">
    在輸入或輸出方向上檢測常見的粗俗用語。默認判定為 `flag`（僅可見，不攔截），方便你先審查活動記錄再決定是否要攔截。

    允許的判定結果：`flag`（默認）、`deny`。

    階段：`input` 和/或 `output`。

    ```json theme={null}
    { "guardrail_id": "profanity", "phase": "output", "verdict": "flag" }
    ```
  </Accordion>
</AccordionGroup>

## 五種判定結果

規則的判定結果（verdict）告訴運行器在該保護觸發時應該做什麼。運行器會針對某個階段彙總所有匹配規則中最嚴重的判定結果，並只應用一次：

* **flag（標記）** —— 直接放行。匹配記錄會寫入執行日誌；其餘內容不做任何改動。
* **redact（脫敏）** —— 在轉發之前，將匹配到的文本替換為 `[REDACTED:<kind>]`。
* **truncate（截斷）** —— 裁剪到配置的限制並追加 `…[truncated]`。
* **repair（修復）** —— 對緩衝區執行一次修復處理。僅 `json_repair` 使用。
* **deny（拒絕）** —— 攔截該請求。在 `input` 階段，網關會在任何模型調用之前返回 `422 invalid_request_error`，並附帶 `code: "guardrail_violation"`。在 `output` 階段，響應內容會被替換為拒絕原因，並且當次生成產生的所有產物都會被丟棄。

面向客戶的消息永遠不會提及上游提供商——SDK 會暴露一個穩定的 `guardrail_violation` 代碼，讓你的應用可以基於策略強制執行結果來做分支處理，而無需知道具體是哪個檢測器觸發的。

## 快速開始 —— 儀表盤

1. 打開 **Dashboard → Guardrails**，選擇一個預設（或點擊 **New policy** 新建一個空白策略）。
2. 從選擇器中添加保護項；每張卡片都可以讓你選擇階段和判定結果。
3. 使用右側欄中的 **Test bench（測試台）**，通過該策略回放一個示例提示詞以及可選的模型輸出。你將看到每條規則的判定軌跡。
4. 在編輯器下方的 **Bindings（綁定）** 面板中，為你想要強制執行該策略的每個 API 密鑰打開開關。

就是這樣。策略會立即在所有已綁定的密鑰上生效。

## 快速開始 —— SDK

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

// 1. （可選）從預設開始
const presets = await theo.guardrails.presets.list();
const enterprise = presets.find((p) => p.id === "enterprise-default")!;

// 2. 創建策略
const policy = await theo.guardrails.policies.create({
  name: "Production defaults",
  description: "PII redaction + jailbreak deny + JSON repair on output.",
  rules: enterprise.rules,
});

// 3. 將其綁定到某個 API 密鑰
await theo.keys.setGuardrailPolicy("<key-uuid>", policy.id);

// 4. 驗證綁定情況
const bindings = await theo.guardrails.policies.bindings(policy.id);
console.log(`Policy is enforcing on ${bindings.count} key(s).`);

// 5. 追蹤審計日誌
const recent = await theo.guardrails.executions.list({ policyId: policy.id, limit: 20 });
```

<Note>
  管理端點（`/api/v1/guardrail-policies/*`、`/api/v1/keys/{id}/guardrails`）需要 `billing` API 密鑰作用域——與路由偏好設置的約定保持一致。如果你打算以編程方式管理策略，請顯式鑄造一個具有該作用域的密鑰；對於正常流量而言，默認的 `completions` 作用域已經足夠。
</Note>

## 錯誤信封

當輸入階段的 `deny` 觸發時，API 會返回：

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "guardrail_violation",
    "message": "Request blocked by your active guardrail policy.",
    "request_id": "req_..."
  }
}
```

HTTP 狀態碼為 `422`。對於流式補全，同一個信封會以 `error` SSE 事件的形式發出：

```
event: error
data: { "error": { "type": "invalid_request_error", "code": "guardrail_violation", ... } }
```

拒絕原因是該保護項暴露給客戶的文案；匹配到的模式 ID（例如 `ignore_previous`）刻意**不會**被包含在內，以防攻擊者藉此探測出到底是哪個檢測器觸發的。

## 流式行為

輸出護欄會在服務器完整收集完整個令牌流之後才運行。這意味着：

* **令牌會在模型生成時實時流式傳輸。** 客戶端實時看到的是未經護欄處理的原始文本。
* **`done` 事件攜帶的是經過護欄處理的緩衝區內容。** 任何從 `done` 事件重新渲染消息主體的客戶端（官方 SDK、playground、嵌入式組件）最終展示的都是符合策略的版本。
* **在 `deny` 判定下，會在 `done` 之前額外發出一個 `error` SSE 事件。** `done.content` 會被替換為拒絕原因，並且該輪對話中產生的所有產物都會被丟棄。

如果你的客戶端是實時渲染令牌流、並且不會重新讀取 `done.content`，那麼當你需要對每一個可見字符都進行字節級精確的策略強制執行時，請考慮切換到非流式模式（`stream: false`）。

## 團隊策略

`scope: "team"` 策略對所屬組織的每一位成員都可見，創建/更新需要 `manageWebhooks` 權限（該權限被複用作為通用的團隊配置門檻；目前還沒有專門的 `manageGuardrails` 權限位）。

個人策略只對其創建者可見。團隊密鑰只能綁定到同一組織內的團隊策略——當作用域不匹配時，綁定端點會以 `guardrail_policy_not_bindable` 強制執行這一規則。

## 審計與遙測

每次評估都會向 `guardrail_executions` 寫入一條不可變的記錄（保留期 90 天，由 BullMQ 保留期工作進程強制執行）。每條記錄都會捕獲：

* `policy_id`、`key_id`、`user_id` —— 觸發本次評估的主體/對象。
* `guardrail_id`、`phase`、`verdict` —— 觸發的規則與結果。
* `matched_pattern`、`redacted_count` —— 有邊界限制的取證上下文（不包含原始提示詞）。
* `latency_ms` —— 每條規則的開銷，會展示在儀表盤的活動流中。

可以通過 `theo.guardrails.executions.list({ keyId, policyId, since })` 或 `GET /api/v1/guardrail-executions` 追蹤該日誌。儀表盤的 **Recent activity（最近活動）** 面板會以通俗易懂的語言渲染同一批記錄。

## 護欄不會改變的內容

* **模型允許列表、路由規則、技能、品牌人格、響應風格與個性**都會各自獨立地照常工作。護欄是圍繞請求/響應路徑附加的一層，不會覆蓋其他密鑰級功能。
* **沒有綁定的現有密鑰保持不變。** 你需要按密鑰逐一選擇啓用。
* **不影響成本。** 內置保護項都是純評估器（亞毫秒級）；`json_repair` 的修復處理只有在檢測到格式錯誤的 JSON 時才會額外產生一次很小的調用開銷。

## API 參考

* [列出策略](/api-reference/guardrails/list-policies)
* [創建策略](/api-reference/guardrails/create-policy)
* [獲取 / 更新 / 刪除策略](/api-reference/guardrails/get-policy)
* [測試策略](/api-reference/guardrails/test-policy)
* [列出某策略的綁定](/api-reference/guardrails/policy-bindings)
* [列出預設](/api-reference/guardrails/presets)
* [獲取 / 設置密鑰綁定](/api-reference/guardrails/key-binding)
* [列出執行記錄](/api-reference/guardrails/executions)


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