[测试版] 防护栏策略

使用策略来分组 Guardrail（防护栏），并控制哪些防护栏针对特定的团队、密钥或模型运行。

为什么要使用策略？

• 为团队、密钥或模型启用/禁用特定的防护栏
• 将多个防护栏归入同一个策略中
• 从现有策略继承并按需覆盖设置

快速入门

config.yaml

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

UI（LiteLLM 仪表板）

第 1 步：创建策略

前往 Policies（策略）选项卡并点击 + Create New Policy（创建新策略）。填写策略名称、描述，并选择要添加的防护栏。

响应头显示执行了哪些内容

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

为特定团队添加防护栏

信息

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

如果您已设置全局基准，但想为特定团队添加额外防护栏：

config.yaml

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

UI（LiteLLM 仪表板）

选项 1：创建团队范围的附加项

前往 Policies（策略）> Attachments（附加项）选项卡，点击 + Create New Attachment（创建新附加项）。选择策略并指定要应用的团队。

选项 2：从团队设置中附加

前往 Teams（团队） > 点击某个团队 > Settings（设置）选项卡 > 在 Policies（策略）下，选择要附加的策略。

现在，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 在哪里应用每个策略。

Global（全局） - 对每个请求运行

config.yaml

policy_attachments:
  - policy: default
    scope: "*"

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

config.yaml

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

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

config.yaml

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

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

config.yaml

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

标签从密钥和团队的 metadata.tags 读取。例如，使用 metadata: {"tags": ["healthcare"]} 创建的密钥将匹配上述附加项。

测试策略匹配

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

UI（LiteLLM 仪表板）

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

API

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)

如需条件执行（例如：仅在第一个防护栏失败时运行第二个），请使用 策略流构建器 来定义流水线，并配置各步骤的 pass（通过）、fail（失败）和可选的 error（错误）操作 (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]

1. 请求进入，携带 team_alias='finance'
2. 匹配 base（通过 scope: "*"）和 finance-policy（通过 teams: [finance]）
3. 解析防护栏：base 添加 pii_masking，finance-policy 继承并添加 audit_logger
4. 最终防护栏：pii_masking, audit_logger