OpenAI 更新评测接口

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

更新评测

post /evals/{eval_id}

更新评测的部分属性。

路径参数

• eval_id: string

评测 ID。

请求体参数

内容类型为 application/json。

• metadata: optional Metadata or null

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

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

• name: optional string

重命名评测。

返回值

• 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

分数阈值。

示例

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

响应

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

代码内文字译释：

• 聊天机器人效果评测。

{
  "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"
    }
  ]
}

示例

代码内文字译释：

• 更新后的评测。
• 更新后的描述。

## [中文] 发送POST请求；将示例API凭证及资源标识替换为应用使用的值。
curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Eval", "metadata": {"description": "Updated description"}}'

响应

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

代码内文字译释：

• 字符串检查。
• 字符串检查，标识后缀2eaf2d8d-d649-4335-8148-9535a7ca73c2。
• 更新后的评测。
• 更新后的描述。

{
  "object": "eval",
  "id": "eval_67abd54d9b0081909a86353f6fb9317a",
  "data_source_config": {
    "type": "custom",
    "schema": {
      "type": "object",
      "properties": {
        "item": {
          "type": "object",
          "properties": {
            "input": {
              "type": "string"
            },
            "ground_truth": {
              "type": "string"
            }
          },
          "required": [
            "input",
            "ground_truth"
          ]
        }
      },
      "required": [
        "item"
      ]
    }
  },
  "testing_criteria": [
    {
      "name": "String check",
      "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2",
      "type": "string_check",
      "input": "{{item.input}}",
      "reference": "{{item.ground_truth}}",
      "operation": "eq"
    }
  ],
  "name": "Updated Eval",
  "created_at": 1739314509,
  "metadata": {"description": "Updated description"}
}