OpenAI Moderation

概觀

屬性	詳細資訊
說明	使用 OpenAI 內建的 Moderation API 偵測並封鎖有害內容，包括仇恨言論、騷擾、自殘、性內容與暴力。
提供者	OpenAI Moderation API
Supported Actions	`BLOCK`（偵測到違規時會擲出 HTTP 400 例外）
支援的模式	`pre_call`、`during_call`、`post_call`
Streaming Support	✅ 完整支援串流回應
API Requirements	OpenAI API 金鑰

快速開始

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

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

Config.yaml
環境變數

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

guardrails:
  - guardrail_name: "openai-moderation-pre"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY  # Optional if already set globally
      model: "omni-moderation-latest"     # Optional, defaults to omni-moderation-latest
      api_base: "https://api.openai.com/v1"  # Optional, defaults to OpenAI API

`mode` 的支援值

pre_call 在 LLM 呼叫前 執行，針對 使用者輸入
during_call 在 LLM 呼叫期間 執行，針對 使用者輸入。與 pre_call 相同，但會與 LLM 呼叫平行執行。直到防護欄檢查完成前不會回傳回應。
post_call 在 LLM 呼叫後 執行，針對 LLM 回應

支援的 OpenAI Moderation 模型

omni-moderation-latest（預設）- 最新多模態 moderation 模型
text-moderation-latest - 最新純文字 moderation 模型

設定您的 OpenAI API 金鑰：

Setup Environment Variables
export OPENAI_API_KEY="your-openai-api-key"

2. 啟動 LiteLLM 閘道

litellm --config config.yaml --detailed_debug

3. 測試請求

被封鎖的請求
成功的呼叫

由於請求包含有害內容，預期這會失敗：

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-1234" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "I hate all people and want to hurt them"}
    ],
    "guardrails": ["openai-moderation-pre"]
  }'

失敗時的預期回應：

{
  "error": {
    "message": {
      "error": "Violated OpenAI moderation policy",
      "moderation_result": {
        "violated_categories": ["hate", "violence"],
        "category_scores": {
          "hate": 0.95,
          "violence": 0.87,
          "harassment": 0.12,
          "self-harm": 0.01,
          "sexual": 0.02
        }
      }
    },
    "type": "None",
    "param": "None", 
    "code": "400"
  }
}

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-1234" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "guardrails": ["openai-moderation-pre"]
  }'

預期回應：

{
  "id": "chatcmpl-4a1c1a4a-3e1d-4fa4-ae25-7ebe84c9a9a2",
  "created": 1741082354,
  "model": "gpt-4",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The capital of France is Paris.",
        "role": "assistant"
      }
    }
  ],
  "usage": {
    "completion_tokens": 8,
    "prompt_tokens": 13,
    "total_tokens": 21
  }
}

進階組態

輸入與輸出的多重防護欄

您可以為使用者輸入與 LLM 回應分別設定防護欄：

Multiple Guardrails Config
guardrails:
  - guardrail_name: "openai-moderation-input" 
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY
      
  - guardrail_name: "openai-moderation-output"
    litellm_params:
      guardrail: openai_moderation
      mode: "post_call" 
      api_key: os.environ/OPENAI_API_KEY

自訂 API 組態

設定自訂 OpenAI API 端點或不同模型：

Custom API Config
guardrails:
  - guardrail_name: "openai-moderation-custom"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY
      api_base: "https://your-custom-openai-endpoint.com/v1"
      model: "text-moderation-latest"

串流支援

OpenAI Moderation 防護欄完整支援串流回應。當以 post_call 模式使用時，將會：

收集所有串流區塊
組裝完整回應
對完整內容套用 moderation
若偵測到違規，封鎖整個串流
若內容安全，回傳原始串流

Streaming Config
guardrails:
  - guardrail_name: "openai-moderation-streaming"
    litellm_params:
      guardrail: openai_moderation
      mode: "post_call"  # Works with streaming responses
      api_key: os.environ/OPENAI_API_KEY

內容類別

OpenAI Moderation API 會偵測以下有害內容類別：

Category	說明
`hate`	表達、煽動或宣揚基於種族、性別、族裔、宗教、國籍、性傾向、身心障礙狀態或種姓的仇恨內容
`harassment`	騷擾、霸凌或恐嚇個人的內容
`self-harm`	宣揚、鼓勵或描繪自殘行為的內容
`sexual`	意圖引發性興奮或推廣性服務的內容
`violence`	描繪死亡、暴力或身體傷害的內容

每個類別都會以布林旗標與信心分數（0.0 到 1.0）進行評估。

錯誤處理

當內容違反 OpenAI 的 moderation 政策時：

HTTP 狀態：400 Bad Request
錯誤類型：HTTPException
錯誤詳情：包含違規類別與信心分數
行為：請求會立即被封鎖

最佳實務

1. 對使用者輸入使用前置呼叫

guardrails:
  - guardrail_name: "input-moderation"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"  # Block harmful user inputs early

2. 對 LLM 回應使用後置呼叫

guardrails:
  - guardrail_name: "output-moderation"
    litellm_params:
      guardrail: openai_moderation  
      mode: "post_call"  # Ensure LLM responses are safe

3. 與其他防護欄結合

guardrails:
  - guardrail_name: "openai-moderation"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      
  - guardrail_name: "custom-pii-detection"
    litellm_params:
      guardrail: presidio
      mode: "pre_call"

疑難排解

常見問題

無效的 API 金鑰：請確認您的 OpenAI API 金鑰已正確設定
```
export OPENAI_API_KEY="sk-your-actual-key"
```
速率限制：OpenAI Moderation API 有速率限制。在高流量情境下請監控用量。
網路問題：請驗證與 OpenAI API 端點的連線。

除錯模式

啟用詳細記錄以疑難排解問題：

litellm --config config.yaml --detailed_debug

請尋找以 OpenAI Moderation: 開頭的記錄，以追蹤防護欄執行流程。

API 成本

OpenAI Moderation API 對於內容政策合規而言是免費使用。與其他商業 moderation 服務相比，這使它成為具成本效益的防護欄選項。

需要協助嗎？

如需額外支援：

概觀​

快速開始​

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

mode 的支援值​

支援的 OpenAI Moderation 模型​

2. 啟動 LiteLLM 閘道​

3. 測試請求​

進階組態​

輸入與輸出的多重防護欄​

自訂 API 組態​

串流支援​

內容類別​

錯誤處理​

最佳實務​

1. 對使用者輸入使用前置呼叫​

2. 對 LLM 回應使用後置呼叫​

3. 與其他防護欄結合​

疑難排解​

常見問題​

除錯模式​

API 成本​

需要協助嗎？​

概觀