使用 Azure AI 评估 SDK 在本地评估生成 AI 应用程序（预览版）

可以通过将生成 AI 应用程序应用到大量数据集来彻底评估生成 AI 应用程序的性能。 使用 Azure AI 评估 SDK 在开发环境中评估应用程序。

当您提供测试数据集或目标时，生成式 AI 应用程序的输出将通过基于数学的指标和 AI 辅助的质量与安全评估器进行定量测量。 内置或自定义评估器可以提供对应用程序功能和限制的全面见解。

本文介绍如何在单个数据行上运行计算器，以及如何在应用程序目标上运行更大的测试数据集。 使用在本地利用 Azure AI 评估 SDK 的内置评估器。 然后，你将了解如何跟踪 Foundry 项目中的结果和评估日志。

开始

首先，从 Azure AI 评估 SDK 安装评估程序包：

pip install azure-ai-evaluation

内置评估器

内置质量和安全指标接受查询和响应对，并为特定评估员提供其他信息。

内置评估程序的数据要求

内置评估器可以接受查询和响应对、JSON Lines（JSONL）格式的对话列表，或者同时接受两者。

Azure OpenAI 评分员需要一个模板，来描述他们如何将输入列转化为评分员实际使用的输入。 例如，如果有两个输入称为 查询 和 响应，并且模板格式设置为 {{item.query}}，则仅使用查询。 同样，您可以使用类似{{item.conversation}}的内容来接受对话输入，但系统处理此输入的能力取决于您如何配置余下的系统参数以期待该输入。

有关智能体评估程序的数据要求的详细信息，请参阅评估 AI 智能体。

对文本的单轮支持

所有内置评估器接收字符串形式的查询和响应对作为单轮输入。 例如：

from azure.ai.evaluation import RelevanceEvaluator

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

# Initialize 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."}

评估测试数据集可以包含以下元素，具体取决于每个内置计算器的要求：

• 查询：发送到生成 AI 应用程序的查询。
• 响应：对生成式 AI 应用程序生成的查询的响应。
• 上下文：生成的响应所基于的源。 即基础文档。
• 基本真相：用户或人类生成的响应作为真实答案。

若要查看每个计算器需要的内容，请参阅 计算器。

文本中的对话支持

对于支持文本对话的评估器，你可以提供 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。 然后将按轮次评估对话，结果会按所有轮次聚合以得出对话分数。

对于对话模式，下面提供了一个 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"),
)

# Initialize the Groundedness evaluator:
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
        ]
    }
}

对图像及多模态文本与图像的对话支持

对于支持图像以及多模态图像和文本对话的评估程序，你可以在 conversation 中传入图像 URL 或 Base64 编码的图像。

支持的方案包括：

• 输入多个图像与文本，生成图像或文本。
• 仅限文本输入用于图像生成。
• 仅输入图像以生成文本。

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

# Create an instance of 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 MB。
• 绝对 URL 和 Base64 编码图像。
• 单轮中的多个图像。
• JPG/JPEG、PNG 和 GIF 文件格式。

设置

对于 AI 辅助质量评估器，除GroundednessProEvaluator预览版外，必须在gpt-35-turbo中指定一个 GPT 模型（gpt-4、gpt-4-turbo、gpt-4o、gpt-4o-mini或model_config）。 GPT 模型充当法官来评分评估数据。 我们同时支持 Azure OpenAI 或 OpenAI 模型配置架构。 为了获得最佳性能，并与我们的评估器产生可解析的响应，我们建议使用未处于预览状态的 GPT 模型。

对于所有风险与安全评估器和 GroundednessProEvaluator（预览版），必须提供 model_config 信息，而不是 azure_ai_project 中的 GPT 部署。 这会使用 Foundry 项目访问后端评估服务。

AI 辅助内置评估器的提示

为了提高透明度，我们将质量评估程序的提示开源于我们的评估器库和 Azure AI 评估 Python SDK 存储库，但不包括由 Azure AI 内容安全提供支持的安全评估器和 GroundednessProEvaluator。 这些提示充当语言模型执行其评估任务的说明，这需要对指标及其关联的评分标准进行人工友好的定义。 强烈建议你根据方案细节自定义定义和评分标准。 有关详细信息，请参阅 自定义评估器。

复合评估器

复合评估器是内置的评估器，结合了单个质量或安全指标。 它们可开箱即用地为查询响应对和聊天消息提供广泛的指标。

使用 evaluate() 对测试数据集进行本地评估

在单行数据上抽样检查内置或自定义评估器后，可以对整个测试数据集组合使用多个评估器和 evaluate() API。

Microsoft Foundry 项目的先决条件准备步骤

如果这是你在 Foundry 项目中首次运行评估并记录日志，可能需要执行以下设置步骤：

1. 创建存储帐户并将其连接到资源级别的 Foundry 项目。 此 bicep 模板预配存储帐户，并使用密钥身份验证将存储帐户连接到 Foundry 项目。
2. 确保连接的存储帐户有权访问所有项目。
3. 如果使用 Microsoft Entra ID 连接到存储帐户，请确保在 Azure 门户中向帐户和 Foundry 项目资源授予存储 Blob 数据所有者的 Microsoft 标识权限。

评估数据集并将结果记录到 Foundry 中。

若要确保 evaluate() API 能够正确分析数据，必须指定列映射，以便将列从数据集映射到计算器接受的关键字。 此示例指定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 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 file of metric summary, row-level data, and the metric and Foundry project URL.
    output_path="./myevalresults.json"
)

评估器输出的结果为字典形式，其中包含聚合 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() 的要求：

evaluate() API 需要特定的数据格式和计算器参数键名称才能正确显示 Foundry 项目中的评估结果图表。

数据格式

evaluate() API 仅接受 JSONL 格式的数据。 对于所有内置评估器，evaluate() 需要数据采用以下格式，并包含必要的输入字段。 请参阅 上一部分，了解内置计算器所需的数据输入。 以下代码片段展示了一行代码的示例格式：

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

评估程序参数格式

在传入内置评估器时，请在evaluators参数列表中指定正确的关键字映射。 下表显示了内置评估程序的结果记录到 Foundry 项目后要在 UI 中显示所需的关键字映射。

下面是如何设置 evaluators 参数的示例：

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

目标上的本地评估

如果有要运行和计算的查询列表，则 evaluate() API 还支持参数 target 。 此参数将查询发送到应用程序以收集答案，然后在生成的查询和响应上运行计算器。

目标可以是目录中的任何可调用类。 在此示例中，有一个具有可调用类的 Python 脚本 askwiki.py ，该类 askwiki() 设置为目标。 如果您有可以输入到简单 askwiki 应用程序的查询数据集，则可以评估输出结果的可靠性。 请确保在 "column_mapping" 中为数据指定正确的列映射。 可以使用 "default" 来为所有评估器指定列映射。

以下是在 "data.jsonl" 中的内容：

{"query":"When was United States 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}"
            } 
        }
    }
)

相关内容

• 适用于 Python 的 Azure AI 评估客户端库
• 排查 AI 评估 SDK 问题
• 生成 AI 中的可观测性
• 使用 Microsoft Foundry SDK 在云中运行评估
• 生成用于评估的合成数据和模拟数据
• 在 Foundry 门户中查看评估结果
• Foundry 入门
• 开始使用评估示例