Partilhar via

Tutorial: Parte 1 - Configurar o ambiente de projeto e desenvolvimento para construir uma aplicação personalizada de recuperação de conhecimento (RAG) com o Microsoft Foundry SDK (clássico)

Observação

Este documento refere-se ao portal Microsoft Foundry (clássico).

🔍 Consulte a documentação (nova) da Microsoft Foundry para saber mais sobre o novo portal.

Neste tutorial, configura os recursos necessários para construir uma aplicação de chat personalizada de recuperação de conhecimento (RAG) com o Microsoft Foundry SDK. Esta é a primeira parte de uma série de tutoriais em três partes. Cria os recursos aqui, constrói a aplicação na parte dois e avalia-a na parte três. Nesta parte, você:

  • Criar um projeto
  • Criar um índice Azure AI Search
  • Instale a Azure CLI e inicie sessão
  • Instalar Python e pacotes
  • Implante modelos em seu projeto
  • Configurar as variáveis de ambiente

Se completaste outros tutoriais ou quickstarts, talvez já tenhas criado alguns dos recursos necessários para este tutorial. Se sim, sinta-se à vontade para pular esses passos.

Pré-requisitos

Importante

Este artigo fornece suporte legado para projetos baseados em hubs. Não funciona para projetos da Foundry. Veja : Como sei que tipo de projeto tenho?

Nota de compatibilidade do SDK: Exemplos de código requerem uma versão específica do Microsoft Foundry SDK. Se encontrar problemas de compatibilidade, considere migrar de um projeto baseado em hub para um projeto Foundry.

  • Uma conta Azure com subscrição ativa e função Proprietário ou Contribuidor atribuída. Se você não tiver uma, crie uma conta gratuitamente.
  • Microsoft Foundry: Papel de Proprietário ou Contribuinte para criar um projeto.

Criar um projeto baseado em hub

Para criar um projeto baseado num hub no Microsoft Foundry, siga estes passos:

  1. Inicie sessão no Microsoft Foundry. Certifica-te de que a opção do New Foundry está desligada. Estes passos referem-se à Foundry (clássica).

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

    • Se não tem projetos existentes: Siga os passos em Quickstart: Comece com o 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.

      A captura de tela mostra a criação de um novo projeto a partir de uma trilha de navegação.

    • Se não estiver num projeto: Selecione Criar novo no canto superior direito para criar um novo projeto Foundry

      Uma captura de ecrã mostra como criar um novo projeto no Foundry.

  3. Selecione Recurso do hub AI e, em seguida, selecione Avançar.

  4. Introduza um nome para o projeto.

  5. Se tiver um hub, verá selecionado aquele que usou mais recentemente.

    • Se tiveres acesso a mais de um hub, podes selecionar um hub diferente no menu de seleção.

    • Se quiser criar um novo, seleccione Criar um novo hub no menu suspenso.

      Captura de tela da página de detalhes do projeto na caixa de diálogo criar projeto.

  6. Caso não tenhas um hub, criar-se-á um hub padrão para ti.

  7. Selecione Criar.

Implantar modelos

É necessário dois modelos para construir uma aplicação de chat baseada em RAG: um modelo de chat Azure OpenAI (gpt-4o-mini) e um modelo de embedding Azure OpenAI (text-embedding-ada-002). Implemente estes modelos no seu projeto Foundry usando este conjunto de passos para cada modelo.

Estes passos implementam um modelo para um endpoint em tempo real a partir do catálogo de modelos do portal Foundry:

Sugestão

Como pode personalizar o painel esquerdo no portal Microsoft Foundry, pode ver itens diferentes dos mostrados nestes passos. Se não encontrar o que procura, selecione ... Mais informações 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 ecrã da página de seleção do modelo.

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

  4. Deixe o nome padrão de Deployment e selecione Deploy. Ou, se o modelo não estiver disponível na 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 Azure AI Search

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

Precisa de um serviço Azure AI Search e uma ligação para criar um índice de pesquisa.

Observação

Criar um serviço Azure AI Search e os subsequentes índices de pesquisa acarreta custos. Para confirmar o custo antes de criar o recurso, verifique os preços e os escalões de preços do serviço Azure AI Search na página de criação. Para este tutorial, usa uma faixa de preços de Basic ou superior.

Se já tem um serviço Azure AI Search, vá à secção seguinte.

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

Sugestão

Este passo é a única vez que usa o portal do Azure nesta série de tutoriais. Faz o resto do seu trabalho no portal da Foundry ou no seu ambiente de desenvolvimento local.

  1. Criar um serviço Azure AI Search no portal Azure.
  2. Selecione o grupo de recursos e os detalhes da instância. Consulte os preços e os escalões de preços nesta página. Para este tutorial, usa uma faixa de preços de Basic ou superior.
  3. Continue pelo assistente e selecione Revisar + atribuir para criar o recurso.
  4. Confirme os detalhes do seu serviço Azure AI Search, incluindo o custo estimado.
  5. Selecione Create para criar o serviço Azure AI Search.

Ligue o Azure AI Search ao seu projeto

Se o seu projeto já tiver uma ligação Azure AI Search, vá a Instale o Azure CLI e inicie sessão.

No portal Foundry, verifique se há um recurso ligado ao Azure AI Search.

  1. No Foundry, vá ao seu projeto e selecione Centro de Gestão no painel esquerdo.

  2. Na secção Recursos Conectados, veja se tem uma ligação do tipo Azure AI Search.

  3. Se tiver uma ligação ao Azure AI Search, pode saltar os passos seguintes.

  4. Caso contrário, selecione Nova ligação e depois Azure AI Search.

  5. Encontre o seu serviço de Azure AI Search nas opções e selecione Adicionar ligaçã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 Microsoft Entra ID, que requer os papéis Search Index Data Contributor e Search Service Contributor (configurados em Pré-requisitos). Para saber mais, consulte Ligar-se ao Azure AI Search usando papéis. Para este tutorial, a chave API é aceitável se quiseres avançar rapidamente. Mude para o Entra ID antes de a implementar em produção.

  7. Selecione Adicionar ligaçã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 Python. Não instale pacotes na sua instalação global de Python. Use sempre um ambiente virtual ou conda ao instalar pacotes Python. Caso contrário, podes estragar a instalação global do Python.

Se necessário, instala Python

Usa Python 3.10 ou posterior, mas pelo menos Python 3.9 é obrigatório. Se não tiver uma versão adequada do Python instalada, siga as instruções no tutorial VS Code Python para a forma mais fácil de instalar Python no seu sistema operativo.

Criar um ambiente virtual

Se já tem Python 3.10 ou superior instalado, crie um ambiente virtual usando os seguintes comandos:

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

Quando ativas o ambiente Python, executar python ou pip a partir da linha de comandos usa o interpretador Python na pasta .venv da tua aplicação.

Observação

Use o comando deactivate para sair do ambiente virtual Python. Podes reativá-lo mais tarde, quando necessário.

Instalar pacotes

Instale os pacotes necessários.

  1. Cria um ficheiro chamado requirements.txt na pasta do teu 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 AI Projects biblioteca cliente, azure-ai-inference, python-dotenv.

  2. Instale os pacotes necessários:

    pip install -r requirements.txt

Configurar variáveis de ambiente

A sua cadeia de ligação de projeto é necessária para chamar o Azure OpenAI nos modelos Microsoft 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 a sua cadeia de conexão no projeto Foundry que criou no quickstart Foundry playground. Abra o projeto, depois encontre a connection string na página Visão Geral. Copie o connection string e cole no ficheiro .env.

    Captura de ecrã mostra a página de visão geral de um projeto e a localização do connection string.

  • 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ê tiver criado 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 quando os implantou, atualize os .env valores no arquivo para corresponder aos nomes usados.

Sugestão

Se estiver a trabalhar no VS Code, feche e reabra a janela do terminal depois de guardar as .env alterações no ficheiro.

Advertência

Certifica-te de que o teu .env está no teu ficheiro .gitignore para que não o adiciones acidentalmente ao teu repositório git.

Instale a Azure CLI e inicie sessão

Instala o Azure CLI e inicia sessão a partir do seu ambiente local de desenvolvimento, para que possa usar as suas credenciais de utilizador para ligar Azure OpenAI no Microsoft Foundry Models.

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

winget install -e --id Microsoft.AzureCLI

Podes seguir as instruções Como instalar o Azure CLI se estes comandos não funcionarem para o teu sistema operativo ou configuração em particular.

Depois de instalar o Azure CLI, inicie sessão usando o comando az login e inicie sessão pelo navegador:

az login

Em alternativa, pode iniciar sessão manualmente através do navegador com um código de dispositivo.

az login --use-device-code

Mantém esta janela do terminal aberta para executares os teus scripts python a partir daqui, agora que iniciaste sessão.

Verifique a configuração

Verifique se o seu ambiente está corretamente configurado fazendo 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 vires "Setup successful!", as tuas credenciais de Azure e o SDK estão configurados corretamente.

Sugestão

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

Referências: Azure biblioteca cliente AI Projects, DefaultAzureCredential.

Criar script auxiliar

Crie uma pasta para o seu trabalho. Cria um ficheiro chamado config.py nesta pasta. Vais usar este guião auxiliar nas próximas duas partes da série de tutoriais. O script carrega as variáveis do ambiente e inicializa o cliente Azure AI Projects. 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, DefaultAzureCredential, load_dotenv.

Observação

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

Limpeza de recursos

Para evitar custos desnecessários com o Azure, elimine os recursos que criou neste tutorial se já não forem necessários. Para gerir recursos, pode usar o portal Azure .

Mas não os apagues ainda se quiseres criar uma app de chat na próxima parte desta série de tutoriais.

Próximo passo

Neste tutorial, configura tudo o que precisa para construir uma aplicação de chat personalizada com o Azure AI SDK. Na próxima parte desta série de tutoriais, você cria o aplicativo personalizado.

Parte 2: Constrói uma aplicação de chat personalizada com o SDK

  • Last updated on