[测试版] 防护栏策略

使用策略来对护栏进行分组，并控制哪些护栏在特定的团队、密钥或模型上运行。

为什么要使用策略？

为团队、密钥或模型启用/禁用特定护栏
将护栏组合成单一策略
从现有策略继承并按需覆盖

快速入门

config.yaml
UI（LiteLLM 仪表盘）

config.yaml
model_list:
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4

# 1. Define your guardrails
guardrails:
  - guardrail_name: pii_masking
    litellm_params:
      guardrail: presidio
      mode: pre_call

  - guardrail_name: prompt_injection
    litellm_params:
      guardrail: lakera
      mode: pre_call
      api_key: os.environ/LAKERA_API_KEY

# 2. Create a policy
policies:
  my-policy:
    guardrails:
      add:
        - pii_masking
        - prompt_injection

# 3. Attach the policy
policy_attachments:
  - policy: my-policy
    scope: "*"  # apply to all requests

响应头会显示执行了哪些操作

x-litellm-applied-policies: my-policy
x-litellm-applied-guardrails: pii_masking,prompt_injection

为特定团队添加护栏

信息

✨ 企业版专属功能，支持基于团队/密钥的策略关联。获取免费试用

您拥有一个全局基准策略，但希望为特定团队添加额外的护栏。

config.yaml
UI（LiteLLM 仪表盘）

config.yaml
policies:
  global-baseline:
    guardrails:
      add:
        - pii_masking

  finance-team-policy:
    inherit: global-baseline
    guardrails:
      add:
        - strict_compliance_check
        - audit_logger

policy_attachments:
  - policy: global-baseline
    scope: "*"

  - policy: finance-team-policy
    teams:
      - finance  # team alias from /team/new

现在，finance（财务）团队将获得 pii_masking + strict_compliance_check + audit_logger，而其他所有人仅获得 pii_masking。

移除特定团队的护栏

信息

✨ 企业版专属功能，支持基于团队/密钥的策略关联。获取免费试用

您已经在全局运行了护栏，但希望为特定团队（例如内部测试）禁用部分护栏。

config.yaml
policies:
  global-baseline:
    guardrails:
      add:
        - pii_masking
        - prompt_injection

  internal-team-policy:
    inherit: global-baseline
    guardrails:
      remove:
        - pii_masking  # don't need PII masking for internal testing

policy_attachments:
  - policy: global-baseline
    scope: "*"

  - policy: internal-team-policy
    teams:
      - internal-testing  # team alias from /team/new

现在，internal-testing（内部测试）团队仅获得 prompt_injection，而其他所有人均获得两个护栏。

继承

从基础策略开始构建

config.yaml
policies:
  base:
    guardrails:
      add:
        - pii_masking
        - toxicity_filter

  strict:
    inherit: base
    guardrails:
      add:
        - prompt_injection

  relaxed:
    inherit: base
    guardrails:
      remove:
        - toxicity_filter

您将获得

base → [pii_masking, toxicity_filter]
strict → [pii_masking, toxicity_filter, prompt_injection]
relaxed → [pii_masking]

模型条件

仅对特定模型运行护栏

config.yaml
policies:
  gpt4-safety:
    guardrails:
      add:
        - strict_content_filter
    condition:
      model: "gpt-4.*"  # regex - matches gpt-4, gpt-4-turbo, gpt-4o

  bedrock-compliance:
    guardrails:
      add:
        - audit_logger
    condition:
      model:  # exact match list
        - bedrock/claude-3
        - bedrock/claude-2

关联 (Attachments)

在关联之前，策略不会生效。关联告诉 LiteLLM 在何处应用每项策略。

全局 - 在每个请求上运行

config.yaml
policy_attachments:
  - policy: default
    scope: "*"

团队特定（使用 /team/new 中的团队别名）

config.yaml
policy_attachments:
  - policy: hipaa-compliance
    teams:
      - healthcare-team  # team alias
      - medical-research  # team alias

密钥特定（使用 /key/generate 中的密钥别名，支持通配符）

config.yaml
policy_attachments:
  - policy: internal-testing
    keys:
      - "dev-*"  # key alias pattern
      - "test-*"  # key alias pattern

基于标签（通过元数据标签匹配密钥/团队，支持通配符）

config.yaml
policy_attachments:
  - policy: hipaa-compliance
    tags:
      - "healthcare"
      - "health-*"  # wildcard - matches health-team, health-dev, etc.

标签从密钥和团队的 metadata.tags 中读取。例如，创建一个 metadata: {"tags": ["healthcare"]} 的密钥将匹配上述关联。

测试策略匹配

调试特定上下文下应用的策略和护栏。在部署前使用此功能验证您的策略配置。

UI（LiteLLM 仪表盘）
API

进入 Policies（策略） > Test（测试）标签页。输入团队别名、密钥别名、模型或标签，点击 Test（测试）查看哪些策略匹配，以及将应用哪些护栏。

curl -X POST "https://:4000/policies/resolve" \
    -H "Authorization: Bearer <your_api_key>" \
    -H "Content-Type: application/json" \
    -d '{
        "tags": ["healthcare"],
        "model": "gpt-4"
    }'

响应

{
    "effective_guardrails": ["pii_masking"],
    "matched_policies": [
        {
            "policy_name": "hipaa-compliance",
            "matched_via": "tag:healthcare",
            "guardrails_added": ["pii_masking"]
        }
    ]
}

策略流构建器 (Policy Flow Builder)

如需条件执行（例如：仅当第一个护栏失败时才运行第二个护栏），请使用策略流构建器来定义带有每步通过、失败和可选错误操作 (on_pass, on_fail, on_error) 的流水线。

配置参考

`policies`（策略）

policies:
  <policy-name>:
    description: ...
    inherit: ...
    guardrails:
      add: [...]
      remove: [...]
    condition:
      model: ...
    pipeline: ...  # optional; see Policy Flow Builder

字段	类型	描述
`description`	`string`	可选。此策略的功能。
`inherit（继承）`	`string`	可选。从中继承护栏的父策略。
`guardrails.add（添加护栏）`	`list[string]（字符串列表）`	要启用的护栏。
`guardrails.remove（移除护栏）`	`list[string]（字符串列表）`	要禁用的护栏（在继承时非常有用）。
`condition.model（模型条件）`	`string` 或 `list[string]`	可选。仅在模型匹配时应用。支持正则表达式。
`pipeline（流水线）`	`对象`	可选。有序的护栏执行流程，带有每步操作（`on_pass`, `on_fail`, 可选 `on_error`）。参考策略流构建器。

`policy_attachments`（策略关联）

policy_attachments:
  - policy: ...
    scope: ...
    teams: [...]
    keys: [...]
    models: [...]
    tags: [...]

字段	类型	描述
`policy（策略）`	`string`	必填。要关联的策略名称。
`scope（范围）`	`string`	使用 `"*"` 进行全局应用。
`teams（团队）`	`list[string]（字符串列表）`	团队别名（来自 `/team/new`）。支持 `*` 通配符。
`keys（密钥）`	`list[string]（字符串列表）`	密钥别名（来自 `/key/generate`）。支持 `*` 通配符。
`models（模型）`	`list[string]（字符串列表）`	模型名称。支持 `*` 通配符。
`tags（标签）`	`list[string]（字符串列表）`	标签模式（来自密钥/团队 `metadata.tags`）。支持 `*` 通配符。

响应头

头	描述
`x-litellm-applied-policies`	匹配该请求的策略
`x-litellm-applied-guardrails`	实际运行的护栏
`x-litellm-policy-sources`	每项策略的匹配原因（例如：`hipaa=tag:healthcare; baseline=scope:*`）

工作原理

示例配置

config.yaml
policies:
  base:
    guardrails:
      add: [pii_masking]

  finance-policy:
    inherit: base
    guardrails:
      add: [audit_logger]

policy_attachments:
  - policy: base
    scope: "*"
  - policy: finance-policy
    teams: [finance]

收到请求，其 team_alias='finance'
匹配 base（通过 scope: "*"）和 finance-policy（通过 teams: [finance]）
解析护栏：base 添加了 pii_masking，finance-policy 继承并添加了 audit_logger
最终护栏：pii_masking, audit_logger

为什么要使用策略？​

快速入门​

为特定团队添加护栏​

移除特定团队的护栏​

继承​

模型条件​

关联 (Attachments)​

测试策略匹配​

策略流构建器 (Policy Flow Builder)​

配置参考​

policies（策略）​

policy_attachments（策略关联）​

响应头​

工作原理​