Kiértékelések futtatása a felhőben a Microsoft Foundry SDK használatával

Ebből a cikkből megtudhatja, hogyan futtathat értékeléseket a felhőben egy tesztadatkészlet előzetes üzembe helyezési teszteléséhez.

A legtöbb forgatókönyvhez használjon felhőbeli kiértékelést – különösen nagy méretekben történő teszteléskor, az értékelések folyamatos integrációs és folyamatos kézbesítési (CI/CD) folyamatokba való integrálásához, vagy az előzetes üzembe helyezési teszteléshez. A kiértékelések felhőben való futtatása szükségtelenné teszi a helyi számítási infrastruktúra kezelését, és támogatja a nagy léptékű, automatizált tesztelési munkafolyamatokat. Azt is ütemezheti , hogy a kiértékelések ismétlődően fussanak, vagy beállíthatja a folyamatos értékelést , hogy automatikusan kiértékelje a mintául szolgáló ügynökválaszokat az éles környezetben.

A felhőbeli kiértékelési eredmények a Foundry-projektben vannak tárolva. Megtekintheti az eredményeket a portálon, lekérheti őket az SDK-on keresztül, vagy átirányíthatja őket az Application Insightsba, ha csatlakoztatva van. A felhőalapú értékelés támogatja az összes Microsoft által válogatott beépített kiértékelőt és a saját egyedi kiértékelőket. A kiértékelőket a kiértékelőkatalógusban kezelik ugyanazzal a projekthatókörrel, szerepköralapú hozzáférés-vezérléssel.

Tipp

A teljes futtatható példákért tekintse meg a Python SDK-kiértékelési mintákat a GitHub.

Hogyan működik a felhő kiértékelése?

A felhő kiértékelése három lépésből áll:

  1. Határozza meg, hogy mit értékeljen ki. Írja le az adatstruktúrát (a data_source_config) és az azt értékelő kiértékelőket (tesztelési kritériumokat).
  2. Hozza létre az értékelést. Küldje el a definíciót a következő használatával openai_client.evals.create(): .
  3. Futtassa, és olvassa el az eredményeket. Indítson el egy futtatást a(z) openai_client.evals.runs.create() használatával, kérdezze le rendszeresen, amíg be nem fejeződik, majd olvassa ki a pontozott eredményeket. Lásd az eredményséma eredményének lekérése című témakört.

A szakasz többi része végigvezeti az 1. lépés bemeneteit: válasszon ki egy forgatókönyvet, majd válasszon ki kiértékelőket.

Válassza ki a kiindulási pontot

Meglévő adatkészlet

Ezt a lehetőséget akkor használja, ha a lekérdezések és válaszok már össze vannak gyűjtve egy fájlban (vagy a lekérdezésekhez tartozó referenciaértékek), és csak azt szeretné, hogy a Foundry pontozza őket. A JSONL támogatja a fordulószintű sorokat és a beszélgetési szintű bemeneteket is; A CSV csak fordulószintű.

Forgatókönyv Mikor érdemes használni? Adatforrás típusa
Párbeszédforduló-szintű adatkészlet-kiértékelés Minden sor egy query/response pár, opcionálisan context vagy ground_truth elemmel. jsonl Vagy csv
Beszélgetésszintű adathalmaz kiértékelése (előzetes verzió) Minden sor egy messages tömbként kifejezett beszélgetés. jsonl

Adatok az Foundryben vagy az Application Insightsban

Ezt az útvonalat akkor használja, ha az ügynök már fut, és értékelni szeretné, hogy mi is történt valójában. Az adatok áthelyezése helyett a Foundryt azokra az adatokra irányítja, ahol azok már megtalálhatók – a Foundry-válaszazonosító, illetve az Application Insights nyomkövetési vagy beszélgetési azonosítója alapján.

Forgatókönyv Mikor érdemes használni? Adatforrás típusa
Ügynök válaszának kiértékelése Az ügynököd a Foundryben fut, és vannak pontozandó válaszazonosítóid. azure_ai_responses
Fordulószintű nyomkövetési kiértékelés (előzetes) Az ügynök OpenTelemetry-nyomkövetéseket bocsát ki az Application Insightsba – beleértve a nem öntödei keretrendszereket, például a LangChaint vagy az egyéni OpenTelemetry-eszközökkel rendelkező ügynököket. Az egyes nyomkövetések egymástól függetlenül lesznek értékelve. azure_ai_trace_data_source_preview
Beszélgetésszintű nyomkövetés kiértékelése (előzetes verzió) Ugyanazok a nyomkövetési források, de teljes beszélgetéseket pontozhat beszélgetésazonosító vagy ügynök szerinti szűrés alapján, mintavételezéssel. azure_ai_trace_data_source_preview

Válaszok nélküli bemenetek

Ezt az elérési utat akkor használja, ha rendelkezik a bemenetekkel, de még nincs válasz. A Foundry az értékelés során egy modell- vagy ügynökcélponthoz generál válaszokat, majd pontozza őket. Válasszon egy sort annak alapján, hogy a bemenet lekérdezésekből áll-e (különálló fordulókként elküldve), vagy forgatókönyv-leírásokból (egy beszélgetésszintű interakció irányítására használva).

Forgatókönyv Mikor érdemes használni? Adatforrás/cél
Model Target befejezések Vannak lekérdezései, és szeretné kiértékelni egy modelltelepítés válaszait. azure_ai_target_completions → azure_ai_model
Ügynök célkiegészítései Vannak lekérdezései, és egy Foundry-ügynök válaszait szeretné kiértékelni. azure_ai_target_completions → azure_ai_agent
Beszélgetési szimuláció (előzetes verzió) Rendelkezik forgatókönyv-leírásokkal (nincsenek lekérdezések); Az Foundry egy olyan felhasználót szimulál, aki beszélgetési szintű interakciót hajt az ügynökkel. azure_ai_target_completions → azure_ai_agent

Még nincs adat

Akkor használja ezt az útvonalat, amikor új modellt vagy ügynököt hoz létre, és még nem gyűjtött be semmilyen bemeneti adatot. A Foundry a semmiből hozza létre a tesztadatokat – válasszon szintetikus lekérdezéseket a széles körű minőségi lefedettséghez, vagy adverzárius promptokat a biztonsági teszteléshez.

Forgatókönyv Mikor érdemes használni? Adatforrás/cél
Szintetikus adatértékelés (előzetes verzió) Olyan minőségi lefedettséget szeretne, amely túlmutat azon, amit kézzel írna. Az Foundry teszt-lekérdezéseket hoz létre, elküldi őket a célnak, és válaszokat ad vissza. azure_ai_synthetic_data_gen_preview azure_ai_model→ vagyazure_ai_agent
Piros csapat értékelése Automatizált adverzárius tesztelést szeretne – a Foundry korlátozásokat megkerülő és káros tartalomra irányuló promptokat generál, valamint pontozza, hogyan reagál a célrendszer. azure_ai_red_team azure_ai_model→ vagyazure_ai_agent

Kiértékelők kiválasztása

Minden forgatókönyv oszlopleképezéseken keresztül köti a kiértékelőket az adatok mezőihez. Az elérhető mezők az adatforrástól függenek. Az adathalmazalapú forgatókönyvek elérhetővé teszik az egyéni elemek mezőit, míg a cél által generált forgatókönyvek egy mintasémán keresztül a modell vagy az ügynök válaszát is elérhetővé teszik. A cikk későbbi, forgatókönyvenkénti alszakaszai az egyes esetek oszlopleképezéseit mutatják be.

Az elérhető kiértékelők áttekintését és azok kiválasztását a beépített kiértékelők és egyéni kiértékelők című témakörben tekintheti meg.

Előfeltételek

  • Egy Foundry-projekt.

  • Egy Azure OpenAI-telepítés a csevegés befejezését támogató GPT-modellel (például gpt-5-mini).

  • Foundry-felhasználó szerepkör a Foundry-projektben.

    Fontos

    Az Foundry RBAC-szerepköröket nemrég átnevezték. Foundry user, Foundry Owner, Foundry-fióktulajdonos és Foundry Project Manager korábban Azure AI-felhasználónak, Azure AI-tulajdonosnak, Azure AI-fióktulajdonosnak és Azure AI-Project-kezelőnek hívták. Előfordulhat, hogy egyes helyeken továbbra is a korábbi elnevezések jelennek meg, amíg az átnevezés fokozatosan bevezetésre kerül. A szerepkör-azonosítók és az alapvető jogosultságok az átnevezés ellenére változatlanok maradnak.

  • Igény szerint saját tárfiókját is használhatja a kiértékelések futtatásához.

Megjegyzés

Egyes kiértékelési funkciók regionális korlátozásokkal rendelkeznek. Részletekért tekintse meg a támogatott régiókat .

Első lépések

Telepítse az SDK-t, és állítsa be az ügyfelet:

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

Bemeneti adatok előkészítése

A legtöbb kiértékelési forgatókönyvhez bemeneti adatokra van szükség. Kétféleképpen adhat meg adatokat:

Töltsön fel egy JSONL- vagy CSV-fájlt, hogy verziószámozott adathalmazt hozzon létre a Foundry-projektben. Az adathalmazok támogatják a verziószámozást és az újbóli használatot több kiértékelési futtatás során. Ezt a megközelítést éles teszteléshez és CI/CD-munkafolyamatokhoz használhatja.

JSONL-fájl előkészítése soronként egy JSON-objektummal, amely a kiértékelők számára szükséges mezőket tartalmazza:

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

Vagy készítsen elő egy CSV-fájlt a kiértékelőmezőknek megfelelő oszlopfejlécekkel:

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

Az adatok közvetlen megadása

A kis tesztkészletekkel való gyors kísérletezéshez adja meg az adatokat közvetlenül a kiértékelési kérelemben a használatával 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",
            }
        ),
    ],
)

Az adatforrás konfigurációjában adja meg a source mezőt futtatás létrehozásakor "source"-ként. A következő szakaszok alapértelmezés szerint file_id-t használnak.

Adathalmazok kiértékelése

Értékelje ki az előre kiszámított válaszokat egy JSONL-fájlban az adatforrás típusával jsonl . Ez a forgatókönyv akkor hasznos, ha már rendelkezik modellkimenetekkel, és értékelni szeretné azok minőségét.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket , és készítse elő a bemeneti adatokat.

Az adatséma és a kiértékelők meghatározása

Adja meg a JSONL-mezőknek megfelelő sémát, és válassza ki a futtatni kívánt kiértékelőket (tesztelési feltételeket). Használja a data_mapping paramétert arra, hogy a bemeneti adatmezőket a {{item.field}} szintaxis használatával összekapcsolja az értékelő paraméterekkel. Mindig foglalja bele a data_mapping az értékelőhöz szükséges beviteli mezőket. A mezőneveknek meg kell egyezniük a JSONL-fájlban lévőkkel – például, ha az adatokban "question" szerepel ahelyett, hogy "query" lenne, akkor használja a "{{item.question}}" értéket a leképezésben. Az egyes kiértékelőkhöz szükséges paraméterekért lásd a beépített kiértékelőket.

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

Kiértékelés és futtatás létrehozása

Hozza létre az értékelést, majd indítsa el a futtatást a feltöltött adathalmazon. A futtatás minden kiértékelőt végrehajt az adathalmaz minden sorában.

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

Egy teljes futtatható példáért lásd sample_evaluations_builtin_with_dataset_id.py a GitHub. A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

CSV-adathalmaz kiértékelése

Egy CSV-fájlban előre összeállított válaszok kiértékelése az csv adatforrás típusával. Ez a forgatókönyv ugyanúgy működik, mint az adathalmazok kiértékelése , de A JSONL helyett CSV-fájlokat fogad el. Amikor az adatok már táblázat vagy táblázatos formátumúak, használja a CSV-t.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket , és készítse elő a bemeneti adatokat.

CSV-fájl előkészítése

Hozzon létre egy CSV-fájlt olyan oszlopfejlécekkel, amelyek megfelelnek a kiértékelők számára szükséges mezőknek. Minden sor egy tesztesetet jelöl.

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.

Feltöltés és futtatás

Töltse fel a CSV-fájlt adathalmazként. Ezután hozzon létre egy értékelést az adatforrás típusával csv . A sémadefiníció és az értékelő konfigurációja megegyezik a JSONL-értékelésekéval. Az egyetlen különbség az "type": "csv" adatforrásban van.

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

A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Modellcél kiértékelése

Lekérdezések küldése egy üzembe helyezett modellre futásidőben. Értékelje a válaszokat a(z) azure_ai_target_completions adatforrástípus használatával egy azure_ai_model célhoz. A bemeneti adatok lekérdezéseket tartalmaznak. A modell válaszokat hoz létre, amelyeket aztán kiértékel.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket , és készítse elő a bemeneti adatokat.

Az üzenetsablon és a cél meghatározása

A input_messages sablon szabályozza, hogy a rendszer hogyan küldi el a lekérdezéseket a modellnek. A bemeneti adatok mezőinek hivatkozására szolgál {{item.query}} . Adja meg a kiértékelendő modellt és az opcionális mintavételezési paramétereket:

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

Kiértékelők és adatleképezések beállítása

Amikor a modell futásidőben hoz létre válaszokat, használja {{sample.output_text}} a data_mapping modell kimenetére való hivatkozáshoz. A bemeneti adatok mezőinek hivatkozására szolgál {{item.field}} .

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

Kiértékelés és futtatás létrehozása

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

A teljes futtatható példáért tekintse meg a sample_model_evaluation.py GitHub. A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Tipp

Egy másik próbafuttatás hozzáadásához használja ugyanazt a kódot.

Az ügynök céljának kiértékelése

Lekérdezéseket küldhet egy Foundry-ügynöknek futási időben, és a válaszokat a azure_ai_target_completions adatforrástípus használatával egy azure_ai_agent célhoz értékelheti. Ez a forgatókönyv mind a készenléti ügynökök, mind a tárolt ügynökök esetében működik.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket , és készítse elő a bemeneti adatokat.

Tipp

A válaszprotokollt használó üzemeltetett ügynökök az itt látható kódmintákkal működnek. Az invocations protokollt használó üzemeltetett ügynökök esetében a input_messages formátum eltérő. Részletekért tekintse meg az üzemeltetett ügynök meghívási protokollját .

Az üzenetsablon és a cél meghatározása

A input_messages sablon szabályozza, hogy a lekérdezések hogyan legyenek elküldve az ügynöknek. A bemeneti adatok mezőinek hivatkozására szolgál {{item.query}} . Adja meg a név alapján kiértékelni kívánt ügynököt:

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

Kiértékelők és adatleképezések beállítása

Amikor az ügynök futásidőben generál válaszokat, használja a {{sample.*}} változókat a data_mapping-ban az ügynök kimenetére való hivatkozásra.

Változó Leírás Használat a következőhöz:
{{sample.output_text}} Az ügynök egyszerű szöveges válasza. Olyan kiértékelők, amelyek sztringválaszt várnak (például coherence, violence).
{{sample.output_items}} Az ügynök strukturált JSON-kimenete, beleértve az eszközhívásokat is. Olyan kiértékelők, amelyek teljes interakciós környezetet igényelnek (például task_adherence).
{{item.field}} Egy mező a bemeneti adatokból. Beviteli mezők, mint a query vagy ground_truth.

Tipp

A query mező strukturált JSON-t tartalmazhat, beleértve a rendszerüzeneteket és a beszélgetési előzményeket. Egyes ügynökértékelők, például task_adherence ezt a kontextust használják a pontosabb pontozáshoz. A lekérdezés formázásának részleteiért tekintse meg az ügynökértékelők dokumentációját.

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

Kiértékelés és futtatás létrehozása

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

A teljes futtatható példáért lásd sample_agent_evaluation.py a GitHub. A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Üzemeltetett ügynök meghívási protokollja

Az invocations protokollt használó üzemeltetett ügynökök ugyanazt azure_ai_agent a céltípust támogatják, de szabadkérelmű input_messages formátumot használnak. A strukturált sablonformátum helyett adjon meg egy JSON-objektumot, amely közvetlenül az ügynök kéréstörzséhez /invocations lesz leképezve. A {{item.*}} bemeneti adatok mezőit helyőrzőkkel helyettesítheti.

Ha egy üzemeltetett ügynök támogatja a válaszokat és a hívási protokollokat is, a szolgáltatás alapértelmezés szerint az invocations protokollt használja.

Az üzenet formátumának és céljának meghatározása

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

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

Kiértékelés és futtatás létrehozása

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

A kiértékelő beállítása és az adattérképezések megegyeznek az prompt ügynök kiértékeléssel. Az ügynök szöveges válaszához használja a {{sample.output_text}} jelölést, és a teljes strukturált kimenethez, beleértve az eszközhívásokat is, a {{sample.output_items}} jelölést.

Ügynök válaszának kiértékelése

Az öntödei ügynök válaszait válaszazonosítók szerint azure_ai_responses adatforrástípus segítségével leikérdezheti és kiértékelheti. Ezzel a forgatókönyvkel kiértékelhet bizonyos ügynök-interakciókat azok bekövetkezése után.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket.

A válaszazonosító egy egyedi azonosító, amelyet minden alkalommal ad vissza, amikor egy Foundry-ügynök választ hoz létre. A válaszazonosítókat az ügynökök interakcióiból a Válasz API használatával vagy az alkalmazás nyomkövetési naplóiból gyűjtheti össze. Adja meg a beágyazott azonosítókat fájltartalomként, vagy töltse fel őket adathalmazként (lásd : Bemeneti adatok előkészítése).

Válaszazonosítók gyűjtése

A Válaszok API minden hívása egy egyedi id mezővel rendelkező válaszobjektumot ad vissza. Gyűjtse össze ezeket az azonosítókat az alkalmazás interakcióiból, vagy hozza létre őket közvetlenül:

# 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

A válaszazonosítókat az alkalmazás nyomkövetési naplóiban vagy monitorozási folyamatában található ügynöki interakciókból is gyűjtheti. Minden válaszazonosító egyedileg azonosítja a kiértékelési szolgáltatás által lekérhető tárolt választ.

Kiértékelés és futtatás létrehozása

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

A teljes futtatható példáért lásd sample_agent_response_evaluation.py a GitHub. A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Nyomkövetés kiértékelése (előzetes verzió)

Értékelje ki az Application Insights által már rögzített ügynök-interakciókat. Használja az azure_ai_traces adatforrás típusát. Ez a forgatókönyv hasznos a valós üzemi forgalom üzembe helyezés utáni értékelésére. Kiválaszthatja a nyomokat a monitoringfolyamatából, és értékelőket futtathat rajtuk anélkül, hogy újrajátszana bármilyen kérést.

Fontos

A nyomkövetéses kiértékelés az ajánlott megközelítés a nem a Microsoft Foundry Agent Service-szel készített ügynökök kiértékelésére, beleértve a LangChaint és az egyéni keretrendszereket. Ha az ügynök a GenAI szemantikai konvenciók szerinti OpenTelemetria-adatokat bocsát ki az Application Insightsban, a nyomkövetési kiértékelés az Foundry-ügynökök számára elérhető kiértékelőkkel értékelheti az interakciókat.

A nyomkövetés kiértékelése két módot támogat:

  • Nyomkövetési azonosítók alapján – Adott ügynök-interakciók kiértékelése az Application Insights értékeinek megadásával operation_Id .
  • Ügynökszűrővel – Egy adott ügynök legutóbbi nyomkövetéseinek automatikus felderítése és kiértékelése anélkül, hogy manuálisan gyűjtenek nyomkövetési azonosítókat.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket. Ez a forgatókönyv egy Application Insights-erőforrást is igényel, amely az Foundry-projekthez csatlakozik.

Intelligens mintavételezés

A nyomkövetési értékelés támogatja az intelligens mintavételezést, amely a nyomkövetések egy reprezentatív részhalmazát választja ki kiértékeléshez ahelyett, hogy minden rögzített nyomkövetést kiértékel. A funkció engedélyezéséhez kapcsolja be az Intelligens mintavételezés kapcsolót az Foundry portálon a nyomkövetés-kiértékelési futtatás konfigurálásakor. Az intelligens mintavételezés csökkenti a kiértékelési költségeket, miközben megőrzi a nyomkövetési sokféleséget – így biztosítva, hogy a peremes esetek, a hibavonalak és a változatos beszélgetési minták szerepeljen a kiértékelt készletben.

Az intelligens mintavételezés működése

A mintavételezési algoritmus a MinHash legtávolabbi sokféleségi megközelítését használja, amely több fázisban fut:

  1. Pontos ismétlődésmentesítés - Eltávolítja az ismétlődő nyomokat a halmazból.
  2. Szigorú szűrők – Eltávolítja a hibás munkameneteket, a csonkolt nyomkövetéseket és a kiértékelésre nem alkalmas hibás eszközhívásokat.
  3. Aggregáció – A nyomkövetési szintű jeleket egységes ábrázolásba egyesíti.
  4. MinHash legtávolabbi kijelölés – Kiszámítja a felhasználói szöveg területileg érzékeny kivonatait (MinHash-aláírásokat) a nyomkövetések közötti hasonlóság becsléséhez, majd iteratív módon kiválasztja a fennmaradó készlet legkülönbözőbb nyomkövetését. Minden egymást követő kiválasztás a lehető legnagyobb távolságot biztosítja az összes korábban kiválasztott nyomvonaltól.

Ez a megközelítés jelentősen nagyobb lexikális sokféleséget és szélesebb szókincs-lefedettséget eredményez a véletlenszerű mintavételezéshez képest, ami azt jelenti, hogy a kiértékelt készlet jobban megfelel az ügynök-interakciók teljes körének , beleértve a ritka, kemény és új eseteket, amelyeket a véletlenszerű mintavételezés általában kihagy.

Az intelligens mintavételezés különösen hatékony a következő célokra:

  • Értékelés és teljesítménymutatók – Maximalizálja a bemeneti eloszlás lefedettségét, így az értékelési pontszámok a valós sokszínűséget tükrözik.
  • Értékelési szempontrendszer létrehozása - Célzottabb és jobban alkalmazható értékelési szempontrendszereket hoz létre a változatos beszélgetési minták bemutatásával.
  • Az adathalmazok finomhangolása – Olyan nyomkövetéseket választ ki, amelyek segítenek a modellek hatékonyabb megismerésében.

Az algoritmus teljes egészében helyi számításon fut extra API-hívások nélkül, így nem jár többletmodell-következtetési költségekkel a kiértékelésen túl.

Intelligens mintavételezési példa

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

Nyomkövetési adatokra vonatkozó követelmények

A nyomkövetéses kiértékeléshez az ügynöknek olyan spaneket kell létrehoznia, amelyek követik a generatív MI-re vonatkozó OpenTelemetry szemantikai konvenciókat. A kiértékelési szolgáltatás beolvassa invoke_agent a Application Insights-ből a részleteket, és kinyeri a beszélgetési adatokat az attribútumaikból.

A rendszer a következő span attribútumokat használja:

Attribútum Szükséges Leírás
gen_ai.operation.name Igen Kell egyenlőnek "invoke_agent" lennie. A szolgáltatás figyelmen kívül hagyja az összes többi időtartamot.
gen_ai.agent.id Ügynökszűrő mód esetén Egyedi ügynökazonosító (formátum: agent-name:version).
gen_ai.agent.name Ügynökszűrő mód esetén Ember által olvasható ügynök neve.
gen_ai.input.messages Kiértékelők lekérdezési bemenetei A GenAI szemantikai konvenciók üzenetformátumát követő bemeneti üzenetek JSON-tömbje. Az user vagy system szerepkörrel rendelkező üzenetek a query-hez rendelődnek; az assistant vagy tool szerepkörrel rendelkező üzenetek a response-höz rendelődnek.
gen_ai.output.messages Kiértékelők lekérdezési bemenetei Modell által létrehozott kimeneti üzenetek JSON-tömbje. Az összes kimeneti üzenet megfelel a response-nek. Ha a kimenet a type: tool_call vagy a type: tool_result elemet is tartalmazza, az a tool_calls elemnek felel meg.
gen_ai.tool.definitions Választható Az ügynök számára elérhető eszközséma JSON-tömbje. Ha nem jelenik meg, a szolgáltatás eszközdefiníciókat próbál kikövetkeztetni az eszközhívási üzenetekből, de a következtetett sémák hiányosak lehetnek.
gen_ai.conversation.id Választható Beszélgetésazonosító, továbbítva a kiértékelési eredmények korrelációjához.

Megjegyzés

Ha gen_ai.input.messages és gen_ai.output.messages üresek vagy hiányoznak, a minőségértékelők (koherencia, folyékonyság, relevancia, szándékfeloldás) score=None értéket adnak vissza. A biztonsági értékelők (erőszak, önkárosítás, szexuális, gyűlölet/tisztességtelenség) még mindig képesek részleges adatokkal rendelkező pontszámokat létrehozni, de nem feltétlenül hoznak érdemi eredményeket.

A Azure AI-ügynökkiszolgáló SDK-val létrehozott Python ügynökök esetében adja hozzá a [tracing] extra elemet az automatikus hatótáv-kibocsátás engedélyezéséhez:

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

A nyomkövetési értékelés előfeltételei

Az általános előfeltételek mellett a nyomkövetési értékeléshez a következőre van szükség:

  • Az Foundry-projekthez csatlakoztatott Application Insights-erőforrás . Lásd: Kövesse nyomon a Microsoft Foundry-ban.
  • A projekt felügyelt identitásának rendelkeznie kell a Log Analytics Olvasó szerepkörével az Application Insights-erőforráson és a csatolt Log Analytics-munkaterületen.
  • A azure-monitor-query Python csomag (csak akkor szükséges, ha manuálisan gyűjt nyomkövetési azonosítókat).
pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Állítsa be a következő környezeti változókat:

  • APPINSIGHTS_RESOURCE_ID – Az Application Insights-erőforrás azonosítója (például /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — A nyomkövetési integráció (gen_ai.agent.id attribútum) által kibocsátott ügynökazonosító, amely a nyomkövetések szűrésére szolgál. Formátum: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Nem kötelező) A nyomkövetések lekérdezése során visszatekintendő órák száma. Alapértelmezettként .1

Opció A: Kiértékelés ügynök szűrő alapján

A legegyszerűbb módszer, ha lehetővé teszi, hogy a szolgáltatás automatikusan felderítse és értékelje az adott ügynök legutóbbi nyomkövetéseit. Nincs szükség manuális nyomkövetési azonosító-gyűjteményre.

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

A szolgáltatás szűr invoke_agent az attribútum alapján, mintákat vesz legfeljebb gen_ai.agent.id egyedi nyomkövetési azonosítóból, és kiértékeli az összes tartományt ezekből a nyomkövetésekből.

B. lehetőség: Kiértékelés nyomkövetési azonosítók alapján

További szabályozás érdekében gyűjtsön konkrét nyomkövetési azonosítókat az Application Insightsból, és értékelje ki őket. Ez a módszer akkor hasznos, ha válogatott interakciókat szeretne kiértékelni, például a riasztások által megjelölt nyomkövetéseket, vagy minőségi felülvizsgálatra mintát szeretne venni.

Nyomkövetési azonosítók gyűjtése az Application Insightsból

Az Application Insights operation_Id lekérdezése az ügynök nyomkövetési értékeihez. Mindegyik operation_Id egy teljes ügynök-interakciót jelöl:

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

Kiértékelés és futtatás nyomkövetési azonosítókkal

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

Kiértékelők és adatleképezések beállítása

A nyomkövetések kiértékelésekor a szolgáltatás automatikusan kinyeri a beszélgetési adatokat az OpenTelemetry span attribútumaiból. Használja ezeket a mezőneveket közvetlenül a data_mapping-ban (anélkül, hogy a item. vagy a sample. előtagokat használná más forgatókönyvek esetén):

Változó Forrásattribútum Leírás
{{item.query}} gen_ai.input.messages (felhasználói és rendszer szerepkörök) A nyomkövetésből kinyert felhasználói lekérdezés.
{{item.response}} gen_ai.input.messages (asszisztensi/eszközszerepkörök) + gen_ai.output.messages Az ügynök válasza a nyomkövetésből származik.
{{item.tool_definitions}} gen_ai.tool.definitions Az ügynök számára elérhető eszközséma. Csak az eszközhöz kapcsolódó kiértékelők számára szükséges.
{{item.tool_calls}} Kinyerve a segédüzenetekből gen_ai.input.messages / gen_ai.output.messages Az ügynök által az interakció során indított eszközhívások. Az eszközértékelők használják. Csak az eszközhöz kapcsolódó kiértékelők számára szükséges. 
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,
        },
    },
]

A teljes futtatható példáért lásd sample_evaluations_builtin_with_traces.py a GitHub. A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Szintetikus adatértékelés (előzetes verzió)

Az adatforrás típusával azure_ai_synthetic_data_gen_preview szintetikus teszt lekérdezéseket hozhat létre, elküldheti őket egy üzembe helyezett modellnek vagy Foundry-ügynöknek, és kiértékelheti a válaszokat. Ezt a forgatókönyvet akkor használja, ha nincs tesztadatkészlete. A szolgáltatás lekérdezéseket hoz létre az Ön által megadott kérés (és/vagy az ügynök utasításai alapján), futtatja őket a célon, és kiértékeli a válaszokat.

Tipp

Mielőtt hozzákezdene, végezze el az első lépéseket.

A szintetikus adatértékelés működése

  1. A szolgáltatás szintetikus lekérdezéseket hoz létre az Ön prompt és a beállított kezdőadat fájlok alapján.
  2. A rendszer minden lekérdezést a megadott célnak (modellnek vagy ügynöknek) küld válasz létrehozásához.
  3. A kiértékelők a létrehozott lekérdezéssel és válaszsal pontozza az egyes válaszokat.
  4. A létrehozott lekérdezések adathalmazként vannak tárolva a projektben újrafelhasználásra.

Paraméterek

Paraméter Szükséges Leírás
samples_count Igen A létrehozandó szintetikus teszt lekérdezések maximális száma.
model_deployment_name Igen Modelltelepítés szintetikus lekérdezések létrehozásához. Csak a Responses API-képességgel rendelkező modellek támogatottak. A rendelkezésre állásról a Responses API-régió rendelkezésre állása című témakörben olvashat.
prompt Nem A létrehozandó lekérdezések típusát leíró utasítások. Nem kötelező, ha az ügynök célhelye konfigurálva van.
output_dataset_name Nem Annak a kimeneti adatkészletnek a neve, amelyben a létrehozott lekérdezések tárolódnak. Ha nem ad meg nevet, a szolgáltatás automatikusan létrehoz egyet.
sources Nem A generált lekérdezések relevanciájának javítása érdekében a magadattárfájlokat fájlazonosító alapján használjuk. Jelenleg csak egy fájl támogatott.

Kiértékelők és adatleképezések beállítása

A szintetikus adatgenerátor lekérdezéseket hoz létre a {{item.query}} mezőben. A cél a következőben elérhető válaszokat generálja {{sample.output_text}}: . Képezheti le ezeket a mezőket a kiértékelőkhöz:

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

Kiértékelés és futtatás létrehozása

Modellcél

Szintetikus lekérdezések létrehozása és modell kiértékelése:

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

Igény szerint hozzáadhat egy rendszerkérést a célmodell viselkedésének alakításához. A input_messages szintetikus adatok létrehozásával való használatakor csak system role-üzeneteket foglaljon bele – a szolgáltatás automatikusan felhasználói üzenetekként adja meg a létrehozott lekérdezéseket.

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

Ügynök célpont

Szintetikus lekérdezések létrehozása és egy Foundry-ügynök kiértékelése:

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

A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört. A válasz tartalmaz egy output_dataset_id tulajdonságot, amely tartalmazza a létrehozott adathalmaz azonosítóját, amellyel lekérheti vagy újra felhasználhatja a szintetikus adatokat.

Beszélgetésszintű kiértékelés (előzetes verzió)

Értékelje ki a teljes beszélgetéseket, hogy értékelje az ügynök minőségét a teljes felhasználói interakcióban – nem csak az egyes válaszokban. A beszélgetési szintű értékeléssel azonosíthatja a minőségi problémákat, például a hiányos feladatmegoldást, a felhasználói frusztrációt és az eszközhívási regressziókat, amelyekről a fordulószintű értékelés hiányzik.

Vegyünk például egy ügyfélszolgálati munkatársat, aki esetében a felhasználó több váltás során egyre frusztráltabb lesz:

1. kör — Felhasználó: "Vissza kell állítanom a jelszavamat." Ügyintéző: "Megtaláltam a fiókját. Elküldöm az alaphelyzetbe állítási hivatkozást."

2. forduló — Felhasználó: "Nem kaptam meg az e-mailt." Ügynök: "Újra elküldtem a linket." Kérjük, ellenőrizze a levélszemét."

Turn 3 – Felhasználó: "Még mindig semmi. Vissza tudja állítani közvetlenül?" Ügynök: "Elküldtem egy másik visszaállítási hivatkozást."

A fordulószintű értékelő csak az utolsó választ pontozza – amely udvarias és intézkedést tesz –, ezért magas pontszámot kap. Egy beszélgetésszintű értékelő, amely a teljes beszélgetés során az ügyfél-elégedettséget értékeli, jelzi, hogy a munkatárs háromszor megismételte ugyanazt a sikertelen lépést anélkül, hogy alternatívát próbált volna, így a felhasználó problémája megoldatlan maradt.

A beszélgetési szintű értékelés többféleképpen különbözik a fordulószintű értékeléstől:

Aspect Fordulószintű Beszélgetési szint
Scope Egyedi lekérdezés-válasz párok Beszélgetések befejezése több cserével
Metrics Válaszonkénti minőség és biztonság Beszélgetési szintű eredmények és felhasználói elégedettség
Adatformátum JSONL query és response mezőkkel JSONL a teljes beszélgetést tartalmazó tömbbel messages
Használati eset Az egyes modellválaszok tesztelése A teljes körű ügynökélmény tesztelése

A beszélgetési szintű értékelés négy adatforrás-beállítást támogat:

Option Mikor érdemes használni? Adatforrás típusa
Adatkészletből vagy beágyazottból Vannak helyi beszélgetési nyomai vagy tesztadatai jsonl file_id-val vagy file_content-vel
Beszélgetésazonosító szerint Konkrét beszélgetéseket szeretne kiértékelni az App Insightsból azure_ai_trace_data_source_preview és trace_source
Ügynökszűrő alapján mintavételezéssel Szeretné felmérni az ügynök általános minőségét a mintában szereplő éles forgalomban azure_ai_trace_data_source_preview és trace_source
Szimulált beszélgetések Szintetikus tesztbeszélgetéseket szeretne létrehozni azure_ai_target_completions és conversation_gen_preview

Kiértékelési szint kiválasztása

A evaluation_level futtatás paramétere határozza meg, hogy az értékelők egyéni fordulókat vagy teljes beszélgetéseket értékelnek-e:

Value Viselkedés
"turn" Az értékelők egymástól függetlenül értékelik az egyes fordulókat.
"conversation" Az értékelők a teljes beszélgetést egészként értékelik.
(kihagyva) Alapértelmezettként ."turn"

Fontos

Kiértékelő kompatibilitása: Minden kiértékelő támogatja a meghatározott értékelési szinteket. Ellenőrizze a kiértékelő supported_evaluation_levels mezőjét a kiértékelői katalógusban.

  • A csak fordulónkénti kiértékelők (például fluency, relevance) nem használhatók együtt a(z) evaluation_level="conversation" elemmel.
  • Jelenleg az összes beszélgetési szintű kiértékelő támogatja mind "turn" a "conversation" szinteket.

Gyakori hibák

Hiba A probléma oka Megoldás
Inkompatibilis kiértékelési szint A(z) evaluation_level="conversation" használata csak fordulónkénti kiértékelővel Távolítsa el a csak fordulós kiértékelőt, vagy módosítsa a következőre: evaluation_level="turn"

Beszélgetési adatok előkészítése

Hozzon létre egy JSONL-fájlt, amelyben minden sor egy teljes beszélgetést tartalmaz a messages mezőben. Minden üzenetnek tartalmaznia kell role-t (felhasználó, asszisztens vagy rendszer) és content-et. Egy teljes példát az SDK konversation-kiértékelési mintáiban talál:

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

Eszközdefiníciókat és eszközhívásokat is megadhat, ha az ügynök eszközöket használ:

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

Az adatséma és a kiértékelők meghatározása

Adja meg a beszélgetési adatok sémáját, az "üzeneteket", és válassza ki a beszélgetési szintű kiértékeléshez tervezett kiértékelőket. A beszélgetési szintű kiértékelők az egyes fordulatok helyett a teljes interakciót értékelik.

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

Kiértékelés és futtatás létrehozása

Előkészítés: töltse le a sample_data_multiturn_conversations.jsonl fájlt.

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

A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Beszélgetések kiértékelése nyomkövetési azonosító alapján

Értékelje ki az Application Insights adott beszélgetéseit a beszélgetés azonosítóinak megadásával. Ezzel az opcióval feltárhatja a problémák kiváltó okát, vagy ellenőrizheti a javításokat bizonyos interakciókon. Megvizsgálhat például egy riasztás által megjelölt beszélgetést, vagy ellenőrizheti egy ismert probléma kijavítását.

Hol találhatók a beszélgetési azonosítók?

Beszélgetési azonosítók keresése a következő helyen:

  • Application Insights nyomkövetési naplók felhasználói felülete – Keresse meg az érdekes nyomkövetéseket, és keresse meg a conversation_id mezőt a nyomkövetés részletei között.
  • Az alkalmazás naplókimenete — Ha az ügynökválaszok létrehozásakor kifejezetten beállítja a(z) conversation_id elemet, keresse ki a naplókból.
  • OpenTelemetry trace context — A conversation_id a traceparent fejlécből is származhat, ha az ügynöke szabványos nyomkövetési kontextusterjesztést használ.

Megjegyzés

Az eszközdefiníciók automatikusan lekérhetők a nyomkövetésekből, vagy lekérdezhetők az ügynökregisztrációs adatbázisból. A kérésben nem kell megadnia őket.

A beszélgetésazonosító-keresés paraméterei

Paraméter Szükséges Leírás
conversation_ids Igen Kiértékelendő beszélgetésazonosítók tömbje.
lookback_hours Nem Az ettől számított visszakeresés órákban: end_time Alapértelmezés szerint hét nap (168 óra).
end_time Nem A keresési ablak vége (ISO 8601 formátum). Alapértelmezett érték az aktuális időpontra. 
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"},
    )

Megjegyzés

  • Az Application Insights adatbetöltése késést okozhat a nyomkövetések létrehozása és a kiértékeléshez rendelkezésre álló adatok között. Ha a lekérdezés nem talál nyomokat, várjon néhány percet, és próbálkozzon újra.
  • A visszatekintés maximális ideje 7 nap (168 óra). A korábbi nyomkövetési adatok eléréséhez használja a start_time és end_time elemeket az App Insights adatmegőrzési korlátain belül.

Mintabeszélgetések kiértékelése ügynökszűrő alapján

Értékelje ki az Application Insightsból származó beszélgetések mintáit az ügynök nevének szűrésével. Ezzel a lehetőséggel értékelheti az ügynök általános minőségét a teljes éles forgalomban. Futtathat például rendszeres minőségértékeléseket, vagy figyelheti a termelés minőségromlását.

A szűréshez megadott ügynök egy többügynökből álló beszélgetés része lehet. A szűrő megegyezik minden olyan beszélgetésben, amelyben az ügynök részt vett.

Megjegyzés

Az eszközdefiníciók automatikusan lekérhetők a nyomkövetésekből, vagy lekérdezhetők az ügynökregisztrációs adatbázisból. A kérésben nem kell megadnia őket.

Az ügynök azonosítómezői

Adja meg a szűrni kívánt ügynököt az alábbi formátumok egyikével:

Format Example Leírás
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Két külön mező. Ha agent_version nincs megadva, használja a legújabb verziót.
agent_id "agent_id": "my-agent:1" Egyetlen karakterlánc "name:version" formátumban.

Szűrési stratégiák

Strategy Leírás
random_sampling (Alapértelmezett) Egyenletes eloszlású véletlenszerű minta legfeljebb max_traces beszélgetésből.
smart_filtering A szolgáltatás által kezelt heurisztika, amely az „érdekes” nyomkövetések felé terel: olyan beszélgetések felé, amelyekben lehetséges problémák, szélső esetek vagy anomáliák fordulnak elő.

Paraméterek

Paraméter Szükséges Leírás
agent_name Igen Az ügynök neve, amely alapján szűrni szeretné a nyomkövetéseket.
agent_version Nem Az ügynök verziója. Ha nincs megadva, a legújabb verziót használja.
agent_id Nem Alternatíva a agent_name + agent_version. Egyetlen karakterlánc a következő formátumban: "name:version".
start_time Igen Az időablak kezdete (Unix epoch másodperc, UTC).
end_time Igen Az időablak vége (Unix epoch másodperc, UTC). Az adatbeviteli késleltetés elkerülése érdekében növelje meg +600 másodperccel.
max_traces Nem A mintavételre szolgáló beszélgetések maximális száma. Alapértelmezés szerint 1 000.
filter_strategy Nem "random_sampling" (alapértelmezett) vagy "smart_filtering" (szolgáltatás által kezelt heurisztika, amely az érdekes nyomokat részesíti előnyben).

Fontos

Az időablaknak (end_time - start_time) legalább 15 percnek (900 másodpercnek) kell lennie. Ez a követelmény azért létezik, mert a beszélgetésszintű lekérdezések minden peremhálózaton 5 perces inaktivitási puffert alkalmaznak a részleges beszélgetések elkerülése érdekében.

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

Megjegyzés

Az App Insights lekérdezési időkorlátja jelenleg legfeljebb 7 napra (168 órára) korlátozódik. Az App Insights megőrzési korlátain belül nem férhet hozzá a 7 napnál régebbi nyomkövetési adatokhoz anélkül, hogy kifejezetten megadná a(z) start_time és end_time értékeket.

A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Beszélgetési szimuláció

Szimulált beszélgetéseket hozhat létre a forgatókönyv-leírásokból, és kiértékeli őket a beszélgetés szintjén. Ezzel a forgatókönyvkel tesztelheti az ügynök viselkedését ellenőrzött helyzetekben az üzembe helyezés előtt. A szolgáltatás reális beszélgetéseket hoz létre a forgatókönyv leírásai alapján, majd kiértékeli őket.

Ez a megközelítés a következő esetekben hasznos:

  • Üzembe helyezés előtti tesztelés: Az ügynök viselkedésének ellenőrzése különböző helyzetekben, valós felhasználói forgalom nélkül.
  • Szélső esetek lefedése: Olyan tesztforgatókönyvek, amelyek természetes körülmények között ritkán fordulnak elő, de fontos, hogy megfelelően kezeljük őket.
  • Regressziós tesztelés: Győződjön meg arról, hogy az ügynökfrissítések nem csökkentik az ismert forgatókönyvek teljesítményét.
  • Skálázhatósági tesztelés: Számos beszélgetés gyors létrehozása az ügynök képességeinek stresszteszteléséhez.

A beszélgetésszimuláció működése

  1. Megadja a forgatókönyvek leírását tartalmazó adathalmazt – minden sor egy olyan helyzetet ír le, amit a szimulált felhasználó megpróbál végrehajtani.
  2. A szolgáltatás egy szimulátormodell használatával játssza le a felhasználó szerepét, és a forgatókönyv alapján kommunikál az ügynökkel.
  3. Minden forgatókönyv egy vagy több teljes beszélgetést generál.
  4. A beszélgetésszintű kiértékelők értékelik a létrehozott beszélgetéseket.
  5. A projekt mind a beszélgetéseket, mind a kiértékelési eredményeket tárolja.

Forgatókönyvadatok előkészítése

Hozzon létre egy JSONL-fájlt, amelyben minden sor leírja a szimulált felhasználó forgatókönyvét. A sémához id, test_case_description és desired_num_turns szükséges. Adjon meg részleteket a felhasználó céljáról, környezetéről és a korlátozásokról. Egy teljes példáért lásd az SDK-ban található beszélgetéskiértékelési mintákat.


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

Paraméterek

Paraméter Szükséges Leírás
num_conversations Nem Forgatókönyvenként létrehozandó beszélgetések száma. Az alapértelmezett érték 5, a kiszolgálóoldali felső korlát pedig szintén 5.
max_turns Nem Beszélgetésenként a fordulók (cserék) maximális száma. Alapértelmezés szerint 10, kiszolgálóoldali korlát 20.
model Igen Modell üzembe helyezése a felhasználó szimulálásához. Például: gpt-4.1.
sampling_params Nem A szimulátormodell mintavételezési paraméterei, beleértve a következőket: temperature, top_p és max_completion_tokens.
data_mapping Nem Leképezi a mezőket a forgatókönyv JSONL-fájljából a szimulációs paraméterekre. Gyakori leképezések: test_case_description, id. desired_num_turns

Kiértékelők definiálása

Válassza ki a beszélgetésszintű értékeléshez tervezett kiértékelőket. A szimulált beszélgetések automatikusan hozzá vannak rendelve az értékelőkhöz.

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

Kiértékelés és futtatás létrehozása

Előkészítés: töltse le a sample_data_simulation_scenarios.jsonl fájlt.

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

A befejezés ellenőrzéséhez és az eredmények értelmezéséhez tekintse meg a Eredmények lekérése című témakört.

Eredmények lekérése

A kiértékelési futtatás befejezése után kérje le a pontozott eredményeket, és tekintse át azokat a portálon vagy programozottan.

Szavazás az eredményekről

A kiértékelési folyamatok aszinkron módon futnak. Kérdezze le a futási állapotot az elkészülésig, majd szerezze be az eredményeket:

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

Eredmények értelmezése

Egyetlen adat példában az összes kiértékelő a következő sémát adja ki:

  • Címke: bináris "pass" vagy "fail" címke, hasonló az egységteszt kimenetéhez. Ezzel az eredménnyel megkönnyítheti a kiértékelők közötti összehasonlítást.
  • Pontszám: az egyes kiértékelők természetes skálájából származó pontszám. Egyes értékelők finomított rubricát használnak, pontozást 5 pontos skálán (minőségértékelők) vagy 7 pontos skálán (tartalombiztonsági értékelők). Mások, például a szöveges hasonlóság-kiértékelők, F1 pontszámokat használnak, amelyek 0 és 1 közötti lebegőpontosak. Minden nem bináris „pontszámot” a „küszöbérték” alapján „megfelelt” vagy „nem felelt meg” értékre alakítanak a „címke” mezőben.
  • Küszöbérték: a nem bináris pontszámok egy alapértelmezett küszöbérték alapján „megfelelt” vagy „nem felelt meg” értékre lesznek binarizálva, amelyet a felhasználó felülírhat az SDK-ban.
  • Ok: Az érthetőség javítása érdekében minden LLM-bíró kiértékelő egy érvelési mezőt is ad ki, amely elmagyarázza, miért ad meg egy adott pontszámot.
  • Részletek: (nem kötelező) Egyes kiértékelők, például a tool_call_accuracy esetében előfordulhatnak "részletek" mezők vagy jelzők, amelyek további információkat tartalmaznak az alkalmazások hibakereséséhez.

Példakimenet (egyetlen elem)

{
  "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éldakimenet (összesítés)

Több adat példán (adathalmazon) végzett összesítés esetén a "pass" értékkel rendelkező példák átlagos aránya adja meg az adott adathalmaz átviteli sebességét.

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

Hibaelhárítás

Hosszú ideig futó feladat

Előfordulhat, hogy a kiértékelési feladat hosszabb ideig futó állapotban marad. Ez a feltétel általában akkor fordul elő, ha a Azure OpenAI-modell üzembe helyezése nem rendelkezik elegendő kapacitással, ami miatt a szolgáltatás újrapróbálkozásokat kezdeményez.

Felbontás:

  1. Az aktuális kiértékelési feladat megszakításához használja a(z) openai_client.evals.runs.cancel(run_id, eval_id=eval_id) elemet.
  2. Növelje a modellkapacitást a Azure portálon.
  3. Futtassa újra az értékelést.

Hitelesítési hibák

Ha hibaüzenetet 401 Unauthorized403 Forbidden kap, ellenőrizze, hogy:

  • Megfelelően DefaultAzureCredential van konfigurálva. Ha az Azure CLI-t használja, futtassa a(z) az login parancsot.
  • Az Ön fiókja a Foundry projektben a Foundry User szerepkörrel rendelkezik.
  • A projektvégpont URL-címe helyes, és tartalmazza a fiókokat és a projektneveket is.

Adatformátummal kapcsolatos hibák

Ha a kiértékelés séma- vagy adatleképezési hibával meghiúsul:

  • Ellenőrizze, hogy a JSONL-fájl egy érvényes JSON-objektummal rendelkezik-e soronként.
  • Győződjön meg arról, hogy a data_mapping mezőnevek pontosan egyeznek a JSONL-fájl mezőnevével (kis- és nagybetűk megkülönböztetése).
  • Ellenőrizze, hogy a item_schema tulajdonságok megfelelnek-e az adathalmaz mezőinek.

Sebességkorlátozási hibák

A bérlői, az előfizetési és a projektszint korlátozza az értékelési futtatások létrehozását. Ha egy 429 Too Many Requests választ kap:

  • Ellenőrizze a retry-after fejlécet a válaszban az ajánlott várakozási időre vonatkozóan.
  • A sebességkorlát részleteiért tekintse át a válasz törzsét.
  • A sikertelen kérések újrapróbálkozásakor exponenciális visszalépést használjon.

Ha egy kiértékelési feladat végrehajtása során egy 429 hiba jelentkezik:

  • Csökkentse a kiértékelési adatkészlet méretét, vagy ossza fel kisebb kötegekre.
  • Növelje a modell üzembe helyezésére vonatkozó tokenek percenkénti (TPM) kvótáját az Azure portálon.

Ügynökértékelő eszköz hibái

Ha egy ügynök kiértékelője hibát ad vissza a nem támogatott eszközök esetében:

  • Ellenőrizze az ügynökértékelők támogatott eszközeit .
  • Kerülő megoldásként csomagolja be a nem támogatott eszközöket felhasználó által definiált függvényeszközökként, hogy a kiértékelő értékelhesse őket.

Kapcsolódó tartalom

  • Last updated on