Primeiros passos: bate-papo usando seus próprios dados (exemplo de Python)

Este artigo mostra como implantar e executar o Chat com seu próprio exemplo de dadosusando código de exemplo para Python. Este aplicativo de chat de exemplo é criado com Python, Azure OpenAI Service e Retrieval Augmented Generation (RAG) por meio do Azure AI Search.

O aplicativo fornece respostas às perguntas dos usuários sobre os benefícios dos funcionários em uma empresa fictícia. Utiliza Retrieval-Augmented Geração (RAG) para referenciar o conteúdo de arquivos PDF fornecidos, que podem incluir:

• Um manual do funcionário
• Um documento de visão geral dos benefícios
• Uma lista de funções e expectativas da empresa

Ao analisar esses documentos, o aplicativo pode responder a consultas em linguagem natural com respostas precisas e contextualmente relevantes. Essa abordagem demonstra como você pode usar seus próprios dados para potencializar experiências de bate-papo inteligentes e específicas do domínio com o Azure OpenAI e o Azure AI Search.

Você também aprende a definir as configurações do aplicativo para modificar seu comportamento de resposta.

Depois de concluir as etapas neste artigo, você pode começar a personalizar o projeto com seu próprio código. Este artigo faz parte de uma série que o orienta na criação de uma aplicação de chat com o Serviço Azure OpenAI e a Pesquisa Azure AI. Outros artigos da série incluem:

• .NET
• Java
• JavaScript
• Frontend JavaScript com backend Python

Nota

Este artigo é baseado em um ou mais modelos de aplicativo de IA, que servem como implementações de referência bem mantidas. Esses modelos são projetados para serem fáceis de implantar e fornecer um ponto de partida confiável e de alta qualidade para criar seus próprios aplicativos de IA.

Exemplo de arquitetura de aplicativo

O diagrama a seguir mostra uma arquitetura simples do aplicativo de bate-papo.

Os principais componentes da arquitetura incluem:

• Uma aplicação web que hospeda a interface de chat interativa (geralmente construída com Python Flask ou JavaScript/React) e envia perguntas do usuário para o back-end para processamento.
• Um recurso de Pesquisa de IA do Azure que executa pesquisa inteligente em documentos indexados (PDFs, arquivos do Word, etc.) e retorna trechos de documentos relevantes (blocos) para uso em respostas.
• Uma instância do Serviço OpenAI do Azure que:
  • Converte documentos e perguntas do usuário em representações vetoriais para pesquisa de semelhança semântica.
  • Extrai palavras-chave importantes para refinar as consultas do Azure AI Search.
  • Sintetiza as respostas finais usando os dados recuperados e a consulta do usuário.

O fluxo típico do aplicativo de bate-papo é o seguinte:

• O usuário envia uma pergunta: um usuário insere uma pergunta em linguagem natural por meio da interface do aplicativo Web.
• O Azure OpenAI processa a pergunta: O back-end usa o Azure OpenAI para:
  • Gere uma incorporação da pergunta usando o modelo text-embedding-ada-002.
  • Opcionalmente, extraia palavras-chave para refinar a relevância da pesquisa
• O Azure AI Search recupera dados relevantes: a incorporação ou palavras-chave são usadas para executar uma pesquisa semântica sobre conteúdo indexado (como PDFs) no Azure AI Search.
• Combine os resultados com a pergunta: Os trechos mais relevantes do documento (partes) são combinados com a pergunta original do usuário.
• O Azure OpenAI gera uma resposta: a entrada combinada é passada para um modelo GPT (como gpt-35-turbo ou gpt-4), que gera uma resposta sensível ao contexto.
• A resposta é devolvida ao usuário: A resposta gerada é exibida na interface do chat.

Pré-requisitos

Um ambiente de contentor de desenvolvimento está disponível com todas as dependências necessárias para completar este artigo. Você pode executar o contêiner de desenvolvimento no GitHub Codespaces (em um navegador) ou localmente usando o Visual Studio Code.

Para usar este artigo, você precisa dos seguintes pré-requisitos:

• Uma assinatura do Azure. Crie uma conta gratuita antes de começar.

• Permissões da conta do Azure. Sua Conta do Azure deve ter permissões Microsoft.Authorization/roleAssignments/write. Funções como Administrador de Acesso de Usuário ou Proprietário atendem a esse requisito.

• Acesso concedido ao Azure OpenAI na sua subscrição do Azure. Na maioria dos casos, você pode criar filtros de conteúdo personalizados e gerenciar níveis de gravidade com acesso geral aos modelos do Azure OpenAI. O registro para acesso baseado em aprovação não é necessário para acesso geral. Para obter mais informações, consulte Recursos de acesso limitado para serviços de IA do Azure.

• Modificações de filtro de conteúdo ou abuso (opcional). Para criar filtros de conteúdo personalizados, alterar níveis de gravidade ou dar suporte ao monitoramento de abusos, você precisa de aprovação formal de acesso. Pode solicitar o acesso preenchendo os formulários de registo necessários. Para obter mais informações, consulte Registro para filtros de conteúdo modificados e/ou monitoramento de abuso.

• Suporte e solução de problemas de acesso. Para acessar a solução de problemas, abra um problema de suporte no repositório GitHub.

• Uma conta do GitHub. Necessário para bifurcar o repositório e usar o GitHub Codespaces ou cloná-lo localmente.

Visual Studio Code

• Uma assinatura do Azure. Crie uma conta gratuita antes de começar.

• Permissões da conta do Azure. Sua Conta do Azure deve ter permissões Microsoft.Authorization/roleAssignments/write. Funções como Administrador de Acesso de Usuário ou Proprietário atendem a esse requisito.

• Acesso concedido ao Azure OpenAI na sua subscrição do Azure. Na maioria dos casos, você pode criar filtros de conteúdo personalizados e gerenciar níveis de gravidade com acesso geral aos modelos do Azure OpenAI. O registro para acesso baseado em aprovação não é necessário para acesso geral. Para obter mais informações, consulte Recursos de acesso limitado para serviços de IA do Azure.

• Modificações de filtro de conteúdo ou abuso (opcional). Para criar filtros de conteúdo personalizados, alterar níveis de gravidade ou dar suporte ao monitoramento de abusos, você precisa de aprovação formal de acesso. Pode solicitar o acesso preenchendo os formulários de registo necessários. Para obter mais informações, consulte Registro para filtros de conteúdo modificados e/ou monitoramento de abuso.

• A CLI para Desenvolvedores do Azure (azd). Para obter instruções de instalação, consulte Instalar ou atualizar a CLI do Azure Developer.

• Área de trabalho do Docker. Verifique se o Docker Desktop está instalado e em execução antes de começar.

• Código do Visual Studio. Instale a extensão Dev Containers para habilitar o desenvolvimento em contêineres.

Custo de uso para recursos de amostra

A maioria dos recursos usados nessa arquitetura se enquadra em níveis de preços básicos ou baseados no consumo. Isso significa que você paga apenas pelo que usa, e as cobranças geralmente são mínimas durante o desenvolvimento ou teste.

Para concluir este exemplo, pode haver um pequeno custo incorrido com o uso de serviços como Azure OpenAI, AI Search e armazenamento. Depois de concluir a avaliação ou a implantação do aplicativo, você poderá excluir todos os recursos provisionados para evitar cobranças contínuas.

Para obter um detalhamento detalhado dos custos esperados, consulte a Estimativa de custos no repositório GitHub para o exemplo.

Ambiente de desenvolvimento aberto

Comece configurando um ambiente de desenvolvimento que tenha todas as dependências instaladas para concluir este artigo.

Codespaces do GitHub (recomendado)

• Uma assinatura do Azure. Crie um gratuitamente.
• Permissões da conta do Azure. Sua Conta do Azure deve ter permissões Microsoft.Authorization/roleAssignments/write. Funções como Administrador de Acesso de Usuário ou Proprietário atendem a esse requisito.
• Uma conta do GitHub. Necessário para bifurcar o repositório e usar o GitHub Codespaces ou cloná-lo localmente.

• Uma assinatura do Azure. Crie um gratuitamente.
• Permissões da conta do Azure. Sua Conta do Azure deve ter permissões Microsoft.Authorization/roleAssignments/write. Funções como Administrador de Acesso de Usuário ou Proprietário atendem a esse requisito.
• CLI do Desenvolvedor do Azure.
• Área de trabalho do Docker. * Área de trabalho do Docker. Verifique se o Docker Desktop está instalado e em execução antes de começar.
• Código do Visual Studio.
• extensão Dev Containers.

Abra um ambiente de desenvolvimento

Use as instruções a seguir para implantar um ambiente de desenvolvimento pré-configurado contendo todas as dependências necessárias para concluir este artigo.

Espaços de código do GitHub

Para a configuração mais simples e simplificada, use o GitHub Codespaces. O GitHub Codespaces executa um contêiner de desenvolvimento gerenciado pelo GitHub e fornece o Visual Studio Code for the Web como a interface do usuário (UI). Esse ambiente inclui todas as ferramentas, SDKs, extensões e dependências necessárias pré-instaladas, para que você possa começar a desenvolver imediatamente sem configuração manual.

O uso do Codespaces garante:

• As ferramentas e versões corretas do desenvolvedor já estão instaladas.
• Não é necessário instalar o Docker, o VS Code ou extensões localmente.
• Integração inicial rápida e configuração de ambiente reproduzível.

Importante

Todas as contas do GitHub podem usar o GitHub Codespaces por até 60 horas gratuitas por mês com 2 instâncias principais. Se você exceder a cota gratuita ou usar opções de computação maiores, as taxas de cobrança padrão do GitHub Codespaces serão aplicadas. Para obter mais informações, consulte GitHub Codespaces - Armazenamento mensal incluído e horas principais.

1. Para começar a trabalhar com o projeto de exemplo, crie um novo espaço de código GitHub na main ramificação do Azure-Samples/azure-search-openai-demo repositório GitHub.

   Clique com o botão direito do mouse na opção GitHub Codespaces - Open na parte superior da página do repositório e selecione Abrir link na nova janela. Isso garante que o contêiner de desenvolvimento seja iniciado em uma guia dedicada do navegador em tela cheia, dando acesso ao código-fonte e à documentação interna.

   

2. Na página Criar um novo espaço de código , revise as definições de configuração do espaço de código e selecione Criar espaço de código:

   

   Aguarde até que o espaço de código do GitHub seja iniciado. O processo de inicialização pode levar alguns minutos.

3. Depois que o espaço de código do GitHub for aberto, entre no Azure com a CLI do Desenvolvedor do Azure inserindo o seguinte comando no painel Terminal do espaço de código:

   azd auth login
   

   O GitHub exibe um código de segurança no painel Terminal.

   1. Copie o código de segurança no painel Terminal e selecione Enter. Abre-se uma janela do browser.

   2. No prompt, cole o código de segurança no campo do navegador.

   3. Siga as instruções para autenticar com sua conta do Azure.

Você conclui as tarefas restantes do GitHub Codespaces neste artigo no contexto deste contêiner de desenvolvimento.

A extensão Dev Containers para Visual Studio Code requer o Docker instalado em sua máquina local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host Docker com as ferramentas de desenvolvedor corretas e dependências pré-instaladas para concluir este artigo.

1. No computador local, crie um diretório de projeto chamado my-intelligent-app e mude para o diretório:

   mkdir my-intelligent-app
   cd my-intelligent-app
   

2. Abra o Visual Studio Code no diretório do projeto:

   code .
   

3. No Visual Studio Code, abra o painel Terminal selecionando Terminal>Novo Terminal ou use o atalho de teclado Ctrl+Shift+` (acento grave).

4. No painel Terminal de código do Visual Studio, execute o seguinte comando para baixar o repositório GitHub para seu computador local:

   azd init -t azure-search-openai-demo
   

5. Quando solicitado, insira um nome de ambiente. O nome é adicionado como um sufixo ao nome do diretório my-intelligent-app. Use um nome curto com todas as letras minúsculas e traços (-), como myenv. Não use letras maiúsculas, números ou caracteres especiais. O nome do ambiente é usado como parte do nome do grupo de recursos.

   O Visual Studio Code abre o conteúdo do diretório de projeto my-intelligent-app no modo de exibição do Explorer de arquivos:

   

6. Na Barra de Atividades, selecione Explorador Remoto para Contentores de Desenvolvimento e, em seguida, selecione a ligação reabrir a pasta atual num contentor :

   

   Pode levar algum tempo para que o diretório do projeto seja aberto em um contêiner de desenvolvimento. Para monitorar o progresso, selecione mostrar log na caixa de diálogo de progresso:

   

   Aguarde até que o diretório do projeto seja aberto no modo de exibição Explorador Remoto , antes de continuar para a próxima etapa.

7. No painel Terminal de código do Visual Studio, entre no Azure com a CLI do desenvolvedor do Azure (azd):

   azd auth login
   

   Copie o código do painel Terminal e cole-o em um navegador. Siga as instruções do sistema para autenticar com sua conta do Azure.

Você conclui os exercícios restantes neste projeto no contexto deste contêiner de desenvolvimento.

Implantar o aplicativo de chat no Azure

O repositório de exemplo inclui tudo o que você precisa para implantar um bate-papo com seu próprio aplicativo de dados no Azure, incluindo:

• Código fonte da aplicação (Python)
• Arquivos de infraestrutura como código (Bicep)
• Configuração para integração com GitHub e CI/CD (opcional)

Use as etapas seguintes para implantar o aplicativo com a CLI do Desenvolvedor do Azure (azd).

Importante

Os recursos do Azure criados nesta seção, especialmente o Azure AI Search, podem começar a acumular encargos imediatamente após o provisionamento, mesmo que a implantação seja interrompida antes da conclusão. Para evitar cobranças inesperadas, monitore seu uso do Azure e exclua recursos não utilizados imediatamente após o teste.

1. No painel Terminal de código do Visual Studio, crie os recursos do Azure e implante o código-fonte executando o seguinte azd comando:

   azd up
   

2. O processo solicita uma ou mais das seguintes configurações com base na sua configuração:

   • Nome do ambiente: esse valor é usado como parte do nome do grupo de recursos. Insira um nome curto com letras minúsculas e traços (-), como myenv. Não há suporte para letras maiúsculas, números e caracteres especiais.

   • Assinatura: selecione uma assinatura para criar os recursos. Se não vir a subscrição pretendida, utilize as teclas de seta para percorrer a lista completa de subscrições disponíveis.

   • Localização: esta localização de região é usada para a maioria dos recursos, incluindo hospedagem. Selecione uma localização de região perto de você geograficamente.

   • Localização do modelo OpenAI ou recurso de Inteligência Documental: Selecione o local mais próximo geograficamente. Se a região selecionada para a sua Localização estiver disponível para esta definição, selecione a mesma região.

   Pode levar algum tempo para que o aplicativo seja implantado. Aguarde a conclusão da implantação antes de continuar.

3. Depois que o aplicativo for implantado com êxito, o painel Terminal exibirá uma URL de ponto final:

   

4. Selecione o endereço do URL para abrir a aplicação de bate-papo num navegador:

   

Use o aplicativo de bate-papo para obter respostas de arquivos PDF

A aplicação de chat é pré-carregada com informações sobre benefícios dos funcionários a partir de arquivos PDF. Você pode usar o aplicativo de bate-papo para fazer perguntas sobre os benefícios. As etapas a seguir orientam você pelo processo de uso do aplicativo de bate-papo. As suas respostas podem variar à medida que os modelos subjacentes são atualizados.

1. No aplicativo de bate-papo, selecione a opção O que acontece em uma avaliação de desempenho? ou insira o mesmo texto na caixa de texto do bate-papo. O aplicativo retorna a resposta inicial:

   

2. Na caixa de resposta, selecione uma citação:

   

3. O GitHub Codespaces abre o painel Citação à direita, com três regiões separadas por guias, e o foco está na guia Citação.

   

   O GitHub Codespaces fornece três guias de informações para ajudá-lo a entender como o aplicativo de bate-papo gerou a resposta:

   Guia	Descrição
   Processo de Pensamento	Exibe um script das interações de pergunta/resposta no chat. Você pode visualizar o conteúdo fornecido pelo aplicativo de chat system, perguntas inseridas pelo user e esclarecimentos feitos pelo sistema assistant.
   Conteúdo de suporte	Lista as informações usadas para responder à sua pergunta e o material de origem. O número de citações de material de origem é especificado pelas configurações do desenvolvedor. O número padrão de citações é 3.
   Citação	Mostra a fonte original contida para a citação selecionada.

4. Quando terminar, selecione a aba atualmente ativa no painel direito. O painel direito é fechado.

Usar configurações para alterar o comportamento de resposta

O modelo OpenAI específico determina a inteligência do chat e as configurações usadas para interagir com o modelo. A opção Configurações do desenvolvedor abre o painel Configurar geração de respostas , onde você pode alterar as configurações do aplicativo de bate-papo:

Configuração	Descrição
Substituir modelo de prompt	Substitui o prompt usado para gerar a resposta com base na pergunta e nos resultados da pesquisa.
Temperatura	Define a temperatura da solicitação para o modelo de linguagem grande (LLM) que gera a resposta. Temperaturas mais altas resultam em respostas mais criativas, mas podem ser menos fundamentadas.
Sementes	Define uma semente para melhorar a reprodutibilidade das respostas do modelo. A semente pode ser qualquer inteiro.
Pontuação mínima de pesquisa	Define uma pontuação mínima para os resultados de pesquisa retornados da Pesquisa de IA do Azure. O intervalo de pontuação depende se você usa Híbrido (padrão), Somente vetores ou Somente texto para a configuração do modo de recuperação .
Pontuação mínima do reclassificador	Define uma pontuação mínima para os resultados da pesquisa retornados do reclassificador semântico. O resultado varia sempre entre 0-4. Quanto maior a pontuação, mais semanticamente relevante é o resultado para a pergunta.
Recuperar esses muitos resultados de pesquisa	Define o número de resultados de pesquisa a serem recuperados do Azure AI Search. Mais resultados podem aumentar a probabilidade de encontrar a resposta correta, mas podem levar o modelo a ficar "perdido no meio". Você pode ver as fontes retornadas nas guias Processo de pensamento e Conteúdo de suporte do painel Citação .
Incluir categoria	Especifica as categorias a serem incluídas ao gerar os resultados da pesquisa. Use a lista suspensa para fazer a sua seleção. A ação padrão é incluir Todas as categorias.
Excluir categoria	Especifica as categorias a serem excluídas dos resultados da pesquisa. Não há categorias usadas no conjunto de dados padrão.
Usar classificador semântico para recuperação	Habilita o classificador semântico da Pesquisa do Azure AI, um modelo que reclassifica os resultados da pesquisa com base na semelhança semântica com a consulta do usuário.
Usar legendas semânticas	Envia legendas semânticas para o LLM em vez do resultado completo da pesquisa. Uma legenda semântica é extraída de um resultado de pesquisa durante o processo de classificação semântica.
Sugira perguntas de acompanhamento	Pede ao LLM que sugira perguntas de acompanhamento com base na consulta do usuário.
Modo de recuperação	Define o modo de recuperação para a consulta Azure AI Search. A ação padrão é Vetores + Texto (Híbrido), que usa uma combinação de pesquisa vetorial e pesquisa de texto completo. A opção Vetores usa apenas a pesquisa vetorial. A opção Texto usa apenas a pesquisa de texto completo. A abordagem híbrida é ótima.
Transmitir respostas de conclusão do chat	Transmite continuamente a resposta na interface do chat à medida que o conteúdo é gerado.

As etapas a seguir orientam você pelo processo de alteração das configurações.

1. No navegador, selecione a opção Configurações do desenvolvedor .

2. Marque a caixa de seleção Sugerir perguntas de acompanhamento para habilitar a opção e selecione Fechar para aplicar a alteração de configuração.

3. No aplicativo de bate-papo, refaça a pergunta, desta vez inserindo o texto na caixa de perguntas:

   What happens in a performance review?
   

   A resposta do aplicativo de bate-papo agora inclui sugestões de perguntas de acompanhamento:

   

4. Selecione a opção Configurações do desenvolvedor novamente e desmarque Usar classificação semântica para a opção de recuperação . Feche as configurações.

5. Faça a mesma pergunta novamente e observe a diferença na resposta do aplicativo de bate-papo.

   Com o classificador semântico: "Durante uma avaliação de desempenho na Contoso Electronics, seu supervisor discutirá seu desempenho no ano passado e fornecerá feedback sobre as áreas a serem melhoradas. Você também terá a oportunidade de discutir suas metas e objetivos para o próximo ano. A revisão é um diálogo bidirecional entre gestores e funcionários, e é incentivado para que os funcionários sejam honestos e abertos durante o processo (1). O feedback fornecido durante a revisão deve ser positivo e construtivo, com o objetivo de ajudar os funcionários a se desenvolverem e crescerem em suas funções. Os funcionários receberão um resumo escrito de sua avaliação de desempenho, que incluirá uma avaliação de seu desempenho, feedback e metas e objetivos para o próximo ano (1)."

   Sem o classificador semântico: "Durante uma avaliação de desempenho na Contoso Electronics, seu supervisor discutirá seu desempenho no ano passado e fornecerá feedback sobre as áreas a serem melhoradas. É um diálogo bidirecional onde você é encorajado a ser honesto e aberto (1). O feedback fornecido durante a avaliação deve ser positivo e construtivo, com o objetivo de ajudá-lo a se desenvolver e crescer em sua função. Você receberá um resumo por escrito da avaliação, incluindo uma avaliação de seu desempenho, feedback e metas para o próximo ano (1)."

Limpar recursos

Depois de concluir o exercício, é uma prática recomendada remover todos os recursos que não são mais necessários.

Limpar recursos do Azure

Os recursos do Azure criados neste artigo são cobrados na sua assinatura do Azure. Se você não espera precisar desses recursos no futuro, exclua-os para evitar incorrer em mais cobranças.

Exclua os recursos do Azure e remova o código-fonte executando o seguinte azd comando:

azd down --purge --force

As opções de comando incluem:

• purge: Os recursos eliminados são imediatamente removidos. Esta opção permite reutilizar a métrica de tokens por minuto (TPM) do Azure OpenAI.
• force: A eliminação ocorre silenciosamente, sem exigir o consentimento do utilizador.

Limpar espaços de código do GitHub

Excluir o ambiente do GitHub Codespaces garante que possais maximizar o número de horas gratuitas por núcleo a que tendes direito na vossa conta.

Importante

Para obter mais informações sobre os direitos da sua conta do GitHub, consulte Espaços de código do GitHub - Armazenamento incluído mensalmente e horas principais.

1. Faça login no painel de controlo do GitHub Codespaces.

2. No painel, localize seus espaços de código atualmente em execução provenientes do Azure-Samples/azure-search-openai-demo repositório GitHub:

   

3. Abra o menu de contexto do espaço de código e selecione Excluir:

   

Você não é necessariamente obrigado a limpar seu ambiente local, mas pode parar o contêiner de desenvolvimento em execução e retornar à execução do Visual Studio Code no contexto de um espaço de trabalho local.

• Abra a Paleta de comandos, procure os comandos Contêineres de desenvolvimento e selecione Contêineres de desenvolvimento: Reabrir pasta localmente:

  

Gorjeta

O Visual Studio Code interrompe o contêiner de desenvolvimento em execução, mas o contêiner ainda existe no Docker em um estado interrompido. Você sempre tem a opção de excluir a instância do contêiner, a imagem do contêiner e os volumes do Docker para liberar mais espaço na máquina local.

Obter ajuda

Este repositório de exemplo oferece informações sobre solução de problemas.

Se o problema não for resolvido, adicione o problema à página Problemas do repositório.

Conteúdo relacionado

• Obtenha o código-fonte para o exemplo usado neste artigo
• Construa um aplicativo de chat com a arquitetura de solução de práticas recomendadas do Azure OpenAI
• Controle de acesso em aplicativos de IA generativa com Pesquisa de IA do Azure
• Crie uma solução OpenAI pronta para o uso empresarial com o Azure API Management
• Superando a pesquisa vetorial com recursos híbridos de recuperação e classificação