Compartilhar via

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

Observação

Alguns links neste artigo podem abrir conteúdo na nova documentação do Microsoft Foundry em vez da documentação do Foundry (clássico) que você está exibindo agora.

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ê:

  • Criar um projeto
  • Criar um índice de Azure AI Search
  • Instalar o Azure CLI e entrar
  • Instalar Python e pacotes
  • Implantar modelos no projeto
  • Configurar suas variáveis de ambiente

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

Importante

Este artigo fornece suporte legado para projetos baseados em hub. Ele não funcionará para projetos do Foundry. Veja como saber qual tipo de projeto tenho?

Observação de compatibilidade do SDK: os exemplos de código exigem uma versão específica do SDK do Microsoft Foundry. Se você encontrar problemas de compatibilidade, considere a migração de um projeto baseado em hub para um projeto do Foundry.

  • Uma conta Azure com uma assinatura ativa e uma função Owner ou Contributor 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. 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

      A captura de tela mostra como criar um novo projeto na Foundry.

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

      A captura de tela mostra a criação de um novo projeto com base em uma barra de trilha.

  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.

      Captura de tela da página de detalhes do projeto na caixa de diálogo de criação do projeto.

  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 Azure OpenAI (gpt-4o-mini) e um modelo de embeddings 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 ponto de extremidade em tempo real do catálogo de modelos do portal da Fábrica:

Dica

Como você pode personalizar o painel esquerdo no portal do Microsoft Foundry, talvez você veja itens diferentes dos mostrados nestas etapas. Se você não vir o que está procurando, selecione ... Mais na parte inferior do painel esquerdo.

  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.

    Captura de tela da página de seleção do modelo.

  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 Azure AI Search

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 Azure AI Search e uma conexão para criar um índice de pesquisa.

Observação

A criação de um serviço Azure AI Search e índices de pesquisa subsequentes gera custos. Para confirmar o custo antes de criar o recurso, verifique os preços e as camadas de preços do serviço Azure AI Search na página de criação. Para este tutorial, use um tipo de preço básico ou superior.

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

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

Dica

Esta etapa é a única vez que você usa o portal Azure nesta série de tutoriais. Você faz o restante do seu trabalho no portal do Foundry ou em seu ambiente de desenvolvimento local.

  1. Criar um serviço de Azure AI Search no portal 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 Azure AI Search, incluindo o custo estimado.
  5. Selecione Create para criar o serviço Azure AI Search.

Conectar o Azure AI Search ao seu projeto

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

No portal do Foundry, verifique a presença de um recurso conectado ao Azure AI Search.

  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 Azure AI Search.

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

  4. Caso contrário, selecione Novo conexão e Azure AI Search.

  5. Localize seu serviço do Azure AI Search 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 requer as funções Search Index Data Contributor e Search Service Contributor (conforme configurado nos Pré-requisitos). Para obter mais informações, consulte Conectar-se ao Azure AI Search usando roles. 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 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

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.

Observação

Use o comando deactivate para sair do ambiente virtual Python. Você pode reativar mais tarde, quando necessário.

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 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 connection string na página Overview. Copie o connection string e cole-o no arquivo .env.

    Screenshot mostra a página de visão geral de um projeto e o local do connection string.

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

Dica

Se estiver trabalhando no VS Code, feche e reabra a janela do terminal depois de salvar as alterações no arquivo .env.

Aviso

Certifique-se de que .env esteja em seu arquivo .gitignore para que você não faça check-in dele acidentalmente no repositório git.

Instalar o Azure CLI e entrar

Instale o Azure CLI e entre em seu ambiente de desenvolvimento local, para que você possa usar suas credenciais de usuário para chamar Azure OpenAI no Microsoft Foundry Models.

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

winget install -e --id Microsoft.AzureCLI

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

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

Dica

Este tutorial requer a versão 1.0.0b10 do SDK de Projetos de IA do Azure. A versão do SDK exibida acima ajuda você a verificar a compatibilidade. Se você tiver uma versão diferente, o from_connection_string() método poderá não estar disponível. Para instalar a versão necessária, execute pip install azure-ai-projects==1.0.0b10.

Referências: Biblioteca cliente de 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 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.

Observação

Esse script também usa um pacote que você ainda não instalou, azure.monitor.opentelemetry. Você instalará esse pacote na próxima parte da série de tutoriais.

Limpar os 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.

Part 2: criar um aplicativo de chat personalizado com o SDK de IA Azure

  • Last updated on