Valutare le conversazioni nel cloud (anteprima)

Valutare le conversazioni complete dai set di dati o dalle tracce di Application Insights a livello di turno o di conversazione.

Prerequisiti

Gli esempi usano il client SDK configurato in Configurare il client SDK.

Valutare i set di dati di conversazione

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 utilizzare 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 Cause 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, consulta gli esempi di valutazione delle conversazioni 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/major city 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 della valutazione cloud.

Per un esempio completo eseguibile, consulta sample_multiturn_conversation_evaluation.py su GitHub.

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.

Note

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

Note

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

Per un esempio completo eseguibile, consulta sample_multiturn_trace_evaluation_by_id.py su GitHub.

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.

Note

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:

Format Esempio Description
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 Description
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 Description
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"},
    )

Note

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.

Passaggi successivi

  • Last updated on