Delen via

Evaluaties uitvoeren vanuit de SDK

Belangrijk

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor meer informatie.

In dit artikel leert u hoe u evaluaties uitvoert in de cloud (preview) voor predeploymenttests op een testgegevensset.

Gebruik batchevaluaties voor de meeste scenario's, met name bij het testen op schaal, het integreren van evaluaties in CI/CD-pijplijnen (continue integratie en continue levering) of het uitvoeren van predeploymenttests. Het uitvoeren van evaluaties in de cloud elimineert de noodzaak om de lokale rekeninfrastructuur te beheren en biedt ondersteuning voor grootschalige, geautomatiseerde testwerkstromen. U kunt ook evaluaties plannen om op terugkerende basis uit te voeren, of continue evaluatie instellen om automatisch reacties van een steekproefagent in productie te evalueren.

Batch-evaluatieresultaten worden opgeslagen in uw Foundry-project. U kunt de resultaten bekijken in de portal, ze ophalen via de SDK of ze doorsturen naar Application Insights als er verbinding is. Batch-evaluatie ondersteunt alle door Microsoft samengestelde ingebouwde evaluators en uw eigen aangepaste evaluators. Evaluators worden beheerd in de evaluatorcatalogus met hetzelfde projectbereik, op rollen gebaseerd toegangsbeheer.

Aanbeveling

Zie de Python SDK-evaluatievoorbeelden op GitHub voor volledige uitvoerbare voorbeelden.

Wanneer u de Foundry-SDK gebruikt, worden de evaluatieresultaten in uw Foundry-project voor een betere waarneembaarheid in logboeken opgeslagen. Deze functie ondersteunt alle door Microsoft samengestelde ingebouwde evaluators en uw eigen aangepaste evaluators. Uw evaluators kunnen zich in de evaluatorbibliotheek bevinden en hetzelfde projectbereik, op rollen gebaseerd toegangsbeheer hebben.

Hoe batch-evaluatie werkt

Als u een batch-evaluatie wilt uitvoeren, maakt u een evaluatiedefinitie met uw gegevensschema en testcriteria (evaluators) en maakt u vervolgens een evaluatieuitvoering. De uitvoering voert elke evaluator uit op uw gegevens en retourneert gescoorde resultaten die u kunt opvragen voor voltooiing.

Batch-evaluatie ondersteunt de volgende scenario's:

Scenario Wanneer te gebruiken Gegevensbrontype Doelwit
Evaluatie van gegevensset Evalueer vooraf berekende antwoorden in een JSONL-bestand. jsonl —
Evaluatie van modeldoel Geef query's op en genereer antwoorden van een model tijdens runtime voor evaluatie. azure_ai_target_completions azure_ai_model
Doelevaluatie van agent Geef query's op en genereer antwoorden van een Foundry-agent tijdens runtime voor evaluatie. azure_ai_target_completions azure_ai_agent
Evaluatie van reactie van agent Antwoorden van Foundry-agents ophalen en evalueren op basis van antwoord-id's. azure_ai_responses —
Synthetische gegevensevaluatie (preview) Genereer synthetische testquery's, verzend ze naar een model of agent en evalueer de antwoorden. azure_ai_synthetic_data_gen_preview azure_ai_model of azure_ai_agent
Evaluatie van rood team Voer geautomatiseerde adversarial testen uit tegen een model of agent. azure_ai_red_team azure_ai_model of azure_ai_agent

Voor de meeste scenario's zijn invoergegevens vereist. U kunt gegevens op twee manieren opgeven:

Brontype Description
file_id Verwijs naar een geüploade gegevensset op basis van ID.
file_content Geef gegevens inline op in de aanvraag.

Voor elke evaluatie is een data_source_config evaluatie vereist die aangeeft welke velden in uw gegevens moeten worden verwacht:

  • custom — U definieert een item_schema met uw veldnamen en -typen. Ingesteld include_sample_schema op true wanneer u een doel gebruikt, zodat evaluators kunnen verwijzen naar gegenereerde antwoorden.
  • azure_ai_source — Het schema wordt afgeleid van de service. Ingesteld "scenario" op "responses" voor evaluatie van agentreacties, "synthetic_data_gen_preview" voor synthetische gegevensevaluatie (preview) of "red_team" voor rode koppeling.

Voor elk scenario zijn evaluators vereist die uw testcriteria definiëren. Zie ingebouwde evaluators voor hulp bij het selecteren van evaluators.

Vereiste voorwaarden

  • Een Foundry-project.
  • Een Azure OpenAI-implementatie met een GPT-model dat ondersteuning biedt voor voltooiing van chats (bijvoorbeeld gpt-5-mini).
  • Azure AI-gebruiker rol in het Foundry-project.
  • U kunt eventueel uw eigen opslagaccount gebruiken om evaluaties uit te voeren.

Opmerking

Sommige evaluatiefuncties hebben regionale beperkingen. Zie ondersteunde regio's voor meer informatie.

Get started

Installeer de SDK en stel uw client in:

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

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

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

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

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

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

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

Invoergegevens voorbereiden

Voor de meeste evaluatiescenario's zijn invoergegevens vereist. U kunt gegevens op twee manieren opgeven:

Upload een JSONL-bestand om een versiegegevensset te maken in uw Foundry-project. Gegevenssets ondersteunen versiebeheer en hergebruik in meerdere evaluatieuitvoeringen. Gebruik deze methode voor productietests en CI/CD-werkstromen.

Bereid een JSONL-bestand voor met één JSON-object per regel met de velden die uw evaluators nodig hebben:

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

# 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

Gegevens inline opgeven

Voor snelle experimenten met kleine testsets geeft u gegevens rechtstreeks in de evaluatieaanvraag op met behulp van 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",
            }
        ),
    ],
)

Gebruik source als het "source" veld in de configuratie van uw gegevensbron bij het maken van een run. De volgende scenariosecties gebruiken standaard file_id.

Evaluatie van gegevensset

Evalueer vooraf berekende antwoorden in een JSONL-bestand met behulp van het jsonl gegevensbrontype. Dit scenario is handig wanneer u al modeluitvoer hebt en de kwaliteit ervan wilt beoordelen.

Aanbeveling

Voordat u begint, voltooit u Aan de slag en bereidt u invoergegevens voor.

Het gegevensschema en de evaluators definiëren

Geef het schema op dat overeenkomt met uw JSONL-velden en selecteer de evaluators (testcriteria) die moeten worden uitgevoerd. Gebruik de data_mapping parameter om velden van uw invoergegevens te verbinden met parameters voor evaluator met {{item.field}} syntaxis. Neem altijd de vereiste invoervelden op met data_mapping voor elke evaluator. Uw veldnamen moeten overeenkomen met die in uw JSONL-bestand — bijvoorbeeld, als uw gegevens "question" in plaats van "query" bevatten, gebruik dan "{{item.question}}" in de mapping. Zie ingebouwde evaluator voor de vereiste parameters per evaluator.

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

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

Evaluatie maken en uitvoeren

Maak de evaluatie en start vervolgens een uitvoering op basis van uw geüploade gegevensset. De uitvoering voert elke evaluator uit op elke rij in de gegevensset.

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

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

Zie sample_evaluations_builtin_with_dataset_id.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Zie Resultaten ophalen om de voltooiing te controleren en de resultaten te interpreteren.

Evaluatie van modeldoel

Verzend query's tijdens runtime naar een geïmplementeerd model en evalueer de antwoorden met behulp van het azure_ai_target_completions gegevensbrontype met een azure_ai_model doel. Uw invoergegevens bevatten query's; het model genereert antwoorden die vervolgens worden geëvalueerd.

Aanbeveling

Voordat u begint, voltooit u Aan de slag en bereidt u invoergegevens voor.

De berichtsjabloon en het doel definiëren

De input_messages sjabloon bepaalt hoe query's naar het model worden verzonden. Gebruik {{item.query}} dit om te verwijzen naar velden uit uw invoergegevens. Geef het model op voor het evalueren en optionele steekproefparameters:

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

Evaluators en gegevenskoppelingen instellen

Wanneer het model tijdens runtime antwoorden genereert, gebruikt u {{sample.output_text}} in data_mapping om te verwijzen naar de uitvoer van het model. Gebruik {{item.field}} dit om te verwijzen naar velden uit uw invoergegevens.

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

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

Evaluatie maken en uitvoeren

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

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

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

Zie sample_model_evaluation.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Zie Resultaten ophalen om de voltooiing te controleren en de resultaten te interpreteren.

Aanbeveling

Als u een andere evaluatieuitvoering wilt toevoegen, voert u dezelfde evaluatie opnieuw uit met dezelfde evaluatiegroep. Elke uitvoering maakt een nieuwe uitvoering onder dezelfde groep, waarmee u resultaten kunt vergelijken >met uitvoeringen nadat u zaken zoals het model, de prompt of de gegevensset hebt gewijzigd, zonder een nieuwe evaluatie te maken of een andere API te gebruiken.

Bekijk het voorbeeld dat dezelfde evaluatiegroep opnieuw gebruikt om meerdere uitvoeringen te maken ter vergelijking.

Doelevaluatie van agent

Verzend query's tijdens runtime naar een Foundry-agent en evalueer de antwoorden met behulp van het azure_ai_target_completions gegevensbrontype met een azure_ai_agent doel.

Aanbeveling

Voordat u begint, voltooit u Aan de slag en bereidt u invoergegevens voor.

De berichtsjabloon en het doel definiëren

De input_messages sjabloon bepaalt hoe query's naar de agent worden verzonden. Gebruik {{item.query}} dit om te verwijzen naar velden uit uw invoergegevens. Specificeer de agent die op naam moet worden geëvalueerd.

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

Evaluators en gegevenskoppelingen instellen

Wanneer de agent tijdens runtime antwoorden genereert, gebruikt {{sample.*}} variabelen in data_mapping om te refereren aan de uitvoer van de agent.

Variable Description Te gebruiken voor
{{sample.output_text}} Het platte tekst antwoord van de agent. Evaluators die een tekenreeksantwoord verwachten (bijvoorbeeld coherence, violence).
{{sample.output_items}} De gestructureerde JSON-uitvoer van de agent, inclusief hulpprogramma-aanroepen. Evaluators die volledige interactiecontext nodig hebben (bijvoorbeeld task_adherence).
{{item.field}} Een veld van uw invoergegevens. Invoervelden zoals query of ground_truth.

Aanbeveling

Het query veld kan gestructureerde JSON bevatten, inclusief systeemberichten en gespreksgeschiedenis. Sommige agent evaluators, zoals task_adherence deze context gebruiken voor nauwkeuriger scoren. Zie agent evaluators voor meer informatie over queryopmaak.

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

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

Evaluatie maken en uitvoeren

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

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

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

Zie sample_agent_evaluation.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Zie Resultaten ophalen om de voltooiing te controleren en de resultaten te interpreteren.

Aanbeveling

Als u een andere evaluatieuitvoering wilt toevoegen, voert u dezelfde evaluatie opnieuw uit met dezelfde evaluatiegroep. Elke uitvoering maakt een nieuwe uitvoering onder dezelfde groep, waarmee u resultaten kunt vergelijken >met uitvoeringen nadat u zaken zoals het model, de prompt of de gegevensset hebt gewijzigd, zonder een nieuwe evaluatie te maken of een andere API te gebruiken.

Bekijk het voorbeeld dat dezelfde evaluatiegroep opnieuw gebruikt om meerdere uitvoeringen te maken ter vergelijking.

Evaluatie van reactie van agent

Antwoorden van Foundry-agents ophalen en evalueren op basis van antwoord-id's met behulp van het azure_ai_responses gegevensbrontype. Gebruik dit scenario om specifieke agentinteracties te evalueren nadat deze zich hebben voorgedaan.

Aanbeveling

Voordat u begint, voltooit u Aan de slag.

Een antwoord-id is een unieke id die wordt geretourneerd telkens wanneer een Foundry-agent een antwoord genereert. U kunt antwoord-id's verzamelen van agentinteracties met behulp van de Response-API of vanuit de traceringslogboeken van uw toepassing. Geef de id's inline op als bestandsinhoud of upload ze als een gegevensset (zie Invoergegevens voorbereiden).

Antwoord-id's verzamelen

Elke aanroep naar de Response-API retourneert een antwoordobject met een uniek id veld. Verzamel deze id's van de interacties van uw toepassing of genereer deze rechtstreeks:

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

U kunt ook antwoord-id's verzamelen van agentinteracties in de traceringslogboeken of bewakingspijplijn van uw toepassing. Elke antwoord-id identificeert een opgeslagen antwoord dat door de evaluatieservice kan worden opgehaald.

Evaluatie maken en uitvoeren

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

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

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

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

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

Zie sample_agent_response_evaluation.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Zie Resultaten ophalen om de voltooiing te controleren en de resultaten te interpreteren.

Aanbeveling

Als u een andere evaluatieuitvoering wilt toevoegen, voert u dezelfde evaluatie opnieuw uit met dezelfde evaluatiegroep. Elke uitvoering maakt een nieuwe uitvoering onder dezelfde groep, waarmee u resultaten kunt vergelijken >met uitvoeringen nadat u zaken zoals het model, de prompt of de gegevensset hebt gewijzigd, zonder een nieuwe evaluatie te maken of een andere API te gebruiken.

Bekijk het voorbeeld dat dezelfde evaluatiegroep opnieuw gebruikt om meerdere uitvoeringen te maken ter vergelijking.

Evaluatie van synthetische gegevens (voorvertoning)

Genereer synthetische testquery's, verzend ze naar een geïmplementeerd model of Foundry-agent en evalueer de antwoorden met behulp van het azure_ai_synthetic_data_gen_preview gegevensbrontype. Gebruik dit scenario wanneer u geen testgegevensset hebt: de service genereert query's op basis van een prompt die u opgeeft (en/of vanuit de instructies van de agent), voert deze uit op uw doel en evalueert de antwoorden.

Aanbeveling

Voordat u begint, voltooit u Aan de slag.

Hoe synthetische gegevensevaluatie werkt

  1. De service genereert synthetische query's op basis van uw prompt en optionele seed-gegevensbestanden.
  2. Elke query wordt verzonden naar het opgegeven doel (model of agent) om een antwoord te genereren.
  3. Evaluators beoordelen elk antwoord met behulp van de gegenereerde query en het antwoord.
  4. De gegenereerde query's worden opgeslagen als een gegevensset in uw project voor hergebruik.

Parameterwaarden

Kenmerk Verplicht Description
samples_count Ja Maximum aantal synthetische testquery's dat moet worden gegenereerd.
model_deployment_name Ja Modelimplementatie voor het genereren van synthetische query's. Alleen modellen met de mogelijkheid van de response-API worden ondersteund. Zie beschikbaarheid van de antwoorden-API-regio voor beschikbaarheid.
prompt Nee. Instructies voor het type query's dat moet worden gegenereerd. Optioneel wanneer het agentdoel instructies heeft geconfigureerd.
output_dataset_name Nee. Naam voor de uitvoergegevensset waarin gegenereerde query's worden opgeslagen. Als deze niet is opgegeven, genereert de service automatisch een naam.
sources Nee. Gegevensbestanden zaaien (op basis van bestands-ID) om de relevantie van gegenereerde query's te verbeteren. Op dit moment wordt slechts één bestand ondersteund.

Evaluators en gegevenskoppelingen instellen

De synthetische gegevensgenerator produceert query's in het {{item.query}} veld. Het doel genereert antwoorden die beschikbaar zijn in {{sample.output_text}}. Koppel deze velden aan uw evaluatoren:

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

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

Evaluatie maken en uitvoeren

Modeldoel

Synthetische query's genereren en een model evalueren:

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

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

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

U kunt eventueel een systeemprompt toevoegen om het gedrag van het doelmodel vorm te geven. Wanneer u input_messages gebruikt bij het genereren van synthetische data, neem dan alleen system rolberichten op — de service levert de gegenereerde query's automatisch als gebruikersberichten.

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

Doelstelling agent

Genereer synthetische query's en evalueer een Foundry-agent:

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

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

Zie Resultaten ophalen om de voltooiing te controleren en de resultaten te interpreteren. Het antwoord bevat een output_dataset_id eigenschap die de id van de gegenereerde gegevensset bevat, die u kunt gebruiken om de synthetische gegevens op te halen of opnieuw te gebruiken.

Resultaten verkrijgen

Nadat een evaluatieuitvoering is voltooid, haalt u de gescoorde resultaten op en bekijkt u deze in de portal of programmatisch.

Poll voor resultaten

Evaluaties verlopen asynchroon. Controleer de uitvoeringsstatus totdat deze is voltooid en haal vervolgens de resultaten op:

import time
from pprint import pprint

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

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

Resultaten interpreteren

Voor één gegevensvoorbeeld voeren alle evaluators het volgende schema uit:

  • Label: een binair 'pass' of 'fail'-label, vergelijkbaar met de uitvoer van een eenheidstest. Gebruik dit resultaat om vergelijkingen tussen evaluators te vergemakkelijken.
  • Score: een score van de natuurlijke schaal van elke evaluator. Sommige evaluators gebruiken een fijnkorrelige rubriek, scoren op een 5-puntschaal (kwaliteits evaluators) of een 7-puntsschaal (inhoudsveiligheids evaluators). Andere, zoals tekstuele gelijkenis-evaluators, gebruiken F1-scores, die tussen 0 en 1 zweven. Elke niet-binaire score wordt gebinariseerd naar 'pass' of 'fail' in het 'label'-veld op basis van de drempelwaarde.
  • Drempelwaarde: eventuele niet-binaire scores worden omgezet naar 'pass' of 'fail' op basis van een standaarddrempel, die de gebruiker kan overschrijven in de SDK-interface.
  • Reden: Om de begrijpelijkheid te verbeteren, leveren alle LLM-jury-evaluators ook een redeneringsveld op om uit te leggen waarom een bepaalde score wordt gegeven.
  • Details: (optioneel) Voor sommige evaluators, zoals tool_call_accuracy, is er mogelijk een veld met details of vlaggen die aanvullende informatie bevatten om gebruikers te helpen bij het opsporen van fouten in hun toepassingen.

Voorbeelduitvoer (één item)

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

Voorbeelduitvoer (aggregaat)

Voor geaggregeerde resultaten over meerdere gegevensvoorbeelden (een gegevensset) vormt de gemiddelde snelheid van de voorbeelden met een 'pass' de doorgangsfrequentie voor die gegevensset.

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

Probleemoplossingsproces

Taak die lang wordt uitgevoerd

Uw evaluatietaak blijft mogelijk gedurende een langere periode actief. Dit gebeurt meestal wanneer de implementatie van het OpenAI-model Azure onvoldoende capaciteit heeft, waardoor de service aanvragen opnieuw probeert uit te voeren.

Resolutie:

  1. Annuleer de huidige evaluatietaak met behulp van client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Verhoog de modelcapaciteit in de Azure-portal.
  3. Voer de evaluatie opnieuw uit.

Authenticatiefouten

Als u een 401 Unauthorized-fout of 403 Forbidden-fout ontvangt, controleer dan of:

  • Uw DefaultAzureCredential is correct geconfigureerd (voer az login uit als u Azure CLI gebruikt).
  • Uw account heeft de rol Azure AI-gebruiker in het Foundry-project.
  • De EINDPUNT-URL van het project is juist en bevat zowel de account- als de projectnamen.

Fouten in gegevensindeling

Als de evaluatie mislukt met een schema- of gegevenstoewijzingsfout:

  • Controleer of uw JSONL-bestand één geldig JSON-object per regel heeft.
  • Controleer of veldnamen data_mapping exact overeenkomen met de veldnamen in uw JSONL-bestand (hoofdlettergevoelig).
  • item_schema Controleer of de eigenschappen overeenkomen met de velden in uw gegevensset.

Frequentielimietfouten

Het maken van evaluatie-runs is beperkt op tenant-, abonnements- en projectniveau. Als u een 429 Too Many Requests antwoord ontvangt:

  • Controleer de retry-after header in het antwoord op de aanbevolen wachttijd.
  • Bekijk de hoofdtekst van het antwoord voor details van de frequentielimiet.
  • Gebruik exponentieel uitstel bij het opnieuw proberen van mislukte aanvragen.

Als een evaluatietaak mislukt met een 429 fout tijdens de uitvoering:

  • Verklein de grootte van uw evaluatiegegevensset of splits deze in kleinere batches.
  • Verhoog het TPM-quotum (tokens per minuut) voor uw modelimplementatie in de Azure-portal.

Fouten in het hulpprogramma Agent-evaluator

Als een agent-evaluator een fout retourneert voor niet-ondersteunde hulpprogramma's:

  • Controleer de ondersteunde hulpprogramma's voor agent evaluators.
  • Als tijdelijke oplossing kunt u niet-ondersteunde hulpprogramma's verpakken als door de gebruiker gedefinieerde functiehulpprogramma's, zodat de evaluator deze kan evalueren.

Verwante inhoud

  • Last updated on