Come eseguire valutazioni online con Azure AI Foundry SDK

Articolo
01/23/2025

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.

Questo articolo illustra come eseguire valutazioni online in modo continuo con Azure AI Foundry SDK. Le valutazioni negli ambienti di pre-produzione sono essenziali per garantire che l'applicazione sia sicura, efficiente e produa risultati di alta qualità. Tuttavia, la valutazione non si arresta dopo la distribuzione dell'applicazione. Nell'ambiente di produzione, possono cambiare vari aspetti, ad esempio i tipi di query che gli utenti inviano all'applicazione, che possono influenzare le prestazioni dell'applicazione. Per mantenere un elevato grado di osservabilità nell'applicazione di intelligenza artificiale generativa di produzione, è importante tracciare e valutare continuamente i dati dell'applicazione. In questo modo, è possibile mantenere la fiducia nella sicurezza, nella qualità e nelle prestazioni dell'applicazione.

Funzionamento della valutazione online

In questa sezione si apprenderà come funziona la valutazione online, come si integra con Application Insights di Monitoraggio di Azure e come usarla per eseguire valutazioni continue sui dati di traccia dalle applicazioni di intelligenza artificiale generative.

Dopo aver instrumentato l'applicazione per inviare dati di traccia ad Application Insights, configurare una pianificazione di valutazione online per valutare continuamente questi dati. La valutazione online è un servizio che usa il calcolo di Intelligenza artificiale di Azure per eseguire continuamente un set configurabile di analizzatori. Dopo aver configurato una pianificazione di valutazione online con Azure AI Foundry SDK, viene eseguita in base a una pianificazione configurabile. Ogni volta che viene eseguito il processo pianificato, esegue i passaggi seguenti:

Eseguire query sui dati di traccia dell'applicazione dalla risorsa di Application Insights connessa usando la query Kusto (KQL) fornita.
Eseguire ogni analizzatore sui dati di traccia e calcolare ogni metrica (ad esempio, base: 3).
Scrivere i punteggi di valutazione in ogni traccia usando convenzioni semantiche standardizzate.

Nota

La valutazione online supporta le stesse metriche della valutazione di Intelligenza artificiale di Azure. Per altre informazioni sul funzionamento della valutazione e sulle metriche di valutazione supportate, vedere Valutare l'applicazione generativa per intelligenza artificiale con Azure AI Evaluation SDK.

Si supponga, ad esempio, di avere un'applicazione di chat distribuita che riceve molte domande sui clienti su base giornaliera. Si vuole valutare continuamente la qualità delle risposte dell'applicazione. Si configura una pianificazione di valutazione online con una ricorrenza giornaliera. È possibile configurare gli analizzatori: base, coerenza e fluenza. Ogni giorno, il servizio calcola i punteggi di valutazione per queste metriche e scrive nuovamente i dati in Application Insights per ogni traccia raccolta durante l'intervallo di tempo di ricorrenza (in questo esempio le ultime 24 ore). È quindi possibile eseguire query sui dati da ogni traccia e rendere accessibili in Azure AI Foundry e In Application Insights di Monitoraggio di Azure.

I risultati della valutazione sono stati riscritto in ogni traccia all'interno di Application Insights seguendo le convenzioni seguenti. Viene aggiunto un intervallo univoco a ogni traccia per ogni metrica di valutazione:

Proprietà	Tabella di Application Insights	Campi per un determinato operation_ID	Valore di esempio
Metrica di valutazione	tracce, AppTraces	`customDimensions[“event.name”]`	`gen_ai.evaluation.relevance`
Punteggio della metrica di valutazione	tracce, AppTraces	`customDimensions[“gen_ai.evaluation.score”]`	`3`
Commento della metrica di valutazione (se applicabile)	tracce, AppTraces	`message`	`{“comment”: “I like the response”}`

Dopo aver compreso il funzionamento della valutazione online e la modalità di connessione ad Application Insights di Monitoraggio di Azure, il passaggio successivo consiste nel configurare il servizio.

Configurare la valutazione online

In questa sezione si apprenderà come configurare una pianificazione di valutazione online per monitorare continuamente l'applicazione di intelligenza artificiale generativa distribuita. Azure AI Foundry SDK offre funzionalità di questo tipo. Un'API Python e supporta tutte le funzionalità disponibili nelle valutazioni locali. Usare la procedura seguente per inviare la pianificazione di valutazione online sui dati usando analizzatori predefiniti o personalizzati.

Nota

Le valutazioni sono supportate solo nelle stesse aree delle metriche di rischio e sicurezza assistita dall'intelligenza artificiale.

Prerequisiti

Completare i passaggi prerequisiti seguenti per configurare l'ambiente e l'autenticazione per le risorse necessarie:

Una sottoscrizione di Azure.
Gruppo di risorse in un'area supportata dalla valutazione.
Nuova identità gestita assegnata dall'utente nello stesso gruppo di risorse e nella stessa area. Prendere nota di clientId. Sarà necessario in un secondo momento.
Un hub di intelligenza artificiale di Azure nello stesso gruppo di risorse e nella stessa area.
Un progetto di Intelligenza artificiale di Azure in questo hub, vedere Creare un progetto nel portale di Azure AI Foundry.
Una risorsa di Application Insights di Monitoraggio di Azure.
Passare alla pagina hub in portale di Azure e aggiungere una risorsa di Application Insights, vedere Aggiornare app Azure lication Insights e Registro Azure Container.
Distribuzione OpenAI di Azure con il modello GPT che supporta chat completion, ad esempio gpt-4.
Connection String per il progetto di intelligenza artificiale di Azure per creare AIProjectClient facilmente l'oggetto. È possibile ottenere il stringa di connessione progetto in Dettagli progetto dalla pagina Panoramica del progetto.
Passare alla risorsa di Application Insights nella portale di Azure e usare la scheda Controllo di accesso (IAM) per aggiungere il Log Analytics Contributor ruolo all'identità gestita assegnata dall'utente creata in precedenza.
Collegare l'identità gestita assegnata dall'utente al progetto.
Passare a Servizi di intelligenza artificiale di Azure nella portale di Azure e usare la scheda Controllo di accesso (IAM) per aggiungere il Cognitive Services OpenAI Contributor ruolo all'identità gestita assegnata dall'utente creata in precedenza.

Istruzioni di installazione

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

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

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

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

python3 -m venv .venv
source .venv/bin/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.

È anche possibile creare un nuovo ambiente Python usando conda:

conda create -n online-evaluation
conda activate online-evaluation

Installare i pacchetti necessari:

pip install azure-identity azure-ai-projects azure-ai-ml

Suggerimento

Facoltativamente, è possibile usare pip install azure-ai-evaluation se si vuole un'esperienza code-first per recuperare l'ID dell'analizzatore per gli analizzatori predefiniti nel codice. Per informazioni su come eseguire questa operazione, vedere Specifica di analizzatori dalla libreria dell'analizzatore.

Configurare la traccia per l'applicazione di intelligenza artificiale generativa

Prima di configurare la valutazione online, assicurarsi di aver configurato la traccia per l'applicazione di intelligenza artificiale generativa.

Uso del nome del servizio nei dati di traccia

Per identificare l'applicazione tramite un ID univoco in Application Insights, è possibile usare la proprietà OpenTelemetry del nome del servizio nei dati di traccia. Ciò è particolarmente utile se si registrano dati da più applicazioni alla stessa risorsa di Application Insights e si vuole distinguerli. Ad esempio, si supponga di avere due applicazioni: App-1 e App-2, con traccia configurata per registrare i dati nella stessa risorsa di Application Insights. Forse si vuole configurare App-1 per essere valutato continuamente in base alla pertinenza e all'app-2 per essere valutato in modo continuo in base a groundedness. È possibile usare il nome del servizio per distinguere le applicazioni nelle configurazioni di valutazione online.

Per configurare la proprietà del nome del servizio, è possibile eseguire questa operazione direttamente nel codice dell'applicazione seguendo i passaggi, vedere Uso di più provider di traccia con risorse diverse. In alternativa, è possibile impostare la variabile OTEL_SERVICE_NAME di ambiente prima di distribuire l'app. Per altre informazioni sull'uso del nome del servizio, vedere Variabili di ambiente ROUTE e Convenzioni semantiche delle risorse del servizio.

Per altre informazioni sull'uso del nome del servizio per distinguere le applicazioni di intelligenza artificiale generative, vedere traccia.

Eseguire query sui dati di traccia archiviati in Application Insights

Usando il Linguaggio di query Kusto (KQL) è possibile eseguire query sui dati di traccia dell'applicazione di intelligenza artificiale generati da Application Insights per usarli per la valutazione online continua. Se si usa il pacchetto Di traccia di Intelligenza artificiale di Azure per tracciare l'applicazione di intelligenza artificiale generativa, è possibile usare la query Kusto seguente:

Importante

La query KQL usata dal servizio di valutazione online deve restituire le colonne seguenti: operation_Id, operation_ParentIde gen_ai_response_id. Inoltre, ogni analizzatore ha i propri requisiti di dati di input. La query KQL deve restituire queste colonne da usare come input per gli analizzatori stessi. Per un elenco dei requisiti dei dati per gli analizzatori, vedere Requisiti dei dati per gli analizzatori predefiniti.

let gen_ai_spans = (
    dependencies
    | where isnotnull(customDimensions["gen_ai.system"])
    | extend response_id = tostring(customDimensions["gen_ai.response.id"])
    | project id, operation_Id, operation_ParentId, timestamp, response_id
);
let gen_ai_events = (
    traces
    | where message in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
        or tostring(customDimensions["event.name"]) in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
    | project 
        id = operation_ParentId, 
        operation_Id, 
        operation_ParentId, 
        user_input = iff(
            message == "gen_ai.user.message" or tostring(customDimensions["event.name"]) == "gen_ai.user.message", 
            parse_json(iff(message == "gen_ai.user.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        system = iff(
            message == "gen_ai.system.message" or tostring(customDimensions["event.name"]) == "gen_ai.system.message", 
            parse_json(iff(message == "gen_ai.system.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        llm_response = iff(
            message == "gen_ai.choice", 
            parse_json(tostring(parse_json(tostring(customDimensions["gen_ai.event.content"])).message)).content, 
            iff(tostring(customDimensions["event.name"]) == "gen_ai.choice", parse_json(parse_json(message).message).content, "")
        )
    | summarize 
        operation_ParentId = any(operation_ParentId), 
        Input = maxif(user_input, user_input != ""), 
        System = maxif(system, system != ""), 
        Output = maxif(llm_response, llm_response != "") 
    by operation_Id, id
);
gen_ai_spans
| join kind=inner (gen_ai_events) on id, operation_Id
| project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id

Se si usa la OTEL_SERVICE_NAME variabile di ambiente nell'applicazione di intelligenza artificiale generativa per impostare il nome del servizio, è possibile eseguire una query per l'interno della cloud_RoleName pianificazione di valutazione online aggiungendo la riga seguente alla query Kusto (KQL):

| where cloud_RoleName == "service_name"

Facoltativamente, è possibile usare l'operatore sample o l'operatore take nella query Kusto in modo che restituisca solo un subset di tracce. Poiché le valutazioni assistita dall'intelligenza artificiale possono essere costose su larga scala, questo approccio consente di controllare i costi valutando solo un campione casuale (o n tracce) dei dati.

Configurare la valutazione online con Azure AI Project SDK

È possibile inviare un processo pianificato per la valutazione online con Azure AI Project SDK tramite un'API Python. Vedere lo script seguente per informazioni su come configurare la valutazione online con analizzatori di prestazioni e qualità (ai-assisted). Per visualizzare un elenco completo degli analizzatori supportati, vedere Valutare con Azure AI Evaluation SDK. Per informazioni su come usare analizzatori personalizzati, vedere Analizzatori personalizzati.

Per iniziare, importare i pacchetti necessari e configurare le variabili necessarie:

from azure.ai.projects import AIProjectClient 
from azure.identity import DefaultAzureCredential 
from azure.ai.projects.models import ( 
    ApplicationInsightsConfiguration,
    EvaluatorConfiguration,
    EvaluationSchedule,
    RecurrenceTrigger,
)
from azure.ai.evaluation import CoherenceEvaluator 

# This sample includes the setup for an online evaluation schedule using the Azure AI Project SDK and Azure AI Evaluation SDK
# The schedule is configured to run daily over the collected trace data while running two evaluators: CoherenceEvaluator and RelevanceEvaluator
# This sample can be modified to fit your application's requirements

# Name of your online evaluation schedule
SAMPLE_NAME = "online_eval_name"

# Connection string to your Azure AI Foundry project
# Currently, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
PROJECT_CONNECTION_STRING = "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"

# Your Application Insights resource ID
APPLICATION_INSIGHTS_RESOURCE_ID = "appinsights_resource_id"

# Kusto Query Language (KQL) query to query data from Application Insights resource
# This query is compatible with data logged by the Azure AI Inferencing Tracing SDK (linked in documentation)
# You can modify it depending on your data schema
# The KQL query must output these required columns: operation_ID, operation_ParentID, and gen_ai_response_id
# You can choose which other columns to output as required by the evaluators you are using
KUSTO_QUERY = "let gen_ai_spans=(dependencies | where isnotnull(customDimensions[\"gen_ai.system\"]) | extend response_id = tostring(customDimensions[\"gen_ai.response.id\"]) | project id, operation_Id, operation_ParentId, timestamp, response_id); let gen_ai_events=(traces | where message in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") or tostring(customDimensions[\"event.name\"]) in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") | project id= operation_ParentId, operation_Id, operation_ParentId, user_input = iff(message == \"gen_ai.user.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.user.message\", parse_json(iff(message == \"gen_ai.user.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), system = iff(message == \"gen_ai.system.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.system.message\", parse_json(iff(message == \"gen_ai.system.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), llm_response = iff(message == \"gen_ai.choice\", parse_json(tostring(parse_json(tostring(customDimensions[\"gen_ai.event.content\"])).message)).content, iff(tostring(customDimensions[\"event.name\"]) == \"gen_ai.choice\", parse_json(parse_json(message).message).content, \"\")) | summarize operation_ParentId = any(operation_ParentId), Input = maxif(user_input, user_input != \"\"), System = maxif(system, system != \"\"), Output = maxif(llm_response, llm_response != \"\") by operation_Id, id); gen_ai_spans | join kind=inner (gen_ai_events) on id, operation_Id | project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id"

Definire quindi un client e una distribuzione GPT openAI di Azure (ad esempio GPT-4) che verrà usata per eseguire la pianificazione della valutazione online. Connettersi anche alla risorsa di Application Insights:

# Connect to your Azure AI Foundry Project
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=PROJECT_CONNECTION_STRING
)

# Connect to your Application Insights resource 
app_insights_config = ApplicationInsightsConfiguration(
    resource_id=APPLICATION_INSIGHTS_RESOURCE_ID,
    query=KUSTO_QUERY
)

# Connect to your Azure OpenAI Service resource. You must use a GPT model deployment for this example.
deployment_name = "gpt-4"
api_version = "2024-08-01-preview"

# This is your Azure OpenAI Service connection name, which can be found in your Azure AI Foundry project under the 'Models + Endpoints' tab.
default_connection = project_client.connections._get_connection(
    "aoai_connection_name"
)

model_config = {
    "azure_deployment": deployment_name,
    "api_version": api_version,
    "type": "azure_openai",
    "azure_endpoint": default_connection.properties["target"]
}

Configurare quindi gli analizzatori da usare:

# RelevanceEvaluator
# id for each evaluator can be found in your Azure AI Foundry registry - please see documentation for more information
# init_params is the configuration for the model to use to perform the evaluation
# data_mapping is used to map the output columns of your query to the names required by the evaluator
relevance_evaluator_config = EvaluatorConfiguration(
    id="azureml://registries/azureml-staging/models/Relevance-Evaluator/versions/4",
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

# CoherenceEvaluator
coherence_evaluator_config = EvaluatorConfiguration(
    id=CoherenceEvaluator.id,
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

Infine, definire la ricorrenza e creare la pianificazione:

Nota: nei passaggi dei prerequisiti è stata creata un'identità gestita assegnata dall'utente per autenticare la pianificazione di valutazione online alla risorsa di Application Insights. L'oggetto AzureMSIClientIdproperties nel parametro della EvaluationSchedule classe è l'oggetto clientId di questa identità.

# Frequency to run the schedule
recurrence_trigger = RecurrenceTrigger(frequency="day", interval=1)

# Dictionary of evaluators
evaluators = {
    "relevance": relevance_evaluator_config,
    "coherence" : coherence_evaluator_config
}

name = SAMPLE_NAME
description = f"{SAMPLE_NAME} description"
# AzureMSIClientId is the clientID of the User-assigned managed identity created during set-up - see documentation for how to find it
properties = {"AzureMSIClientId": "your_client_id"}

# Configure the online evaluation schedule
evaluation_schedule = EvaluationSchedule(
    data=app_insights_config,
    evaluators=evaluators,
    trigger=recurrence_trigger,
    description=description,
    properties=properties)

# Create the online evaluation schedule 
created_evaluation_schedule = project_client.evaluations.create_or_replace_schedule(name, evaluation_schedule)
print(f"Successfully submitted the online evaluation schedule creation request - {created_evaluation_schedule.name}, currently in {created_evaluation_schedule.provisioning_state} state.")

Eseguire operazioni su una pianificazione di valutazione online

È possibile ottenere, elencare e disabilitare le pianificazioni di valutazione online aggiungendo il codice seguente allo script di configurazione della valutazione online:

Avviso: attendere una piccola quantità di tempo (circa 30 secondi) tra la creazione di una pianificazione di valutazione online e l'esecuzione dell'API get_schedule() .

Ottenere una pianificazione di valutazione online:

name = "<my-online-evaluation-name>"
get_evaluation_schedule = project_client.evaluations.get_schedule(name)

Elencare tutte le pianificazioni di valutazione online:

count = 0
for evaluation_schedule in project_client.evaluations.list_schedule():
    count += 1
        print(f"{count}. {evaluation_schedule.name} "
        f"[IsEnabled: {evaluation_schedule.is_enabled}]")
        print(f"Total evaluation schedules: {count}")

Disabilitare (eliminazione temporanea) la pianificazione della valutazione online:

name = "<my-online-evaluation-name>"
project_client.evaluations.disable_schedule(name)

Condividi tramite

Come eseguire valutazioni online con Azure AI Foundry SDK

Funzionamento della valutazione online

Configurare la valutazione online

Prerequisiti

Istruzioni di installazione

Creare un nuovo ambiente Python

Se necessario, installare Python

Creare un ambiente virtuale

Installare i pacchetti necessari:

Configurare la traccia per l'applicazione di intelligenza artificiale generativa

Uso del nome del servizio nei dati di traccia

Eseguire query sui dati di traccia archiviati in Application Insights

Configurare la valutazione online con Azure AI Project SDK

Eseguire operazioni su una pianificazione di valutazione online

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Come eseguire valutazioni online con Azure AI Foundry SDK

Funzionamento della valutazione online

Configurare la valutazione online

Prerequisiti

Istruzioni di installazione

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

Creare un nuovo ambiente Python

Se necessario, installare Python

Creare un ambiente virtuale

Installare i pacchetti necessari:

Configurare la traccia per l'applicazione di intelligenza artificiale generativa

Uso del nome del servizio nei dati di traccia

Eseguire query sui dati di traccia archiviati in Application Insights

Configurare la valutazione online con Azure AI Project SDK

Eseguire operazioni su una pianificazione di valutazione online

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive