本文提供命令的完整 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
環境檔案優先順序:
-
.env.local(自動偵測 Agents Toolkit 專案) -
.env.local.user(密碼,如果存在,則自動載入) -
env/.env.<environment>(由) 指定--env - 系統環境變數
--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 設定的常見問題,請參閱 疑難排解 一文。