Riferimento CLI alle valutazioni di Microsoft 365 Copilot

Questo articolo fornisce informazioni di riferimento complete sulla riga di comando per il runevals comando, che fa parte del @microsoft/m365-copilot-eval pacchetto.

Sinossi

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

Descrizione

Il runevals comando valuta gli agenti di Microsoft 365 Copilot inviando richieste di test e risposte punteggio utilizzando la valutazione cloud di Microsoft Foundry e le metriche integrate. Lo strumento supporta la valutazione in batch da file JSON, prompt inline e test interattivi.

CLI v1 usa il tag npm latest . L'interfaccia della riga di comando v2 usa preview e valuta anche le risposte di Copilot che usano i plug-in. Nella versione 2, un'esecuzione senza un ID agente configurato valuta la chat di Microsoft 365 Copilot. Per la configurazione dell'anteprima e gli esempi dello schema v2, vedere Analizzatori delle chiamate agli strumenti.

Opzioni

-V, --version

Restituisce il numero di versione dello strumento CLI.

Esempio:

runevals --version

Produzione:

1.15.0

--log-level [level]

Impostare il livello di dettaglio di registrazione. Livelli disponibili: debug, info, warning, error.

  • Impostazione predefinita: quando si utilizza il flag senza un valore, il valore predefinito è .info
  • debug: informazioni di debug dettagliate, inclusi i payload delle API.
  • info: Informazioni generali sullo stato di avanzamento della valutazione.
  • avviso: solo messaggi di avviso.
  • errore: solo messaggi di errore.

Esempi:

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

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

Avviso

Il livello potrebbe includere payload API non elaborati e dati di risposta nell'output debug della console. L'oscuramento è basato su modelli e potrebbe non rilevare tutte le informazioni personali o le credenziali. Non condividere pubblicamente l'output di debug senza una revisione manuale.

--prompts <prompts...>

Specificare uno o più prompt direttamente nella riga di comando per un test rapido senza creare un file.

Esempi:

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

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

--expected <responses...>

Fornire le risposte previste per accompagnare i prompt specificati con --prompts. Il numero di risposte deve corrispondere al numero di richieste.

Esempio:

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

Più richieste e risposte:

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

--prompts-file <file>

Specifica un file JSON personalizzato contenente richieste di test. Questo file sostituisce l'individuazione automatica.

Esempio:

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

Formato del file:

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

Per lo schema completo del set di dati, vedere Schema del set di dati e progettazione del test.

-o, --output <file>

Specificare il percorso e il formato del file di output. Il formato è determinato dall'estensione del file.

Formati supportati:

  • .html - Rapporto HTML (predefinito, si apre automaticamente nel browser)
  • .json - Risultati JSON
  • .csv - Foglio di calcolo CSV

Esempi:

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

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

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

Comportamento predefinito:

Senza --output, il comando salva i risultati in ./.evals/YYYY-MM-DD_HH-MM-SS.html.

-i, --interactive

Attivare la modalità interattiva per l'immissione e il test manuali delle richieste.

Esempio:

runevals --interactive

In modalità interattiva ti viene richiesto di inserire le richieste una alla volta, in modo da poter eseguire test esplorativi.

--m365-agent-id <id>

Eseguire l'override dell'ID agente per valutare un agente specifico. Questo parametro è utile quando si testano più agenti o quando l'ID agente non può essere rilevato automaticamente.

Esempio:

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

Formati ID agente:

  • Ambito utente: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • Ambito tenant: T_agent-name.declarativeAgent

Per gli scenari di plug-in di anteprima v2, omettere questa opzione e rimuovere M365_AGENT_ID e legacy AGENT_ID dalla shell e dai file di ambiente caricati.

--list-tools <agent-id> (Anteprima V2)

Elencare gli identificatori di consenso e le identità degli analizzatori pronti per la copia per le azioni di un agente dichiarativo. Questa opzione non è supportata per i plug-in autonomi. Gli strumenti individuati dinamicamente potrebbero non essere visualizzati; Confermare la propria identità dopo diagnostics.tool_calls una valutazione.

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

Per i nomi di consenso dei plug-in autonomi e l'identità dell'analizzatore in tre parti, vedere Trovare i nomi delle chiamate degli strumenti.

--evaluate-only <file>

Ripeti l'assegnazione di un punteggio alle risposte salvate e alla diagnostica disponibile senza eseguire richieste. Ogni elemento o turno deve includere un file .response Configurare un giudice se si selezionano valutatori basati su LLM; L'autenticazione di esecuzione di Microsoft 365 non è necessaria.

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

Il nuovo punteggio delle chiamate degli strumenti richiede l'anteprima CLI v2 e l'evidenza delle chiamate degli strumenti conservata. Per informazioni dettagliate, vedere Diagnostica e valutazione delle risposte salvate.

--env <environment>

Specifica la configurazione di ambiente da caricare. Questo parametro carica env/.env.<environment>.

Impostazione predefinita: dev (caricamenti env/.env.dev)

Esempi:

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

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

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

Precedenza dei file di ambiente:

  1. .env.local (rilevato automaticamente per i progetti Agents Toolkit)
  2. .env.local.user (segreti, caricati automaticamente se presenti)
  3. env/.env.<environment> (specificato da --env)
  4. Variabili di ambiente di sistema

--init-only

Inizializza l'ambiente Python e scarica le dipendenze senza eseguire valutazioni. Questa opzione è utile per:

  • Preriscaldamento della cache nelle pipeline CI/CD
  • Risoluzione dei problemi relativi all'installazione
  • Verifica della configurazione prima di eseguire i test

Esempio:

runevals --init-only

Per la risoluzione dei problemi, combinare questa opzione con --log-level debug:

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

-h, --help

Visualizza le informazioni della Guida sui comandi e le opzioni disponibili.

Esempio:

runevals --help

Comandi della cache

Lo strumento di valutazione utilizza una cache locale per il runtime Python e le dipendenze. Questi comandi consentono di gestire la cache.

cache-info

Visualizza le statistiche sull'ambiente Python memorizzato nella cache, incluse le dimensioni, la posizione e i pacchetti installati.

Esempio:

runevals cache-info

Produzione:

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

Rimuove l'ambiente Python memorizzato nella cache e tutte le dipendenze scaricate. Usa questo comando per risolvere i problemi di installazione o liberare spazio su disco.

Esempio:

runevals cache-clear

Follow-up:

Dopo aver cancellato la cache, reinizializzare:

runevals --init-only

cache-dir

Consente di stampare il percorso assoluto della directory della cache. Questa funzionalità è utile per gli script o per l'ispezione manuale.

Esempio:

runevals cache-dir

Produzione:

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

Utilizzo negli script:

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

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

Variabili di ambiente

Lo strumento legge la configurazione dai file di ambiente e dalle variabili di sistema. Per istruzioni dettagliate su come ottenere questi valori, vedere Variabili di ambiente richieste.

Variabili necessarie

Variabile Descrizione Esempio
TENANT_ID ID tenant di Microsoft Entra xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT Endpoint del progetto Microsoft Foundry per l'assegnazione dei punteggi basata su LLM. Non necessario per la valutazione solo deterministica. https://<account>.services.ai.azure.com/api/projects/<project>

Variabili facoltative

Variabile Descrizione Impostazione predefinita
M365_AGENT_ID ID agente da valutare Rilevato automaticamente da M365_TITLE_ID
M365_TITLE_ID ID del titolo dell'agente (Agents Toolkit) Nessuno
AZURE_AI_MODEL_NAME Modello per le valutazioni gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS Impostato su true per omettere la diagnostica mantenuta. Non oscura prompt, risposte, opzioni dell'analizzatore o messaggi di convalida nativi. Le prove soppresse non possono essere riprodotte. Non impostato

Esempi

Utilizzo di base

Valutare usando il file del set di dati individuato automaticamente:

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

Specifica l'ambiente

Usa la configurazione dell'ambiente di produzione:

runevals --env prod

File di set di dati personalizzato

Usa un file di test specifico:

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

Test in linea

Test rapido con prompt incorporati:

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

Modalità interattiva

Immetti i prompt manualmente:

runevals --interactive

Formato di output personalizzato

Genera risultati JSON:

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

Modalità debug

Esecuzione con registrazione dettagliata:

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

Solo configurazione

Pre-cache dell'ambiente Python senza eseguire test:

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

ID agente di override

Testare un agente specifico:

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

Opzioni combinate

Valutazione completa con impostazioni personalizzate:

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"

Codici di uscita

Codice Significato
0 Operazione riuscita
1 Errore generale
2 Argomenti non validi
3 Errore di configurazione dell'ambiente
4 Agente non trovato
5 Errore di autenticazione
10 Errore di configurazione dell'ambiente Python

Risoluzione dei problemi

Per problemi comuni con l'installazione, l'autenticazione, gli errori di runtime, i problemi della cache e la configurazione del proxy, vedere l'articolo Risoluzione dei problemi .