Auswerten von Unterhaltungen in der Cloud (Vorschau)

Bewerten Sie vollständige Konversationen aus Datensätzen oder Ablaufverfolgungen aus Application Insights auf Äußerungs- oder Konversationsebene.

Voraussetzungen

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

Konversationsdatensätze auswerten

Bewerten Sie vollständige Unterhaltungen, um die Agentqualität über ganze Benutzerinteraktionen hinweg zu bewerten – nicht nur einzelne Antworten. Verwenden Sie die Evaluierung auf Konversationsebene, um Qualitätsprobleme wie unvollständige Aufgabenlösung, Benutzerfrustration und Regressionen bei Tool-Aufrufen zu identifizieren, die bei der Bewertung auf Turn-Ebene übersehen werden.

Betrachten Sie beispielsweise einen Support-Agenten, bei dem der Benutzer im Verlauf mehrerer Gesprächsrunden zunehmend frustriert wird:

Turn 1 — User: "Ich muss mein Kennwort zurücksetzen." Agent: "Ich habe Ihr Konto gefunden. Ich schicke einen Link zum Zurücksetzen.

Turn 2 — User: "Ich habe die E-Mail nicht erhalten." Agent: "Ich habe den Link erneut gesendet. Bitte überprüfen Sie Spam."

Turn 3 — Benutzer: "Immer noch nichts. „Können Sie es nicht einfach direkt zurücksetzen?“ Agent: „Ich habe einen weiteren Link zum Zurücksetzen gesendet.“

Ein Evaluator auf Turn-Ebene bewertet nur die letzte Antwort – die höflich ist und handelt – und erhält daher eine gute Bewertung. Ein Evaluator auf Gesprächsebene, der die Kundenzufriedenheit über den gesamten Gesprächsverlauf hinweg bewertet, stellt fest, dass der Agent dieselbe erfolglose Maßnahme dreimal wiederholt hat, ohne eine Alternative zu versuchen, sodass das Problem des Nutzers ungelöst blieb.

Die Bewertung auf Konversationsebene unterscheidet sich in mehreren Punkten von der Bewertung auf Turn-Ebene:

Aspect Durchlaufebene Konversationsebene
Umfang Einzelne Abfrageantwortpaare Vollständige Konversationen mit mehreren Nachrichten
Metrics Qualität und Sicherheit pro Reaktion Ergebnisse auf Konversationsebene und Benutzerzufriedenheit
Datenformat JSONL mit query und response Feldern JSONL mit einem messages Array, das die vollständige Unterhaltung enthält
Anwendungsfall Testen einzelner Modellantworten Testen der End-to-End-Agent-Erfahrungen

Die Bewertung auf Konversationsebene unterstützt vier Optionen für Datenquellen:

Auswahl Wann verwenden? Datenquellentyp
Aus Datensatz oder Inline Sie haben lokale Gesprächsprotokolle oder Testdaten. jsonl mit file_id oder file_content
Nach Konversations-ID Sie möchten bestimmte Unterhaltungen aus App Insights auswerten azure_ai_trace_data_source_preview mit trace_source
Nach Agentenfilter mit Sampling Sie möchten die Qualität des Agenten insgesamt anhand von stichprobenartig erfasstem Produktivverkehr bewerten. azure_ai_trace_data_source_preview mit trace_source
Simulierte Unterhaltungen Sie möchten synthetische Testgespräche generieren azure_ai_target_completions mit conversation_gen_preview

Auswählen einer Auswertungsstufe

Der evaluation_level-Parameter für die Ausführung bestimmt, ob Evaluatoren einzelne Durchläufe oder vollständige Unterhaltungen bewerten sollen:

Wert Behavior
"turn" Die Bewertungen der Evaluatoren werden jeweils unabhängig voneinander bewertet.
"conversation" Evaluatoren bewerten die gesamte Unterhaltung als Ganzes.
(weggelassen) Wird standardmäßig auf "turn" festgelegt.

Important

Evaluatorkompatibilität: Jeder Evaluator unterstützt bestimmte Auswertungsstufen. Überprüfen Sie das Feld des supported_evaluation_levelsEvaluators im Evaluator-Katalog.

  • Evaluatoren nur für einzelne Turns (z. B. fluency, relevance) können nicht mit evaluation_level="conversation" verwendet werden.
  • Derzeit unterstützen alle Evaluatoren auf Konversationsebene sowohl die Ebenen "turn" als auch "conversation".

Häufige Fehler

Fehler Ursache Lösung
Inkompatible Auswertungsebene Verwenden von evaluation_level="conversation" mit einem Evaluator nur für Durchläufe Entfernen sie den reinen Evaluator, oder ändern Sie den Wert in evaluation_level="turn"

Gesprächsdaten vorbereiten

Erstellen Sie eine JSONL-Datei, in der jede Zeile eine vollständige Unterhaltung im messages Feld enthält. Jede Nachricht sollte ein role (Benutzer, Assistent oder System) und ein content enthalten. Ein vollständiges Beispiel finden Sie in den Beispielen zur konversationsauswertung im 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?"}]}

Sie können auch Tooldefinitionen und Toolaufrufe einschließen, wenn Ihr Agent Tools verwendet:

{"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."}]}

Definieren des Datenschemas und der Auswerter

Geben Sie das Schema für Ihre Unterhaltungsdaten, "Nachrichten" an, und wählen Sie Evaluatoren aus, die für die Auswertung auf Unterhaltungsebene entwickelt wurden. Evaluatoren auf Unterhaltungsebene bewerten die gesamte Interaktion, nicht nur einzelne Durchläufe.

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

Auswertung erstellen und ausführen

Vorbereitung: sample_data_multiturn_conversations.jsonl herunterladen

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

Informationen zum Abfragen des Abschlussstatus und zum Interpretieren der Ergebnisse finden Sie unter Abrufen von Cloudauswertungsergebnissen.

Ein vollständiges, ausführbares Beispiel finden Sie auf GitHub unter sample_multiturn_conversation_evaluation.py.

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.

Note

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 Description
conversation_ids Ja Array von Konversations-IDs zur Auswertung.
lookback_hours Nein Stunden, die ab end_time nach hinten durchsucht werden sollen. Der Standardwert ist sieben Tage (168 Stunden).
end_time Nein 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["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

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

Note

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 Description
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 Description
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 Description
agent_name Ja Der Name des Agenten, nach dem Ablaufverfolgungen gefiltert werden sollen.
agent_version Nein Die Agent-Version. Wenn sie weggelassen wird, wird die neueste Version verwendet.
agent_id Nein 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 Nein Maximale Anzahl an Konversationen zur Auswahl. Der Standardwert ist 1.000.
filter_strategy Nein "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["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

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