Unterhaltungen mit bereitgestellten Modellen und Agents mit dem Microsoft Foundry SDK (Vorschau) bewerten

Werten Sie vollständige Unterhaltungen aus der Produktionsumgebung aus, die in Application Insights erfasst wurden, um bestimmte Interaktionen zu untersuchen oder den Datenverkehr des bereitgestellten Agents stichprobenartig zu analysieren.

Voraussetzungen

In den Beispielen wird der in SDK-Client einrichten konfigurierte SDK-Client verwendet.

Konversationen anhand der ID aus Ablaufverfolgungen auswerten

Bewerten Sie bestimmte Unterhaltungen aus Application Insights, indem Sie ihre Unterhaltungs-IDs bereitstellen. Verwenden Sie diese Option, um Ursachen von Problemen zu ermitteln oder Fehlerbehebungen bei bestimmten Interaktionen zu überprüfen. Sie können z. B. eine Unterhaltung untersuchen, die durch eine Warnung gekennzeichnet ist, oder eine Lösung für ein bekanntes Problem überprüfen.

Wo Sie Konversations-IDs finden

Finden Sie Konversations-IDs in:

  • Benutzeroberfläche der Application Insights-Trace-Protokolle: Wechseln Sie zu relevanten Traces, und suchen Sie das Feld conversation_id in den Trace-Details.
  • Die Protokollierungsausgabe Ihrer Anwendung – Wenn Sie beim Erstellen von Agentantworten explizit festlegen conversation_id , rufen Sie sie aus Ihren Protokollen ab.
  • OpenTelemetry-Trace-Kontext — Das conversation_id kann auch aus dem traceparent-Header abgeleitet werden, wenn Ihr Agent die standardmäßige Weitergabe des Trace-Kontexts verwendet.

Hinweis

Tooldefinitionen werden automatisch aus den Traces abgerufen oder aus der Agent-Registrierung abgefragt. Sie müssen sie nicht in der Anforderung angeben.

Parameter für die Suche nach Konversations-ID

Parameter Erforderlich Beschreibung
conversation_ids Ja Array von Konversations-IDs zur Auswertung.
lookback_hours No Stunden, die ab end_time nach hinten durchsucht werden sollen. Der Standardwert ist sieben Tage (168 Stunden).
end_time No Ende des Suchfensters (ISO 8601-Format). Standardmäßig ist die aktuelle Uhrzeit eingestellt. 
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"},
    )

Hinweis

  • Die Datenerfassung in Application Insights kann zu einer Verzögerung zwischen dem Generieren von Traces und ihrer Verfügbarkeit für die Bewertung führen. Wenn die Abfrage keine Traces findet, warten Sie einige Minuten und versuchen Sie es erneut.
  • Der maximale Lookback beträgt 7 Tage (168 Stunden). Um auf ältere Ablaufverfolgungen zuzugreifen, verwenden Sie start_time und end_time innerhalb Ihrer App Insights-Aufbewahrungsgrenzen.

Ein vollständig lauffähiges Beispiel finden Sie auf GitHub unter sample_multiturn_trace_evaluation_by_id.py.

Stichprobenartig ausgewählte Gespräche nach Agentenfilter auswerten

Bewerten Sie eine stichprobenbasierte Gruppe von Unterhaltungen aus Application Insights, indem Sie nach Agentnamen filtern. Verwenden Sie diese Option, um die Gesamtqualität des Agents über den gesamten Produktionsdatenverkehr hinweg zu bewerten. Führen Sie z. B. regelmäßige Qualitätsbewertungen aus, oder überwachen Sie qualitätsbeeinträchtigungen in der Produktion.

Der Agent, den Sie zum Filtern angeben, kann Teil einer Konversation mit mehreren Agenten sein. Der Filter entspricht jeder Unterhaltung, an der dieser Agent teilgenommen hat.

Hinweis

Tooldefinitionen werden automatisch aus den Traces abgerufen oder aus der Agent-Registrierung abgefragt. Sie müssen sie nicht in der Anforderung angeben.

Agent-Identitätsfelder

Geben Sie den zu filternden Agent mithilfe eines der folgenden Formate an:

Format Example Beschreibung
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Zwei separate Felder. Wenn agent_version weggelassen wird, verwenden Sie die neueste Version.
agent_id "agent_id": "my-agent:1" Einzelne Zeichenfolge im "name:version" Format.

Filterstrategien

Strategy Beschreibung
random_sampling (Standard) Gleichverteilte Zufallsstichprobe von bis zu max_traces Konversationen.
smart_filtering Dienstverwaltete Heuristik, die interessante Traces bevorzugt – also Konversationen mit potenziellen Problemen, Randfällen oder Anomalien.

Parameters

Parameter Erforderlich Beschreibung
agent_name Ja Der Name des Agenten, nach dem Ablaufverfolgungen gefiltert werden sollen.
agent_version No Die Agent-Version. Wenn sie weggelassen wird, wird die neueste Version verwendet.
agent_id No Alternative zu agent_name + agent_version. Einzelne Zeichenfolge im Format "name:version".
start_time Ja Beginn des Zeitfensters (Unix-Epochenzeit in Sekunden, UTC).
end_time Ja Ende des Zeitfensters (Sekunden seit der Unix-Epoche, UTC). Um +600 Sekunden auffüllen, um Verzögerungen bei der Datenaufnahme zu vermeiden.
max_traces No Maximale Anzahl an Konversationen zur Auswahl. Der Standardwert ist 1.000.
filter_strategy No "random_sampling" (Standard) oder "smart_filtering" (vom Dienst verwaltete Heuristik, die interessante Traces bevorzugt).

Important

Das Zeitfenster (end_time - start_time) muss mindestens 15 Minuten (900 Sekunden) betragen. Diese Anforderung ist vorhanden, da Abfragen auf Unterhaltungsebene einen 5-minütigen Inaktivitätspuffer auf jedem Rand anwenden, um partielle Unterhaltungen zu vermeiden.

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

Hinweis

Der Zeitbereich der App Insights-Abfrage ist derzeit auf maximal 7 Tage (168 Stunden) beschränkt. Sie können nicht auf Ablaufverfolgungen zugreifen, die älter als 7 Tage sind, ohne start_time und end_time innerhalb der Aufbewahrungsgrenzen von App Insights explizit anzugeben.

Nächste Schritte

  • Last updated on