Eseguire valutazioni nel cloud usando Microsoft Foundry SDK

Questo articolo illustra come eseguire valutazioni nel cloud per i test di pre-distribuzione in un set di dati di test.

Usare le valutazioni cloud per la maggior parte degli scenari, in particolare quando si testano su larga scala, integrando valutazioni in pipeline di integrazione continua e recapito continuo (CI/CD) o eseguendo test di pre-distribuzione. L'esecuzione di valutazioni nel cloud elimina la necessità di gestire l'infrastruttura di calcolo locale e supporta flussi di lavoro di test automatizzati su larga scala. È anche possibile pianificare le valutazioni da eseguire su base ricorrente o configurare la valutazione continua per valutare automaticamente le risposte degli agenti campionati nell'ambiente di produzione.

I risultati della valutazione cloud vengono archiviati nel progetto Foundry. È possibile esaminare i risultati nel portale, recuperarli tramite l'SDK o instradarli ad Application Insights, se connessi. La valutazione cloud supporta tutti gli analizzatori predefiniti curati da Microsoft e i propri analizzatori personalizzati. Gli analizzatori vengono gestiti nel catalogo dell'analizzatore con lo stesso ambito di progetto, il controllo degli accessi in base al ruolo.

Suggerimento

Per esempi eseguibili completi, vedere gli esempi di valutazione di Python SDK in GitHub.

Come funziona la valutazione del cloud

Una valutazione cloud prevede tre passaggi:

  1. Definire gli elementi da valutare. Descrivi la struttura dei dati (il data_source_config) e i valutatori (criteri di valutazione) che la valutano.
  2. Creare la valutazione. Inviare la definizione usando openai_client.evals.create().
  3. Eseguirlo e leggere i risultati. Avvia un'esecuzione utilizzando openai_client.evals.runs.create(), effettua il polling fino al completamento e leggi i risultati valutati. Vedere Ottenere i risultati per lo schema dei risultati.

Nella parte restante di questa sezione vengono illustrati gli input al passaggio 1: selezionare uno scenario e quindi scegliere gli analizzatori.

Scegliere il punto di partenza

Set di dati esistente

Usa questo percorso quando hai già raccolto query e risposte in un file (oppure query e dati di ground truth) e vuoi solo che Foundry li valuti. JSONL supporta sia le righe per turno sia gli input a livello di conversazione; CSV supporta solo le righe per turno.

Scenario Quando usare Tipo di origine dati
Valutazione del set di dati a livello di turno Ogni riga è una query/response coppia, facoltativamente con context o ground_truth. jsonl O csv
Valutazione del set di dati a livello di conversazione (anteprima) Ogni riga è una conversazione espressa come messages matrice. jsonl

Dati in Foundry o Application Insights

Utilizzare questo percorso quando l'agente è già in esecuzione e si desidera valutare cosa è realmente successo. Invece di spostare i dati altrove, si fa puntare Foundry ai dati nel punto in cui già risiedono, tramite l'ID di risposta di Foundry oppure l'ID di traccia o di conversazione di Application Insights.

Scenario Quando usare Tipo di origine dati
Valutazione della risposta dell'agente L'agente viene eseguito in Foundry e si dispone di ID di risposta da assegnare un punteggio. azure_ai_responses
Valutazione della traccia a livello di turno (anteprima) L'agente invia tracce OpenTelemetry ad Application Insights, compresi framework non-Foundry come LangChain o agenti personalizzati strumentati con OpenTelemetry. Ogni traccia riceve un punteggio individualmente. azure_ai_trace_data_source_preview
Valutazione della traccia a livello di conversazione (anteprima) Stesse fonti di tracciamento, ma valuta intere conversazioni, per ID della conversazione o per filtro agente con campionamento. azure_ai_trace_data_source_preview

Input senza risposte

Usare questo percorso quando si hanno gli input ma non sono ancora presenti risposte. Foundry genera risposte per un modello o un agente di destinazione durante la valutazione, quindi le valuta assegnando un punteggio. Selezionare una riga in base al fatto che l'input sia costituito da query (inviate come singoli turni ) o descrizioni di scenari (usate per guidare un'interazione a livello di conversazione).

Scenario Quando usare Origine dati/destinazione
Completamento della destinazione del modello Hai delle query e vuoi valutare le risposte di una distribuzione del modello. azure_ai_target_completions → azure_ai_model
Completamenti di Agent Target Hai delle query e vuoi valutare le risposte di un agente Foundry. azure_ai_target_completions → azure_ai_agent
Simulazione della conversazione (anteprima) Sono disponibili descrizioni degli scenari (nessuna query); Foundry simula un utente che guida un'interazione a livello di conversazione con l'agente. azure_ai_target_completions → azure_ai_agent

Nessun dato ancora

Utilizza questo percorso quando stai creando un nuovo modello o un nuovo agente e non hai ancora raccolto alcun input. Foundry genera i dati di test da zero: scegliere query sintetiche per un'ampia copertura di qualità o richieste antagoniste per i test di sicurezza.

Scenario Quando usare Origine dati/destinazione
Valutazione dei dati sintetici (anteprima) Vuoi una copertura di qualità oltre ciò che scriveresti a mano. Foundry genera query di test, le invia alla destinazione e assegna punteggi alle risposte. azure_ai_synthetic_data_gen_preview→ azure_ai_model o azure_ai_agent
Valutazione del Red Team Vuoi eseguire test avversariali automatizzati: Foundry genera jailbreak e prompt con contenuti dannosi e valuta il modo in cui il sistema di destinazione risponde. azure_ai_red_team→ azure_ai_model o azure_ai_agent

Scegliere gli analizzatori

Ogni scenario associa i valutatori ai campi nei tuoi dati tramite mappature delle colonne. I campi disponibili dipendono dall'origine dati. Gli scenari del dataset espongono i campi personalizzati degli elementi, mentre gli scenari generati dalla destinazione espongono anche la risposta del modello o dell'agente tramite uno schema di esempio. Le sottosezioni relative a ciascuno scenario, più avanti nell’articolo, mostrano le mappature delle colonne per ogni caso.

Per una panoramica degli analizzatori disponibili e su come selezionarli, vedere Analizzatori predefiniti e analizzatori personalizzati.

Prerequisiti

  • Progetto Foundry.

  • Una distribuzione OpenAI di Azure con un modello GPT che supporta il completamento della chat (ad esempio, gpt-5-mini).

  • Ruolo di utente Foundry nel progetto Foundry.

    Importante

    I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  • Facoltativamente, è possibile usare il proprio account di archiviazione per eseguire valutazioni.

Nota

Alcune funzionalità di valutazione hanno restrizioni a livello di area. Per informazioni dettagliate, vedere aree supportate .

Inizia

Installare l'SDK e configurare il client:

pip install "azure-ai-projects>=2.2.0"

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
openai_client = project_client.get_openai_client()

Preparare i dati di input

La maggior parte degli scenari di valutazione richiede dati di input. È possibile fornire dati in due modi:

Caricare un file JSONL o CSV per creare un set di dati con versione nel progetto Foundry. I set di dati supportano il controllo delle versioni e il riutilizzo tra più esecuzioni di valutazione. Usare questo approccio per i test di produzione e i flussi di lavoro CI/CD.

Preparare un file JSONL con un oggetto JSON per riga contenente i campi necessari agli analizzatori:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

In alternativa, preparare un file CSV con intestazioni di colonna corrispondenti ai campi dell'analizzatore:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Fornire i dati in linea

Per una sperimentazione rapida con set di test di piccole dimensioni, fornire i dati direttamente nella richiesta di valutazione usando file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Passare source come campo "source" nella configurazione dell'origine dati quando si crea un'esecuzione. Le sezioni dello scenario che seguono usano file_id per impostazione predefinita.

Valutazione del set di dati

Valutare le risposte precalcolate in un file JSONL usando il tipo di sorgente dati jsonl. Questo scenario è utile quando si dispone già di output del modello e si vuole valutarne la qualità.

Suggerimento

Prima di iniziare, completare Introduzione e Preparare i dati di input.

Definire lo schema dei dati e gli analizzatori

Specificare lo schema che corrisponde ai campi JSONL e selezionare gli analizzatori (criteri di test) da eseguire. Usare il parametro data_mapping per connettere i campi dai dati di input ai parametri dell'analizzatore con la sintassi {{item.field}}. Includere data_mapping sempre con i campi di input necessari per ogni analizzatore. I nomi dei campi devono corrispondere a quelli nel file JSONL, ad esempio se i dati hanno "question" invece di "query", usare "{{item.question}}" nel mapping. Per i parametri obbligatori per analizzatore, vedere Analizzatori predefiniti.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

Creare una valutazione ed eseguire

Creare la valutazione, quindi avviare un'esecuzione sul set di dati caricato. L'esecuzione applica ciascun valutatore a ogni riga del set di dati.

# Create the evaluation
eval_object = openai_client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

Per un esempio eseguibile completo, vedere sample_evaluations_builtin_with_dataset_id.py su GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Valutazione del set di dati CSV

Valutare le risposte pre-calcolate in un file CSV usando il csv tipo di origine dati. Questo scenario funziona allo stesso modo della valutazione del set di dati , ma accetta file CSV anziché JSONL. Usare CSV quando i dati sono già in formato foglio di calcolo o tabulare.

Suggerimento

Prima di iniziare, completare Introduzione e Preparare i dati di input.

Preparare un file CSV

Creare un file CSV con intestazioni di colonna che corrispondano ai campi necessari agli analizzatori. Ogni riga rappresenta un test case.

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Caricare ed eseguire

Caricare il file CSV come set di dati. Creare quindi una valutazione usando il csv tipo di origine dati. La definizione dello schema e la configurazione dell'analizzatore sono le stesse delle valutazioni JSONL. L'unica differenza è nell'"type": "csv" origine dati.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = openai_client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Valutazione della destinazione del modello

Inviare query a un modello distribuito in fase di esecuzione. Valuta le risposte utilizzando il tipo di origine dati azure_ai_target_completions con una destinazione azure_ai_model. I dati di input contengono query. Il modello genera risposte, che verranno quindi valutate.

Suggerimento

Prima di iniziare, completare Introduzione e Preparare i dati di input.

Definire il modello di messaggio e la destinazione

Il input_messages modello controlla la modalità di invio delle query al modello. Usare {{item.query}} per fare riferimento ai campi dei dati di input. Specificare il modello per valutare e facoltativi i parametri di campionamento:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Configurare analizzatori e mappature dei dati

Quando il modello genera risposte in fase di esecuzione, usare {{sample.output_text}} in data_mapping per fare riferimento all'output del modello. Usare {{item.field}} per fare riferimento ai campi dei dati di input.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Creare una valutazione ed eseguire

eval_object = openai_client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Per un esempio eseguibile completo, vedere sample_model_evaluation.py in GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Suggerimento

Per aggiungere un'altra esecuzione di valutazione, usare lo stesso codice.

Valutazione della destinazione dell'agente

Invia query a un agente Foundry in fase di esecuzione e valuta le risposte usando il tipo di origine dati azure_ai_target_completions con una destinazione azure_ai_agent. Questo scenario funziona sia per gli agenti prompt che per gli agenti ospitati.

Suggerimento

Prima di iniziare, completare Introduzione e Preparare i dati di input.

Suggerimento

Gli agenti ospitati che usano il protocollo di risposte funzionano con gli stessi esempi di codice illustrati di seguito. Per gli agenti ospitati che usano il protocollo di chiamata, il input_messages formato è diverso. Per informazioni dettagliate, vedere Protocollo chiamate dell'agente ospitato .

Definire il modello di messaggio e la destinazione

Il input_messages modello controlla la modalità di invio delle query all'agente. Usare {{item.query}} per fare riferimento ai campi dei dati di input. Specificare l'agente da valutare in base al nome:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Configurare analizzatori e mappature dei dati

Quando l'agente genera risposte in fase di esecuzione, usare {{sample.*}} le variabili in data_mapping per fare riferimento all'output dell'agente:

Variabile Descrizione Usare per
{{sample.output_text}} Risposta di testo normale dell'agente. Analizzatori che prevedono una risposta di stringa ( ad esempio , coherenceviolence).
{{sample.output_items}} L'output JSON strutturato dell'agente, incluse le invocazioni degli strumenti. Analizzatori che necessitano di un contesto di interazione completo (ad esempio, task_adherence).
{{item.field}} Un campo dai tuoi dati di input. Campi di input come query o ground_truth.

Suggerimento

Il query campo può contenere json strutturato, inclusi i messaggi di sistema e la cronologia delle conversazioni. Alcuni analizzatori di agenti, task_adherence ad esempio, usano questo contesto per un punteggio più accurato. Per informazioni dettagliate sulla formattazione delle query, vedere Analizzatori di agenti.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Creare una valutazione ed eseguire

eval_object = openai_client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Per un esempio eseguibile completo, vedere sample_agent_evaluation.py in GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Protocollo chiamate dell'agente ospitato

Gli agenti ospitati che usano il protocollo di invocazioni supportano lo stesso azure_ai_agent tipo di destinazione, ma usano un formato libero input_messages. Anziché il formato del modello strutturato, fornire un oggetto JSON mappato direttamente al corpo della richiesta dell'agente /invocations . Usare {{item.*}} segnaposto per sostituire i campi dai dati di input.

Se un agente ospitato supporta sia le risposte che i protocolli di chiamata, per impostazione predefinita il servizio usa il protocollo di chiamata.

Definire il formato e la destinazione del messaggio

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Creare una valutazione ed eseguire

eval_object = openai_client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

La configurazione dell'analizzatore e i mapping dei dati sono uguali a per la valutazione dell'agente di richiesta. Usare {{sample.output_text}} per la risposta di testo dell'agente e {{sample.output_items}} per l'output strutturato completo, incluse le chiamate agli strumenti.

Valutazione della risposta dell'agente

Recuperare e valutare le risposte dell'agente Foundry in base agli ID risposta usando il tipo di origine dati azure_ai_responses. Usare questo scenario per valutare interazioni specifiche dell'agente dopo che si verificano.

Suggerimento

Prima di iniziare, completare l'introduzione.

Un ID risposta è un identificatore univoco restituito ogni volta che un agente Foundry genera una risposta. È possibile raccogliere gli ID risposta dalle interazioni dell'agente usando l'API Risposte o dai log di tracciamento dell'applicazione. Specificare gli ID inline come contenuto di file o caricarli come set di dati (vedere Preparare i dati di input).

Raccogliere gli ID delle risposte

Ogni chiamata all'API Risposte restituisce un oggetto risposta con un campo univoco id . Raccogliere questi ID dalle interazioni dell'applicazione o generarli direttamente:

# Generate response IDs by calling a model through the Responses API
response = openai_client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

È anche possibile raccogliere gli ID di risposta dalle interazioni dell'agente nei file di log o nel processo di monitoraggio dell'applicazione. Ogni ID risposta identifica in modo univoco una risposta archiviata che il servizio di valutazione può recuperare.

Creare una valutazione ed eseguire

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = openai_client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

Per un esempio eseguibile completo, vedere sample_agent_response_evaluation.py su GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Valutazione della traccia (anteprima)

Valutare le interazioni dell'agente già acquisite da Application Insights. Utilizzare la tipologia di origine dati azure_ai_traces. Questo scenario è utile per la valutazione post-distribuzione del traffico di produzione reale. È possibile selezionare tracce dalla pipeline di monitoraggio ed eseguire analizzatori su di essi senza riprodurre alcuna richiesta.

Importante

La valutazione delle tracce è l'approccio consigliato per valutare agenti non creati con Microsoft Foundry Agent Service, compresi LangChain e framework personalizzati. A condizione che l'agente invii span OpenTelemetry conformi alle convenzioni semantiche GenAI in Application Insights, la valutazione delle tracce può analizzarne le interazioni usando gli stessi valutatori disponibili per gli agenti di Foundry.

La valutazione della traccia supporta due modalità:

  • Per ID di traccia : valutare interazioni di agenti specifici fornendo i relativi operation_Id valori da Application Insights.
  • Per filtro agente : consente di individuare e valutare automaticamente le tracce recenti per un determinato agente, senza raccogliere manualmente gli ID di traccia.

Suggerimento

Prima di iniziare, completare l'introduzione. Questo scenario richiede anche una risorsa di Application Insights connessa al progetto Foundry.

Campionamento intelligente

La valutazione della traccia supporta il campionamento intelligente, che seleziona un sottoinsieme rappresentativo di tracce per la valutazione anziché valutare ogni traccia acquisita. Abilita questa funzionalità attivando l'interruttore Campionamento intelligente nel portale Foundry durante la configurazione di un'esecuzione di valutazione delle tracce. Il campionamento intelligente riduce i costi di valutazione mantenendo la diversità di traccia, assicurandosi che i casi perimetrali, i percorsi di errore e i vari modelli di conversazione siano inclusi nel set valutato.

Funzionamento del campionamento intelligente

L'algoritmo di campionamento usa un approccio di diversificazione MinHash con selezione dei punti più distanti, articolato in più fasi:

  1. Deduplicazione esatta : rimuove le tracce duplicate dal pool.
  2. Filtri severi - Rimuove sessioni interrotte, tracce troncate e chiamate agli strumenti mal formate che non sono idonee alla valutazione.
  3. Aggregazione : combina i segnali a livello di traccia in una rappresentazione unificata.
  4. Selezione minHash più lontana : calcola gli hash sensibili alla località (firme MinHash) del testo dell'utente per stimare la somiglianza tra le tracce, quindi seleziona in modo iterativo la traccia più diversa dal pool rimanente. Ogni selezione successiva ottimizza la distanza da tutte le tracce selezionate in precedenza.

Questo approccio produce una diversità lessicale significativamente superiore e una copertura del vocabolario più ampia rispetto al campionamento casuale, il che significa che il set valutato rappresenta meglio l'intera gamma di interazioni degli agenti, inclusi casi rari, difficili e nuovi casi che il campionamento casuale tende a perdere.

Il campionamento intelligente è particolarmente efficace per:

  • Valutazione e benchmark : ottimizza la copertura della distribuzione di input, in modo che i punteggi di valutazione riflettano la diversità reale.
  • Generazione di rubriche: produce rubriche più incentrate e interattive esponendo modelli di conversazione diversi.
  • Selezione del set di dati per la messa a punto - Seleziona le tracce che aiutano i modelli ad apprendere in modo più efficiente.

L'algoritmo viene eseguito interamente sul calcolo locale senza chiamate API aggiuntive, quindi non comporta costi di inferenza del modello aggiuntivi oltre la valutazione stessa.

Esempio di campionamento intelligente

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Requisiti dei dati di traccia

La valutazione della traccia richiede che l'agente crei intervalli che seguono le convenzioni semantiche OpenTelemetry per l'intelligenza artificiale generativa. In particolare, il servizio di valutazione legge invoke_agent ampiezze da Application Insights ed estrae i dati della conversazione dai relativi attributi.

Vengono usati gli attributi di intervallo seguenti:

Attribute Obbligatorio Descrizione
gen_ai.operation.name Sì Deve essere uguale a "invoke_agent". Il servizio ignora tutti gli altri intervalli.
gen_ai.agent.id Per la modalità filtro agente Identificatore univoco dell'agente (formato: agent-name:version).
gen_ai.agent.name Per la modalità filtro agente Nome agente leggibile dagli esseri umani.
gen_ai.input.messages Per gli input di query dei valutatori Matrice JSON di messaggi di input che seguono il formato dei messaggi semantici GenAI. Messaggi con ruolo user o system mappa a query; messaggi con ruolo assistant o tool mappati a response.
gen_ai.output.messages Per gli input di query dei valutatori Matrice JSON di messaggi di output generati dal modello. Tutti i messaggi di output sono mappati a response. Se l'output contiene anche type: tool_call o type: tool_result, viene mappato su tool_calls.
gen_ai.tool.definitions Opzionale Matrice JSON degli schemi degli strumenti disponibili per l'agente. Se assente, il servizio tenta di dedurre le definizioni degli strumenti dai messaggi di chiamata dello strumento, ma gli schemi dedotti potrebbero essere incompleti.
gen_ai.conversation.id Opzionale Identificatore di conversazione, passato ai risultati della valutazione per la correlazione.

Nota

Se gen_ai.input.messages e gen_ai.output.messages sono vuoti o mancanti, gli analizzatori di qualità (coerenza, fluenza, pertinenza, risoluzione delle finalità) restituiscono score=None. Gli analizzatori di sicurezza (violenza, autolesionismo, sesso, odio/ingiustità) possono comunque produrre punteggi con dati parziali, ma potrebbero non produrre risultati significativi.

Per gli agenti Python creati con l'SDK Azure AI Agent Server, aggiungere il [tracing] aggiuntivo per abilitare l'emissione automatica di span:

pip install "azure-ai-agentserver-core[tracing]"

Prerequisiti per la valutazione della traccia

Oltre ai prerequisiti generali, la valutazione della traccia richiede:

pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Impostare queste variabili di ambiente:

  • APPINSIGHTS_RESOURCE_ID : ID risorsa di Application Insights(ad esempio, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — Identificatore dell'agente generato dall'integrazione di tracciamento (gen_ai.agent.id attributo), usato per filtrare le tracce. Formato: agent-name:version.
  • TRACE_LOOKBACK_HOURS: (facoltativo) Numero di ore da esaminare quando si eseguono query sulle tracce. Di default è 1.

Opzione A: Valutare tramite filtro agente

L'approccio più semplice consiste nell'consentire al servizio di individuare e valutare automaticamente le tracce recenti per un agente specifico. Non è necessaria alcuna raccolta di ID di tracciamento manuale.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Il servizio filtra le estensioni invoke_agent in base all'attributo gen_ai.agent.id, seleziona fino a max_traces ID di traccia univoci e valuta tutte le estensioni di tali tracce.

Opzione B: Valutare tramite gli identificatori di traccia

Per un maggiore controllo, raccogliere ID di traccia specifici da Application Insights e valutarli. Questo metodo è utile quando si vuole valutare un set curato di interazioni, ad esempio tracce contrassegnate da avvisi o campionate per la verifica della qualità.

Raccogliere gli ID di traccia da Application Insights

Esegui una query su Application Insights per ottenere valori operation_Id dalle tracce dell'agente. Ognuno operation_Id rappresenta un'interazione completa dell'agente:

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Creare una valutazione ed eseguire un test con ID di traccia

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Configurare analizzatori e mappature dei dati

Quando si valutano le tracce, il servizio estrae automaticamente i dati della conversazione dagli attributi dell'intervallo OpenTelemetry. Usare questi nomi di campo direttamente in data_mapping (senza i prefissi item. o sample. utilizzati in altri scenari).

Variabile Attributo di origine Descrizione
{{item.query}} gen_ai.input.messages (ruoli utente/sistema) La query dell'utente estratta dalla traccia.
{{item.response}} gen_ai.input.messages (ruoli assistente/strumento) + gen_ai.output.messages Risposta dell'agente estratta dalla traccia.
{{item.tool_definitions}} gen_ai.tool.definitions Schemi degli strumenti disponibili per l'agente. Obbligatorio solo per gli analizzatori correlati agli strumenti.
{{item.tool_calls}} Estratto dai messaggi dell'assistente in gen_ai.input.messages / gen_ai.output.messages Chiamate agli strumenti effettuate dall'agente durante l'interazione. Usato dagli analizzatori di strumenti. Obbligatorio solo per gli analizzatori correlati agli strumenti. 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Per un esempio eseguibile completo, vedere sample_evaluations_builtin_with_traces.py in GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Valutazione dei dati sintetici (anteprima)

Usare il azure_ai_synthetic_data_gen_preview tipo di origine dati per generare query di test sintetiche, inviarle a un modello distribuito o a un agente Foundry e valutare le risposte. Usare questo scenario quando non si ha un set di dati di test. Il servizio genera query in base a un prompt che fornisci (e/o in base alle istruzioni dell'agente), le esegue sul target e ne valuta le risposte.

Suggerimento

Prima di iniziare, completare l'introduzione.

Funzionamento della valutazione dei dati sintetici

  1. Il servizio genera query sintetiche basate su prompt e si file di dati iniziali facoltativi.
  2. Ogni query viene inviata alla destinazione specificata (modello o agente) per generare una risposta.
  3. Gli analizzatori valutano ogni risposta in base alla query e alla risposta generate.
  4. Le query generate vengono archiviate come set di dati nel progetto per il riutilizzo.

Parametri

Parametro Obbligatorio Descrizione
samples_count Sì Numero massimo di query di test sintetiche da generare.
model_deployment_name Sì Implementazione del modello da usare per generare query sintetiche. Sono supportati solo i modelli con funzionalità API Risposte. Per la disponibilità, vedere Disponibilità dell'area dell'API Risposte.
prompt No Istruzioni che descrivono il tipo di query da generare. È facoltativo se la destinazione dell'agente ha le istruzioni configurate.
output_dataset_name No Nome del set di dati di output in cui vengono archiviate le query generate. Se non si specifica un nome, il servizio ne genera uno automaticamente.
sources No Eseguire il seeding dei file di dati (in base all'ID file) per migliorare la pertinenza delle query generate. Attualmente è supportato un solo file.

Configurare analizzatori e mappature dei dati

Il generatore di dati sintetici produce query nel {{item.query}} campo . La destinazione genera risposte disponibili in {{sample.output_text}}. Associa questi campi ai valutatori:

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Creare una valutazione ed eseguire

Destinazione del modello

Generare query sintetiche e valutare un modello:

eval_object = openai_client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Facoltativamente, è possibile aggiungere un prompt di sistema per modellare il comportamento del modello di destinazione. Quando usi input_messages con la generazione di dati sintetici, includi solo i messaggi con ruolo system: il servizio fornisce automaticamente le query generate come messaggi dell'utente.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

Destinazione dell'agente

Generare query sintetiche e valutare un agente Foundry:

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati. La risposta include una output_dataset_id proprietà che contiene l'ID del set di dati generato, che è possibile usare per recuperare o riutilizzare i dati sintetici.

Valutazione a livello di conversazione (anteprima)

Valutare le conversazioni complete per valutare la qualità dell'agente tra intere interazioni utente, non solo le singole risposte. Usare la valutazione a livello di conversazione per identificare problemi di qualità come la risoluzione incompleta delle attività, la frustrazione dell'utente e le regressioni delle chiamate agli strumenti che non vengono valutate a livello di turno.

Si consideri, ad esempio, un agente di supporto in cui l'utente si esaspera nel corso di più scambi:

Turno 1 - Utente: "Devo reimpostare la password". Agente: "Ho trovato il tuo account. Invierò un collegamento di reimpostazione."

Turno 2 — Utente: "Non ho ricevuto l'e-mail." Agente: "Ho reinviato il link." Si prega di controllare la posta indesiderata."

Turn 3 — User: "Ancora niente. Puoi semplicemente reimpostarla direttamente?" Agente: "Ho inviato un altro collegamento di reimpostazione".

Un valutatore a livello di singolo turno assegna un punteggio solo all’ultima risposta, che è educata e intraprende un’azione, perciò ottiene un buon punteggio. Un valutatore a livello di conversazione che valuta la soddisfazione del cliente nell'intera conversazione segnala che l'agente ha ripetuto la stessa azione inefficace tre volte senza tentare un'alternativa, lasciando il problema dell'utente irrisolto.

La valutazione a livello di conversazione differisce dalla valutazione a livello di turno in diversi modi:

Aspect Livello di turno Livello di conversazione
Scope Singole coppie di query-risposta Conversazioni complete con scambi multipli
Metrics Qualità e sicurezza per ogni risposta Risultati a livello di conversazione e soddisfazione degli utenti
Formato dati JSONL con campi query e response JSONL con messages matrice contenente la conversazione completa
caso d'uso Test delle risposte dei singoli modelli Verifica delle esperienze end-to-end degli agenti

La valutazione a livello di conversazione supporta quattro opzioni di origine dati:

Opzione Quando usare Tipo di origine dati
Da un set di dati o in linea Sono presenti tracce di conversazioni locali o dati di test jsonl con file_id o file_content
In base all'ID conversazione Si vogliono valutare conversazioni specifiche da App Insights azure_ai_trace_data_source_preview Con trace_source
Per filtro agente con campionamento Si vuole valutare la qualità complessiva dell'agente nel traffico di produzione campionato azure_ai_trace_data_source_preview Con trace_source
Conversazioni simulate Vuoi generare conversazioni di test sintetiche azure_ai_target_completions Con conversation_gen_preview

Scegliere un livello di valutazione

Il parametro evaluation_level del comando run determina se i valutatori valutano i singoli turni o conversazioni complete:

Value Behavior
"turn" Gli analizzatori valutano ogni turno in modo indipendente.
"conversation" Gli analizzatori valutano l'intera conversazione nel suo complesso.
(omesso) Di default è "turn".

Importante

Compatibilità dell'analizzatore: ogni analizzatore supporta livelli di valutazione specifici. Controllare il campo supported_evaluation_levels del valutatore nel catalogo dei valutatori.

  • Valutatori solo per turno (ad esempio, fluency, relevance) non possono essere utilizzati con evaluation_level="conversation".
  • Attualmente, tutti i valutatori a livello di conversazione supportano sia il livello "turn" sia il livello "conversation".

Errori comuni

Error Motivo Soluzione
Livello di valutazione incompatibile Uso di evaluation_level="conversation" con un valutatore solo turni Rimuovere il valutatore solo turno o modificare in evaluation_level="turn"

Preparare i dati della conversazione

Creare un file JSONL in cui ogni riga contiene una conversazione completa nel messages campo. Ogni messaggio deve includere un role (utente, assistente o sistema) e content. Per un esempio completo, vedere gli esempi di valutazione conversation nell'SDK:

 {"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": "Your current balance is $1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}]}

È anche possibile includere definizioni di strumenti e chiamate agli strumenti se l'agente usa strumenti:

{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris"}]}
{"messages": [{"role": "user", "content": "How do I reverse a string in Python?"}, {"role": "assistant", "content": "You can reverse a string in Python by using slicing: string[::-1]"}]}
{"messages": [{"role": "user", "content": "What are the main causes of climate change?"}, {"role": "assistant", "content": "The main causes of climate change are the increase in greenhouse gases in the atmosphere, primarily due to human activities such as burning fossil fuels and deforestation."}]}
{"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_account_balance", "arguments": "{\"account_id\": \"ACCT-7890\"}"}}]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{ \"balance\": 1234.56, \"currency\": \"USD\" }"}, {"role": "assistant", "content": "Your current balance is 1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}], "tool_definitions": [{"name": "get_account_balance", "description": "Retrieves the current balance for a customer account", "parameters": {"type": "object", "properties": {"account_id": {"type": "string"}}, "required": ["account_id"]}}]}
{"messages": [{"role": "user", "content": "Explain the theory of relativity in simple terms."}, {"role": "assistant", "content": "Einstein's theory of relativity shows that space and time are interconnected and relative to the observer's frame of reference."}]}
{"messages": [{"role": "user", "content": "What's the weather in Seattle?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Seattle, WA\"}"}}]}, {"role": "tool", "tool_call_id": "call_002", "content": "{ \"temperature\": 55, \"condition\": \"Cloudy\" }"}, {"role": "assistant", "content": "It's currently 55F and cloudy in Seattle."}], "tool_definitions": [{"name": "get_weather", "description": "Get the current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]}
{"messages": [{"role": "user", "content": "What is the tallest mountain in the world?"}, {"role": "assistant", "content": "Mount Everest is the tallest mountain in the world."}]}
{"messages": [{"role": "user", "content": "Is 4 x 2 = 16?"}, {"role": "assistant", "content": "No, 4 x 2 = 8."}]}
{"messages": [{"role": "user", "content": "What is the best Italian desert?"}, {"role": "assistant", "content": "Tiramisu is a popular Italian dessert."}]}
{"messages": [{"role": "user", "content": "What is the chemical formula for water?"}, {"role": "assistant", "content": "The chemical formula for water is H2O."}]}

Definire lo schema dei dati e gli analizzatori

Specifica lo schema per i tuoi dati di conversazione, "messages", e seleziona i valutatori progettati per valutare l'intera conversazione. Gli analizzatori a livello di conversazione valutano l'intera interazione anziché i singoli turni.

pip install "azure-ai-projects>=2.2.0"

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Creare una valutazione ed eseguire

Preparazione: scarica sample_data_multiturn_conversations.jsonl

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

# Upload conversation data
data_id = project_client.datasets.upload_file(
    name="multiturn-conversation-data",
    version="1",
    file_path="./sample_data_multiturn_conversations.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run with evaluation_level set to "conversation"
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="multiturn-conversation-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
    extra_body={"evaluation_level": "conversation"},
)

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Valutare le conversazioni in base all'ID dalle tracce

Valuta conversazioni specifiche in Application Insights fornendo i relativi ID di conversazione. Usare questa opzione per risolvere i problemi di causa radice o verificare le correzioni per interazioni specifiche. Ad esempio, è possibile analizzare una conversazione contrassegnata da un avviso o verificare una correzione per un problema noto.

Dove trovare gli ID della conversazione

Trovare gli ID delle conversazioni in:

  • Interfaccia utente dei log di analisi di Application Insights — passare alle tracce di interesse e individuare il campo conversation_id nei dettagli della traccia.
  • Output dei log dell'applicazione — Se imposti conversation_id esplicitamente quando crei le risposte dell'agente, recuperalo dai log.
  • Contesto di traccia OpenTelemetry — Il conversation_id può anche essere derivato dall'intestazione traceparent se l'agente utilizza la propagazione standard del contesto di traccia.

Nota

Le definizioni degli strumenti vengono recuperate automaticamente dalle tracce o richieste al registro dell'agente. Non è necessario specificarli nella richiesta.

Parametri per la ricerca dell'ID della conversazione

Parametro Obbligatorio Descrizione
conversation_ids Sì Array di ID di conversazione da valutare.
lookback_hours No Ore da cercare a ritroso da end_time. Il valore predefinito è sette giorni (168 ore).
end_time No Fine della finestra di ricerca (formato ISO 8601). L'impostazione predefinita è l'ora corrente. 
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

  • L'inserimento dati di Application Insights può causare un ritardo tra quando vengono generate tracce e quando sono disponibili per la valutazione. Se la query non trova tracce, attendere alcuni minuti e riprovare.
  • Il lookback massimo è di 7 giorni (168 ore). Per accedere alle tracce meno recenti, usare start_time e end_time entro i limiti di conservazione di App Insights.

Valutare le conversazioni campionate in base al filtro dell'agente

Valutare un set campionato di conversazioni da Application Insights filtrando il nome dell'agente. Usare questa opzione per valutare la qualità complessiva dell'agente nel traffico di produzione. Ad esempio, eseguire valutazioni di qualità regolari o monitorare la riduzione della qualità nell'ambiente di produzione.

L'agente specificato per il filtro può far parte di una conversazione multi-agente. Il filtro corrisponde a qualsiasi conversazione in cui l'agente ha partecipato.

Nota

Le definizioni degli strumenti vengono recuperate automaticamente dalle tracce o richieste al registro dell'agente. Non è necessario specificarli nella richiesta.

Campi dell'identità dell'agente

Specificare l'agente da filtrare usando uno dei formati seguenti:

Formato Esempio Descrizione
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Due campi separati. Se agent_version viene omesso, usare la versione più recente.
agent_id "agent_id": "my-agent:1" Stringa singola in "name:version" formato.

Strategie di filtro

Strategy Descrizione
random_sampling (Impostazione predefinita) Campione selezionato casualmente in modo uniforme fino a un massimo di max_traces conversazioni.
smart_filtering Euristica gestita dal servizio che privilegia le tracce "interessanti" - conversazioni con potenziali problemi, casi limite o anomalie.

Parametri

Parametro Obbligatorio Descrizione
agent_name Sì Nome dell'agente per cui filtrare le tracce.
agent_version No Versione dell'agente. Se omesso, usa la versione più recente.
agent_id No Alternativa a agent_name + agent_version. Stringa singola in formato "name:version".
start_time Sì Inizio dell'intervallo di tempo (secondi dell'epoca Unix, UTC).
end_time Sì Fine dell'intervallo di tempo (secondi dell'epoca Unix, UTC). Aggiungere un margine di +600 secondi per evitare il ritardo di acquisizione.
max_traces No Numero massimo di conversazioni da campionare. Il valore predefinito è 1.000.
filter_strategy No "random_sampling" (predefinito) o "smart_filtering" (euristica gestita dal servizio che privilegia le tracce interessanti).

Importante

L'intervallo di tempo (end_time - start_time) deve essere di almeno 15 minuti (900 secondi). Questo requisito esiste perché le query a livello di conversazione applicano un buffer di inattività di 5 minuti a ciascuna estremità per evitare conversazioni parziali.

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

L'intervallo di tempo delle query di App Insights è attualmente limitato a un massimo di 7 giorni (168 ore). Non è possibile accedere alle tracce precedenti a 7 giorni senza fornire start_time in modo esplicito e end_time entro i limiti di conservazione di App Insights.

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Simulazione conversazioni

Generare conversazioni simulate dalle descrizioni degli scenari e valutarle a livello di conversazione. Usare questo scenario per testare il comportamento dell'agente in situazioni controllate prima della distribuzione. Il servizio genera conversazioni realistiche in base alle descrizioni degli scenari e quindi le valuta.

Questo approccio è utile per:

  • Test di pre-distribuzione: convalidare il comportamento dell'agente in diversi scenari senza traffico utente reale.
  • Copertura dei casi limite: scenari di test che si verificano raramente, ma che è importante gestire correttamente.
  • Test di regressione: assicurarsi che gli aggiornamenti dell'agente non degradino le prestazioni in scenari noti.
  • Test di scalabilità: generare molte conversazioni rapidamente per le funzionalità dell'agente di test di stress.

Funzionamento della simulazione della conversazione

  1. Viene fornito un set di dati di descrizioni degli scenari: ogni riga descrive una situazione che l'utente simulato tenta di eseguire.
  2. Il servizio usa un modello di simulatore per svolgere il ruolo dell'utente, interagendo con l'agente in base allo scenario.
  3. Ogni scenario genera una o più conversazioni complete.
  4. I valutatori a livello di conversazione valutano le conversazioni generate.
  5. Il progetto archivia sia le conversazioni che i risultati della valutazione.

Preparare i dati dello scenario

Creare un file JSONL in cui ogni riga descrive uno scenario per l'utente simulato. Lo schema richiede id, test_case_descriptione desired_num_turns. Includere dettagli sull'obiettivo, il contesto e gli eventuali vincoli dell'utente. Per un esempio completo, consulta gli esempi di valutazione delle conversazioni nell’SDK.


{"id": "contoso_refund_timeline", "test_case_description": "Customer returned an item to Contoso Electronics 5 days ago and hasn't received their refund yet. They want to know how long Contoso refunds take.", "desired_num_turns": 10}
{"id": "contoso_store_hours_lookup", "test_case_description": "Customer wants to know what time the Contoso Electronics store closes today. Simple single-fact question with possibly one clarifying turn about which location.", "desired_num_turns": 3}

Parametri

Parametro Obbligatorio Descrizione
num_conversations No Numero di conversazioni da generare per scenario. Il valore predefinito è 5, limite lato server pari a 5.
max_turns No Numero massimo di turni (scambi) per conversazione. Il valore predefinito è 10, limite lato server pari a 20.
model Sì Distribuzione del modello da usare per simulare l'utente. Ad esempio: gpt-4.1.
sampling_params No Parametri di campionamento per il modello di simulatore, tra cui temperature, top_pe max_completion_tokens.
data_mapping No Esegue il mapping dei campi dallo scenario JSONL ai parametri di simulazione. Mappature comuni: test_case_description, id, desired_num_turns.

Definire gli analizzatori

Seleziona i valutatori progettati per valutare conversazioni. Le conversazioni simulate vengono automaticamente associate ai valutatori.

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator, PromptAgentDefinition

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Creare una valutazione ed eseguire

Preparazione: scaricare sample_data_simulation_scenarios.jsonl.

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./sample_data_simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "item_generation_params": {
            "type": "conversation_gen_preview",
            "model": model_deployment_name,
            "num_conversations": 2,
            "max_turns": 5,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
            "data_mapping": {
                "test_case_description": "test_case_description",
                "id": "id",
                "desired_num_turns": "desired_num_turns",
            },
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Ottenere risultati

Al termine dell'esecuzione di una valutazione, recuperare i risultati con punteggio ed esaminarli nel portale o a livello di codice.

Sondare i risultati

I processi di valutazione sono asincroni. Eseguire il polling dello stato dell'esecuzione fino al completamento, quindi recuperare i risultati:

import time
from pprint import pprint

while True:
    run = openai_client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    openai_client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Interpretare i risultati

Per un singolo esempio di dati, tutti gli analizzatori generano lo schema seguente:

  • Etichetta: un'etichetta binaria "pass" o "fail", simile all'output di un test unitario. Usare questo risultato per facilitare i confronti tra gli analizzatori.
  • Punteggio: punteggio della scala naturale di ogni analizzatore. Alcuni analizzatori usano una rubrica con granularità fine, l'assegnazione di punteggi su una scala a 5 punti (analizzatori di qualità) o una scala a 7 punti (analizzatori di sicurezza del contenuto). Altri, come gli analizzatori di somiglianza testuale, usano punteggi F1, che sono float tra 0 e 1. Qualsiasi punteggio non binario viene binarizzato in "superato" o "non superato" nel campo "label" in base alla "soglia".
  • Soglia: tutti i punteggi non binari vengono convertiti in "superato" o "non superato" in base a una soglia predefinita, che l'utente può modificare nell'SDK.
  • Motivo: per migliorare l'intelligibilità, tutti gli analizzatori di giudici LLM generano anche un campo di ragionamento per spiegare perché viene assegnato un determinato punteggio.
  • Dettagli: (facoltativo) Per alcuni analizzatori, ad esempio tool_call_accuracy, potrebbe essere presente un campo o flag "dettagli" che contengono informazioni aggiuntive per consentire agli utenti di eseguire il debug delle applicazioni.

Output di esempio (singolo elemento)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Risultato d'esempio (aggregato)

Per i risultati aggregati su più esempi di dati (un set di dati), la frequenza media degli esempi con un "pass" costituisce la velocità di passaggio per tale set di dati.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Risoluzione dei problemi

Attività in esecuzione da molto tempo

Il processo di valutazione potrebbe rimanere nello stato In esecuzione per un periodo prolungato. Questa condizione si verifica in genere quando la distribuzione del modello OpenAI Azure non dispone di capacità sufficiente, causando la ripetizione delle richieste da parte del servizio.

Risoluzione:

  1. Annullare il processo di valutazione corrente usando openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Aumentare la capacità del modello nel portale di Azure.
  3. Eseguire di nuovo la valutazione.

Errori di autenticazione

Se viene visualizzato un errore 401 Unauthorized o 403 Forbidden, verificare che:

  • Il tuo DefaultAzureCredential è configurato correttamente. Se si usa interfaccia della riga di comando di Azure, eseguire az login.
  • Il tuo account ha il ruolo di Utente Foundry nel progetto Foundry.
  • L'URL dell'endpoint del progetto è corretto e include sia l'account che i nomi dei progetti.

Errori di formato dati

Se la valutazione fallisce a causa di un errore di mapping dello schema o dei dati:

  • Verificare che il file JSONL abbia un oggetto JSON valido per riga.
  • Verificare che i nomi dei campi in data_mapping corrispondano esattamente ai nomi dei campi nel file JSONL (con distinzione tra maiuscole e minuscole).
  • Verificare che item_schema le proprietà corrispondano ai campi nel set di dati.

Errori di limitazione della velocità

La creazione di esecuzioni di valutazione è soggetta a limitazioni di frequenza a livello di tenant, sottoscrizione e progetto. Se si riceve una 429 Too Many Requests risposta:

  • Controllare l'intestazione retry-after nella risposta per il tempo di attesa consigliato.
  • Esaminare il corpo della risposta per informazioni dettagliate sul limite di frequenza.
  • Usare il backoff esponenziale quando si ritentano richieste non riuscite.

Se un processo di valutazione non riesce a causa di un errore 429 durante l'esecuzione:

  • Ridurre le dimensioni del set di dati di valutazione o suddividerlo in batch più piccoli.
  • Aumenta la quota di token al minuto (TPM) per la distribuzione del modello nel portale di Azure.

Errori dello strumento di valutazione dell'agente

Se un valutatore agente restituisce un errore a causa degli strumenti non supportati:

  • Verifica gli strumenti supportati per i valutatori di agenti.
  • Come soluzione alternativa, incapsulare gli strumenti non supportati come funzioni definite dall'utente in modo che l'analizzatore possa valutarli.

Contenuto correlato

  • Last updated on