Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Интерфейс командной строки оценки Microsoft 365 Copilot (@microsoft/m365-copilot-eval) включает набор встроенных оценщиков. Если встроенные средства оценивания не охватывают ваш сценарий, можно создать настраиваемые оценщики для оценки ответов агентов по критериям, относящимся к конкретной области, таким как соответствие нормативным требованиям, тон бренда или настраиваемая рубрика релевантности.
Существует два типа пользовательских оценщиков, и интерфейс командной строки автоматически различает их:
-
LLM-судья-оценщики (
<name>.pyи<name>.prompty) вызывают модель для оценки ответа. Им требуется конфигурация Microsoft Foundry и шкала от 1 до 5. -
Оценщики только кода (не LLM) (
<name>.pyтолько, нет<name>.prompty) - это чистые проверки Python без вызова модели - например, "fail, if the response contains the forbidden term." Они не требуют настройки Microsoft Foundry и могут возвращать любые числовые оценки.
Чтобы использовать собственные настраиваемые средства оценивания, создайте папку custom-evaluators/ в корневой папке проекта (из каталога, из которого выполняется интерфейс командной строки) и добавьте по одной подпапке для каждого средства оценивания. Во время выполнения интерфейс командной строки сканирует <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, , ,Groundedness,CitationsPartialMatchSimilarityToolCallAccuracyExactMatchRetrievalQueryи .RetrievalResultCoherenceЧтобы создать ориентированную на домен версию встроенного средства оценивания, укажите перед его именем префикс, например,domain_relevanceвместоrelevance.
Автор: оценщик со степенью магистра права
Оценщик LLM-judge имеет два файла: .prompty файл, определяющий приглашение судьи, и .py оболочку, которая его запускает.
Файл запроса
Файл .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}}
Вы должны объявить inputs: блок в заднем элементе, в котором перечислены все переменные, используемые в шаблоне. Без этого promptflow отфильтровывает все аргументы ключевых слов, и ваш шаблон отображается с пустыми {{var}} подстановками - модель видит пустой запрос, и вы получаете ошибку или бессмысленную оценку. Для каждого ввода требуется type: значение, которым обычно stringявляется .
Примечание
Среда выполнения promptflow резервируется prompt как внутренний параметр, поэтому избегайте использования {{prompt}} (и объявления) в шаблоне inputs.prompt prompty. Используйте другое имя переменной, например {{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, поэтому вы не возвращаете их. При объединении результатов в единый вывод интерфейс командной строки score переписывает ключ в имя папки средства оценивания, поэтому оценка выглядит так, как <folder_name> в отчетах JSON, CSV и HTML.
Вам не нужно переворачивать в __call__try/except Если ваша оболочка вызывает исключение, интерфейс командной строки перехватывает его и выдает error результат для этого оценщика, пока продолжается дальнейшая работа. Чтобы управлять сообщением об ошибке самостоятельно, верните диктовку через специальный канал ошибок (сохраняется только error сообщение; все остальные клавиши опускаются):
{ "error": "<explanation>" }
Ограничения оценки
Для оценщика LLM-судьи должно быть целое число в диапазоне [1, 5] (по той же шкале от 1 до 5, score что и у встроенных оценщиков LLM). Математические целые значения числа с плавающей точкой (например, 4.0) принимаются и нормализуются. Все, что находится за пределами этого диапазона, нечисловое значение или отсутствует score ключ, возвращает error результат; выполнение оценки продолжается с другими вычислителями.
Поглощение параметров конструктора, которые вы не используете
Структура всегда проходит threshold и options к __init__ (плюс model_config для оценщиков LLM-судей). 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), чтобы исправить это.
Соглашения об использовании аргументов ключевых слов
Интерфейс командной строки вызывает ваш __call__ метод с помощью следующего фиксированного набора аргументов ключевых слов. Все четыре передаются вашему оценщику (судье LLM), а не испытуемому агенту.
| Аргумент | Описание | Типичное использование в судье |
|---|---|---|
prompt |
Вопрос или инструкция пользователя, отправленная агенту. | Проверьте скорость отклика. |
response |
Фактический ответ агента (вещь, которую забивают). | Предмет оценки. |
expected_response |
Ссылка или идеальный ответ с expected_response мест. |
Сверьте точность со ссылкой. |
context |
Обоснование или исходный материал, к которому ответ должен быть верным, с context места. |
Проверьте заземленность (нет противоречий или галлюцинаций). |
Аргументы prompt, expected_responseand context взяты непосредственно из текущего элемента (или хода) в документе оценки. Этот response аргумент — это фактические выходные данные агента, записанные при отправке prompt CLI тестируемому агенту. В частности, context является основанием только для судьи - агент никогда не видит и не восстанавливает его.
Поля expected_response and context не являются обязательными в документе eval. Если они отсутствуют, CLI передает пустую строку. Поскольку интерфейс командной строки всегда передает все четыре аргумента, объявите те, которые вы используете, и поглотите остальные с помощью **_. Метод __call__ , который пропускает одно из четырех повышений без универсального **_ повышения , TypeErrorи этот оценщик сообщает error результат.
Подготовка model_config к load_flow
Среде promptflow.client.load_flow выполнения требуется type поле в словаре конфигурации, чтобы выбрать правильный класс подключения (AzureOpenAI по сравнению с OpenAI). Поле AzureOpenAIModelConfiguration CLI не содержит этого поля, поэтому добавьте его перед вызовом 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 в заблуждение.
Создание средства оценивания только для кода
Оценщик только по коду — это папка с ключом only <name>.py и без <name>.prompty. CLI обнаруживает отсутствующую подсказку и рассматривает оценщик как чистую проверку Python. Он никогда не вызывает модель, поэтому для запуска, использующего только средства оценивания только кода, не требуется настройка Microsoft Foundry.
Используйте оценщики только кода для детерминированных проверок на основе правил: сканирование запрещенных сроков, проверка регулярных выражений или формата, ограничения длины, соответствие JSON-схеме и т. д.
Большинство оценщиков только кода представляют собой простую проверку "годен/не годен". Идиоматический способ выразить эту проверку - вернуться score: 1 для прохождения и score: 0 для сбоя, а порог по умолчанию оставить на 1 месте. Тогда структура производится result = "pass" , когда score (1) больше или равно threshold (1), а "fail" когда score (0) меньше threshold (1).
Метод __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 |
| Конфигурация литейного цеха | Обязательно | Не требуется |
Контракт результата
Структура владеет result и threshold для обоих типов оценщиков. При успехе возвращается только {"score", "reason"}; структура выводится 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 предохраняет от случайно пропущенного запроса: если .pyкод -only ссылается на механизм LLM (load_flow, promptflow, model_config, или .prompty), интерфейс командной строки регистрирует предупреждение, которое предполагает, что вы, возможно, забыли файл подсказки. Предупреждение никогда не блокирует прогон.
Ссылка на настраиваемые средства оценивания из документа оценки
Добавляйте пользовательские оценщики на evaluators карту, как и встроенные оценщики. Пороговое значение по умолчанию для 3 оценщиков LLM-judge (шкала от 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 (extendreplaceили ) точно так же, как со встроенными вычислителями, чтобы указать, будет ли пользовательский оценщик работать вместе со значениями по умолчанию или заменять их. Дополнительные сведения см. в разделе Настройка оценщиков.
Модель безопасности
Пользовательские оценщики запускаются с теми же разрешениями, что и сам интерфейс командной строки. Просмотрите код в любом пользовательском оценщике, прежде чем добавлять его в свой проект - он может делать все, что может Python.
Подробнее о формате .prompty
Формат .prompty представляет собой открытый стандарт Майкрософт для запросов LLM. Полный список полей frontmatter, параметров модели, синтаксиса шаблонов и поддерживаемых поставщиков см. в следующих ресурсах:
- prompty.ai — обзор и инструкции.
- microsoft/prompty - исходный код и схема TypeSpec.
Блок model.parameters передается прямо в Chat Completions API, поэтому такие параметры, как temperature, , max_tokenstop_p, response_formatseed, и stop все доступны.
Устранение неполадок
Чтобы устранить распространенные проблемы с настраиваемым оценщиком, используйте следующую таблицу.
| Проблема | Вероятная причина и дальнейшие действия |
|---|---|
Unknown evaluator '<name>' |
Убедитесь, что папка находится по адресу <your_project>/custom-evaluators/<name>/, что базовые имена файлов соответствуют имени папки, и что вы запускаете интерфейс командной строки из корня проекта. |
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помощью .