Tutorial: Criar um aplicativo de geração aumentada de recuperação no Serviço de Aplicativo do Azure com o Azure OpenAI e o Azure AI Search (FastAPI)

2025-05-20

Neste tutorial, você criará um aplicativo Python Retrieval Augmented Generation (RAG) usando FastAPI, Azure OpenAI e Azure AI Search e implantá-lo no Serviço de Aplicativo do Azure. Este aplicativo demonstra como implementar uma interface de bate-papo 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.

Neste tutorial, aprenderás como:

Implante um aplicativo FastAPI 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 uma comunicação segura entre serviços.
Teste sua implementação 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:

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

Vetorização integrada: os recursos de vetorização integrada do Azure AI Search tornam fácil e rápido ingerir todos os seus documentos para pesquisa, sem exigir mais código para gerar incorporações.
Acesso simplificado à API: usando o padrão Azure OpenAI On Your Data com o Azure AI Search como uma fonte de dados para finalizações do Azure OpenAI, não há necessidade de implementar pesquisa vetorial complexa ou geração de incorporação. É apenas uma chamada de API e o Azure OpenAI lida com tudo, incluindo engenharia de prompt e otimização de consultas.
Recursos de pesquisa avançada: A vetorização integrada fornece tudo o que é necessário para a pesquisa híbrida avançada com reclassificação semântica, que combina os pontos fortes da correspondência de palavras-chave, semelhança vetorial e classificação baseada em IA.
Suporte completo a citações: as respostas incluem automaticamente citações a documentos de origem, tornando as informações verificáveis e rastreáveis.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa - Crie uma conta gratuitamente.
Conta do GitHub para usar o GitHub Codespaces - Saiba mais sobre o GitHub Codespaces.

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.

Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-rag-openai-ai-search-python.
Selecione o botão Código , selecione a guia Codespaces e clique em Criar espaço de código na principal.
Aguarde alguns instantes até que o Codespace seja inicializado. Quando estiver pronto, você verá um ambiente VS Code totalmente configurado em seu navegador.

2. Implante a arquitetura de exemplo

No terminal, faça logon no Azure usando a CLI do Azure Developer:
```
azd auth login
```
Siga as instruções para concluir o processo de autenticação.
Provisione os recursos do Azure com o modelo AZD:
```
azd provision
```

Quando solicitado, forneça as seguintes respostas:

Pergunta	Resposta
Insira um novo nome de ambiente:	Escreva um nome exclusivo.
Selecione uma Assinatura do Azure para usar:	Selecione uma subscrição.
Escolha um grupo de recursos para usar:	Selecione Criar um novo grupo de recursos.
Selecione um local para criar o grupo de recursos em:	Selecione qualquer região. Os recursos serão efetivamente criados na região East US 2.
Insira um nome para o novo grupo de recursos:	Digite Enter.

Aguarde até que a implementação seja concluída. Este processo irá:
- Crie todos os recursos necessários do Azure.
- Implante o aplicativo Blazor no Serviço de Aplicativo do Azure.
- Configure a autenticação segura de serviço a serviço usando identidades gerenciadas.
- Configure as atribuições de função necessárias para o acesso seguro entre serviços.
Observação

Para saber mais sobre como as identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure e Como usar identidades gerenciadas com o Serviço de Aplicativo.
Após a implantação bem-sucedida, você verá uma URL para seu aplicativo implantado. Anote este URL, mas ainda não o aceda porque ainda precisa de configurar o índice de pesquisa.

3. Carregue documentos e crie um índice de pesquisa

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

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.
Selecione Contêineres no menu de navegação esquerdo e abra o contêiner de documentos .
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.
Navegue até o serviço Azure AI Search no portal do Azure.
Selecione Importar e vetorizar dados para iniciar o processo de criação de um índice de pesquisa.
No passo Conectar aos seus dados:
- Selecione Armazenamento de Blob do Azure como a Fonte de Dados.
- Selecione RAG.
- Escolha sua conta de armazenamento e o contêiner de documentos .
- Verifique se a opção Autenticar usando identidade gerenciada está selecionada.
- Selecione Seguinte.
Na etapa Vetorizar seu texto :
- Selecione seu serviço Azure OpenAI.
- Escolha text-embedding-ada-002 como o modelo de incorporação. O modelo AZD já implantou esse modelo para você.
- Selecione Identidade atribuída ao sistema para autenticação.
- Marque a caixa de seleção de confirmação dos custos adicionais.
- Selecione Seguinte.
Sugestão

Saiba mais sobre a Pesquisa vetorial na Pesquisa de IA do Azure e incorporações de texto no Azure OpenAI.
Na etapa Vetorizar e enriquecer suas imagens :
- Mantenha as configurações padrão.
- Selecione Seguinte.
Na etapa Configurações avançadas :
- Verifique se a opção Ativar classificação semântica está selecionada.
- (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 Seguinte.
Na etapa Revisar e criar :
- Copie o valor do prefixo Nome dos objetos . É o seu nome de índice de pesquisa.
- Selecione Criar para iniciar o processo de indexação.
Aguarde a conclusão do processo de indexação. Isso pode levar alguns minutos, dependendo do tamanho e do número de seus documentos.
Para testar a importação de dados, selecione Iniciar pesquisa e tente uma consulta de pesquisa como "Conte-me sobre sua empresa".
De volta ao seu terminal Codespace, defina o nome do índice de pesquisa como uma variável de ambiente 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 em implantações subsequentes para definir a configuração do aplicativo do App Service.

4. Teste o aplicativo e implante

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

No seu terminal Codespace, obtenha os valores do ambiente AZD:
```
azd env get-values
```
Abra .env. Usando a saída do terminal, atualize os seguintes valores, nos respetivos espaços reservados <input-manually-for-local-testing>:
- AZURE_OPENAI_ENDPOINT
- AZURE_SEARCH_SERVICE_URL
- AZURE_SEARCH_INDEX_NAME
Entre no Azure com a CLI do Azure:
```
az login
```
Isso permite que a biblioteca de cliente do Azure Identity no código de exemplo receba um token de autenticação para o usuário conectado.

Execute o aplicativo localmente:

pip install -r requirements.txt
uvicorn main:app

Quando visualizar a mensagem O seu aplicativo a correr na porta 8000 está disponível, selecione Abrir no navegador.
Tente fazer algumas perguntas na interface de chat. Se você receber uma resposta, seu aplicativo está se conectando com êxito ao recurso do Azure OpenAI.
Pare o servidor de desenvolvimento com Ctrl+C.
Aplique a nova SEARCH_INDEX_NAME configuração no Azure e implante o código de aplicativo de exemplo:
```
azd up
```

5. Teste o aplicativo RAG implantado

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

Abra a URL do aplicativo fornecida no final da implantação.
Você vê uma interface de bate-papo onde você pode inserir perguntas sobre o conteúdo de seus documentos carregados.
Tente fazer perguntas específicas sobre o conteúdo dos 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 apresentar uma reclamação de garantia?
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.
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 palavras-chave).
- Perguntas sobre conceitos que podem ser descritos usando termos diferentes (bom para pesquisa vetorial).
- Perguntas complexas que requerem compreensão do contexto (bom para classificação semântica).

Limpeza de recursos

Quando terminar o aplicativo, você pode excluir todos os recursos para evitar incorrer em custos adicionais:

azd down --purge

Este comando exclui todos os recursos associados ao seu aplicativo.

Perguntas frequentes

Como o código de exemplo recupera citações de finalizações de bate-papo do Azure OpenAI?
Qual é a vantagem de usar identidades gerenciadas nessa solução?
Como a identidade gerenciada atribuída ao sistema é usada nessa arquitetura e aplicativo de exemplo?
Como a pesquisa híbrida com classificador semântico é implementada no aplicativo de exemplo?
Por que todos os recursos são criados na região East US 2?
Posso usar meus próprios modelos OpenAI em vez dos fornecidos pelo Azure?
Como posso melhorar a qualidade das respostas?

Como o código de exemplo recupera citações de finalizações de bate-papo do Azure OpenAI?

O exemplo recupera citações usando uma fonte de dados com o Azure AI Search para o cliente de chat. Quando uma conclusão de chat é solicitada, a resposta inclui um citations objeto dentro do contexto da mensagem. O aplicativo de exemplo passa o objeto de resposta para o código do cliente, que extrai as citações da seguinte maneira:

fetch('/api/chat/completion', {
    // ...
})
// ...
.then(data => {

    // ...
    const message = choice.message;
    const content = message.content;
    
    // Extract citations from context
    const citations = message.context?.citations || [];
    
    // ...
})

Na mensagem de resposta, o conteúdo usa [doc#] notação para fazer referência à citação correspondente na lista, permitindo que os usuários rastreiem as informações até os documentos de origem originais. Para obter mais informações, consulte:

Qual é a vantagem de usar identidades gerenciadas nessa 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 os princípios de segurança do Zero Trust e reduz o risco de exposição de credenciais.

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

A implantação do AZD cria identidades gerenciadas atribuídas ao sistema para o Serviço de Aplicativo do Azure, Azure OpenAI e Azure AI Search. Ele também faz as respetivas atribuições de função para cada um deles (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 o Azure OpenAI On Your Data.

No aplicativo FastAPI de exemplo, os SDKs do Azure usam essa identidade gerenciada para autenticação segura, portanto, você não precisa armazenar credenciais ou segredos em nenhum lugar. Por exemplo, o AsyncAzureOpenAI cliente é inicializado com DefaultAzureCredential, que usa automaticamente a identidade administrada quando é executado no Azure.

self.credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
    self.credential,
    "https://cognitiveservices.azure.com/.default"
)

self.openai_client = AsyncAzureOpenAI(
    azure_endpoint=self.openai_endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-10-21"
)

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

data_source = {
    "type": "azure_search",
    "parameters": {
        "endpoint": self.search_url,
        "index_name": self.search_index_name,
        "authentication": {
            "type": "system_assigned_managed_identity"
        },
        # ...
    }
}

response = await self.openai_client.chat.completions.create(
    model=self.gpt_deployment,
    messages=messages,
    extra_body={
        "data_sources": [data_source]
    },
    stream=False
)

Essa configuração permite uma comunicação segura e sem senha entre seu aplicativo FastAPI e os serviços do Azure, seguindo as práticas recomendadas para segurança Zero Trust. Saiba mais sobre DefaultAzureCredential e a biblioteca de cliente do Azure Identity para Python.

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

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

data_source = {
    "type": "azure_search",
    "parameters": {
        # ...
        "query_type": "vector_semantic_hybrid",
        "semantic_configuration": f"{self.search_index_name}-semantic-configuration",
        "embedding_dependency": {
            "type": "deployment_name",
            "deployment_name": self.embedding_deployment
        }
    }
}

Essa configuração permite que o aplicativo combine pesquisa vetorial (semelhança semântica), correspondência de palavras-chave e classificação semântica em uma única consulta. O classificador semântico reordena os resultados para retornar as respostas mais relevantes e contextualmente apropriadas, que sã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 seja associada exclusivamente ao índice correspondente e siga uma convenção de nomenclatura consistente.

Por que todos os recursos são criados no East US 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 programados para serem aposentados em breve, fornecendo estabilidade para a implantação da amostra. A disponibilidade do modelo e os tipos de implantação podem variar de acordo com a região, portanto, o East US 2 é selecionado para garantir que a amostra funcione prontamente. Se você quiser usar uma região ou modelos diferentes, certifique-se de selecionar modelos disponíveis para o mesmo tipo de implantação na mesma região. Ao escolher seus próprios modelos, verifique sua disponibilidade e datas de aposentadoria para evitar interrupções.

Disponibilidade do modelo: modelos do Serviço OpenAI do Azure
Datas de desativação do modelo: descontinuações e desativações do modelo do Serviço OpenAI do Azure.

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

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

Como posso melhorar a qualidade das respostas?

Pode melhorar a qualidade da resposta:

Upload de documentos de maior qualidade e mais relevantes.
Ajustar estratégias de fragmentação no pipeline de indexação do Azure AI Search. No entanto, não é possível personalizar a fragmentação com a vetorização integrada mostrada neste tutorial.
Experimentando diferentes modelos de prompt no código do aplicativo.
Aperfeiçoar os resultados da pesquisa com outras propriedades na type: "azure_search fonte de dados.
Usando modelos OpenAI do Azure mais especializados para seu domínio específico.

Partilhar via