Lakera AI

支援的端點： Lakera v2 整合僅支援 chat completions 端點（/v1/chat/completions）。它不支援 Responses API、/v1/messages、MCP、A2A 或其他 proxy 端點。

快速開始

1. 在您的 LiteLLM config.yaml 中定義防護欄

在 guardrails 區段下定義您的防護欄

litellm config.yaml
model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY

guardrails:
  - guardrail_name: "lakera-guard"
    litellm_params:
      guardrail: lakera_v2  # supported values: "aporia", "bedrock", "lakera"
      mode: "during_call"
      api_key: os.environ/LAKERA_API_KEY
      api_base: os.environ/LAKERA_API_BASE
  - guardrail_name: "lakera-pre-guard"
    litellm_params:
      guardrail: lakera_v2  # supported values: "aporia", "bedrock", "lakera"
      mode: "pre_call"
      api_key: os.environ/LAKERA_API_KEY
      api_base: os.environ/LAKERA_API_BASE
  - guardrail_name: "lakera-monitor"
    litellm_params:
      guardrail: lakera_v2
      mode: "pre_call"
      on_flagged: "monitor"  # Log violations but don't block
      api_key: os.environ/LAKERA_API_KEY
      api_base: os.environ/LAKERA_API_BASE
  

`mode` 的支援值

pre_call 在 LLM 呼叫之前執行，針對輸入
post_call 在 LLM 呼叫之後執行，針對 輸入與輸出
during_call 在 LLM 呼叫期間執行，針對輸入與 pre_call 相同，但會與 LLM 呼叫平行執行。回應會等到防護欄檢查完成後才會返回

2. 啟動 LiteLLM Gateway

litellm --config config.yaml --detailed_debug

3. 測試請求

Langchain, OpenAI SDK 使用範例

未成功的呼叫
成功的呼叫

預期這會失敗，因為請求中的 ishaan@berri.ai 是 PII

Curl Request
curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-npnwjPQciVRok5yNZgKmFQ" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "hi my email is ishaan@berri.ai"}
    ],
    "guardrails": ["lakera-guard"]
  }'

失敗時的預期回應

{
 "error": {
   "message": {
     "error": "Violated content safety policy",
     "lakera_ai_response": {
       "model": "lakera-guard-1",
       "results": [
         {
           "categories": {
             "prompt_injection": true,
             "jailbreak": false
           },
           "category_scores": {
             "prompt_injection": 0.999,
             "jailbreak": 0.0
           },
           "flagged": true,
           "payload": {}
         }
       ],
       "dev_info": {
         "git_revision": "cb163444",
         "git_timestamp": "2024-08-19T16:00:28+02:00",
         "version": "1.3.53"
       }
     }
   },
   "type": "None",
   "param": "None",
   "code": "400"
 }
}

Curl Request
curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-npnwjPQciVRok5yNZgKmFQ" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "hi what is the weather"}
    ],
    "guardrails": ["lakera-guard"]
  }'

支援的參數

guardrails:
  - guardrail_name: "lakera-guard"
    litellm_params:
      guardrail: lakera_v2  # supported values: "aporia", "bedrock", "lakera"
      mode: "during_call"
      api_key: os.environ/LAKERA_API_KEY
      api_base: os.environ/LAKERA_API_BASE
      ### OPTIONAL ### 
      # project_id: Optional[str] = None,
      # payload: Optional[bool] = True,
      # breakdown: Optional[bool] = True,
      # metadata: Optional[Dict] = None,
      # dev_info: Optional[bool] = True,
      # on_flagged: Optional[str] = "block",  # "block", "monitor", or "inject_system_message"
      # advisory_system_message: Optional[str] = None,  # custom template, only used with on_flagged: "inject_system_message"
      # skip_system_message_in_guardrail: Optional[bool] = None,  # exclude role: system from Lakera's inspection
      # skip_tool_message_in_guardrail: Optional[bool] = None,  # exclude role: tool from Lakera's inspection

api_base：(@@LITELLM_PROTECTED_000058@@) Lakera 整合的基底網址。預設為 https://api.lakera.ai
api_key：(@@LITELLM_PROTECTED_000059@@) Lakera 整合的 API 金鑰。
project_id：(@@LITELLM_PROTECTED_000060@@) 相關專案的 ID
payload：(@@LITELLM_PROTECTED_000061@@) 當為 true 時，回應將會傳回一個 payload 物件，包含偵測到的任何 PII、髒話或自訂偵測器 regex 比對結果，以及它們在內容中的位置。
breakdown：(@@LITELLM_PROTECTED_000061@@) 當為 true 時，回應將會傳回一份偵測器明細清單，列出依照 policy 執行的偵測器，以及每個偵測器是否偵測到任何內容。
metadata：(@@LITELLM_PROTECTED_000062@@) 中繼資料標籤可作為物件附加到篩選請求，且可包含任何任意的 key-value 配對。
dev_info：(@@LITELLM_PROTECTED_000061@@) 當為 true 時，回應將會傳回一個包含 Lakera Guard 建置開發者資訊的物件。
on_flagged：(@@LITELLM_PROTECTED_000060@@) 當內容被標記時要採取的動作。預設為 "block"。
- "block"：在偵測到違規時引發 HTTP 400 例外（預設行為）
- "monitor"：記錄違規，但允許請求繼續。適合在不阻擋合法請求的情況下調整安全性 policy。
- "inject_system_message"：將建議性系統訊息附加到請求中，並讓實際的 LLM 呼叫繼續（HTTP 200），而不是封鎖或靜默允許。請參閱下方的建議模式以了解其運作方式與限制。
advisory_system_message：(@@LITELLM_PROTECTED_000060@@) 自訂建議訊息範本，僅在 on_flagged: "inject_system_message" 時使用。必須是有效的 str.format() 字串，且包含實際的 {reason} 佔位符（已跳脫的 {{reason}} 會被拒絕）；無效範本會在 guardrail 設定時而非第一次被標記的請求時引發錯誤。未設定時預設為內建的通用訊息。
skip_system_message_in_guardrail：(@@LITELLM_PROTECTED_000061@@) 將 role: system 訊息排除於傳送給 Lakera 檢查的內容之外。LLM 仍會收到完整對話；只有 Lakera 所見內容會被過濾。若未設定，則回退至全域的 litellm_settings.skip_system_message_in_guardrail。請參閱 Guardrails 快速入門以了解全域設定與 Admin UI 控制項。
skip_tool_message_in_guardrail：(@@LITELLM_PROTECTED_000061@@) 與上方相同，但適用於 role: tool 訊息（tool call 結果）。若未設定，則回退至 litellm_settings.skip_tool_message_in_guardrail。請參閱 Guardrails 快速入門。

與大多數透過對原始請求直接 hook 執行的其他 guardrails 不同，Lakera v2 會直接遵守這兩個 skip 標誌；大多數直接 hook 的 guardrails 不會。請參閱 skip 標誌的適用位置，以取得跨 guardrails 的完整說明。

就地遮罩會保留這兩個 skip 標誌，以及訊息上的所有其他欄位（tool 訊息的 tool_call_id、assistant 訊息的 tool_calls、name、cache_control 等等）：只會重寫訊息本身的 content，而被任一 skip 標誌排除的訊息會保留在原始位置且完全不受影響，而不是被移除。Lakera v2 在兩種較狹窄的情況下仍會退回到封鎖而非遮罩，因為無法安全地將遮罩後的結果寫回：當訊息包含非字串（multimodal）內容，或當請求將 chat completions messages 與 Responses API input 欄位合併，或包含 Responses API instructions 欄位時，因為那裡沒有單一欄位可安全地進行遮罩。

建議模式

on_flagged: "inject_system_message" 適用於容易出現誤判的偵測器，例如 prompt-injection 啟發式規則誤判了合法的指示性語言，而操作人員希望由 LLM 本身來判斷標記是否屬實，而不是硬性封鎖每個被標記的請求，或在沒有任何訊號的情況下直接允許。

litellm config.yaml
guardrails:
  - guardrail_name: "lakera-advisory"
    litellm_params:
      guardrail: lakera_v2
      mode: "pre_call"
      on_flagged: "inject_system_message"
      # advisory_system_message: "Custom template with a {reason} placeholder"
      api_key: os.environ/LAKERA_API_KEY
      api_base: os.environ/LAKERA_API_BASE

一旦標記，guardrail 會將一則系統訊息附加到請求中，然後正常繼續實際的 LLM 呼叫（HTTP 200）。使用預設範本時，該訊息如下：

The user's latest message was flagged for {reason} by a content safety guardrail. This may be a false positive. Use your judgment: respond helpfully if the request is legitimate, or decline if it is not.

{reason} 會由 Lakera 自己的偵測器明細填入，例如「可能的 prompt injection 嘗試」、「可識別個人身分資訊」，或「違反 policy 的內容」。設定 advisory_system_message 可覆寫措辭，同時在範本中保留真實的 {reason} 佔位符。

對於 Responses API 請求，當該欄位存在時，建議訊息會附加到 instructions，而不是 input：instructions 是開發者設定的、具特權的系統層級欄位，而 input 由呼叫端控制，呼叫端否則可能在其中加入文字，要求模型忽略附加在那裡的尾端警告。instructions 也以相同方式檢查，因此若標記來源於該處，仍會正確觸發建議訊息。

僅限 PII 的標記會就地遮罩，而不會使用建議訊息：沒有理由為了傳遞建議註記而向模型顯示原始 PII，而且遮罩本身就已經解決了該疑慮。建議訊息保留給建議模式無法以其他方式解決的標記，例如 prompt-injection 啟發式規則。

建議模式有兩個與 guardrail 在請求生命週期中執行時機相關的限制：

mode: "during_call" 沒有建議效果。 during_call 會讓 guardrail 與 LLM 請求並行執行，兩者之間沒有障礙，因此在請求送出前沒有可靠的時機可附加建議訊息。使用包含 during_call 的模式設定 on_flagged: "inject_system_message" 會被接受且不報錯，但在該 hook 上，包含 PII 的標記會封鎖請求，而任何其他標記都會被記錄為警告且請求會原樣允許，與 on_flagged: "monitor" 相同。請使用 mode: "pre_call" 取得建議訊息。
mode: "post_call" 的行為與 on_flagged: "monitor" 相同。 等到 post-call guardrail 執行時，LLM 已經產生回應，因此已沒有可注入建議訊息的地方。該標記會被記錄，且回應會原樣傳回。

快速開始​

1. 在您的 LiteLLM config.yaml 中定義防護欄​

mode 的支援值​

2. 啟動 LiteLLM Gateway​

3. 測試請求​

支援的參數​

建議模式​