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

  • Artigo

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 pular essas etapas aqui.

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

Importante

Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Pré-requisitos

Criar um projeto

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

  1. Vá para a página inicial do Azure AI Foundry.
  2. Selecione + Criar projeto.
  3. Introduza um nome para o projeto. Mantenha todas as outras configurações como padrão.
  4. Os projetos são criados em hubs. Se você vir Criar um novo hub , selecione-o e especifique um nome. Em seguida, selecione Seguinte. (Se não vir Crie um novo hub, não se preocupe, é porque um novo está sendo criado para você.)
  5. Selecione Personalizar para especificar as propriedades do hub.
  6. Use os valores desejados, exceto Região. Recomendamos que você use East US2 ou Sweden Central para a região para esta série de tutoriais.
  7. Selecione Seguinte.
  8. Selecione Criar projeto.

Implementar 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 em um ponto de extremidade em tempo real a partir do catálogo de modelos do portal do AI Foundry:

  1. No painel de navegação 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 .

Criar um serviço Azure AI Search

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.

Nota

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.

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.

Gorjeta

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.

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 serviço Azure OpenAI.

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

Criar um novo ambiente Python

Primeiro você precisa criar um novo ambiente Python para usar para instalar o pacote necessário para este tutorial. 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.8. Se você não tiver uma versão adequada do Python instalada, você pode seguir 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, poderá criar 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.

Nota

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

Instalar pacotes

Instale azure-ai-projects(visualização) e azure-ai-inference (visualização), juntamente com outros pacotes necessários.

  1. Primeiro, crie um arquivo chamado requirements.txt na pasta do projeto. Adicione os seguintes pacotes ao arquivo:

    azure-ai-projects
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)

Configurar variáveis de ambiente

Sua cadeia de conexão de projeto é necessária para chamar o serviço Azure OpenAI 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 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.

Gorjeta

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

Aviso

Certifique-se de que você .env está em seu .gitignore arquivo para que você não acidentalmente verificá-lo em seu repositório git.

Clean up resources (Limpar 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