Compartilhar via

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

  • Artigo

Neste tutorial, você usará o SDK do Azure AI Foundry (e outras bibliotecas) para criar, configurar, avaliar e avaliar um aplicativo de chat para sua empresa de varejo chamada Contoso Trek. Sua empresa de varejo é especializada em equipamentos e roupas de acampamento ao ar livre. O aplicativo de chat deve responder perguntas sobre seus produtos e serviços. Por exemplo, o aplicativo de chat pode responder a perguntas como "qual é a barraca mais impermeável?" ou "qual é o melhor saco de dormir para o frio?".

Este tutorial é a parte um de um tutorial de três partes. Esta parte um prepara você para escrever código na parte dois e avaliar o aplicativo de chat na parte três. Nesta parte, você:

  • Criar um projeto
  • Criar um índice da Pesquisa de IA do Azure
  • Instalar a CLI do Azure e entrar
  • Instalar o Python e os pacotes
  • Implantar modelos no projeto
  • Configurar suas variáveis de ambiente

Se você concluiu outros tutoriais ou guias de início rápido, talvez já tenha criado alguns dos recursos necessários para este tutorial. Se você tiver feito isso, fique à vontade para ignorar as presentes etapas.

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

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Pré-requisitos

Criar um projeto

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

  1. Vá para a página Início do Azure AI Foundry.
  2. Selecione + Criar projeto.
  3. Insira um nome para o projeto. Deixe todas as outras configurações com os valores padrão.
  4. Os projetos são criados em hubs. Se você vir a opção Criar novo hub selecione-a e especifique um nome. Em seguida, selecione Avançar. (Se você não vir Criar 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 Leste dos EUA2 ou Suécia Central para a região para esta série de tutoriais.
  7. Selecione Avançar.
  8. Selecione Criar projeto.

Implantar modelos

Você precisa de dois modelos para criar um aplicativo de chat baseado em RAG: um modelo de chat do OpenAI do Azure (gpt-4o-mini) e um modelo de inserção do OpenAI do Azure (text-embedding-ada-002). Implante estes modelos no seu projeto Azure AI Foundry, usando esse conjunto de etapas para cada modelo.

Essas etapas implantam um modelo em um ponto de extremidade em tempo real do catálogo de modelos 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 tela 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 implantá-lo.

  4. Deixe o Nome de implantação padrão. Escolha Implantar. Ou, se o modelo não estiver disponível em sua região, uma região diferente será selecionada para você e conectada ao seu projeto. Neste 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 de Pesquisa de IA do Azure

A meta 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.

Para criar um índice de pesquisa, você precisa de um serviço e de uma conexão da Pesquisa de IA do Azure.

Observação

Exitem custos associados à criação de um serviço Pesquisa de IA do Azure e dos índices de pesquisa subsequentes. Você pode ver os detalhes sobre preços e tipos de preço do serviço de Pesquisa de IA do Azure na página da criação para confirmar os custos antes de criar o recurso.

Se você já tiver um serviço Pesquisa de IA do Azure, poderá pular para a próxima seção.

Caso contrário, você poderá criar um serviço Pesquisa de IA do Azure usando o portal do Azure.

Dica

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

  1. Criar um serviço de Pesquisa de IA do Azure no portal do Azure.
  2. Selecione seu grupo de recursos e os detalhes da instância. Você pode conferir os detalhes de preços e tipos de preços nessa página.
  3. Continue por meio do assistente e selecione Revisar + atribuir para criar o recurso.
  4. Confirme os detalhes do seu serviço de Pesquisa de IA do Azure, incluindo os custos estimados.
  5. Selecione Criar para criar o serviço Pesquisa de IA do Azure.

Conectar a Pesquisa de IA do Azure ao seu projeto

Se já tem uma conexão da Pesquisa de IA do Azure no projeto, você pode ir diretamente para Instalar a CLI do Azure e entrar.

No portal Azure AI Foundry, verifique se há um recurso conectado à Pesquisa de IA do Azure.

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

  2. Na seção Recursos conectados, procure se você tem uma conexão do tipo Pesquisa de IA do Azure.

  3. Se você tem uma conexão da Pesquisa de IA do Azure, pode ir diretamente para a próxima seção.

  4. Caso contrário, selecione Nova conexão e, em seguida, Pesquisa de IA do Azure.

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

  6. Use a chave de API para autenticação.

    Observação

    Você pode usar o Microsoft Entra ID para autenticação. Se fizer isso, você também deverá configurar o controle de acesso para o serviço Pesquisa de IA do Azure. Atribua as funções de Colaborador de Dados do Índice de Pesquisa e Colaborador do Serviço de Pesquisa à sua conta de usuário. Se você não sabe fazer isso ou não tem as permissões necessárias, use a chave de API para Autenticação.

  7. Selecione Adicionar conexão.

Instalar a CLI do Azure e entrar

Instale a CLI do Azure e entre no seu ambiente de desenvolvimento local, para que você possa usar suas credenciais de usuário para chamar o serviço OpenAI do Azure.

Na maioria dos casos, você pode instalar a CLI do Azure do 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 específico ou configuração.

Depois de instalar a CLI do Azure, entre usando o comando az login e entre usando o navegador:

az login

Como alternativa, você pode fazer logon manualmente por meio do navegador com um código de dispositivo.

az login --use-device-code

Criar um ambiente do Python

Primeiro, você precisa criar um ambiente de Python que será usado para instalar o pacote necessário para este tutorial. NÃO instale pacotes na instalação global do Python. Você sempre deve usar um ambiente virtual ou conda ao instalar pacotes do Python, caso contrário, poderá interromper a instalação global do Python.

Se necessário, instale o Python

É recomendável usar o Python 3.10 ou posterior, mas ter pelo menos Python 3.8 é necessário. Se você não tiver uma versão adequada do Python instalada, poderá seguir as instruções no Tutorial do Python do VS Code para obter 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, ao executar python ou pip na linha de comando, você usará o interpretador Python contido na pasta .venv do seu aplicativo.

Observação

Você pode usar o comando deactivate para sair do ambiente virtual do Python e depois reativar quando necessário.

Instalar Pacotes

Instale o azure-ai-projects (versão prévia) e o azure-ai-inference (versão prévia), 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 seu trabalho. Crie um arquivo chamado config.py nessa pasta. Esse script auxiliar é usado nas próximas duas partes da série de tutoriais. Adicione os códigos a seguir:

# 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

A cadeia de conexão do projeto é necessária para chamar o serviço do OpenAI do Azure do seu código. Neste início rápido, você salva esse valor em um arquivo .env, que é um arquivo que contém variáveis de ambiente que seu aplicativo pode ler.

Crie um arquivo .env 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"

  • Localize a cadeia de conexão no projeto de IA do Azure Foundry criado no início rápido do playground de 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 arquivo .env.

    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 tem um índice de pesquisa, mantenha o valor “example-index” para AISEARCH_INDEX_NAME. Na segunda parte deste tutorial, você criará o índice usando esse nome. Se você já criou um índice de pesquisa que deseja usar, atualize o valor para que ele corresponda ao nome desse índice de pesquisa.

  • Se você alterou os nomes dos modelos ao implantá-los, atualize os valores no arquivo .env para que corresponda aos nomes usados.

Dica

Se estiver trabalhando no VS Code, feche e reabra a janela do terminal depois de salvar as alterações no arquivo .env.

Aviso

Certifique-se de que .env esteja em seu arquivo .gitignore para que você não faça check-in dele acidentalmente no repositório git.

Limpar os recursos

Para evitar incorrer em custos desnecessários do Azure, exclua os recursos criados neste tutorial se eles não forem mais necessários. Para gerenciar os recursos, use o portal do Azure.

Mas não os exclua ainda, se você quiser criar um aplicativo de chat na próxima parte desta série de tutoriais.

Próxima etapa

Neste tutorial, você configura tudo de que precisa para criar um aplicativo de chat personalizado com o SDK de IA do Azure. Na próxima parte desta série de tutoriais, você criará o aplicativo personalizado.

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