Condividi tramite

Esercitazione: Parte 1: Configurare un ambiente di sviluppo e progetto per creare un'app di recupero delle conoscenze personalizzata con Azure AI Foundry SDK

  • Articolo

In questa esercitazione si usa Azure AI Foundry SDK (e altre librerie) per creare, configurare e valutare un'app di chat per la società di vendita al dettaglio denominata Contoso Trek. La società di vendita al dettaglio è specializzata in attrezzatura da campeggio all'aperto e abbigliamento. L'app di chat deve rispondere a domande sui prodotti e sui servizi. Ad esempio, l'app di chat può rispondere a domande come "quale tenda è la più impermeabile?" o "qual è il miglior sacco a pelo per il freddo?".

Questa esercitazione è la prima di tre parti. Questa parte si prepara a scrivere codice nella seconda parte e valutare l'app di chat nella terza parte. In questa parte:

  • Creare un progetto
  • Creare un indice di Azure AI Search
  • Installare l'interfaccia della riga di comando di Azure ed eseguire l'accesso
  • Installare Python e pacchetti
  • Distribuire modelli nel progetto
  • Configurare le variabili di ambiente

Se sono state completate altre esercitazioni o guide introduttive, è possibile che siano già state create alcune delle risorse necessarie per questa esercitazione. In caso affermativo, ignorare questi passaggi.

Questa esercitazione è la prima di tre parti.

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Prerequisiti

Creare un progetto

Per creare un progetto in Azure AI Foundry, seguire questa procedura:

  1. Passare alla home page di Azure AI Foundry.
  2. Selezionare + Crea progetto.
  3. Immettere un nome per il progetto. Mantenere tutte le altre impostazioni come predefinite.
  4. I progetti vengono creati negli hub. Se viene visualizzato Crea un nuovo hub , selezionarlo e specificare un nome. Quindi seleziona Avanti. (Se non viene visualizzato Creare un nuovo hub, non preoccuparti, perché ne viene creato uno nuovo.
  5. Selezionare Personalizza per specificare le proprietà dell'hub.
  6. Usare tutti i valori desiderati, ad eccezione dell'area. È consigliabile usare Stati Uniti orientali 2 o Svezia centrale per l'area per questa serie di esercitazioni.
  7. Selezionare Avanti.
  8. Seleziona Crea progetto.

Distribuire i modelli

Sono necessari due modelli per creare un'app di chat basata su RAG: un modello di chat Azure OpenAI (gpt-4o-mini) e un modello di incorporamento Azure OpenAI (text-embedding-ada-002). Distribuire questi modelli nel progetto Azure AI Foundry usando questo set di passaggi per ogni modello.

Questi passaggi distribuiscono un modello in un endpoint in tempo reale dal catalogo dei modelli del portale di Azure AI Foundry:

  1. Nel riquadro di spostamento sinistro selezionare Catalogo modelli.

  2. Selezionare il modello gpt-4o-mini dall'elenco dei modelli. È possibile usare la barra di ricerca per trovarla.

    Screenshot della pagina di selezione del modello.

  3. Nella pagina dei dettagli del modello selezionare Distribuisci.

    Screenshot della pagina dei dettagli del modello con un pulsante per distribuire il modello.

  4. Lasciare il nome di distribuzione predefinito. selezionare Distribuisci. In alternativa, se il modello non è disponibile nell'area, viene selezionata un'area diversa per l'utente e la connessione al progetto. In questo caso, selezionare Connetti e distribuisci.

Dopo aver distribuito gpt-4o-mini, ripetere i passaggi per distribuire il modello text-embedding-ada-002.

L'obiettivo di questa applicazione è quello di fondare le risposte del modello sui dati personalizzati. L'indice di ricerca viene utilizzato per recuperare i documenti pertinenti in base alla domanda dell'utente.

Per creare un indice di ricerca, è necessario un servizio di Ricerca intelligenza artificiale di Azure e una connessione.

Nota

La creazione di un servizio Azure AI Search e degli indici di ricerca successivi comportano costi associati. È possibile visualizzare informazioni dettagliate sui prezzi e sui piani tariffari per il servizio Ricerca intelligenza artificiale di Azure nella pagina di creazione per confermare i costi prima di creare la risorsa. Per questa esercitazione, è consigliabile usare un piano tariffario Basic o superiore.

Se si dispone già di un servizio Azure AI Search, è possibile passare alla sezione successiva.

In caso contrario, è possibile creare un servizio Azure AI Search usando il portale di Azure.

Suggerimento

Questo passaggio è l'unica volta che si usa la portale di Azure in questa serie di esercitazioni. Il resto del lavoro viene eseguito nel portale di Azure AI Foundry o nell'ambiente di sviluppo locale.

  1. Creare un servizio ricerca di intelligenza artificiale di Azure nel portale di Azure.
  2. Selezionare il gruppo di risorse e i dettagli dell'istanza. In questa pagina sono disponibili informazioni dettagliate sui piani tariffari e sui piani tariffari.
  3. Continuare con la procedura guidata e selezionare Rivedi e assegna per creare la risorsa.
  4. Verificare i dettagli del servizio Ricerca intelligenza artificiale di Azure, incluso il costo stimato.
  5. Selezionare Crea per creare il servizio Azure AI Search.

Connettere Azure AI Search al progetto

Se nel progetto è già presente una connessione di Ricerca intelligenza artificiale di Azure, è possibile passare a Installare l'interfaccia della riga di comando di Azure ed eseguire l'accesso.

Nel portale di Azure AI Foundry verificare la presenza di una risorsa connessa ricerca di intelligenza artificiale di Azure.

  1. In Azure AI Foundry passare al progetto e selezionare Centro di gestione nel riquadro sinistro.

  2. Nella sezione Risorse connesse verificare se si dispone di una connessione di tipo Ricerca di intelligenza artificiale di Azure.

  3. Se si ha una connessione di Ricerca intelligenza artificiale di Azure, è possibile passare alla sezione successiva.

  4. In caso contrario, selezionare Nuova connessione e quindi Ricerca di intelligenza artificiale di Azure.

  5. Trovare il servizio Ricerca intelligenza artificiale di Azure nelle opzioni e selezionare Aggiungi connessione.

  6. Usare la chiave API per l'autenticazione.

    Importante

    L'opzione Chiave API non è consigliata per l'ambiente di produzione. Per selezionare e usare l'opzione di autenticazione consigliata di Microsoft Entra ID, è necessario configurare anche il controllo di accesso per l'servizio di ricerca di Intelligenza artificiale di Azure. Assegnare i ruoli Collaboratore ai dati dell'indice di ricerca e Collaboratore servizio di ricerca all'account utente. Per altre informazioni, vedere Connettersi a Ricerca di intelligenza artificiale di Azure usando i ruoli e il controllo degli accessi in base al ruolo nel portale di Azure AI Foundry.

  7. Selezionare Aggiungi connessione.

Installare l'interfaccia della riga di comando di Azure ed eseguire l'accesso

Si installa l'interfaccia della riga di comando di Azure e si accede dall'ambiente di sviluppo locale, in modo da poter usare le credenziali utente per chiamare il servizio OpenAI di Azure.

Nella gran parte dei casi è possibile installare l'interfaccia della riga di comando di Azure dal terminale usando il comando seguente:

winget install -e --id Microsoft.AzureCLI

Se questi comandi non funzionano per il sistema operativo o l'installazione specifici, è possibile seguire le istruzioni in Come installare l'interfaccia della riga di comando di Azure.

Dopo aver installato l'interfaccia della riga di comando di Azure, accedere usando il comando az login e registrarsi tramite il browser:

az login

In alternativa, è possibile accedere manualmente tramite il browser con un codice del dispositivo.

az login --use-device-code

Creare un nuovo ambiente Python

Prima di tutto è necessario creare un nuovo ambiente Python da usare per installare il pacchetto necessario per questa esercitazione. NON installare i pacchetti nell'installazione globale di Python. Quando si installano i pacchetti Python, è necessario usare sempre un ambiente virtuale o Conda, altrimenti si rischia di interrompere l'installazione di Python nel sistema.

Se necessario, installare Python

È consigliabile usare Python 3.10 o versione successiva; è comunque necessario avere almeno Python 3.8. Se non è installata una versione appropriata di Python, seguire le istruzioni riportate in Esercitazione di Vs Code Python, che descrive il modo più semplice per installare Python nel sistema operativo.

Creare un ambiente virtuale

Se Python 3.10 o versione successiva è già installato, è possibile creare un ambiente virtuale usando i comandi seguenti:

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

L'attivazione dell'ambiente Python implica che quando si esegue python o pip dalla riga di comando, si usa l'interprete Python contenuto nella cartella .venv dell'applicazione.

Nota

Per uscire dall'ambiente virtuale Python è possibile usare il comando deactivate. Potrà poi essere riattivato successivamente, quando necessario.

Installare i pacchetti

Installare azure-ai-projects(anteprima) e azure-ai-inference (anteprima), insieme ad altri pacchetti necessari.

  1. Creare prima di tutto un file denominato requirements.txt nella cartella del progetto. Aggiungere i pacchetti seguenti al file:

    azure-ai-projects
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api

  2. Installare i pacchetti necessari:

    pip install -r requirements.txt

Creare uno script helper

Creare una cartella per il lavoro. Creare un file denominato config.py in questa cartella. Questo script helper viene usato nelle due parti successive della serie di esercitazioni. Aggiungere il codice seguente:

# 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)

Nota

Questo script usa anche un pacchetto non ancora installato, azure.monitor.opentelemetry. Questo pacchetto verrà installato nella parte successiva della serie di esercitazioni.

Configurare le variabili di ambiente

Il progetto stringa di connessione è necessario per chiamare il servizio Azure OpenAI dal codice. In questa guida introduttiva si salva questo valore in un file, ovvero un .env file che contiene variabili di ambiente che l'applicazione può leggere.

Creare un file .env e incollare il codice seguente:

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"

  • Trovare il stringa di connessione nel progetto Azure AI Foundry creato nell'argomento di avvio rapido di Azure AI Foundry Playground. Aprire il progetto, quindi trovare il stringa di connessione nella pagina Panoramica. Copiare il stringa di connessione e incollarlo nel .env file.

    Screenshot che mostra la pagina di panoramica di un progetto e la posizione del stringa di connessione.

  • Se non si dispone ancora di un indice di ricerca, mantenere il valore "example-index" per AISEARCH_INDEX_NAME. Nella parte 2 di questa esercitazione si creerà l'indice usando questo nome. Se in precedenza è stato creato un indice di ricerca da usare, aggiornare il valore in modo che corrisponda al nome dell'indice di ricerca.

  • Se sono stati modificati i nomi dei modelli quando sono stati distribuiti, aggiornare i valori nel .env file in modo che corrispondano ai nomi usati.

Suggerimento

Se si lavora in VS Code, chiudere e riaprire la finestra del terminale dopo aver salvato le modifiche nel .env file.

Avviso

Assicurarsi che si .env trovi nel .gitignore file in modo da non archiviarlo accidentalmente nel repository Git.

Pulire le risorse

Per evitare di incorrere in costi di Azure superflui, è necessario eliminare le risorse create in questo avvio rapido, se non sono più richieste. Per gestire le risorse, è possibile usare il portale di Azure.

Ma non eliminarli ancora, se si vuole creare un'app di chat nella parte successiva di questa serie di esercitazioni.

Passaggio successivo

In questa esercitazione si configurano tutti gli elementi necessari per creare un'app di chat personalizzata con Azure AI SDK. Nella parte successiva di questa serie di esercitazioni si compila l'app personalizzata.

Parte 2: Creare un'app di chat personalizzata con Azure AI SDK