Spring AI e Groq: Guia Completo para Criar um Assistente Inteligente

Introdução

Olá pessoal! Nesse artigo vamos aprender como utilizar o Spring AI integrado com o Groq. Entenderemos o que é um template, prompt, client e o Groq. Tudo isso através de uma pequena e simples aplicação de demonstração de um assistente para responder nossas dúvidas.

O que é o Groq?

O Groq é uma tecnologia projetada para realizar inferência de modelos de linguagem natural (LLMs) com altíssimo desempenho. Ele utiliza um tipo de processador dedicado, chamado LPU (Language Processing Unit), que é otimizado especificamente para executar modelos já treinados de forma extremamente rápida e com latência previsível e mínima.

Diferente de GPUs ou CPUs tradicionais, que atendem a uma variedade de tarefas, o foco do Groq está em acelerar exclusivamente o processo de inferência — ou seja, a etapa em que o modelo de IA recebe uma entrada e gera uma resposta. Essa especialização permite que grandes modelos de linguagem funcionem de forma fluida e em tempo real, mesmo com cargas intensas de uso.

É uma excelente opção para realização de testes e pequenos projetos, pois tem algumas opções de LLMs e rate limits consideráveis, se quiser saber mais acesse: groq.com

Essa abordagem o torna ideal para aplicações que dependem de respostas instantâneas, como assistentes de texto, análises automatizadas e geração de linguagem em grande escala.

Criando um API Key

Acesse o site groq.com, em seguida o menu conforme abaixo:

Realize o login. Uma vez logado você já estará na tela para criação, clique em Create API Key, dê um nome para sua chave, copie a mesma e salve em um lugar seguro. Após finalizar o processo, você poderá gerenciar suas chaves, como excluir ou editar o nome, mas não recuperar o valor.

Setup

Para esse projeto estamos utilizando Spring na versão 3.4.7 com Java 21. Se você pretende recriar o projeto desse tutorial, indico utilizar o Spring Initializr para criar a base de seu projeto. Senão, pode baixar o projeto completo através do link que se encontra no final do artigo.

Dependências

Com o projeto criado, vamos inserir as dependências necessárias para a integração com inteligências artificiais:

		<dependency>
			<groupId>org.springframework.ai</groupId>
			<artifactId>spring-ai-openai</artifactId>
			<version>1.0.0</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.ai</groupId>
			<artifactId>spring-ai-client-chat</artifactId>
			<version>1.0.0</version>
		</dependency>

Arquivo de Propriedades

Em nosso arquivo de propriedades (application.yaml) vamos inserir as seguintes configurações:

chat:
  base-url: https://api.groq.com/openai
  api-key: ${GROQ_API_KEY}
  model: llama3-70b-8192
  max-tokens: 1000
  temperature: 0.7

Note que estamos informando a api-key como variável de ambiente (GROQ_API_KEY), essa é a chave que foi gerada no site do Groq.

Template

Para deixarmos nosso assistente mais eficiente, utilizaremos um template (promptTemplate.st).

No Spring AI, um arquivo .st é um template de prompt escrito no formato StringTemplate, uma linguagem de template simples e poderosa que permite montar dinamicamente o conteúdo enviado para o modelo de IA.

Esse arquivo funciona como um modelo de texto com variáveis, onde você define o que será fixo no prompt e quais partes serão preenchidas com informações dinâmicas (em nosso caso, a pergunta do usuário).

Estruturamos o template com o padrão CATS, que é uma forma prática e estruturada de criar bons prompts para IA. Ele ajuda a deixar as instruções mais claras e organizadas, o que melhora muito a qualidade das respostas geradas pela IA.

Cada letra de CATS representa um elemento essencial do prompt:

• C — Contexto:
  Dá à IA informações sobre a situação ou o perfil do usuário.
  Ex: “Você é um assistente que responde dúvidas gerais em um chat.”
• A — Ângulo:
  Define o tom ou o papel que a IA deve assumir.
  Ex: “Responda de forma amigável e direta.”
• T — Tarefa:
  Especifica o que a IA deve fazer.
  Ex: “Explique o que é juros compostos.”
• S — Estilo (Style):
  Define o formato e o jeito que a resposta deve ter.
  Ex: “Use linguagem simples, evite termos técnicos.”

Ficando assim em nosso contexto:

Você é um assistente de IA versátil, capaz de responder qualquer tipo de pergunta ou dúvida do usuário em um chat.

CONTEXTO:
O usuário está fazendo perguntas diversas e espera respostas diretas e fáceis de entender.

ÂNGULO:
Aja como um assistente objetivo, confiável e informativo.

TAREFA:
Responda à seguinte pergunta ou dúvida do usuário:
{message}

ESTILO:
Use uma linguagem simples, acessível, respondendo de forma clara, objetiva e útil.

REGRAS:
    - Se a pergunta for ambígua ou faltar informação essencial, peça esclarecimentos antes de dar uma resposta completa.
    - Se envolver cálculo ou etapas lógicas, mostre o raciocínio de forma legível (sem exagerar).
    - Se não tiver certeza, seja transparente e sugira caminhos para confirmação.
    - Adapte o nível de profundidade ao tom solicitado.
    - Nunca invente dados específicos (números, datas, estatísticas) sem indicar incerteza ou sugerir verificação.
    - Mantenha a resposta em português a menos que o usuário peça outro idioma.
    - Responda diretamente, em texto plano sem quebras de linha (\n).
    - Substitua aspas duplas por aspas simples.

**A partir disso, responda à TAREFA seguindo o CONTEXTO, ÂNGULO e ESTILO acima.**

Implementação

A ideia é focar nos pontos principais de implementação por se tratar de uma aplicação de demonstração/estudo e para não se tornar um artigo extenso.

Iniciaremos criando um arquivo de propriedades, onde iremos carregar todas as configurações do application.yaml para utilizá-las posteriormente em nossos Beans de configuração:

@Validated
@Configuration
@ConfigurationProperties(prefix = "chat")
public class ChatClientProperties {

    @NotEmpty(message = "O campo base-url deve ser informado")
    private String baseUrl;

    @NotEmpty(message = "O campo api-key deve ser informado")
    private String apiKey;

    @NotEmpty(message = "O campo model deve ser informado")
    private String model;

    @NotNull(message = "O campo max-tokens deve ser informado")
    private Integer maxTokens;

    @NotNull(message = "O campo temperature deve ser informado")
    private Double temperature;

    //getters and setters
}

Abaixo, criaremos nossos Beans de configuração injetando nossas propriedades:

@Configuration
public class ChatClientConfig {

    private final ChatClientProperties properties;

    public ChatClientConfig(ChatClientProperties properties) {
        this.properties = properties;
    }

    @Bean
    public OpenAiApi openAiApi() {
        return OpenAiApi.builder()
                .apiKey(properties.getApiKey())
                .baseUrl(properties.getBaseUrl())
                .build();
    }

    @Bean
    public OpenAiChatOptions openAiChatOptions() {
        return OpenAiChatOptions.builder()
                .model(properties.getModel())
                .maxTokens(properties.getMaxTokens())
                .temperature(properties.getTemperature())
                .build();
    }

    @Bean
    public OpenAiChatModel openAiChatModel(OpenAiApi openAiApi, OpenAiChatOptions openAiChatOptions) {
        return OpenAiChatModel.builder()
                .openAiApi(openAiApi)
                .defaultOptions(openAiChatOptions)
                .build();
    }

    @Bean
    public ChatClient chatClient(OpenAiChatModel openAiChatModel) {
        return ChatClient.builder(openAiChatModel).build();
    }
}

Aqui criamos um Bean do tipo OpenApiAi atribuindo nossa chave (apiKey) e a url (baseUrl).

Criamos um outro Bean do tipo OpenApiChatOptions, atribuindo o modelo (model), quantidade máxima de tokens (maxTokens) e a temperatura (temperature).

Com esses dois Beans criados, passamos eles na criação de um novo Bean do tipo OpenAiChatModel.

E por fim, para criar o Bean do Chatclient, informamos o Bean acima.

Há várias formas de implementação, inclusive podendo ser configurado diretamente no application.yaml sem a necessidade de reescrever os Beans.

Optei por implementar dessa forma, para melhor entendimento do funcionamento do Spring AI. Outro detalhe importante é que nessa versão não temos a exposição de um Client diretamente.

Criando um Bean para o Client em nosso contexto, conseguimos injetar o mesmo para utilização em nossa Service:

@Service
public class ChatService {

    @Value("classpath:/prompt/promptTemplate.st")
    private Resource resource;

    private final ChatClient chatClient;

    public ChatService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public ChatOutput sendMessage(ChatInput chatInput) {

        var promptTemplate = PromptTemplate.builder()
                .resource(resource)
                .build();

        var prompt = promptTemplate.render(Map.of("message", chatInput.getMessage()));

        var response = this.chatClient.prompt()
                .user(prompt)
                .call()
                .content();

        return new ChatOutput(response);
    }
}

Nosso método sendMessage cria um objeto do tipo PromptTemplate utilizando o nosso template pré-definido, no qual recuperamos como atributo da classe.

Após a criação, atribuímos em um mapa a mensagem do usuário recebida para que possa ser substituída no template.

Com o template pronto, vamos passar para o Client na seguinte ordem:

• primeiramente chamando o método prompt(), no qual iniciará a construção de um prompt para o modelo de linguagem.
• Definiremos a mensagem do usuário passando o prompt construído com user().
• Executaremos a chamada à IA com call() (Em nosso contexto, para o Groq).
• Extrairemos o conteúdo da resposta retornada pela IA com **content() **(tipicamente um String com o texto gerado pelo modelo).

Enviando uma requisição para testarmos nossa aplicação temos:

Conclusão

Ao longo deste artigo, percorremos todo o processo de criação de um assistente simples utilizando Spring AI integrado ao Groq — desde a compreensão do que é o Groq e como ele acelera a inferência de modelos de linguagem, até a configuração de dependências, propriedades e templates de prompt no padrão CATS para estruturar melhor nossas interações com a IA. Vimos também como criar e injetar Beans personalizados para entender a fundo o fluxo de configuração do Spring AI e, por fim, como implementar um serviço capaz de receber uma pergunta, aplicar o template e obter respostas claras e rápidas.

Agora que você já conhece a base, o próximo passo é soltar a criatividade: experimente adaptar o template para outros estilos de resposta, integrar novas fontes de dados, adicionar histórico de conversas ou até criar comandos personalizados. Quanto mais você explorar, mais aprenderá sobre como unir boas práticas de desenvolvimento com o poder das inteligências artificiais.

Pegue este projeto como ponto de partida, modifique, refine e crie algo único. Afinal, a melhor forma de dominar uma tecnologia é colocando a mão no código e deixando suas ideias ganharem vida.

🔗 Repositório com projeto completo

Acesse o repositório com o projeto completo pronto para rodar:
👉 https://github.com/LuizEduardoBilotta/demo-springai-groq

📚 Referências oficiais

• Documentação Spring AI
• Documentação Groq