CLI-Referenz für Microsoft 365 Copilot-Bewertungen

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.

CLI v1 verwendet das npm-Tag latest . CLI v2 verwendet preview und wertet auch Copilot-Antworten aus, die Plug-Ins verwenden. In Version 2 wertet eine Ausführung ohne konfigurierte Agent-ID den Microsoft 365 Copilot Chat aus. Beispiele für Vorschausetup und Schema v2 finden Sie unter Tool-Call-Evaluatoren.

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

Warnung

Die debug Ebene kann unformatierte API-Nutzlasten und Antwortdaten in der Konsolenausgabe enthalten. Die Schwärzung erfolgt musterbasiert und erfasst möglicherweise nicht alle personenbezogenen Daten oder Anmeldeinformationen. Geben Sie die Debugausgabe nicht ohne manuelle Überprüfung öffentlich frei.

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

Lassen Sie für v2-Vorschau-Plug-In-Szenarien diese Option weg, und entfernen Sie M365_AGENT_ID ein Legacy AGENT_ID aus Ihrer Shell und geladenen Umgebungsdateien.

--list-tools <agent-id> (v2 Vorschau)

Listen Sie Zustimmungsbezeichner und kopierbereite Evaluatoridentitäten für die Aktionen eines deklarativen Agenten auf. Diese Option wird für eigenständige Plug-Ins nicht unterstützt. Dynamisch erkannte Tools werden möglicherweise nicht angezeigt. Bestätigen Sie ihre Identität nach diagnostics.tool_calls einer Bewertung.

npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

Eigenständige Namen für Plug-In-Zustimmungen und die dreiteilige Evaluator-Identität finden Sie unter Suchen von Tool-Call-Namen.

--evaluate-only <file>

Bewerten Sie gespeicherte Antworten und verfügbare Diagnosen neu, ohne Eingabeaufforderungen auszuführen. Jeder Gegenstand oder Zug muss einen responseenthalten. Konfigurieren Sie einen Richter, wenn Sie LLM-basierte Bewerter auswählen; Die Microsoft 365-Ausführungsauthentifizierung ist nicht erforderlich.

runevals --evaluate-only results\captured-responses.json --output results\rescored.html

Die erneute Bewertung von Toolaufrufen erfordert eine CLI v2-Vorschau und aufbewahrte Toolaufruf-Beweise. Weitere Informationen finden Sie unter Diagnose und Auswertung gespeicherter Antworten.

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

Variable Beschreibung Beispiel
TENANT_ID Microsoft Entra-Mandanten-ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT Microsoft Foundry-Projektendpunkt für die LLM-basierte Bewertung. Nicht erforderlich für die rein deterministische Auswertung. https://<account>.services.ai.azure.com/api/projects/<project>

Optionale Variablen

Variable Beschreibung Standard
M365_AGENT_ID Agent-ID, die ausgewertet werden soll Automatisch erkannt von M365_TITLE_ID
M365_TITLE_ID Agenttitel-ID (Agents Toolkit) Keine
AZURE_AI_MODEL_NAME Modell für Auswertungen gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS true Auf "Beibehaltene Diagnosen" festlegen. Schwärzt keine Eingabeaufforderungen, Antworten, Auswertungsoptionen oder systemeigenen Validierungsmeldungen. Unterdrückte Beweise können nicht wiedergegeben werden. Nicht festlegen

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

Debugmodus

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

Code Bedeutung
0 Erfolgreich
1 Allgemeiner Fehler
2 Ungültige Argumente
3 Fehler bei der Umgebungskonfiguration
4 Agent nicht gefunden
5 Authentifizierungsfehler
10 Fehler bei der Einrichtung der Python-Umgebung

Problembehandlung

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