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 agentinriktad utvärdering mot en Foundry-agent eller värdbaserad agent med hjälp av inbyggda utvärderare för kvalitet, säkerhet och agentbeteende. Mer specifikt, du:

  • Konfigurera SDK-klienten för utvärdering.
  • Välj utvärderare för kvalitet, säkerhet och agentbeteende.
  • Skapa en testdatauppsättning och kör en utvärdering.
  • Tolka resultat och integrera dem i arbetsflödet.

Tips

Allmän utvärdering av generativa AI-modeller och program, inklusive anpassade utvärderare, olika datakällor och ytterligare SDK-alternativ, finns i Köra utvärderingar från SDK.

Förutsättningar

  • Python 3.8 eller senare.
  • Ett Foundry-projekt med en agent eller en värdbaserad agent.
  • En Azure OpenAI-distribution med en GPT-modell som stöder chattens slutförande (till exempel gpt-4o eller gpt-4o-mini).
  • Azure AI User roll i Foundry-projektet.

Observera

Vissa utvärderingsfunktioner har regionala begränsningar. Se detaljer för regioner som stöds.

Konfigurera klienten

Installera Foundry SDK och konfigurera autentisering:

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

Skapa projektklienten. Följande kodexempel förutsätter att du kör dem i den här kontexten:

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

Välj utvärderare

Utvärderare är funktioner som utvärderar agentens svar. Vissa utvärderare använder AI-modeller som domare, medan andra använder regler eller algoritmer. För agentutvärdering bör du överväga den här uppsättningen:

Utvärderaren Vad den mäter
Uppgiftsföljsamhet Följer agenten sina systeminstruktioner?
Samstämmighet Är svaret logiskt och välstrukturerat?
Våld Innehåller svaret våldsamt innehåll?

Fler inbyggda utvärderare finns i:

Information om hur du skapar egna utvärderare finns i Anpassade utvärderare.

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

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 utvärderarna. Varje utvärderare behöver en datamappning som anger var indata ska hittas:

  • {{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.

AI-assisterade utvärderare, som Aktivitetsefterlevnad och Koherens, kräver ett modelldistributionsnamn i initialization_parameters. Värdet måste matcha ett GPT-distributionsnamn i projektet – det här är den domarmodell som används för att bedöma svar. Vissa utvärderare kan kräva ytterligare fält, till exempel ground_truth eller verktygsdefinitioner. Mer information finns i dokumentationen för utvärderaren.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "Task Adherence",
        "evaluator_name": "builtin.task_adherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Violence",
        "evaluator_name": "builtin.violence",
        "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.

data_source_config = {
    "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,
)

Skapa slutligen en körning av testprocessen 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": "my-agent",  # Replace with your agent name
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

Tips

Det här exemplet fungerar för både promptagenter och värdbaserade agenter som använder svarsprotokollet. För värdbaserade agenter som använder anropsprotokollet input_messages är formatet annorlunda – ange ett JSON-objekt i frihandsformat i stället för den strukturerade mallen. Mer information och kodexempel finns i protokollet för värdbaserade agentanrop i molnutvärderingsguiden.

Tolka resultat

Utvärderingar slutförs vanligtvis på några minuter, beroende på antalet frågor. Sök efter slutförande och hämta rapport-URL:en för att visa resultatet på Microsoft Foundry-portalen under fliken 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}")

Screenshot som visar utvärderingsresultat för en agent i Microsoft Foundry Portal.

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": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

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": "Task Adherence",
            "metric": "task_adherence",
            "label": "pass",
            "reason": "Agent followed system instructions correctly",
            "threshold": 3,
            "passed": true,
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        ... // remaining evaluation results
    ]
}

Integrera i arbetsflödet

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ör körningar för att mäta förbättring.
  4. Upprepa tills kvalitetströsklar uppfylls.

Relaterat innehåll

  • Last updated on