使用Evals API处理图像输入：OpenAI评估框架实战指南

本教程面向有编程基础的开发者，深入讲解如何使用OpenAI Evals API评估基于图像的任务。通过采样生成模型响应，并利用LLM作为裁判进行评分，实现自动化评估。内容涵盖环境搭建、数据集准备、评估配置、运行与结果分析，并补充了技术背景、核心原理、架构设计、常见错误排查及生产优化建议，帮助开发者掌握AI评估工程实践。

技术背景

在AI应用开发中，评估模型性能至关重要，尤其是涉及图像输入的任务（如视觉问答、图像描述）。传统人工评估耗时且主观，自动化评估成为刚需。OpenAI Evals API提供标准化评估框架，支持采样和模型评分，可高效评估模型对图像和提示的响应质量。本教程解决如何利用该框架进行图像任务评估的问题，适用于模型迭代、质量监控等场景。主要限制包括依赖LLM评分的主观性、API成本及数据隐私考量。

核心原理

核心原理基于两个阶段：采样和评分。采样阶段，使用指定模型（如gpt-4o-mini）根据用户提示和图像生成响应。评分阶段，使用另一个模型（如o4-mini）作为裁判，根据图像、提示、参考答案和模型响应，输出0到1的分数，并依据阈值判断是否通过。数据流为：数据集（Hugging Face）→ 数据源配置 → 评估对象 → 运行（采样+评分）→ 结果输出。关键设计决策包括：使用模板引用数据项（如{{item.prompt}}），支持图像URL或base64，评分器可定制提示词以优化评估标准。

架构分析

系统架构分为三层：数据层、评估层和结果层。数据层负责加载和格式化数据，支持自定义数据源和日志数据源。评估层包含评估对象（定义数据结构和评分器）和运行（指定采样模型和输入模板）。结果层通过轮询获取运行状态，并解析输出项生成DataFrame。设计思想强调模块化和可配置性，评分器与采样模型解耦，便于替换和优化。关键组件包括：数据源配置（item_schema）、评分器配置（grader_config）、采样消息模板（sampling_messages）。可修改点包括评分器提示词、阈值、模型选择等。

完整实战教程

Evals API：图像输入

本教程演示如何使用OpenAI的Evals框架进行基于图像的任务。利用Evals API，我们将通过采样生成模型对图像和提示的响应，并使用模型评分（LLM作为裁判）根据图像、提示和参考答案对模型响应进行评分。

在此示例中，我们将评估模型在以下方面的表现：

生成适当的响应：针对用户关于图像的提示
与参考答案对齐：代表高质量响应的参考答案

安装依赖 + 环境设置

# Install required packages
!pip install openai datasets pandas --quiet

# Import libraries
from datasets import load_dataset
from openai import OpenAI
import os
import json
import time
import pandas as pd

数据集准备

我们使用托管在 Hugging Face 上的 VibeEval 数据集。该数据集包含用户提示、附带图像和参考答案数据的集合。首先，我们加载数据集。

dataset = load_dataset("RekaAI/VibeEval")

我们提取相关字段，并将其放入类似 JSON 的格式中，以便作为 Evals API 中的数据源传入。输入图像数据可以是网页 URL 或 base64 编码字符串的形式。这里，我们使用提供的网页 URL。

evals_data_source = []

# select the first 3 examples in the dataset to use for this cookbook
for example in dataset["test"].select(range(3)):
    evals_data_source.append({
        "item": {
            "media_url": example["media_url"], # image web URL
            "reference": example["reference"], # reference answer
            "prompt": example["prompt"] # prompt
        }
    })

如果你打印数据源列表，每个条目应该类似于：

{
  "item": {
    "media_url": "https://storage.googleapis.com/reka-annotate.appspot.com/vibe-eval/difficulty-normal_food1_7e5c2cb9c8200d70.jpg"
    "reference": "This appears to be a classic Margherita pizza, which has the following ingredients..."
    "prompt": "What ingredients do I need to make this?"
  }
}

评估配置

现在我们已经有了数据源和任务，我们将创建我们的评估。有关 OpenAI Evals API 文档，请访问 API 文档。

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
)

评估包含两个部分：“评估”和“运行”。在“评估”中，我们定义数据的预期结构和测试标准（评分器）。

数据源配置

根据我们整理的数据，数据源配置如下：

data_source_config = {
    "type": "custom",
    "item_schema": {
        "type": "object",
        "properties": {
          "media_url": { "type": "string" },
          "reference": { "type": "string" },
          "prompt": { "type": "string" }
        },
        "required": ["media_url", "reference", "prompt"]
      },
    "include_sample_schema": True, # enables sampling
}

测试标准

对于我们的测试标准，我们设置了评分器配置。在这个例子中，它是一个模型评分器，接收图像、参考答案和采样模型响应（在 sample 命名空间中），然后根据模型响应与参考答案的匹配程度及其对对话的总体适用性，输出一个介于 0 和 1 之间的分数。有关模型评分器的更多信息，请访问 API 评分器文档。

确保数据和评分器都正确对于有效的评估至关重要。因此，您可能希望迭代地优化评分器的提示词。

注意：图像 URL 字段 / 模板需要放置在输入图像对象中才能被解释为图像。否则，该图像将被解释为文本字符串。

grader_config = {
        "type": "score_model",
        "name": "Score Model Grader",
        "input":[
            {
                "role": "system",
                "content": "You are an expert grader. Judge how well the model response suits the image and prompt as well as matches the meaniing of the reference answer. Output a score of 1 if great. If it's somewhat compatible, output a score around 0.5. Otherwise, give a score of 0."
            },
            {
                "role": "user",
                "content": [{ "type": "input_text", "text": "Prompt: {{ item.prompt }}."},
                            { "type": "input_image", "image_url": "{{ item.media_url }}", "detail": "auto" },
                            { "type": "input_text", "text": "Reference answer: {{ item.reference }}. Model response: {{ sample.output_text }}."}
                ]
            }
        ],
        "pass_threshold": 0.9,
        "range": [0, 1],
        "model": "o4-mini" # model for grading; check that the model you use supports image inputs
    }

现在，我们创建 eval 对象。

eval_object = client.evals.create(
        name="Image Grading",
        data_source_config=data_source_config,
        testing_criteria=[grader_config],
    )

Eval Run

为了创建运行，我们传入 eval 对象 ID、数据源（即我们之前编译的数据）以及用于采样生成模型响应的聊天消息输入。请注意，EvalsAPI 还支持存储的完成和包含图像作为数据源的响应。有关更多信息，请参阅附加信息：日志数据源部分。

以下是我们在本例中使用的采样消息输入。

sampling_messages = [{
    "role": "user",
    "type": "message",
    "content": {
        "type": "input_text",
        "text": "{{ item.prompt }}"
      }
  },
  {
    "role": "user",
    "type": "message",
    "content": {
        "type": "input_image",
        "image_url": "{{ item.media_url }}",
        "detail": "auto"
    }
  }]

现在我们启动一次评估运行。

eval_run = client.evals.runs.create(
        name="Image Input Eval Run",
        eval_id=eval_object.id,
        data_source={
            "type": "responses", # sample using responses API
            "source": {
                "type": "file_content",
                "content": evals_data_source
            },
            "model": "gpt-4o-mini", # model used to generate the response; check that the model you use supports image inputs
            "input_messages": {
                "type": "template", 
                "template": sampling_messages}
        }
    )

轮询并显示结果

当运行结束时，我们可以查看结果。你也可以在组织的OpenAI评估仪表板中查看进度和结果。

while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=eval_object.id)
    if run.status == "completed" or run.status == "failed": # check if the run is finished
        output_items = list(client.evals.runs.output_items.list(
            run_id=run.id, eval_id=eval_object.id
        ))
        df = pd.DataFrame({
                "prompt": [item.datasource_item["prompt"] for item in output_items],
                "reference": [item.datasource_item["reference"] for item in output_items],
                "model_response": [item.sample.output[0].content for item in output_items],
                "score": [item.results[0].score for item in output_items],
                "passed": [item.results[0].passed for item in output_items],
                "grading_results": [item.results[0].sample["output"][0]["content"] for item in output_items]
            })
        display(df)
        break
    time.sleep(5)

查看单个输出项

要查看完整的输出项，我们可以执行以下操作。输出项的结构在 API 文档中此处有详细说明。

first_item = output_items[0]

print(json.dumps(dict(first_item), indent=2, default=str))

附加信息：日志数据源

如前所述，EvalsAPI 支持包含图像的日志（即存储的补全或响应）作为数据源。要使用此功能，请按如下方式更改评估配置：

评估创建

设置 data_source_config = { "type": "logs" }
修改 grader_config 中的模板，使用 {{item.input}} 和/或 {{sample.output_text}}，分别表示日志的输入和输出

评估运行创建

在 data_source 字段中指定用于获取评估运行相应日志的过滤器（有关更多信息，请参阅文档）

结论

在本教程中，我们介绍了使用 OpenAI Evals API 评估基于图像任务的工作流程。通过利用图像输入功能进行采样和模型评分，我们能够简化该任务的评估过程。

我们期待您将此方法扩展到自己的基于图像的使用场景，无论是 OCR 准确性、图像生成评分，还是更多！

常见问题

常见错误：1) 图像URL字段未正确放置在input_image对象中，导致被当作文本处理；2) 评分模型不支持图像输入，需检查模型能力；3) 数据源格式与item_schema不匹配，导致验证失败；4) 运行状态长时间不更新，可能是API限流或网络问题。排查方法：检查API返回错误信息，确认数据源和评分器配置正确，使用日志数据源时确保过滤器正确。生产优化：使用缓存减少重复调用，批量处理数据，选择成本更低的评分模型，设置合理的超时和重试机制。

企业应用扩展

本教程可扩展至多种图像评估场景，如OCR准确性、图像生成质量评分、视觉对话系统评估。可结合其他评估指标（如BLEU、ROUGE）与模型评分互补。未来可探索使用多模态模型进行更细粒度的评分，或集成到CI/CD流水线实现持续评估。此外，可考虑使用本地模型或微调评分器以降低成本和提升准确性。

总结

内容来源与验证

内容等级：PREMIUM_A
质量等级：A
难度：中级
验证等级：V1
原文作者：daisyshe-oai
原文日期：2025-07-15
来源许可：MIT
来源版本：ac6666fd5a1983742ad9ceb800b4187bc31475fb
查看原文

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员