Para integrar LLM Guard a um pipeline RAG, examine separadamente a pergunta e os trechos recuperados antes de enviá-los ao modelo. Use o resultado dos scanners para tomar uma decisão explícita: aceitar, colocar o documento em quarentena ou interromper a resposta. Um detector instalado, mas cujo resultado é ignorado pela aplicação, não muda o comportamento do sistema.
O recorte aqui é a implementação dessa barreira em recuperação de documentos. RAG significa geração apoiada por busca: o sistema seleciona textos para fornecer contexto ao modelo. Esses textos podem conter instruções maliciosas. A avaliação mais ampla de ataques está no guia de testes contra injeção de prompt; abaixo, a questão é onde conectar o scanner e como tratar seus retornos.
Resumo rápido
- Escaneie conteúdo recuperado, não apenas a mensagem do usuário.
- Preserve identificador e origem de cada trecho analisado.
- PromptInjection sinaliza suspeita; não deve ser tratado como removedor automático de ataques.
- Defina o comportamento para bloqueio, falha técnica e ausência de evidência.
- Valide o detector com português e documentos do seu domínio.
Onde posicionar os scanners no fluxo
Uma arquitetura prática tem duas barreiras de entrada. A primeira verifica a pergunta recebida. A segunda examina os fragmentos retornados pela busca antes da montagem do contexto. Se a aplicação acrescentar textos depois dessa etapa, como respostas de ferramentas ou páginas externas, eles também precisam de uma decisão de confiança.
A documentação oficial do scanner PromptInjection inclui RAG entre os cenários de injeção indireta e desaconselha aplicar o detector ao prompt de sistema. A separação proposta facilita localizar qual conteúdo externo causou a sinalização, sem misturá-lo às instruções legítimas da aplicação.
Faça o controle de acesso documental antes de recuperar conteúdo para o usuário. O scanner não verifica se uma pessoa pode ler determinado contrato. Um texto sem instruções maliciosas ainda pode ser confidencial. O artigo sobre controle de acesso a documentos com RBAC cobre esse problema complementar.
Se houver preparação na ingestão, mantenha uma análise também no momento do uso. A verificação antecipada ajuda a revisar documentos, mas não cobre automaticamente novas fontes, mudanças no extrator ou conteúdo produzido por ferramentas. Registre a versão que passou pela análise para evitar confundir um arquivo antigo aprovado com outro atualizado.
| Momento | Objeto analisado | Decisão da aplicação |
|---|---|---|
| Recepção | Pergunta externa | Prosseguir ou responder com orientação segura |
| Após recuperação | Cada trecho documental | Manter, colocar em quarentena ou interromper |
| Montagem | Conjunto autorizado de evidências | Verificar se há informação suficiente |
| Saída | Resposta produzida | Liberar, mascarar conforme política ou reter |
Entenda o retorno antes de escrever a política
O código de PromptInjection retorna texto, indicador de validade e pontuação de risco. Nesse scanner, o texto retornado permanece o original, inclusive quando há detecção. Portanto, chamar a variável de “texto sanitizado” não prova que uma instrução perigosa foi removida.
Na composição de scanners, scan_prompt retorna o texto processado e dicionários de resultados e pontuações. A opção fail_fast interrompe a sequência na primeira reprovação. Ela não bloqueia por conta própria a chamada seguinte ao modelo; esse desvio de fluxo deve existir no seu código.
Trate a pontuação como sinal do mecanismo escolhido, sem convertê-la em probabilidade universal de ataque. Um limiar útil depende dos exemplos benignos e suspeitos do domínio. A avaliação operacional deve olhar o efeito da decisão: quantos textos legítimos foram retidos e quantas tentativas conhecidas atravessaram a barreira.
Há também uma diferença entre rejeição e erro técnico. Um retorno indicando conteúdo inválido é uma decisão do detector. Falta de memória, dependência indisponível e exceção durante a análise são execuções incompletas. Registre os dois estados de forma distinta e defina antecipadamente a resposta permitida para cada um.
Um adaptador mínimo para trechos recuperados
O exemplo seguinte mostra somente a barreira entre busca e geração. Ele usa identificadores fictícios e lança uma exceção quando um trecho é sinalizado. A aplicação chamadora deve capturar essa condição, registrar metadados mínimos e produzir o encaminhamento definido. O código não inclui banco vetorial, modelo gerador ou configuração de infraestrutura.
from llm_guard.input_scanners import PromptInjection
from llm_guard.input_scanners.prompt_injection import MatchType
scanner = PromptInjection(
threshold=0.5,
match_type=MatchType.SENTENCE,
)
def filtrar_contexto(trechos: list[tuple[str, str]]) -> list[str]:
aprovados: list[str] = []
for documento_id, texto in trechos:
if not texto.strip():
continue
texto_analisado, valido, risco = scanner.scan(texto)
if not valido:
raise ValueError(
f"Contexto retido: documento={documento_id}; risco={risco}"
)
aprovados.append(texto_analisado)
if not aprovados:
raise ValueError("Sem contexto aprovado para responder")
return aprovadosO limite de 0,5 é apenas demonstrativo, não uma recomendação para produção. Inicialize o scanner fora do caminho repetido de cada fragmento e prepare as dependências e o modelo antes de atender solicitações. Siga as orientações de instalação do repositório oficial e fixe as versões usadas na implantação.
O exemplo interrompe o conjunto inteiro quando encontra suspeita. Outra política possível é descartar um fragmento e continuar, mas isso exige verificar se a resposta restante continua sustentada. Se o único trecho que contém uma condição importante for retido, responder com os demais pode produzir orientação incompleta. Documente essa escolha por tipo de tarefa.
Não insira a exceção bruta na conversa. Identificadores internos, caminhos e detalhes de configuração pertencem ao registro restrito. Para o usuário, uma mensagem como “não foi possível validar as fontes desta resposta” pode ser suficiente, acompanhada do canal de revisão disponível.
Calibração, contexto longo e proteção da saída
Monte uma coleção com conteúdo legítimo, conteúdo deliberadamente suspeito e situações ambíguas. Inclua manuais que ensinam comandos, políticas que usam linguagem imperativa e documentos de segurança que citam ataques. Esses textos ajudam a verificar se o detector está confundindo uma instrução descrita com uma tentativa de controlar o assistente.
Acrescente casos em português, mensagens bilíngues e texto com falhas de extração. Não suponha que comportamento observado em outro idioma represente sua base. Faça a revisão humana dos rótulos antes de medir resultados. Uma amostra com classificação incorreta pode levar a equipe a calibrar o limite na direção errada.
Teste instruções suspeitas no início, no meio e no final dos documentos. Compare a estratégia de segmentação com o tamanho real dos trechos retornados pelo recuperador. A implementação oferece diferentes modos de correspondência e aplica limites associados ao modelo; enviar um documento longo não demonstra que cada parte relevante foi examinada da mesma maneira.
O modo por sentença do exemplo serve para demonstrar uma alternativa. Frases isoladas também perdem contexto, e uma instrução distribuída entre várias partes pode exigir outro desenho de avaliação. Preserve no relatório a configuração de segmentação, a versão do extrator e a ordem dos trechos. Assim, uma mudança de comportamento pode ser investigada.
A saída exige uma política própria. O scanner Sensitive oferece identificação de entidades e opção de redação, conforme sua configuração. Ele não equivale a uma verificação de autorização nem assegura cobertura de todo identificador brasileiro. Avalie os tipos de dados efetivamente presentes antes de confiar no mascaramento.
Se houver resposta em streaming, decida quando a aplicação pode liberar conteúdo. Analisar apenas o texto completo depois de já transmiti-lo não evita a exposição inicial. Para tarefas sensíveis, uma opção de arquitetura é reter a resposta até concluir as verificações necessárias, medindo o impacto dessa escolha na espera do usuário.
Exemplo: suporte técnico de uma indústria em Joinville
Imagine uma indústria fictícia em Joinville com um assistente que consulta manuais de manutenção. Os documentos vêm de fornecedores e da equipe interna. O caso é ilustrativo e não representa uma implantação medida. O objetivo é orientar técnicos sobre onde encontrar procedimentos aprovados, sem permitir que o assistente altere equipamentos.
Na ingestão, a equipe registra origem, revisão e responsável pelo manual. Na consulta, aplica as permissões do técnico e recupera os trechos relevantes. Antes da geração, passa cada trecho pelo adaptador e mantém sua referência documental. Um fragmento suspeito interrompe a resposta daquele conjunto e abre uma tarefa de revisão interna.
O responsável verifica se o alerta veio de uma instrução normal do manual ou de conteúdo estranho. A simples presença de verbos no imperativo não é motivo suficiente para concluir que houve ataque. Ao mesmo tempo, a origem conhecida do fornecedor não transforma todo texto futuro em instrução autorizada para o assistente.
O exercício de aceitação inclui uma pergunta legítima, um manual com comando técnico benigno, um documento de teste com instrução externa suspeita e uma simulação de indisponibilidade do detector. A equipe confere o que chegou ao modelo em cada cenário. Essa observação é mais útil do que apenas confirmar que o scanner foi chamado.
Erros comuns
Examinar somente a pergunta. Em RAG, a instrução indesejada pode estar no material recuperado. Desenhe o teste para acompanhar todas as entradas externas que realmente chegam ao gerador, incluindo conteúdo acrescentado após a busca inicial.
Continuar silenciosamente quando o scanner falha. Isso transforma uma falha técnica em liberação implícita. Defina uma resposta reduzida, uma retenção ou um encaminhamento compatível com a criticidade. Não deixe a decisão depender de um tratamento genérico de exceções.
Prometer proteção completa. Um classificador é uma camada de defesa. Preserve separação entre dados e instruções, limites de ferramentas e autorização fora do modelo. O assistente de consulta não precisa receber poderes de execução para explicar um documento.
Registrar documentos completos em qualquer log. Metadados, resultados e referências podem bastar para uma triagem inicial. Quando o texto integral for necessário à investigação, restrinja o acesso e defina retenção. A observabilidade não deve criar uma nova cópia indiscriminada da base confidencial.
Perguntas frequentes
LLM Guard remove automaticamente a injeção?
Não assuma isso. No scanner PromptInjection examinado, o conteúdo original é retornado junto da decisão. Cabe à aplicação impedir que um texto reprovado seja enviado ao modelo. Outros scanners podem transformar texto conforme a função e a configuração.
Devo bloquear a resposta inteira ou só um trecho?
Depende da tarefa e da evidência restante. Reter o conjunto simplifica a decisão, mas pode interromper consultas legítimas. Remover somente um trecho exige conferir se a resposta ainda pode ser completa e correta sem ele.
Posso usar a mesma configuração em todos os idiomas?
Você pode testar essa hipótese, mas não deve aceitá-la sem evidência. Separe resultados por idioma e tipo de documento. Se uma categoria apresentar falhas recorrentes, ajuste o desenho ou mantenha revisão adicional antes de automatizar a liberação.
O scanner substitui permissões do banco vetorial?
Não. Ele examina conteúdo segundo critérios de detecção. Permissões determinam quais documentos podem ser consultados por cada pessoa. Aplique ambos no ponto adequado e teste também a impossibilidade de acessar material de outra equipe.
Qual resultado comprova que a integração funciona?
Uma evidência operacional é mostrar que um trecho reprovado não chegou ao gerador, que uma falha técnica seguiu a política definida e que conteúdo legítimo aprovado preservou suas referências. Isso comprova o fluxo testado, sem garantir detecção de todos os ataques futuros.
