將自訂評估工具新增至您的代理程式評估

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 欄位、模型參數、範本語法和支援提供者的完整清單,請參閱下列資源:

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