Microsoft 365 Copilot評估 CLI (@microsoft/m365-copilot-eval) 包含一組內建評估工具。 當內建評估工具無法涵蓋您的案例時,您可以撰寫 自訂評估工具 ,以根據網域特定準則對客服專員回應進行評分,例如法規合規性、品牌語氣或自訂相關性評分指標。
有兩種自訂評估程式,CLI 會自動區分它們:
-
LLM 判斷評估者 (
<name>.py並<name>.prompty) 調用模型來對回應進行評分。 他們需要 Microsoft Foundry 設定並使用 1-5 比例。 -
僅程式碼 (非 LLM) 評估工具 (
<name>.py,沒有<name>.prompty) 是沒有模型呼叫的純 Python 檢查 - 例如,「如果回應包含禁止字詞,則失敗」。它們不需要 Microsoft Foundry 設定,而且可以傳回任何數值分數。
若要使用您自己的自訂評估器,請在專案根目錄 (您從) 執行 CLI 的目錄中建立資料夾 custom-evaluators/ ,並為每個評估器新增一個子資料夾。 在執行階段,CLI 會自動掃描 <your_project>/custom-evaluators/ 並僅載入評估文件參考的評估程式。
資料夾版面配置
每個自訂評估工具都位於自己的子資料夾中。 LLM 法官評估員由兩個文件組成;純程式碼評估工具只是檔案:.py
<your_project>/
custom-evaluators/
professional_tone/ # LLM-judge: has a .prompty
professional_tone.prompty # the LLM judge prompt
professional_tone.py # the Python wrapper that runs it
consistency_check/
consistency_check.prompty
consistency_check.py
forbidden_terms/ # code-only: NO .prompty
forbidden_terms.py # pure Python check, no model call
的 <name>.prompty 存在是唯一的區分因素:有了它,評估者就是 LLM 法官;沒有它,它就只有程式碼。
命名規則
- 資料夾名稱、評估程式名稱和檔案基底名稱必須完全相符。
- 名稱必須符合有效識別碼 (模式
^[a-zA-Z][a-zA-Z0-9_]*$:以字母開頭,後面接著字母、數字或底線) 。 - 名稱不得與內建評估工具名稱衝突, (不區分大小寫的) :
Relevance、、GroundednessRetrievalQueryCoherenceToolCallAccuracyRetrievalResultSimilarityCitationsExactMatchPartialMatch和 。 若要建立內建評估程式的網域量身打造版本,請以前置詞其名稱 - 例如,domain_relevance而不是relevance。
撰寫 LLM 評審評估員
LLM 法官評估工具有兩個檔案:一個 .prompty 定義法官提示的檔案,以及 .py 執行它的包裝函式。
.prompty 檔案
.prompty檔案是 LLM 法官提示。 它在分隔符上方的 --- YAML 前端具有模型配置,然後system:user:是分隔符下方的區段。 在內文中參 {{var}} 照的變數會對應至包裝函式傳遞至提示流程的關鍵字引數。
下列範例會顯示最小 professional_tone.prompty 的檔案:
---
name: professional_tone
description: Scores professional tone 1-5.
model:
api: chat
parameters:
temperature: 0.0
max_tokens: 400
response_format:
type: json_object
inputs:
user_prompt:
type: string
response:
type: string
---
system:
You score professional tone 1 (hostile) to 5 (consistently professional).
Reply with only: {"score": <int 1-5>, "reason": "<one sentence>"}
user:
# User prompt
{{user_prompt}}
# Agent response
{{response}}
您必須在 frontmatter 中聲明一個 inputs: 區塊,其中列出範本使用的每個變數。 如果沒有它,Promptflow 會篩選掉所有關鍵字引數,而您的範本會以空白 {{var}} 的替代詞呈現 - 模型會看到空白提示,而您會收到錯誤或無意義的分數。 每個輸入都需要一個 type: 值,通常是 string。
注意
promptflow 執行階段會保留 prompt 為內部參數,因此請避免 {{prompt}} 在prompty 範本中使用 (和 inputs.prompt 宣告) 。 使用不同的變數名稱, {{user_prompt}}例如 ,並讓包裝函式在呼叫提示流程時轉送該名稱下的值。
.py包裝廣告
Python 模組必須匯出類別。 CLI 會動態匯入模組,並將它找到的第一個最上層類別具現化。 班級必須符合下列合約:
class MyEvaluator:
def __init__(self, *, model_config, threshold, options=None):
# model_config: AzureOpenAIModelConfiguration
# threshold: numeric pass/fail threshold
# options: dict of extra config from the eval document
...
def __call__(
self,
*,
prompt: str = "",
expected_response: str = "",
response: str = "",
context: str = "",
**_, # accept extras for forward compatibility
) -> dict:
# On success, return a flat dict with just:
# {
# "score": <integer 1-5>,
# "reason": "<explanation>",
# }
...
架構擁有 result 和 threshold: 它衍生 result = "pass" if score >= threshold else "fail" 並附加 threshold,因此您不會傳回它們。 當 CLI 將結果合併到統一輸出時,會將金鑰重寫 score 為評估工具的資料夾名稱,因此分數會顯示為 <folder_name> JSON、CSV 和 HTML 報告中。
您不需要用 __call__/tryexcept。 如果您的包裝函式引發例外狀況,CLI 會攔截它並發出 error 該評估程式的結果,而其餘的執行會繼續執行。 若要自行控制錯誤訊息,請透過專用錯誤通道傳回字典, (只保留該 error 訊息;而刪除任何其他機碼) :
{ "error": "<explanation>" }
分數限制式
對於 LLM 法官評估工具, score 必須是與內建 LLM 評估工具) 相同的 1-5 (範圍內 [1, 5] 的整數。 數學上為整數的浮點數值 (例如, 4.0) 會接受並正常化。 此範圍之外的任何項目、非數值或遺漏 score 的索引鍵都會 error 產生結果;eval 執行會繼續與其他評估工具一起執行。
吸收您不使用的建構函式參數
該框架總是通過,thresholdoptions並且 __init__ (model_config 法學碩士法官評估員) 。 Python 要求您 __init__ 接受呼叫它的每個關鍵字,但您不必命名您要忽略的關鍵字。 只有在實際使用參數時,才為其命名。 用包羅萬象吸收 **_ 任何其他內容:
# Names only what it uses (options), absorbs the rest (threshold, and so on):
class ForbiddenTermsEvaluator:
def __init__(self, *, options=None, **_):
self._terms = (options or {}).get("terms", [])
# A check that needs no configuration at all - absorb everything:
class NonEmptyEvaluator:
def __init__(self, **_): # ignores model_config, threshold, options
pass
def __call__(self, *, response: str = "", **_) -> dict:
return {
"score": 1 if response.strip() else 0,
"reason": "non-empty" if response.strip() else "empty response",
}
請勿在沒有包羅萬象的情況下命名參數子集。 例如, def __init__(self, *, options=None) 提出 TypeError,因為框架仍然通過 threshold= 並且沒有任何東西接受它。 新增 **_ (或命名 threshold) 以修正此問題。
關鍵字引數慣例
CLI 會使用下列固定的關鍵字引數集呼叫您的 __call__ 方法。 所有四個都會傳遞給您的評估員 (LLM 法官) ,而不是傳遞給被測的代理程式。
| 引數 | 這是什麼 | 法官的常見用法 |
|---|---|---|
prompt |
使用者的問題或傳送給代理程式的指示。 | 檢查回應性。 |
response |
客服人員的實際答案 (被評分) 的東西。 | 評估的主體。 |
expected_response |
來自欄位的 expected_response 參考或理想答案。 |
根據參照檢查精確度。 |
context |
接地或來源材料 答案應該忠實於,來自 context 現場。 |
檢查腳踏實地 (沒有矛盾或幻覺) 。 |
prompt、 和expected_responsecontext引數直接來自評估文件中的目前項目 (或 turn) 。
response引數是代理程式的實際輸出,在 CLI 傳送prompt至受測代理程式時擷取。 特別是, context 僅對法官有根據——代理人永遠不會看到或檢索它。
and context 欄位在expected_response評估文件中為選用。 當它們缺席時,CLI 會傳遞一個空字串。 因為 CLI 總是傳遞所有四個參數,所以聲明您使用的參數並使用 吸收其餘參數。**_
__call__省略四個**_中之一而不進行包羅萬象引發TypeError的方法,並且該評估器報告error結果。
為load_flow準備model_config
promptflow.client.load_flow執行階段需要設定字典上的欄位type,以挑選正確的連線類別 (AzureOpenAI 而不是 OpenAI) 。 CLI 傳遞的不會 AzureOpenAIModelConfiguration 包含該欄位,因此請在呼叫 load_flow之前新增它:
prepared_config = dict(model_config)
prepared_config.setdefault(
"type",
"azure_openai" if "azure_endpoint" in prepared_config else "openai",
)
self._flow = load_flow(source=prompty_path, model={"configuration": prepared_config})
如果沒有此步驟,您會在叫用時看到誤導性錯誤 Not Support connection type None for embedding api 。
撰寫僅程式碼評估工具
純程式碼評估工具是只有 <name>.py 和沒有 <name>.prompty的資料夾。 CLI 會偵測到遺失的提示,並將評估器視為純 Python 檢查。 它從不呼叫模型,因此只使用僅程式碼評估程式的執行不需要 Microsoft Foundry 設定。
使用僅程式碼評估工具進行確定性、以規則為基礎的檢查:禁止期限掃描、正則表達式或格式驗證、長度限制、JSON 結構描述一致性等。
大部分的純程式碼評估工具都是簡單的通過/失敗檢查。 表達該檢查的慣用方式是返回 score: 1 通過和 score: 0 失敗,並保留預設閾值 1 。 當 (1) 大於或等threshold於 (1) ,score以及score"fail"當 (0) 小threshold於 1) 時,架構便會衍生 (result = "pass"。
__init__僅程式碼評估工具的方法省略:model_config
class ForbiddenTermsEvaluator:
def __init__(self, *, threshold, options=None):
self._terms = (options or {}).get("terms", [])
def __call__(self, *, response: str = "", **_) -> dict:
hit = [t for t in self._terms if t.lower() in response.lower()]
# Default threshold is 1, so 1 -> pass, 0 -> fail.
return {
"score": 0 if hit else 1,
"reason": f"Found: {', '.join(hit)}" if hit else "clean",
}
下表摘要說明僅程式碼評估工具與 LLM 判斷評估工具的差異。
| 外觀 | LLM-judge (.py + .prompty) |
僅限程式碼 (.py) |
|---|---|---|
__init__ 引數 |
model_config, threshold, options |
threshold, (options 無 model_config) |
score |
整數 1-5 | 任何數字,沒有 1-5 夾具 (通常為 0 或 1) |
| 預設信用額度 | 3 | 1 |
| 鑄造廠設定 | 必要 | 不需要 |
結果合約
該框架擁有 result 和 threshold 適用於這兩種評估者。 成功時,返回 {"score", "reason"}just ; 框架派生 result = "pass" if score >= threshold else "fail" 並附加 threshold。 若要發出失敗訊號,請引發例外狀況或傳回 {"error": "<msg>"}。
分數必須定向,以便越高越好,因為框架 score >= threshold在 . 使用預設的 1非 LLM 閾值,將布林值結果編碼為 1 (通過) 或 0 (失敗) 。 在評估文件中設置閾值以匹配您的分數使用的任何比例 - [1, 5] 僅代碼評估器沒有限制。 針對評分檢查,請傳回分數分數並設定分數閾值。 例如,傳回比率 [0, 1] 的部分比對評估工具將設定 threshold: 0.7 為需要 70% 的比對。
秘訣
因為遺失.prompty的檔案會無訊息地將評估工具變成純程式碼編輯器,因此 CLI 會防止意外省略提示:如果僅評估工具的程式碼參考 LLM 機制 (load_flow、 promptflowmodel_config、 或 .prompty) ,CLI .py會記錄警告,指出您可能忘記提示檔案。 警告永不會封鎖執行。
從評估文件參考自訂評估工具
將自訂評估工具 evaluators 新增至地圖,就像內建評估工具一樣。 對於 (1-5 等級) 的 LLM 判斷評估者和1僅使用程式碼的評估者,閾值預設為3。 如果您想要不同的截止值,請明確設定閾值:
{
"schemaVersion": "1.7.0",
"items": [
{
"prompt": "How do I file an expense report?",
"evaluators": {
"Relevance": {},
"professional_tone": { "threshold": 4 },
"consistency_check": {
"threshold": 3,
"options": { "samples": 5 }
}
}
}
]
}
(extend 或 replace) ,就像evaluators_mode使用內建評估工具一樣,控制自訂評估工具是與預設值一起執行還是取代預設值。 如需詳細資訊,請參閱 設定評估工具。
安全性模型
自訂評估工具會以與 CLI 本身相同的許可執行。 在將程式碼新增至專案之前,請先在任何自訂評估工具中檢閱程式碼 - 它可以執行 Python 可以執行的任何動作。
深入了解 .prompty 格式
此 .prompty 格式是 LLM 提示的開放式 Microsoft 標準。 如需 frontmatter 欄位、模型參數、範本語法和支援提供者的完整清單,請參閱下列資源:
- prompty.ai - 概觀和操作指南。
- microsoft/prompty - 來源和 TypeSpec 結構描述。
該model.parameters區塊會直接傳遞至 Chat Completions API,因此 、 、 max_tokensresponse_formattop_pseed、 、 等stop參數temperature都可供使用。
疑難排解
使用下表來解決常見的自訂評估工具問題。
| 問題 | 可能原因和後續步驟 |
|---|---|
Unknown evaluator '<name>' |
請檢查資料夾位於 <your_project>/custom-evaluators/<name>/,檔案基底名稱是否與資料夾名稱相符,以及您正在從專案根目錄執行 CLI。 |
Custom evaluator '<name>' is missing required file '<name>.py' |
每個評估工具資料夾都必須包含 <name>.py。
<name>.prompty只有 LLM 判斷評估者才需要檔案;對於僅代碼評估者,請省略它。 |
Custom evaluator '<name>' failed to import |
Python 語法錯誤或檔案中 .py 缺少相依性。 錯誤訊息包含基礎例外狀況。 |
結果顯示 error 原因 could not parse score |
模型未傳回語式正確的 JSON。 確認您的提示具有 response_format: { type: json_object } (或對等的 JSON 結構描述) ,且範本明確要求 {"score": ..., "reason": ...} 提供圖形。 |
如需更豐富的記錄,請使用 --log-level debug來執行 CLI 。