Spouštění vyhodnocení v cloudu pomocí sady Microsoft Foundry SDK

V tomto článku se dozvíte, jak spustit vyhodnocení v cloudu pro testování předem připravených testovacích datových sad.

Pro většinu scénářů používejte vyhodnocení cloudu – zejména při testování ve velkém měřítku, integraci vyhodnocení do kanálů kontinuální integrace a průběžného doručování (CI/CD) nebo provádění předběžného testování. Spouštění vyhodnocení v cloudu eliminuje nutnost spravovat místní výpočetní infrastrukturu a podporuje rozsáhlé automatizované testovací pracovní postupy. Můžete také naplánovat, aby se hodnocení spouštěla opakovaně, nebo můžete nastavit průběžné hodnocení , aby se automaticky vyhodnocovaly vzorkované odpovědi agenta v produkčním prostředí.

Výsledky vyhodnocení cloudu se ukládají do projektu Foundry. Výsledky můžete zkontrolovat na portálu, načíst je prostřednictvím sady SDK nebo je směrovat do Application Insights, pokud jsou připojené. Cloudové hodnocení podporuje všechny Microsoftem kurátorované vestavěné hodnotitele a vaše vlastní vlastní hodnotitele. Vyhodnocovače se spravují v katalogu vyhodnocovačů se stejným řízením přístupu na základě role v oboru projektu.

Tip

Kompletní spustitelné příklady najdete v ukázkách Python SDK pro vyhodnocení na GitHub.

Jak funguje vyhodnocení cloudu

Vyhodnocení cloudu má tři kroky:

  1. Definujte, co se má vyhodnotit. Popište svou datovou strukturu ( data_source_config) a hodnotitele (kritéria testování), kteří ji hodnotí.
  2. Vytvořte vyhodnocení. Odešlete definici pomocí .openai_client.evals.create()
  3. Spusťte ho a přečtěte si výsledky. Spusťte běh pomocí openai_client.evals.runs.create(), opakovaně zjišťujte jeho stav, dokud se nedokončí, a přečtěte si ohodnocené výsledky. Viz Získání výsledků pro schéma výsledků.

Zbývající část této části vás provede vstupy ke kroku 1: vyberte scénář a pak zvolte vyhodnocovače.

Výběr výchozího bodu

Existující datová sada

Tuto možnost použijte, pokud už máte dotazy a odpovědi uložené v souboru (nebo dotazy plus ground truth) a chcete jen, aby je Foundry vyhodnotil. JSONL podporuje jak řádky na úrovni jednotlivých tahů, tak vstupy na úrovni celé konverzace; CSV podporuje pouze úroveň jednotlivých tahů.

Scénář Kdy použít Typ zdroje dat
Vyhodnocení datové sady na úrovni jednotlivých tahů Každý řádek tvoří jednu dvojici query/response, případně s context nebo ground_truth. jsonl Nebo csv
Vyhodnocení datové sady na úrovni konverzace (Preview) Každý řádek je konverzace vyjádřená messages jako pole. jsonl

Data v Foundry nebo Application Insights

Tuto cestu použijte, když už je agent spuštěný a chcete vyhodnotit, co se skutečně stalo. Místo přesunu dat nasměrujete Foundry na data, která už existují – podle ID odpovědi Foundry nebo pomocí trasování Application Insights nebo ID konverzace.

Scénář Kdy použít Typ zdroje dat
Vyhodnocení odpovědi agenta Váš agent běží ve Foundry a máte k dispozici ID odpovědí k vyhodnocení. azure_ai_responses
Vyhodnocení trasování na úrovni jednotlivých tahů (verze Preview) Váš agent odesílá trasování OpenTelemetry do Application Insights, včetně frameworků mimo Foundry, jako je LangChain, nebo vlastních agentů instrumentovaných pomocí OpenTelemetry. Každá stopa je hodnocena nezávisle. azure_ai_trace_data_source_preview
Vyhodnocení trasování na úrovni konverzace (náhled) Stejné zdroje trasování, ale skóre úplných konverzací – podle ID konverzace nebo podle filtru agenta s vzorkováním azure_ai_trace_data_source_preview

Vstupy bez odpovědí

Tuto cestu použijte, pokud máte vstupy, ale zatím žádné odpovědi. Foundry vygeneruje odpovědi na model nebo cíl agenta v době vyhodnocení a pak je vyhodnotí. Vyberte řádek podle toho, zda váš vstup tvoří dotazy (odesílané jako jednotlivé tahy) nebo popisy scénářů (používané pro řízení interakce na úrovni celé konverzace).

Scénář Kdy použít Zdroj dat / cíl
Dokončení cíle modelu Máte dotazy a chcete vyhodnotit odpovědi z nasazení modelu. azure_ai_target_completions → azure_ai_model
Dokončení cílů agenta Máte dotazy a chcete vyhodnotit odpovědi od agenta Foundry. azure_ai_target_completions → azure_ai_agent
Simulace konverzací (Preview) Máte popisy scénářů (žádné dotazy); Foundry simuluje uživatele, který řídí interakci na úrovni konverzace s agentem. azure_ai_target_completions → azure_ai_agent

Zatím žádná data

Tuto cestu použijte, když vytváříte nový model nebo agenta a neshromažďujete žádné vstupy. Foundry generuje testovací data úplně od začátku – zvolte syntetické dotazy pro široké pokrytí kvality nebo nežádoucí výzvy k testování bezpečnosti.

Scénář Kdy použít Zdroj dat / cíl
Vyhodnocení syntetických dat (Preview) Chcete mít kvalitní pokrytí nad rámec toho, co byste napsali ručně. Foundry generuje testovací dotazy, odesílá je do cíle a vyhodnotuje odpovědi. azure_ai_synthetic_data_gen_preview azure_ai_model→ neboazure_ai_agent
Vyhodnocení červeného týmu Chcete automatizované adverzariální testování – Foundry generuje jailbreaky a prompty se škodlivým obsahem a vyhodnocuje, jak cílový systém reaguje. azure_ai_red_team azure_ai_model→ neboazure_ai_agent

Výběr vyhodnocovačů

Každý scénář spojuje vyhodnocovače s poli v datech prostřednictvím mapování sloupců. Dostupná pole závisí na zdroji dat. Scénáře datových sad zpřístupňují pole vlastních položek, zatímco cílové vygenerované scénáře také zveřejňují odpověď modelu nebo agenta prostřednictvím ukázkového schématu. Pododdíly pro jednotlivé scénáře dále v tomto článku ukazují mapování sloupců pro každý případ.

Přehled dostupných vyhodnocovačů a informace o tom, jak je vybrat, najdete v článcích předdefinované vyhodnocovače a vlastní vyhodnocovače.

Požadavky

  • Projekt Foundry.

  • Nasazení OpenAI Azure s modelem GPT, který podporuje dokončování chatu (například gpt-5-mini).

  • Role uživatele Foundry v projektu Foundry.

    Důležité

    Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Foundry Account Owner a Foundry Project Manager se dříve nazývaly Uživatel Azure AI, Vlastník Azure AI, Vlastník účtu Azure AI a Správce projektů Azure AI. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.

  • Volitelně můžete ke spuštění vyhodnocení použít vlastní účet úložiště .

Poznámka

Některé funkce vyhodnocení mají regionální omezení. Podrobnosti najdete v podporovaných oblastech .

Začínáme

Nainstalujte sadu SDK a nastavte klienta:

pip install "azure-ai-projects>=2.2.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
openai_client = project_client.get_openai_client()

Příprava vstupních dat

Většina scénářů vyhodnocení vyžaduje vstupní data. Data můžete poskytnout dvěma způsoby:

Nahrajte soubor JSONL nebo CSV a vytvořte ve svém projektu Foundry datovou sadu s verzí. Datové sady podporují správu verzí a opakované použití napříč několika testovacími běhy. Tento přístup použijte pro produkční testování a pracovní postupy CI/CD.

Připravte soubor JSONL s jedním objektem JSON na řádek obsahující pole, která vaši vyhodnocovače potřebují:

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

Nebo připravte soubor CSV se záhlavími sloupců odpovídajícími polím vyhodnocovače:

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

Vložení dat do textu

Pro rychlé experimentování s malými testovacími sadami nebo pro scénáře, které vyžadují vložená data, jako je vyhodnocení odpovědi agenta, poskytují data přímo v žádosti o vyhodnocení pomocí file_content. Pro vyhodnocení odpovědí agenta file_content je jediným podporovaným typem zdroje.

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

Při vytváření procesu zadejte source jako pole "source" v konfiguraci zdroje dat. Oddíly scénáře, které následují, používají file_id jako výchozí nastavení.

Podpora typu zdroje podle scénáře

Ne všechny scénáře podporují oba typy zdrojů. Následující matice ukazuje, jaký typ zdroje každý scénář podporuje.

Scénář file_id file_content
Datová sada (jsonl) Ano Ano
CSV (csv) Ano Ano
Model nebo cíl agenta Ano Ano
Odpověď agenta (azure_ai_responses) Ne Ano
Trasování (azure_ai_traces) N/A N/A
Syntetická data (ve verzi Preview) N/A N/A

Vyhodnocení datové sady

Vyhodnoťte předem vypočítané odpovědi v souboru JSONL pomocí jsonl typu zdroje dat. Tento scénář je užitečný, pokud už máte výstupy modelu a chcete posoudit jejich kvalitu.

Tip

Než začnete, dokončete začínáme a připravte vstupní data.

Definování schématu dat a vyhodnocovačů

Zadejte schéma, které odpovídá vašim polím JSONL, a vyberte vyhodnocovače (testovací kritéria) ke spuštění. Pomocí parametru data_mapping připojte pole ze vstupních dat k vyhodnocovačovým parametrům pomocí {{item.field}} syntaxe. Vždy zahrňte data_mapping do požadovaných vstupních polí každého vyhodnocovače. Názvy polí se musí shodovat s názvy polí v souboru JSONL — například, pokud vaše data mají "question" místo "query", použijte v mapování "{{item.question}}". Požadované parametry na vyhodnocovače najdete v předdefinovaných vyhodnocovacích nástrojích.

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": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "model": 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}}",
        },
    },
]

Vytvořit vyhodnocení a spustit

Vytvořte vyhodnocení, a pak spusťte test nad vaší nahranou datovou sadou. Spuštění provede každý vyhodnocovací objekt na každém řádku datové sady.

# Create the evaluation
eval_object = openai_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 = openai_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,
        ),
    ),
)

Úplný příklad, jak ho spustit, najdete v souboru sample_evaluations_builtin_with_dataset_id.py na GitHubu. Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Vyhodnocení datové sady CSV

Pomocí typu zdroje dat vyhodnoťte předem vypočtené odpovědi v souboru csv CSV. Tento scénář funguje stejně jako vyhodnocení datové sady , ale přijímá soubory CSV místo JSONL. Použijte CSV, pokud jsou vaše data již v tabulkovém nebo tabulkovém formátu.

Tip

Než začnete, dokončete začínáme a připravte vstupní data.

Příprava souboru CSV

Vytvořte soubor CSV se záhlavími sloupců, které odpovídají polím, která vaše vyhodnocovače potřebují. Každý řádek představuje jeden testovací případ.

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.

Nahrání a spuštění

Nahrajte soubor CSV jako datovou sadu. Pak vytvořte vyhodnocení pomocí csv typu zdroje dat. Definice schématu a konfigurace vyhodnocovače jsou stejné jako pro vyhodnocení JSONL. Jediný rozdíl je v "type": "csv" ve zdroji dat.

# 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": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Vyhodnocení cíle modelu

Odesílání dotazů do nasazeného modelu za běhu Vyhodnoťte odpovědi pomocí azure_ai_target_completions typu zdroje dat s azure_ai_model cílem. Vstupní data obsahují dotazy. Model generuje odpovědi, které pak vyhodnotíte.

Tip

Než začnete, dokončete začínáme a připravte vstupní data.

Definování šablony zprávy a cíle

Šablona input_messages řídí způsob odesílání dotazů do modelu. Slouží {{item.query}} k odkazování na pole ze vstupních dat. Zadejte model pro vyhodnocení a volitelné parametry vzorkování:

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

Nastavení vyhodnocovačů a mapování dat

Když model generuje odpovědi během zpracování, použijte {{sample.output_text}} v data_mapping k odkazování na výstup modelu. Slouží {{item.field}} k odkazování na pole ze vstupních dat.

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": {
            "model": 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}}",
        },
    },
]

Vytvořit vyhodnocení a spustit

eval_object = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Úplný příklad s možností spuštění najdete v tématu sample_model_evaluation.py na GitHub. Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Tip

Pokud chcete přidat další zkušební spuštění, použijte stejný kód.

Vyhodnocení cíle agenta

Odešlete dotazy do agenta Foundry za běhu a vyhodnoťte odpovědi pomocí azure_ai_target_completions typu zdroje dat s azure_ai_agent cílem. Tento scénář funguje pro okamžité agenty i hostované agenty.

Tip

Než začnete, dokončete začínáme a připravte vstupní data.

Tip

Hostovaní agenti, kteří používají protokol odpovědí, pracují se stejnými vzorovými kódy, které jsou zde uvedené. U hostovaných agentů, kteří používají invokační protokol, je formát input_messages jiný. Podrobnosti najdete v protokolu vyvolání hostovaného agenta .

Definování šablony zprávy a cíle

Šablona input_messages určuje, jak se dotazy odesílají agentovi. Slouží {{item.query}} k odkazování na pole ze vstupních dat. Zadejte agenta, který se má vyhodnotit podle názvu:

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

Nastavení vyhodnocovačů a mapování dat

Když agent generuje odpovědi za běhu, použijte {{sample.*}} proměnné data_mapping k odkazování na výstup agenta:

Proměnné Popis Použít pro
{{sample.output_text}} Odpověď agenta ve formátu prostého textu. Vyhodnocovače, které očekávají řetězcovou odpověď (například coherence, violence).
{{sample.output_items}} Strukturovaný výstup JSON agenta, včetně volání nástrojů. Vyhodnocovače, kteří potřebují úplný kontext interakce (například task_adherence).
{{item.field}} Pole ze vstupních dat Vstupní pole jako query nebo ground_truth.

Tip

Pole query může obsahovat strukturovaný JSON, včetně systémových zpráv a historie konverzací. Někteří vyhodnocovači agentů, jako task_adherence, používají tento kontext pro přesnější hodnocení. Podrobnosti o formátování dotazů najdete v části vyhodnocovače agentů.

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": {
            "model": 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": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Vytvořit vyhodnocení a spustit

eval_object = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Úplný příklad s možností spuštění najdete v tématu sample_agent_evaluation.py na GitHub. Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Protokol volání hostovaného agenta

Hostovaní agenti , kteří používají protokol vyvolání, podporují stejný azure_ai_agent cílový typ, ale používají volný formát input_messages . Místo strukturovaného formátu šablony zadejte objekt JSON, který se mapuje přímo na text požadavku agenta /invocations . Zástupné {{item.*}} symboly slouží k nahrazení polí ze vstupních dat.

Pokud hostovaný agent podporuje protokoly odpovědí i volání, služba ve výchozím nastavení používá protokol vyvolání.

Definování formátu a cíle zprávy

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Vytvořit vyhodnocení a spustit

eval_object = openai_client.evals.create(
    name="Hosted Agent Invocations 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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

Nastavení vyhodnocovače a mapování dat jsou stejné jako při vyhodnocování agenta výzvy. Používá se {{sample.output_text}} pro textovou odpověď agenta a {{sample.output_items}} pro úplný strukturovaný výstup včetně volání nástrojů.

Vyhodnocení odpovědi agenta

Načtěte a vyhodnoťte odpovědi agenta Foundry podle ID odpovědí pomocí azure_ai_responses typu zdroje dat. Tento scénář použijte k vyhodnocení konkrétních interakcí agentů po jejich výskytu.

Tip

Než začnete, dokončete Začínáme.

ID odpovědi je jedinečný identifikátor vrácený pokaždé, když agent Foundry vygeneruje odpověď. ID odpovědí můžete shromažďovat z interakcí agentů pomocí rozhraní API odpovědí nebo z protokolů trasování vaší aplikace. Uveďte ID přímo jako obsah souboru.

Důležité

Vyhodnocení odpovědí agenta (azure_ai_responses) podporují pouze file_content pro poskytování ID odpovědí. Typ file_id zdroje není podporovaný a vrátí 400 Bad Request chybu.

Shromažďování ID odpovědí

Každé volání rozhraní API odpovědi vrátí objekt odpovědi s jedinečným id polem. Shromážděte tato ID z interakcí vaší aplikace nebo je vygenerujte přímo:

# 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

ID odpovědí můžete shromažďovat také z interakcí agentů v protokolech trasování vaší aplikace nebo v kanálu monitorování. Každé ID odpovědi jednoznačně identifikuje uloženou odpověď, kterou může služba vyhodnocení načíst.

Vytvořit vyhodnocení a spustit

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    {
        "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,
)

Úplný příklad spustitelného příkazu najdete v tématu sample_agent_response_evaluation.py na GitHub. Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Vyhodnocení trasování (Preview)

Vyhodnoťte interakce agenta, které služba Application Insights už zachytila. azure_ai_traces Použijte typ zdroje dat. Tento scénář je užitečný pro vyhodnocení skutečného produkčního provozu po nasazení. Vyberete stopy z monitorovací pipeline a spustíte na nich evaluátory, aniž byste museli znovu přehrávat jakékoli požadavky.

Důležité

Vyhodnocování trasování je doporučený přístup k hodnocení agentů, kteří nejsou vytvořeni pomocí služby Microsoft Foundry Agent Service – včetně frameworku LangChain a vlastních frameworků. Pokud váš agent odesílá do Application Insights trasovací úseky OpenTelemetry podle sémantických konvencí GenAI, vyhodnocování trasování může posoudit interakce agenta pomocí stejných vyhodnocovačů, které jsou k dispozici pro agenty Foundry.

Vyhodnocení trasování podporuje dva režimy:

  • Podle ID trasování – Vyhodnoťte konkrétní interakce agentů zadáním hodnot operation_Id z Application Insights.
  • Podle filtru agenta – Automatické zjišťování a vyhodnocení nedávných trasování pro daného agenta bez ručního shromažďování ID trasování

Tip

Než začnete, dokončete Začínáme. Tento scénář také vyžaduje prostředek Application Insights připojený k vašemu projektu Foundry.

Inteligentní vzorkování

Vyhodnocení trasování podporuje inteligentní vzorkování, které místo vyhodnocení každého zachyceného trasování vybere reprezentativní podmnožinu trasování. Povolte tuto funkci zapnutím přepínače Intelligent sampling na portálu Foundry při konfiguraci běhu vyhodnocení tras. Inteligentní vzorkování snižuje náklady na vyhodnocení a zároveň zachovává rozmanitost tras, čímž zajišťuje, že do vyhodnocované sady budou zahrnuty hraniční případy, chybové cesty a různé typy konverzací.

Jak inteligentní vzorkování funguje

Algoritmus pro výběr vzorků používá přístup MinHash k zajištění rozmanitosti typu farthest-first, který probíhá ve více fázích:

  1. Přesná deduplikace – Odebere duplicitní stopy z fondu.
  2. Pevné filtry – Odebere přerušené relace, zkrácené trasování a chybně formátovaná volání nástrojů, která nejsou vhodná pro vyhodnocení.
  3. Agregace – kombinuje signály na úrovni trasování do sjednocené reprezentace.
  4. Výběr metodou nejprve nejvzdálenějších pomocí MinHash – Vypočítá haše citlivé na lokalitu (signatury MinHash) z uživatelského textu pro odhad podobnosti mezi trasami a poté iterativně vybírá nejméně podobnou trasu ze zbývající množiny. Každý následný výběr maximalizuje vzdálenost od všech dříve vybraných tras.

Tento přístup vytváří výrazně vyšší lexikální rozmanitost a širší pokrytí slovníku v porovnání s náhodným vzorkováním, což znamená, že vyhodnocená sada lépe představuje celou škálu interakcí s agenty – včetně vzácných, tvrdých a nových případů, které náhodné vzorkování obvykle vynechává.

Inteligentní vzorkování je zvláště účinné pro:

  • Hodnocení a srovnávací testy – maximalizuje pokrytí vstupního rozdělení, takže hodnocení skóre odrážejí skutečnou rozmanitost.
  • Generování rubrik – vytváří lépe zaměřené a použitelné rubriky tím, že zpřístupňuje různorodé vzory konverzací.
  • Kurátorování datové sady pro jemné doladění - Vybírá záznamy, které modelům pomáhají učit se efektivněji.

Algoritmus běží zcela na místních výpočetních prostředcích bez dalších volání rozhraní API, takže neúčtují další náklady na odvozování modelu nad rámec samotného vyhodnocení.

Příklad inteligentního vzorkování

# 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
)

Požadavky na trasování dat

Vyhodnocení tras vyžaduje, aby váš agent generoval spany, které dodržují sémantické konvence OpenTelemetry pro generativní AI. Konkrétně hodnotící služba čte invoke_agent rozpětí z Application Insights a extrahuje z atributů data konverzací.

Používají se následující atributy span:

Atribut Požadované Popis
gen_ai.operation.name Ano Musí být rovno "invoke_agent". Služba ignoruje všechny ostatní úseky.
gen_ai.agent.id Pro režim filtru agenta Jedinečný identifikátor agenta (formát: agent-name:version).
gen_ai.agent.name Pro režim filtru agenta Název agenta srozumitelný pro lidi.
gen_ai.input.messages Vstupy dotazů pro vyhodnocovače Pole JSON vstupních zpráv podle formátu zpráv GenAI semantických konvencí. Zprávy s rolí user nebo system mapou na query; zprávy s rolí assistant nebo tool mapou na response.
gen_ai.output.messages Vstupy dotazů pro vyhodnocovače Pole JSON výstupních zpráv generovaných modelem Všechny výstupní zprávy se mapují na response. Pokud výstup obsahuje také type: tool_call nebo type: tool_result, odpovídá to tool_calls.
gen_ai.tool.definitions Volitelné Pole JSON schémat nástrojů dostupných agentům Pokud chybí, služba se pokusí odvodit definice nástrojů ze zpráv o volání nástrojů, ale odvozená schémata mohou být neúplná.
gen_ai.conversation.id Volitelné Identifikátor konverzace, předávaný do výsledků vyhodnocení pro účely korelace.

Poznámka

Pokud jsou gen_ai.input.messages a gen_ai.output.messages prázdné nebo chybí, hodnotitele kvality (soudržnost, plynulost, relevance, určení záměru) vrátí score=None. Vyhodnocení bezpečnosti (násilí, sebeškozování, sexuální, nenávist/nespravedlivost) mohou stále vytvářet skóre s částečnými daty, ale nemusí vést k smysluplným výsledkům.

Pro Python agenty vytvořené pomocí sady SDK Azure agenta AI přidejte [tracing] navíc, abyste umožnili automatické emise rozsahu:

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

Předpoklady pro vyhodnocení sledování

Kromě obecných požadavků vyžaduje vyhodnocení trasování:

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

Nastavte tyto proměnné prostředí:

  • APPINSIGHTS_RESOURCE_ID – ID prostředku Application Insights (například /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — Identifikátor agenta vygenerovaný integrací trasování (gen_ai.agent.id atribut), který se používá k filtrování trasování. Formát: agent-name:version.
  • TRACE_LOOKBACK_HOURS – (Volitelné) Počet hodin, o které se má při dotazování tras vrátit zpět. Výchozí je 1.

Možnost A: Vyhodnocení podle filtru agenta

Nejjednodušší přístup spočívá v tom, že necháte službu automaticky vyhledat a vyhodnotit nedávné trasy pro konkrétního agenta. Není potřeba žádná kolekce ID ručního trasování.

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

Služba filtruje invoke_agent úseky podle atributu gen_ai.agent.id, vzorkuje až na max_traces jedinečných ID trasování a vyhodnocuje všechny úseky z těchto trasování.

Možnost B: Vyhodnocení podle ID sledování

Pokud chcete mít větší kontrolu, shromážděte konkrétní ID trasování z Application Insights a vyhodnoťte je. Tato metoda je užitečná, když chcete vyhodnotit pečlivě vybranou sadu interakcí, například trasování označená výstrahami nebo vzorky vybrané ke kontrole kvality.

Shromáždit identifikátory tras z Application Insights

Vyhledávejte v Application Insights pro operation_Id hodnoty z trasování agenta. Každá operation_Id představuje úplnou interakci 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")

Vytvoření vyhodnocení a spuštění s využitím ID trasování

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

Nastavení vyhodnocovačů a mapování dat

Při vyhodnocování trasování služba automaticky extrahuje data konverzace z atributů OpenTelemetry span. Tyto názvy polí použijte přímo v data_mapping (bez předpon item. ani sample. použitých v jiných scénářích):

Proměnné Zdrojový atribut Popis
{{item.query}} gen_ai.input.messages (role uživatele/systému) Dotaz uživatele extrahovaný z trasování.
{{item.response}} gen_ai.input.messages (asistent/role nástrojů) + gen_ai.output.messages Odpověď agenta extrahovaná ze záznamu.
{{item.tool_definitions}} gen_ai.tool.definitions Schémata nástrojů dostupná pro agenta. Vyžaduje se pouze pro evaluátory související s nástroji.
{{item.tool_calls}} Extrahované ze zpráv asistenta v gen_ai.input.messages / gen_ai.output.messages Volání nástrojů provedená agentem během interakce. Používá se vyhodnocovači nástrojů. Vyžaduje se pouze pro evaluátory související s nástroji. 
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": {
            "model": 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": {
            "model": 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,
        },
    },
]

Úplný příklad spustitelného příkazu najdete v tématu sample_evaluations_builtin_with_traces.py na GitHub. Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Vyhodnocení syntetických dat (Preview)

azure_ai_synthetic_data_gen_preview Pomocí typu zdroje dat můžete vygenerovat syntetické testovací dotazy, odeslat je do nasazeného modelu nebo agenta Foundry a vyhodnotit odpovědi. Tento scénář použijte, pokud nemáte testovací datovou sadu. Služba generuje dotazy na základě výzvy, kterou zadáte (nebo z pokynů agenta), spustí je proti cíli a vyhodnotí odpovědi.

Tip

Než začnete, dokončete Začínáme.

Jak funguje hodnocení syntetických dat

  1. Služba generuje syntetické dotazy na základě vašich prompt a volitelných počátečních datových souborů.
  2. Každý dotaz se odešle do zadaného cíle (modelu nebo agenta) a vygeneruje odpověď.
  3. Vyhodnocovače vyhodnotí jednotlivé odpovědi pomocí vygenerovaného dotazu a odpovědi.
  4. Vygenerované dotazy se ve vašem projektu ukládají jako datová sada pro opakované použití.

Parametry

Parametr Požadované Popis
samples_count Ano Maximální počet syntetických testovacích dotazů, které se mají vygenerovat.
model_deployment_name Ano Nasazení modelu, které se použije ke generování syntetických dotazů Podporují se jenom modely s funkcí rozhraní API pro odpovědi. Dostupnost najdete v tématu Dostupnost oblastí rozhraní API odpovědí.
prompt Ne Pokyny popisující typ dotazů, které se mají vygenerovat. Volitelné, pokud má cíl agenta nakonfigurované pokyny.
output_dataset_name Ne Název výstupní datové sady, ve které se ukládají vygenerované dotazy. Pokud nezadáte název, služba ho automaticky vygeneruje.
sources Ne Počáteční datové soubory (podle ID souboru) pro zlepšení relevance vygenerovaných dotazů. V současné době je podporován pouze jeden soubor.

Nastavení vyhodnocovačů a mapování dat

Generátor syntetických dat vytváří dotazy v {{item.query}} poli. Cíl generuje odpovědi, které jsou k dispozici v {{sample.output_text}}. Namapujte tato pole na vyhodnocovače:

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": {
            "model": 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}}",
        },
    },
]

Vytvořit vyhodnocení a spustit

Cíl modelu

Vygenerujte syntetické dotazy a vyhodnoťte model:

eval_object = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Volitelně můžete přidat výzvu systému k tvarování chování cílového modelu. Pokud používáte input_messages s generováním syntetických dat, zahrňte pouze system zprávy rolí – služba poskytuje generované dotazy jako uživatelské zprávy automaticky.

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

Cíl agenta

Generování syntetických dotazů a vyhodnocení 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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků. Odpověď obsahuje output_dataset_id vlastnost, která obsahuje ID vygenerované datové sady, kterou můžete použít k načtení nebo opakovanému použití syntetických dat.

Vyhodnocení na úrovni konverzace (náhled)

Vyhodnoťte kompletní konverzace a vyhodnoťte kvalitu agenta napříč všemi interakcemi uživatelů – nejen individuálními odpověďmi. Pomocí hodnocení na úrovni celé konverzace můžete identifikovat problémy s kvalitou, jako jsou neúplné vyřešení úkolu, frustrace uživatelů a regrese při volání nástrojů, které hodnocení na úrovni jednotlivých tahů nezachytí.

Představte si například pracovníka podpory, kdy je uživatel během několika výměn stále frustrovanější:

Turn 1 — User: "I need to reset my password" (Potřebuji resetovat heslo). Agent: "Našel jsem váš účet. Pošlu odkaz pro resetování."

Turn 2 — User: "I didn't get the email" (Nedostal(a) jsem e-mail. Agent: "Přepošli jsem odkaz. Zkontrolujte spam."

Turn 3 — Uživatel: "Pořád nic. Můžete ho jednoduše resetovat přímo?" Agent: "Odeslal(a) jsem jiný odkaz pro resetování.

Hodnoticí mechanismus na úrovni jednotlivých tahů hodnotí pouze poslední odpověď, která je zdvořilá a podniká kroky, takže získá dobré hodnocení. Hodnotitel na úrovni celé konverzace, který v jejím průběhu hodnotí spokojenost zákazníka, upozorní na to, že agent třikrát zopakoval stejný neúspěšný postup, aniž by zkusil alternativu, a problém uživatele tak zůstal nevyřešen.

Hodnocení na úrovni celé konverzace se od hodnocení na úrovni jednotlivých tahů liší v několika ohledech:

Aspect Na úrovni replik Úroveň konverzace
Scope Jednotlivé páry odpovědí na dotazy Kompletní konverzace s více replikami
Metrics Kvalita a bezpečnost každé odpovědi Výsledky na úrovni konverzace a spokojenost uživatelů
Formát dat JSONL s poli query a response JSONL s polem messages obsahujícím úplnou konverzaci
Případ použití Testování odpovědí jednotlivých modelů Testování kompletních prostředí agentů

Vyhodnocení na úrovni konverzace podporuje čtyři možnosti zdroje dat:

Možnost Kdy použít Typ zdroje dat
Z datové sady nebo z vloženého textu Máte místní záznamy konverzací nebo testovací data. jsonl s file_id nebo file_content
Podle ID konverzace Chcete vyhodnotit konkrétní konverzace z App Insights azure_ai_trace_data_source_preview s trace_source
Podle filtru agenta s vzorkováním Chcete vyhodnotit celkovou kvalitu agenta napříč vzorkovaným provozním provozem. azure_ai_trace_data_source_preview s trace_source
Simulované konverzace Chcete vygenerovat syntetické testovací konverzace. azure_ai_target_completions s conversation_gen_preview

Volba úrovně vyhodnocení

Parametr evaluation_level u běhu určuje, zda hodnotitelé hodnotí jednotlivé tahy konverzace, nebo celé konverzace:

Value Chování
"turn" Hodnotitelé hodnotí každý tah nezávisle.
"conversation" Vyhodnocovače hodnotí celou konverzaci jako celek.
(vynecháno) Výchozí je "turn".

Důležité

Kompatibilita vyhodnocovače: Každý vyhodnocovací nástroj podporuje konkrétní úrovně vyhodnocení. Zkontrolujte pole vyhodnocovače supported_evaluation_levels v katalogu vyhodnocovače.

  • Vyhodnocovače jen pro otáčení (například fluency, relevance) nelze použít s evaluation_level="conversation".
  • V současné době podporují všechny vyhodnocovače na úrovni konverzací obě "turn" úrovně i "conversation" úrovně.

Běžné chyby

Error Příčina Řešení
Nekompatibilní úroveň vyhodnocení Použití evaluation_level="conversation" s vyhodnocovačem jen pro otáčení Odeberte vyhodnocovač pouze pro otáčení nebo změňte na evaluation_level="turn"

Příprava dat konverzace

Vytvořte soubor JSONL, ve kterém každý řádek obsahuje úplnou konverzaci v messages poli. Každá zpráva by měla obsahovat role (uživatel, asistent nebo systém) a content. Úplný příklad najdete v ukázkách vyhodnocení konverzací v sadě 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?"}]}

Můžete také zahrnout definice nástrojů a volání nástrojů, pokud váš agent používá nástroje:

{"messages": [{"role": "user", "content": "What is the capital 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."}]}

Definování schématu dat a vyhodnocovačů

Zadejte schéma pro data konverzace, zprávy a výběrové vyhodnocovače navržené pro vyhodnocení na úrovni konverzace. Vyhodnocovače na úrovni konverzací hodnotí celou interakci, nikoli jednotlivé obraty.

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

Vytvořit vyhodnocení a spustit

Příprava: stáhněte sample_data_multiturn_conversations.jsonl

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

Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Vyhodnoťte konverzace podle ID z trasování

Vyhodnoťte konkrétní konverzace z Application Insights zadáním ID konverzací. Tuto možnost použijte k původní příčině problémů nebo k ověření oprav konkrétních interakcí. Můžete například prošetřit konverzaci označenou upozorněním nebo ověřit opravu známého problému.

Kde najít ID konverzací

Najděte ID konverzací v:

  • Uživatelské rozhraní trasovacích protokolů Application Insights — Přejděte k zajímavým trasováním a v podrobnostech trasování vyhledejte pole conversation_id.
  • Výstup protokolování vaší aplikace – Pokud explicitně nastavíte conversation_id při vytváření odpovědí agenta, načtěte ho z protokolů.
  • Kontext trasování OpenTelemetry — conversation_id může být také odvozeno z hlavičky traceparent, pokud váš agent používá standardní propagaci kontextu trasování.

Poznámka

Definice nástrojů jsou automaticky načítány z tras nebo zjišťovány z registru agenta. V požadavku je nemusíte zadávat.

Parametry pro vyhledání ID konverzace

Parametr Požadované Popis
conversation_ids Ano Pole identifikátorů konverzací k vyhodnocení.
lookback_hours Ne Počet hodin zpětného hledání od end_time. Výchozí hodnota je sedm dní (168 hodin).
end_time Ne Konec vyhledávacího okna (formát ISO 8601). Ve výchozím nastavení je nastaven aktuální čas. 
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"},
    )

Poznámka

  • Příjem dat do Application Insights může způsobit zpoždění mezi okamžikem, kdy jsou trasovací záznamy generovány, a okamžikem, kdy jsou k dispozici pro účely vyhodnocení. Pokud dotaz nenajde trasování, počkejte několik minut a zkuste to znovu.
  • Maximální zpětné vyhledávání je 7 dní (168 hodin). Pokud chcete získat přístup ke starším trasováním, použijte start_time a end_time v rámci limitů uchovávání informací v App Insights.

Vyhodnocení ukázkových konverzací podle filtru agenta

Vyhodnoťte ukázkovou sadu konverzací z Application Insights filtrováním podle názvu agenta. Pomocí této možnosti můžete posoudit celkovou kvalitu agenta napříč produkčním provozem. Například spusťte pravidelné hodnocení kvality nebo monitorujte snížení kvality v produkčním prostředí.

Agent, který zadáte pro filtrování, může být součástí konverzace s více agenty. Filtr odpovídá jakékoli konverzaci, ve které se tento agent zúčastnil.

Poznámka

Definice nástrojů jsou automaticky načítány z tras nebo zjišťovány z registru agenta. V požadavku je nemusíte zadávat.

Pole identit agenta

Určete agenta, který se má filtrovat pomocí jednoho z těchto formátů:

Format Příklad Popis
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Dvě samostatná pole. Pokud agent_version je vynechán, použijte nejnovější verzi.
agent_id "agent_id": "my-agent:1" Jeden řetězec ve formátu "name:version".

Strategie filtrování

Strategy Popis
random_sampling (Výchozí) Rovnoměrně náhodně vzorkujte konverzace max_traces .
smart_filtering Heuristika spravovaná službou, která upřednostňuje „zajímavá“ trasování – konverzace s potenciálními problémy, okrajovými případy nebo anomáliemi.

Parametry

Parametr Požadované Popis
agent_name Ano Název agenta pro filtrování trasování.
agent_version Ne Verze agenta. Pokud tento parametr vynecháte, použije se nejnovější verze.
agent_id Ne Alternativa k agent_name + agent_version. Jeden řetězec ve formátu "name:version".
start_time Ano Začátek časového intervalu (v sekundách od začátku Unixové epochy, UTC).
end_time Ano Konec časového intervalu (Unix epoch seconds, UTC). Přidejte rezervu +600 sekund, abyste předešli zpoždění při příjmu dat.
max_traces Ne Maximální počet konverzací k ukázce Výchozí hodnota je 1 000.
filter_strategy Ne "random_sampling" (výchozí) nebo "smart_filtering" (heuristika spravovaná službou, která upřednostňuje zajímavé trasy).

Důležité

Časové období (end_time - start_time) musí být nejméně 15 minut (900 sekund). Tento požadavek je dán tím, že dotazy na úrovni konverzací uplatňují na každé straně pětiminutový interval nečinnosti, aby se předešlo neúplným konverzacím.

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

Poznámka

Časový interval dotazu App Insights je momentálně omezený na maximálně 7 dnů (168 hodin). Nemůžete získat přístup k trasování starším než 7 dnů bez explicitního poskytnutí start_time a end_time v rámci limitů uchovávání informací v App Insights.

Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Simulace konverzací

Vygenerujte simulované konverzace z popisů scénářů a vyhodnoťte je na úrovni konverzace. Tento scénář použijte k otestování chování agenta v kontrolovaných situacích před nasazením. Služba generuje realistické konverzace na základě popisu scénáře a pak je vyhodnotí.

Tento přístup je užitečný pro:

  • Testování před nasazením: Ověřte chování agenta v různých scénářích bez skutečného provozu uživatelů.
  • Pokrytí okrajových případů: Testovací scénáře, které se přirozeně vyskytují jen zřídka, ale je důležité je správně ošetřit.
  • Regresní testování: Zajistěte, aby aktualizace agenta nezhoršily výkon v známých scénářích.
  • Testování škálovatelnosti: Rychle generujte mnoho konverzací, abyste zátěžově otestovali schopnosti agenta.

Jak funguje simulace konverzací

  1. Zadáte datovou sadu popisů scénářů – každý řádek popisuje situaci, kterou se simulovaný uživatel pokusí provést.
  2. Služba používá model simulátoru k hraní role uživatele a interakci s vaším agentem na základě scénáře.
  3. Každý scénář generuje jednu nebo více kompletních konverzací.
  4. Vyhodnocovače na úrovni konverzací vyhodnotí vygenerované konverzace.
  5. Váš projekt ukládá jak konverzace, tak výsledky vyhodnocení.

Příprava dat scénáře

Vytvořte soubor JSONL, kde každý řádek popisuje scénář pro simulovaného uživatele. Schéma vyžaduje id, test_case_descriptiona desired_num_turns. Uveďte podrobnosti o cíli, kontextu a omezeních uživatele. Úplný příklad najdete v sadě SDK v ukázkách vyhodnocení konverzací.


{"id": "contoso_refund_timeline", "test_case_description": "Customer returned an item to Contoso Electronics 5 days ago and hasn't received their refund yet. They want to know how long Contoso refunds take.", "desired_num_turns": 10}
{"id": "contoso_store_hours_lookup", "test_case_description": "Customer wants to know what time the Contoso Electronics store closes today. Simple single-fact question with possibly one clarifying turn about which location.", "desired_num_turns": 3}

Parametry

Parametr Požadované Popis
num_conversations Ne Počet konverzací, které se mají vygenerovat v jednotlivých scénářích Výchozí hodnota je 5, limit 5 na straně serveru.
max_turns Ne Maximální počet replik (výměn) v jedné konverzaci Výchozí hodnota je 10, limit na straně serveru 20.
model Ano Nasazení modelu, které se má použít k simulaci uživatele. Například: gpt-4.1.
sampling_params Ne Parametry vzorkování pro model simulátoru, včetně temperature, top_pa max_completion_tokens.
data_mapping Ne Mapuje pole z vašeho scénáře JSONL na parametry simulace. Společné mapování: test_case_description, id, desired_num_turns.

Definování vyhodnocovačů

Vyberte vyhodnocovače navržené pro hodnocení na úrovni konverzace. Simulované konverzace se automaticky přiřazují k hodnotitelům.

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, PromptAgentDefinition

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"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}}"},
        ),
    ]

Vytvořit vyhodnocení a spustit

Příprava: stáhněte si sample_data_simulation_scenarios.jsonl.

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./sample_data_simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "item_generation_params": {
            "type": "conversation_gen_preview",
            "model": model_deployment_name,
            "num_conversations": 2,
            "max_turns": 5,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
            "data_mapping": {
                "test_case_description": "test_case_description",
                "id": "id",
                "desired_num_turns": "desired_num_turns",
            },
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

Chcete-li zjistit dokončení a interpretovat výsledky, podívejte se na Získání výsledků.

Získání výsledků

Po dokončení zkušebního spuštění načtěte výsledky se skóre a zkontrolujte je na portálu nebo programaticky.

Hlasování o výsledcích

Procesy vyhodnocení jsou asynchronní. Dotazujte stav spuštění, dokud se neskončí, a pak načtěte výsledky:

import time
from pprint import pprint

while True:
    run = openai_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(
    openai_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}")

Interpretace výsledků

V jednom příkladu dat vypíše všechny vyhodnocovače následující schéma:

  • Popisek: binární popisek "úspěšný" (pass) nebo "neúspěšný" (fail), podobný výstupu jednotkového testu. Pomocí tohoto výsledku můžete usnadnit porovnání mezi vyhodnocovači.
  • Skóre: skóre z přirozeného měřítka každého vyhodnocovače. Někteří hodnotitelé používají jemně odstupňovanou rubriku, bodování na 5bodové stupnici (vyhodnocovače kvality) nebo 7bodové měřítko (vyhodnocovače bezpečnosti obsahu). Jiné, například textové vyhodnocovače podobnosti, používají skóre F1, které jsou plovoucí mezi 0 a 1. Libovolné skóre jiné než binární se v poli "label" podle hodnoty "threshold" převede na "pass" nebo "fail".
  • Prahová hodnota: Jakékoli nebinární skóre se binarizují na "pass" nebo "fail" na základě výchozí prahové hodnoty, kterou může uživatel přepsat v prostředí sady SDK.
  • Důvod: Aby bylo možné zlepšit srozumitelnost, vypíše všechny vyhodnocovací moduly LLM také pole s odůvodněním, které vysvětluje, proč je zadané určité skóre.
  • Podrobnosti: (volitelné) U některých vyhodnocovačů, například tool_call_accuracy, může existovat pole podrobností nebo příznaky, které obsahují další informace, které uživatelům pomůžou ladit své aplikace.

Příklad výstupu (jedna položka)

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

Příklad výstupu (agregace)

Pro agregaci výsledků v rámci datových příkladů (datové sady) tvoří průměrný poměr případů označených jako "pass" průběžnou míru pro danou datovou sadu.

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

Řešení potíží

Úloha běží po dlouhou dobu

Vaše vyhodnocovací úloha může zůstat ve stavu Spuštěno na delší dobu. K tomuto stavu obvykle dochází, když nasazení modelu Azure OpenAI nemá dostatečnou kapacitu, což způsobí, že služba bude požadavky opakovat.

Rozlišení:

  1. Zrušte aktuální úlohu vyhodnocení pomocí funkce openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Zvyšte kapacitu modelu na portálu Azure.
  3. Znovu spusťte vyhodnocení.

Chyby ověřování

Pokud obdržíte chybu 401 Unauthorized nebo 403 Forbidden, ověřte, že:

  • Vaše DefaultAzureCredential konfigurace je správně nakonfigurovaná. Pokud používáte Azure CLI, spusťte az login.
  • Váš účet má v projektu Foundry roli uživatele Foundry .
  • Adresa URL koncového bodu projektu je správná a obsahuje názvy účtů i projektů.

Chyby formátu dat

Pokud vyhodnocení selže s chybou schématu nebo mapování dat:

  • Ověřte, že soubor JSONL obsahuje jeden platný objekt JSON na řádek.
  • Ověřte, že názvy polí odpovídají data_mapping názvům polí v souboru JSONL přesně (rozlišují se malá a velká písmena).
  • Zkontrolujte, že item_schema vlastnosti odpovídají polím v datové sadě.

Chyba HTTP 400 při použití file_id při vyhodnocování odpovědí agenta

Vyhodnocení odpovědí agenta (azure_ai_responses) podporují pouze vložená data prostřednictvím file_content. Pokud zadáte ID odpovědí pomocí file_id, požadavek vrátí 400 Bad Request chybu.

Řešení: Přepněte na file_content a uveďte ID odpovědí přímo v textu.

Chyby omezení rychlosti

Na úrovni tenanta, předplatného a projektu se u vytváření běhů vyhodnocení uplatňují limity četnosti. Pokud obdržíte odpověď 429 Too Many Requests:

  • Zkontrolujte hlavičku retry-after v odpovědi na doporučenou dobu čekání.
  • Podrobnosti o limitu rychlosti najdete v textu odpovědi.
  • Při opakování neúspěšných požadavků použijte exponenciální zpomalování.

Pokud úloha vyhodnocení selže s chybou 429 během provádění:

  • Zmenšete velikost testovací datové sady nebo ji rozdělte do menších dávek.
  • Zvyšte kvótu tokenů za minutu (TPM) pro nasazení modelu na portálu Azure.

Chyby nástroje vyhodnocovače agentů

Pokud hodnoticí modul agenta vrátí chybu pro nástroje bez podpory:

  • Projděte si podporované nástroje pro vyhodnocovače agentů.
  • Jako alternativní řešení zabalte nepodporované nástroje jako uživatelsky definované nástroje funkcí, aby je vyhodnocovací nástroj mohl posoudit.

Související obsah

  • Last updated on