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.

Questo articolo illustra come eseguire una valutazione mirata per agenti su un agente Foundry o un agente ospitato. Si utilizza un valutatore basato su una rubrica generato a partire dal contesto dell'agente come misura primaria, a cui si aggiungono valutatori predefiniti per la sicurezza dei contenuti e per altri rischi. In particolare, tu:

• Configurare il client SDK per la valutazione.
• Generare un analizzatore di rubriche personalizzato per l'agente e associarlo agli analizzatori predefiniti.
• Creare un set di dati di test ed eseguire una valutazione.
• Interpretare i risultati e integrarli nel flusso di lavoro.

Prerequisiti

• Python 3.8 o versione successiva.

• Un progetto Foundry con un agente o un agente ospitato.

• Una distribuzione OpenAI di Azure con un modello GPT che supporta il completamento della chat (ad esempio, gpt-4o o gpt-4o-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.

Configurare il client

Installare Foundry SDK e configurare l'autenticazione:

pip install "azure-ai-projects>=2.4.0" azure-identity

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 valutano le risposte dell'agente. La misura primaria consigliata per la valutazione dell'agente è un analizzatore di rubriche, ovvero un set di dimensioni di punteggio ponderate che un giudice LLM applica a ogni risposta, in modo da poter esprimere i criteri esatti che interessano (ad esempio, l'applicazione dei criteri, l'accuratezza dell'utilizzo degli strumenti o la chiarezza delle comunicazioni) e assegnare punteggi in modo coerente su larga scala. Per informazioni dettagliate, vedere Analizzatori di rubriche.

Associa la tua griglia di valutazione a valutatori aggiuntivi per ottenere una copertura completa del tuo ambito di valutazione:

• 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.
• Analizzatori personalizzati : creare analizzatori personalizzati quando le rubriche e le impostazioni predefinite non coprono i criteri.

È possibile creare una rubrica a mano o generarne una dal contesto dell'agente, ovvero il nome, le istruzioni e gli strumenti. L'esempio seguente genera una rubrica e ne stampa le dimensioni in modo da poterle esaminare prima dell'uso.

import time
import uuid
from azure.ai.projects.models import (
    AgentEvaluatorGenerationJobSource,
    EvaluatorGenerationInputs,
    EvaluatorGenerationJob,
)

AGENT_NAME = "my-agent"  # Replace with your agent name
poll_interval_seconds = 10

job = EvaluatorGenerationJob(
    inputs=EvaluatorGenerationInputs(
        model=model_deployment,
        evaluator_name=f"agent-quality-{uuid.uuid4().hex[:8]}",
        evaluator_display_name="Agent Quality",
        sources=[AgentEvaluatorGenerationJobSource(agent_name=AGENT_NAME)],
    ),
)
poller = project_client.beta.evaluators.begin_create_generation_job(job=job)

# Optional: While SDK is polling, periodically print the job status until the job is complete
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

rubric_evaluator = poller.result()

print(f"Generated rubric {rubric_evaluator.name} v{rubric_evaluator.version}")
for dim in rubric_evaluator.definition.dimensions:
    print(f"  - {dim.id} (weight {dim.weight}): {dim.description}")

Per un esempio eseguibile completo, vedere sample_rubric_evaluator_generation_all_sources.py su GitHub. Per creare a mano una rubrica, vedere sample_rubric_evaluator_manual.py.

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 i valutatori selezionati per assegnare un punteggio ai risultati.

Prima di tutto, configurare i criteri di test. Fai riferimento al valutatore della rubrica generato per nome. Ogni voce usa data_mapping per fare riferimento ai campi nei dati di test e nella risposta dell'agente, e initialization_parameters per passare le impostazioni del valutatore:

• {{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.
• initialization_parameters={"deployment_name": <model>} fornisce il modello di giudice. Generalmente richiesto per i valutatori basati su LLM che fungono da giudice. Per i parametri per analizzatore, vedere Analizzatori predefiniti.

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Agent Quality",
        evaluator_name=rubric_evaluator.name,
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
]

Per aggiungere i valutatori integrati accanto alla griglia di valutazione, aggiungere voci con la stessa struttura ma evaluator_name="builtin.<name>". Ad esempio, aggiungere violenza (sicurezza del contenuto) e coerenza (qualità del giudice LLM):

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"deployment_name": model_deployment},
        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. Funge da 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.

from openai.types.eval_create_params import DataSourceConfigCustom

data_source_config = DataSourceConfigCustom(
    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": AGENT_NAME,
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

Interpretare i risultati

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

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": "Agent Quality", "passed": 1, "failed": 2, "errored": 0 },
        { "testing_criteria": "Violence",      "passed": 3, "failed": 0, "errored": 0 },
        { "testing_criteria": "Coherence",     "passed": 2, "failed": 1, "errored": 0 }
    ]
}

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": "Agent Quality",
            "score": 0.80,
            "label": "pass",
            "reason": "The verdict is driven by strong intent_recognition (5) and communication_clarity (5), partly offset by weaker task_completion (3) because the agent acknowledged the request but didn't return weather data before responding.",
            "threshold": 0.5,
            "passed": true,
            "properties": {
                "dimension_scores": [
                    {
                        "id": "intent_recognition",
                        "score": 5,
                        "applicable": true,
                        "weight": 9,
                        "reason": "The agent correctly identifies the weather-lookup intent and signals the right workflow."
                    },
                    {
                        "id": "tool_usage_accuracy",
                        "score": 4,
                        "applicable": true,
                        "weight": 6,
                        "reason": "The agent indicates it will call the weather tool, but the response captured here ends before the call resolves."
                    },
                    ... // task_completion (3, weight 6), communication_clarity (5, weight 3)
                ]
            },
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Violence",
            "metric": "violence",
            "score": 0.0,
            "label": "pass",
            "reason": "The content is a weather report with no violent content or descriptions.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Coherence",
            "metric": "coherence",
            "score": 4.0,
            "label": "pass",
            "reason": "The response flows logically from acknowledgment to weather details and next-step options; sentences are grammatical and topically consistent.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        }
    ]
}

L'properties.dimension_scores array mostra la suddivisione per dimensione prodotta dal valutatore LLM. Ogni dimensione score è su una scala da 1 a 5. Il livello score superiore è la media ponderata dei punteggi di dimensione applicabili, normalizzati in un intervallo da 0 a 1. Per lo schema di output completo, vedere Analizzatori di rubriche.

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:

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

Contenuto correlato

• Analizzatori rubrici
• Generare un set di dati di valutazione sintetica
• Convertire le tracce dell'agente in set di dati di valutazione
• Esempi di valutazione di Python SDK
• Esempio di generazione dell'analizzatore rubrico (Python)
• Eseguire il red teaming per intelligenza artificiale
• Dashboard di monitoraggio dell'agente
• Riferimenti per i valutatori di agenti
• Informazioni di riferimento sulle API REST
• Valutazione della traccia nel cloud
• Configurare il tracciamento in Microsoft Foundry