# AI Lakera Guard 配置选项

ai-lakera-guard 插件通过 Lakera Guard API 筛查 AI 流量，检测请求和 LLM 响应中的提示词注入及其他不安全内容。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

该插件支持在字符串类型的配置字段中使用网关引用。使用 `$env://` 前缀引用环境变量中的值，或使用 `$secret://` 前缀引用密钥管理器中的值，例如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)。网关在运行时解析这些引用。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。有关更多信息，请参阅[插件中的环境变量](https://docs.apiseven.com/apisix/reference/environment-variables.md#plugins)和[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

* api\_key

  string

  必填

  有效值：

  非空

  ***

  用于向 Lakera Guard API 进行认证的 API Key。它会作为 Bearer Token 通过 `Authorization` 请求头发送。该值会在存储前加密。

* lakera\_endpoint

  string

  默认值：`https://api.lakera.ai/v2/guard`

  ***

  Lakera Guard v2 端点的 URL。可将其设置为指向自托管或区域化的 Lakera Guard 部署。

* project\_id

  string

  ***

  Lakera 项目 ID，其策略（检测器和阈值）将应用于本次扫描。

* direction

  string

  默认值：`input`

  有效值：

  `input`、`output` 或 `both`

  ***

  要扫描的流量。取值为 `input` 时，仅扫描请求提示词。取值为 `output` 时，仅扫描 LLM 响应（包括流式响应）。取值为 `both` 时，两者都扫描。

* action

  string

  默认值：`block`

  有效值：

  `block` 或 `alert`

  ***

  如何处理被标记的判定结果。取值为 `block` 时，请求或响应将被拒绝。取值为 `alert` 时，流量将被放行且仅记录判定结果，这在正式实施某个策略之前评估该策略时很有用。

* deny\_code

  integer

  默认值：`200`

  有效值：

  介于 200 和 599 之间（含边界值）

  ***

  拦截被标记流量时返回的 HTTP 状态码。默认值 `200` 会返回一个与提供商兼容的补全，其内容为失败消息，因此 SDK 客户端可以优雅地处理它。设置为 `4xx` 值可改为将拦截以 HTTP 错误的形式呈现。

* request\_failure\_message

  string

  默认值：`Request blocked by Lakera Guard`

  ***

  当请求提示词被标记时，在拒绝响应中返回的消息。

* response\_failure\_message

  string

  默认值：`Response blocked by Lakera Guard`

  ***

  当 LLM 响应被标记时，在拒绝响应中返回的消息。

* reveal\_failure\_categories

  boolean

  默认值：`false`

  ***

  如果为 true，将被标记的检测器类别（及其置信度）追加到失败消息中。

* fail\_open

  boolean

  默认值：`false`

  ***

  当对 Lakera Guard API 的调用失败或超时时的行为。如果为 false，流量将被拦截（失败时关闭，fail closed）。如果为 true，流量将被放行（失败时打开，fail open）。

* fail\_mode

  string

  默认值：`skip`

  有效值：

  `skip`、`warn` 或 `error`

  ***

  当请求格式未被识别为 AI 流量时（例如路由未同时配置 `ai-proxy` 或 `ai-proxy-multi`）的行为。取值为 `skip` 时，请求将不经检查直接放行。取值为 `warn` 时，请求将放行并记录一条警告日志。取值为 `error` 时，请求将以 HTTP 500 被拒绝。这些结果均不代表 Lakera 扫描成功。

* timeout

  integer

  默认值：`5000`

  有效值：

  大于或等于 1

  ***

  对 Lakera Guard API 发起请求的超时时间，单位为毫秒。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 true，验证 Lakera Guard 端点的 TLS 证书。
