--- title: "Lakera AI" url: "/docs/proxy/guardrails/lakera_ai" canonical_url: "https://docs.litellm.ai/docs/proxy/guardrails/lakera_ai" type: "docs" last_updated: "2026-10-08" related: - "/docs/proxy/guardrails/javelin" - "/docs/proxy/guardrails/lasso_security" --- # Lakera AI > Index of all LiteLLM docs: https://docs.litellm.ai/llms.txt **支援的端點：** Lakera v2 整合僅支援 **chat completions** 端點（`/v1/chat/completions`）。它不支援 Responses API、`/v1/messages`、MCP、A2A 或其他 proxy 端點。 ## 快速開始 {#quick-start} ### 1. 在您的 LiteLLM config.yaml 中定義防護欄 {#1-define-guardrails-on-your-litellm-configyaml} 在 `guardrails` 區段下定義您的防護欄 ```yaml showLineNumbers title="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` 的支援值 {#supported-values-for-mode} - `pre_call` 在 LLM 呼叫之前執行，針對 **輸入** - `post_call` 在 LLM 呼叫之後執行，針對 **輸入與輸出** - `during_call` 在 LLM 呼叫期間執行，針對 **輸入** 與 `pre_call` 相同，但會與 LLM 呼叫平行執行。回應會等到防護欄檢查完成後才會返回 ### 2. 啟動 LiteLLM Gateway {#2-start-litellm-gateway} ```shell litellm --config config.yaml --detailed_debug ``` ### 3. 測試請求 {#3-test-request} **[Langchain, OpenAI SDK 使用範例](/docs/proxy/user_keys#request-format)** **未成功的呼叫** 預期這會失敗，因為請求中的 `ishaan@berri.ai` 是 PII ```shell showLineNumbers title="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"] }' ``` 失敗時的預期回應 ```shell { "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" } } ``` **成功的呼叫 ** ```shell showLineNumbers title="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"] }' ``` ## 支援的參數 {#supported-params} ```yaml 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-mode) 以了解其運作方式與限制。 - `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 快速入門](./quick_start#skip-system-messages-in-guardrail-evaluation) 以了解全域設定與 Admin UI 控制項。 - `skip_tool_message_in_guardrail`：(@@LITELLM_PROTECTED_000061@@) 與上方相同，但適用於 `role: tool` 訊息（tool call 結果）。若未設定，則回退至 `litellm_settings.skip_tool_message_in_guardrail`。請參閱 [Guardrails 快速入門](./quick_start#skip-tool-messages-in-guardrail-evaluation)。 與大多數透過對原始請求直接 hook 執行的其他 guardrails 不同，Lakera v2 會直接遵守這兩個 skip 標誌；大多數直接 hook 的 guardrails 不會。請參閱 [skip 標誌的適用位置](./quick_start#where-the-skip-flags-apply)，以取得跨 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` 欄位時，因為那裡沒有單一欄位可安全地進行遮罩。 ## 建議模式 {#advisory-mode} `on_flagged: "inject_system_message"` 適用於容易出現誤判的偵測器，例如 prompt-injection 啟發式規則誤判了合法的指示性語言，而操作人員希望由 LLM 本身來判斷標記是否屬實，而不是硬性封鎖每個被標記的請求，或在沒有任何訊號的情況下直接允許。 ```yaml showLineNumbers title="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 已經產生回應，因此已沒有可注入建議訊息的地方。該標記會被記錄，且回應會原樣傳回。 ## Related pages - [Javelin 防護欄](https://docs.litellm.ai/docs/proxy/guardrails/javelin.md) - [Lasso Security](https://docs.litellm.ai/docs/proxy/guardrails/lasso_security.md)