Пользовательские вычислители (предварительная версия)

Important

Элементы, помеченные (предварительная версия) в этой статье, в настоящее время находятся в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или могут иметь ограниченные возможности. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews.

Встроенные вычислители позволяют легко отслеживать качество поколений приложения. Чтобы настроить оценки, можно создать собственные вычислители на основе кода или на основе запросов.

Пользовательские вычислители позволяют определять метрики качества для конкретного домена, которые выходят за рамки встроенного каталога вычислителя. Используйте пользовательский вычислитель, когда необходимо измерять критерии, уникальные для приложения, например тон бренда, точность конкретного домена или соответствие формату выходных данных.

Вы можете создать два типа пользовательских вычислителей:

Code-based Prompt-based
Принцип работы Функция Python grade() оценивает каждый элемент с детерминированной логикой. Запрос судьи указывает LLM оценить каждый элемент.
Best for Проверки на основе правил, сопоставление ключевых слов, проверка формата, ограничения длины. Субъективные оценки качества, семантическое сходство, анализ тонов.
Scoring method Непрерывный: с плавающей запятой от 0,0 до 1,0 (выше). Порядковый номер, непрерывный или двоичный файл. Вы определяете диапазон min/max для порядковых и непрерывных показателей. Лучше для числовых показателей.
Output contract Одно значение с плавающей запятой от 0,0 до 1.0. Объект JSON с result и reason. Тип result зависит от метода оценки: целое число для порядкового номера, float для непрерывного или логического значения для двоичного файла.

После создания настраиваемого вычислителя его можно добавить в каталог вычислителя в проекте Foundry и использовать его в выполнении пакетной оценки.

Code-based evaluators

Вычислитель на основе кода — это функция Python с именем grade, которая получает два параметра дикта (sample и item) и возвращает оценку с плавающей запятой от 0,0 до 1,0 (выше). На практике доступ ко всем данным осуществляется через item:

  • Dataset evaluation: поля ввода, такие как response или ground_truth, можно получить в коде Python, например item.get("response") или item.get("ground_truth").
  • Модель или целевая оценка агента: чтобы получить созданный текст ответа, используйте item.get("sample", {}).get("output_text").

Note

В настоящее время доступ к созданному тексту ответа из модели или целевого объекта агента осуществляется через item.get("sample", {}).get("output_text"). Этот шаблон доступа подлежит изменению в будущем обновлении API.

Следующий пример оценивает ответы на основе длины, предпочитая ответы от 50 до 500 символов:

def grade(sample: dict, item: dict) -> float:
    """Score based on response length (prefer 50-500 chars)."""
    # For dataset evaluation, access fields directly from item:
    response = item.get("response", "")

    # For model/agent target evaluation, use item.get("sample") instead:
    # response = item.get("sample", {}).get("output_text", "")

    if not response:
        return 0.0

    length = len(response)
    if length < 50:
        return 0.2
    elif length > 500:
        return 0.5
    return 1.0

Note

grade() Если функция вызывает исключение или время ожидания, служба записывает результат службы как 0.0 результат и помечает его как ошибку в отчете оценки. Создайте функцию оборонительным образом— используйте try/except для рискованных операций и возвращает резервную оценку, а не позволяет распространять исключения.

Поддерживаемые пакеты и ограничения

Вычислители на основе кода выполняются в изолированной среде Python со следующими ограничениями:

  • Размер кода должен быть меньше 256 КБ.
  • Выполнение ограничено 2 минутами на вызов grading.
  • Сетевой доступ недоступен во время выполнения.
  • Ограничение памяти составляет 2 ГБ, ограничение диска составляет 1 ГБ, а ЦП ограничено 2 ядрами.

Доступны следующие сторонние пакеты:

Package Version
numpy 2.2.4
scipy 1.15.2
pandas 2.2.3
scikit-learn 1.6.1
rapidfuzz 3.10.1
sympy 1.13.3
jsonschema 4.23.0
pydantic 2.10.6
deepdiff 8.4.2
nltk 3.9.1
rouge-score 0.1.2
pyyaml 6.0.2

Корпус NLTK punkt, stopwords, wordnetomw-1.4и names предварительно загружены.

Runtime parameters

pass_threshold и deployment_name требуются в качестве параметров инициализации при создании вычислителя на основе кода. Несмотря на то, что вычислители на основе кода не вызывают LLM, схема API службы требуется deployment_name для оркестрации, выполняемой вычислением. Можно передать любое допустимое имя развертывания модели из проекта.

Prompt-based evaluators

Средство оценки на основе запроса использует шаблон запроса судьи, который llM вычисляет для каждого элемента. Переменные шаблона используют двойные фигурные скобки (например, {{query}}) и сопоставляют с полями входных данных.

Вычислители на основе запросов поддерживают три метода оценки:

  • Порядковый номер: целочисленные оценки в дискретном масштабе, определяемом (например, 1–5). Выше лучше.
  • Непрерывный: значения с плавающей запятой для точного измерения в заданном диапазоне (например, 0.0–1.0). Выше лучше.
  • Двоичный (true/false): логический результат для проверок на основе пороговых значений.

Средство оценки должно возвращать объект JSON с result и reason. Тип result соответствует методу оценки: целое число для порядкового номера, плавающее для непрерывного или логическое значение для двоичного файла.

В следующем примере запроса используется порядковая оценка (1–5) для оценки дружественности ответа:

Friendliness assesses the warmth and approachability of the response.
Rate the friendliness of the response between one and five using the following scale:

1 - Unfriendly or hostile
2 - Mostly unfriendly
3 - Neutral
4 - Mostly friendly
5 - Very friendly

Assign a rating based on the tone and demeanor of the response.

Response:
{{response}}

Output Format (JSON):
{
  "result": <integer from 1 to 5>,
  "reason": "<brief explanation for the score>"
}

Runtime parameters

Оба deployment_name и требуются в качестве параметров инициализации threshold при создании оценщика на основе запроса.

Создание пользовательского вычислителя с помощью пакета SDK

Предварительные требования и настройка

Установите пакет SDK и настройте клиент:

pip install "azure-ai-projects>=2.0.0"

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import EvaluatorCategory, EvaluatorDefinitionType
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (required for prompt-based evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Create the project client
project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Создание вычислителя на основе кода

Передайте функцию grade() в виде строки в code_text поле. Определите data_schema поля ввода, которые ожидает функция, и metrics описать оценку, возвращаемую функцией. Вычислители на основе кода используют continuous тип метрик с диапазоном от 0,0 до 1.0.

Сначала определите схему версии вычислителя:

code_evaluator = project_client.beta.evaluators.create_version(
    name="response_length_scorer",
    evaluator_version={
        "name": "response_length_scorer",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Response Length Scorer",
        "description": "Scores responses based on length, preferring 50-500 characters",
        "definition": {
            "type": EvaluatorDefinitionType.CODE,
            "code_text": (
                'def grade(sample: dict, item: dict) -> float:\n'
                '    """Score based on response length (prefer 50-500 chars)."""\n'
                '    response = item.get("response", "")\n'
                '    if not response:\n'
                '        return 0.0\n'
                '    length = len(response)\n'
                '    if length < 50:\n'
                '        return 0.2\n'
                '    elif length > 500:\n'
                '        return 0.5\n'
                '    return 1.0\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "pass_threshold": {"type": "number"},
                },
                "required": ["deployment_name", "pass_threshold"],
            },
            "metrics": {
                "result": {
                    "type": "continuous",
                    "desirable_direction": "increase",
                    "min_value": 0.0,
                    "max_value": 1.0,
                }
            },
            "data_schema": {
                "type": "object",
                "required": ["item"],
                "properties": {
                    "item": {
                        "type": "object",
                        "properties": {
                            "response": {"type": "string"},
                        },
                    },
                },
            },
        },
    },
)

Полный пример см. в примере кода Python пакета SDK.

Создание оценщика на основе запроса

Передайте запрос судьи prompt_text в поле. Определите data_schema поля ввода, которые ожидает запрос, и metrics описание метода оценки и диапазона. init_parameters Объявление развертывания модели и пороговое значение, необходимое средство оценки во время выполнения.

prompt_evaluator = project_client.beta.evaluators.create_version(
    name="friendliness_evaluator",
    evaluator_version={
        "name": "friendliness_evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Friendliness Evaluator",
        "description": "Evaluates the warmth and approachability of a response",
        "definition": {
            "type": EvaluatorDefinitionType.PROMPT,
            "prompt_text": (
                "Friendliness assesses the warmth and approachability of the response.\n"
                "Rate the friendliness of the response between one and five "
                "using the following scale:\n\n"
                "1 - Unfriendly or hostile\n"
                "2 - Mostly unfriendly\n"
                "3 - Neutral\n"
                "4 - Mostly friendly\n"
                "5 - Very friendly\n\n"
                "Assign a rating based on the tone and demeanor of the response.\n\n"
                "Response:\n{{response}}\n\n"
                "Output Format (JSON):\n"
                '{\n  "result": <integer from 1 to 5>,\n'
                '  "reason": "<brief explanation for the score>"\n}\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "threshold": {"type": "number"},
                },
                "required": ["deployment_name", "threshold"],
            },
            "data_schema": {
                "type": "object",
                "properties": {
                    "response": {"type": "string"},
                },
                "required": ["response"],
            },
            "metrics": {
                "custom_prompt": {
                    "type": "ordinal",
                    "desirable_direction": "increase",
                    "min_value": 1,
                    "max_value": 5,
                }
            },
        },
    },
)

Полный пример см. в примере prompt на основе пакета SDK Python.

Запуск оценки с помощью пользовательского вычислителя

После создания пользовательских вычислителей используйте их в ходе оценки так же, как и встроенные вычислители. Вы можете включить несколько вычислителей в один запуск.

В следующем примере выполняется как код, response_length_scorer так и запрос на основе friendliness_evaluator запроса.

Определение и запуск оценки

# Define the data schema
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "response": {"type": "string"},
        },
        "required": ["response"],
    },
)

# Reference both custom evaluators in testing criteria
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "response_length_scorer",
        "evaluator_name": "response_length_scorer",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "pass_threshold": 0.5,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "friendliness_evaluator",
        "evaluator_name": "friendliness_evaluator",
        "data_mapping": {
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "threshold": 3,
        },
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="custom-eval-test",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Run the evaluation with inline data
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="custom-eval-run-01",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileContent(
            type="file_content",
            content=[
                SourceFileContentContent(
                    item={
                        "response": "I'm sorry this watch isn't working for you. I'd be happy to help you with a replacement!",
                    }
                ),
                SourceFileContentContent(
                    item={
                        "response": "I will not apologize for my behavior!",
                    }
                ),
            ],
        ),
    ),
)

Get results

Опрашивает выполнение оценки, пока не завершится, а затем получите результаты для каждого элемента и URL-адрес отчета.

while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=eval_object.id)
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)

# Get per-item results
output_items = list(
    client.evals.runs.output_items.list(run_id=run.id, eval_id=eval_object.id)
)

print(f"Status: {run.status}")
print(f"Report: {run.report_url}")

Очистка ресурсов

Удалите версию пользовательского вычислителя и оценку, если они больше не нужны:

# Delete the custom evaluator version
project_client.beta.evaluators.delete_version(
    name="response_length_scorer",
    version=code_evaluator.version,
)

# Delete the evaluation
client.evals.delete(eval_id=eval_object.id)

Дополнительные сведения о параметрах источника данных, сопоставлениях оценщика и расширенных сценариях см. в статье "Выполнение вычислений" из пакета SDK.

Дополнительные примеры, включая перечисление, обновление и удаление вычислителей, см. в примере пакета SDK для управления каталогом Python .

Создание пользовательского вычислителя на портале

Пользовательские вычислители можно создавать непосредственно на портале Azure AI Foundry без написания кода пакета SDK.

  1. В проекте Foundry перейдите вкаталог оценщика оценки>.
  2. Выберите "Создать настраиваемый вычислитель>".
  3. Заполните следующие поля:
Field Description
Name Уникальный идентификатор для вычислителя (например, response_length_scorer).
Display name Имя, доступное для чтения человеком, показанное в каталоге оценщика.
Description Краткое описание того, что измеряет средство оценки.
Type На основе кода или на основе запроса. Определяет, предоставляется ли функция Python grade() или запрос судьи.
Scoring method Вычислители на основе кода используют непрерывные (0.0–1.0). Вычислители на основе запросов могут использовать порядковый номер, непрерывную или двоичную оценку с пользовательским диапазоном.
Код или запрос Для кода напишите grade() функцию в редакторе кода. Для запроса на основе запроса напишите запрос судьи в редакторе запросов. Примеры и требования см. в разделах о вычислителях на основе кода и на основе запросов.

Использование пользовательского вычислителя в оценке портала

После создания пользовательского вычислителя используйте его в ходе оценки на портале:

  1. В проекте Foundry перейдите к разделу "Оценка " и нажмите кнопку "Создать".
  2. Следуйте инструкциям мастера создания оценки. На шаге "Критерии" выберите "Добавить вычислителя".
  3. Выберите пользовательский вычислитель из каталога вычислителя.
  4. Укажите необходимые параметры инициализации. Для оценщиков на основе запросов укажите развертывание модели и пороговое значение. Для вычислителей на основе кода укажите пороговое значение.
  5. Завершите работу мастера и запустите запуск оценки.

Подробные инструкции по выполнению вычислений на портале см. на портале.

Related content

  • Last updated on