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_]*$(유효한 식별자: 문자로 시작하고 그 뒤에 문자, 숫자 또는 밑줄이 오름)과 일치해야 합니다. - 이름은 기본 제공 계산기 이름(대/소문자 구분)과 충돌해서는 안 됩니다.
RelevanceCoherenceGroundednessSimilarityToolCallAccuracyCitationsExactMatchPartialMatchRetrievalQueryRetrievalResult기본 제공 계산기의 도메인 맞춤화 버전을 만들려면 해당 이름 접두사(예:domain_relevance보다는relevance)를 붙입니다.
LLM 심사위원 평가자 작성자
LLM 판사 평가자에는 판사 프롬프트를 정의하는 파일과 .py 이를 실행하는 래퍼라는 .prompty 두 개의 파일이 있습니다.
.prompty 파일
.prompty 파일은 LLM 판사 프롬프트입니다. 구분 기호 system:user: 위에 --- YAML 프런트매터에 모델 구성이 있고 그 아래에 섹션이 있습니다. 본문에서 참조되는 변수는 {{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 되므로 프롬프트 템플릿에서 (및 inputs.prompt 선언)을 사용하지 {{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>",
# }
...
프레임워크는 and 를 threshold소유 result 하고 연결threshold하므로 result = "pass" if score >= threshold else "fail" 반환하지 않습니다. 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 하고 전달합니다 __init__ (LLM 심사위원 평가자의 경우 포함 model_configoptions). 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",
}
catch-all 없이 매개 변수의 하위 집합에 이름을 지정하지 마세요. 예를 들어 def __init__(self, *, options=None) 프레임워크가 여전히 통과 threshold= 하고 아무것도 허용하지 않기 때문에 , 발생합니다TypeError. (또는 이름 threshold)을 추가 **_ 하여 수정합니다.
키워드 인수 규칙
CLI는 다음과 같은 고정된 키워드(keyword) 인수 집합을 사용하여 메서드를 __call__ 호출합니다. 네 가지 모두 테스트 중인 에이전트가 아닌 평가자(LLM 판사)에게 전달됩니다.
| 인수 | 설명 | 판사에서의 일반적인 사용 |
|---|---|---|
prompt |
에이전트에 전송된 사용자의 질문 또는 지침입니다. | 응답성을 확인합니다. |
response |
에이전트의 실제 답변(점수가 매겨지는 항목). | 평가 대상입니다. |
expected_response |
현장의 expected_response 참조 또는 이상적인 답변입니다. |
참조에 대한 정확도를 확인합니다. |
context |
현장에서 답변 context 이 충실해야 하는 기초 또는 소스 자료. |
근거를 확인합니다(모순이나 환각 없음). |
prompt, expected_response, 및 context 인수는 평가 문서의 현재 항목(또는 차례)에서 직접 가져옵니다. 인수는 response CLI가 테스트 중인 에이전트에 전송 prompt 될 때 캡처되는 에이전트의 실제 출력입니다. 특히 판 context 사만을 위한 근거입니다 - 에이전트는 그것을 보거나 검색하지 않습니다.
and context 필드는 expected_response 평가 문서에서 선택 사항입니다. 없는 경우 CLI는 빈 문자열을 전달합니다. CLI는 항상 네 개의 인수를 모두 전달하므로 사용하는 인수를 선언하고 나머지는 로 흡수합니다.**_ catch-all raise TypeError없이 **_ 네 가지 중 하나를 생략하고 평가자가 __call__ 결과를 보고하는 error 메서드입니다.
load_flow을 위한 model_config 준비
런타임은 promptflow.client.load_flow 올바른 연결 클래스를AzureOpenAI 선택하기 위해 구성 dict의 필드가 type 필요합니다( 대 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: 0 실패를 반환 score: 1 하고 기본 임계값인 1 그대로 두는 것입니다. 그런 다음 프레임워크는 (1)이 (1)보다 threshold 크거나 같고 (0)이 (1)보다 threshold 작을 때 score 도출 result = "pass"score"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 구성 | 필수 | 필수가 아닙니다. |
결과 계약
프레임워크는 두 종류의 평가자 모두를 소유 resultthreshold 합니다. 성공하면 그냥 {"score", "reason"}반환합니다. 프레임워크 result = "pass" if score >= threshold else "fail"threshold는 . 실패를 알리려면 예외를 발생시키거나 {"error": "<msg>"}반환합니다.
프레임워크는 다음과 같이 score >= threshold통과하기 때문에 점수는 높을수록 좋도록 방향이 지정되어야 합니다. 기본 비LLM 임계값을 1사용하여 부울 결과를 (통과) 또는 0 (실패)로 1 인코딩합니다. 평가 문서에서 점수가 사용하는 척도와 일치하도록 임계값을 설정합니다. 코드 전용 평가자에는 제약이 없습니다 [1, 5] . 채점된 검사의 경우 소수 점수를 반환하고 소수 임계값을 설정합니다. 예를 들어 비율 [0, 1] 을 반환하는 부분 일치 평가자는 70% 일치가 필요하도록 설정됩니다 threshold: 0.7 .
팁
누락된 .prompty 파일은 자동으로 평가자를 코드 전용 평가자로 바꾸기 때문에 CLI는 실수로 생략된 프롬프트를 방지합니다. 전용 평가자의 코드가 LLM 기계(load_flow, promptflow, model_config, 또는 .prompty)를 참조하는 경우 .pyCLI는 프롬프트 파일을 잊어버렸을 수 있음을 나타내는 경고를 기록합니다. 경고는 실행을 차단하지 않습니다.
평가 문서에서 사용자 지정 계산기 참조
기본 제공 평가자와 마찬가지로 맵에 evaluators 사용자 지정 평가자를 추가합니다. 임계값은 3 기본적으로 LLM 심사자 평가자(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 }
}
}
}
]
}
기본extend 제공 계산기를 사용하는 것과 정확히 ( 또는 replace)를 사용하여 evaluators_mode 사용자 지정 계산기가 기본값과 함께 실행되는지 아니면 기본값을 대체할지 제어합니다. 자세한 내용은 계산기 구성을 참조하세요.
보안 모델
사용자 지정 계산기는 CLI 자체와 동일한 권한으로 실행됩니다. 프로젝트에 추가하기 전에 사용자 지정 계산기에서 코드를 검토합니다. Python이 할 수 있는 모든 작업을 수행할 수 있습니다.
.prompty 형식에 대한 자세한 정보
형식은 .prompty LLM 프롬프트에 대한 공개 Microsoft 표준입니다. 프런트매터 필드, 모델 매개 변수, 템플릿 구문 및 지원되는 공급자의 전체 목록은 다음 리소스를 참조하세요.
- prompty.ai - 개요 및 방법 가이드입니다.
- microsoft/prompty - 원본 및 TypeSpec 스키마.
블록은 model.parameters Chat Completions API로 바로 전달되므로 , seedmax_tokenstop_presponse_format와 stop 같은 temperature매개 변수를 모두 사용할 수 있습니다.
문제 해결
다음 표를 사용하여 일반적인 사용자 지정 계산기 문제를 resolve합니다.
| 증상 | 가능한 원인 및 다음 단계 |
|---|---|
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 누락된 종속성입니다. 오류 메시지에는 근본적인 예외가 포함됩니다. |
결과가 이유와 함께 표시됨 errorcould not parse score |
모델이 올바른 형식의 JSON을 반환하지 않았습니다. 프롬프트에 (또는 동등한 JSON 스키마)가 있고 response_format: { type: json_object } 템플릿에서 명시적으로 셰이프를 요청 {"score": ..., "reason": ...} 하는지 확인합니다. |
더 풍부한 로그의 경우 CLI를 .--log-level debug