Bewerten Sie Ihre KI-Agenten

Die Bewertung ist unerlässlich, um sicherzustellen, dass Ihr Agent vor der Bereitstellung Qualitäts- und Sicherheitsstandards erfüllt. Durch die Ausführung von Auswertungen während der Entwicklung legen Sie einen Basisplan für die Leistung Ihres Agents fest und können Akzeptanzschwellenwerte festlegen, z. B. eine 85% Durchlaufrate für aufgabenbezogene Einhaltung, bevor Sie sie für Benutzer freigeben.

In diesem Artikel erfahren Sie, wie Sie eine agentorientierte Auswertung für einen Foundry-Agent oder gehosteten Agent ausführen. Sie verwenden einen aus dem Kontext Ihres Agenten generierten Rubrik-Auswerter als primären Maßstab und ergänzen ihn durch integrierte Auswerter für Inhaltssicherheit und andere Risiken. Insbesondere Sie:

• Richten Sie den SDK-Client für die Auswertung ein.
• Erstellen Sie einen auf Ihren Agenten zugeschnittenen Rubrik-Evaluator und kombinieren Sie ihn mit integrierten Evaluatoren.
• Erstellen Sie ein Test-Dataset, und führen Sie eine Auswertung aus.
• Interpretieren Sie Ergebnisse, und integrieren Sie sie in Ihren Workflow.

Voraussetzungen

• Python 3.8 oder höher.

• Ein Foundry-Projekt mit einem Agenten oder einem gehosteten Agenten.

• Eine Azure OpenAI-Bereitstellung mit einem GPT-Modell, das den Chatabschluss unterstützt (z. B. gpt-4o oder gpt-4o-mini).

• Rolle "Foundry User " im Foundry-Projekt.

  Important

  Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

Einrichten des Clients

Installieren Sie das Foundry SDK, und richten Sie die Authentifizierung ein:

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

Erstellen Sie den Projektclient. In den folgenden Codebeispielen wird davon ausgegangen, dass Sie sie in diesem Kontext ausführen:

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

Evaluatoren auswählen

Evaluatoren bewerten die Antworten Ihres Agenten. Die empfohlene primäre Messgröße für die Bewertung von Agenten ist ein Rubrik-Evaluator – ein Satz gewichteter Bewertungsdimensionen, den ein LLM als Bewerter auf jede Antwort anwendet, sodass Sie die genauen Kriterien festlegen können, auf die es ankommt (z. B. die Durchsetzung von Richtlinien, die Genauigkeit bei der Tool-Nutzung oder die Klarheit der Kommunikation), und konsistent in großem Maßstab bewerten können. Ausführliche Informationen finden Sie unter Rubrikenbewertungen.

Koppeln Sie Ihre Rubrik mit zusätzlichen Bewertern, um die vollständige Abdeckung Ihres Bewertungsbereichs zu erhalten:

• Agent-Auswertungen – Bewerten Sie, wie effektiv Agents Aufgaben, Tools und Benutzerabsichten verarbeiten.
• Qualitätsbewertungen – Messen sie die Gesamtqualität der generierten Antworten.
• Textgleichheits-Evaluatoren – Vergleichen sie generierten Text mit Referenzantworten mithilfe von NLP-Metriken.
• Sicherheitsbewertungen – Identifizieren potenzieller Inhalte und Sicherheitsrisiken bei der generierten Ausgabe.
• Benutzerdefinierte Bewerter – Erstellen Sie Ihre eigenen Bewerter, wenn die Rubrik und die integrierten Werte Ihre Kriterien nicht abdecken.

Sie können eine Rubrik manuell erstellen oder eine aus dem Kontext des Agenten generieren – seinem Namen, seinen Anweisungen und seinen Tools. Im folgenden Beispiel wird eine Rubrik generiert und seine Abmessungen gedruckt, sodass Sie sie vor der Verwendung überprüfen können.

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

Ein vollständig lauffähiges Beispiel finden Sie auf GitHub unter sample_rubric_evaluator_generation_all_sources.py. Wenn Sie stattdessen eine Bewertungsrubrik manuell erstellen möchten, siehe sample_rubric_evaluator_manual.py.

Erstellen eines Testdatensatzes

Erstellen Sie eine JSONL-Datei mit Testabfragen für Ihren Agent. Jede Zeile enthält ein JSON-Objekt mit einem query Feld:

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

Laden Sie diese Datei als Dataset in Ihrem Projekt hoch:

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

Ausführen einer Auswertung

Wenn Sie eine Auswertung ausführen, sendet der Dienst jede Testabfrage an Ihren Agent, erfasst die Antwort und wendet die ausgewählten Auswertungen an, um die Ergebnisse zu bewerten.

Konfigurieren Sie zunächst Ihre Testkriterien. Verweisen Sie namentlich auf den generierten Rubrik-Evaluator. Jeder Eintrag verwendet data_mapping, um auf Felder in den Testdaten und der Agentenantwort zu verweisen, und initialization_parameters, um Evaluatoreinstellungen zu übergeben:

• {{item.X}} verweist auf Felder aus Ihren Testdaten, wie z. B. query.
• {{sample.output_items}} verweist auf die vollständige Agent-Antwort, einschließlich Toolaufrufen.
• {{sample.output_text}} verweist nur auf den Text der Antwortnachricht.
• initialization_parameters={"deployment_name": <model>} liefert das Richtermodell. Typischerweise erforderlich für LLM-Judge-Evaluatoren. Informationen zu Parametern pro Evaluator finden Sie unter integrierten Bewertern.

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

Um zusätzlich zu der Rubrik integrierte Evaluatoren einzubinden, fügen Sie Einträge mit derselben Struktur, jedoch mit evaluator_name="builtin.<name>", an. Fügen Sie z. B. Gewalt (Inhaltssicherheit) und Kohärenz (LLM-Richterqualität) hinzu:

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

Erstellen Sie als Nächstes die Auswertung. Eine Auswertung definiert das Testdatenschema und Testkriterien. Sie dient als Container für mehrere Ausführungen. Alle Ausführungen unter derselben Auswertung entsprechen demselben Schema und erzeugen denselben Satz von Metriken. Diese Konsistenz ist wichtig, um Ergebnisse über mehrere Durchläufe hinweg zu vergleichen.

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

Erstellen Sie schließlich eine Ausführung, die Ihre Testabfragen an den Agent sendet, und wenden Sie die Auswertungen an:

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

Interpretieren von Ergebnissen

Auswertungen werden je nach Anzahl der Abfragen in der Regel in wenigen Minuten abgeschlossen. Rufen Sie den Abschluss ab und erhalten Sie die Berichts-URL, um die Ergebnisse im Microsoft Foundry-Portal unter der Registerkarte Auswertungen anzuzeigen:

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

Aggregierte Ergebnisse

Auf Ausführungsebene können aggregierte Daten angezeigt werden, einschließlich der Anzahl der bestandenen und nicht bestandenen Prüfungen, der Token-Nutzung pro Modell und der Ergebnisse pro 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 }
    ]
}

Ausgabe auf Zeilenebene

Jede Auswertungsausführung gibt Ausgabeelemente pro Zeile in Ihrem Test-Dataset zurück und bietet detaillierte Einblicke in die Leistung Ihres Agents. Ausgabeelemente umfassen die ursprüngliche Abfrage, die Agentantwort, einzelne Auswertungsergebnisse mit Bewertungen und Gründen sowie die Tokenverwendung:

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

Das properties.dimension_scores Array zeigt die nach Dimensionen aufgeschlüsselte Bewertung, die vom LLM-Richter erstellt wurde. Jede Dimension score befindet sich auf einer Skala von 1 bis 5. Die oberste Ebene score ist der gewichtete Durchschnitt der anwendbaren Dimensionsergebnisse, normalisiert auf einen Bereich von 0 bis 1. Das vollständige Ausgabeschema finden Sie unter Rubrikenwertgeber.

Integrieren in Ihren Workflow

• CI/CD-Pipeline: Verwenden Sie die Auswertung als Qualitätsschranke in Ihrer Bereitstellungspipeline. Ausführliche Integration finden Sie unter Run-Auswertungen mit GitHub Actions.
• Produktionsüberwachung: Überwachen Sie Ihren Agenten in der Produktion mithilfe einer kontinuierlichen Auswertung. Anweisungen zum Einrichten finden Sie unter Einrichten einer kontinuierlichen Auswertung.

Optimieren und Vergleichen von Versionen

Verwenden Sie die Auswertung, um Ihren Agenten zu iterieren und zu verbessern.

1. Führen Sie eine Auswertung aus, um schwache Bereiche zu identifizieren. Verwenden Sie die Clusteranalyse , um Muster und Fehler zu finden.
2. Passen Sie Agentenanweisungen oder Tools basierend auf Ergebnissen an.
3. Neubewertung und Vergleich der Läufe zur Messung der Verbesserung.
4. Wiederholen Sie den Vorgang, bis Qualitätsschwellenwerte erfüllt sind.

Verwandte Inhalte

• Rubrikenwerter
• Generieren eines synthetischen Auswertungsdatensatzes
• Konvertieren Sie Ablaufverfolgungen von Agenten in Evaluierungsdatensätze
• Python SDK-Evaluierungsbeispiele
• Beispiel für die Rubrikenbewertungsgenerierung (Python)
• Ausführen von KI-Red-Teaming
• Agent-Überwachungsdashboard
• Referenz zu Agent-Gutachtern
• REST-API-Referenz
• Tracerauswertung in der Cloud
• Ablaufverfolgung in Microsoft Foundry einrichten