Partilhar via

Tutorial: Parte 1 - Configurar o ambiente de projeto e desenvolvimento para criar um aplicativo de recuperação de conhecimento (RAG) personalizado com o SDK do Azure AI Foundry

Neste tutorial, você usa o SDK do Azure AI Foundry (e outras bibliotecas) para criar, configurar e avaliar um aplicativo de chat para sua empresa de varejo chamado Contoso Trek. Sua empresa de varejo é especializada em equipamentos e roupas de camping ao ar livre. O aplicativo de bate-papo deve responder a perguntas sobre seus produtos e serviços. Por exemplo, o aplicativo de bate-papo pode responder a perguntas como "qual barraca é a mais à prova d'água?" ou "qual é o melhor saco-cama para o tempo frio?".

Este tutorial é parte um de um tutorial de três partes. Esta parte um prepara você para escrever código na parte dois e avaliar seu aplicativo de bate-papo na parte três. Nesta parte, você:

  • Criar um projeto
  • Criar um índice do Azure AI Search
  • Instalar a CLI do Azure e entrar
  • Instalar Python e pacotes
  • Implante modelos em seu projeto
  • Configurar as variáveis de ambiente

Se você concluiu outros tutoriais ou inícios rápidos, talvez já tenha criado alguns dos recursos necessários para este tutorial. Se tiver, sinta-se à vontade para ignorar essas etapas.

Este tutorial é parte um de um tutorial de três partes.

Pré-requisitos

Observação

Este tutorial usa um projeto baseado em hub. As etapas e o código mostrados aqui não funcionam para um projeto do Foundry. Para obter mais informações, consulte Tipos de projetos.

Criar um projeto baseado em hub

Para criar um projeto baseado em hub no Azure AI Foundry, siga estas etapas:

  1. Entre no Azure AI Foundry.

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

    • Se você não tiver nenhum projeto existente: siga as etapas em Guia de início rápido: introdução ao Azure AI Foundry para criar 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 você não estiver em um 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 no Azure AI 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, selecione Criar novo hub e forneça um nome.

      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

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). Implante esses modelos em seu projeto do Azure AI Foundry, usando este conjunto de etapas para cada modelo.

Estas etapas implantam um modelo num endpoint em tempo real a partir do portal do Azure AI Foundry catálogo de modelos:

Sugestão

Como você pode personalizar o painel esquerdo no portal do Azure AI Foundry, poderá ver itens diferentes dos mostrados nestas etapas. 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 Implantar.

    Captura de tela da página de detalhes do modelo com um botão para implantar o modelo.

  4. Deixe o nome de implantação padrão. selecione Implantar. 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 .

O objetivo com este aplicativo é fundamentar as respostas do modelo em seus dados personalizados. O índice de pesquisa é usado para recuperar documentos relevantes com base na pergunta do usuário.

Você precisa de um serviço e conexão do Azure AI Search para criar um índice de pesquisa.

Observação

A criação de um serviço Azure AI Search e índices de pesquisa subsequentes tem custos associados. Você pode ver detalhes sobre preços e níveis de preços para o serviço Azure AI Search na página de criação, para confirmar o custo antes de criar o recurso. Para este tutorial, recomendamos o uso de um nível de preço básico ou superior.

Se você já tiver um serviço Azure AI Search, poderá pular para a próxima seção.

Caso contrário, você pode criar um serviço Azure AI Search usando o portal do Azure.

Sugestão

Esta etapa é a única vez que você usa o portal do Azure nesta série de tutoriais. O resto do seu trabalho é feito no portal do Azure AI Foundry ou no seu ambiente de desenvolvimento local.

  1. Crie um serviço Azure AI Search no portal do Azure.
  2. Selecione o grupo de recursos e os detalhes da instância. Você pode ver detalhes sobre preços e níveis de preços nesta página.
  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 você já tiver uma conexão do Azure AI Search em seu projeto, poderá pular para Instalar a CLI do Azure e entrar.

No portal do Azure AI Foundry, verifique se há um recurso conectado do Azure AI Search.

  1. No Azure AI Foundry, vá para seu projeto e selecione Centro de gerenciamento no painel esquerdo.

  2. Na seção Recursos conectados, verifique se você tem uma conexão do tipo Azure AI Search.

  3. Se você tiver uma conexão do Azure AI Search, poderá pular para a próxima seção.

  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. Para selecionar e usar a opção de autenticação recomendada do Microsoft Entra ID , você também deve configurar o controle de acesso para o serviço Azure AI Search. Atribua as funções Colaborador de Dados do Índice de Pesquisa e Colaborador do Serviço de Pesquisa à sua conta de usuário. Para obter mais informações, consulte Conectar-se à Pesquisa de IA do Azure usando funções e Controle de acesso baseado em função no portal do Azure AI Foundry.

  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 você precisa criar um novo ambiente Python. NÃO instale pacotes em sua instalação global do python. Você deve sempre usar um ambiente virtual ou conda ao instalar pacotes python, caso contrário, você pode quebrar sua instalação global do Python.

Se necessário, instale o Python

Recomendamos o uso do Python 3.10 ou posterior, mas é necessário ter pelo menos o Python 3.9. 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 você já tiver o Python 3.10 ou superior instalado, crie um ambiente virtual usando os seguintes comandos:

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

Ativar o ambiente Python significa que quando você executa python ou pip a partir da linha de comando, você usa o interpretador Python contido na .venv pasta do seu aplicativo.

Observação

Você pode usar o deactivate comando para sair do ambiente virtual python e, posteriormente, reativá-lo quando necessário.

Instalar pacotes

Instale os pacotes necessários.

  1. Primeiro, 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

  2. Instale os pacotes necessários:

    pip install -r requirements.txt

Criar script auxiliar

Crie uma pasta para o seu trabalho. Crie um arquivo chamado config.py nesta pasta. Este script auxiliar é usado nas próximas duas partes da série de tutoriais. 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)

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.

Configurar variáveis de ambiente

A sua string de conexão do projeto é necessária para chamar o Azure OpenAI nos modelos do Azure AI 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 do Azure AI Foundry que você criou no início rápido do playground do Azure AI 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.

    A captura de tela mostra a página de visão geral de um projeto e o local da cadeia de conexão.

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

Instalar a CLI do Azure e entrar

Você instala a CLI do Azure e entra em seu ambiente de desenvolvimento local, para que possa usar suas credenciais de usuário para chamar o Azure OpenAI nos Modelos do Azure AI Foundry.

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

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

Mantenha esta janela do terminal aberta para executar seus scripts python a partir daqui também, agora que você entrou.

Limpeza de recursos

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

Mas não os exclua ainda, se você quiser criar um aplicativo de bate-papo 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.

Parte 2: Criar um aplicativo de chat personalizado com o SDK do Azure AI