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

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

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

• Uma conta Azure com subscrição ativa e função de Proprietário ou Contribuinte 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.

     

   • Se não estiver num projeto: Selecione Criar novo no canto superior direito para criar um novo projeto 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.

     

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

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 incorporação do 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 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 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.

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

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

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

1. Crie um serviço Azure AI Search no portal do 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 Criar para criar o serviço Azure AI Search.

Conectar a Pesquisa de IA do Azure ao seu projeto

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

No portal Foundry, verifique se existe 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 seção Recursos conectados, verifique se você tem uma conexão do tipo Azure AI Search.

3. Se tiver uma ligação Azure AI Search, pode saltar os próximos passos.

4. Caso contrário, selecione Nova conexão e, em seguida , Azure AI Search.

5. Encontre seu serviço Azure AI Search 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 Microsoft Entra ID , que requer os papéis de Contribuidor de Dados do Índice de Pesquisa e Contribuidor do Serviço de Pesquisa (configurados em Pré-requisitos). Para obter mais informações, consulte Conectar-se à Pesquisa de IA do Azure usando funções. 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 em sua instalação global do 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, instale o Python

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

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

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

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

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

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
   

Verifique a configuração

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

Referências: Azure AI Projects biblioteca cliente, 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.

Configurar variáveis de ambiente

A sua string de ligação ao projeto é necessária para chamar Azure OpenAI no Microsoft Foundry Models 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 início rápido do playground Foundry. 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 .env arquivo.

  

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

Instalar a CLI do Azure e entrar

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

Na maioria dos casos, você pode instalar a 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

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

Depois de instalar a CLI do Azure, entre usando o az login comando e entre usando o 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.

Limpeza de recursos

Para evitar custos desnecessários do Azure, elimina os recursos que criaste neste tutorial se já não forem necessários. Para gerenciar recursos, você pode usar o portal do 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, você configura tudo o que precisa para criar um aplicativo de chat personalizado com o SDK da IA do Azure. Na próxima parte desta série de tutoriais, você cria o aplicativo personalizado.