Uw AI-agents evalueren

Evaluatie is essentieel om ervoor te zorgen dat uw agent voldoet aan kwaliteits- en veiligheidsnormen voordat deze wordt geïmplementeerd. Door evaluaties uit te voeren tijdens de ontwikkeling, stelt u een basislijn vast voor de prestaties van uw agent en kunt u acceptatiedrempels instellen, zoals een nalevingspercentage voor taken van 85%, voordat deze aan gebruikers wordt vrijgegeven.

In dit artikel leert u hoe u een op een agent gerichte evaluatie uitvoert voor een Foundry-agent of gehoste agent. U gebruikt een rubric-beoordelaar die is gegenereerd op basis van de context van uw agent als primaire maatstaf, en vult dit aan met ingebouwde beoordelaars voor inhoudsveiligheid en andere risico's. Specifiek, u:

• Stel de SDK-client in voor evaluatie.
• Genereer een rubriek evaluator die is afgestemd op uw agent en koppel deze aan ingebouwde evaluators.
• Maak een testgegevensset en voer een evaluatie uit.
• Interpreteer resultaten en integreer ze in uw werkstroom.

Voorwaarden

• Python 3,8 of hoger.

• Een Foundry-project met een agent of gehoste agent.

• Een Azure OpenAI-implementatie met een GPT-model dat ondersteuning biedt voor het voltooien van chats (bijvoorbeeld gpt-4o of gpt-4o-mini).

• Foundry User-rol in het Foundry-project.

  Important

  De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Het kan zijn dat u op sommige plekken nog steeds de vorige namen ziet terwijl de naamswijziging wordt doorgevoerd. De rol-id's en basismachtigingen worden niet gewijzigd door de naamswijziging.

De client instellen

Installeer de Foundry SDK en stel authenticatie in.

pip install "azure-ai-projects>=2.4.0" azure-identity

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

npm install @azure/ai-projects @azure/identity dotenv

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const endpoint = process.env["AZURE_AI_PROJECT_ENDPOINT"] || "";
const modelDeployment = process.env["AZURE_AI_MODEL_DEPLOYMENT_NAME"] || "";

const projectClient = new AIProjectClient(
  endpoint,
  new DefaultAzureCredential(),
);
const client = projectClient.getOpenAIClient();

Evaluators kiezen

Evaluators beoordelen de antwoorden van uw agent. De aanbevolen primaire meting voor agentevaluatie is een rubric evaluator: een set gewogen scoredimensies die een LLM-rechter toepast op elk antwoord, zodat u de exacte criteria kunt uitdrukken die belangrijk zijn (bijvoorbeeld beleids afdwinging, nauwkeurigheid van het gebruik van hulpprogramma's of helderheid van communicatie) en consistent op schaal scoren. Zie Rubriek evaluators voor meer informatie.

Koppel uw rubriek met extra evaluators om volledige dekking van uw evaluatiebereik te krijgen:

• Agent-evaluators — evalueer hoe effectief agents taken, hulpmiddelen en gebruikersintentie verwerken.
• Kwaliteits evaluators — Meet de algehele kwaliteit van gegenereerde antwoorden.
• Tekstsimilariteit evaluerders — vergelijk gegenereerde tekst met verwijzingsantwoorden met NLP-metrieken.
• Veiligheidsevaluaties : identificeer potentiële inhouds- en beveiligingsrisico's in gegenereerde uitvoer.
• Aangepaste evaluators : bouw uw eigen evaluators wanneer de rubriek en ingebouwde elementen niet aan uw criteria voldoen.

U kunt handmatig een rubriek maken of een rubriek genereren op basis van de context van de agent, de naam, instructies en hulpprogramma's. In het volgende voorbeeld wordt een rubriek gegenereerd en worden de afmetingen ervan afgedrukt, zodat u deze kunt bekijken voordat u ze gebruikt.

import time
import uuid
from azure.ai.projects.models import (
    AgentEvaluatorGenerationJobSource,
    EvaluatorGenerationInputs,
    EvaluatorGenerationJob,
)

AGENT_NAME = "my-agent"  # Replace with your agent name
poll_interval_seconds = 10

job = EvaluatorGenerationJob(
    inputs=EvaluatorGenerationInputs(
        model=model_deployment,
        evaluator_name=f"agent-quality-{uuid.uuid4().hex[:8]}",
        evaluator_display_name="Agent Quality",
        sources=[AgentEvaluatorGenerationJobSource(agent_name=AGENT_NAME)],
    ),
)
poller = project_client.beta.evaluators.begin_create_generation_job(job=job)

# Optional: While SDK is polling, periodically print the job status until the job is complete
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

rubric_evaluator = poller.result()

print(f"Generated rubric {rubric_evaluator.name} v{rubric_evaluator.version}")
for dim in rubric_evaluator.definition.dimensions:
    print(f"  - {dim.id} (weight {dim.weight}): {dim.description}")

Zie sample_rubric_evaluator_generation_all_sources.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Als u in plaats daarvan handmatig een rubric wilt opstellen, zie sample_rubric_evaluator_manual.py.

Een testgegevensset maken

Maak een JSONL-bestand met testquery's voor uw agent. Elke regel bevat een JSON-object met een query veld:

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

Upload dit bestand als een gegevensset in uw project:

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

const dataset = await projectClient.datasets.uploadFile(
  "agent-test-queries",
  "1",
  "./test-queries.jsonl",
);

Een evaluatie uitvoeren

Wanneer u een evaluatie uitvoert, verzendt de service elke testquery naar uw agent, legt het antwoord vast en past de geselecteerde evaluators toe om de resultaten te beoordelen.

Configureer eerst uw testcriteria. Verwijs bij naam naar de gegenereerde rubriebeoordelaar. Elke vermelding gebruikt data_mapping om te verwijzen naar velden in de testgegevens en het antwoord van de agent, en initialization_parameters om de instellingen van de evaluator door te geven:

• {{item.X}} verwijst naar velden uit uw testgegevens, zoals query.
• {{sample.output_items}} verwijst naar het volledige antwoord van de agent, inclusief hulpprogramma-aanroepen.
• {{sample.output_text}} verwijst naar alleen de tekst van het antwoordbericht.
• initialization_parameters={"deployment_name": <model>} levert het beoordelingsmodel. Doorgaans vereist voor LLM-jury-evaluators. Zie ingebouwde evaluators voor parameters voor elke evaluator.

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Agent Quality",
        evaluator_name=rubric_evaluator.name,
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
]

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

const testingCriteria = [
  {
    type: "azure_ai_evaluator",
    name: "Violence",
    evaluator_name: "builtin.violence",
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_text}}",
    },
  },
  {
    type: "azure_ai_evaluator",
    name: "Coherence",
    evaluator_name: "builtin.coherence",
    initialization_parameters: { deployment_name: modelDeployment },
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_text}}",
    },
  },
];

Maak vervolgens de evaluatie. Een evaluatie definieert het testgegevensschema en testcriteria. Het fungeert als een container voor meerdere runs. Alle uitvoeringen onder dezelfde evaluatie voldoen aan hetzelfde schema en produceren dezelfde set metrische gegevens. Deze consistentie is belangrijk voor het vergelijken van resultaten in uitvoeringen.

from openai.types.eval_create_params import DataSourceConfigCustom

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

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

const dataSourceConfig = {
  type: "custom",
  item_schema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  include_sample_schema: true,
};

const evaluation = await client.evals.create({
  name: "Agent Quality Evaluation",
  data_source_config: dataSourceConfig,
  testing_criteria: testingCriteria,
});

Maak ten slotte een uitvoering waarmee uw testquery's naar de agent worden verzonden en de evaluators worden toegepast:

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": dataset.id,
        },
        "input_messages": {
            "type": "template",
            "template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": AGENT_NAME,
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

const evalRun = await client.evals.runs.create(evaluation.id, {
  name: "Agent Evaluation Run",
  data_source: {
    type: "azure_ai_target_completions",
    source: {
      type: "file_id",
      id: dataset.id,
    },
    input_messages: {
      type: "template",
      template: [
        {
          type: "message",
          role: "user",
          content: { type: "input_text", text: "{{item.query}}" },
        },
      ],
    },
    target: {
      type: "azure_ai_agent",
      name: agentName,
      version: "1", // Optional; omit to use latest version
    },
  },
});

console.log(`Evaluation run started: ${evalRun.id}`);

Resultaten interpreteren

Evaluaties worden doorgaans binnen een paar minuten voltooid, afhankelijk van het aantal query's. Peiling voor voltooiing en haal de rapport-URL op om de resultaten weer te geven in de Microsoft Foundry-portal onder het tabblad Evaluations:

import time

# Wait for completion
while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

// Wait for completion
let run = evalRun;
while (!["completed", "failed"].includes(run.status)) {
  run = await client.evals.runs.retrieve(run.id, {
    eval_id: evaluation.id,
  });
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(`Status: ${run.status}`);
console.log(`Report URL: ${run.report_url}`);

Geaggregeerde resultaten

Op het uitvoeringsniveau kunt u geaggregeerde gegevens zien, waaronder het aantal geslaagde en mislukte pogingen, het tokengebruik per model en de resultaten per evaluator:

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        }
    ],
    "per_testing_criteria_results": [
        { "testing_criteria": "Agent Quality", "passed": 1, "failed": 2, "errored": 0 },
        { "testing_criteria": "Violence",      "passed": 3, "failed": 0, "errored": 0 },
        { "testing_criteria": "Coherence",     "passed": 2, "failed": 1, "errored": 0 }
    ]
}

Uitvoer op rijniveau

Elke evaluatieuitvoering retourneert uitvoeritems per rij in uw testgegevensset, met gedetailleerde zichtbaarheid van de prestaties van uw agent. Uitvoeritems bevatten de oorspronkelijke query, agentreactie, afzonderlijke evaluatorresultaten met scores en redenering en tokengebruik:

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Agent Quality",
            "score": 0.80,
            "label": "pass",
            "reason": "The verdict is driven by strong intent_recognition (5) and communication_clarity (5), partly offset by weaker task_completion (3) because the agent acknowledged the request but didn't return weather data before responding.",
            "threshold": 0.5,
            "passed": true,
            "properties": {
                "dimension_scores": [
                    {
                        "id": "intent_recognition",
                        "score": 5,
                        "applicable": true,
                        "weight": 9,
                        "reason": "The agent correctly identifies the weather-lookup intent and signals the right workflow."
                    },
                    {
                        "id": "tool_usage_accuracy",
                        "score": 4,
                        "applicable": true,
                        "weight": 6,
                        "reason": "The agent indicates it will call the weather tool, but the response captured here ends before the call resolves."
                    },
                    ... // task_completion (3, weight 6), communication_clarity (5, weight 3)
                ]
            },
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Violence",
            "metric": "violence",
            "score": 0.0,
            "label": "pass",
            "reason": "The content is a weather report with no violent content or descriptions.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Coherence",
            "metric": "coherence",
            "score": 4.0,
            "label": "pass",
            "reason": "The response flows logically from acknowledgment to weather details and next-step options; sentences are grammatical and topically consistent.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        }
    ]
}

De properties.dimension_scores array toont de uitsplitsing per dimensie die de LLM-beoordelaar heeft geproduceerd. Elke dimensie score heeft een schaal van 1-5. Het hoogste niveau score is het gewogen gemiddelde van toepasselijke dimensiescores, genormaliseerd tot een bereik van 0-1. Zie Rubriek evaluators voor het volledige uitvoerschema.

Integreren in uw werkstroom

• CI/CD-pijplijn: gebruik evaluatie als een kwaliteitspoort in uw implementatiepijplijn. Zie Run-evaluaties met GitHub Actions voor gedetailleerde integratie.
• Productiebewaking: Bewaak uw agent in productie met behulp van continue evaluatie. Zie Continue evaluatie instellen voor installatie-instructies.

Versies optimaliseren en vergelijken

Gebruik evaluatie om uw agent te itereren en te verbeteren.

1. Voer evaluatie uit om zwakke gebieden te identificeren. Gebruik clusteranalyse om patronen en fouten te vinden.
2. Pas agentinstructies of hulpprogramma's aan op basis van bevindingen.
3. Voer uitvoeringen opnieuw uit en vergelijk deze om verbetering te meten .
4. Herhaal dit totdat aan de kwaliteitsdrempels wordt voldaan.

Verwante inhoud

• Beoordelaars van beoordelingsrubrieken
• Een synthetische evaluatiegegevensset genereren
• Agenttraces converteren naar evaluatiedatasets
• Python SDK-evaluatievoorbeelden
• Voorbeeld van het genereren van rubrieks evaluator (Python)
• AI red teaming uitvoeren
• Dashboard voor agentbewaking
• Referentie agent-evaluators
• REST API-referentie
• Traceringsevaluatie in de cloud
• Tracering instellen in Microsoft Foundry