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

Aplica-se somente a:Portal Foundry (clássico). Este artigo não está disponível para o novo portal do Foundry. Saiba mais sobre o novo portal.

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 Azure com uma assinatura ativa e uma função Owner ou Contributor atribuída. Se você não tiver uma, crie uma conta gratuitamente.
• Microsoft Foundry: ter a função de proprietário ou colaborador para criar um projeto.

Criar um projeto baseado em hub

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

1. Entre no Microsoft Foundry. Certifique-se de que o alternador New Foundry está desativado. Essas etapas se referem ao Foundry (clássico).

   

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

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

     

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

     

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á selecionado aquele que você usou mais recentemente.

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

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

     

6. Se você não tiver 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 Azure OpenAI (gpt-4o-mini) e um modelo de embedding do Azure OpenAI (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 endpoint de tempo real do portal Foundry catálogo de modelos:

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á-la.

   

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. Nesse 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 deste aplicativo é basear 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 Pesquisa de IA do Azure  e uma conexão para criar um índice de pesquisa.

Se você já tiver um serviço de Pesquisa de IA do Azure , vá para a seção next.

Caso contrário, crie um serviço de Pesquisa de IA do Azure  usando o portal Azure.

1. Criar um serviço de Pesquisa de IA do Azure  no portal Azure.
2. Selecione o grupo de recursos e os detalhes da instância. Verifique os preços e as 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 Examinar + atribuir para criar o recurso.
4. Confirme os detalhes do serviço Pesquisa de IA do Azure , incluindo o custo estimado.
5. Selecione Create para criar o serviço Pesquisa de IA do Azure .

Conectar o Pesquisa de IA do Azure  ao seu projeto

Se o projeto já tiver uma conexão Pesquisa de IA do Azure , vá para Instale o CLI do Azure e entre.

No portal do Foundry, verifique se há um recurso do Pesquisa de IA do Azure  conectado.

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

2. Na seção Conectados recursos, veja se você tem uma conexão do tipo Pesquisa de IA do Azure .

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

4. Caso contrário, selecione Novo conexão e 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 de chave de API não é recomendada para produção. A abordagem recomendada é a autenticação do Microsoft Entra ID, que exige os perfis de função Search Index Data Contributor e Search Service Contributor (configurados em Pré-requisitos). Para obter mais informações, consulte Conectar ao Pesquisa de IA do Azure  usando perfis de acesso. Para este tutorial, a chave de API será aceitável se você quiser prosseguir rapidamente. Antes de implantar em produção, alterne para o Entra ID.

7. Selecione Adicionar conexão.

Criar um novo ambiente de 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 de Python. Não instale pacotes na instalação do Python global. Sempre use um ambiente virtual ou conda ao instalar pacotes Python. Caso contrário, você poderá interromper a instalação global de Python.

Se necessário, instale Python

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

Criar um ambiente virtual

Se você já tiver 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 de Python, executar python ou pip da linha de comando usa o interpretador de Python na pasta .venv 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: Azure biblioteca de clientes de Projetos de IA, azure-ai-inference, python-dotenv.

2. Instale os pacotes necessários:

   pip install -r requirements.txt
   

Configurar variáveis de ambiente

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

Crie um .env arquivo 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"

• Encontre sua cadeia de conexão no projeto Foundry que você criou no guia rápido do playground Foundry. Abra o projeto e localize a cadeia de conexão na página Overview. Copie o cadeia de conexão e cole-o no arquivo .env.

  

• Se você ainda não tiver um índice de pesquisa, mantenha o valor "example-index" para AISEARCH_INDEX_NAME. Na parte 2 deste tutorial, você criará o índice usando esse nome. Se você criou anteriormente um índice de pesquisa que deseja usar, atualize o valor para corresponder ao nome desse índice de pesquisa.

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

Instalar o CLI do Azure e entrar

Instale o CLI do Azure e entre em seu ambiente de desenvolvimento local para que seu código possa usar suas credenciais de usuário para chamar serviços Azure por meio do Foundry.

Na maioria dos casos, você pode instalar 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 o CLI do Azure se esses comandos não funcionarem para seu sistema operacional específico ou configuração.

Depois de instalar o 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.

Verificar sua configuração

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

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

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

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

Referências: Biblioteca de Cliente de Projetos de Azure AI, 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 Azure projetos de IA. 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.

Limpar recursos

Para evitar incorrer em custos desnecessários de Azure, exclua os recursos criados neste tutorial se eles não forem mais necessários. Para gerenciar recursos, você pode usar o Azure portal.

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 o 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.