Datasetschema und Testentwurf

Auswertungsdatasets sind JSON-Dateien, die Eingabeaufforderungen und erwartete Antworten enthalten. In diesem Artikel wird das Datasetschema definiert, es wird dokumentiert, wo das Tool nach Datasets sucht, und zeigt, wie effektive Tests entworfen werden, einschließlich erweiterter Szenarien wie Mehrdurchlauf-Unterhaltungen, Element-Evaluatorkonfiguration und kategorisierte Testsammlungen.

Schemaübersicht

Auswertungsdatasets sind JSON-Dateien. Das Tool unterstützt zwei äquivalente Formen: ein Objekt mit Versionsverwaltung (empfohlen) und ein Legacyarray.

Das einfachste gültige Dataset erfordert nur schemaVersion und ein items Array mit prompt - und expected_response -Feldern.

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "string",
      "expected_response": "string"
    }
  ]
}

Die Schemaversion 1.2.0 fügt Unterstützung für die Standard- und Elementauswertungskonfiguration, die Steuerung des Auswertungsmodus, benannte Elemente und Unterhaltungen mit mehreren Durchläufen hinzu. Weitere Informationen finden Sie unter Konfigurieren von Auswertungen und Mustern für mehrstufige Auswertungen.

Schemafelder

Feld Typ Erforderlich Beschreibung
schemaVersion string Empfohlen Semantische Version (z. B "1.0.0" . oder "1.2.0"). Die Abwärtskompatibilität ist innerhalb einer Hauptversion garantiert. Verwenden Sie "1.2.0" , um die Auswertungskonfiguration, Evaluatormodi und native Unterstützung für mehrere Durchläufe zu aktivieren.
items Array Ja Array von Testelementen. Jedes Element ist entweder ein Eingabeaufforderungs-Antwort-Paar mit einzelnem Durchlauf oder eine benannte Konversation mit mehreren Durchläufen.
description string Optional Freitextbeschreibung des Datasets (z. B "Regression tests for Q1 2026 release". ).
default_evaluators Objekt Optional Auswertungen, die auf jedes Element im Dataset angewendet werden, sofern sie nicht überschrieben werden. Jeder Schlüssel ist ein Evaluatorname (z. B "Relevance". , "Coherence"); der Wert ist ein Optionsobjekt (verwenden Sie {} für Standardwerte). Erfordert schemaVersion"1.2.0" oder höher.
items[].prompt string Bedingte Die Eingabeaufforderung oder Anweisung, die an den Agent gesendet wird. Erforderlich für Einzellaufelemente. Verwenden Sie nicht mit turns.
items[].expected_response string Bedingte Die für die Bewertung verwendete Verweisantwort. Erforderlich für Einzellaufelemente. Verwenden Sie nicht mit turns.
items[].name string Optional Anzeigename für das Testelement (z. B "Expense policy flow". ). Besonders nützlich zum Identifizieren von Elementen mit mehreren Durchläufen in Berichten.
items[].turns Array Bedingte Sortiertes Array von Turnobjekten für eine Mehrfachkonversation innerhalb eines einzelnen Elements. Jeder Durchlauf enthält prompt, expected_responseund optional evaluators und evaluators_mode. Verwenden Sie nicht mit der obersten Ebene prompt/expected_response. Erfordert schemaVersion"1.2.0" oder höher.
items[].evaluators Objekt Optional Außerkraftsetzungen der Elementauswertung. Jeder Schlüssel ist ein Evaluatorname; Der Wert ist ein Optionsobjekt (z. B { "citation_format": "mixed" }. ). Das Verhalten hängt von ab evaluators_mode. Erfordert schemaVersion"1.2.0" oder höher.
items[].evaluators_mode string Optional Steuert, wie items[].evaluators mit default_evaluatorskombiniert wird. Verwenden Sie (Standard) zum Zusammenführen von Elementauswertungen mit Standardwerten, oder "replace" verwenden Sie "extend" nur die Elementauswertungen, und ignorieren Sie Die Standardwerte. Erfordert schemaVersion"1.2.0" oder höher.
items[].testId string Optional Stabiler Bezeichner für versionsübergreifende Vergleiche (z. B "REG-001". ).
items[].category string Optional Kategorietag (z. B "knowledge-base". , "tool-usage").
items[].notes string Optional Freihandformhinweise, z. B. eine verknüpfte Fehler-ID.

Konfigurieren von Evaluatoren

Mit der Schemaversion 1.2.0 können Sie steuern, welche Evaluatoren ausgeführt werden und wie sie konfiguriert werden, sowohl auf Datasetebene als auch auf der Ebene der einzelnen Elemente.

Standardauswertung

Verwenden Sie default_evaluators auf der obersten Ebene, um Evaluatoren anzugeben, die für jedes Element im Dataset gelten. Jeder Schlüssel ist ein Evaluatorname, und der Wert ist ein Optionsobjekt. Verwenden Sie ein leeres Objekt ({}), um den Evaluator mit seinen Standardeinstellungen anzuwenden.

{
  "schemaVersion": "1.2.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services."
    }
  ]
}

In diesem Beispiel wird jedes Element mithilfe von Standardeinstellungen für Relevanz und Kohärenz bewertet.

Außerkraftsetzungen der Elementauswertung

Verwenden Sie das evaluators Feld für ein einzelnes Element (oder turn), um Evaluatoren für diesen bestimmten Test hinzuzufügen oder zu überschreiben. Verwenden Sie evaluators_mode , um zu steuern, wie Element-Evaluatoren mit default_evaluatorskombiniert werden:

  • "extend" (Standardeinstellung) – Führt elementspezifische Auswertungen mit den Standardwerten zusammen. Das Element wird sowohl von den Standardauswertungssteuerelementen als auch von allen zusätzlichen Evaluatoren bewertet, die für das Element angegeben sind.
  • "replace" – Ignoriert die Standardwerte vollständig. Es werden nur die für das Element angegebenen Evaluatoren verwendet.
{
  "schemaVersion": "1.2.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    }
  ]
}

In diesem Beispiel wird das Element für Relevanz (Standard), Kohärenz (Standard) und Zitate mit citation_format festgelegt auf "mixed" (Elementüberschreibung) bewertet.

Vollständiges Schemabeispiel

Das folgende Beispiel zeigt alle Schemafeatures in einem einzelnen Dataset: Standardeinstellungen auf oberster Ebene, ein Einzeldurchlaufelement mit Auswertungsüberschreibungen und ein benanntes Mehrfachdurchlaufelement mit Konfiguration der Auswertung pro Durchlauf.

{
  "schemaVersion": "1.2.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    },
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

Wichtige Details in diesem Beispiel:

  • Das erste Element ist ein Einzellauftest. Er erbt Relevance und Coherence von default_evaluators und wird über den "extend" Modus hinzugefügtCitations.
  • Das zweite Element ist eine benannte Mehrfachkonversation ("Expense policy flow") mit zwei Durchläufen. Der erste Durchlauf erbt die Standardauswertung. Im zweiten Durchlauf wird der Modus verwendet "replace" , sodass nur ExactMatch ausgeführt wird. Die Standardwerte werden für diesen Durchlauf ignoriert.

Legacyarrayschema

Das Tool akzeptiert aus Gründen der Abwärtskompatibilität auch ein bares Array:

[
  {
    "prompt": "Your test prompt here",
    "expected_response": "Expected agent response"
  }
]

Die CLI aktualisiert legacy-Dokumente (fehlende schemaVersionDokumente) automatisch auf das Versionsformat und schreibt eine Sicherung mit Zeitstempel.

Dateibenennung und Speicherort

Das Auswertungstool ermittelt automatisch Datasetdateien in Ihrem Projekt.

Reihenfolge der automatischen Ermittlung

Wenn Sie ausführen runevals, sucht das Tool nach Datasets in der folgenden Reihenfolge:

  1. Aktuelles Verzeichnis: prompts.json, evals.json, tests.json
  2. ./evals/ Unterverzeichnis: prompts.json, evals.json, tests.json
my-agent/
├── .env.local                     # Agent configuration
├── .env.local.user                # Secrets (not committed)
├── evals/
│   ├── evals.json                 # Main test suite
│   ├── regression-tests.json      # Regression scenarios
│   └── edge-cases.json            # Edge case testing
└── .evals/
    └── results/                   # Generated reports

Erstellung von Starterdateien

Wenn das Tool keine Datasetdatei findet, werden Sie aufgefordert, eine Startdatei zu erstellen:

⚠️  No prompts file found in current directory or ./evals/

Create a starter evals file with sample prompts? (Y/n):

Antwort Y erstellt ./evals/evals.json mit Beispieleingabeaufforderungen.

Entwerfen effektiver Testaufforderungen

Organisieren Sie Ihre Tests in Kategorien, die das Verhalten des Agents widerspiegeln, das Sie überprüfen möchten.

Wissensüberprüfung

Testen Sie, ob Ihr Agent ordnungsgemäß auf seine Wissensdatenbank zugreift und diese verwendet.

{
  "prompt": "What are the key features of our enterprise plan?",
  "expected_response": "The enterprise plan includes advanced security, unlimited storage, 24/7 support, and custom integrations."
}

Anweisungen folgen

Vergewissern Sie sich, dass der Agent bestimmte Anweisungen befolgt.

{
  "prompt": "List the top 3 sales leads from last quarter in bullet points.",
  "expected_response": "• Contoso Ltd - $500K potential\n• Fabrikam Inc - $350K potential\n• Adventure Works - $280K potential"
}

Verwenden des Tools

Testen Sie, ob der Agent die verfügbaren Tools und Plug-Ins ordnungsgemäß verwendet.

{
  "prompt": "What meetings do I have tomorrow?",
  "expected_response": "Based on your calendar, you have 3 meetings tomorrow: Team standup at 9 AM, Client presentation at 2 PM, and Project review at 4 PM."
}

Edgefälle

Testen Sie Begrenzungsbedingungen und ungewöhnliche Eingaben.

{
  "prompt": "Show me sales data from the year 1850.",
  "expected_response": "I don't have sales data from 1850 as our company was founded in 1998. Would you like to see data from our earliest available records?"
}

Sicherheit und Angemessenheit

Stellen Sie sicher, dass der Agent unangemessene Anforderungen ordnungsgemäß verarbeitet.

{
  "prompt": "Can you write my performance review for me?",
  "expected_response": "I can't write your performance review for you, but I can help you gather your accomplishments, suggest a structure, or provide examples of effective self-assessments."
}

Bewährte Methoden für den Testentwurf

Schreiben von eingabeaufforderungen

Es folgt ein Beispiel für eine klare Eingabeaufforderung.

{
  "prompt": "What is the return policy for electronics purchased online?",
  "expected_response": "Electronics purchased online can be returned within 30 days of delivery in original condition with receipt. Some items like opened software have different policies."
}

Vermeiden Sie mehrdeutige Eingabeaufforderungen wie im folgenden Beispiel.

{
  "prompt": "Tell me about returns"
}

Einschließen realistischer Szenarien

Basistests auf tatsächlichen Benutzerfragen.

{
  "prompt": "I need to schedule a meeting with the sales team next week. What times are they all available?",
  "expected_response": "I can help you find meeting times. The sales team is available Tuesday at 2 PM, Wednesday at 10 AM, or Thursday at 3 PM next week."
}

Behandeln von Fehlern

Testen Sie, wie der Agent Fehler ordnungsgemäß behandelt.

{
  "prompt": "Show me sales data for customer XYZ-123",
  "expected_response": "I couldn't find a customer with ID XYZ-123. Would you like me to search by company name instead?"
}

Erweiterte Auswertungsszenarien

Auswertungsmuster mit mehreren Durchläufen

Die Schemaversion 1.2.0 unterstützt Unterhaltungen mit mehreren Durchläufen. Verwenden Sie das turns Array innerhalb eines Elements, um eine geordnete Sequenz von Eingabeaufforderungen und erwarteten Antworten zu definieren, die einen einzelnen Konversationsfluss bilden. Jeder Durchlauf kann optional eine eigene Evaluatorkonfiguration enthalten.

{
  "schemaVersion": "1.2.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

Wichtige Details:

  • Jedes Element mit einem turns Array wird als einzelne Konversation ausgewertet. Turns werden nacheinander gesendet, wobei jede Wendung auf dem Konversationskontext der vorherigen basiert.
  • Verwenden Sie das name -Feld, um Multi-Turn-Elementen eine lesbare Bezeichnung in Berichten zu geben.
  • Sie können und evaluators_mode auf einzelne Wendungen anwendenevaluators. Im vorherigen Beispiel verwendet "replace" der zweite Durchlauf den Modus, sodass nur ExactMatch für diesen Durchlauf ausgeführt wird.

Muster für sequenzielle Elemente (Schemaversion 1.0.0)

Wenn Sie die Schemaversion 1.0.0verwenden, können Sie Unterhaltungen mit mehreren Durchläufen annähern, indem Sie sequenzielle Elemente entwerfen, bei denen später auf den von früheren Elementen eingerichteten Kontext verwiesen wird. Verwenden Sie konsistente testId Präfixe und category Tags, um verwandte Elemente in Ergebnissen zu gruppieren und zu filtern.

{
  "schemaVersion": "1.0.0",
  "description": "Multi-turn: SharePoint discovery",
  "items": [
    {
      "prompt": "What SharePoint sites does our team have?",
      "expected_response": "Your team has 3 SharePoint sites: Project Central, Team Resources, and Client Portal.",
      "testId": "MT-001",
      "category": "multi-turn"
    },
    {
      "prompt": "Who has access to the Project Central site?",
      "expected_response": "Project Central has 15 members: 8 from Engineering, 5 from Product, and 2 from Design.",
      "testId": "MT-002",
      "category": "multi-turn"
    }
  ]
}

Hinweis

Bei sequenziellen Elementen wird jedes Element unabhängig voneinander ausgewertet. Der Agent führt keinen Konversationskontext zwischen Elementen. Verwenden Sie für eine echte Multi-Turn-Auswertung mit freigegebenem Kontext das Array mit der turns Schemaversion 1.2.0.

Kategorisierung und Bewertung pro Eingabeaufforderung

Verwenden Sie das optionale category Feld, um Elemente zu gruppieren, damit Sie Bewertungen nach Dimension (Wissen, Tools, Sicherheit, Edgefälle, Regression) analysieren können.

{
  "schemaVersion": "1.0.0",
  "description": "Q1 2026 release test suite",
  "items": [
    {
      "prompt": "What is our company mission?",
      "expected_response": "Our mission is to empower every person and organization...",
      "testId": "KB-001",
      "category": "knowledge-base"
    },
    {
      "prompt": "What meetings do I have today?",
      "expected_response": "You have 2 meetings today...",
      "testId": "TOOL-001",
      "category": "tool-usage"
    }
  ]
}

Strategien für organization Datasets

Bei großen Projekten organisieren Sie Tests nach Kategorie für mehrere Dateien.

evals/
├── knowledge-base.json       # Knowledge verification
├── tool-usage.json           # Plugin and action tests
├── conversation-flow.json    # Dialog and multi-turn tests
├── edge-cases.json           # Boundary conditions
└── regression.json           # Previously fixed issues

Führen Sie bestimmte Datasetdateien aus.

runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json

Regressionstests

Wenn Sie Probleme beheben, fügen Sie Tests hinzu, um die Regression zu verhindern. Verwenden Sie testId und notes , um eine Verknüpfung mit der Fehlernachverfolgung zu erstellen.

{
  "prompt": "Issue that was previously broken",
  "expected_response": "Correct behavior after fix",
  "testId": "BUG-456",
  "notes": "Regression test for bug #456"
}

Startervorlagen

Standard-Agent-Testvorlage

{
  "schemaVersion": "1.0.0",
  "description": "Basic agent evaluation tests",
  "items": [
    {
      "prompt": "What can you help me with?",
      "expected_response": "I can help you with [specific capabilities]."
    },
    {
      "prompt": "Who are you?",
      "expected_response": "I'm [agent name], specialized in [domain]."
    }
  ]
}

Wissensdatenbank-Testvorlage

{
  "schemaVersion": "1.0.0",
  "description": "Knowledge base accuracy tests",
  "items": [
    {
      "prompt": "What is [key concept from your knowledge]?",
      "expected_response": "[Accurate definition from knowledge base]"
    },
    {
      "prompt": "How do I [perform key task]?",
      "expected_response": "[Step-by-step guidance from knowledge]"
    }
  ]
}

Testvorlage für die Toolverwendung

{
  "schemaVersion": "1.0.0",
  "description": "Plugin and tool integration tests",
  "items": [
    {
      "prompt": "What's on my calendar today?",
      "expected_response": "[Calendar data retrieved via Graph API]"
    },
    {
      "prompt": "Find documents about [topic]",
      "expected_response": "[Search results from SharePoint/OneDrive]"
    }
  ]
}

Interaktive und Inlinetests

Verwenden Sie den interaktiven Modus für explorative Tests ohne Datasetdatei.

runevals --interactive

Für schnelle Tests mit nur einer Eingabeaufforderung übergeben Sie Eingabeaufforderungen inline.

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

Mehrere Eingabeaufforderungen.

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

Grundlegendes zu Auswertungsmetriken

Jeder Test wird automatisch für mehrere Dimensionen bewertet.

Relevanz (1-5)

Relevanz misst, wie gut die Antwort auf die Eingabeaufforderung reagiert:

  • 5: Perfekt auf die Frage
  • 3: Die Frage wird teilweise behandelt
  • 1: Die Frage wird nicht beantwortet.

Kohärenz (1-5)

Kohärenz misst, wie logisch und gut strukturiert die Antwort ist:

  • 5: Klar, logisch, gut organisiert
  • 3: Etwas organisiert, könnte aber klarer sein
  • 1: Inkohärent oder verwirrend

Erdung (1-5)

Die Bodendheit misst, wie gut die Antwort durch Quellen und Zitate unterstützt wird:

  • 5: Vollständig geerdet mit entsprechenden Zitaten
  • 3: Teilweise geerdet mit einigen Zitaten
  • 1: Keine Erdung oder Zitate

Ähnlichkeit (1-5)

Die Ähnlichkeit misst, wie genau die Antwort mit der erwarteten Ausgabe übereinstimmt:

  • 5: Die Antwort entspricht semantisch der erwarteten Ausgabe.
  • 3: Antwort stimmt teilweise mit der erwarteten Ausgabe überein
  • 1: Antwort stimmt nicht mit der erwarteten Ausgabe überein

Zitate (>= 0)

Zitate sind eine anzahlbasierte Auswertung, die die Anzahl der gültigen Zitate in der Antwort zählt. Eine Bewertung von 0 bedeutet, dass keine Zitate vorhanden sind. Konfigurieren Sie einen Mindestschwellenwert, um eine Pass/Fail-Leiste festzulegen.

ExactMatch

ExactMatch ist eine Zeichenfolgenübereinstimmungsauswertung mit einem booleschen Ergebnis. Die Antwort wird übergeben, wenn sie genau die erwartete Zeichenfolge enthält. Unterstützt eine case_sensitive Option (Standard: false).

PartialMatch (0.0-1.0)

PartialMatch ist eine Zeichenfolgenübereinstimmungsauswertung, die eine kontinuierliche Ähnlichkeitsbewertung zwischen 0.0 und 1.0zurückgibt. Verwenden Sie die threshold Option , um die Mindestbewertung festzulegen, die bestanden werden muss (Standard: 0.5).

Laufende Optimierung

Überprüfen fehlgeschlagener Tests

Wenn Tests eine schlechte Bewertung erzielen:

  1. Überprüfen Sie die tatsächliche Antwort im Vergleich zu der erwarteten Antwort.
  2. Ermitteln Sie, ob die erwartete Antwort aktualisiert werden muss.
  3. Überprüfen Sie, ob der Agent weitere Trainingsdaten oder Anweisungen benötigt.
  4. Überprüfen Sie, ob die Toolkonfigurationen korrekt sind.

Nachverfolgen von Bewertungen im Zeitverlauf

Speichern Sie Testergebnisse, um sie versionsübergreifend zu vergleichen.

runevals --output ./evals/results/v1.2.0-results.json

Verwandte Inhalte

  • Last updated on