Spring AI: integre uma aplicação Spring com a OpenAI

Spring AI - Apresentação

Boas-vindas! Eu sou o Rodrigo Caneppele, um dos instrutores na Escola de Programação da Alura, e quero te convidar para mais um curso focado em inteligência artificial integrada à programação.

Audiodescrição: Rodrigo se descreve como um homem de pele branca, com cabelo curto e liso castanho-escuro, e olhos castanho-escuros. Ele veste uma camisa esverdeada, e está sentado em uma cadeira preta em frente a uma parede clara iluminada em gradiente azul, com dois quadros de moldura preta pendurados, um à esquerda e outro à direita do instrutor.

Para quem é este curso?

Este curso é para quem trabalha com programação em Java e deseja integrar aplicações com APIs de inteligência artificial generativa para geração de textos, imagens, áudio, entre outros objetivos.

O que vamos aprender?

Neste curso, entenderemos como funciona a integração utilizando o Spring AI, módulo do Spring para integração em uma aplicação Java.

Aprenderemos a criar um projeto utilizando o Spring — famoso framework do mundo Java — com um módulo AI, que consegue se conectar e integrar com diversos provedores de inteligência artificial generativa, como o Amazon Bedrock ou a OpenAI, que possui o famoso ChatGPT.

Provavelmente, você já utiliza o ChatGPT ou o Gemini do Google para gerar textos e imagens, e deseja integrar esses recursos em aplicações. Faremos isso com Java e Spring AI.

Para isso, criaremos um projeto com o Spring AI, entenderemos como ele funciona, e aprenderemos a escrever um código usando as classes do Spring para integrar com as APIs de maneira flexível, permitindo trocar o provedor ou a plataforma de maneira simples, sem reescrever toda a aplicação.

Utilizaremos a inteligência artificial, principalmente, para geração de textos e imagens, e descobriremos como fazer isso usando o módulo do Spring AI.

Também aprenderemos técnicas como prompt engineering (ou Engenharia de Prompt) para melhorar os prompts que nossa aplicação envia ao integrar com a API, obtendo respostas mais assertivas e próximas do esperado.

Além disso, entenderemos como o Spring lida com erros de integração e APIs externas fora do ar, evitando a necessidade de tratamento manual nos códigos Java. Utilizaremos bastante as documentações do Spring AI e da OpenAI para entender esses recursos e funcionalidades.

Quais são os requisitos?

Para melhor aproveitamento do curso, é necessário ter conhecimentos em Java e Spring Boot. Na plataforma da Alura, oferecemos formações para aprender Java e Spring Boot, pois, neste curso, utilizaremos essas ferramentas, mas não as ensinaremos do zero.

Também é importante conhecer API REST, pois desenvolveremos uma API REST que se comunicará com outra API REST. Portanto, é necessário entender o que é:

• API;
• Requisição;
• Resposta;
• Protocolo;
• Verbos HTTP;
• Cabeçalhos;
• Entre outros.

Por fim, devemos saber o que é uma inteligência artificial generativa. Embora uma das etapas do curso seja nos integrarmos a essas ferramentas, não explicaremos do zero o que é o ChatGPT ou a ideia de IA generativa. Na plataforma, temos cursos que ensinam essa base sobre IA generativa.

Esses são os pré-requisitos para acompanhar o curso sem dificuldades.

Conclusão

Esperamos que você goste do curso e aproveite o módulo do Spring para tornar o código Java mais simples ao integrar com APIs de inteligência artificial generativa. Focaremos na OpenAI, mas o Spring suporta dezenas de ferramentas e provedores, sendo fácil trocar de um para outro.

Em caso de dúvidas, utilize nosso fórum ou participe da comunidade no Discord.

Ao final do curso, lembre-se de deixar sua avaliação, pois os feedbacks são essenciais para sempre melhorarmos nossos conteúdos. Nos encontramos na primeira aula!

Spring AI - Criando um projeto com Spring AI

Neste vídeo, vamos iniciar nosso projeto utilizando o Spring AI para criar uma aplicação Java que se integra com a API da OpenAI, aproveitando recursos de inteligência artificial generativa.

Criando um projeto com Spring AI

Acessando a documentação do Spring AI

Começaremos com a documentação do Spring aberta, especificamente, o módulo do Spring AI.

Esse site é a fonte de informações onde podemos entender o que é o projeto, como ele funciona, e acessar a documentação necessária para aprender a usar o módulo do Spring focado em IA.

Na página, encontramos duas abas. A primeira delas é a aba de overview (visão geral), que explica o projeto Spring AI e suas funcionalidades, como, por exemplo:

• O chat, que será a principal funcionalidade utilizada ao longo do curso;
• Os provedores de inteligência artificial suportados, como Amazon Bedrock, Azure OpenAI, Mistral AI e Minimax AI, por exemplo, sendo a OpenAI a principal que utilizaremos;
• Os recursos de envio de mensagens e geração de imagens, com uma listagem dos provedores suportados para cada tipo de recurso;
• Entre outras informações.

Ao final da página, há uma seção chamada "Getting Started". Após entender os recursos e provedores suportados, podemos iniciar um projeto. Para isso, são oferecidas duas opções:

1. Usar uma ferramenta de linha de comando do Spring, caso o Spring CLI esteja instalado no computador;
2. Ou utilizar o site Spring Initializr para gerar o projeto através de um formulário em uma página HTML.

Nesse caso, optaremos pela segunda opção: utilizar o Spring Initializr.

Utilizando o Spring Initializr

O Spring Initializr é um site muito conhecido, utilizado para geração de projetos com o Spring, principalmente, com o Spring Boot. Criaremos o projeto a partir desta opção.

O formulário é dividido em duas partes:

• À esquerda, informações sobre linguagem, projeto e versão;
• À direita, informações sobre dependências e módulos do Spring a serem adicionados.

Escolheremos o Maven como gerenciador de build e de dependências, e a linguagem será Java. No momento da gravação deste curso, a última versão estável do Spring Boot é a 3.3.3.

As informações do Maven serão as seguintes:

• Group: br.com.alura
• Artifact: ecomart
• Name: ecomart
• Description: Demo project for Spring Boot
• Package name: br.com.alura.ecomart
• Packaging: Jar
• Java: 21

No lado direito do formulário, adicionaremos as dependências. Para isso, clicamos no botão "ADD DEPENDENCIES…" ou utilizamos o atalho "Ctrl + B". A principal dependência será a OpenAI.

Atenção! Devemos escolher a opção OpenAI, não a Azure OpenAI.

Além da OpenAI, adicionaremos mais duas dependências: a Spring Web, para testar funcionalidades via requisições HTTP; e a Spring Boot DevTools, para facilitar mudanças no código com publicação automática, sem necessidade de reiniciar manualmente o projeto na IDE.

Ao final, as três dependências selecionadas serão: OpenAI; Spring Web; e Spring Boot DevTools.

Após preencher todo o formulário, clicaremos no botão "GENERATE" no canto inferior esquerdo, que criará um arquivo ZIP (ecomart.zip) do projeto. Após salvá-lo na pasta de downloads do computador, podemos descompactar para acessar a pasta do projeto ("ecomart").

Feito isso, podemos apagar o arquivo ZIP, pois já foi descompactado. Agora, precisamos abrir o projeto na IDE. Nesse caso, utilizaremos o IntelliJ, recomendado para facilitar o aprendizado.

Abrindo o projeto no IntelliJ

Com o IntelliJ aberto, escolheremos a opção "Open" para abrir um projeto. Em seguida, navegaremos até a pasta "Downloads" e selecionaremos a pasta do projeto "ecomart".

Na tag dependencies do arquivo pom.xml, começamos a listar as dependências, incluindo a Spring AI e a OpenAI (provedor escolhido para implementação no módulo de inteligência artificial do Spring AI), além do Spring Web, do DevTools, e outras configurações automáticas do Spring.

pom.xml:

<!-- código omitido -->

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

        <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-devtools</artifactId>
                <scope>runtime</scope>
                <optional>true</optional>
        </dependency>
        <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
        </dependency>
</dependencies>

<!-- código omitido -->

No diretório "src > main > java", a estrutura de pacotes segue as configurações feitas no site ("br.com.alura.ecomart"), onde encontramos a classe EcomartApplication (arquivo EcomartApplication.java) com o método main(), que usaremos para executar a aplicação.

EcomartApplication.java:

package br.com.alura.ecomart;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class EcomartApplication {

    public static void main(String[] args) {
        SpringApplication.run(EcomartApplication.class, args);
    }

}

Pode haver um erro no IntelliJ se o Java não estiver configurado corretamente, mas isso pode ser ajustado. Se já tivermos rodado outros projetos Java, isso provavelmente não ocorrerá.

Conclusão

Com o projeto criado, temos uma aplicação Java com Spring Boot. Se já conhecemos o Spring Boot, não há novidades, exceto pelo módulo e pela dependência do Spring AI.

No próximo vídeo, vamos entender como usar o Spring AI e integrar com a API da OpenAI!

Spring AI - Integração com a API da OpenAI

Agora que temos nosso projeto criado e importado no IntelliJ, podemos implementar alguma funcionalidade escrevendo algum código que irá usar a inteligência artificial, ou seja, que irá se integrar com a API da OpenAI. Esse será nosso objetivo neste vídeo.

Integração com a API da OpenAI

Como mencionado, trabalharemos no projeto fictício de uma empresa chamada Ecomart, um e-commerce de produtos ecológicos. Ao longo do curso, teremos alguns cenários específicos, isto é, alguns casos de uso de funcionalidades que precisarão utilizar inteligência artificial generativa.

Gerando nomes de produtos ecológicos

Para começar, neste primeiro exemplo, precisamos gerar nomes de produtos ecológicos, e queremos usar a inteligência artificial para nos ajudar com isso.

Imagine que a pessoa que vai utilizar o sistema irá entrar em alguma tela ou funcionalidade específica, e ela precisa de nomes criativos para produtos. A geração de nomes criativos será feita pela IA. Portanto, o objetivo deste vídeo será escrever um código que chama a API da OpenAI e envia o pedido de 5 nomes de produtos ecológicos; como se enviássemos um prompt, mas via código Java.

Criando a classe GeradorDeProdutosController

Começaremos com um código Java tradicional, pensando em uma API REST.

Na criação do projeto, adicionamos um módulo web, justamente para testar a aplicação via requisições HTTP no navegador.

Com o projeto aberto no IntelliJ, criaremos uma nova classe que será um controller responsável por receber a requisição, e essa classe terá o código que chama a API da OpenAI.

Com o pacote "ecomart" selecionado, usaremos o atalho "Alt + Insert" e escolheremos a opção "Java Class". Feito isso, digitaremos controller. para criar um subpacote com esse nome, seguido do nome da classe, que será GeradorDeProdutosController.

GeradorDeProdutosController.java:

package br.com.alura.ecomart.controller;

public class GeradorDeProdutosController {
}

Transformando a classe em um controller

Para transformar a classe em um controller, adicionamos a anotação @RestController acima da declaração, visto que será um controller do tipo REST.

Além disso, usamos a anotação @RequestMapping(), passando entre parênteses e aspas duplas a URL que será chamada no controller quando for disparada uma requisição. Nesse caso, passaremos a URL "gerador", ou seja, se chegar uma requisição para a /gerador, ela cairá nesse controller.

// código omitido

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("gerador")
public class GeradorDeProdutosController {
}

Declarando o método gerarProdutos()

No controller, precisamos ter um método com alguma lógica que será executada na requisição.

Dito isso, no escopo de GeradorDeProdutosController, criaremos um método public que devolve uma String, e nomearemos esse método como gerarProdutos(). Por enquanto, ele não fará nada; apenas compilaremos com return seguido de uma string vazia ("").

Acima do método, adicionamos @GetMapping para mapear o verbo do protocolo HTTP.

// código omitido

@RestController
@RequestMapping("gerador")
public class GeradorDeProdutosController {

    @GetMapping
    public String gerarProdutos() {
        return "";
    }

}

Usando o Spring AI para chamar a API

Até o momento, temos a parte web implementada, um controller construído, e a requisição GET mapeada. Assim, se chegar uma requisição GET para /gerador, cairemos no método gerarProdutos(), que, no momento, devolve apenas uma string vazia. O escopo do método gerarProdutos() é onde faremos a chamada para a API da OpenAI, usando o Spring AI.

O Spring AI já foi adicionado ao projeto como uma das dependências, com o módulo da OpenAI. Porém, qual classe devemos chamar? Qual classe precisamos instanciar? Como fazer para integrar? Como funciona a API do Spring para se integrar com a API da OpenAI?

Retornaremos à documentação do Spring para descobrir.

Acessando a documentação do Spring AI

Com a documentação do Spring AI aberta, ao final da página, encontramos a seção "Getting Started", que explica como criar o projeto. Contudo, não há exemplo de código.

Agora que temos o projeto criado, como proceder?

No topo da página, temos duas abas: a primeira chamada "OVERVIEW", que exploramos até o momento; e a segunda chamada "LEARN". Nessa segunda aba, encontramos as versões do Spring AI:

• 1.0.0-SNAPSHOT;
• 1.0.0-M2.

Nesse caso, acessaremos a versão 1.0.0-SNAPSHOT, que é a atual no momento da gravação. À direita da versão, há um link chamado "Reference Doc.". É justamente isso que queremos acessar: a documentação de referência, para entendermos como funciona a parte do código.

Ao clicar nesse link, somos redirecionados para uma documentação com o ponto de vista técnico de código. Trata-se de uma documentação muito completa, com uma barra de menu lateral à esquerda contendo categorias, onde conseguimos encontrar o que desejamos implementar.

A depender do que queremos implementar, encontramos seções específicas neste menu.

Nesse menu lateral esquerdo, clicaremos sobre o item "Spring AI API". Ao fazer isso, a página se expande para exibir vários sub-itens dentro dessa seção. A partir do menu, selecionaremos o primeiro item: "Chat Client API".

Nosso objetivo é acessar a API do Spring para fazer a integração com o recurso de chat, pois esse é o modo que queremos usar da inteligência artificial generativa. No momento, não queremos gerar imagens ou fazer transcrição de áudio, por exemplo; queremos apenas o modo de chat, como no ChatGPT, onde fazemos uma pergunta, a IA gera uma resposta, e retorna a resposta gerada.

Na documentação do Chat Client API, é explicado como esse modo funciona no caso do Spring, e são apresentados alguns exemplos de código. Com base nessa parte da documentação, aprenderemos a escrever um código para fazer a chamada para a API da OpenAI. Observe o exemplo abaixo:

Exemplo de código extraído da documentação do Spring AI, na seção "Spring AI API > Chat Client API > Using an autoconfigured ChatClient.Builder":

@RestController
class MyController {

    private final ChatClient chatClient;

    public MyController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/ai")
    String generation(String userInput) {
        return this.chatClient.prompt()
            .user(userInput)
            .call()
            .content();
    }
}

Perceba que foi usado um exemplo semelhante ao que fizemos anteriormente, criando um controller e um método. No escopo do método, está o trecho de código que precisamos.

Ajustando o método gerarProdutos()

Vamos copiar esse trecho do return, voltar para o IntelliJ, e substituir o return "" pelo que copiamos. Evidentemente, teremos um erro de compilação, pois o exemplo usa return this.chatClient. Sendo assim, precisamos ter um atributo na classe chamado chatClient.

Analisando o controller de exemplo da documentação, ele tem um atributo e um construtor para fazer a injeção de dependências desse atributo. Copiaremos tanto o atributo quanto o construtor e colaremos no escopo da classe GeradorDeProdutosController, acima da declaração do método.

Agora, precisamos apenas fazer a importação. Para isso, vamos pedir que o IntelliJ importe ChatClient e substituir o nome do controller MyController por GeradorDeProdutosController.

GeradorDeProdutosController.java:

package br.com.alura.ecomart.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("gerador")
public class GeradorDeProdutosController {

    private final ChatClient chatClient;

    public GeradorDeProdutosController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping
    public String gerarProdutos() {
        return this.chatClient.prompt()
                .user(userInput)
                .call()
                .content();
    }

}

Sempre que quisermos fazer uma chamada para a API, para o provedor de inteligência artificial que usamos neste curso (OpenAI), precisamos usar a classe ChatClient, que é o cliente de chat.

Essa classe do Spring abstrai a integração com a API, seja da OpenAI ou de qualquer provedor, para usar o recurso de chat — envio de mensagens e geração de respostas via IA generativa.

Perceba que o construtor GeradorDeProdutosController() não recebe como parâmetro um objeto ChatClient, mas sim um ChatClient.Builder.

No Spring, não conseguimos injetar diretamente o ChatClient. É necessário injetar o Builder, que possui um método chamado build(), responsável pela construção do ChatClient. Portanto, no construtor, injetamos Builder e chamamos build() para obter o objeto.

Declarando a variável pergunta

No momento, o método gerarProdutos() retorna um erro de compilação, pois a variável userInput não existe. O userInput seria a pergunta, isto é, o texto.

Para corrigir isso, antes do return no escopo do método, vamos declarar uma variável (var) chamada pergunta, que será igual a uma string com o pedido "Gere 5 produtos ecológicos". Feito isso, no método user(), iremos substituir userInput pela variável local pergunta.

// código omitido

@GetMapping
public String gerarProdutos() {
    var pergunta = "Gere 5 produtos ecologicos";

    return this.chatClient.prompt()
            .user(pergunta)
            .call()
            .content();
}

// código omitido

Esse é o código para fazermos a integração com a API da OpenAI. Note que ele é simples: temos primeiro this.chatClient.prompt(), seguido de .user() contendo a mensagem da pessoa usuária, .call() para disparar a requisição, e .content() para obter o conteúdo da resposta.

Isso retorna uma string com a resposta gerada pela inteligência artificial.

Conclusão

Assim, temos o código implementado, o controller finalizado, e uma funcionalidade aplicada ao projeto que já conseguimos testar. Basta executar a aplicação e acessar o endereço localhost:8080/gerador, para chamar o método gerarProdutos() e retornar a string.

Para executar o projeto, acessamos o menu "Project" à esquerda, abrimos a classe EcomartApplication (que contém o método main()), clicamos no ícone de play, e escolhemos a opção "Run". Ao fazer isso, o console retorna um erro, indicando que precisa de uma chave de API que está indefinida. Abordaremos esse detalhe importante no próximo vídeo!

Sobre o curso Spring AI: integre uma aplicação Spring com a OpenAI

O curso Spring AI: integre uma aplicação Spring com a OpenAI possui 130 minutos de vídeos, em um total de 45 atividades. Gostou? Conheça nossos outros cursos de IA para Programação em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Spring AI
• Prompt Engineering
• Modelos e custos
• Tratamento de erros
• Flexibilidade do Spring AI