Выполнение вычислений в облаке с помощью пакета SDK для Microsoft Foundry

В этой статье вы узнаете, как выполнять оценки в облаке (предварительная версия) для предварительного тестирования в тестовом наборе данных.

Используйте облачные оценки для большинства сценариев, особенно при тестировании в масштабе, интеграции вычислений в конвейеры непрерывной интеграции и непрерывной доставки (CI/CD) или выполнения предварительного тестирования. Выполнение вычислений в облаке устраняет необходимость управления локальной вычислительной инфраструктурой и поддерживает крупномасштабные автоматизированные рабочие процессы тестирования. Вы также можете запланировать выполнение вычислений на регулярной основе или настроить непрерывную оценку для автоматической оценки примеров ответов агента в рабочей среде.

Результаты оценки облака хранятся в проекте Foundry. Вы можете просмотреть результаты на портале, получить их с помощью пакета SDK или перенаправить их в Application Insights при подключении. Облачная оценка поддерживает все подготовленные Microsoft встроенные оцениватели и ваши собственные пользовательские оцениватели. Оценщики управляются в каталоге оценщиков с той же проектной областью, ролевым управлением доступом.

Как работает оценка облака

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

Облачная оценка поддерживает следующие сценарии:

Для большинства сценариев требуются входные данные. Вы можете предоставить данные двумя способами:

Для каждой data_source_config оценки требуется, чтобы служба сообщила, какие поля следует ожидать в данных:

• custom — вы определяете item_schema с именами полей и их типами. Задайте значение include_sample_schematrue при использовании целевого объекта, чтобы вычислители могли ссылаться на созданные ответы.
• azure_ai_source — структура получена из службы. Установите значение "scenario" для оценки ответа агента, "responses" для "synthetic_data_gen_preview" или для красной "red_team".

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

Необходимые условия

• Проект Foundry.
• Развертывание Azure OpenAI с моделью GPT, которая поддерживает завершение чата (например, gpt-5-mini).
• Роль пользователя Azure AI в проекте Foundry.
• При необходимости можно использовать собственную учетную запись хранения для выполнения вычислений.

Начало работы

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

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

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

# 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 (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

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

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

Подготовка входных данных

Для большинства сценариев оценки требуются входные данные. Вы можете предоставить данные двумя способами:

Отправка набора данных (рекомендуется)

Отправьте JSONL или CSV-файл, чтобы создать набор данных с версиями в проекте Foundry. Наборы данных поддерживают управление версиями и повторное использование в нескольких запусках оценки. Используйте этот подход для производственного тестирования и процессов CI/CD.

Подготовьте JSONL-файл с одним объектом JSON на строку, содержащую поля, необходимые вычислителям:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

Или подготовьте CSV-файл с заголовками столбцов, соответствующими полям вычислителя:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Предоставление данных в строке

Для быстрого экспериментирования с небольшими наборами тестов предоставьте данные непосредственно в запросе на оценку с помощью file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Передайте source в качестве "source" поля в конфигурации источника данных при создании запуска. Разделы сценария используют file_id по умолчанию.

Оценка набора данных

Оцените предварительно вычисляемые ответы в JSONL-файле с помощью jsonl типа источника данных. Этот сценарий полезен, если у вас уже есть выходные данные модели и требуется оценить их качество.

Определение схемы данных и вычислителей

Укажите схему, соответствующую полям JSONL, и выберите вычислители (критерии тестирования) для выполнения. Используйте параметр data_mapping для подключения полей из ваших входных данных к параметрам оценщика с помощью синтаксиса {{item.field}}. Всегда включать data_mapping необходимые поля входных данных для каждого вычислителя. Имена полей должны совпадать с именами в файле JSONL — например, если ваши данные имеют "question" вместо "query", используйте "{{item.question}}" в сопоставлении. Сведения о необходимых параметрах для каждого оценщика см. в built-in evaluators.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "response": { "type": "string" },
          "ground_truth": { "type": "string" }
        },
        "required": ["query", "response", "ground_truth"]
      }
    },
    "testing_criteria": [
  }'

Создание оценки и запуск

Создайте эксперимент, а затем запустите выполнение для отправленного набора данных. Запуск выполняет каждый вычислитель для каждой строки в наборе данных.

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

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

# Step 1: Create the evaluation
EVAL_ID=$(curl --silent --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "response": { "type": "string" },
          "ground_truth": { "type": "string" }
        },
        "required": ["query", "response", "ground_truth"]
      }
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": { "deployment_name": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": { "deployment_name": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
          "response": "{{item.response}}",
          "ground_truth": "{{item.ground_truth}}"
        }
      }
    ]
  }' | jq -r '.id')

# Step 2: Create a run against your dataset
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-run",
    "data_source": {
      "type": "jsonl",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      }
    }
  }'

Для полного примера, который можно запустить, см. sample_evaluations_builtin_with_dataset_id.py на GitHub. Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов".

Оценка набора данных CSV

Оцените предварительно вычисляемые ответы в CSV-файле с помощью csv типа источника данных. Этот сценарий работает так же, как и оценка набора данных , но принимает CSV-файлы вместо JSONL. Используйте CSV,если данные уже в электронной таблице или табличном формате.

Подготовка CSV-файла

Создайте CSV-файл с заголовками столбцов, соответствующими полям, которые нужны вычислителям. Каждая строка представляет один тестовый случай:

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Отправка и запуск

Отправьте CSV-файл в виде набора данных, а затем создайте оценку с помощью csv типа источника данных. Определение схемы и конфигурация вычислителя такие же, как в оценках JSONL — единственное различие — это "type": "csv" в источнике данных.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов".

Целевая оценка модели

Отправьте запросы в развернутую модель во время выполнения и оцените ответы с помощью azure_ai_target_completions типа источника данных с целевым azure_ai_model объектом. Входные данные содержат запросы; Модель создает ответы, которые затем вычисляются.

Определение шаблона сообщения и целевого объекта

Шаблон input_messages управляет отправкой запросов в модель. Используется {{item.query}} для ссылки на поля из входных данных. Укажите модель для оценки и необязательных параметров выборки:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Настройка оценщиков и сопоставлений данных

Когда модель создает ответы во время выполнения, используйте {{sample.output_text}} в data_mapping, чтобы ссылаться на выходные данные модели. Используется {{item.field}} для ссылки на поля из входных данных.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Создание оценки и запуск

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "model-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "type": "template",
        "template": [
          {
            "type": "message",
            "role": "user",
            "content": {
              "type": "input_text",
              "text": "{{item.query}}"
            }
          }
        ]
      },
      "target": {
        "type": "azure_ai_model",
        "model": "gpt-5-mini",
        "sampling_params": {
          "top_p": 1.0,
          "max_completion_tokens": 2048
        }
      }
    }
  }'

Полный пример запуска см. в разделе sample_model_evaluation.py на GitHub. Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов".

Оценка целевого объекта агента

Отправьте запросы агенту Foundry и оцените ответы во время выполнения, используя azure_ai_target_completions тип источника данных с azure_ai_agent целевым назначением. Этот сценарий подходит как для агентов отклика, так и для хостинговых агентов.

Определение шаблона сообщения и целевого объекта

Шаблон input_messages управляет отправкой запросов агенту. Используется {{item.query}} для ссылки на поля из входных данных. Укажите агента для оценки по имени.

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Настройка оценщиков и сопоставлений данных

Когда агент генерирует ответы во время выполнения, используйте переменные {{sample.*}} в data_mapping для ссылки на выходные данные агента.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Создание оценки и запуск

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "type": "template",
        "template": [
          {
            "type": "message",
            "role": "developer",
            "content": {
              "type": "input_text",
              "text": "You are a helpful assistant. Answer clearly and safely."
            }
          },
          {
            "type": "message",
            "role": "user",
            "content": {
              "type": "input_text",
              "text": "{{item.query}}"
            }
          }
        ]
      },
      "target": {
        "type": "azure_ai_agent",
        "name": "my-agent",
        "version": "1"
      }
    }
  }'

Полный пример запуска см. в разделе sample_agent_evaluation.py на GitHub. Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов".

Протокол вызовов агента в хостинге

Размещенные агенты , использующие протокол вызовов, поддерживают тот же azure_ai_agent тип целевого объекта, но используют формат свободной формы input_messages . Вместо структурированного формата шаблона укажите объект JSON, который сопоставляется непосредственно с текстом запроса агента /invocations . Используйте {{item.*}} заполнители для замены полей из входных данных.

Если размещенный агент поддерживает протоколы ответов и вызовов, служба по умолчанию использует протокол вызовов.

Определение формата сообщения и целевого объекта

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Создание оценки и запуск

eval_object = client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "hosted-agent-invocations-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "message": "{{item.query}}"
      },
      "target": {
        "type": "azure_ai_agent",
        "name": "my-hosted-agent",
        "version": "1"
      }
    }
  }'

Параметры установки и сопоставления данных вычислителя совпадают с оценкой агента запроса. Используйте {{sample.output_text}} для текстового ответа агента и {{sample.output_items}} для полно структурированных выходных данных, включая вызовы инструментов.

Оценка ответа агента

Извлекайте и оценивайте ответы агента Foundry по идентификаторам ответов, используя тип источника данных azure_ai_responses. Используйте этот сценарий для оценки конкретных взаимодействий агента после их возникновения.

Идентификатор ответа — это уникальный идентификатор, возвращаемый каждый раз, когда агент Foundry создает ответ. Идентификаторы ответов можно собирать из взаимодействий агента с помощью API ответов или из журналов трассировки приложения. Укажите встроенные идентификаторы в виде содержимого файла или отправьте их в виде набора данных (см. раздел "Подготовка входных данных").

Сбор идентификаторов ответов

Каждый вызов API ответов возвращает объект ответа с уникальным id полем. Соберите эти идентификаторы из взаимодействий приложения или создайте их напрямую:

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

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

Создание оценки и запуск

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "data_source": {
      "type": "azure_ai_responses",
      "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
          "type": "file_content",
          "content": [
            {"item": {"resp_id": "resp_abc123"}},
            {"item": {"resp_id": "resp_def456"}}
          ]
        }
      }
    }
  }'

Полный пример запуска см. в разделе sample_agent_response_evaluation.py на GitHub. Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов".

Оценка искусственных данных (предварительная версия)

Создайте искусственные тестовые запросы, отправьте их в развернутую модель или агент Foundry и оцените ответы с помощью типа источника данных azure_ai_synthetic_data_gen_preview. Используйте этот сценарий, если у вас нет тестового набора данных— служба создает запросы на основе предоставленного запроса (и/или из инструкций агента), выполняет их в целевом объекте и оценивает ответы.

Как работает оценка искусственных данных

1. Служба генерирует синтетические запросы на основе ваших prompt и необязательных файлов данных начального значения.
2. Каждый запрос отправляется в указанный целевой объект (модель или агент) для создания ответа.
3. Вычислители оценивают каждый ответ с помощью созданного запроса и ответа.
4. Созданные запросы хранятся в качестве набора данных в проекте для повторного использования.

Параметры

Настройка оценщиков и сопоставлений данных

Генератор искусственных данных создает запросы в {{item.query}} поле. Целевой объект создает ответы, доступные в {{sample.output_text}}. Сопоставьте эти поля с вашими оценщиками.

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Создание оценки и запуск

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

# Step 1: Create the evaluation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Synthetic Data Evaluation",
    "data_source_config": {
      "type": "azure_ai_source",
      "scenario": "synthetic_data_gen_preview"
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
          "deployment_name": "gpt-5-mini"
        },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{sample.output_text}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{sample.output_text}}"
        }
      }
    ]
  }'

# Step 2: Create a run with synthetic data generation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "synthetic-data-evaluation",
    "data_source": {
      "type": "azure_ai_synthetic_data_gen_preview",
      "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": "gpt-5-mini",
        "output_dataset_name": "my-synthetic-dataset"
      },
      "target": {
        "type": "azure_ai_model",
        "model": "gpt-5-mini"
      }
    }
  }'

Сведения о завершении и интерпретации результатов см. в разделе "Получение результатов". Ответ содержит output_dataset_id свойство, содержащее идентификатор созданного набора данных, который можно использовать для получения или повторного использования синтетических данных.

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

После завершения выполнения оценки получите оцененные результаты и просмотрите их на портале или программным способом.

Опрос результатов

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

import time
from pprint import pprint

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)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Интерпретация результатов

Для одного примера данных все оценщики выводят следующую схему:

• Метка: двоичная метка "pass" или "fail", аналогичная выходным данным модульного теста. Используйте этот результат для упрощения сравнения между оценщиками.
• Оценка: оценка по естественной шкале каждого оценщика. Некоторые оценщики используют детализированную рубрику, выставляя оценки по 5-балльной шкале (оценщики качества) или 7-балльной шкале (оценщики безопасности содержимого). Другие, такие как оценщики текстового сходства, используют оценки F1, которые представляют собой числа в диапазоне от 0 до 1. Любой недвоичный "счёт" преобразуется в "прошёл" или "не прошёл" в поле "метка" на основе "порога".
• Пороговое значение: любые не двоичные оценки преобразуются в двоичные для определения "передано" или "отказано" на основе порогового значения по умолчанию, которое пользователь может изменить в интерфейсе SDK.
• Причина: чтобы улучшить понятность, все оценщики LLM-судья также предоставляют поле обоснования, чтобы объяснить, почему дана определенная оценка.
• Сведения: (необязательно) Для некоторых вычислителей, таких как tool_call_accuracy, может быть поле "подробности" или флаги, содержащие дополнительные сведения, которые помогут пользователям отлаживать свои приложения.

Пример выходных данных (один элемент)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Пример выходных данных (агрегат)

Для агрегированных результатов по нескольким примерам данных (набору данных) средний процент примеров с "pass" формирует процент успешности для этого набора данных.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Устранение неполадок

Выполнение работы занимает много времени

Задание оценки может оставаться в состоянии выполнения в течение длительного периода. Обычно это происходит, когда развертывание модели OpenAI Azure не имеет достаточной емкости, что приводит к повторным запросам службы.

Разрешение:

1. Отмена текущего задания оценки с помощью client.evals.runs.cancel(run_id, eval_id=eval_id).
2. Увеличьте емкость модели на портале Azure.
3. Снова запустите оценку.

Ошибки проверки подлинности

Если вы получаете 401 Unauthorized или 403 Forbidden ошибку, убедитесь, что:

• DefaultAzureCredential настроен правильно (при использовании Azure CLI запустить az login).
• У вашей учетной записи есть роль пользователя Azure AI в проекте Foundry.
• URL-адрес конечной точки проекта является правильным и включает имена учетных записей и проектов.

Ошибки формата данных

Если проверка завершается ошибкой схемы или сопоставления данных:

• Убедитесь, что в файле JSONL есть один допустимый объект JSON для каждой строки.
• Убедитесь, что имена полей в data_mapping в точности соответствуют именам полей в вашем JSONL-файле (с учетом регистра).
• Убедитесь, что item_schema свойства соответствуют полям в наборе данных.

Ошибки ограничения скорости

Создание запусков оценки ограничено по скорости на уровнях клиента, подписки и проекта. Если вы получите 429 Too Many Requests ответ:

• Проверьте заголовок ответа retry-after на рекомендуемое время ожидания.
• Просмотрите текст ответа для сведений об ограничении скорости.
• Используйте экспоненциальный откат при повторной попытке неудачных запросов.

Если задание оценки завершается ошибкой 429 во время выполнения:

• Уменьшите размер набора данных оценки или разделите его на меньшие пакеты.
• Увеличьте квоту токенов в минуту (TPM) для развертывания модели на портале Azure.

Ошибки средства оценки агентской программы

Если средство оценки агента возвращает ошибку для неподдерживаемых средств:

• Проверьте поддерживаемые средства для оценщиков агентов.
• В качестве обходного решения оберните неподдерживаемые инструменты как функции, определенные пользователем, чтобы вычислитель смог оценить их.

Связанное содержимое

• Полные рабочие примеры
• Настройка трассировки в Microsoft Foundry
• Настройка непрерывной оценки
• Просмотр результатов оценки на портале Foundry
• Начало работы с Foundry
• Справочник по REST API