Udostępnij za pośrednictwem

Uruchamianie ocen w chmurze 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 Wygólne warunki użytkowania Microsoft Azure Previews.

Z tego artykułu dowiesz się, jak uruchamiać oceny w chmurze (wersja zapoznawcza) na potrzeby testowania wstępnego wdrożenia na testowym zestawie danych.

Korzystaj z ocen chmury w przypadku większości scenariuszy — szczególnie w przypadku testowania na dużą skalę, integrowania ocen z potokami ciągłej integracji i ciągłego dostarczania (CI/CD) lub przeprowadzania testów wstępnych. Uruchamianie ocen w chmurze eliminuje konieczność zarządzania lokalną infrastrukturą obliczeniową i obsługuje przepływy pracy testowania automatycznego na dużą skalę. Możesz również zaplanować uruchamianie ocen cyklicznie lub skonfigurować ciągłą ocenę w celu automatycznego oceniania przykładowych odpowiedzi agenta w środowisku produkcyjnym.

Wyniki oceny chmury są przechowywane w projekcie Foundry. Możesz przejrzeć wyniki w portalu, pobrać je za pośrednictwem zestawu SDK lub kierować je do usługi Application Insights, jeśli nawiązano połączenie. Ocena chmury obsługuje wszystkie wyselekcjonowane przez Microsoft wbudowane ewaluatory i twoje własne ewaluatory. Ewaluatorzy są zarządzani w katalogu ewaluatorów przy użyciu tej samej kontroli dostępu opartej na rolach w zakresie projektu.

Wskazówka

Aby uzyskać kompletne przykłady do uruchomienia, zobacz przykłady oceny SDK dla języka Python na GitHubie.

Gdy używasz Foundry SDK, rejestruje wyniki oceny w projekcie Foundry dla lepszej obserwowalności. Ta funkcja obsługuje wszystkie wyselekcjonowane przez Microsoft wbudowani ewaluatorzy. i własnych spersonalizowanych ewaluatorów. Twoi ewaluatorzy mogą znajdować się w bibliotece ewaluatorów i mają takie same, projektowe zasady dostępu oparte na rolach.

Jak działa ocena chmury

Aby uruchomić ocenę w chmurze, należy utworzyć definicję oceny przy użyciu schematu danych i kryteriów testowania (ewaluatorów), a następnie utworzyć przebieg oceny. Przebieg wykonuje każdego z ewaluatorów względem twoich danych i zwraca ocenione wyniki, które możesz sprawdzać, czy ukończone.

Ocena chmury obsługuje następujące scenariusze:

Scenariusz Kiedy należy używać Typ źródła danych Target
Ocena zestawu danych Oceń wstępnie obliczone odpowiedzi w pliku JSONL. jsonl —
Ocena zestawu danych CSV Oceń wstępnie obliczone odpowiedzi w pliku CSV. csv —
Ocena docelowa modelu Podaj zapytania i generuj odpowiedzi na podstawie modelu podczas działania, na potrzeby oceny. azure_ai_target_completions azure_ai_model
Ocena celów agenta Zadaj pytania i generuj odpowiedzi od agenta Foundry podczas działania na potrzeby oceny. azure_ai_target_completions azure_ai_agent
Ocena odpowiedzi agenta Pobierz i oceń odpowiedzi agenta usługi Foundry według identyfikatorów odpowiedzi. azure_ai_responses —
Ocena śledzenia Oceń interakcje agentów, które zostały już przechwycone w usłudze Application Insights za pomocą identyfikatora śledzenia. azure_ai_traces —
Syntetyczna ocena danych (wersja zapoznawcza) Generuj syntetyczne zapytania testowe, wysyłaj je do modelu lub agenta i oceniaj odpowiedzi. azure_ai_synthetic_data_gen_preview azure_ai_model lub azure_ai_agent
Ocena zespołu czerwonego Uruchom zautomatyzowane testowanie adwersarialne dla modelu lub agenta. azure_ai_red_team azure_ai_model lub azure_ai_agent

Większość scenariuszy wymaga danych wejściowych. Dane można udostępniać na dwa sposoby:

Typ źródła Opis
file_id Powołaj się na przekazany zestaw danych, używając jego identyfikatora.
file_content Podaj dane bezpośrednio w treści żądania.

Każda ocena wymaga data_source_config, który wskazuje usłudze, jakich pól oczekiwać w danych.

  • custom — Definiujesz element item_schema z nazwami pól i typami. Ustaw include_sample_schema na true podczas korzystania z elementu docelowego, aby ewaluatorzy mogli odwoływać się do wygenerowanych odpowiedzi.
  • azure_ai_source — schemat jest wnioskowany z usługi. Ustaw "scenario" na "responses" dla oceny odpowiedzi agenta, "traces" dla oceny śledzenia, "synthetic_data_gen_preview" dla oceny danych syntetycznych (wersja zapoznawcza) lub "red_team" dla red teamingu.

Każdy scenariusz wymaga ewaluatorów, które definiują kryteria testowania. Aby uzyskać wskazówki dotyczące wybierania ewaluatorów, zobacz wbudowane ewaluatory.

Wymagania wstępne

  • Projekt Foundry.
  • Wdrożenie OpenAI na platformie Azure z modelem GPT obsługującym ukończenie czatu (na przykład gpt-5-mini).
  • Rola Azure AI User w projekcie Foundry.
  • Opcjonalnie możesz użyć własnego konta magazynu do przeprowadzania ocen.

Uwaga / Notatka

Niektóre funkcje oceny mają ograniczenia regionalne. Aby uzyskać szczegółowe informacje, zobacz obsługiwane regiony .

Wprowadzenie

Zainstaluj zestaw SDK i skonfiguruj klienta:

pip install "azure-ai-projects>=2.0.0"

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Przygotowywanie danych wejściowych

Większość scenariuszy oceny wymaga danych wejściowych. Dane można udostępniać na dwa sposoby:

Przekaż plik JSONL lub CSV, aby utworzyć wersjonowany zestaw danych w projekcie Foundry. Zestawy danych obsługują wersjonowanie i ponowne użycie w wielu iteracjach oceny. Użyj tego podejścia do testowania w środowisku produkcyjnym i procesów CI/CD.

Przygotuj plik JSONL z jednym obiektem JSON na wiersz zawierający pola, których potrzebują ewaluatorzy:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

Możesz też przygotować plik CSV z nagłówkami kolumn pasującymi do pól ewaluatora:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Podawanie danych w linii

Aby szybko eksperymentować z małymi zestawami testów, podaj dane bezpośrednio w żądaniu oceny przy użyciu polecenia file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Przekaż source jako pole "source" w konfiguracji źródła danych przy tworzeniu przebiegu. Domyślnie używane są sekcje scenariusza oznaczone jako file_id.

Ocena zestawu danych

Oceń wstępnie obliczone odpowiedzi w pliku JSONL przy użyciu jsonl typu źródła danych. Ten scenariusz jest przydatny, gdy masz już dane wyjściowe modelu i chcesz ocenić ich jakość.

Wskazówka

Przed rozpoczęciem ukończ kroki rozpoczynania pracy i przygotowywania danych wejściowych.

Definiowanie schematu danych i ewaluatorów

Określ schemat zgodny z polami JSONL i wybierz ewaluatorów (kryteria testowania), które mają zostać uruchomione. Użyj parametru data_mapping , aby połączyć pola z danych wejściowych z parametrami ewaluatora ze składnią {{item.field}} . Zawsze dołączaj data_mapping do wymaganych pól wejściowych dla każdego ewaluatora. Nazwy pól muszą być zgodne z tymi w pliku JSONL — na przykład jeśli Twoje dane mają "question" zamiast "query", użyj "{{item.question}}" w mapowaniu. Aby zapoznać się z wymaganymi parametrami dla każdego ewaluatora, zobacz sekcję wbudowane ewaluatory.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

Utwórz ocenę i uruchom

Utwórz ocenę, a następnie rozpocznij proces względem przekazanego zestawu danych. Przebieg wykonuje każdego ewaluatora w każdym wierszu w zestawie danych.

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

Aby uzyskać pełny przykład z możliwością uruchamiania, zobacz sample_evaluations_builtin_with_dataset_id.py w GitHub. Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Ocena zestawu danych CSV

Oceń wstępnie obliczone odpowiedzi w pliku CSV przy użyciu csv typu źródła danych. Ten scenariusz działa tak samo jak ocena zestawu danych , ale akceptuje pliki CSV zamiast JSONL. Użyj pliku CSV, gdy dane są już w formacie arkusza kalkulacyjnego lub tabelarycznego.

Wskazówka

Przed rozpoczęciem ukończ kroki rozpoczynania pracy i przygotowywania danych wejściowych.

Przygotowywanie pliku CSV

Utwórz plik CSV z nagłówkami kolumn odpowiadającymi polam, których potrzebują ewaluatorzy. Każdy wiersz reprezentuje jeden przypadek testowy:

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Prześlij i uruchom

Przekaż plik CSV jako zestaw danych, a następnie utwórz ocenę przy użyciu csv typu źródła danych. Definicja schematu i konfiguracja narzędzia oceny są takie same jak w przypadku ocen JSONL — jedyna różnica dotyczy źródła danych "type": "csv".

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Ocena docelowa modelu

Wysyłaj zapytania do wdrożonego modelu w czasie wykonywania i oceniaj odpowiedzi przy użyciu azure_ai_target_completions typu źródła danych z obiektem azure_ai_model docelowym. Dane wejściowe zawierają zapytania; model generuje odpowiedzi, które następnie są oceniane.

Wskazówka

Przed rozpoczęciem ukończ kroki rozpoczynania pracy i przygotowywania danych wejściowych.

Definiowanie szablonu wiadomości i elementu docelowego

Szablon input_messages określa sposób wysyłania zapytań do modelu. Użyj {{item.query}}, aby odwołać się do pól z danych wejściowych. Określ model do oceny i opcjonalnych parametrów próbkowania:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Konfigurowanie ewaluatorów i mapowań danych

Gdy model generuje odpowiedzi w czasie wykonywania, użyj {{sample.output_text}} w data_mapping do odwoływania się do danych wyjściowych modelu. Użyj {{item.field}}, aby odwołać się do pól z danych wejściowych.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Utwórz ocenę i uruchom

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Pełny przykład z możliwością uruchamiania można znaleźć w GitHub sample_model_evaluation.py. Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Wskazówka

Aby dodać kolejny przebieg oceny, możesz użyć tego samego kodu.

Ocena celów agenta

Wysyłaj zapytania do agenta Foundry w czasie wykonywania i oceniaj odpowiedzi, korzystając z typu źródła danych azure_ai_target_completions oraz docelowego obiektu azure_ai_agent.

Wskazówka

Przed rozpoczęciem ukończ kroki rozpoczynania pracy i przygotowywania danych wejściowych.

Definiowanie szablonu wiadomości i elementu docelowego

Szablon input_messages określa sposób wysyłania zapytań do agenta. Użyj {{item.query}}, aby odwołać się do pól z danych wejściowych. Określ agenta do oceny według nazwy:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Konfigurowanie ewaluatorów i mapowań danych

Gdy agent generuje odpowiedzi w czasie pracy, użyj {{sample.*}} zmiennych w data_mapping, aby odwołać się do wyników agenta.

Variable Opis Użyj dla
{{sample.output_text}} Odpowiedź agenta w postaci zwykłego tekstu. Moduły oceniające, które oczekują odpowiedzi w postaci ciągu znaków (na przykład coherence, violence).
{{sample.output_items}} Ustrukturyzowane dane wyjściowe JSON agenta, w tym wywołania narzędzi. Ewaluatorzy, którzy potrzebują pełnego kontekstu interakcji (na przykład task_adherence).
{{item.field}} Pole z danych wejściowych. Pola wejściowe, takie jak query lub ground_truth.

Wskazówka

Pole query może zawierać ustrukturyzowany kod JSON, w tym komunikaty systemowe i historię konwersacji. Niektórzy ewaluatorzy agentów, na przykład task_adherence używają tego kontekstu do dokładniejszego oceniania. Aby uzyskać szczegółowe informacje na temat formatowania zapytań, zobacz ewaluatory agentów.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Utwórz ocenę i uruchom

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Pełny przykład z możliwością uruchamiania można znaleźć w GitHub sample_agent_evaluation.py. Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Ocena odpowiedzi agenta

Pobieranie i ocenianie odpowiedzi agenta usługi Foundry według identyfikatorów odpowiedzi z wykorzystaniem azure_ai_responses typu źródła danych. Użyj tego scenariusza, aby ocenić konkretne interakcje agentów po ich wystąpieniu.

Wskazówka

Zanim zaczniesz, ukończ Get started.

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 wbudowane identyfikatory jako zawartość pliku lub przekaż je jako zestaw danych (zobacz Przygotowywanie danych wejściowych).

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 = 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ć z interakcji agenta w logach śledzenia aplikacji lub procesie monitorowania. Każdy identyfikator odpowiedzi jednoznacznie identyfikuje przechowywaną odpowiedź, którą może pobrać usługa oceny.

Utwórz ocenę i uruchom

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = 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 = 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 sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Analiza śledzenia

Oceń interakcje agentów, które zostały już przechwycone w usłudze Application Insights. Użyj typu źródła danych azure_ai_traces. Ten scenariusz jest przydatny do oceny rzeczywistego ruchu produkcyjnego po wdrożeniu — wybierasz ślady diagnostyczne z przepływu monitorowania i uruchamiasz na nich analizatory bez ponownego wykonywania żądań.

Ocena śledzenia obsługuje dwa tryby:

  • Według identyfikatorów śledzenia — ocenianie określonych interakcji agenta poprzez podanie ich operation_Id wartości z usługi Application Insights.
  • Według filtru agenta — automatycznie odnajdywanie i ocenianie ostatnich śladów dla danego agenta bez ręcznego zbierania identyfikatorów śledzenia.

Wskazówka

Zanim zaczniesz, ukończ Get started. Ten scenariusz wymaga również zasobu usługi Application Insights połączonego z projektem Foundry.

Wymagania dotyczące danych śledzenia

Ocena śledzenia wymaga, aby agent emitował zakresy zgodnie z semantycznymi konwencjami OpenTelemetry dla generatywnej sztucznej inteligencji. W szczególności usługa ewaluacji odczytuje segmentyinvoke_agent z usługi Application Insights i wyodrębnia dane konwersacyjne z ich atrybutów.

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

Atrybut Wymagane 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 odwzorowują się na query; komunikaty z rolą assistant lub tool odwzorowują się na response.
gen_ai.output.messages W przypadku danych wejściowych zapytań ewaluatorów 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ż typ: tool_call lub typ: tool_result, mapuje na tool_calls
gen_ai.tool.definitions Opcjonalna Tablica JSON schematów narzędzi dostępnych dla agenta. Jeśli jest nieobecny, usługa próbuje wywnioskować definicje narzędzi z komunikatów wywołań, ale wnioskowane schematy mogą być niekompletne.
gen_ai.conversation.id Opcjonalna Identyfikator konwersacji przekazany do wyników oceny dla korelacji.

Uwaga / Notatka

Jeśli gen_ai.input.messages i gen_ai.output.messages są puste lub nieobecne, ewaluatory jakości (spójność, płynność, istotność, rozdzielczość intencji) zwrócą 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 oceny śledzenia

Oprócz ogólnych wymagań wstępnych ocena analizy śladu wymaga:

  • Zasób usługi Application Insights połączony z projektem Foundry. Zobacz Konfigurowanie śledzenia w Microsoft Foundry.
  • Tożsamość zarządzana projektu musi mieć rolę Log Analytics Reader zarówno w zasobie usługi Application Insights, jak i w połączonym obszarze roboczym Log Analytics.
  • Pakiet azure-monitor-query Python (potrzebny tylko wtedy, gdy ręcznie zbierasz identyfikatory śledzenia).
pip install "azure-ai-projects>=2.0.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, przez które należy zwrócić uwagę podczas wykonywania zapytań dotyczących śladów. Wartość domyślna to 1.

Opcja A: Ocena według filtru agenta

Najprostsze podejście — umożliwia usłudze automatyczne odnajdywanie i ocenianie ostatnich śladów dla określonego agenta. Nie jest wymagane ręczne zbieranie identyfikatorów śledzenia.

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 = 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 = 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. Jest to przydatne, gdy chcesz ocenić wyselekcjonowany zestaw interakcji (na przykład ślady oznaczone przez ostrzeżenia lub wybrane na potrzeby przeglądu jakości).

Zbieranie identyfikatorów śledzenia 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 = 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 = 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 programie data_mapping (bez prefiksów item. lub sample. używanych w innych scenariuszach):

Variable 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 (asystent/role narzędzi) + 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 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "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": {
            "deployment_name": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "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": {
            "deployment_name": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Aby uzyskać pełny przykład gotowy do uruchomienia, zobacz sample_evaluations_builtin_with_traces.py na GitHubie. Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników.

Syntetyczna ocena danych (wersja zapoznawcza)

Generowanie syntetycznych zapytań testowych, wysyłanie ich do wdrożonego modelu lub agenta foundry oraz ocenianie odpowiedzi przy użyciu azure_ai_synthetic_data_gen_preview typu źródła danych. Użyj tego scenariusza, gdy nie masz zestawu danych testowych — usługa generuje zapytania na podstawie podanego monitu (i/lub z instrukcji agenta), uruchamia je względem celu i ocenia odpowiedzi.

Wskazówka

Zanim zaczniesz, ukończ Get started.

Jak działa syntetyczna ocena danych

  1. Usługa generuje syntetyczne zapytania na podstawie Twoich prompt i opcjonalnych plików danych początkowych.
  2. Każde zapytanie jest wysyłane do określonego elementu docelowego (modelu lub agenta), aby wygenerować odpowiedź.
  3. Ewaluatorzy oceniają każdą odpowiedź przy użyciu wygenerowanego zapytania i odpowiedzi.
  4. Wygenerowane zapytania są przechowywane jako zestaw danych w projekcie w celu ponownego użycia.

Parametry

Parameter Wymagane Opis
samples_count Tak Maksymalna liczba syntetycznych zapytań testowych do wygenerowania.
model_deployment_name Tak Wdrożenie modelu do użycia do generowania zapytań syntetycznych. Obsługiwane są tylko modele z funkcją interfejsu API odpowiedzi. Aby uzyskać informacje o dostępności, zobacz Dostępność regionów interfejsu API odpowiedzi.
prompt Nie. Instrukcje opisujące typ zapytań do wygenerowania. Opcjonalnie, gdy cel agenta ma skonfigurowane instrukcje.
output_dataset_name Nie. Nazwa wyjściowego zestawu danych, w którym są przechowywane wygenerowane zapytania. Jeśli nie zostanie podana, usługa automatycznie wygeneruje nazwę.
sources Nie. Inicjowanie plików danych (według identyfikatora pliku) w celu zwiększenia istotności wygenerowanych zapytań. Obecnie obsługiwany jest tylko jeden plik.

Konfigurowanie ewaluatorów i mapowań danych

Generator danych syntetycznych tworzy zapytania w {{item.query}} polu. Element docelowy generuje odpowiedzi dostępne w pliku {{sample.output_text}}. Zamapuj te pola na ewaluatorów:

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Utwórz ocenę i uruchom

Cel modelu

Generuj zapytania syntetyczne i oceniaj model:

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Opcjonalnie można dodać monit systemowy, aby wpłynąć na zachowanie modelu docelowego. W przypadku używania input_messages z syntetycznym generowaniem danych włączaj tylko komunikaty roli system — usługa automatycznie udostępnia wygenerowane zapytania jako komunikaty użytkownika.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

Element docelowy agenta

Generowanie zapytań syntetycznych i ocena agenta Foundry:

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

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

Aby sondować pod kątem ukończenia i interpretowania wyników, zobacz Pobieranie wyników. Odpowiedź zawiera właściwość zawierającą output_dataset_id identyfikator wygenerowanego zestawu danych, którego można użyć do pobrania lub ponownego użycia danych syntetycznych.

Pobieranie wyników

Po zakończeniu przebiegu oceny pobierz wyniki oceny i przejrzyj je w portalu lub programowo.

Sonduj wyniki

Przebiegi oceny są asynchroniczne. Sonduj stan przebiegu, dopóki nie zostanie ukończony, a następnie pobierz wyniki:

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Interpretowanie wyników

W przypadku pojedynczego przykładu danych wszyscy oceniający generują następujący schemat:

  • Etykieta: binarna etykieta "pass" lub "fail", podobna do danych wyjściowych testu jednostkowego. Użyj tego wyniku, aby ułatwić porównania między ewaluatorami.
  • Wynik: wynik z naturalnej skali każdego ewaluatora. Niektórzy ewaluatorzy używają szczegółowej rubryki, oceniają na 5-punktowej skali (ewaluatorzy jakości) lub 7-punktowej skali (ewaluatorzy bezpieczeństwa treści). Inne, takie jak ewaluatory podobieństw tekstowych, używają wyników F1, które są liczbami zmiennoprzecinkowymi w zakresie od 0 do 1. Każdy niebinarny "wynik" jest binarizowany na wartość "pass" lub "fail" w polu "label" na podstawie wartości "threshold".
  • Próg: wszystkie wyniki inne niż binarne są przekształcane w binarne do "zdania" lub "niezdania" na podstawie domyślnego progu, który użytkownik może zastąpić w interfejsie SDK.
  • Powód: Aby zwiększyć zrozumiałość, wszyscy ewaluatorzy LLM-judge również wyświetlają pole rozumowania, aby wyjaśnić, dlaczego dany wynik jest podany.
  • Szczegóły: (opcjonalnie) W przypadku niektórych ewaluatorów, takich jak tool_call_accuracy, może istnieć pole lub flagi zawierające dodatkowe informacje ułatwiające użytkownikom debugowanie aplikacji.

Przykładowe dane wyjściowe (pojedynczy element)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Przykładowe dane wyjściowe (agregacja)

W przypadku agregowania wyników z wielu przykładów (zestawu danych), średni współczynnik przykładów z "zdaniem" stanowi współczynnik zdawalności dla tego zestawu danych.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Rozwiązywanie problemów

Zadanie działa od dłuższego czasu

Zadanie oceny może pozostać w stanie Uruchomiony przez dłuższy czas. Dzieje się tak zwykle, gdy wdrożenie modelu Azure OpenAI nie ma wystarczającej pojemności, co powoduje ponawianie żądań przez usługę.

Rozwiązanie:

  1. Anuluj bieżące zadanie oceny przy użyciu polecenia client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Zwiększ pojemność modelu w portalu Azure.
  3. Uruchom ponownie ocenę.

Błędy uwierzytelniania

Jeśli otrzymasz błąd 401 Unauthorized lub 403 Forbidden, sprawdź, czy:

  • DefaultAzureCredential jest poprawnie skonfigurowany (uruchom az login, jeśli używasz Azure CLI).
  • Twoje konto ma rolę użytkownika Azure AI w projekcie Foundry.
  • Adres URL punktu końcowego projektu jest poprawny i zawiera zarówno nazwy konta, jak i projektu.

Błędy formatu danych

Jeśli ocena zakończy się niepowodzeniem z powodu błędu schematu lub mapowania danych:

  • Sprawdź, czy plik JSONL ma jeden prawidłowy obiekt JSON na wiersz.
  • Upewnij się, że nazwy pól w data_mapping dokładnie odpowiadają nazwom pól w pliku JSONL (z uwzględnieniem wielkości liter).
  • Sprawdź, czy item_schema właściwości są zgodne z polami w zestawie danych.

Błędy limitu szybkości

Tworzenie przebiegów oceny jest limitowane na poziomie dzierżawy, subskrypcji i projektu. Jeśli otrzymasz 429 Too Many Requests odpowiedź:

  • retry-after Sprawdź nagłówek w odpowiedzi pod kątem zalecanego czasu oczekiwania.
  • Przejrzyj treść odpowiedzi, aby uzyskać szczegóły limitu szybkości.
  • Podczas ponawiania żądań, które zakończyły się niepowodzeniem, należy użyć wycofywania wykładniczego.

Jeśli zadanie oceny zakończy się niepowodzeniem z powodu błędu 429 podczas wykonywania:

  • Zmniejsz rozmiar zestawu danych oceny lub podziel go na mniejsze partie.
  • Zwiększ limit przydziału tokenów na minutę (TPM) dla wdrożenia modelu w portalu Azure.

Błędy narzędzia ewaluatora agenta

Jeśli agent ewaluatora zwraca błąd dla nieobsługiwanych narzędzi:

  • Sprawdź obsługiwane narzędzia dla oceniających agentów.
  • Aby obejść ten problem, opakuj nieobsługiwane narzędzia jako narzędzia funkcji zdefiniowane przez użytkownika, aby ewaluator mógł je ocenić.

Treści powiązane

  • Last updated on