Utvärdera distribuerade modell- och agentkonversationer med Microsoft Foundry SDK (förhandsversion)

Utvärdera fullständiga produktionskonversationer som samlats in i Application Insights för att undersöka specifika interaktioner eller exempel på distribuerad agenttrafik.

Förutsättningar

I exemplen används SDK-klienten som konfigurerats i Konfigurera SDK-klienten.

Utvärdera konversationer efter ID från spårningar

Utvärdera specifika konversationer från Application Insights genom att ange deras konversations-ID: n. Använd det här alternativet för att hitta grundorsaken till problem eller verifiera korrigeringar för specifika interaktioner. Du kan till exempel undersöka en konversation som flaggas av en avisering eller verifiera en korrigering för ett känt problem.

Var du hittar konversations-ID:t

Hitta konversations-ID:t i:

  • Application Insights-användargränssnittet för spårningsloggar – Bläddra till intressanta spårningar och leta upp conversation_id fältet i spårningsinformationen.
  • Programmets loggningsutdata – Om du uttryckligen anger conversation_id när du skapar agentsvar hämtar du det från loggarna.
  • OpenTelemetry-spårningskontext — conversation_id kan också härledas från traceparent-huvudet om agenten använder standardmässig spridning av spårningskontext.

Note

Verktygsdefinitioner hämtas automatiskt från spårningarna eller efterfrågas från agentregistret. Du behöver inte ange dem i begäran.

Parametrar för konversations-ID-sökning

Parameter Obligatoriskt Beskrivning
conversation_ids Yes Lista med konversations-ID:n som ska utvärderas.
lookback_hours No Antal timmar att söka bakåt från end_time. Standardinställningen är sju dagar (168 timmar).
end_time No Slutet av sökfönstret (ISO 8601-format). Standardvärdet är den aktuella tiden. 
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"},
    )

Note

  • Application Insights-datainmatning kan orsaka en fördröjning mellan när spårningar genereras och när de är tillgängliga för utvärdering. Om frågan inte hittar spårningar väntar du några minuter och försöker igen.
  • Den längsta återblicksperioden är 7 dagar (168 timmar). Om du vill komma åt äldre spår använder du start_time och end_time inom kvarhållningsgränserna för App Insights.

För ett fullständigt körbart exempel, se sample_multiturn_trace_evaluation_by_id.py på GitHub.

Utvärdera exempelkonversationer efter agentfilter

Utvärdera en exempeluppsättning konversationer från Application Insights genom att filtrera efter agentnamn. Använd det här alternativet för att utvärdera den övergripande agentkvaliteten i produktionstrafiken. Kör till exempel regelbundna kvalitetsbedömningar eller övervaka kvalitetsförsämring i produktionen.

Agenten som du anger för filtrering kan ingå i en konversation med flera agenter. Filtret matchar alla konversationer där agenten deltog.

Note

Verktygsdefinitioner hämtas automatiskt från spårningarna eller efterfrågas från agentregistret. Du behöver inte ange dem i begäran.

Agentidentitetsfält

Ange vilken agent som ska filtreras med något av följande format:

Format Example Beskrivning
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Två separata fält. Om agent_version utelämnas använder du den senaste versionen.
agent_id "agent_id": "my-agent:1" Enkel sträng i "name:version" format.

Filterstrategier

Strategy Beskrivning
random_sampling (Standard) Enhetligt slumpmässigt urval upp till max_traces konversationer.
smart_filtering En tjänsthanterad heuristik som prioriterar ”intressanta” spår – konversationer med potentiella problem, gränsfall eller avvikelser.

Parameters

Parameter Obligatoriskt Beskrivning
agent_name Yes Namnet på agenten som spårningar ska filtreras efter.
agent_version No Agentens version. Om det utelämnas använder du den senaste versionen.
agent_id No Alternativ till agent_name + agent_version. Enkel sträng i format "name:version".
start_time Yes Start av tidsfönstret (Unix-epoksekunder, UTC).
end_time Yes Slutet av tidsfönstret (Unix-epoksekunder, UTC). Lägg till 600 sekunder för att undvika inläsningsfördröjning.
max_traces No Maximalt antal konversationer som ska samplas. Standardvärdet är 1 000.
filter_strategy No "random_sampling" (standard) eller "smart_filtering" (tjänsthanterad heuristik som gynnar intressanta spår).

Important

Tidsfönstret (end_time - start_time) måste vara minst 15 minuter (900 sekunder). Det här kravet finns eftersom frågor på konversationsnivå tillämpar en 5-minuters inaktivitetsbuffert på varje kant för att undvika partiella konversationer.

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

Note

Frågetidsintervallet för App Insights är för närvarande begränsat till högst 7 dagar (168 timmar). Du kan inte komma åt spårningar som är äldre än 7 dagar utan att uttryckligen ange start_time och end_time inom App Insights-kvarhållningsgränser.

Nästa steg

  • Last updated on