Valutare gli agenti di intelligenza artificiale

La valutazione è essenziale per garantire che l'agente soddisfi gli standard di qualità e sicurezza prima della distribuzione. Eseguendo valutazioni durante lo sviluppo, si stabilisce una linea di base per le prestazioni dell'agente e si possono impostare soglie di accettazione, ad esempio 85% frequenza di superamento dell'attività, prima di rilasciarla agli utenti.

In questo articolo imparerai come eseguire una valutazione mirata all'agente su un agente Foundry o un agente ospitato utilizzando analizzatori predefiniti per la qualità, la sicurezza e il comportamento dell'agente. In particolare, tu:

Configurare il client SDK per la valutazione.
Scegliere i valutatori per la qualità, la sicurezza e il comportamento degli agenti.
Creare un set di dati di test ed eseguire una valutazione.
Interpretare i risultati e integrarli nel flusso di lavoro.

Suggerimento

Per la valutazione generica dei modelli di intelligenza artificiale generativi e delle applicazioni, inclusi analizzatori personalizzati, origini dati diverse e opzioni aggiuntive dell'SDK, vedere Eseguire valutazioni dall'SDK.

Prerequisiti

Python 3.8 o versione successiva.
Progetto Foundry con un agente o un agente ospitato.
Una distribuzione openAI Azure con un modello GPT che supporta il completamento della chat, ad esempio gpt-4o o gpt-4o-mini).
Ruolo di Utente Azure AI nel progetto Foundry.

Nota

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

Configurare il client

Installare Foundry SDK e configurare l'autenticazione:

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

Creare il client del progetto. Gli esempi di codice seguenti presuppongono che vengano eseguiti in questo contesto:

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

Scegliere gli analizzatori

Gli analizzatori sono funzioni che valutano le risposte dell'agente. Alcuni analizzatori usano i modelli di intelligenza artificiale come giudici, mentre altri usano regole o algoritmi. Per la valutazione dell'agente, prendere in considerazione questo insieme:

Valutatore	Cosa misura
Adesione al compito	L'agente segue le istruzioni di sistema?
Coerenza	La risposta è logica e ben strutturata?
Violenza	La risposta contiene contenuti violenti?

Per altri analizzatori predefiniti, vedere:

Valutatori di agenti: valutano l'efficacia con cui gli agenti gestiscono attività, strumenti e intenzioni degli utenti.
Analizzatori di qualità : misurare la qualità complessiva delle risposte generate.
Analizzatori di somiglianza del testo : confrontare il testo generato con le risposte di riferimento usando le metriche NLP.
Analizzatori di sicurezza : identificare potenziali rischi per contenuti e sicurezza nell'output generato.

Per creare analizzatori personalizzati, vedere Analizzatori personalizzati.

Creare un set di dati di test

Creare un file JSONL con query di test per il tuo agente. Ogni riga contiene un oggetto JSON con un query campo:

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

Caricare questo file come set di dati nel progetto:

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

Eseguire una valutazione

Quando si esegue una valutazione, il servizio invia ogni query di test all'agente, acquisisce la risposta e applica gli analizzatori selezionati per assegnare un punteggio ai risultati.

Configurare prima di tutto gli analizzatori. Ogni analizzatore necessita di un mapping dei dati che indica dove trovare gli input:

{{item.X}} fa riferimento ai campi dei dati di test, ad esempio query.
{{sample.output_items}} fa riferimento alla risposta completa dell'agente, incluse le chiamate agli strumenti.
{{sample.output_text}} fa riferimento solo al testo del messaggio di risposta.

Gli analizzatori assistiti dall'intelligenza artificiale, come Task Adherence e Coherence, richiedono un nome di implementazione del modello in initialization_parameters. Il valore deve corrispondere a un nome di distribuzione GPT del tuo progetto, ovvero il modello di giudice usato per assegnare punteggi alle risposte. Alcuni analizzatori potrebbero richiedere campi aggiuntivi, ad esempio ground_truth o definizioni degli strumenti. Per altre informazioni, vedere la documentazione dell'analizzatore.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "Task Adherence",
        "evaluator_name": "builtin.task_adherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Creare quindi la valutazione. Una valutazione definisce lo schema dei dati di test e i criteri di test. Serve come contenitore per più esecuzioni. Tutte le esecuzioni con la stessa valutazione sono conformi allo stesso schema e producono lo stesso set di metriche. Questa coerenza è importante per confrontare i risultati tra le esecuzioni.

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

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

Infine, crea un'esecuzione che invii le query di test all'agente e applichi i valutatori:

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": dataset.id,
        },
        "input_messages": {
            "type": "template",
            "template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": "my-agent",  # Replace with your agent name
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

Suggerimento

Questo esempio funziona sia per gli agenti "prompt" che per gli agenti ospitati che utilizzano il protocollo delle risposte. Per gli agenti ospitati che usano il protocollo di invocazione, il formato input_messages è diverso: fornisci un oggetto JSON non strutturato anziché il modello strutturato. Per informazioni dettagliate ed esempi di codice, vedere Protocollo chiamate dell'agente ospitato nella guida alla valutazione del cloud.

Interpretare i risultati

Le valutazioni vengono in genere completate in pochi minuti, a seconda del numero di query. Effettuare il polling per completare e ottenere l'URL del report per visualizzare i risultati nel portale Microsoft Foundry nella scheda Evaluations:

import time

# Wait for completion
while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

Risultati aggregati

A livello di esecuzione, è possibile visualizzare i dati aggregati, inclusi i conteggi dei passaggi e degli errori, l'utilizzo dei token per modello e i risultati per ogni analizzatore:

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        },
        ...
    ],
    "per_testing_criteria_results": [
        {
            "testing_criteria": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

Output a livello di riga

Ogni esecuzione di valutazione restituisce gli elementi di output per riga nel set di dati di test, offrendo visibilità dettagliata sulle prestazioni dell'agente. Gli elementi di output includono la query originale, la risposta dell'agente, i risultati dei singoli analizzatori con punteggi e ragionamenti e l'utilizzo dei token:

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Task Adherence",
            "metric": "task_adherence",
            "label": "pass",
            "reason": "Agent followed system instructions correctly",
            "threshold": 3,
            "passed": true,
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        ... // remaining evaluation results
    ]
}

Integrazione nel flusso di lavoro

Pipeline CI/CD: Usare la valutazione come filtro di qualità nella pipeline di distribuzione. Per un'integrazione dettagliata, vedere Eseguire valutazioni con GitHub Actions.
Monitoraggio della produzione: monitorare l'agente nell'ambiente di produzione usando la valutazione continua. Per istruzioni sull'installazione, vedere Configurare la valutazione continua.

Ottimizzare e confrontare le versioni

Usare la valutazione per iterare e migliorare l'agente:

Eseguire la valutazione per identificare le aree deboli. Usare l'analisi del cluster per trovare modelli ed errori.
Modificare le istruzioni o gli strumenti dell'agente in base ai risultati.
Rivalutare e confrontare le esecuzioni per misurare il miglioramento.
Ripetere finché non vengono soddisfatte le soglie di qualità.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-05-01