Geïmplementeerde model- en agentgesprekken evalueren met Microsoft Foundry SDK (preview)

Evalueer volledige productiegesprekken die zijn vastgelegd in Application Insights om specifieke interacties of voorbeeld van geïmplementeerd agentverkeer te onderzoeken.

Prerequisites

In de voorbeelden wordt de SDK-client gebruikt die is geconfigureerd in de SDK-client instellen.

Gesprekken evalueren op basis van ID uit traces

Evalueer specifieke gesprekken van Application Insights door hun gespreks-id's op te geven. Gebruik deze optie om de hoofdoorzaak van problemen te achterhalen of oplossingen voor specifieke interacties te verifiëren. U kunt bijvoorbeeld een gesprek onderzoeken dat is gemarkeerd door een waarschuwing of een oplossing voor een bekend probleem controleren.

Waar kunt u gespreks-id's vinden

Gespreks-ID's zoeken in:

  • Gebruikersinterface voor traceringslogboeken van Application Insights : blader naar interessante traceringen en zoek het conversation_id veld in de traceringsdetails.
  • De loguitvoer van uw toepassing — Als u conversation_id expliciet instelt bij het maken van agentreacties, haalt u deze op uit uw loggegevens.
  • OpenTelemetry-traceringscontext : deze conversation_id kan ook worden afgeleid van de traceparent-header als uw agent gebruikmaakt van standaarddoorgifte van traceringscontext.

Opmerking

Tooldefinities worden automatisch opgehaald uit de traces of opgevraagd uit het agentregister. U hoeft ze niet op te geven in de aanvraag.

Parameters voor opzoeken van gespreks-id

Parameter Required Beschrijving
conversation_ids Ja Lijst met gespreks-ID's om te evalueren.
lookback_hours No Aantal uren om terug te zoeken vanaf end_time. De standaardwaarde is zeven dagen (168 uur).
end_time No Einde van het zoekvenster (ISO 8601-indeling). De standaardinstelling is de huidige tijd. 
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"},
    )

Opmerking

  • Gegevensopname van Application Insights kan een vertraging veroorzaken tussen wanneer traceringen worden gegenereerd en wanneer ze beschikbaar zijn voor evaluatie. Als de query geen traceringen vindt, wacht u enkele minuten en probeert u het opnieuw.
  • De maximale terugkijkperiode is 7 dagen (168 uur). Gebruik start_time en end_time om oudere traceringen te openen binnen uw bewaarlimieten voor App Insights.

Zie sample_multiturn_trace_evaluation_by_id.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd.

Voorbeeldgesprekken evalueren op agentfilter

Evalueer een voorbeeldset gesprekken van Application Insights door te filteren op de naam van de agent. Gebruik deze optie om de algehele kwaliteit van agents binnen het productieverkeer te beoordelen. Voer bijvoorbeeld regelmatig kwaliteitsevaluaties uit of controleer op kwaliteitsvermindering in de productie.

De agent die u opgeeft voor filteren, kan deel uitmaken van een gesprek met meerdere agents. Het filter komt overeen met een gesprek waaraan die agent heeft deelgenomen.

Opmerking

Tooldefinities worden automatisch opgehaald uit de traces of opgevraagd uit het agentregister. U hoeft ze niet op te geven in de aanvraag.

Agentidentiteitsvelden

Geef de agent op die moet worden gefilterd met behulp van een van deze indelingen:

Format Voorbeeld Beschrijving
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Twee afzonderlijke velden. Als agent_version wordt weggelaten, gebruik dan de nieuwste versie.
agent_id "agent_id": "my-agent:1" Eén tekenreeks in "name:version" indeling.

Filterstrategieën

Strategy Beschrijving
random_sampling (Standaard) Een aselecte steekproef van maximaal max_traces gesprekken.
smart_filtering Door de service beheerde heuristiek die de voorkeur geeft aan 'interessante' traces: gesprekken met potentiële problemen, randgevallen of afwijkingen.

Parameters

Parameter Required Beschrijving
agent_name Ja De agentnaam om traces op te filteren.
agent_version No De versie van de agent. Als u dit weglaat, wordt de nieuwste versie gebruikt.
agent_id No Alternatief voor agent_name + agent_version. Eén tekenreeks in indeling "name:version".
start_time Ja Begin van het tijdvenster (Unix epoch seconds, UTC).
end_time Ja Einde van het tijdvenster (Unix-epochtijd in seconden, UTC). Houd een marge van +600 seconden aan om innamevertraging te voorkomen.
max_traces No Maximum aantal gesprekken dat u kunt samplen. Standaard ingesteld op 1.000.
filter_strategy No "random_sampling" (standaard) of "smart_filtering" (door de service beheerde heuristiek die de voorkeur geeft aan interessante traces).

Important

Het tijdvenster (end_time - start_time) moet ten minste 15 minuten (900 seconden) zijn. Deze vereiste bestaat omdat query's op gespreksniveau een buffer van 5 minuten inactiviteit toepassen op elke rand om gedeeltelijke gesprekken te voorkomen.

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

Opmerking

De tijdsduur van de App Insights-query is momenteel beperkt tot maximaal 7 dagen (168 uur). U hebt geen toegang tot traceringen die ouder zijn dan 7 dagen zonder expliciet start_time en end_time op te geven binnen de retentielimieten van App Insights.

Volgende stappen 

  • Last updated on