Evaluaties uitvoeren in de cloud met behulp van de Microsoft Foundry 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 cloudevaluaties 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.

Resultaten van cloudevaluatie 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. Cloudevaluatie ondersteunt alle door Microsoft gecureerde ingebouwde evaluators en uw eigen aangepaste evaluators. Evaluators worden beheerd in de evaluatorcatalogus met hetzelfde projectbereik, op rollen gebaseerd toegangsbeheer.

Tip

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

Hoe cloudevaluatie werkt

Als u een cloudevaluatie 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.

Cloudevaluatie ondersteunt de volgende scenario's:

Scenario Wanneer gebruikt u Gegevensbrontype Doelgerichtheid
Evaluatie van gegevensset Evalueer vooraf berekende antwoorden in een JSONL-bestand. jsonl —
Evaluatie van CSV-gegevensset Evalueer vooraf berekende antwoorden in een CSV-bestand. csv —
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 (prompt of gehost) 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 —
Traceringsevaluatie Evalueer agentinteracties die al in Application Insights zijn vastgelegd op tracerings-id. Gebruik deze methode voor niet-Foundry-agents (LangChain en aangepaste frameworks die voldoen aan OpenTelemetry-gebaseerde logging). azure_ai_traces —
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 testing uit op 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 Beschrijving
file_id Verwijs naar een geüploade dataset via ID.
file_content Geef gegevens inline op in de aanvraag.

Voor elke evaluatie is een data_source_config nodig 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, "traces" voor traceringsevaluatie, "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.

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.

Beginnen

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- of CSV-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."}

Of bereid een CSV-bestand voor met kolomkoppen die overeenkomen met de velden van uw evaluator:

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

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.

Tip

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 data_mapping op met de vereiste invoervelden voor elke evaluator. Uw veldnamen moeten overeenkomen met die in uw JSONL-bestand — bijvoorbeeld, als uw gegevens "question" in plaats van "query" hebben, gebruikt u "{{item.question}}" in de toewijzing. 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 dataset.

# 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 naar voltooiing te peilen en de resultaten te interpreteren.

Evaluatie van CSV-gegevensset

Evalueer vooraf berekende antwoorden in een CSV-bestand met behulp van het csv gegevensbrontype. Dit scenario werkt op dezelfde manier als de evaluatie van gegevenssets , maar accepteert CSV-bestanden in plaats van JSONL. Gebruik CSV als uw gegevens al in spreadsheet- of tabelindeling zijn.

Tip

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

Een CSV-bestand voorbereiden

Maak een CSV-bestand met kolomkoppen die overeenkomen met de velden die uw evaluators nodig hebben. Elke rij vertegenwoordigt één testcase:

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.

Uploaden en uitvoeren

Upload het CSV-bestand als een gegevensset en maak vervolgens een evaluatie met behulp van het csv gegevensbrontype. De schemadefinitie en evaluatorconfiguratie zijn hetzelfde als voor JSONL-evaluaties. Het enige verschil is het "type": "csv" verschil in de gegevensbron.

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

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

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

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

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

Zie Resultaten ophalen om naar voltooiing te peilen 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.

Tip

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 gegevenstoewijzingen inrichten

Wanneer het model tijdens runtime antwoorden genereert, gebruikt u {{sample.output_text}} in data_mapping om naar de uitvoer van het model te verwijzen. 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 naar voltooiing te peilen en de resultaten te interpreteren.

Tip

Als u een andere evaluatieuitvoering wilt toevoegen, kunt u dezelfde code gebruiken.

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. Dit scenario werkt voor zowel promptagenten als gehoste agenten.

Tip

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

Tip

Gehoste agents die gebruikmaken van het antwoordprotocol werken met dezelfde codevoorbeelden die hier worden weergegeven. Voor gehoste agents die gebruikmaken van het aanroepprotocol, is de input_messages indeling anders. Zie het protocol voor gehoste agent-aanroepen voor meer informatie.

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. Geef de agent op die moet worden geëvalueerd bij naam.

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 gegevenstoewijzingen inrichten

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

Variabele Beschrijving Gebruiken voor
{{sample.output_text}} De platte tekstreactie 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.

Tip

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 te controleren op voltooiing en vervolgens resultaten te interpreteren.

Protocol voor gehoste agent-aanroepen

Gehoste agents die gebruikmaken van het aanroepprotocol ondersteunen hetzelfde azure_ai_agent doeltype, maar gebruiken een vrije-vormindeling input_messages . Geef in plaats van de indeling van de gestructureerde sjabloon een JSON-object op dat rechtstreeks aan de aanvraagbody van de agent /invocations wordt toegewezen. Gebruik {{item.*}} tijdelijke aanduidingen voor het vervangen van velden in uw invoergegevens.

Als een gehoste agent zowel de antwoorden als aanroepprotocollen ondersteunt, wordt het protocol voor aanroepen standaard gebruikt door de service.

De berichtindeling en het doel definiëren

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

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

Evaluatie maken en uitvoeren

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

De installatie van de evaluator en gegevenstoewijzingen zijn hetzelfde als voor promptagent-evaluatie. Gebruik {{sample.output_text}} deze functie voor het tekstantwoord van de agent en {{sample.output_items}} voor de volledige gestructureerde uitvoer, inclusief hulpprogramma-aanroepen.

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.

Tip

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 naar voltooiing te peilen en de resultaten te interpreteren.

Traceringsevaluatie

Evalueer agentinteracties die al zijn vastgelegd in Application Insights. Gebruik het azure_ai_traces gegevensbrontype. Dit scenario is handig voor evaluatie na de implementatie van echt productieverkeer. U selecteert traceringen uit uw bewakingspijplijn en draait evaluatoren zonder aanvragen opnieuw uit te voeren.

Belangrijk

Trace-evaluatie is de aanbevolen methode om agents die niet zijn gebouwd met de Microsoft Foundry Agent Service te evalueren, inclusief LangChain- en aangepaste frameworks. Zolang uw agent OpenTelemetry-spans verzendt volgens de GenAI-semantische conventies naar Application Insights, kan trace-evaluatie de interacties beoordelen met behulp van dezelfde evaluatoren die beschikbaar zijn voor Foundry-agents.

Trace-evaluatie ondersteunt twee modi:

  • Door trace IDs — evalueer specifieke agentinteracties door hun operation_Id waarden te verstrekken uit Application Insights.
  • Op agentfilter : automatisch recente traceringen voor een bepaalde agent detecteren en evalueren zonder tracerings-id's handmatig te verzamelen.

Tip

Voordat u begint, voltooit u Aan de slag. Voor dit scenario is ook een Application Insights-resource vereist die is verbonden met uw Foundry-project.

Tracering van gegevensvereisten

Voor traceringsevaluatie moet uw agent spans verzenden volgens de semantische OpenTelemetry-conventies voor generatieve AI. De evaluatieservice leest met name invoke_agent 'spans' uit Application Insights en extraheert gespreksgegevens uit hun attributen.

De volgende spankenmerken worden gebruikt:

Kenmerk Vereist Beschrijving
gen_ai.operation.name Ja Moet gelijk zijn aan "invoke_agent". De service negeert alle andere traces.
gen_ai.agent.id Voor agentfiltermodus Unieke agentidentificator (formaat: agent-name:version).
gen_ai.agent.name Voor agentfiltermodus Naam van door mensen leesbare agent.
gen_ai.input.messages Voor evaluatorquery-invoer JSON-matrix met invoerberichten volgens de semantische indeling van genAI-conventies. Berichten met rol user of system toewijzing aan query; berichten met rol assistant of tool toewijzing aan response.
gen_ai.output.messages Voor evaluatorquery-invoer JSON-matrix met door het model gegenereerde uitvoerberichten. Alle uitvoerberichten worden toegewezen aan response. Als de uitvoer ook het type tool_call of tool_result bevat, wordt dit toegewezen aan tool_calls
gen_ai.tool.definitions Optioneel JSON-matrix met hulpprogrammaschema's die beschikbaar zijn voor de agent. Als deze niet aanwezig is, probeert de service hulpprogrammadefinities af te leiden uit oproepberichten van hulpprogramma's, maar kunnen afgeleid schema's onvolledig zijn.
gen_ai.conversation.id Optioneel Gespreks-id, doorgegeven aan evaluatieresultaten voor correlatie.

Opmerking

Als gen_ai.input.messages en gen_ai.output.messages leeg zijn of ontbreken, zullen kwaliteitevaluators (coherentie, vloeiendheid, relevantie, het oplossen van intenties) score=None teruggeven. Veiligheids evaluators (geweld, zelfverschadiging, seksueel, haat/oneerlijkheid) kunnen nog steeds scores met gedeeltelijke gegevens produceren, maar ze produceren mogelijk geen zinvolle resultaten.

Voor Python-agents die zijn gebouwd met de Azure AI Agent Server SDK, de [tracing] extra toevoegen om automatische spanemissie mogelijk te maken.

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

Vereisten voor traceringsevaluatie

Naast de algemene vereisten is traceringsevaluatie vereist:

  • Een Application Insights-resource die is verbonden met uw Foundry-project. Zie Tracering instellen in Microsoft Foundry.
  • De beheerde identiteit van het project moet de rol Log Analytics Reader hebben voor zowel de Application Insights-resource als de gekoppelde Log Analytics werkruimte.
  • Het azure-monitor-query Python-pakket (alleen nodig als u tracerings-id's handmatig verzamelt).
pip install "azure-ai-projects>=2.0.0" azure-monitor-query

Stel deze omgevingsvariabelen in:

  • APPINSIGHTS_RESOURCE_ID: de Application Insights-resource-id (bijvoorbeeld /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — De agent-id die wordt verzonden door de traceringsintegratie (gen_ai.agent.id kenmerk), die wordt gebruikt om traceringen te filteren. Indeling: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Optioneel) Aantal uren om terug te kijken bij het uitvoeren van query's op traceringen. Standaard is 1.

Optie A: Evalueren op agentfilter

De eenvoudigste benadering: laat de service automatisch recente traceringen voor een specifieke agent detecteren en evalueren. Er is geen handmatige tracerings-id-verzameling nodig.

import os

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

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

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

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

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

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

De service filtert invoke_agent spans op het gen_ai.agent.id kenmerk, monstert tot max_traces unieke trace-ID's en evalueert alle spans van deze traceringen.

Optie B: Evalueren met behulp van trace-ID's

Voor meer controle verzamelt u specifieke tracerings-id's van Application Insights en evalueert u deze. Dit is handig als u een samengestelde set interacties wilt evalueren (bijvoorbeeld traceringen die zijn gemarkeerd door waarschuwingen of een steekproef voor kwaliteitsbeoordeling).

Tracering-ID's verzamelen van Application Insights

Query uitvoeren op Application Insights voor operation_Id-waarden uit de traces van uw agent. Elk operation_Id vertegenwoordigt een volledige agentinteractie:

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

Evaluatie maken en uitvoeren met tracerings-id's

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

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

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

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

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

Evaluators en gegevenstoewijzingen inrichten

Bij het evalueren van traces worden gespreksgegevens automatisch geëxtraheerd uit de OpenTelemetry-span-kenmerken. Gebruik deze veldnamen rechtstreeks in data_mapping (zonder de item. of sample. voorvoegsels die in andere scenario's worden gebruikt):

Variabele Bronkenmerk Beschrijving
{{item.query}} gen_ai.input.messages (gebruikers-/systeemrollen) De gebruikersquery die is geëxtraheerd uit de tracering.
{{item.response}} gen_ai.input.messages (assistent-/toolrollen) + gen_ai.output.messages Het antwoord van de agent dat is geëxtraheerd uit de tracering.
{{item.tool_definitions}} gen_ai.tool.definitions Toolschema's die beschikbaar zijn voor de agent. Alleen vereist voor hulpprogramma-gerelateerde beoordelaars
{{item.tool_calls}} Geëxtraheerd uit assistentberichten in gen_ai.input.messages / gen_ai.output.messages Aanroepen van hulpprogramma's door de agent tijdens de interactie. Wordt gebruikt door hulpprogramma-evaluators. Alleen vereist voor toolgerelateerde beoordelaars 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

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

Synthetische gegevensevaluatie (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.

Tip

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.

Parameters

Parameter Vereist Beschrijving
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 Seed-gegevensbestanden (op bestands-id) om de relevantie van gegenereerde query's te verbeteren. Op dit moment wordt slechts één bestand ondersteund.

Evaluators en gegevenstoewijzingen inrichten

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

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

Doelstelling van het model

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 met synthetische gegevensgeneratie, neemt u alleen system rolberichten op — de service levert automatisch de gegenereerde query's 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 van de 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 naar voltooiing te peilen 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

Evaluatieruns worden asynchroon uitgevoerd. 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...")

# 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 omgezet naar 'pass' of 'fail' in het veld 'label', waarbij dit gebeurt op basis van de drempelwaarde.
  • Drempelwaarde: eventuele niet-binaire scores worden omgezet in binaire vorm naar 'pass' of 'fail' aan de hand van een standaarddrempel, die de gebruiker kan overschrijven binnen de gebruikerservaring van de SDK.
  • 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
    }
  ]
}

Probleemoplossing

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 capaciteit van het model in de Azure-portal.
  3. Voer de evaluatie opnieuw uit.

Authenticatiefouten

Als u een 401 Unauthorized 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 evaluatieuitvoeringen 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