一个逐一筛查请求中试图覆盖模型指令行为的 AI 网关
支持助手的用户可以输入任何内容,其中一些输入试图让模型忽略它被赋予的指令。 位于模型前面的网关可以先将每个请求发送给一个防护服务:该服务询问一个 经过训练的分类器,判断请求是否属于此类企图,若是则拒绝,并将其余请求 转发给模型。本工作区将这一部署编译为 Kubernetes manifests:网关、防护服务, 以及运行防护服务所用分类器的检测器。
请求这一能力的 Feature 是 core/prompt-injection-shield。它的作用比名称
可能暗示的更窄,本页用于说明它不做什么的篇幅与说明它做什么的篇幅相当:判定
出自一个概率分类器,它会漏掉一些攻击,也会拒绝一些合法请求,已知可以被
规避,并且它既不判断模型的回复,也不判断工具调用参数,也不判断
图像。它是与其他控制措施并列的一项控制。
本工作区不编写任何自有的目录实体。这里的三个实体文件 ——一个 Aggregate、一个 Manifest 和一个 Release——就是任何人需要 编写的全部内容。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
router | core/gateway/litellm | AI 网关:在其模型映射中写入一个别名 assistant,指向位于防护服务之后的模型 |
guard | core/security/nemo-guardrails | 位于模型路径中的 NVIDIA NeMo Guardrails 服务器,它检查每个聊天请求,并将其放行的请求转发给模型 |
detector | core/security/trustyai-huggingface-detector | 防护服务所询问的分类器服务,运行其默认的提示注入分类器 |
两条 uses 边:网关的 guard 插槽指向防护服务,防护服务的
detector 插槽指向检测器。两个 Feature 挂载:shield,即该
防护盾,挂载在网关上,设为 sensitivity: standard;以及 upstream_key,即防护服务向模型 API 出示的
凭据,挂载在防护服务上。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example ai-gateway-prompt-injection-shield然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd ai-gateway-prompt-injection-shield构建
aggrega build --release release.yaml --auto-pullrelease 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build此工作区从 .aggrega-config.yaml 指定的默认注册表解析目录实体。shield 的实现会运行一个既不随编译器也不随目录提供的插件,即网关配置步骤 pipeline-step/litellm-gateway-config,解析过程会从 default_registry 指定的注册表 hub.aggrega.ai 获取它。
构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
[… omitted: a line reporting on the gateway configuration step's plugin, a warning that the upstream_key credential's declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 10 files written to <workspace>/distRelease 指定了 guard 和 detector 的镜像,因为目录对两者都未指定。 每个 Component 的 infra.image 都是没有默认值的必填设置;Component 中它旁边的注释说明了原因,并指出了验证其行为时所用的构建版本。release.yaml 中的两个值是占位符,应替换为你所运行构建的副本,并镜像到你控制的注册表中。构建会原样传递其中的任何字符串;请在部署前替换这两个值。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `ai-gateway-prompt-injection-shield` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `ai-gateway-prompt-injection-shield`,且不提供 `dir`:它会把示例写入一个新的 `ai-gateway-prompt-injection-shield` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `ai-gateway-prompt-injection-shield`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `ai-gateway-prompt-injection-shield/dist/` 下。渲染出的目录树
dist/helm/├── detector-default-service.yaml├── detector-deployment.yaml├── guard--upstream-zukey--guard-secret-guard-upstream-key.yaml├── guard-default-service.yaml├── guard-deployment.yaml├── guard/│ └── nemo-guardrails-config.configmap.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yaml该防护层本身不带任何文件。它的作用被写入了 网关的配置中。
网关所读取的路由
网关的配置主体,即
dist/helm/router/litellm-gateway-config/configmap.yaml 中的 config.yaml 键:
model_list: - model_name: assistant litellm_params: model: openai/gpt-4o-mini api_base: "http://guard-default:8000/v1" api_key: "the-guard-holds-the-upstream-credential"litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filtercallback_settings: request_field_filter.router-shield: policies: - reason: "sends every model request through a prompt-injection guard, which checks chat completions only" served_request_types: - acompletion从中可以读出三点。
每个别名都指向守卫。 api_base 是守卫发布的端点,从 guard 边读取,因此对 assistant 的请求会通过 OpenAI API 发往守卫,
请求 gpt-4o-mini;守卫将其放行的请求转发到 release.yaml 在其 upstream_endpoint 中指定的模型 API。移除
该防护后,条目写出时不带 api_base,与之前完全相同。这就是为什么别名是写入网关的 values.models,而不是由连接到其 models 插槽的模型提供:连接的模型的条目会以
该模型自己的端点及其连接自己的密钥写出,因此其请求会绕过守卫直接发往模型,而该防护会拒绝这样的连接,见
下文。
网关不持有模型的凭据。 条目在密钥的位置写入一个固定的词,
因为网关访问的是守卫而非
提供方,而守卫出示自己的凭据,即附加到其
upstream_key 槽位的凭据。调用方自己的 Authorization 标头永远不会到达
模型。
只提供聊天补全服务。 守卫检查聊天补全, 不提供 completions、embeddings、responses 或 messages 路由,因此该策略 让网关的请求守卫在转发任何内容之前,以 HTTP 400 拒绝其他所有类型的请求,并说明原因:
This gateway sends every model request through a prompt-injection guard, which checks chat completions only, and it does not serve embeddings requests while it does, so the request was not forwarded. It serves chat completions requests.防护层做什么
防护层的配置,即
dist/helm/guard/nemo-guardrails-config.configmap.yaml 中的 config.yaml 键,从其 rails 部分开始:
rails: config: hf_classifier: prompt_injection: engine: fms model: "protectai/deberta-v3-base-prompt-injection-v2" base_url: "http://detector-default:8000" threshold: 0.5 blocked_labels: ["INJECTION"] input: flows: - hf classifier check input $classifier=prompt_injection对于每个聊天请求,无论是普通请求还是流式请求,防护层都会把最新的用户
消息发送给检测器,检测器用其加载的分类器为消息打分;当检测器报告 INJECTION 的分数达到或超过 0.5 时,防护层拒绝该请求。被
拒绝的请求由防护层自己应答,返回一个普通的补全,其消息为 I’m sorry, I can’t respond to that.——请求要求流式输出时以流式返回——请求的任何内容都不会到达模型。防护层
放行的请求按调用方发送的原样到达模型,包括其系统消息和
之前的对话轮次。
调用方无法通过请求关闭检查。防护层的
配置带有一个流程 rails.co,无论请求
体要求什么,它都会运行检查;防护层只运行这一份配置,并拒绝
指定其他配置的请求。在这个网关上,guardrails 字段属于网关自身,
不会被转发;网关未配置转发的字段,例如
extra_body,会被拒绝。
它不做什么
- **它会漏掉一些攻击,也会拒绝一些合法请求。**判定结果 是分类器的评分与阈值的比较。经过改写、用另一种语言书写、经过编码或改换拼写的尝试 可能得分很低而被放行;普通请求也可能得分很高而被拒绝。
- **它只读取最新的用户消息。**放在系统 消息、先前轮次或工具结果中的尝试会未经读取地到达模型。
- 它不评判模型的回复、工具调用参数或图像。
- **它只覆盖经过网关的流量。**直接调用 模型地址的工作负载会绕过它。guard 和检测器 不对任何调用方进行身份验证,因此它们的 Services 是供调用它们的组件使用的地址,而不是用于对外发布的地址。
灵敏度
standard 和 strict 作为 guard 的阈值运行:0.5 和 0.001。
这两个数值是针对检测器的默认分类器测得的,该分类器的
分数接近 0 或接近 1。在 0.5 时,guard 会拒绝直白地试图
覆盖模型指令的请求。在 0.001 时,它还会拒绝以 leetspeak 改写拼写的此类尝试
(分类器对其评分约为 0.008),同时也会拒绝
一些分类器评分较低但并不接近零的普通请求。
阈值是 guard 自身的值,因此切换到 strict 需要同时进行两处
修改:在 attachment 上设置 sensitivity: strict,并在
guard 的 values 中设置 threshold: 0.001。realization 会检查两者是否一致。它只能看到 guard,
看不到其后的检测器,因此无法判断检测器
加载了哪个模型;运行其他模型的检测器评分会有所不同,其阈值
需要重新测定。
什么会中止构建
以下每一项都是构建打印的一句话,指明需要修改什么:
-
sensitivity 与 guard 的阈值不一致。 设置
sensitivity: strict,并让 guard 保持默认值:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0010] instance routernode "router": pipeline step failed[… omitted: the step, the template position and the template's own source]error calling fail: core/prompt-injection-shield attachment "shield" on "router" asks for sensitivity strict, which this realization runs as the guard's threshold 0.001, but the guard "guard" runs at 0.5; set values.threshold of "guard" to 0.001 -
未连接 guard。 移除网关的
uses块(其中只有guard边),构建会在任何内容渲染之前中止,并指明该插口:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "prompt-injection-shield-litellm" instance "router" assertion "guard_is_wired": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/prompt-injection-shield attachment "shield" on "router" needs a guard to send the gateway's model requests through, but nothing is wired to its guard socket; wire a core/security/nemo-guardrails to the guard socket of "router" -
连接到网关
models插口的模型。 它的条目会绕过 guard,使用其连接自身的密钥发送到该模型自己的端点。将一个core/ai-model/openai以fast连接到该插口,在连接上带一个凭据,与类型化别名并列——设置values.model: assistant(因为此时网关提供两个别名而只发布一个),并在 Release 中指明fast、在 Manifest 中指明其 Recipe——构建会在任何内容渲染之前中止,并指明该连接:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "prompt-injection-shield-litellm" instance "router" assertion "no_wired_models": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/prompt-injection-shield attachment "shield" on "router" sends every model request through the guard, which forwards it to its own upstream with its own credential, but the models socket of "router" holds fast, each sent to its own model's endpoint with its own connection's credential, past the guard; remove those connections and reach that model through the guard's upstream, or remove the shield attachment -
网关
provider_key槽位上的凭据。 它会被提供给 guard,而不提供给任何模型;构建会改为指明 guard 的upstream_key槽位。 -
另一个 guard。 该 socket 接受任何其提示词防护为训练好的分类器的 component, 而 realization 对除
core/security/nemo-guardrails之外的任何 guard 都会中止,因为两个 sensitivity 正是基于它测定的—— 对连接到该 socket 的第二个 guard 也会中止。 -
未写成
openai/<model>的目标,网关会通过另一种 API 将其发往 guard。 -
同一网关上的
core/semantic-caching。 该缓存通过映射中的一个别名嵌入每个提示词, 而该别名会被发送到 guard,guard 不响应任何 embeddings 请求;缓存将什么都不缓存。 -
网关上的第二个防护。
当 guard 或检测器无法访问时
请求会被拒绝,不会有任何内容到达模型。检测器宕机时,guard 对普通请求返回一个报告内部错误的补全结果,对流式请求返回一个不含任何文本的流。guard 宕机时,网关返回错误。此配置中没有任何部分会在 guard 失败时绕过它发送请求。
编译器不做解释的地方
编译器将 guard 的 Service 名称和端口传入网关的配置,并将阈值和检测器的地址传入 guard 的配置,均以字符串形式传递。它不评估提示词,不知道分类器会给出什么分数,也不会联系 guard、检测器或模型。上文的每一种中止都由目录自身的实体声明,或是 shield 的实现中的断言,或是其流水线步骤中的检查,没有一项依赖于对流量的任何理解。
改编示例
- 更严格。 在挂载上设置
sensitivity: strict,同时在 guard 上设置threshold: 0.001。 - 自行运行的模型。 将 guard 的
upstream_endpoint指向模型服务器的端点(core/ai-model/vllm会发布一个), 并将别名的目标写为openai/<the name that server serves>。 - 改用 NGINX 网关。
core/gateway/nginx声明了同样的guard套接字,prompt-injection-shield-nginx在 helm 和 compose 上都将其唯一的 location 指向 guard, 以取代其上游。将 guard 的upstream_endpoint设置为网关的upstream套接字所指定的模型。该 location 上的每个 请求都会发往 guard,guard 处理 chat completions,对其他模型路由则返回 404。