智能 智能 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 配置,可以返回任何数值分数。
要使用自己的自定义评估器, custom-evaluators/ 请在项目的根目录 (你从) 运行 CLI 的目录创建一个文件夹,并为每个评估器添加一个子文件夹。 在运行时,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 frontmatter 中具有模型配置,然后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}}
您必须在 frontmatter 中声明一个 inputs: 块,其中列出模板使用的每个变量。 如果没有它,promptflow 会过滤掉所有关键字 (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 将结果合并到统一输出时,CLI 会将键重写 score 为评估程序的文件夹名称,因此分数的显示方式与 JSON、CSV 和 HTML 报告中相同 <folder_name> 。
无需在 __call__ .try/except 如果包装器引发异常,CLI 会捕获它并发出 error 该评估程序的结果,同时运行的其余部分继续。 要自行控制错误消息,请通过专用错误通道返回 dict, (仅保留消息 error ;删除任何其他键) :
{ "error": "<explanation>" }
分数约束
对于 LLM 法官评估程序 score ,必须是与内置 LLM 评估程序) (范围为 1-5 的整 [1, 5] 数。 数学上为整数的浮点值 (例如, 4.0) 被接受并规范化。 此范围之外的任何内容、非数值或缺少 score 的键都会产生结果 error ;评估运行将继续与其他计算器一起运行。
吸收不使用的构造函数参数
该框架始终通过并thresholdoptions传递给 __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",
}
不要在没有 catch-all 的情况下命名参数的子集。 例如, def __init__(self, *, options=None) 提出 TypeError,因为框架仍然通过 threshold= 并且没有任何内容接受它。 添加 **_ (或命名 threshold) 以修复该问题。
关键字参数约定
CLI 使用以下一组固定关键字 (keyword) 参数调用__call__您的方法。 这四个信息都将传递给 LLM 评委) (评估员,而不是被测代理。
| 参数 | 定义 | 法官的典型用法 |
|---|---|---|
prompt |
发送给代理的用户问题或指示。 | 检查响应能力。 |
response |
代理的实际答案 (被评分) 的内容。 | 评估的主题。 |
expected_response |
来自 expected_response 现场的参考或理想答案。 |
根据引用检查准确性。 |
context |
接地或源材料答案应该忠实于,来自 context 现场。 |
检查脚踏实地 (没有矛盾或幻觉) 。 |
prompt、 和expected_responsecontext参数直接来自评估文档中的当前项 (或转) 。
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以及 "fail" (0) 小于 threshold (1) 时score,框架派生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 法官 (.py + .prompty) |
仅代码 (.py) |
|---|---|---|
__init__ 参数 |
model_config, threshold, options |
threshold, options (无 model_config) |
score |
整数 1-5 | 任何数字,没有 1-5 个夹具 (通常为 0 或 1) |
| 默认阈值 | 3 | 1 |
| 铸造厂配置 | 必需 | 非必需 |
结果协定
该框架拥有resultthreshold这两种类型的评估程序。 成功时,返回 just {"score", "reason"};框架派生并 result = "pass" if score >= threshold else "fail" 附加 threshold。 要发出失败信号,请引发异常或返回 {"error": "<msg>"}。
分数必须定向,以便越高越好,因为框架在 .score >= threshold 将默认非 LLM 阈值 1,将布尔值结果编码为 1 (通过) 或 0 (失败) 。 设置评估文档中的阈值,以匹配分数使用的任何比例 - [1, 5] 对于仅代码评估程序没有约束。 对于评分检查,返回分数并设置分数阈值。 例如,返回比率 [0, 1] 的部分匹配计算器将设置为 threshold: 0.7 需要 70% 的匹配。
提示
由于缺少.prompty的文件以无提示的方式将评估程序转换为仅代码评估程序,因此 CLI 可防止意外省略提示:如果仅适用评估程序的代码引用 LLM 机制 (load_flow、 promptflow或 model_config.prompty) ,则 .pyCLI 会记录一条警告,表明你可能忘记了提示文件。 警告从不会阻止运行。
从评估文档引用自定义赋值器
将自定义赋值器添加到地图, 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 }
}
}
}
]
}
evaluators_mode 像使用内置计算器一样使用 (extend 或 replace) 来控制自定义计算器是与默认值一起运行还是替换它们。 有关详细信息,请参阅 配置评估程序。
安全模型
自定义计算器以与 CLI 本身相同的权限运行。 在任何自定义评估器中添加代码之前,请先查看它 - 它可以执行 Python 可以执行的任何操作。
了解有关 .prompty 格式的详细信息
该 .prompty 格式是用于 LLM 提示的开放 Microsoft 标准。 有关 frontmatter 字段、模型参数、模板语法和支持的提供程序的完整列表,请参阅以下资源:
- prompty.ai - 概述和操作指南。
- microsoft/prompty - 源和 TypeSpec 架构。
该model.parameters块直接传递到对话助手完成 API,因此 、 max_tokens、 seedtop_presponse_format、 和 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.