Valutare le conversazioni di modelli e agenti distribuite con Microsoft Foundry SDK (anteprima)

Valutare le conversazioni di produzione complete acquisite in Application Insights per analizzare interazioni specifiche o il traffico dell'agente distribuito di esempio.

Prerequisiti

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

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.

Annotazioni

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

Parametri per la ricerca dell'ID della conversazione

Parametro Obbligatorio Descrizione
conversation_ids Yes 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["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_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="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"},
    )

Annotazioni

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

Annotazioni

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 Example Descrizione
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Due campi separati. Se agent_version viene omesso, usare la versione più recente.
agent_id "agent_id": "my-agent:1" Stringa singola in "name:version" formato.

Strategie di filtro

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

Parameters

Parametro Obbligatorio Descrizione
agent_name Yes 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 Yes Inizio dell'intervallo di tempo (secondi dell'epoca Unix, UTC).
end_time Yes 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["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_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}}"},
        ),
    ]

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

Annotazioni

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