CLI-Referenz für Agent-Evaluierungen

Dieser Artikel enthält eine vollständige Befehlszeilenreferenz für den Befehl, der runevals Teil des @microsoft/m365-copilot-eval Pakets ist.

Zusammenfassung

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

Beschreibung

Der runevals Befehl wertet Microsoft 365 Copilot-Agents aus, indem Testprompts gesendet und Bewertungsantworten mithilfe der Microsoft Foundry Cloud-Auswertung und integrierten Metriken bewertet werden. Das Tool unterstützt die Stapelauswertung von JSON-Dateien, Inline-Eingabeaufforderungen und interaktive Tests.

Optionen

-V, --version

Gibt die Versionsnummer des CLI-Tools aus.

Beispiel:

runevals --version

Ausgabe:

1.15.0

--log-level [level]

Legen Sie den Ausführlichkeitsgrad für die Protokollierung fest. Verfügbare Ebenen: debug, info, warning, error.

• Standard: Wenn Sie das Flag ohne Wert verwenden, wird standardmäßig .info
• debug: Detaillierte Debuginformationen, einschließlich API-Nutzlasten.
• info: Allgemeine Informationen zum Evaluationsfortschritt.
• Warnung: Nur Warnmeldungen.
• Fehler: Nur Fehlermeldungen.

Beispiele:

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

--prompts <prompts...>

Geben Sie eine oder mehrere Eingabeaufforderungen direkt in der Befehlszeile an, um schnell zu testen, ohne eine Datei zu erstellen.

Beispiele:

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

--expected <responses...>

Geben Sie die erwarteten Antworten für Eingabeaufforderungen an, die mit angegeben sind --prompts. Die Anzahl der Antworten muss mit der Anzahl der Eingabeaufforderungen übereinstimmen.

Beispiel:

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

Mehrere Eingabeaufforderungen und Antworten:

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

--prompts-file <file>

Geben Sie eine benutzerdefinierte JSON-Datei mit Testprompts an. Diese Datei setzt die automatische Ermittlung außer Kraft.

Beispiel:

runevals --prompts-file ./tests/my-custom-tests.json

Dateiformat:

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

Das vollständige Datasetschema finden Sie unter Datasetschema und Testdesign.

-o, --output <file>

Geben Sie den Ausgabedateipfad und das Format an. Das Format wird durch die Dateierweiterung bestimmt.

Unterstützte Formate:

• .html - HTML-Bericht (Standard, öffnet sich automatisch im Browser)
• .json - JSON-Ergebnisse
• .csv - CSV-Tabelle

Beispiele:

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

Standardverhalten:

Ohne --outputspeichert der Befehl die Ergebnisse in ./.evals/YYYY-MM-DD_HH-MM-SS.html.

-i, --interactive

Aktivieren Sie den interaktiven Modus für die manuelle Eingabe von Eingabeaufforderungen und Tests.

Beispiel:

runevals --interactive

Im interaktiven Modus werden Sie aufgefordert, mehrere Eingabeaufforderungen einzugeben, sodass Sie explorative Tests durchführen können.

--m365-agent-id <id>

Außerkraftsetzung der Agent-ID, um einen bestimmten Agent zu bewerten. Dieser Parameter ist nützlich, wenn mehrere Agents getestet werden oder wenn die Agent-ID nicht automatisch erkannt werden kann.

Beispiel:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Agent-ID-Formate:

• Benutzerbezogen: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Mandantenbezogen: T_agent-name.declarativeAgent

--env <environment>

Geben Sie die zu ladende Umgebungskonfiguration an. Dieser Parameter lädt env/.env.<environment>.

Standard: dev (wird env/.env.devgeladen)

Beispiele:

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

Rangfolge der Umgebungsdateien:

1. .env.local (automatisch erkannt für Agents Toolkit-Projekte)
2. .env.local.user (Geheimnisse, automatisch geladen, falls vorhanden)
3. env/.env.<environment> (angegeben durch --env)
4. Systemumgebungsvariablen

--init-only

Initialisiert die Python-Umgebung und lädt Abhängigkeiten herunter, ohne Auswertungen auszuführen. Diese Option ist nützlich für:

• Vorwärmen des Caches in CI/CD-Pipelines
• Behandeln von Installationsproblemen
• Überprüfen der Einrichtung vor dem Ausführen von Tests

Beispiel:

runevals --init-only

Kombinieren Sie zur Problembehandlung diese Option mit --log-level debug:

runevals --init-only --log-level debug

-h, --help

Zeigt Hilfeinformationen zu verfügbaren Befehlen und Optionen an.

Beispiel:

runevals --help

Cachebefehle

Das Auswertungstool verwendet einen lokalen Cache für die Python-Laufzeit und -Abhängigkeiten. Diese Befehle helfen Ihnen bei der Verwaltung des Caches.

cache-info

Zeigt Statistiken zur zwischengespeicherten Python-Umgebung an, einschließlich Größe, Speicherort und installierter Pakete.

Beispiel:

runevals cache-info

Ausgabe:

Cache Information

Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed

Last updated: 2026-04-10 14:23:15

cache-clear

Entfernt die zwischengespeicherte Python-Umgebung und alle heruntergeladenen Abhängigkeiten. Verwenden Sie diesen Befehl bei der Behebung von Installationsproblemen oder beim Freigeben von Speicherplatz.

Beispiel:

runevals cache-clear

Nachbereitung:

Initialisieren Sie nach dem Löschen des Caches erneut:

runevals --init-only

cache-dir

Gibt den absoluten Pfad zum Cacheverzeichnis aus. Dieses Feature ist für Skripts oder die manuelle Überprüfung nützlich.

Beispiel:

runevals cache-dir

Ausgabe:

C:\Users\YourName\.m365-copilot-eval\cache

Verwendung in Skripts:

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

Umgebungsvariablen

Das Tool liest die Konfiguration aus Umgebungsdateien und Systemvariablen. Schrittweise Anweisungen zum Abrufen dieser Werte finden Sie unter Erforderliche Umgebungsvariablen.

Erforderliche Variablen

Optionale Variablen

Beispiele

Grundlegende Verwendung

Auswerten mithilfe der automatisch ermittelten Datasetdatei:

cd /path/to/your-agent-project
runevals

Umgebung angeben

Konfiguration der Produktionsumgebung verwenden:

runevals --env prod

Benutzerdefinierte Datasetdatei

Verwende eine bestimmte Testdatei:

runevals --prompts-file ./tests/regression-tests.json

Inlinetests

Schnelltest mit Inline-Prompts:

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

Interaktiver Modus

Geben Sie Eingabeaufforderungen manuell ein:

runevals --interactive

Benutzerdefiniertes Ausgabeformat

JSON-Ergebnisse generieren:

runevals --output ./results/eval-$(date +%Y%m%d).json

Debug-Modus

Mit detaillierter Protokollierung ausführen:

runevals --log-level debug --output ./debug-results.json

Nur Setup

Python-Umgebung im Vor-Cache ohne Ausführen von Tests:

runevals --init-only --log-level info

Außerkraftsetzung der Agent-ID

Testen Sie einen bestimmten Agent:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Kombinierte Optionen

Umfassende Auswertung mit benutzerdefinierten Einstellungen:

runevals \
  --env staging \
  --prompts-file ./evals/full-suite.json \
  --output ./reports/staging-eval-$(date +%Y%m%d).html \
  --log-level info \
  --m365-agent-id "T_my-agent.declarativeAgent"

Exitcodes

Problembehandlung

Informationen zu häufig auftretenden Problemen mit Installation, Authentifizierung, Laufzeitfehlern, Cacheproblemen und Proxy-Setup finden Sie im Artikel zur Problembehandlung .

Verwandte Inhalte

• Übersicht über die Agent-Evaluierung CLI
• Schnellstart: Verwenden der Agent-Evaluierungs-CLI
• Datasetschema und Testdesign