エージェント評価にカスタム エバリュエーターを追加する

Microsoft 365 Copilot Evaluations CLI (@microsoft/m365-copilot-eval) には、組み込みのエバリュエーターのセットが含まれています。 組み込みのエバリュエーターがシナリオをカバーしていない場合は、 カスタムエバリュエーター を作成して、規制コンプライアンス、ブランド トーン、カスタムの関連性ルーブリックなどのドメイン固有の基準に対してエージェントの応答をスコアリングできます。

2種類のカスタムエバリュエーターが存在し、CLIはそれらを自動的に区別します。

  • LLM 審査員の評価者 (<name>.py と <name>.prompty) は、モデルを呼び出して応答をスコアリングします。 Microsoft Foundry 構成が必要で、1 から 5 のスケールを使用します。
  • コードのみ (LLM 以外) のエバリュエーター (<name>.py のみ、 <name>.promptyなし) は、モデル呼び出しのない純粋な Python チェックです。たとえば、"応答に禁止用語が含まれている場合は失敗します。"Microsoft Foundry の設定は必要なく、数値スコアを返すことができます。

独自のカスタム エバリュエーターを使用するには、プロジェクトのルート (CLI を実行するディレクトリ) に custom-evaluators/ フォルダーを作成し、エバリュエーターごとに 1 つのサブフォルダーを追加します。 実行時に、CLI は自動的に <your_project>/custom-evaluators/ をスキャンし、評価ドキュメントが参照するエバリュエーターのみを読み込みます。

フォルダーのレイアウト

各カスタム エバリュエーターは、それぞれ独自のサブフォルダーにあります。 LLM ジャッジ エバリュエーターは 2 つのファイルで構成されます。コードのみのエバリュエーターは、単なる .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、 Coherence、 Groundedness、 Similarity、 ToolCallAccuracy、 Citations、 ExactMatch、 PartialMatch、 RetrievalQuery、 RetrievalResult。 組み込みエバリュエーターのドメイン調整バージョンを作成するには、その名前のプレフィックスを付けます (たとえば、relevanceではなくdomain_relevance)。

LLM 審査員の評価者の作成者

LLM ジャッジ エバリュエーターには 2 つのファイルがあります。ジャッジ プロンプトを定義する .prompty ファイルと、それを実行する .py ラッパーです。

.prompty ファイル

.promptyファイルは、LLM ジャッジ プロンプトです。 ---区切り記号の上の YAML フロントマターにモデル構成があり、その下に system: セクションと user: セクションがあります。 本文で{{var}}として参照される変数は、ラッパーがプロンプト フローに渡すキーワード (keyword)引数にマップされます。

最小限の 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}}

テンプレートが使用するすべての変数をリストするフロントマターで inputs: ブロックを宣言する必要があります。 これがない場合、プロンプトフローはすべての引数キーワード (keyword)フィルター処理し、テンプレートは空の{{var}}置換でレンダリングされます。モデルには空白のプロンプトが表示され、エラーまたはナンセンスなスコアが表示されます。 各入力には type: 値が必要ですが、通常は string値です。

注

プロンプトフロー ランタイムは prompt を内部パラメーターとして予約するため、プロンプト テンプレートで {{prompt}} (および 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 キーを評価者のフォルダー名に書き換えるため、スコアは JSON、CSV、および HTML レポートに <folder_name> として表示されます。

__call__をtry/exceptで包む必要はありません。 ラッパーが例外を発生させると、CLI はそれをキャッチし、残りの実行が続行されている間、そのエバリュエーターの error 結果を出力します。 エラー メッセージを自分で制御するには、専用のエラー チャネルを介して辞書を返します ( error メッセージのみが保持され、他のキーは削除されます)。

{ "error": "<explanation>" }

スコアの制約

LLM ジャッジ エバリュエーターの場合、 score は [1, 5] の範囲内の整数である必要があります (組み込みの LLM エバリュエーターと同じ 1 から 5 のスケール)。 数学的に整数である浮動小数点値 ( 4.0 など) は受け入れられ、正規化されます。 この範囲外の値、数値以外の値、または欠落している score キーは、 error 結果を生成し、他のエバリュエーターで評価の実行が続行されます。

使用しないコンストラクター パラメーターを吸収する

フレームワークは常に threshold と options を __init__ (さらに LLM 審査員の評価者用の model_config ) に渡します。 Python では、__init__が呼び出されたすべてのキーワード (keyword)を受け入れる必要がありますが、無視した名前を付ける必要はありません。 実際に使う場合のみパラメーターに名前を付けます。 **_ キャッチ オールで他のものを吸収します。

# 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",
        }

キャッチ オールなしにパラメーターのサブセットに名前を付けないでください。 たとえば、フレームワークがまだ threshold= を渡し、それを受け入れるものは何もないため、def __init__(self, *, options=None) は TypeError を発生させます。 修正するには、 **_ (または名前 threshold) を追加します。

キーワード引数の規則

CLI は、次の固定キーワード (keyword)引数セットを使用して __call__ メソッドを呼び出します。 4 つすべてが、テスト対象のエージェントではなく、評価者 (LLM ジャッジ) に渡されます。

引数 説明 判事での一般的な使用
prompt エージェントに送信されるユーザーの質問または指示。 応答性を確認します。
response エージェントの実際の回答 (採点されるもの)。 評価の件名。
expected_response expected_response フィールドからの参照または理想的な回答。 参照に対する精度をチェックします。
context 根拠付けまたはソース資料 回答は、 context 分野から忠実である必要があります。 地に足がついていない (矛盾や幻覚がないこと) を確認してください。

prompt、expected_response、および context 引数は、評価ドキュメントの現在のアイテム (またはターン) から直接取得されます。 response引数はエージェントの実際の出力であり、CLI がテスト対象のエージェントにpromptを送信するときにキャプチャされます。 特に、 context は裁判官のみにとって根拠であり、エージェントはそれを見たり取得したりすることはありません。

評価ドキュメントでは、 expected_response フィールドと context フィールドはオプションです。 存在しない場合、CLI は空の文字列を渡します。 CLI は常に 4 つの引数をすべて渡すため、使用する引数を宣言し、残りを **_ で吸収します。 **_ catch-all を指定せずに 4 つのいずれかを省略する __call__ メソッドはTypeErrorを発生させ、そのエバリュエーターは error 結果をレポートします。

load_flowに向けてmodel_configを準備する

promptflow.client.load_flow ランタイムでは、適切な接続クラス (AzureOpenAI または OpenAI) を選択するために、構成辞書に type フィールドが必要です。 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 のままにしておくことです。 次に、フレームワークは、score (1) が threshold (1) 以上の場合に result = "pass" を導き出し、score (0) が threshold (1) 未満の場合に"fail"を導出します。

コードのみのエバリュエーターの __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 判事 (.py + .prompty) コード専用 (.py のみ)
__init__ 引数 model_config, threshold, options threshold、 options ( model_configなし)
score 整数 1 から 5 任意の数値、1 - 5 のクランプなし (通常は 0 または 1)
既定のしきい値 3 1
Foundry の構成 必須 必須ではありません

結果コントラクト

フレームワークは、両方の種類のエバリュエーターの result と threshold を所有します。 成功した場合は {"score", "reason"} だけを返します。フレームワークは result = "pass" if score >= threshold else "fail" を派生させて thresholdアタッチします。 失敗を通知するには、例外を発生させるか、 {"error": "<msg>"}を返します。

フレームワークは score >= threshold時に合格するため、スコアが高いほど良い方向にする必要があります。 既定の非 LLM しきい値 1 では、ブール値の結果を 1 (合格) または 0 (失敗) としてエンコードします。 スコアが使用するスケールに一致するように評価ドキュメントのしきい値を設定します。コードのみのエバリュエーターには [1, 5] 制約はありません。 採点チェックの場合は、小数点を返し、小数点しきい値を設定します。 たとえば、 [0, 1] で比率を返す部分一致エバリュエーターは、70% の一致を要求するように threshold: 0.7 を設定します。

ヒント

.prompty ファイルが欠落している場合、エバリュエーターはコードのみのエバリュエーターに自動的に変換されるため、CLI は誤って省略されたプロンプトを防ぎます。.py のみのエバリュエーターのコードが LLM 機構 (load_flow、promptflow、model_config、または .prompty) を参照している場合、CLI はプロンプト ファイルを忘れた可能性があることを示唆する警告をログに記録します。 警告によって実行がブロックされることはありません。

評価ドキュメントからのカスタム エバリュエーターの参照

組み込みのエバリュエーターと同様に、カスタム エバリュエーターを evaluators マップに追加します。 LLM ジャッジ エバリュエーターのしきい値は既定で 3 (1 から 5 のスケール)、コードのみのエバリュエーターでは 1 です。 異なるカットオフが必要な場合は、しきい値を明示的に設定します。

{
  "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 }
        }
      }
    }
  ]
}

evaluators_mode (extend または replace) を組み込みのエバリュエーターとまったく同じように使用して、カスタム エバリュエーターを既定値と共に実行するか、既定値を置き換えるかを制御します。 詳細については、「 エバリュエーターの構成」を参照してください。

セキュリティ モデル

カスタム エバリュエーターは、CLI 自体と同じアクセス許可で実行されます。 プロジェクトに追加する前に、カスタム エバリュエーターでコードを確認します - Python では何でも実行できます。

.prompty 形式に関する詳細情報

.prompty形式は、LLM プロンプトのオープンな Microsoft 標準です。 frontmatter フィールド、モデル パラメーター、テンプレート構文、サポートされるプロバイダーの完全な一覧については、次のリソースを参照してください。

model.parameters ブロックは Chat Completions API に直接渡されるため、temperature、max_tokens、top_p、response_format、seed、stop などのパラメーターがすべて使用可能です。

トラブルシューティング

次の表を使用して、カスタム エバリュエーターの一般的な問題を解決します。

現象 考えられる原因と次の手順
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 を実行します。