Microsoft 365 Copilot 評估 CLI 參考

本文提供命令的完整 runevals 命令列參考,它是套件的一部分 @microsoft/m365-copilot-eval 。

劇情簡介

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

描述

runevals此命令會使用 Foundry 雲端評估和內建指標Microsoft傳送測試提示和評分回應來評估Microsoft 365 Copilot代理程式。 該工具支持從 JSON 文件、內嵌提示和交互式測試進行批量評估。

CLI v1 使用 npm latest 標籤。 CLI v2 使用 preview 並也會評估使用外掛程式的 Copilot 回應。 在 v2 中,在沒有設定代理程式識別碼的情況下執行會評估 Microsoft 365 Copilot Chat。 如需預覽設定和結構描述 v2 範例,請參閱 工具呼叫評估工具。

選項

-V, --version

輸出 CLI 工具的版本號碼。

範例:

runevals --version

輸出:

1.15.0

--log-level [level]

設定記錄詳細層級。 可用層級: debug、 info、 warning。 error

  • 預設值:當您使用沒有值的旗標時,預設為 info。
  • 偵錯:詳細偵錯資訊,包括 API 承載。
  • 資訊:有關評估進度的一般資訊。
  • 警告:僅顯示警告訊息。
  • 錯誤: 僅錯誤訊息。

範例:

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

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

警告

該 debug 層級可能在主控台輸出中包含原始 API 承載和回應資料。 密文是以模式為基礎,可能無法擷取所有 PII 或認證。 未經人工檢閱的情況下,請勿公開共用偵錯輸出。

--prompts <prompts...>

直接在命令列上指定一或多個提示,以便快速測試,而不需要建立檔案。

範例:

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

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

--expected <responses...>

提供預期的回應,以伴隨以 指定的 --prompts提示。 回應數必須與提示數相符。

範例:

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

多個提示和回應:

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

--prompts-file <file>

指定包含測試提示的自訂 JSON 檔案。 此檔案會覆寫自動探索。

範例:

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

檔案格式:

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

如需完整的資料集結構描述,請參閱 資料集結構描述和測試設計。

-o, --output <file>

指定輸出檔案的路徑和格式。 格式由副檔名決定。

支援的格式:

  • .html - HTML 報告 (預設,在瀏覽器) 中自動開啟
  • .json - JSON 結果
  • .csv - CSV 試算表

範例:

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

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

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

預設行為:

如果沒有 ,命令 --output會將結果儲存至 ./.evals/YYYY-MM-DD_HH-MM-SS.html。

-i, --interactive

進入手動提示輸入和測試的互動模式。

範例:

runevals --interactive

在互動式模式中,系統會提示您一次輸入一個提示,因此您可以執行探勘測試。

--m365-agent-id <id>

覆寫代理程式識別碼以評估特定代理程式。 測試多個代理程式或無法自動偵測代理程式識別碼時,此參數非常有用。

範例:

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

客服專員識別碼格式:

  • 使用者範圍: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • 租用戶範圍: T_agent-name.declarativeAgent

針對 v2 預覽外掛程式案例,請省略此選項,並從殼層和載入的環境檔案中移除 M365_AGENT_ID 和舊版 AGENT_ID 。

--list-tools <agent-id> (v2 預覽)

列出宣告式代理程式動作的同意識別碼和可複製的評估者身分識別。 獨立外掛程式不支援此選項。 動態探索的工具可能不會出現;在評估後確認 diagnostics.tool_calls 他們的身分。

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

如需獨立外掛程式同意名稱和由三部分組成的評估者身分識別,請參閱 尋找工具呼叫名稱。

--evaluate-only <file>

重新評分已儲存的回應和可用的診斷,而不執行提示。 每個項目或回合都必須包含一個 response。 如果您選取以 LLM 為基礎的評估工具,請設定判斷;不需要 Microsoft 365 執行驗證。

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

工具呼叫重新評分需要 CLI v2 預覽和保留的工具呼叫證據。 如需詳細資料,請參閱 診斷和已儲存的回應評估。

--env <environment>

指定要載入的環境設定。 此參數載 env/.env.<environment>入 。

預設值: dev (載入) env/.env.dev

範例:

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

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

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

環境檔案優先順序:

  1. .env.local (自動偵測 Agents Toolkit 專案)
  2. .env.local.user (密碼,如果存在,則自動載入)
  3. env/.env.<environment> (由) 指定--env
  4. 系統環境變數

--init-only

初始化 Python 環境並下載相依性,而不執行評估。 此選項適用於:

  • 預熱 CI/CD 管線中的快取
  • 疑難排解安裝問題
  • 在執行測試之前先驗證設定

範例:

runevals --init-only

若要進行疑難排解,請結合此選項與 --log-level debug:

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

-h, --help

顯示可用命令和選項的說明資訊。

範例:

runevals --help

快取命令

評估工具會針對 Python 執行階段和相依性使用本機快取。 這些命令可協助您管理快取。

cache-info

顯示快取 Python 環境的相關統計資料,包括大小、位置和已安裝的套件。

範例:

runevals cache-info

輸出:

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

移除快取的 Python 環境和所有下載的相依性。 疑難排解安裝問題或釋放磁碟空間時,請使用此命令。

範例:

runevals cache-clear

跟進:

清除快取之後,重新初始化:

runevals --init-only

cache-dir

列印快取目錄的絕對路徑。 此功能對於指令碼或手動檢查很有用。

範例:

runevals cache-dir

輸出:

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

在指令碼中的用法:

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

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

環境變數

此工具會從環境檔案和系統變數讀取組態。 如需取得這些值的逐步指示,請參閱 必要的環境變數。

必要變數

變數 描述 範例
TENANT_ID Microsoft Entra 租用戶識別碼 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT 用於 LLM 型評分的 Microsoft Foundry 專案端點。 僅限確定性評估不需要。 https://<account>.services.ai.azure.com/api/projects/<project>

選擇性變數

變數 描述 預設
M365_AGENT_ID 要評估的代理程式識別碼 自動偵測來源 M365_TITLE_ID
M365_TITLE_ID 代理程式標題識別碼 (Agents Toolkit) 無
AZURE_AI_MODEL_NAME 評估模型 gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS 設定為 true 省略保留的診斷。 不會修訂提示、回應、評估工具選項或原生驗證訊息。 壓制的證據無法重播。 取消設定

範例

基本用法

使用自動探索到的資料集檔案進行評估:

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

指定環境

使用生產環境設定:

runevals --env prod

自訂資料集檔案

使用特定的測試檔案:

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

內嵌測試

使用內嵌提示進行快速測試:

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

互動模式

手動輸入提示:

runevals --interactive

自訂輸出格式

產生 JSON 結果:

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

偵錯模式

使用詳細記錄執行:

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

僅限安裝程式

預先快取 Python 環境而不執行測試:

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

覆寫代理程式識別碼

測試特定代理程式:

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

組合選項

使用自訂設定進行綜合評估:

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"

結束代碼

代碼 意義
0 成功
1 一般錯誤
2 無效的引數
3 環境設定錯誤
4 找不到代理程式
5 驗證失敗
10 Python 環境設定失敗

疑難排解

有關安裝、驗證、執行階段錯誤、快取問題和 Proxy 設定的常見問題,請參閱 疑難排解 一文。