Ocena poszczególnych interakcji z wdrożonych modeli i agentów przy użyciu zestawu SDK usługi Microsoft Foundry

Ważna

Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Oceń zapisane odpowiedzi lub ślady OpenTelemetry pochodzące z wdrożonych agentów i modeli bez ponownego odtwarzania oryginalnych żądań.

Wymagania wstępne

  • Ukończ wymagania wstępne dotyczące oceny chmury i konfigurację klienta.
  • Zapisane identyfikatory odpowiedzi na potrzeby oceny odpowiedzi lub zasób usługi Application Insights połączony z projektem Foundry na potrzeby oceny śledzenia.
  • Funkcja OpenTelemetry obejmuje zakresy spełniające wymagania dotyczące danych śledzenia podczas oceniania śladów.

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

Ocena interakcji według identyfikatora odpowiedzi

Pobierz i oceń odpowiedzi agenta Foundry według identyfikatorów odpowiedzi przy użyciu azure_ai_responses typu źródła danych. Użyj tego scenariusza, aby ocenić konkretne interakcje agentów po ich wystąpieniu.

Tip

Przed rozpoczęciem ukończ konfigurację klienta.

Identyfikator odpowiedzi jest unikatowym identyfikatorem zwracanym za każdym razem, gdy agent rozwiązania Foundry generuje odpowiedź. Identyfikatory odpowiedzi można zbierać z interakcji agenta przy użyciu interfejsu API odpowiedzi lub dzienników śledzenia aplikacji. Podaj identyfikatory bezpośrednio w treści pliku.

Ważna

Oceny odpowiedzi agenta (azure_ai_responses) obsługują tylko file_content do podawania identyfikatorów odpowiedzi. Typ file_id źródła nie jest obsługiwany i zwraca 400 Bad Request błąd.

Zbieranie identyfikatorów odpowiedzi

Każde wywołanie interfejsu API odpowiedzi zwraca obiekt odpowiedzi z unikatowym id polem. Zbierz te identyfikatory z interakcji aplikacji lub wygeneruj je bezpośrednio:

# Generate response IDs by calling a model through the Responses API
response = openai_client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Identyfikatory odpowiedzi można również zbierać podczas interakcji z agentem w dziennikach śledzenia aplikacji lub linii monitorowania. Każdy identyfikator odpowiedzi jednoznacznie identyfikuje przechowywaną odpowiedź, którą może pobrać usługa oceny.

Utwórz ewaluację i uruchom

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
    ),
]

eval_object = openai_client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

Aby uzyskać pełny przykład z możliwością uruchamiania, zobacz sample_agent_response_evaluation.py w GitHub. Aby sprawdzać, czy proces został ukończony, i interpretować wyniki, zobacz Pobieranie wyników oceny w chmurze.

Ocena śladów (wersja zapoznawcza)

Ocena interakcji agenta przechwyconych już przez usługę Application Insights. Użyj typu źródła danych azure_ai_traces. Ten scenariusz jest przydatny w przypadku oceny rzeczywistego ruchu produkcyjnego po wdrożeniu. Wybierasz ślady z potoku monitorującego i uruchamiasz na nich ewaluatory bez ponownego odtwarzania żądań.

Ważna

Ocena na podstawie śladów jest zalecanym podejściem do oceniania agentów, którzy nie zostali utworzeni za pomocą usługi Microsoft Foundry Agent Service — w tym agentów opartych na LangChain i niestandardowych frameworkach. Jeśli agent emituje zakresy OpenTelemetry zgodnie z konwencjami semantycznymi GenAI do usługi Application Insights, ocena śledzenia może ocenić swoje interakcje przy użyciu tych samych ewaluatorów dostępnych dla agentów usługi Foundry.

Ocena śledzenia obsługuje dwa tryby:

  • Według identyfikatorów śledzenia - Oceniaj określone interakcje agenta, podając ich wartości operation_Id z usługi Application Insights.
  • Według filtra agenta — automatycznie wykrywaj i oceniaj ostatnie ślady śledzenia dla wybranego agenta bez ręcznego zbierania identyfikatorów śladów.

Tip

Przed rozpoczęciem ukończ konfigurację klienta. Ten scenariusz wymaga również zasobu usługi Application Insights połączonego z projektem Foundry.

Inteligentne próbkowanie

Funkcja oceny śledzenia obsługuje inteligentne próbkowanie, które wybiera reprezentatywny podzbiór śladów do oceny zamiast oceniania każdego przechwyconego śladu. Włącz przełącznik Inteligentne próbkowanie w portalu Foundry podczas konfigurowania przebiegu oceny śledzenia. Inteligentne próbkowanie zmniejsza koszt oceny przy zachowaniu różnorodności śledzenia — zapewniając, że przypadki brzegowe, ścieżki błędów i różne wzorce konwersacji są uwzględniane w ocenianym zestawie.

Jak działa inteligentne próbkowanie

Algorytm próbkowania wykorzystuje podejście doboru pod względem różnorodności typu farthest-first z użyciem MinHash, które przebiega wieloetapowo:

  1. Dokładna deduplikacja — usuwa z puli zduplikowane ślady.
  2. Filtry twarde — usuwa przerwane sesje, obcięte ślady i nieprawidłowo sformułowane wywołania narzędzi, które nie są odpowiednie do oceny.
  3. Agregacja — łączy sygnały na poziomie śledzenia w ujednoliconą reprezentację.
  4. Selekcja MinHash metodą „farthest-first” — oblicza hasze uwzględniające lokalność (sygnatury MinHash) dla tekstu użytkownika, aby oszacować podobieństwo między śladami, a następnie iteracyjnie wybiera z pozostałej puli najmniej podobny ślad. Każdy kolejny wybór maksymalizuje odległość od wszystkich poprzednio wybranych śladów.

Takie podejście daje znacznie wyższą różnorodność leksykalną i szerszy zakres słownictwa w porównaniu z próbkowaniem losowym, co oznacza, że oceniony zestaw lepiej reprezentuje pełny zakres interakcji z agentem - w tym rzadkich, twardych i nowatorskich przypadków, które próbkowanie losowe ma tendencję do pomijania.

Inteligentne próbkowanie jest szczególnie skuteczne w następujących celach:

  • Oceny i testy porównawcze — maksymalizuje pokrycie rozkładu danych wejściowych, aby wyniki oceny odzwierciedlały różnorodność w świecie rzeczywistym.
  • Generowanie rubryk — tworzy bardziej skoncentrowane i umożliwiające podejmowanie działań rubryk, ujawniając zróżnicowane wzorce konwersacji.
  • Selekcja zbioru danych do dostrajania — wybiera przebiegi, które pomagają modelom uczyć się efektywniej.

Algorytm działa w całości na obliczeniach lokalnych bez dodatkowych wywołań interfejsu API, więc nie wiąże się z dodatkowymi kosztami wnioskowania modelu poza samą oceną.

Przykład inteligentnego próbkowania

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# 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 - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Wymagania dotyczące danych śledzenia

Ocena śledzenia wymaga od agenta emitowania zakresów, które są zgodne z konwencjami semantycznymi OpenTelemetry na potrzeby generowania sztucznej inteligencji. W szczególności usługa ewaluacji odczytuje zakresyinvoke_agent z usługi Application Insights i wyodrębnia dane dotyczące konwersacji z ich atrybutów.

Używane są następujące atrybuty zakresu:

Atrybut Wymagany Opis
gen_ai.operation.name Yes Musi być równe "invoke_agent". Usługa ignoruje wszystkie pozostałe zakresy.
gen_ai.agent.id Dla trybu filtrowania agenta Unikatowy identyfikator agenta (format: agent-name:version).
gen_ai.agent.name Dla trybu filtrowania agenta Nazwa agenta zrozumiała dla człowieka.
gen_ai.input.messages Dla danych wejściowych zapytań oceniających Tablica JSON komunikatów wejściowych zgodnie z formatem komunikatów semantycznych GenAI. Komunikaty z rolą user lub system są mapowane na query. Komunikaty z rolą assistant lub tool są mapowane na response.
gen_ai.output.messages Dla danych wejściowych zapytań oceniających Tablica JSON komunikatów wyjściowych wygenerowanych przez model. Wszystkie komunikaty wyjściowe są mapowane na response. Jeśli dane wyjściowe zawierają również type: tool_call lub type: tool_result, są mapowane na tool_calls.
gen_ai.tool.definitions Opcjonalnie Tablica JSON schematów narzędzi dostępnych dla agenta. Jeśli ich brak, usługa próbuje wywnioskować definicje narzędzi z komunikatów o wywołaniu narzędzia, ale wywnioskowane schematy mogą być niekompletne.
gen_ai.conversation.id Opcjonalnie Identyfikator konwersacji przekazywany do wyników oceny w celu korelacji.

Note

Jeśli gen_ai.input.messages i gen_ai.output.messages są puste lub brakujące, ewaluatory jakości (spójność, płynność, istotność, rozdzielczość intencji) zwracają wartość score=None. Ewaluatorzy bezpieczeństwa (przemoc, samookaleczenia, seksualna, nienawiść/niesprawiedliwość) mogą nadal generować wyniki z częściowymi danymi, ale mogą nie przynieść znaczących wyników.

W przypadku agentów Python tworzonych za pomocą zestawu SDK Azure AI Agent Server, dodaj dodatek [tracing], aby włączyć automatyczną emisję zakresów.

pip install "azure-ai-agentserver-core[tracing]"

Wymagania wstępne dotyczące analizy śladów

Oprócz ogólnych wymagań wstępnych ocena śladów wymaga:

pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Ustaw następujące zmienne środowiskowe:

  • APPINSIGHTS_RESOURCE_ID — identyfikator zasobu usługi Application Insights (na przykład /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — identyfikator agenta emitowany przez integrację śledzenia (gen_ai.agent.id atrybut), używany do filtrowania śladów. Format: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Opcjonalnie) Liczba godzin, wstecz do uwzględnienia przy zapytaniach o ślady. Wartość domyślna to 1.

Opcja A: Ocena według filtru agenta

Najprostszym podejściem jest umożliwianie usłudze automatycznego odnajdywania i oceniania ostatnich śladów dla określonego agenta. Nie musisz ręcznie zbierać identyfikatorów śladów.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Usługa filtruje zakresy invoke_agent według atrybutu gen_ai.agent.id, wybiera próbki do max_traces unikatowych identyfikatorów śledzenia i ocenia wszystkie zakresy z tych śladów.

Opcja B: ocena według identyfikatorów śledzenia

Aby uzyskać większą kontrolę, zbierz określone identyfikatory śledzenia z usługi Application Insights i oceń je. Ta metoda jest przydatna, gdy chcesz ocenić wybrany zestaw interakcji, na przykład ślady oznaczone przez alerty lub wybrane w ramach próbkowania do kontroli jakości.

Zbieranie identyfikatorów śladów z usługi Application Insights

Przeprowadzanie zapytań w usłudze Application Insights w celu uzyskania operation_Id wartości ze śladów agenta. Każdy operation_Id reprezentuje pełną interakcję agenta:

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Tworzenie oceny i uruchamianie przy użyciu identyfikatorów śledzenia

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Konfigurowanie ewaluatorów i mapowań danych

Podczas oceniania śladów usługa automatycznie wyodrębnia dane konwersacji z atrybutów zakresu OpenTelemetry. Użyj tych nazw pól bezpośrednio w data_mapping (bez prefiksów item. lub sample. używanych w innych scenariuszach).

Zmienna Atrybut źródłowy Opis
{{item.query}} gen_ai.input.messages (role użytkownika/systemu) Zapytanie użytkownika wyodrębnione ze śledzenia.
{{item.response}} gen_ai.input.messages (role asystenta/narzędzia) + gen_ai.output.messages Odpowiedź agenta wyodrębniona z rekordu śledzenia.
{{item.tool_definitions}} gen_ai.tool.definitions Schematy narzędzi dostępne dla agenta. Wymagane tylko dla ewaluatorów związanych z narzędziami.
{{item.tool_calls}} Wyodrębnione z komunikatów asystenta w programie gen_ai.input.messages / gen_ai.output.messages Wywołania narzędzi wykonywane przez agenta podczas interakcji. Używane przez ewaluatorów narzędzi. Wymagane tylko dla ewaluatorów związanych z narzędziami. 
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="intent_resolution",
        evaluator_name="builtin.intent_resolution",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
    # Tool evaluators — assess tool usage quality
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="tool_call_accuracy",
        evaluator_name="builtin.tool_call_accuracy",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
]

Następne kroki

  • Last updated on