Utvärdera dina AI-agenter

Utvärdering är viktigt för att säkerställa att din agent uppfyller kvalitets- och säkerhetsstandarder före distributionen. Genom att köra utvärderingar under utvecklingen upprättar du en baslinje för agentens prestanda och kan ange tröskelvärden för godkännande, till exempel en överföringshastighet på 85% uppgiftsefterlevnad innan den släpps till användarna.

I den här artikeln får du lära dig hur du kör en utvärdering riktad mot en agent på en Foundry-agent eller hostad agent. Du använder en bedömningsmatrisutvärderare som genererats utifrån agentens kontext som främsta mått och kompletterar med inbyggda utvärderare för innehållssäkerhet och andra risker. Mer specifikt, du:

• Konfigurera SDK-klienten för utvärdering.
• Generera en rubrikutvärderare som är skräddarsydd för din agent och kombinera den med inbyggda utvärderare.
• Skapa en testdatauppsättning och kör en utvärdering.
• Tolka resultat och integrera dem i arbetsflödet.

Förutsättningar

• Python 3.8 eller senare.

• Ett Foundry-projekt med en agent eller en värdtjänstagent.

• En Azure OpenAI-distribution med en GPT-modell som stöder chattens slutförande (till exempel gpt-4o eller gpt-4o-mini).

• Foundry-användarroll i Foundry-projektet.

  Important

  Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

Konfigurera klienten

Installera Foundry SDK och konfigurera autentisering:

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

Välj utvärderare

Utvärderare bedömer agentens svar. Det rekommenderade primära måttet för agentutvärdering är en kriterieutvärdering – en uppsättning viktade bedömningsdimensioner som en LLM-domare tillämpar på varje svar, så att du kan uttrycka de exakta kriterier som är viktiga (till exempel principframtvingande, noggrannhet för verktygsanvändning eller kommunikationsklarhet) och poängsätta konsekvent i stor skala. Mer information finns i Kriterier utvärderare.

Para ihop ditt kriterium med ytterligare utvärderare för att få fullständig täckning av utvärderingsomfånget:

• Agentutvärderingar – Utvärdera hur effektivt agenter hanterar uppgifter, verktyg och användar avsikter.
• Kvalitetsutvärderingar – Mät den övergripande kvaliteten på genererade svar.
• Utvärderare för textlikhet – Jämför genererad text med referenssvar med hjälp av NLP-mått.
• Säkerhetsutvärderingar – Identifiera potentiellt innehåll och säkerhetsrisker i genererade utdata.
• Anpassade utvärderare – Skapa dina egna utvärderare när kriterierna och de inbyggda inte täcker dina kriterier.

Du kan skriva en bedömningsmatris för hand eller generera en utifrån agentens kontext – dess namn, instruktioner och verktyg. Följande exempel genererar ett kriterier och skriver ut dess dimensioner så att du kan granska dem innan du använder det.

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

För ett fullständigt körbart exempel, se sample_rubric_evaluator_generation_all_sources.py på GitHub. Om du i stället vill skriva en bedömningsmatris manuellt, se sample_rubric_evaluator_manual.py.

Skapa en testdatauppsättning

Skapa en JSONL-fil med testfrågor för din agent. Varje rad innehåller ett JSON-objekt med ett query fält:

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

Ladda upp den här filen som en datauppsättning i projektet:

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

Köra en utvärdering

När du kör en utvärdering skickar tjänsten varje testfråga till din agent, samlar in svaret och tillämpar de valda utvärderarna för att bedöma resultaten.

Konfigurera först testkriterierna. Referera till den genererade utvärderaren för bedömningsmatrisen med namn. Varje post använder data_mapping för att peka på fält i testdata och agentens svar, och initialization_parameters för att ange utvärderarinställningar:

• {{item.X}} refererar till fält från dina testdata, till exempel query.
• {{sample.output_items}} refererar till det fullständiga agentsvaret, inklusive verktygsanrop.
• {{sample.output_text}} refererar bara till svarsmeddelandetexten.
• initialization_parameters={"deployment_name": <model>} tillhandahåller domarmodellen. Krävs vanligtvis för LLM-utvärderare. För parametrar per utvärderare, se inbyggda utvärderare.

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

Skapa sedan utvärderingen. En utvärdering definierar testdataschemat och testkriterierna. Den fungerar som en container för flera körningar. Alla körningar under samma utvärdering överensstämmer med samma schema och producerar samma uppsättning mått. Den här konsekvensen är viktig för att jämföra resultat mellan körningar.

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

Skapa slutligen en exekvering som skickar dina testfrågor till agenten och tillämpar utvärderarna.

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}`);

Tolka resultat

Utvärderingar slutförs vanligtvis på några minuter, beroende på antalet frågor. Kontrollera om det är klart och hämta URL till rapporten för att visa resultatet på Microsoft Foundry-portalen under fliken Utvärderingar:

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}`);

Aggregerade resultat

På körningsnivå kan du se aggregerade data, inklusive antal pass och fail, tokenanvändning per modell och resultat per utvärderare:

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

Utdata på radnivå

Varje utvärderingskörning returnerar utdataobjekt per rad i testdatauppsättningen, vilket ger detaljerad insyn i agentens prestanda. Utdataobjekt inkluderar den ursprungliga frågan, agentsvaret, enskilda utvärderarresultat med poäng och resonemang samt tokenanvändning:

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

Matrisen properties.dimension_scores visar den uppdelning per dimension som LLM-domaren skapade. Varje dimension är score på en skala mellan 1 och 5. Den översta nivån score är det viktade medelvärdet av tillämpliga dimensionspoäng, normaliserat till ett intervall på 0–1. Det fullständiga utdataschemat finns i Utvärderare för kriterier.

Integrera i arbetsflödet

• CI/CD-pipeline: Använd utvärdering som en kvalitetsbarriär i distributionspipelinens. Detaljerad integrering finns i Kör utvärderingar med GitHub Actions.
• Produktionsövervakning: Övervaka din agent i produktion med kontinuerlig utvärdering. Installationsinstruktioner finns i Konfigurera kontinuerlig utvärdering.

Optimera och jämföra versioner

Använd utvärdering för att iterera och förbättra din agent:

1. Kör utvärdering för att identifiera svaga områden. Använd klusteranalys för att hitta mönster och fel.
2. Justera agentinstruktioner eller verktyg baserat på resultat.
3. Omvärdera och jämföra körningar för att mäta förbättringar.
4. Upprepa tills kvalitetströsklar uppfylls.

Relaterat innehåll

• Utvärderingar av kriterier
• Generera en syntetisk utvärderingsdatauppsättning
• Konvertera agentspårningar till utvärderingsdatauppsättningar
• Python SDK-utvärderingsexempel
• Genereringsexempel för rubrikutvärderare (Python)
• Genomför AI-red teaming
• Kontrollpanel för agentövervakning
• Referens för utvärderare av agenter
• REST API-referens
• Spårningsutvärdering i molnet
• Sätt upp spårning i Microsoft Foundry