Оцените ваше генеративное ИИ-приложение локально с помощью инструментария Azure AI Evaluation SDK.

2025-05-20

Это важно

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

Чтобы тщательно оценить производительность создаваемого приложения ИИ при применении к существенному набору данных, вы можете оценить приложение Generative AI в среде разработки с помощью пакета SDK для оценки ИИ Azure. Учитывая тестовый набор данных или целевой объект, результаты генеративного приложения ИИ количественно измеряются как на основе математических метрик, так и при помощи средств оценки качества и безопасности, поддерживаемых ИИ. Встроенные или пользовательские оценщики могут предоставлять исчерпывающую информацию о возможностях и ограничениях приложения.

В этой статье вы узнаете, как запускать вычислители в одной строке данных, более крупный тестовый набор данных в целевом объекте приложения с встроенными вычислителями с помощью пакета SDK для оценки ИИ Azure локально, а затем отслеживать результаты и журналы оценки в проекте ИИ Azure.

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

Сначала установите пакет оценщиков из пакета SDK для оценки ИИ Azure:

pip install azure-ai-evaluation

Замечание

Дополнительные сведения см. в справочной документации по API для пакета SDK для оценки ИИ Azure.

Встроенные оценщики

Категория	Оценщиков
Общее назначение	`CoherenceEvaluator`, `FluencyEvaluator`, `QAEvaluator`
Подобие текста	`SimilarityEvaluator`, `F1ScoreEvaluator`, `BleuScoreEvaluator`, `GleuScoreEvaluator`, `RougeScoreEvaluator`, `MeteorScoreEvaluator`
поколениеRetrieval-Augmented (RAG)	`RetrievalEvaluator`, `DocumentRetrievalEvaluator`, `GroundednessEvaluator`, `GroundednessProEvaluator`, `RelevanceEvaluator`, `ResponseCompletenessEvaluator`
Риск и безопасность	`ViolenceEvaluator`, `SexualEvaluatorSelfHarmEvaluatorHateUnfairnessEvaluatorIndirectAttackEvaluatorProtectedMaterialEvaluatorUngroundedAttributesEvaluatorCodeVulnerabilityEvaluatorContentSafetyEvaluator`
Агентный	`IntentResolutionEvaluator`, `ToolCallAccuracyEvaluator`, `TaskAdherenceEvaluator`
Azure OpenAI	`AzureOpenAILabelGrader` `AzureOpenAIStringCheckGrader`, `AzureOpenAITextSimilarityGrader`, `AzureOpenAIGrader`

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

Требования к данным для встроенных оценщиков

Встроенные вычислители могут принимать пары запросов и ответов, список бесед в jsonl формате или оба варианта.

Поддержка беседы и однократных взаимодействий с текстом	Поддержка беседы и одноходовой поддержки текста и изображения	Поддержка только одного поворота текста
`GroundednessEvaluator`, `GroundednessProEvaluator`, `RetrievalEvaluatorDocumentRetrievalEvaluatorRelevanceEvaluatorCoherenceEvaluatorFluencyEvaluatorResponseCompletenessEvaluatorIndirectAttackEvaluatorAzureOpenAILabelGraderAzureOpenAIStringCheckGraderAzureOpenAITextSimilarityGraderAzureOpenAIGrader`	`ViolenceEvaluator`, `SexualEvaluator`, `SelfHarmEvaluator`, `HateUnfairnessEvaluator`, `ProtectedMaterialEvaluator`, `ContentSafetyEvaluator`	`UngroundedAttributesEvaluator`, `CodeVulnerabilityEvaluator`, `ResponseCompletenessEvaluatorSimilarityEvaluatorF1ScoreEvaluatorRougeScoreEvaluatorGleuScoreEvaluatorBleuScoreEvaluatorMeteorScoreEvaluatorQAEvaluator`

Замечание

Вычислители качества с поддержкой ИИ, за исключением SimilarityEvaluator поля причины. Они используют методы, в том числе цепочку мыслей, чтобы создать объяснение оценки. Поэтому они потребляют больше токенов при генерации в результате повышения качества оценки. В частности, для генерации оценщиков значение max_token было установлено на 800 для всех оценщиков с поддержкой ИИ (и 1600 для RetrievalEvaluator для обработки более длительных входных данных).

Замечание

Для оценки Azure OpenAI требуется шаблон, описывающий, как входные столбцы преобразуются в реальные входные данные, которые использует оценщик. Пример. Если у вас есть два входных данных с именем "query" и "response", а также шаблон, который был отформатирован следующим образом: {{item.query}}то будет использоваться только запрос. Аналогичным образом вы могли бы использовать {{item.conversation}} для приёма входных данных разговора, но способность системы обрабатывать их будет зависеть от того, как вы настроите остальную часть оценщика, чтобы ожидать этот ввод.

Дополнительные сведения о требованиях к данным для агентических вычислителей см. в описании локальной оценки агента с помощью пакета SDK для оценки ИИ Azure.

Поддержка одного поворота текста

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

from azure.ai.evaluation import RelevanceEvaluator

query = "What is the cpital of life?"
response = "Paris."

# Initializing an evaluator
relevance_eval = RelevanceEvaluator(model_config)
relevance_eval(query=query, response=response)

Для выполнения пакетных вычислений с помощью локальной оценки или отправки набора данных для выполнения облачной оценки необходимо представить набор данных в .jsonl формате. Предыдущие одноэтапные данные (пара запросов и ответа) эквивалентны строке набора данных, как показано ниже (мы показываем три строки в качестве примера):

{"query":"What is the capital of France?","response":"Paris."}
{"query":"What atoms compose water?","response":"Hydrogen and oxygen."}
{"query":"What color is my shirt?","response":"Blue."}

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

Запрос: запрос, отправленный в генеративное приложение ИИ
Ответ: ответ на запрос, созданный приложением сгенерированного ИИ
Контекст: источник, на основе которого создан ответ (т. е. основные документы)
Эталонная истина: ответ, сгенерированный пользователем или человеком как истинный ответ.

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

Поддержка текстовых бесед

Для оценщиков, поддерживающих текстовые диалоги, вы можете предоставить conversation в качестве входного параметра словарь Python со списком messages (которые включают content, role, и, при необходимости, context).

Пример диалога в два хода на Python:

conversation = {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": None
        }
        ]
}

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

{"conversation":
    {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": null
        }
        ]
    }
}

Наши оценщики понимают, что первая очередь беседы предоставляет допустимые query из user, context из assistant, и response из assistant в формате запрос-ответ. Затем беседы оцениваются по каждому ходу, и результаты суммируются и усредняются по всем ходам для оценки бесед.

Замечание

На втором этапе, даже если context является null или отсутствующим ключом, он интерпретируется как пустая строка, а не как ошибка, что может привести к вводящим в заблуждение результатам. Настоятельно рекомендуется проверить данные оценки в соответствии с требованиями к данным.

Ниже приведен пример GroundednessEvaluator в режиме беседы.

# Conversation mode
import json
import os
from azure.ai.evaluation import GroundednessEvaluator, AzureOpenAIModelConfiguration

model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ.get("AZURE_ENDPOINT"),
    api_key=os.environ.get("AZURE_API_KEY"),
    azure_deployment=os.environ.get("AZURE_DEPLOYMENT_NAME"),
    api_version=os.environ.get("AZURE_API_VERSION"),
)

# Initializing Groundedness and Groundedness Pro evaluators
groundedness_eval = GroundednessEvaluator(model_config)

conversation = {
    "messages": [
        { "content": "Which tent is the most waterproof?", "role": "user" },
        { "content": "The Alpine Explorer Tent is the most waterproof", "role": "assistant", "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight." },
        { "content": "How much does it cost?", "role": "user" },
        { "content": "$120.", "role": "assistant", "context": "The Alpine Explorer Tent is $120."}
    ]
}

# alternatively, you can load the same content from a .jsonl file
groundedness_conv_score = groundedness_eval(conversation=conversation)
print(json.dumps(groundedness_conv_score, indent=4))

Для результатов беседы результаты каждого хода хранятся в списке, а общая оценка 'groundedness': 4.0 беседы усредняется по ходам.

{
    "groundedness": 5.0,
    "gpt_groundedness": 5.0,
    "groundedness_threshold": 3.0,
    "evaluation_per_turn": {
        "groundedness": [
            5.0,
            5.0
        ],
        "gpt_groundedness": [
            5.0,
            5.0
        ],
        "groundedness_reason": [
            "The response accurately and completely answers the query by stating that the Alpine Explorer Tent is the most waterproof, which is directly supported by the context. There are no irrelevant details or incorrect information present.",
            "The RESPONSE directly answers the QUERY with the exact information provided in the CONTEXT, making it fully correct and complete."
        ],
        "groundedness_result": [
            "pass",
            "pass"
        ],
        "groundedness_threshold": [
            3,
            3
        ]
    }
}

Замечание

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

Для оценщиков, поддерживающих беседы для изображений и мультимодальных изображений и текста, можно передать URL-адреса изображений или изображения в кодировке Base64 в conversation.

Ниже приведены примеры поддерживаемых сценариев:

Несколько изображений с вводом текста для генерации изображения или текста.
Только текстовый ввод для генерации изображений
Только данные изображений для генерации текста

from pathlib import Path
from azure.ai.evaluation import ContentSafetyEvaluator
import base64

# instantiate an evaluator with image and multi-modal support
safety_evaluator = ContentSafetyEvaluator(credential=azure_cred, azure_ai_project=project_scope)

# example of a conversation with an image URL
conversation_image_url = {
    "messages": [
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "You are an AI assistant that understands images."}
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Can you describe this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/68/178268-050-5B4E7FB6/Tom-Cruise-2013.jpg"
                    },
                },
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "The image shows a man with short brown hair smiling, wearing a dark-colored shirt.",
                }
            ],
        },
    ]
}

# example of a conversation with base64 encoded images
base64_image = ""

with Path.open("Image1.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

conversation_base64 = {
    "messages": [
        {"content": "create an image of a branded apple", "role": "user"},
        {
            "content": [{"type": "image_url", "image_url": {"url": f"data:image/jpg;base64,{base64_image}"}}],
            "role": "assistant",
        },
    ]
}

# run the evaluation on the conversation to output the result
safety_score = safety_evaluator(conversation=conversation_image_url)

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

Только один обмен (беседа может иметь только одно сообщение пользователя и одно сообщение помощника)
Беседа может иметь только одно системное сообщение
Объем полезных данных беседы должен быть меньше 10 МБ (включая изображения)
Абсолютные URL-адреса и образы в кодировке Base64
Несколько изображений за один раз
ФОРМАТы ФАЙЛОВ JPG/JPEG, PNG, GIF

Настройка

Для оценщиков качества с поддержкой ИИ, кроме GroundednessProEvaluator (предварительная версия), необходимо указать модель GPT (gpt-35-turbo, gpt-4, gpt-4-turbo, gpt-4o или gpt-4o-mini) в качестве судьи для выставления оценок данным. Мы поддерживаем схему конфигурации моделей как для Azure OpenAI, так и для OpenAI. Мы рекомендуем использовать модели GPT, которые уже не находятся в стадии предварительного просмотра, для лучшей производительности и распознаваемых ответов нашими оценочными инструментами.

Замечание

Настоятельно рекомендуется заменить gpt-3.5-turbo на gpt-4o-mini для вашей модели оценщика, так как последние дешевле, более эффективные и такие же быстрые согласно OpenAI.

Убедитесь, что у вас есть по крайней мере Cognitive Services OpenAI User роль для ресурса Azure OpenAI, чтобы выполнять вызовы вывода данных с помощью ключа API. Дополнительные сведения о разрешениях см. в статье о разрешениях для ресурса Azure OpenAI.

Всем оценщикам рисков и безопасности и GroundednessProEvaluator (предварительная версия): вместо развертывания GPT в model_config вы должны предоставить свои сведения azure_ai_project. Этот проект предоставляет доступ к сервису оценки производительности бэкенда через ваш проект Azure AI.

Подсказки для встроенных оценщиков с поддержкой ИИ

Мы открываем промпты наших оценщиков качества в библиотеке оценаторов и репозитории Python SDK для оценки ИИ Azure для прозрачности, за исключением специальных оценщиков безопасности и GroundednessProEvaluator (основанных на технологии безопасности содержимого ИИ Azure). Эти запросы служат в качестве инструкций для языковой модели для выполнения задачи оценки, которая требует четкого определения метрики и связанных с ней рубрик оценки. Мы настоятельно рекомендуем пользователям настраивать определения и оценочные критерии в соответствии с конкретными сценариями. См. подробности в пользовательских оценщиках.

Составные оценщики

Составные оценщики — это встроенные инструменты, которые объединяют отдельные метрики качества или безопасности, чтобы легко предоставить широкий спектр метрик в готовом виде как для пар запрос-ответ, так и для сообщений чата.

Составной вычислитель	Содержит	Описание
`QAEvaluator`	`GroundednessEvaluator`, `RelevanceEvaluator`, `CoherenceEvaluator`, `FluencyEvaluator`, `SimilarityEvaluator`, `F1ScoreEvaluator`	Объединяет все вычислители качества для единого вывода объединенных метрик для пар запросов и ответов.
`ContentSafetyEvaluator`	`ViolenceEvaluator` `SexualEvaluator`, `SelfHarmEvaluator`, `HateUnfairnessEvaluator`	Объединяет всех оценщиков безопасности для единого результата объединенных метрик для пар запросов и ответов.

Локальная оценка для тестовых наборов данных с помощью `evaluate()`

После проверки встроенных или пользовательских оценщиков на одной строке данных можно объединить несколько оценщиков с помощью evaluate() API на всем тестовом наборе данных.

Необходимые действия по настройке проектов Azure AI Foundry

Если вы впервые запускаете оценки и регистрируете его в проекте Azure AI Foundry, вам может потребоваться выполнить несколько дополнительных действий по настройке.

Создайте и подключите учетную запись хранения к проекту Azure AI Foundry на уровне ресурса. Этот шаблон Bicep подготавливает и подключает учетную запись хранилища к вашему проекту Foundry с помощью аутентификации по ключу.
Убедитесь, что подключенная учетная запись хранения имеет доступ ко всем проектам.
Если вы подключили учетную запись хранения с помощью Microsoft Entra ID, убедитесь, что вы предоставили разрешения MSI (Microsoft Identity) для владельца данных Storage Blob как вашей учетной записи, так и ресурса проекта Foundry на портале Azure.

Оцените на наборе данных и запишите результаты в Azure AI Foundry

Чтобы evaluate() мог правильно анализировать данные, необходимо указать сопоставление столбцов, чтобы сопоставить столбец из набора данных с ключевыми словами, принимаемыми оценщиками. В этом случае мы указываем сопоставление данных для query, responseа также context.

from azure.ai.evaluation import evaluate

result = evaluate(
    data="data.jsonl", # provide your data here
    evaluators={
        "groundedness": groundedness_eval,
        "answer_length": answer_length
    },
    # column mapping
    evaluator_config={
        "groundedness": {
            "column_mapping": {
                "query": "${data.queries}",
                "context": "${data.context}",
                "response": "${data.response}"
            } 
        }
    },
    # Optionally provide your Azure AI Foundry project information to track your evaluation results in your project portal
    azure_ai_project = azure_ai_project,
    # Optionally provide an output path to dump a json of metric summary, row level data and metric and Azure AI project URL
    output_path="./myevalresults.json"
)

Подсказка

Получите содержимое свойства result.studio_url, чтобы ссылкой просмотреть сохраненные результаты оценки в вашем проекте Azure ИИ.

Оценщик выводит результаты в словаре, который содержит агрегированные metrics данные и метрики, относящиеся к уровню строк. Пример выходных данных:

{'metrics': {'answer_length.value': 49.333333333333336,
             'groundedness.gpt_groundeness': 5.0, 'groundedness.groundeness': 5.0},
 'rows': [{'inputs.response': 'Paris is the capital of France.',
           'inputs.context': 'Paris has been the capital of France since '
                                  'the 10th century and is known for its '
                                  'cultural and historical landmarks.',
           'inputs.query': 'What is the capital of France?',
           'outputs.answer_length.value': 31,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'Albert Einstein developed the theory of '
                            'relativity.',
           'inputs.context': 'Albert Einstein developed the theory of '
                                  'relativity, with his special relativity '
                                  'published in 1905 and general relativity in '
                                  '1915.',
           'inputs.query': 'Who developed the theory of relativity?',
           'outputs.answer_length.value': 51,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'The speed of light is approximately 299,792,458 '
                            'meters per second.',
           'inputs.context': 'The exact speed of light in a vacuum is '
                                  '299,792,458 meters per second, a constant '
                                  "used in physics to represent 'c'.",
           'inputs.query': 'What is the speed of light?',
           'outputs.answer_length.value': 66,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'}],
 'traces': {}}

Требования к `evaluate()`

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

Формат данных

evaluate() API принимает только данные в формате JSONLines. Для всех встроенных оценщиков evaluate() требуются данные в следующем формате с необходимыми полями ввода. См. предыдущий раздел о необходимых входных данных для встроенных вычислителей. Пример одной строки может выглядеть следующим образом:

{
  "query":"What is the capital of France?",
  "context":"France is in Europe",
  "response":"Paris is the capital of France.",
  "ground_truth": "Paris"
}

Формат параметра оценивателя

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

Оценщик	параметр ключевого слова
`GroundednessEvaluator`	"заземленность"
`GroundednessProEvaluator`	"groundedness_pro"
`RetrievalEvaluator`	"извлечение"
`RelevanceEvaluator`	"релевантность"
`CoherenceEvaluator`	"согласованность"
`FluencyEvaluator`	беглость
`SimilarityEvaluator`	"сходство"
`F1ScoreEvaluator`	f1-оценка
`RougeScoreEvaluator`	"rouge"
`GleuScoreEvaluator`	gleu
`BleuScoreEvaluator`	"bleu"
`MeteorScoreEvaluator`	"метеор"
`ViolenceEvaluator`	"насилие"
`SexualEvaluator`	"сексуальный"
`SelfHarmEvaluator`	самоповреждение
`HateUnfairnessEvaluator`	ненависть_несправедливость
`IndirectAttackEvaluator`	косвенная атака
`ProtectedMaterialEvaluator`	защищённый_материал
`CodeVulnerabilityEvaluator`	уязвимость кода
`UngroundedAttributesEvaluator`	незаземлённые атрибуты
`QAEvaluator`	"qa"
`ContentSafetyEvaluator`	безопасность_контента

Ниже приведен пример настройки evaluators параметров:

result = evaluate(
    data="data.jsonl",
    evaluators={
        "sexual":sexual_evaluator
        "self_harm":self_harm_evaluator
        "hate_unfairness":hate_unfairness_evaluator
        "violence":violence_evaluator
    }
)

Локальная оценка на целевом объекте

Если у вас есть список запросов, которые вы хотите выполнить и оценить, evaluate() также поддерживает параметр target, который может отправлять запросы приложению для сбора ответов, а затем запускать функции оценки на полученных запросах и ответах.

Целевой объект может быть любым вызываемым классом в каталоге. В этом случае у нас есть скрипт askwiki.py Python с вызываемым классом askwiki() , который можно задать в качестве целевого объекта. Учитывая набор данных запросов, которые мы можем отправлять в простое askwiki приложение, мы можем оценить заземление выходных данных. Убедитесь, что в данных "column_mapping"указано правильное сопоставление столбцов. Можно использовать "default" для указания сопоставления столбцов для всех оценщиков.

Ниже приведено содержимое в файле data.jsonl:

{"query":"When was United Stated found ?", "response":"1776"}
{"query":"What is the capital of France?", "response":"Paris"}
{"query":"Who is the best tennis player of all time ?", "response":"Roger Federer"}

from askwiki import askwiki

result = evaluate(
    data="data.jsonl",
    target=askwiki,
    evaluators={
        "groundedness": groundedness_eval
    },
    evaluator_config={
        "default": {
            "column_mapping": {
                "query": "${data.queries}"
                "context": "${outputs.context}"
                "response": "${outputs.response}"
            } 
        }
    }
)

Поделиться через

Оцените ваше генеративное ИИ-приложение локально с помощью инструментария Azure AI Evaluation SDK.

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

Встроенные оценщики

Требования к данным для встроенных оценщиков

Поддержка одного поворота текста

Поддержка текстовых бесед

Поддержка бесед для изображений и многомодального текста и изображения

Настройка

Подсказки для встроенных оценщиков с поддержкой ИИ

Составные оценщики

Локальная оценка для тестовых наборов данных с помощью evaluate()

Необходимые действия по настройке проектов Azure AI Foundry

Оцените на наборе данных и запишите результаты в Azure AI Foundry

Требования к evaluate()

Формат данных

Формат параметра оценивателя

Локальная оценка на целевом объекте

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

Обратная связь

Дополнительные ресурсы

Локальная оценка для тестовых наборов данных с помощью `evaluate()`

Требования к `evaluate()`