Compartilhar via

Tutorial: Criar um aplicativo de geração aumentada de recuperação no Serviço de Aplicativo do Azure com o OpenAI do Azure e a Pesquisa de IA do Azure (Spring Boot)

Neste tutorial, você criará um aplicativo RAG (Java Retrieval Retrieval Augmented Generation) usando o Spring Boot, o Azure OpenAI e o Azure AI Search e o implantará no Serviço de Aplicativo do Azure. Este aplicativo demonstra como implementar uma interface de chat que recupera informações de seus próprios documentos e aproveita os serviços de IA do Azure para fornecer respostas precisas e contextualmente conscientes com citações adequadas. A solução usa identidades gerenciadas para autenticação sem senha entre serviços.

Dica

Embora este tutorial use o Spring Boot, os principais conceitos de criação de um aplicativo RAG com o Azure OpenAI e o Azure AI Search se aplicam a qualquer aplicativo Web Java. Se você estiver usando uma opção de hospedagem diferente no Serviço de Aplicativo, como Tomcat ou JBoss EAP, poderá adaptar os padrões de autenticação e o uso do SDK do Azure mostrados aqui para sua estrutura preferida.

Captura de tela mostrando a interface de chat do Spring Boot em introdução.

Neste tutorial, você aprenderá como:

  • Implante um aplicativo Spring Boot que usa o padrão RAG com os serviços de IA do Azure.
  • Configure o Azure OpenAI e o Azure AI Search para pesquisa híbrida.
  • Carregue e indexe documentos para uso em seu aplicativo alimentado por IA.
  • Use identidades gerenciadas para proteger a comunicação serviço a serviço.
  • Teste sua implementação de RAG localmente com serviços de produção.

Visão geral da arquitetura

Antes de começar a implantação, é útil entender a arquitetura do aplicativo que você criará. O diagrama a seguir é do padrão RAG personalizado para o Azure AI Search:

Diagrama de arquitetura mostrando um aplicativo Web conectando-se ao Azure OpenAI e ao Azure AI Search, com o Armazenamento como a fonte de dados

Neste tutorial, o aplicativo Blazer no Serviço de Aplicativo cuida da experiência do aplicativo e do servidor de aplicativos. No entanto, ele não faz uma consulta de conhecimento separada para o Azure AI Search. Em vez disso, ele instrui o OpenAI do Azure a fazer a consulta de conhecimento especificando a Pesquisa de IA do Azure como uma fonte de dados. Essa arquitetura oferece várias vantagens principais:

  • Vetorização integrada: os recursos de vetorização integrada do Azure AI Search facilitam e rapidamente a ingestão de todos os documentos para pesquisa, sem a necessidade de mais código para gerar inserções.
  • Acesso simplificado à API: usando o padrão Azure OpenAI On Your Data com o Azure AI Search como fonte de dados para conclusões do Azure OpenAI, não é necessário implementar a pesquisa de vetor complexa ou a geração de inserção. É apenas uma chamada à API e o Azure OpenAI gerencia tudo, incluindo engenharia de solicitações e otimização de consultas.
  • Capacidades Avançadas de Pesquisa: A vetorização integrada fornece tudo o que é necessário para uma pesquisa híbrida avançada com reranqueamento semântico, que combina os pontos fortes da correspondência de palavras-chave, da similaridade vetorial e da classificação impulsionada por IA.
  • Suporte completo à citação: as respostas incluem automaticamente citações a documentos de origem, tornando as informações verificáveis e rastreáveis.

Pré-requisitos

1. Abra o exemplo com codespaces

A maneira mais fácil de começar é usando o GitHub Codespaces, que fornece um ambiente de desenvolvimento completo com todas as ferramentas necessárias pré-instaladas.

  1. Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java.

  2. Selecione o botão Código , selecione a guia Codespaces e clique em Criar codespace na principal.

  3. Aguarde alguns instantes para que o codespace seja inicializado. Quando estiver pronto, você verá um ambiente do VS Code totalmente configurado em seu navegador.

2. Implantar a arquitetura de exemplo

  1. No terminal, faça logon no Azure usando a CLI do Desenvolvedor do Azure:

    azd auth login

    Siga as instruções para concluir o processo de autenticação.

  2. Provisione os recursos do Azure com o modelo do AZD:

    azd provision

  3. Quando solicitado, dê as seguintes respostas:

    Pergunta Resposta
    Insira um novo nome de ambiente: Digite um nome exclusivo.
    Selecione uma Assinatura do Azure para usar: Selecione a assinatura.
    Escolha um grupo de recursos a ser usado: Selecione Criar um grupo de recursos.
    Selecione um local para criar o grupo de recursos em: Selecione qualquer região. Os recursos serão, de fato, criados no Leste dos EUA 2.
    Insira um nome para o novo grupo de recursos: Digite ENTER.

  4. Aguarde até que a implantação seja concluída. Esse processo será:

    • Crie todos os recursos necessários do Azure.
    • Implante o aplicativo no Serviço de Aplicativo do Azure.
    • Configure a autenticação de serviço a serviço segura usando identidades gerenciadas.
    • Configure as atribuições de função necessárias para acesso seguro entre os serviços.

    Observação

    Para saber mais sobre como as identidades gerenciadas funcionam, confira O que são identidades gerenciadas para recursos do Azure? e Como usar identidades gerenciadas com o Serviço de Aplicativo.

  5. Após a implantação bem-sucedida, você verá uma URL para seu aplicativo implantado. Anote essa URL, mas ainda não a acesse porque você ainda precisa configurar o índice de pesquisa.

3. Carregar documentos e criar um índice de pesquisa

Agora que a infraestrutura está implantada, você precisa carregar documentos e criar um índice de pesquisa que o aplicativo usará:

  1. No portal do Azure, navegue até a conta de armazenamento que foi criada pela implantação. O nome começará com o nome do ambiente fornecido anteriormente.

  2. SelecioneContêineres de > de Dados no menu de navegação à esquerda e abra o contêiner de documentos.

  3. Carregue documentos de exemplo clicando em Carregar. Você pode usar os documentos de exemplo da sample-docs pasta no repositório ou seus próprios arquivos PDF, Word ou texto.

    Captura de tela mostrando como carregar documentos no contêiner de armazenamento.

  4. Navegue até o serviço do Azure AI Search no portal do Azure.

  5. Selecione Importar dados (novo) para iniciar o processo de criação de um índice de pesquisa.

    Captura de tela mostrando o botão Importar e vetorizar dados no Azure AI Search.

  6. Na etapa Conectar-se aos seus dados :

    • Selecione o Armazenamento de Blobs do Azure como a Fonte de Dados.
    • Selecione RAG.
    • Escolha sua conta de armazenamento e o contêiner de documentos .
    • Selecione Autenticar usando a identidade gerenciada.
    • Selecione Próximo.

  7. Na etapa Vetorizar seu texto :

    • Selecione seu serviço Azure OpenAI.
    • Escolha text-embedding-ada-002 como o modelo de inserção. O template AZD já implementou este modelo para você.
    • Selecione a identidade atribuída pelo sistema para autenticação.
    • Selecione a caixa de seleção de confirmação para custos adicionais.
    • Selecione Próximo.

    Dica

    Saiba mais sobre a pesquisa vetorial no Pesquisa de IA do Azure e sobre as incorporações de texto no Azure OpenAI.

  8. Na etapa Vetorizar e enriquecer suas imagens :

    • Mantenha as configurações padrão.
    • Selecione Próximo.

  9. Na etapa configurações avançadas :

    • Verifique se Habilitar o classificador semântico está selecionado.
    • (Opcional) Selecione uma agenda de indexação. Isso é útil se você quiser atualizar seu índice regularmente com as alterações de arquivo mais recentes.
    • Selecione Próximo.

  10. Na etapa Examinar e criar :

    • Copie o valor do prefixo de nome de objetos. É o nome do índice de pesquisa.
    • Selecione Criar para iniciar o processo de indexação.

  11. Aguarde a conclusão do processo de indexação. Isso pode levar alguns minutos dependendo do tamanho e do número de seus documentos.

  12. Para testar a importação de dados, selecione Iniciar a pesquisa e tente uma consulta de pesquisa como "Fale-me sobre sua empresa".

  13. De volta ao terminal do Codespace, defina o nome do índice de pesquisa como uma variável de ambiente do AZD:

    azd env set SEARCH_INDEX_NAME <your-search-index-name>

    Substitua <your-search-index-name> pelo nome do índice copiado anteriormente. O AZD usa essa variável nas implantações seguintes para definir a configuração do aplicativo do Serviço de Aplicativo.

4. Testar o aplicativo e implantar

Se você preferir testar o aplicativo localmente antes ou depois da implantação, poderá executá-lo diretamente do seu Codespace:

  1. No terminal do Codespace, obtenha os valores de ambiente do AZD:

    azd env get-values

  2. Abra src/main/resources/application.properties. Usando a saída do terminal, atualize os seguintes valores nos respectivos espaços reservados <input-manually-for-local-testing>:

    • azure.openai.endpoint
    • azure.search.url
    • azure.search.index.name

  3. Entre no Azure com a CLI do Azure:

    az login

    Isso permite que a biblioteca de clientes da Identidade do Azure no código de exemplo receba um token de autenticação para o usuário conectado.

  4. Execute o aplicativo localmente:

    mvn spring-boot:run

  5. Quando você vir que seu aplicativo em execução na porta 8080 está disponível, selecione Abrir no Navegador.

  6. Tente fazer algumas perguntas na interface de chat. Se você receber uma resposta, seu aplicativo estará se conectando com êxito ao recurso do Azure OpenAI.

  7. Interrompa o servidor de desenvolvimento com Ctrl+C.

  8. Aplique a nova SEARCH_INDEX_NAME configuração no Azure e implante o código de aplicativo de exemplo:

    azd up

5. Testar o aplicativo RAG implantado

Com o aplicativo totalmente implantado e configurado, agora você pode testar a funcionalidade rag:

  1. Abra a URL do aplicativo fornecida no final da implantação.

  2. Você vê uma interface de chat em que pode inserir perguntas sobre o conteúdo dos documentos carregados.

    Captura de tela mostrando a interface de chat blazor.

  3. Tente fazer perguntas específicas ao conteúdo de seus documentos. Por exemplo, se você carregou os documentos na pasta sample-docs , poderá experimentar estas perguntas:

    • Como a Contoso usa meus dados pessoais?
    • Como você solicita uma garantia?

  4. Observe como as respostas incluem citações que fazem referência aos documentos de origem. Essas citações ajudam os usuários a verificar a precisão das informações e encontrar mais detalhes no material de origem.

    Captura de tela mostrando uma resposta com citações aos documentos de origem.

  5. Teste os recursos de pesquisa híbrida fazendo perguntas que podem se beneficiar de diferentes abordagens de pesquisa:

    • Perguntas com terminologia específica (boa para pesquisa de palavra-chave).
    • Perguntas sobre conceitos que podem ser descritos usando termos diferentes (bom para pesquisa de vetor).
    • Perguntas complexas que exigem o contexto de compreensão (bom para classificação semântica).

Limpar os recursos

Quando terminar de usar o aplicativo, você poderá excluir todos os recursos para evitar incorrer em custos adicionais:

azd down --purge

Esse comando exclui todos os recursos associados ao seu aplicativo.

Perguntas frequentes

Como o código de exemplo recupera citações de conclusões de chat do Azure OpenAI?

O exemplo recupera citações usando a AzureSearchChatExtensionConfiguration fonte de dados para o cliente de chat. Quando uma conclusão de chat é solicitada, a resposta inclui um Citations objeto dentro do contexto da mensagem. O código extrai essas citações da seguinte maneira:

public static ChatResponse fromChatCompletions(ChatCompletions completions) {
    ChatResponse response = new ChatResponse();
    
    if (completions.getChoices() != null && !completions.getChoices().isEmpty()) {
        var message = completions.getChoices().get(0).getMessage();
        if (message != null) {
            response.setContent(message.getContent());

            if (message.getContext() != null && message.getContext().getCitations() != null) {
                var azureCitations = message.getContext().getCitations();
                for (int i = 0; i < azureCitations.size(); i++) {
                    var azureCitation = azureCitations.get(i);
                    
                    Citation citation = new Citation();
                    citation.setIndex(i + 1);
                    citation.setTitle(azureCitation.getTitle());
                    citation.setContent(azureCitation.getContent());
                    citation.setFilePath(azureCitation.getFilepath());
                    citation.setUrl(azureCitation.getUrl());
                    
                    response.getCitations().add(citation);
                }
            }
        }
    }
    
    return response;
}

Na resposta de chat, o conteúdo usa a notação [doc#] para referenciar a citação correspondente na lista, permitindo que os usuários rastreiem informações de volta para os documentos originais. Para obter mais informações, consulte:

Qual é a vantagem de usar identidades gerenciadas nesta solução?

As identidades gerenciadas eliminam a necessidade de armazenar credenciais em seu código ou configuração. Usando identidades gerenciadas, o aplicativo pode acessar com segurança serviços do Azure, como o Azure OpenAI e o Azure AI Search sem gerenciar segredos. Essa abordagem segue princípios de segurança de Confiança Zero e reduz o risco de exposição de credenciais.

Como a identidade gerenciada atribuída pelo sistema é usada nesta arquitetura e aplicativo de exemplo?

A implantação do AZD cria identidades gerenciadas atribuídas pelo sistema para o Serviço de Aplicativo do Azure, o Azure OpenAI e o Azure AI Search. Ele também faz as respectivas atribuições de função para cada uma delas (consulte o arquivo main.bicep ). Para obter informações sobre as atribuições de função necessárias, consulte Configuração de Rede e Acesso para Azure OpenAI Nos Seus Dados.

No aplicativo Java de exemplo, os SDKs do Azure usam essa identidade gerenciada para autenticação segura, portanto, você não precisa armazenar credenciais ou segredos em qualquer lugar. Por exemplo, o OpenAIAsyncClient é inicializado com DefaultAzureCredential, que usa automaticamente a identidade gerenciada ao executar no Azure:

@Bean
public TokenCredential tokenCredential() {
   return new DefaultAzureCredentialBuilder().build();
}

@Bean
public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
   return new OpenAIClientBuilder()
         .endpoint(openAiEndpoint)
         .credential(tokenCredential)
         .buildAsyncClient();
}

Da mesma forma, ao configurar a fonte de dados para o Azure AI Search, a identidade gerenciada é especificada para autenticação:

AzureSearchChatExtensionConfiguration searchConfiguration =
   new AzureSearchChatExtensionConfiguration(
      new AzureSearchChatExtensionParameters(appSettings.getSearch().getUrl(), appSettings.getSearch().getIndex().getName())
         .setAuthentication(new OnYourDataSystemAssignedManagedIdentityAuthenticationOptions())
         // ...
   );

Essa configuração permite uma comunicação segura e sem senha entre o aplicativo Spring Boot e os serviços do Azure, seguindo as práticas recomendadas para segurança de Confiança Zero. Saiba mais sobre DefaultAzureCredential e a biblioteca de clientes da Identidade do Azure para Java.

Como a pesquisa híbrida com o classificador semântico é implementada no aplicativo de exemplo?

O aplicativo de exemplo configura a pesquisa híbrida com classificação semântica usando os SDKs java do Azure OpenAI e do Azure AI Search. No back-end, a fonte de dados é configurada da seguinte maneira:

AzureSearchChatExtensionParameters parameters = new AzureSearchChatExtensionParameters(
   appSettings.getSearch().getUrl(),
   appSettings.getSearch().getIndex().getName())
    // ...
    .setQueryType(AzureSearchQueryType.VECTOR_SEMANTIC_HYBRID)
    .setEmbeddingDependency(new OnYourDataDeploymentNameVectorizationSource(appSettings.getOpenai().getEmbedding().getDeployment()))
    .setSemanticConfiguration(appSettings.getSearch().getIndex().getName() + "-semantic-configuration");

Essa configuração permite que o aplicativo combine pesquisa de vetor (similaridade semântica), correspondência de palavra-chave e classificação semântica em uma única consulta. O classificador semântico reorganiza os resultados para retornar as respostas mais relevantes e contextualmente apropriadas, que são então usadas pelo Azure OpenAI para gerar respostas.

O nome da configuração semântica é definido automaticamente pelo processo de vetorização integrado. Ele usa o nome do índice de pesquisa como o prefixo e acrescenta -semantic-configuration como o sufixo. Isso garante que a configuração semântica esteja associada exclusivamente ao índice correspondente e siga uma convenção de nomenclatura consistente.

Por que todos os recursos são criados no Leste dos EUA 2?

O exemplo usa os modelos gpt-4o-mini e text-embedding-ada-002 , ambos disponíveis com o tipo de implantação Standard no Leste dos EUA 2. Esses modelos também são escolhidos porque não estão planejados para serem desativados em breve, proporcionando estabilidade para a implantação do exemplo. Os tipos de disponibilidade e implantação do modelo podem variar de acordo com a região, portanto, o Leste dos EUA 2 foi selecionado para garantir que o exemplo funcione imediatamente. Se você quiser usar uma região ou modelos diferentes, selecione modelos disponíveis para o mesmo tipo de implantação na mesma região. Ao escolher seus próprios modelos, verifique as datas de disponibilidade e de aposentadoria para evitar interrupções.

Posso usar meus próprios modelos OpenAI em vez dos fornecidos pelo Azure?

Essa solução foi projetada para funcionar com o Serviço OpenAI do Azure. Embora você possa modificar o código para usar outros modelos openai, você perderia os recursos de segurança integrados, o suporte à identidade gerenciada e a integração perfeita com o Azure AI Search que essa solução fornece.

Como posso melhorar a qualidade das respostas?

Você pode melhorar a qualidade da resposta:

  • Carregando documentos de maior qualidade e mais relevantes.
  • Ajustando estratégias de segmentação no pipeline de indexação do Azure AI Search. No entanto, você não pode personalizar o agrupamento com a vetorização integrada mostrada neste tutorial.
  • Experimentação de modelos de prompt diferentes no código do aplicativo.
  • Ajuste fino da pesquisa com outras propriedades na classe AzureSearchChatExtensionParameters.
  • Usando modelos mais especializados do Azure OpenAI para seu domínio específico.

Mais recursos

  • Last updated on