政策流程建構器

Policy Flow Builder 可讓您透過條件式執行來設計防護欄管線。它不是讓防護欄彼此獨立執行，而是將它們串接成有順序的步驟，並控制每個防護欄通過、政策檢查失敗（內容干預）或發生技術錯誤（例如逾時、提供者無法連線、缺少防護欄）時會發生什麼事。

它支援兩種模式：guardrail 備援（當某個 guardrail 失敗時改用不同的 guardrail）以及重試相同的 guardrail（如果同一個 guardrail 失敗，則再次執行，例如處理暫時性錯誤）。搭配 on_error，您可以將技術失敗與政策失敗區分處理，例如在主要 API 發生錯誤時改為備援到另一個提供者，同時仍封鎖被標記的內容。

何時使用 Flow Builder

做法	使用情境
簡單政策 (`guardrails.add`)	所有防護欄並行執行；任何失敗都會封鎖請求。
Flow Builder（管線）	防護欄依序執行；您可為每個步驟選擇動作（下一步、封鎖、允許、自訂回應）。

當您需要以下情況時，請使用 Flow Builder：

防護欄備援 — 使用 on_fail: next 在某個防護欄失敗時嘗試不同的防護欄（例如，快速過濾器 → 更嚴格的過濾器）
重試同一個防護欄 — 將同一個防護欄加入多個步驟；如果它失敗，on_fail: next 會移到下一個步驟，而下一個步驟也可以是同一個防護欄（適合處理暫時性的 API 錯誤或速率限制）
條件式路由 — 例如，若快速防護欄失敗，改執行更進階的防護欄，而不是立即封鎖
自訂回應 — 當防護欄失敗時，回傳特定訊息而不是通用封鎖訊息
資料串接 — 將修改後的資料（例如已遮罩 PII 的內容）從一個步驟傳到下一個步驟
細緻控制 — 每個步驟在通過與失敗時採取不同動作
技術錯誤路由 — 將 on_error 與 on_fail 分開設定，讓服務中斷或逾時時可以允許、封鎖、進入下一步，或回傳自訂回應，而不會將它們與內容違規混為一談

概念

管線

一個管線包含：

模式：pre_call（在 LLM 之前）或 post_call（在 LLM 之後）
步驟：按順序排列的防護欄步驟清單

結果：通過、失敗與錯誤

每次步驟執行會產生以下三種結果之一：

結果	意義	常見原因
pass	防護欄已完成且未封鎖	內容被允許，或資料已被修改並回傳
fail	政策干預	防護欄觸發了干預（例如標記內容、封鎖請求）
error	技術失敗	逾時、網路錯誤、防護欄未註冊，或其他非干預例外

on_pass 與 on_fail 分別套用於 pass 與 fail。on_error 僅套用於 error。如果省略 on_error，管線會對 error 結果使用 on_fail（向後相容）。

步驟動作

對於每個步驟，您可以為 pass、fail，以及（可選）error 選擇一個動作。允許的值為：next、allow、block、modify_response。

動作	說明
下一步 (`next`)	繼續到管線中的下一個 guardrail
允許 (`allow`)	停止管線並允許請求繼續
封鎖 (`block`)	停止管線並封鎖請求
自訂回應 (`modify_response`)	傳回自訂訊息，而非預設的封鎖

步驟選項

欄位	類型	說明
`guardrail`	`string`	要執行的 guardrail 名稱
`on_pass`	`string`	結果為 pass 時的動作：`next`、`allow`、`block`、`modify_response`
`on_fail`	`string`	結果為 fail（政策介入）時的動作：`next`、`allow`、`block`、`modify_response`
`on_error`	`string`（選填）	結果為 error（技術性）時的動作。如果省略，error 會使用 `on_fail`。
`pass_data`	`boolean`	將修改後的請求資料（例如已遮罩的 PII）傳遞到下一步
`modify_response_message`	`string`	使用 `modify_response` 動作時的自訂訊息

使用 Flow Builder（UI）

前往 LiteLLM 管理 UI 中的 Policies
按一下 + Create New Policy 或現有政策上的 Edit
選取 Flow Builder（而非簡易表單）
設計您的流程：
- Trigger — 傳入的 LLM 請求（當政策符合時執行）
- Steps — 新增 guardrail；依每一步設定 ON PASS、ON FAIL，以及 ON API FAILURE / ON ERROR（當 ON API FAILURE 未設定時，技術性錯誤會遵循 ON FAIL）
- End — 當管線允許時，請求會繼續傳送至 LLM
在步驟之間使用 + 來插入另一個 guardrail 步驟（用於備援、重試，或更嚴格的第二次檢查）
使用 Test Pipeline 在儲存前執行範例訊息
按一下 Save Policy（或 Save）以建立或更新政策

在 UI 中設定 guardrail 備援（逐步操作）

按一下 Policies

管理 UI 中的 Policies 分頁

按一下 + Add New Policy

新增政策

按一下 Flow Builder

選擇流程建構器

按一下 Continue to Builder

繼續前往建構器

在第一個步驟中按一下 guardrail search 欄位

選取第一個 guardrail，搜尋欄位

選擇 Test Moderation（或您的主要 guardrail）

選擇 Test Moderation

對於其中一個分支（例如 ON API FAILURE），將動作設為 Next Step，這樣當 API 發生錯誤時，流程就可以直接往下進到下一個 guardrail

將動作設為下一步

對於 ON PASS，設定為 Allow（如果在允許之前還需要更多步驟，則可設定為 Next Step）

將通過設為允許

開啟下一個結果的搜尋/下拉選單（例如 ON FAIL）

設定另一個分支，搜尋欄位

如果失敗檢查應該繼續到您的備援 guardrail，請將該分支設為 Next Step

ON FAIL 或分支，Next Step

按一下步驟之間的 + 來新增第二個 guardrail

新增步驟，加號控制項

在新步驟上開啟 guardrail 搜尋欄位

第二個步驟，guardrail 搜尋

選擇 Insults & Personal Attacks（或您的備援 / 更嚴格 guardrail）

選擇辱罵與人身攻擊

依需要將此步驟的分支設定為 Next Step 或 Block

第二個步驟分支，Next Step

當此 guardrail 應成功完成流程時，將 ON PASS 設為 Allow

第二個步驟，通過時允許

開啟您要使用 Custom Response 的分支（例如最後一步的 ON FAIL）

自訂回應，開啟分支選擇器

選擇 Custom Response

選擇自訂回應

按一下 Enter custom response... 並輸入您的訊息

自訂回應文字欄位

視需要在 Enter custom response... 中確認或編輯訊息

自訂回應，確認訊息

開啟 Test Pipeline

Test Pipeline 面板

按一下 Run Test

執行測試

在結果中展開 Step 1（或第一個 guardrail 列），查看 ERROR / Next Step 與 PASS / Allow 的差異

展開測試結果中的第一個步驟

展開 Step 2（例如 Insults & Personal Attacks），確認備援後的 PASS 和 Allow

展開步驟 2，第二個 guardrail 結果

設定（YAML）

在您的 policy 設定中定義 pipeline：

config.yaml
guardrails:
  - guardrail_name: pii_masking
    litellm_params:
      guardrail: presidio
      mode: pre_call

  - guardrail_name: prompt_injection
    litellm_params:
      guardrail: lakera
      mode: pre_call

policies:
  my-pipeline-policy:
    description: "PII mask first, then check for prompt injection"
    guardrails:
      add:
        - pii_masking
        - prompt_injection
    pipeline:
      mode: pre_call
      steps:
        - guardrail: pii_masking
          on_pass: next
          on_fail: block
          pass_data: true
        - guardrail: prompt_injection
          on_pass: allow
          on_fail: block

policy_attachments:
  - policy: my-pipeline-policy
    scope: "*"

備援與重試

guardrail 備援

使用 on_fail: next 在某個 guardrail 失敗時切換到另一個 guardrail。先執行較輕量的 guardrail；如果失敗，則升級到更嚴格或不同的提供者：

policies:
  fallback-policy:
    guardrails:
      add:
        - fast_content_filter
        - strict_content_filter
    pipeline:
      mode: pre_call
      steps:
        - guardrail: fast_content_filter
          on_pass: allow
          on_fail: next
        - guardrail: strict_content_filter
          on_pass: allow
          on_fail: block

如果 fast_content_filter 通過 → 允許。若失敗 → 執行 strict_content_filter；通過 → 允許，失敗 → 封鎖。

重試相同的 guardrail

將同一個 guardrail 作為多個步驟加入，以便在失敗時重試。適用於暫時性錯誤（API 逾時、速率限制）：

policies:
  retry-policy:
    guardrails:
      add:
        - lakera_prompt_injection
    pipeline:
      mode: pre_call
      steps:
        - guardrail: lakera_prompt_injection
          on_pass: allow
          on_fail: next
        - guardrail: lakera_prompt_injection
          on_pass: allow
          on_fail: block

第一次嘗試通過 → 允許。第一次嘗試失敗 → 重新嘗試同一個 guardrail；第二次通過 → 允許，第二次失敗 → 封鎖。

技術錯誤與政策失敗（`on_error`）

當您希望 API/基礎架構問題 與 內容政策 違規採取不同行為時，請使用 on_error。

on_fail — 當 guardrail 介入時執行（例如：偵測到有害內容、PII）。
on_error — 當步驟以錯誤結束時執行（逾時、連線失敗、guardrail 未載入等）。如果省略 on_error，錯誤結果會使用 on_fail。

範例：對不良內容封鎖，但如果主要掃描器停擺，則改用第二個 guardrail，而不是封鎖每一個請求：

policies:
  error-fallback-policy:
    guardrails:
      add:
        - primary_scanner
        - backup_scanner
    pipeline:
      mode: pre_call
      steps:
        - guardrail: primary_scanner
          on_pass: allow
          on_fail: block
          on_error: next
        - guardrail: backup_scanner
          on_pass: allow
          on_fail: block
          on_error: allow

如果 primary_scanner 發生錯誤 → 執行 backup_scanner。如果 backup_scanner 發生錯誤 → 允許該請求（若您偏好 fail-closed，請將 on_error 設為 block）。

範例：失敗時自訂回應

改為回傳品牌化訊息，而非一般性的封鎖：

policies:
  branded-block-policy:
    guardrails:
      add:
        - pii_detector
    pipeline:
      mode: pre_call
      steps:
        - guardrail: pii_detector
          on_pass: allow
          on_fail: modify_response
          modify_response_message: "Your message contains sensitive information. Please remove PII and try again."

測試管線（API）

在附加之前，先用範例訊息測試 pipeline：

curl -X POST "http://localhost:4000/policies/test-pipeline" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "mode": "pre_call",
      "steps": [
        {
          "guardrail": "pii_masking",
          "on_pass": "next",
          "on_fail": "block",
          "pass_data": true
        },
        {
          "guardrail": "prompt_injection",
          "on_pass": "allow",
          "on_fail": "block"
        }
      ]
    },
    "test_messages": [
      {"role": "user", "content": "What is 2+2?"},
      {"role": "user", "content": "My SSN is 123-45-6789"}
    ]
  }'

回應包含各步驟結果（通過/失敗/錯誤）、採取的動作，以及時間資訊。

管線與簡單 policy 的比較

當某個 policy 具有 pipeline 時，pipeline 會定義執行順序與動作。guardrails.add 清單必須包含 pipeline 步驟中使用的所有 guardrail。

Policy 類型	執行
Simple（僅 `guardrails.add`）	所有 guardrail 都會執行；任何失敗都會封鎖
Pipeline（已存在 `pipeline`）	依序執行步驟；動作控制流程

Guardrail Policies — 政策基本概念、附加、繼承
Policy Templates — 預先建立的 policy 範本

何時使用 Flow Builder​

概念​

管線​

結果：通過、失敗與錯誤​

步驟動作​

步驟選項​

使用 Flow Builder（UI）​

在 UI 中設定 guardrail 備援（逐步操作）​

設定（YAML）​

備援與重試​

guardrail 備援​

重試相同的 guardrail​

技術錯誤與政策失敗（on_error）​

範例：失敗時自訂回應​

測試管線（API）​

管線與簡單 policy 的比較​

相關文件​