Ocena wdrożonych konwersacji modelu i agenta przy użyciu zestawu SDK usługi Microsoft Foundry (wersja zapoznawcza)

Oceń pełne konwersacje produkcyjne przechwycone w usłudze Application Insights w celu zbadania określonych interakcji lub przykładowego ruchu wdrożonego agenta.

Wymagania wstępne

W przykładach użyto klienta zestawu SDK skonfigurowanego w temacie Konfigurowanie klienta zestawu SDK.

Ocenianie konwersacji według identyfikatora ze śladów

Oceń konkretne konwersacje z usługi Application Insights, podając ich identyfikatory konwersacji. Użyj tej opcji, aby ustalić przyczynę źródłową problemów lub zweryfikować poprawki dotyczące określonych interakcji. Możesz na przykład zbadać konwersację oflagowaną przez alert lub zweryfikować poprawkę znanego problemu.

Gdzie znaleźć identyfikatory konwersacji

Znajdź identyfikatory konwersacji w:

  • Interfejs użytkownika dzienników śledzenia Application Insights — przejrzyj interesujące ślady i znajdź pole conversation_id w szczegółach śladu.
  • Dane wyjściowe logowania aplikacji — Jeśli jawnie ustawisz conversation_id podczas tworzenia odpowiedzi agenta, pobierz je z dzienników.
  • Kontekst śledzenia OpenTelemetry — conversation_id może również pochodzić z nagłówka traceparent, jeśli agent używa standardowej propagacji kontekstu śledzenia.

Uwaga / Notatka

Definicje narzędzi są automatycznie pobierane ze śladów lub na żądanie z rejestru agentów. Nie musisz podawać ich w żądaniu.

Parametry do wyszukiwania identyfikatora konwersacji

Parametr Required Opis
conversation_ids Yes Tablica identyfikatorów konwersacji do oceny.
lookback_hours No Godziny wyszukiwania z powrotem z end_time. Wartość domyślna to siedem dni (168 godzin).
end_time No Koniec okna wyszukiwania (format ISO 8601). Domyślnie ustawiony jest aktualny czas. 
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"},
    )

Uwaga / Notatka

  • Pozyskiwanie danych przez usługę Application Insights może powodować opóźnienie między momentem wygenerowania śladów a momentem, w którym są one dostępne do oceny. Jeśli zapytanie nie znajdzie śladów, poczekaj kilka minut i spróbuj ponownie.
  • Maksymalny okres wsteczny to 7 dni (168 godzin). Aby uzyskać dostęp do wcześniejszych śladów, użyj start_time i end_time w granicach okresu przechowywania w usłudze App Insights.

Aby zobaczyć kompletny, gotowy do uruchomienia przykład, przejdź do pliku sample_multiturn_trace_evaluation_by_id.py na GitHubie.

Oceń wybrane rozmowy według filtra agenta

Oceń przykładowy zestaw konwersacji z usługi Application Insights, filtrując według nazwy agenta. Użyj tej opcji, aby ocenić całościową jakość agenta w całym ruchu produkcyjnym. Na przykład należy przeprowadzać regularne oceny jakości lub monitorować pogorszenie jakości w środowisku produkcyjnym.

Agent określony do filtrowania może być częścią konwersacji obejmującej wielu agentów. Filtr pasuje do każdej konwersacji, w której uczestniczył ten agent.

Uwaga / Notatka

Definicje narzędzi są automatycznie pobierane ze śladów lub na żądanie z rejestru agentów. Nie musisz podawać ich w żądaniu.

Pola tożsamości agenta

Określ agenta do filtrowania przy użyciu jednego z następujących formatów:

Format Example Opis
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Dwa oddzielne pola. Jeśli agent_version zostanie pominięty, użyj najnowszej wersji.
agent_id "agent_id": "my-agent:1" Pojedynczy ciąg w "name:version" formacie.

Strategie filtrowania

Strategy Opis
random_sampling (Domyślnie) Losowo wybrana próbka obejmująca do max_traces konwersacji.
smart_filtering Heurystyka zarządzana przez usługę, która faworyzuje „interesujące” ślady — rozmowy zawierające potencjalne problemy, przypadki brzegowe lub anomalie.

Parameters

Parametr Required Opis
agent_name Yes Nazwa agenta używana do filtrowania śladów.
agent_version No Wersja agenta. W przypadku pominięcia użyje najnowszej wersji.
agent_id No Alternatywa dla agent_name + agent_version. Pojedynczy ciąg w formacie "name:version".
start_time Yes Początek przedziału czasu (w sekundach epoki Uniksa, UTC).
end_time Yes Koniec przedziału czasu (w sekundach systemu Unix, UTC). Dodaj do +600 sekund, aby uniknąć opóźnienia pozyskiwania.
max_traces No Maksymalna liczba rozmów do wybrania w próbce. Wartość domyślna to 1 000.
filter_strategy No "random_sampling" (domyślnie) lub "smart_filtering" (heurystyka zarządzana przez usługę, preferująca interesujące trace’y).

Important

Przedział czasu (end_time - start_time) musi być co najmniej 15 minut (900 sekund). Ten wymóg wynika z tego, że zapytania dotyczące całej konwersacji stosują 5-minutowy bufor bezczynności na obu krańcach, aby uniknąć niepełnych konwersacji.

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

Uwaga / Notatka

Przedział czasu zapytania usługi App Insights jest obecnie ograniczony do maksymalnie 7 dni (168 godzin). Nie można uzyskać dostępu do śladów starszych niż 7 dni bez jawnego podawania start_time i end_time w ramach limitów przechowywania usługi App Insights.

Następne kroki

  • Last updated on