Eseguire valutazioni nel cloud usando Microsoft Foundry SDK

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente 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 avere funzionalità limitate. Per altre informazioni, vedere Condizioni aggiuntive di utilizzo per le anteprime di Microsoft Azure.

Questo articolo illustra come eseguire valutazioni nel cloud (anteprima) 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 i valutatori predefiniti curati da Microsoft built-in evaluators e i tuoi valutatori personalizzati custom evaluators. 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 completi eseguibili, vedere gli esempi di valutazione Python SDK su GitHub.

Come funziona la valutazione del cloud

Per eseguire una valutazione cloud, creare una definizione di valutazione con lo schema dei dati e i criteri di test (analizzatori), quindi creare un'esecuzione di valutazione. L'esecuzione esegue ogni analizzatore sui dati e restituisce risultati con punteggio di cui è possibile eseguire il polling per il completamento.

La valutazione cloud supporta gli scenari seguenti:

Scenario Quando usare Tipo di origine dati Obiettivo
Valutazione del set di dati Valutare le risposte pre-calcolate in un file JSONL. jsonl —
Valutazione del set di dati CSV Valutare le risposte pre-calcolate in un file CSV. csv —
Valutazione della destinazione del modello Fornire query e generare risposte da un modello in fase di esecuzione per la valutazione. azure_ai_target_completions azure_ai_model
Valutazione dell'obiettivo dell'agente Fornire query e generare risposte tramite un agente Foundry (prompt o in hosting) in tempo reale per la valutazione. azure_ai_target_completions azure_ai_agent
Valutazione della risposta dell'agente Recuperare e valutare le risposte dell'agente Foundry in base agli ID di risposta. azure_ai_responses —
Valutazione della traccia Valutare le interazioni dell'agente già acquisite in Application Insights in base all'ID di traccia. Usare questo approccio per agenti non Foundry (LangChain e framework personalizzati compatibili con la registrazione basata su OpenTelemetry). azure_ai_traces —
Valutazione dei dati sintetici (anteprima) Generare query di test sintetiche, inviarle a un modello o a un agente e valutare le risposte. azure_ai_synthetic_data_gen_preview azure_ai_model o azure_ai_agent
Valutazione del team rosso Eseguire test antagonisti automatizzati su un modello o un agente. azure_ai_red_team azure_ai_model o azure_ai_agent

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

Tipo di origine Descrizione
file_id Fare riferimento a un set di dati caricato in base all'ID.
file_content Specificare i dati inline nella richiesta.

Ogni valutazione richiede un data_source_config oggetto che indica al servizio quali campi aspettarsi nei dati:

  • custom — Definisci un oggetto item_schema con i nomi e i tipi di campo. Impostare include_sample_schema su true quando si utilizza un obiettivo affinché gli analizzatori possano fare riferimento alle risposte generate.
  • azure_ai_source — Lo schema viene dedotto dal servizio. Impostare "scenario" a "responses" per la valutazione della risposta dell'agente, "traces" per la valutazione della traccia, "synthetic_data_gen_preview" per la valutazione dei dati sintetici (anteprima) o "red_team" per il red teaming.

Ogni scenario richiede analizzatori che definiscono i criteri di test. Per indicazioni sulla selezione degli analizzatori, vedere Analizzatori predefiniti.

Prerequisiti

  • Progetto Foundry.
  • Una distribuzione openAI Azure con un modello GPT che supporta il completamento della chat, ad esempio gpt-5-mini.
  • Azure Utente di intelligenza artificiale ruolo nel progetto Foundry.
  • 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.0.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
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

Specificare i dati inline

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",
            }
        ),
    ],
)

Passa source come "source" campo nella configurazione dell'origine dati quando crei 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 origine 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 utilizzando 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": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": 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. Il processo esegue ogni valutatore su ogni riga del set di dati.

# Create the evaluation
eval_object = 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 = 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 in 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 corrispondenti 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, quindi creare una valutazione usando il csv tipo di origine dati. La definizione dello schema e la configurazione dell'analizzatore sono uguali a quelle delle valutazioni JSONL. L'unica differenza è nella fonte dati "type": "csv".

# 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": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = 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 = 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 e valutare le risposte usando il azure_ai_target_completions tipo di origine dati con una azure_ai_model destinazione. I dati di input contengono query; il modello genera risposte che vengono 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 valutatori 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": {
            "deployment_name": 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 = 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 = 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 su GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati.

Suggerimento

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

Valutazione dell'obiettivo dell'agente

Invia query a un agente Foundry a runtime e valuta le risposte utilizzando il tipo di origine dati azure_ai_target_completions con destinazione azure_ai_agent. Questo scenario funziona sia per gli agenti prompt che 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 valutatori 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}} 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 dei 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": {
            "deployment_name": 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": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Creare una valutazione ed eseguire

eval_object = 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 = 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 invocazione 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 . Usa i segnaposto {{item.*}} per sostituire i campi nei 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 = 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 = 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 azure_ai_responses tipo di origine del dato. 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 delle Risposte o dai log di traccia 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 risposta

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 = 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 log di traccia o nella pipeline 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": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = 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 = 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

Valutare le interazioni dell'agente già acquisite in Application Insights. Usare il azure_ai_traces tipo di origine dati. 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 dei tracciati è l'approccio consigliato per valutare agenti non sviluppati con il servizio agente Microsoft Foundry, inclusi LangChain e framework personalizzati. A condizione che l'agente emetta span OpenTelemetry seguendo le convenzioni semantiche GenAI in Application Insights, l'analisi della traccia può esaminare le interazioni utilizzando gli stessi analizzatori disponibili per gli agenti 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.

Requisiti dei dati di traccia

La valutazione della traccia richiede che l'agente emetta intervalli seguendo le convenzioni semantiche OpenTelemetry per l'intelligenza artificiale generativa. In particolare, il servizio di valutazione legge le estensioni da Application Insights ed estrae i dati delle conversazioni dai loro attributi.

Vengono usati gli attributi di intervallo seguenti:

Attributo 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 eseguono il mapping a response. Se l'output contiene anche il tipo tool_call o il tipo tool_result, viene mappato a 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à) restituiranno 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.0.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 per effettuare query sulle tracce. Di default è 1.

Opzione A: Valuta tramite filtro dell'agente

L'approccio più semplice: consente 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 = 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 = 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 in base agli ID traccia

Per un maggiore controllo, raccogliere ID di traccia specifici da Application Insights e valutarli. Ciò è 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 = 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 = 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 valutatori e mappature dei dati

Durante la valutazione delle 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 richiesta dell'utente è stata 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 degli 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": {
            "deployment_name": 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": {
            "deployment_name": 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)

Generare query di test sintetiche, inviarle a un modello distribuito o a un agente Foundry e valutare le risposte usando il tipo di origine dati azure_ai_synthetic_data_gen_preview. Usare questo scenario quando non si dispone di un set di dati di test: il servizio genera query in base a un prompt fornito (e/o alle istruzioni dell'agente), le esegue sul target e valuta le risposte.

Suggerimento

Prima di iniziare, completare l'introduzione.

Funzionamento della valutazione dei dati sintetici

  1. Il servizio genera query sintetiche basate sul tuo prompt e su file di dati opzionali.
  2. Ogni query viene inviata alla destinazione specificata (modello o agente) per generare una risposta.
  3. I valutatori valutano ogni risposta utilizzando la query e la risposta generata.
  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ì Distribuzione del modello da usare per la generazione di 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 quando 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 specificato, il servizio genera automaticamente un nome.
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 valutatori e mappature dei dati

Il generatore di dati sintetici produce query nel {{item.query}} campo . L'obiettivo genera risposte disponibili in {{sample.output_text}}. Mappare questi campi ai tuoi 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": {
            "deployment_name": 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 = 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 = 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 si usa input_messages con la generazione di dati sintetici, includere solo system messaggi di ruolo: il servizio fornisce automaticamente le query generate come messaggi 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."
                }
            }
        ]
    },
}

Obiettivo agente

Creare interrogazioni sintetiche e valutare un agente di 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 = 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.

Ottenere risultati

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

Consultare i risultati

Le esecuzioni di valutazione sono asincrone. Interrogare periodicamente lo stato dell'esecuzione fino a quando non è completato, quindi recuperare i risultati.

import time
from pprint import pprint

while True:
    run = 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(
    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 "pass" o "fail" nel campo "label" in base alla "soglia".
  • Soglia: tutti i punteggi non binari vengono convertiti in "pass" o "fail" sulla base di una soglia predefinita, che l'utente può modificare nell'esperienza dell'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
}

Output di esempio (aggregazione)

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 per molto tempo

Il processo di valutazione potrebbe rimanere nello stato In esecuzione per un periodo prolungato. Ciò 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 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:

  • L'DefaultAzureCredential è configurato correttamente (eseguire az login se si usa interfaccia della riga di comando di Azure).
  • Il tuo account ha il ruolo Utente Azure AI 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 l'valutazione ha esito negativo a causa di uno schema dei dati o un errore di mapping:

  • 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à

Le creazioni delle esecuzioni di valutazione sono soggette a limitazioni di velocità 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 dettagli sulle limitazioni della velocità di risposta.
  • Usare il backoff esponenziale quando si ritentano richieste non riuscite.

Se un processo di valutazione fallisce 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-per-minuto (TPM) per la distribuzione del tuo modello nel portale di Azure.

Errori dello strumento di valutazione dell'agente

Se viene restituito un errore dal valutatore degli agenti per gli strumenti non supportati:

  • Controllare 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