OpenAI 列出评测接口

编者时效说明（2026-11-03）：官方评测指南说明，Evals于2026年10月31日对现有用户转为只读，计划于2026年11月30日关闭。下文为保存的接口文档译文，创建、修改及运行示例不代表当前仍可使用。参见官方说明。

列出评测

get /evals

列出项目的评测。

查询参数

• after: optional string

上一次分页请求返回的最后一个评测的标识符。

• limit: optional integer (default: 20)

要获取的评测数量。

• order: optional "asc" or "desc" (default: "asc")

按时间戳对评测排序。asc表示升序，desc表示降序。

• "asc"

• "desc"

• order_by: optional "created_at" or "updated_at" (default: "created_at")

评测可按创建时间或最后更新时间排序。created_at表示创建时间，updated_at表示最后更新时间。

• "created_at"

• "updated_at"

返回值

• data: array of object { id, created_at, data_source_config, 4 more }

评测对象数组。

• id: string

评测的唯一标识符。

• created_at: integer

时间格式为 Unix 时间戳。

评测创建时的Unix时间戳，单位为秒。

• data_source_config: EvalCustomDataSourceConfig or LogsDataSourceConfig { schema, type, metadata } or EvalStoredCompletionsDataSourceConfig

评测运行中使用的数据源配置。

• EvalCustomDataSourceConfig object { schema, type }

CustomDataSourceConfig，指定item及可选sample命名空间的结构。响应结构定义以下数据的形式：

• 定义测试标准所用的数据；
• 创建运行时必须提供的数据。

• schema: map[unknown]

运行数据源条目的JSON Schema。构建JSON Schema的方法见此处。

• type: "custom" (default: "custom")

数据源类型，固定为custom。

• "custom"

• LogsDataSourceConfig object { schema, type, metadata }

LogsDataSourceConfig，指定日志查询的metadata属性，通常为usecase=chatbot或prompt-version=v2等元数据。此数据源配置返回的结构用于定义评测中可用的变量。使用此配置时，item与sample都会被定义。

• schema: map[unknown]

运行数据源条目的JSON Schema。构建JSON Schema的方法见此处。

• type: "logs" (default: "logs")

数据源类型，固定为logs。

• "logs"

• metadata: optional Metadata or null

可附加到对象的一组16个键值对，用于结构化保存附加信息，并通过API或控制台查询对象。

键为最长64个字符的字符串，值为最长512个字符的字符串。

• EvalStoredCompletionsDataSourceConfig object { schema, type, metadata }

已弃用，请改用LogsDataSourceConfig。

• schema: map[unknown]

运行数据源条目的JSON Schema。构建JSON Schema的方法见此处。

• type: "stored_completions" (default: "stored_completions")

数据源类型，固定为stored_completions。

• "stored_completions"

• metadata: optional Metadata or null

可附加到对象的一组16个键值对，用于结构化保存附加信息，并通过API或控制台查询对象。

键为最长64个字符的字符串，值为最长512个字符的字符串。

• metadata: Metadata or null

可附加到对象的一组16个键值对，用于结构化保存附加信息，并通过API或控制台查询对象。

键为最长64个字符的字符串，值为最长512个字符的字符串。

• name: string

评测名称。

• object: "eval" (default: "eval")

对象类型。

• "eval"

• testing_criteria: array of LabelModelGrader or StringCheckGrader or TextSimilarityGrader or 2 more

测试标准列表。

• LabelModelGrader object { input, labels, model, 3 more }

LabelModelGrader对象，使用模型为评测中的每个条目分配标签。

• input: array of object { content, role, type }

• content: string or ResponseInputText or OutputText { text, type } or 3 more

模型输入，可包含模板字符串。支持输入文本、输出文本、输入图像及输入音频，可以是单个条目或条目数组。

• TextInput = string

提供给模型的文本输入。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

提供给模型的文本输入。

• text: string

提供给模型的输入文本。

• type: "input_text" (default: "input_text")

输入条目类型，固定为input_text。

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

• ttl: optional "30m" or "12h"

此缓存断点的最短有效期。省略时继承请求的 prompt_cache_options.ttl。

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求的prompt_cache_options.ttl，边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为explicit。

• "explicit"

• OutputText object { text, type }

模型的文本输出。

• text: string

模型输出的文本。

• type: "output_text"

输出文本类型，固定为output_text。

• "output_text"

• InputImage object { image_url, type, detail }

EvalItem内容数组中使用的图像输入块。

• image_url: string

格式为 URI。

输入图像的URL。

• type: "input_image"

图像输入类型，固定为input_image。

• "input_image"

• detail: optional string

发送给模型的图像细节级别，可为high、low或auto，默认为auto。

• ResponseInputAudio object { input_audio, type }

模型的音频输入。

• input_audio: object { data, format }

• data: string

Base64编码的音频数据。

• format: "mp3" or "wav"

音频数据格式，目前支持mp3和wav。

• "mp3"

• "wav"

• type: "input_audio"

类型，固定为input_audio。

• "input_audio"

• GraderInputs = array of string or ResponseInputText or OutputText { text, type } or 2 more

输入列表，其中每个条目可为输入文本、输出文本、输入图像或输入音频对象。

• TextInput = string

提供给模型的文本输入。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

提供给模型的文本输入。

• OutputText object { text, type }

模型的文本输出。

• text: string

模型输出的文本。

• type: "output_text"

输出文本类型，固定为output_text。

• "output_text"

• InputImage object { image_url, type, detail }

EvalItem内容数组中使用的图像输入块。

• image_url: string

格式为 URI。

输入图像的URL。

• type: "input_image"

图像输入类型，固定为input_image。

• "input_image"

• detail: optional string

发送给模型的图像细节级别，可为high、low或auto，默认为auto。

• ResponseInputAudio object { input_audio, type }

模型的音频输入。

• role: "user" or "assistant" or "system" or "developer"

消息输入角色，可选user、assistant、system或developer。

• "user"

• "assistant"

• "system"

• "developer"

• type: optional "message"

消息输入类型，固定为message。

• "message"

• labels: array of string

分配给评测中每个条目的标签。

• model: string

评测使用的模型，必须支持结构化输出。

• name: string

评分器名称。

• passing_labels: array of string

表示结果通过的标签，必须是labels的子集。

• type: "label_model"

对象类型，固定为label_model。

• "label_model"

• StringCheckGrader object { input, name, operation, 2 more }

StringCheckGrader对象，使用指定操作比较输入字符串与参考字符串。

• input: string

输入文本，可包含模板字符串。

• name: string

评分器名称。

• operation: "eq" or "ne" or "like" or "ilike"

要执行的字符串检查操作，可为eq、ne、like或ilike。

• "eq"

• "ne"

• "like"

• "ilike"

• reference: string

参考文本，可包含模板字符串。

• type: "string_check"

对象类型，固定为string_check。

• "string_check"

• TextSimilarityGrader = TextSimilarityGrader

TextSimilarityGrader对象，基于相似度指标对文本评分。

• pass_threshold: number

分数阈值。

• PythonGrader = PythonGrader

PythonGrader对象，对输入运行Python脚本。

• pass_threshold: optional number

分数阈值。

• ScoreModelGrader = ScoreModelGrader

ScoreModelGrader对象，使用模型为输入分配分数。

• pass_threshold: optional number

分数阈值。

• first_id: string

data数组中第一个评测的标识符。

• has_more: boolean

是否还有更多评测可获取。

• last_id: string

data数组中最后一个评测的标识符。

• object: "list" (default: "list")

对象类型，固定为“list”。

• "list"

示例

## [中文] 发送GET请求；将示例API凭证及资源标识替换为应用使用的值。
curl https://api.openai.com/v1/evals \
    -H "Authorization: Bearer $OPENAI_API_KEY"

响应

中文说明：以下为原文配置、命令或事件示例，字段名、枚举、标识符及数值保留。

代码内文字译释：

• 聊天机器人效果评测。

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "data_source_config": {
        "schema": {
          "type": "object",
          "properties": {
            "item": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                }
              },
              "required": [
                "label"
              ]
            }
          },
          "required": [
            "item"
          ]
        },
        "type": "custom"
      },
      "metadata": {
        "foo": "string"
      },
      "name": "Chatbot effectiveness Evaluation",
      "object": "eval",
      "testing_criteria": [
        {
          "input": [
            {
              "content": "string",
              "role": "user",
              "type": "message"
            }
          ],
          "labels": [
            "string"
          ],
          "model": "model",
          "name": "name",
          "passing_labels": [
            "string"
          ],
          "type": "label_model"
        }
      ]
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

示例

## [中文] 发送GET请求；将示例API凭证及资源标识替换为应用使用的值。
curl https://api.openai.com/v1/evals?limit=1 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

响应

中文说明：以下为原文配置、命令或事件示例，字段名、枚举、标识符及数值保留。

代码内文字译释：

• 推送通知摘要评分器。
• 推送通知摘要评分器，标识后缀9b876f24-4762-4be9-aff4-db7a9b31c673。
• 将以下推送通知摘要标记为correct（正确）或incorrect（不正确）。下方将提供推送通知及其摘要。好的推送通知摘要应简洁明快。摘要好则标记correct，否则标记incorrect。
• 推送通知：{{item.input}}；摘要：{{sample.output_text}}。
• correct：正确。
• incorrect：不正确。
• 针对推送通知摘要的已存储补全评测。

{
  "object": "list",
  "data": [
    {
      "id": "eval_67abd54d9b0081909a86353f6fb9317a",
      "object": "eval",
      "data_source_config": {
        "type": "stored_completions",
        "metadata": {
          "usecase": "push_notifications_summarizer"
        },
        "schema": {
          "type": "object",
          "properties": {
            "item": {
              "type": "object"
            },
            "sample": {
              "type": "object"
            }
          },
          "required": [
            "item",
            "sample"
          ]
        }
      },
      "testing_criteria": [
        {
          "name": "Push Notification Summary Grader",
          "id": "Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673",
          "type": "label_model",
          "model": "o3-mini",
          "input": [
            {
              "type": "message",
              "role": "developer",
              "content": {
                "type": "input_text",
                "text": "\nLabel the following push notification summary as either correct or incorrect.\nThe push notification and the summary will be provided below.\nA good push notificiation summary is concise and snappy.\nIf it is good, then label it as correct, if not, then incorrect.\n"
              }
            },
            {
              "type": "message",
              "role": "user",
              "content": {
                "type": "input_text",
                "text": "\nPush notifications: {{item.input}}\nSummary: {{sample.output_text}}\n"
              }
            }
          ],
          "passing_labels": [
            "correct"
          ],
          "labels": [
            "correct",
            "incorrect"
          ],
          "sampling_params": null
        }
      ],
      "name": "Push Notification Summary Grader",
      "created_at": 1739314509,
      "metadata": {
        "description": "A stored completions eval for push notification summaries"
      }
    }
  ],
  "first_id": "eval_67abd54d9b0081909a86353f6fb9317a",
  "last_id": "eval_67aa884cf6688190b58f657d4441c8b7",
  "has_more": true
}