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

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

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

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

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

Оценщики на основе кода

Вычислитель на основе кода — это функция 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").

Следующий пример оценивает ответы на основе длины, предпочитая ответы от 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

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

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

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

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

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

Параметры среды выполнения

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

Вычислители на основе запросов

Средство оценки на основе запроса использует шаблон запроса судьи, который 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>"
}

Параметры среды выполнения

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

Вычислители на основе конечных точек

Средство оценки на основе конечных точек делегирует оценку внешней конечной точке HTTP, которую вы владеете и работаете. Служба оценки вызывает конечную точку для каждого элемента (или пакета элементов), передавая сопоставленные входные данные в виде полезных данных JSON. Конечная точка обрабатывает данные с помощью любой выбранной логики и возвращает ответ JSON с оценками.

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

• Сетевой доступ к внешним службам или базам данных во время оценки.
• Собственные модели или конвейеры машинного обучения, размещенные в собственной инфраструктуре.
• Сложная логика оценки, превышающая ограничения для оценки на основе изолированного кода.
• Интеграция с существующими службами оценки или API.

Принцип работы

1. Вы развертываете конечную точку HTTP, которая принимает запросы POST с данными оценки.
2. Вы создаете подключение в проекте Foundry, где хранятся URL-адрес конечной точки и учетные данные проверки подлинности.
3. Вы регистрируете оценщик на основе конечной точки, ссылающийся на подключение.
4. При выполнении оценки служба разрешает подключение, вызывает конечную точку с входными данными и записывает ответ в качестве результата оценки.

Схема запроса конечной точки

Служба оценки отправляет запрос POST в конечную точку с текстом JSON, содержащими метаданные оценки и сопоставленные поля ввода.

В следующей таблице описаны поля, которые получает конечная точка:

Пример запроса:

{
  "schema_version": "0.0.1",
  "evaluator_name": "my_endpoint_evaluator",
  "evaluator_version": "1",
  "evaluation_level": "turn",
  "data": {
    "item": {
      "query": "What is the capital of France?"
    },
    "sample": {
      "response": "Paris"
    }
  }
}

Схема ответа конечной точки

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

Ответ успешного выполнения:

Конечная точка должна вернуть объект JSON, соответствующий стандартной схеме результатов оценки:

{
  "schema_version": "0.0.1",
  "score": 0.95,
  "reason": "The response accurately answers the question using the provided context.",
  "status": "completed",
  "properties": {
    "confidence": 0.87,
    "source_coverage": "full"
  },
  "threshold": 3,
  "passed": true
}

Сбой репонс:

В случае ошибки конечная точка должна вернуть объект JSON, соответствующий следующей схеме:

 {
   "schema_version": "0.0.1",
   "status": "error",
   "error": {
     "code": "500",
     "message": "Model inference failed"
   }
 }

Authentication

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

Создание подключения к конечной точке

Подключения хранят URL-адрес конечной точки и учетные данные проверки подлинности. Создайте подключение с помощью клиента управления Azure Cognitive Services:

Подключение ключа API

from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from azure.mgmt.cognitiveservices.models import ConnectionPropertiesV2BasicResource

mgmt_client = CognitiveServicesManagementClient(
    credential=credential,
    subscription_id=subscription_id,
)

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "ApiKey",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "ApiKey",
        "credentials": {
            "key": "<your-api-key>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-connection",
    connection=connection,
)

подключение Microsoft Entra ID

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "CustomKeys",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "AAD",
        "credentials": {
            "Audience": "api://<your-app-registration-client-id>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-entra-connection",
    connection=connection,
)

Для проверки подлинности Entra ID конечная точка должна быть настроена для принятия маркеров, выданных управляемым удостоверением проекта. Обычно это включает следующие действия:

• Регистрация приложения в Microsoft Entra ID для конечной точки.
• Включение простой проверки подлинности (или эквивалентной проверки маркера) в конечной точке.
• Предоставление управляемому удостоверению проекта назначения роли приложения в целевом приложении.

Регистрация вычислителя

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

endpoint_evaluator = project_client.beta.evaluators.create_version(
    name="my-endpoint-evaluator",
    evaluator_version={
        "name": "my-endpoint-evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "My Endpoint Evaluator",
        "description": "Scores responses using a custom evaluation endpoint",
        "definition": {
            "type": "endpoint",
            "connection_name": "my-endpoint-connection",
        },
    },
)

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

data_mapping Используйте поле, чтобы указать, какие поля входных данных отправляются в конечную точку:

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "endpoint_eval",
        "evaluator_name": "my-endpoint-evaluator",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "context": "{{item.context}}",
        },
    },
]

Ключи data_mapping становятся полями JSON, которые получает конечная точка. Сопоставьте их со столбцами в наборе данных оценки с помощью {{item.<field_name>}} синтаксиса.

Развертывание конечной точки

Конечная точка оценки может быть любой службой HTTP, которая принимает запросы POST и возвращает JSON. Распространенные варианты размещения включают:

• Функции Azure: упрощенное, бессерверное размещение для простой логики оценки.
• Служба приложений Azure: полное размещение веб-приложения для сложных конвейеров оценки.
• Контейнеры приложений Azure: размещение на основе контейнеров для вывода модели машинного обучения.

Конечная точка должна отвечать в течение времени ожидания службы оценки (30 секунд) и возвращать допустимый ответ JSON для каждого запроса.

Создание пользовательского вычислителя с помощью пакета 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!",
                    }
                ),
            ],
        ),
    ),
)

Получение результатов

Опрашивает выполнение оценки, пока не завершится, а затем получите результаты для каждого элемента и 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. Заполните следующие поля:

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

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

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

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

Пользовательские вычислители на уровне беседы

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

1. Задание evaluation_level="conversation" в выполнении оценки
2. grade() Проектирование функции для ожидания item["messages"] в виде массива бесед

При выполнении на уровне item беседы дикт получает полный массив сообщений беседы вместо одной пары запросов и ответа. Это позволяет создавать пользовательские метрики, которые оценивают все взаимодействие с пользователем.

Пример. Проверка соответствия на уровне сеанса

В этом примере проверяется, раскрывал ли агент обязательный отказ в любой момент во время беседы:

def grade(sample: dict, item: dict) -> float:
    """Check if agent disclosed required disclaimer during conversation."""
    messages = item.get("messages", [])
    
    for msg in messages:
        if msg.get("role") == "assistant":
            content = msg.get("content", "")
            if isinstance(content, str) and "not financial advice" in content.lower():
                return 1.0
    
    return 0.0  # Disclaimer never provided

Пример: оценка длины беседы

В этом примере оценивается беседы на основе того, разрешены ли они в целевом количестве поворотов:

def grade(sample: dict, item: dict) -> float:
    """Score based on conversation length (prefer shorter resolutions)."""
    messages = item.get("messages", [])
    
    # Count user turns (excludes system messages)
    user_turns = sum(1 for msg in messages if msg.get("role") == "user")
    
    if user_turns <= 2:
        return 1.0  # Resolved quickly
    elif user_turns <= 4:
        return 0.7  # Reasonable length
    elif user_turns <= 6:
        return 0.4  # Getting long
    else:
        return 0.2  # Too many turns

Связанный контент

• Выполнение вычислений из пакета SDK
• Встроенные вычислители