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)

Aplica-se apenas a:Portal Foundry (clássico). Este artigo não está disponível para o novo portal da Foundry. Saiba 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 SDK Microsoft Foundry. 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, tu:

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 estas etapas.

Pré-requisitos

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

Crie um projeto baseado num hub

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

1. Iniciar 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 faz a seguir depende de onde está:

   • Se não estiveres num projeto, ou ainda não tiveres projetos: Seleciona Criar novo no canto superior direito para criar um novo projeto Foundry

     

   • Se estiveres num projeto: Seleciona a breadcrumb do projeto e depois seleciona Criar novo recurso.

     

3. Seleciona o recurso do hub de IA e depois seleciona Próximo.

4. Introduza um nome para o projeto.

5. Se tiveres um hub, vais ver o que usaste mais recentemente selecionado.

   • Se tiveres acesso a mais do que um hub, podes selecionar um hub diferente no menu suspenso.

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

     

6. Se não tiver um hub, será criado um hub padrão para si.

7. Selecione Criar.

Modelos de implementação

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

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

2. Selecione o modelo gpt-4o-mini da lista de modelos. Podes usar a barra de pesquisa para o encontrar.

   

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 é selecionada para si e ligada ao seu projeto. Neste caso, selecione Ligar e implementar.

Depois de implementar o gpt-4o-mini, repita os passos para implementar o modelo text-embedding-ada-002 .

Criar um serviço Pesquisa de IA do Azure

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 Pesquisa de IA do Azure e uma ligação para criar um índice de pesquisa.

Se já tem um serviço Pesquisa de IA do Azure, vá à secção seguinte.

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

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

Ligue o Pesquisa de IA do Azure ao seu projeto

Se o seu projeto já tiver uma ligação Pesquisa de IA do Azure, vá a Instale o CLI do Azure e inicie sessão.

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

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 Pesquisa de IA do Azure.

3. Se tiver uma ligação ao Pesquisa de IA do Azure, pode saltar os passos seguintes.

4. Caso contrário, selecione Nova ligação e depois Pesquisa de IA do Azure.

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

6. Utilize a chave API para Autenticação.

   Importante

   A opção da chave 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 mais informações, consulte Ligação ao Pesquisa de IA do Azure usando funções. Para este tutorial, a chave API é aceitável se quiseres avançar rapidamente. Altere para o Entra ID antes de implantar em produção.

7. Selecionar Adicionar ligação.

Criar um novo ambiente Python

No IDE que preferir, crie uma nova pasta para o seu projeto. Abre 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.

Crie 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

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

python3 -m venv .venv
source .venv/bin/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.

Pacotes de instalação

Instale os pacotes necessários.

1. Cria um ficheiro chamado requirements.txt na pasta do teu projeto. Adicione os seguintes pacotes ao ficheiro:

   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 string de conexão do seu projeto é necessária para chamar o Azure OpenAI nos Modelos Microsoft Foundry a partir do seu código. Neste quickstart, guarda este valor num .env ficheiro, que é um ficheiro que contém variáveis de ambiente que a sua aplicação pode ler.

Crie um .env ficheiro 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 o seu cadeia de ligação no projeto Foundry que criou no Foundry playground quickstart. Abra o projeto, depois encontre a cadeia de ligação na página Visão Geral. Copie o cadeia de ligação e cole no ficheiro .env.

  

• Se ainda não tiver um índice de pesquisa, mantenha o valor "example-index" para AISEARCH_INDEX_NAME. Na Parte 2 deste tutorial vais criar o índice usando este nome. Se já criou anteriormente um índice de pesquisa que pretende usar, atualize o valor para corresponder ao nome desse índice de pesquisa.

• Se mudaste os nomes dos modelos quando os implementaste, atualiza os valores no .env ficheiro para corresponder aos nomes que usaste.

Instale a CLI do Azure e inicie sessão

Instala o CLI do Azure e inicia sessão a partir do ambiente de desenvolvimento local para que o seu código possa usar as suas credenciais de utilizador para ligar Azure serviços através do Foundry.

Na maioria dos casos, pode instalar o CLI do Azure a partir do seu 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

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

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

Verifica a tua 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.

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

Criar script auxiliar

Cria uma pasta para o teu 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.

Liberar 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, constróis a aplicação personalizada.