Um gateway de IA que examina cada requisição em busca de uma tentativa de sobrepor o modelo
Os usuários de um assistente de suporte podem digitar qualquer coisa, e parte do que digitam tenta fazer o modelo ignorar as instruções que recebeu. O gateway na frente do modelo pode enviar cada requisição primeiro por uma guarda: um serviço que pergunta a um classificador treinado se a requisição é uma tentativa desse tipo, a recusa se for o caso e encaminha o resto ao modelo. Este workspace compila esse arranjo para manifestos do Kubernetes: o gateway, a guarda e o detector em que o classificador da guarda é executado.
A Feature que o solicita é core/prompt-injection-shield. O que ela faz é mais restrito do que o nome pode sugerir, e esta página dedica tanto espaço ao que ela não faz quanto ao que faz: o veredito é o de um classificador probabilístico, ela deixa passar alguns ataques e recusa algumas requisições legítimas, sabe-se que pode ser burlada, e não julga nem a resposta do modelo, nem os argumentos de chamadas de ferramentas, nem imagens. É um controle ao lado de outros.
Este workspace não cria nenhuma entidade de catálogo própria. Os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
router | core/gateway/litellm | o gateway de IA: um alias, assistant, digitado no seu mapa de modelos e apontando para um modelo atrás da guarda |
guard | core/security/nemo-guardrails | o servidor do NVIDIA NeMo Guardrails no caminho do modelo, que verifica cada requisição de chat e encaminha ao modelo o que admite |
detector | core/security/trustyai-huggingface-detector | o serviço classificador que a guarda consulta, executando o seu classificador padrão de injeção de prompt |
Duas arestas uses: o socket guard do gateway para a guarda, e o socket detector da guarda para o detector. Duas vinculações de Feature: shield, o escudo, no gateway, com sensitivity: standard; e upstream_key, a credencial que a guarda apresenta à API do modelo, na guarda.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example ai-gateway-prompt-injection-shieldEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd ai-gateway-prompt-injection-shieldBuild
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia. A realização do escudo executa um plugin que não vem nem no compilador nem no catálogo, a etapa de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução obtém do registro que default_registry nomeia, hub.aggrega.ai.
O build imprime, com <workspace> representando a pasta deste exemplo:
[… 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>/distA Release nomeia as imagens da guarda e do detector, porque o catálogo não nomeia nenhuma das duas. O infra.image de cada Component é uma configuração obrigatória sem padrão; o comentário ao lado dele no Component diz por quê, e nomeia a versão em que o seu comportamento foi comprovado. Os dois valores em release.yaml são marcadores de posição para uma cópia da versão que você executa, espelhada em um registro que você controla. O build canaliza qualquer string que esteja ali; substitua os dois antes de implantar.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `ai-gateway-prompt-injection-shield`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-gateway-prompt-injection-shield` e sem `dir`: ela escreve o exemplo em uma nova pasta `ai-gateway-prompt-injection-shield`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ai-gateway-prompt-injection-shield`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `ai-gateway-prompt-injection-shield/dist/`.A árvore renderizada
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.yamlO escudo não traz nenhum arquivo próprio. O que ele faz é escrito na configuração do gateway.
A rota, como o gateway a lê
O corpo de configuração do gateway, a chave config.yaml de dist/helm/router/litellm-gateway-config/configmap.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: - acompletionVale a pena ler três coisas nele.
Todo alias é endereçado à guarda. api_base é o endpoint que a guarda publica, lido da aresta guard, então uma requisição para assistant vai para a guarda pela API da OpenAI, pedindo gpt-4o-mini; a guarda encaminha o que admite para a API do modelo que release.yaml nomeia no seu upstream_endpoint. Remova o escudo e a entrada é escrita sem api_base, exatamente como antes. É por isso que o alias é digitado nos values.models do gateway em vez de servido por um modelo ligado ao seu socket models: a entrada de um modelo ligado é escrita com o endpoint próprio desse modelo e a chave própria da sua conexão, então as suas requisições iriam ao modelo passando ao largo da guarda, e o escudo recusa uma conexão desse tipo, como mostrado abaixo.
O gateway não detém nenhuma credencial para o modelo. A entrada nomeia uma palavra fixa no lugar de uma chave, porque o gateway alcança a guarda e não o provedor, e a guarda apresenta a sua própria credencial, a vinculada ao seu slot upstream_key. O cabeçalho Authorization próprio de um chamador nunca chega ao modelo.
Apenas chat completions são servidas. A guarda verifica chat completions e não serve nenhuma rota de completions, embeddings, responses ou messages, então a política faz a guarda de requisições do gateway recusar qualquer outro tipo de requisição com HTTP 400, dizendo por quê, antes que qualquer coisa seja encaminhada:
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.O que a guarda faz
A configuração da guarda, a chave config.yaml de dist/helm/guard/nemo-guardrails-config.configmap.yaml, dos seus rails em diante:
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_injectionPara cada requisição de chat, simples ou em streaming, a guarda envia a última mensagem do usuário ao detector, que a pontua com o classificador que carregou, e recusa a requisição quando o detector relata INJECTION em 0.5 ou acima. Uma requisição recusada é respondida pela própria guarda, com uma completion comum cuja mensagem é I’m sorry, I can’t respond to that. (Sinto muito, não posso responder a isso.) — em streaming quando a requisição pediu um stream — e nada dela chega ao modelo. Uma requisição que ela admite chega ao modelo como o chamador a enviou, incluindo a sua mensagem de sistema e os turnos anteriores.
Um chamador não pode desligar a verificação pela requisição. A configuração da guarda traz um flow, rails.co, que executa a verificação seja o que for que um corpo de requisição peça, e a guarda executa essa única configuração e recusa uma requisição que nomeie outra. Neste gateway, um campo guardrails é do próprio gateway e não é encaminhado, e um campo que o gateway não foi configurado para encaminhar, como extra_body, é recusado.
O que ela não faz
- Ela deixa passar alguns ataques e recusa algumas requisições legítimas. O veredito é a pontuação de um classificador comparada a um limite. Uma tentativa reformulada, escrita em outro idioma, codificada ou com a grafia alterada pode ter pontuação baixa e ser servida; uma requisição comum pode ter pontuação alta e ser recusada.
- Ela lê apenas a última mensagem do usuário. Uma tentativa colocada em uma mensagem de sistema, em um turno anterior ou no resultado de uma ferramenta chega ao modelo sem ser lida.
- Ela não julga a resposta do modelo, nem argumentos de chamadas de ferramentas ou imagens.
- Ela cobre apenas o tráfego que atravessa o gateway. Uma carga de trabalho que chama diretamente o endereço do modelo passa ao largo dela. A guarda e o detector não autenticam nenhum chamador, então os seus Services são endereços para os componentes que os chamam, não endereços para publicar.
Sensibilidade
standard e strict são aplicados como o limite da guarda: 0.5 e 0.001. Esses dois números são medidos para o classificador padrão do detector, cujas pontuações ficam perto de 0 ou perto de 1. Com 0.5 a guarda recusa tentativas simples de sobrepor as instruções do modelo. Com 0.001 ela também recusa uma tentativa desse tipo reescrita em leetspeak, que o classificador pontua perto de 0.008, e junto com ela algumas requisições comuns que o classificador pontua baixo, mas não perto de zero.
O limite é um valor próprio da guarda, então passar para strict são duas edições feitas juntas: sensitivity: strict na vinculação, e threshold: 0.001 nos values da guarda. A realização verifica se os dois concordam. Ela vê a guarda e não o detector por trás dela, então não consegue saber qual modelo o detector carregou; um detector que executa outro modelo pontua de forma diferente, e os seus limites são medidos de novo.
O que interrompe o build
Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:
-
A sensibilidade e o limite da guarda não concordam. Defina
sensitivity: stricte deixe a guarda no seu padrão:[… 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 -
Nenhuma guarda ligada. Remova o bloco
usesdo gateway, que contém apenas a arestaguard, e o build é interrompido antes que qualquer coisa seja renderizada, nomeando o socket:[… 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" -
Um modelo ligado ao socket
modelsdo gateway. A sua entrada seria enviada ao endpoint próprio desse modelo com a chave própria da sua conexão, passando ao largo da guarda. Ligue umcore/ai-model/openaiao socket comofast, com uma credencial na conexão, ao lado do alias digitado — definindovalues.model: assistant, já que o gateway passa a servir dois aliases e publicar um, e nomeandofastna Release e a sua Recipe no Manifest — e o build é interrompido antes que qualquer coisa seja renderizada, nomeando a conexão:[… 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 -
Uma credencial no slot
provider_keydo gateway. Ela seria apresentada à guarda e a nenhum modelo; o build nomeia em vez disso o slotupstream_keyda guarda. -
Outra guarda. O socket admite qualquer componente cuja guarda de prompts seja a de um classificador treinado, e a realização é interrompida em qualquer um que não seja
core/security/nemo-guardrails, aquele em que as suas duas sensibilidades foram medidas — e também em uma segunda guarda ligada ao socket. -
Um destino não escrito como
openai/<model>, que o gateway endereçaria à guarda por outra API. -
core/semantic-cachingno mesmo gateway. O cache gera o embedding de cada prompt por um alias do mapa, que seria enviado à guarda, que não responde a nenhuma requisição de embeddings; o cache não armazenaria nada. -
Um segundo escudo no gateway.
Quando a guarda ou o detector não pode ser alcançado
A requisição é recusada, e nada chega ao modelo. Com o detector fora do ar, a guarda responde a uma requisição simples com uma completion que relata um erro interno e a uma em streaming com um stream sem nenhum texto. Com a guarda fora do ar, o gateway responde com um erro. Nada nesta configuração envia uma requisição passando ao largo da guarda quando ela falha.
Onde o compilador não interpreta
O compilador canaliza o nome do Service e a porta da guarda para a configuração do gateway, e o limite e o endereço do detector para a da guarda, como strings. Ele não avalia nenhum prompt, não sabe que pontuação o classificador vai dar, e não contata nem a guarda, nem o detector, nem o modelo. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização do escudo ou uma verificação na sua etapa de pipeline, e nenhuma delas se apoia em qualquer compreensão do tráfego.
Adaptando-o
- Mais rigoroso. Defina
sensitivity: strictna vinculação ethreshold: 0.001na guarda, juntos. - Um modelo que você mesmo executa. Aponte o
upstream_endpointda guarda para o endpoint do servidor do modelo —core/ai-model/vllmpublica um — e escreva o destino do alias comoopenai/<the name that server serves>. - Um gateway NGINX em vez disso.
core/gateway/nginxdeclara o mesmo socketguard, eprompt-injection-shield-nginx, no helm e no compose, aponta a sua única location para a guarda no lugar do seu upstream. Defina oupstream_endpointda guarda como o modelo que o socketupstreamdo gateway nomeia. Toda requisição nessa location vai para a guarda, que serve chat completions e responde 404 às outras rotas de modelo.