powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
Java

Como validar e filtrar a saída de modelos de IA no Spring AI

Com um CallAdvisor do Spring AI você intercepta a resposta do modelo antes que ela chegue ao usuário e redige números de cartão e chaves de API que escaparam pelo meio do caminho.

Por Marcelo TeixeiraColunista8 min de leitura
Imagem gerada por IA

Com um CallAdvisor do Spring AI você intercepta a resposta do modelo antes que ela chegue ao usuário e redige números de cartão e chaves de API que escaparam pelo meio do caminho.

Neste tutorial eu mostro como interceptar a resposta de um modelo de linguagem no Spring AI e remover dados sensíveis antes que ela saia do seu serviço, usando um CallAdvisor. O código foi testado com Spring AI 1.1.8, a versão fixada pelo BOM usado neste tutorial. Ao final você terá um advisor reutilizável, registrado uma única vez no ChatClient, e um teste JUnit que comprova o comportamento sem gastar um único token de API.

Por que filtrar só a entrada não resolve

O Spring AI já traz um SafeGuardAdvisor pronto, que compara a mensagem do usuário com uma lista de palavras sensíveis. É uma primeira camada razoável, mas ela olha só para o que entra, e boa parte do risco mora no que sai.

SituaçãoPor que o filtro de entrada não pega
Pergunta inofensiva puxa dado sensível"Qual cartão está cadastrado?" não tem palavra banida, mas a resposta pode trazer o número vindo de uma tool call ou de um documento recuperado
Prompt injection indiretoInstruções maliciosas escondidas numa página ou documento chegam pela recuperação (RAG), não pela mensagem do usuário
Geração não determinísticaO mesmo prompt seguro pode gerar respostas diferentes a cada chamada, e uma delas pode repetir algo que não devia
Reformulação e codificaçãoUma lista de palavras é fácil de burlar escrevendo o termo de outro jeito; o filtro de saída vê o texto final, já pronto

Um filtro de saída é a única camada que olha para o que de fato vai ser entregue. Por isso as duas camadas convivem: uma não substitui a outra.

As limitações que valem a pena conhecer antes de confiar cegamente

Um filtro de saída baseado em padrões também tem limite, e é melhor saber onde ele para antes de tratá-lo como solução completa.

  • Um regex encontra o formato de um número de cartão, mas não pega um segredo que o modelo parafraseou com outras palavras.
  • Falso positivo acontece: um número de pedido com 16 dígitos pode ser confundido com número de cartão e acabar redigido sem necessidade.
  • Streaming complica tudo: pedaços da resposta chegam ao usuário antes de o texto completo existir, então checar em streaming exige buffer, e buffer custa latência. O advisor deste tutorial cobre só chamadas bloqueantes via call().
  • Usar um segundo modelo como juiz pega mais casos, mas adiciona custo e latência a cada resposta.
  • Isso é rede de segurança, não controle de acesso: a correção mais forte continua sendo nunca dar ao modelo um dado que o usuário não pode ver.

Dependências: o BOM do Spring AI

O exemplo usa o BOM do Spring AI para fixar a versão de todos os artefatos, mais um starter de modelo (aqui, OpenAI, só como exemplo) e o starter de teste do Spring Boot:

xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.1.8</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Com o BOM importado, o starter do modelo não precisa declarar versão própria. E repare: o advisor que eu vou mostrar funciona com qualquer provedor de modelo, porque ele só toca na resposta que volta do ChatClient, nunca no provedor em si. A dependência de teste é só o que o teste do guardrail precisa, já que ele usa um modelo stub em vez de chamar uma API de verdade.

Criando o advisor de saída

Este advisor chama o resto da cadeia primeiro, depois varre a resposta do modelo e substitui números de cartão e chaves de API por [REDACTED]:

java
package com.example.guardrail;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClientRequest;
import org.springframework.ai.chat.client.ChatClientResponse;
import org.springframework.ai.chat.client.advisor.api.CallAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.model.Generation;
import org.springframework.core.Ordered;

import java.util.ArrayList;
import java.util.List;
import java.util.regex.Pattern;

public class OutputGuardrailAdvisor implements CallAdvisor {

    private static final Logger log = LoggerFactory.getLogger(OutputGuardrailAdvisor.class);

    private static final List<Pattern> SENSITIVE = List.of(
            Pattern.compile("\\b\\d(?:[ -]?\\d){12,15}\\b"),
            Pattern.compile("\\bsk-[A-Za-z0-9]{16,}\\b"));

    @Override
    public String getName() {
        return "OutputGuardrailAdvisor";
    }

    @Override
    public int getOrder() {
        return Ordered.LOWEST_PRECEDENCE;
    }

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) {
        ChatClientResponse response = chain.nextCall(request);
        ChatResponse original = response.chatResponse();
        if (original == null) {
            return response;
        }

        List<Generation> safeGenerations = new ArrayList<>();
        boolean changed = false;

        for (Generation generation : original.getResults()) {
            String text = generation.getOutput().getText();
            String cleaned = text == null ? null : redact(text);
            if (cleaned == null || cleaned.equals(text)) {
                safeGenerations.add(generation);
            } else {
                safeGenerations.add(new Generation(new AssistantMessage(cleaned), generation.getMetadata()));
                changed = true;
            }
        }

        if (!changed) {
            return response;
        }

        log.warn("Output guardrail redacted sensitive content from the model reply");
        ChatResponse safe = ChatResponse.builder().from(original).generations(safeGenerations).build();
        return response.mutate().chatResponse(safe).build();
    }

    private String redact(String text) {
        String result = text;
        for (Pattern pattern : SENSITIVE) {
            result = pattern.matcher(result).replaceAll("[REDACTED]");
        }
        return result;
    }
}

CallAdvisor é a interface para advisors que envolvem chamadas bloqueantes, e ela pede três métodos: getName(), getOrder() e adviseCall(). Dentro de adviseCall(), a linha chain.nextCall(request) executa o resto da cadeia e o modelo, então tudo depois dela opera sobre a resposta já pronta.

Advisors com ordem menor rodam primeiro na ida e por último na volta, então Ordered.LOWEST_PRECEDENCE faz deste o advisor mais interno: ele vê a resposta crua antes de qualquer outro, e advisors externos (como memória de conversa ou logging) só recebem o texto já redigido. Os dois padrões são propositalmente simples: o primeiro casa de 13 a 16 dígitos separados opcionalmente por espaço ou hífen, sem engolir o separador seguinte; o segundo casa chaves que começam com sk-.

O laço deixa qualquer Generation intacta quando o texto está ausente ou não muda, o que preserva respostas de tool call, e só reconstrói uma geração quando algo foi redigido. Quando redige, registra um aviso, monta um novo ChatResponse a partir do original com ChatResponse.builder().from(original) (preservando metadados como uso de tokens) e devolve com response.mutate().chatResponse(safe).build().

Registrando o advisor no ChatClient

O advisor é registrado uma única vez, na configuração do ChatClient, para que toda chamada feita por ele já saia protegida:

java
package com.example.config;

import com.example.guardrail.OutputGuardrailAdvisor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                .defaultAdvisors(new OutputGuardrailAdvisor())
                .build();
    }
}

O Spring AI autoconfigura um bean ChatClient.Builder a partir do starter de modelo que estiver no classpath, e defaultAdvisors() anexa o guardrail a toda requisição feita por esse client. Quem chama continua usando chatClient.prompt().user(pergunta).call().content() normalmente, sem precisar lembrar do guardrail, que é justamente a vantagem de colocar a checagem num advisor central.

Para filtrar também a entrada do usuário, basta somar o SafeGuardAdvisor embutido ao mesmo defaultAdvisors().

Testando com um modelo stub

O teste usa um modelo falso que devolve uma resposta fixa, então ele roda em milissegundos, sem chave de API e com resultado sempre igual:

java
package com.example.guardrail;

import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.model.Generation;

import java.util.List;

import static org.assertj.core.api.Assertions.assertThat;

class OutputGuardrailAdvisorTest {

    private String ask(String modelReply) {
        ChatModel stubModel = prompt ->
                new ChatResponse(List.of(new Generation(new AssistantMessage(modelReply))));

        return ChatClient.builder(stubModel)
                .defaultAdvisors(new OutputGuardrailAdvisor())
                .build()
                .prompt()
                .user("What do you have on file for me?")
                .call()
                .content();
    }

    @Test
    void redactsCardNumber() {
        assertThat(ask("Your card 4111 1111 1111 1111 is on file."))
                .isEqualTo("Your card [REDACTED] is on file.");
    }

    @Test
    void redactsApiKey() {
        assertThat(ask("Use key sk-abc123def456ghi789jkl for access."))
                .isEqualTo("Use key [REDACTED] for access.");
    }

    @Test
    void leavesSafeReplyUntouched() {
        assertThat(ask("Your order ships tomorrow."))
                .isEqualTo("Your order ships tomorrow.");
    }
}

O ChatModel stub é uma lambda porque call(Prompt) é seu único método abstrato, e ele sempre responde com o texto que o teste passar, fazendo o papel de uma resposta insegura do modelo. O helper monta um ChatClient real com o advisor real em volta desse stub, então toda a cadeia de advisors roda exatamente como rodaria em produção: só o modelo é falso.

A pergunta do usuário é a mesma frase inofensiva nos três testes, o que evidencia o ponto central deste tutorial: a entrada é segura, e o risco mora inteiro na resposta. Os dois primeiros testes conferem que o texto sensível é substituído; o terceiro confere que uma resposta normal passa intacta, o que protege contra o advisor redigir além da conta.

Conferindo a saída

Rodando os três testes, o que o modelo "disse" e o que o chamador de fato recebeu fica assim:

Model reply    : Your card 4111 1111 1111 1111 is on file.
Caller receives: Your card [REDACTED] is on file.

Model reply    : Use key sk-abc123def456ghi789jkl for access.
Caller receives: Use key [REDACTED] for access.

Model reply    : Your order ships tomorrow.
Caller receives: Your order ships tomorrow.

[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

Nos dois primeiros casos o advisor trocou só a parte que bateu com o padrão, mantendo o resto da frase legível, então o usuário ainda recebe uma resposta útil. O terceiro caso fica intacto porque nenhum padrão bateu, e nenhum aviso é registrado para ele. Os espaços ao redor de [REDACTED] são preservados porque o padrão de cartão não engole o separador seguinte.

O que fica em aberto

Este advisor cobre só chamadas bloqueantes via call(). Se o seu serviço usa stream(), o mesmo princípio vale, mas exige acumular os chunks antes de liberar qualquer coisa ao usuário, o que adiciona latência e é assunto para outro artigo. Vale também lembrar que regex só pega o que você consegue descrever: um segredo parafraseado pelo modelo passa batido, e um número de pedido com formato parecido pode virar falso positivo.

Para seguir daqui, vale a pena olhar a documentação de Advisors do Spring AI e testar o SafeGuardAdvisor embutido como camada de entrada, somando-o ao defaultAdvisors() do mesmo ChatClient. Em caso de dúvida sobre o contrato de CallAdvisorChain ou sobre como advisors de streaming funcionam, vale consultar a documentação oficial do Spring AI ou os canais de comunidade do projeto.

Fonte: Java Code Geeks

PatrocínioContinue estudando JavaTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Marcelo Teixeira. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Marcelo Teixeira

Editor virtual de Java do Linha de Código. Cobre Java moderno (records, pattern matching, virtual threads), Spring Boot, JPA e Hibernate, Maven e Gradle, e o Kotlin quando ele conversa com a JVM. Escreve para quem mantém o monólito da empresa e para quem está aprendendo a primeira linguagem tipada, sempre declarando a versão do JDK e do framework.

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.