Tutorial: Parte 1 – Configurar o ambiente de projeto e desenvolvimento para criar um aplicativo de RAG (recuperação de conhecimento personalizado) com o SDK do Microsoft Foundry

Neste tutorial, você configurará os recursos necessários para criar um aplicativo de chat RAG (Recuperação de Conhecimento) personalizado com o SDK do Microsoft Foundry. Esta é a primeira parte de uma série de tutoriais de três partes. Você cria os recursos aqui, cria o aplicativo na parte dois e o avalia na parte três. Nesta parte, você:

Se você concluiu outros tutoriais ou guias de início rápido, talvez já tenha criado alguns dos recursos necessários para este tutorial. Se você fez isso, sinta-se à vontade para ignorar essas etapas.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa e função de Proprietário ou Colaborador atribuída. Se você não tiver, crie uma conta gratuita.
• Microsoft Foundry: Função de proprietário ou colaborador para criar um projeto.

Criar um projeto baseado em hub

Para criar um projeto baseado em hub no Microsoft Foundry, siga estas etapas:

1. Entre no Microsoft Foundry. Certifique-se de que o botão New Foundry está desativado. Estas etapas referem-se à Fábrica (clássico).

   

2. O que você faz a seguir depende de onde você está:

   • Se você não tiver nenhum projeto existente: siga as etapas em Início rápido: Introdução ao Microsoft Foundry para criar o seu primeiro projeto.

   • Se você estiver em um projeto: selecione a trilha do projeto e, em seguida, selecione Criar novo recurso.

     

   • Se você não estiver em um projeto: selecione Criar novo no canto superior direito para criar um novo projeto Foundry

     

3. Selecione o recurso do hub de IA e selecione Avançar.

4. Insira um nome para o projeto.

5. Se você tiver um hub, verá o que usou mais recentemente selecionado.

   • Se tiver acesso a mais de um hub, poderá selecionar um hub diferente na lista suspensa.

   • Se você quiser criar um novo, selecione Criar um novo hub no menu suspenso.

     

6. Caso você não tenha um hub, um hub padrão será criado para você.

7. Selecione Criar.

Implantar modelos

Você precisa de dois modelos para criar um aplicativo de chat baseado em RAG: um modelo de chat do OpenAI do Azure (gpt-4o-mini) e um modelo de inserção do OpenAI do Azure (text-embedding-ada-002). Implante esses modelos em seu projeto do Foundry usando este conjunto de etapas para cada modelo.

Estas etapas implantam um modelo em um ponto de extremidade em tempo real do catálogo de modelos do portal da Fábrica:

1. No painel esquerdo, selecione Catálogo de modelos.

2. Selecione o modelo gpt-4o-mini na lista de modelos. Você pode usar a barra de pesquisa para encontrá-lo.

   

3. Na página de detalhes do modelo, selecione Usar este modelo.

4. Deixe o nome da Implantação padrão e selecione Implantar. Ou, se o modelo não estiver disponível em sua região, uma região diferente será selecionada para você e conectada ao seu projeto. Neste caso, selecione Conectar e implantar.

Depois de implantar o gpt-4o-mini, repita as etapas para implantar o modelo text-embedding-ada-002.

Criar um serviço de Pesquisa de IA do Azure

O objetivo desta aplicação é fundamentar as respostas do modelo em seus dados personalizados. O índice de pesquisa recupera documentos relevantes com base na pergunta do usuário.

Você precisa de um serviço e conexão do Azure AI Search para criar um índice de pesquisa.

Se você já tiver um serviço do Azure AI Search, vá para a próxima seção.

Caso contrário, crie um serviço do Azure AI Search usando o portal do Azure.

1. Criar um serviço de Pesquisa de IA do Azure no portal do Azure.
2. Selecione seu grupo de recursos e os detalhes da instância. Verifique os preços e faixas de preços nesta página. Para este tutorial, use um tipo de preço básico ou superior.
3. Continue por meio do assistente e selecione Revisar + atribuir para criar o recurso.
4. Confirme os detalhes do serviço do Azure AI Search, incluindo o custo estimado.
5. Selecione Criar para criar o serviço Pesquisa de IA do Azure.

Conectar a Pesquisa de IA do Azure ao seu projeto

Se o projeto já tiver uma conexão do Azure AI Search, vá para Instalar a CLI do Azure e entre.

No portal do Foundry, verifique se há um recurso conectado do Azure AI Search.

1. No Foundry, vá para o projeto e selecione o Centro de Gerenciamento no painel esquerdo.

2. Na seção Recursos conectados, procure se você tem uma conexão do tipo Pesquisa de IA do Azure.

3. Se você tiver uma conexão do Azure AI Search, poderá ignorar as próximas etapas.

4. Caso contrário, selecione Nova conexão e, em seguida, Pesquisa de IA do Azure.

5. Localize seu serviço de Pesquisa de IA do Azure nas opções e selecione Adicionar conexão.

6. Use a chave de API para autenticação.

   Importante

   A opção Chave de API não é recomendada para produção. A abordagem recomendada é a autenticação do Microsoft Entra ID, que exige as funções Colaborador de Dados do Índice de Pesquisa e Colaborador do Serviço de Pesquisa (configuradas nos Pré-requisitos). Para obter mais informações, confira Conectar-se à Pesquisa de IA do Azure usando funções. Para este tutorial, a chave de API será aceitável se você quiser prosseguir rapidamente. Alterne para o Entra ID antes de implantar em produção.

7. Selecione Adicionar conexão.

Criar um novo ambiente Python

No IDE de sua escolha, crie uma nova pasta para seu projeto. Abra uma janela de terminal nessa pasta.

Primeiro, crie um novo ambiente do Python. Não instale pacotes em sua instalação global do Python. Sempre use um ambiente virtual ou conda ao instalar pacotes do Python. Caso contrário, você poderá interromper a instalação global do Python.

Se necessário, instale o Python

Use o Python 3.10 ou posterior, mas pelo menos o Python 3.9 é necessário. Se você não tiver uma versão adequada do Python instalada, siga as instruções no Tutorial do Python do VS Code para obter a maneira mais fácil de instalar o Python em seu sistema operacional.

Criar um ambiente virtual

Se você já tiver o Python 3.10 ou superior instalado, crie um ambiente virtual usando os seguintes comandos:

py -3 -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Quando você ativa o ambiente do Python, a execução python ou pip a partir da linha de comando usa o interpretador do Python na .venv pasta do aplicativo.

Instalar pacotes

Instale os pacotes necessários.

1. Crie um arquivo chamado requirements.txt na pasta do projeto. Adicione os seguintes pacotes ao arquivo:

   azure-ai-projects==1.0.0b10
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

   Referências: biblioteca de clientes do Azure AI Projects, azure-ai-inference, python-dotenv.

2. Instale os pacotes necessários:

   pip install -r requirements.txt
   

Verificar sua configuração

Verifique se o ambiente está configurado corretamente executando um teste rápido:

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# This will fail if credentials aren't set up, confirming auth is working
client = AIProjectClient.from_config(credential=DefaultAzureCredential())
print("Setup successful! You're ready to build your RAG app.")

Se você vir "Setup successful!", suas credenciais do Azure e o SDK serão configurados corretamente.

Referências: biblioteca de clientes do Azure AI Projects, DefaultAzureCredential.

Criar script auxiliar

Crie uma pasta para seu trabalho. Crie um arquivo chamado config.py nesta pasta. Você usará esse script auxiliar nas próximas duas partes da série de tutoriais. O script carrega suas variáveis de ambiente e inicializa o cliente de Projetos de IA do Azure. Adicione o seguinte código:

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

Referências: AIProjectClient, DefaultAzureCredentialload_dotenv.

Configurar variáveis de ambiente

A cadeia de conexão do projeto é necessária para chamar o OpenAI do Azure nos Modelos da Fábrica da Microsoft a partir do seu código. Neste início rápido, você salva esse valor em um arquivo .env, que é um arquivo que contém variáveis de ambiente que seu aplicativo pode ler.

Crie um arquivo .env e cole o seguinte código:

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

• Localize a cadeia de conexão no projeto da Fábrica que você criou no início rápido do playground da Fábrica. Abra o projeto e localize a cadeia de conexão na página Visão geral. Copie a cadeia de conexão e cole-a no arquivo .env.

  

• Se você ainda não tem um índice de pesquisa, mantenha o valor “example-index” para AISEARCH_INDEX_NAME. Na segunda parte deste tutorial, você criará o índice usando esse nome. Se você já criou um índice de pesquisa que deseja usar, atualize o valor para que ele corresponda ao nome desse índice de pesquisa.

• Se você alterou os nomes dos modelos ao implantá-los, atualize os valores no arquivo .env para que corresponda aos nomes usados.

Instalar a CLI do Azure e entrar

Instale a CLI do Azure e entre em seu ambiente de desenvolvimento local, de modo que você possa usar as suas credenciais de usuário para chamar o OpenAI do Azure nos Modelos da Fábrica da Microsoft.

Na maioria dos casos, você pode instalar a CLI do Azure do terminal usando o seguinte comando:

winget install -e --id Microsoft.AzureCLI

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

Você pode seguir as instruções Como instalar a CLI do Azure se esses comandos não funcionarem para seu sistema operacional específico ou configuração.

Depois de instalar a CLI do Azure, entre usando o comando az login e entre usando o navegador:

az login

Como alternativa, você pode entrar manualmente por meio do navegador com um código de dispositivo.

az login --use-device-code

Mantenha essa janela do terminal aberta para executar seus scripts python daqui também, agora que você entrou.

Limpar os recursos

Para evitar incorrer em custos desnecessários do Azure, exclua os recursos criados neste tutorial se eles não forem mais necessários. Para gerenciar os recursos, use o portal do Azure.

Mas não os exclua ainda se você quiser criar um aplicativo de chat na próxima parte desta série de tutoriais.

Próxima etapa

Neste tutorial, você configura tudo de que precisa para criar um aplicativo de chat personalizado com o SDK de IA do Azure. Na próxima parte desta série de tutoriais, você criará o aplicativo personalizado.