TRAE-AI编程
OpenAI 创建评测接口
编者时效说明（2026-11-03）：官方评测指南说明，Evals于2026年10月31日对现有用户转为只读，计划于2026年11月30日关闭。下文为保存的接口文档译文，创建、修改及运行示例不代表当前仍可使用。参见官方说明。
创建评测
post /evals
创建用于测试模型表现的评测结构。评测由一组测试标准和数据源配置组成，配置规定评测数据的结构。创建评测后，可以针对不同模型及模型参数运行。支持多种评分器和数据源。详见评测指南。
请求体参数
内容类型为 application/json。
data_source_config: CustomDataSourceConfig { item_schema, type, include_sample_schema } or LogsDataSourceConfig { type, metadata } or StoredCompletionsDataSourceConfig { type, metadata }
评测运行使用的数据源配置，规定评测数据的结构。
CustomDataSourceConfig object { item_schema, type, include_sample_schema }
CustomDataSourceConfig对象，定义评测运行所用数据源的结构。此结构用于定义以下数据的形式：
- 定义测试标准所用的数据；
- 创建运行时必须提供的数据。
item_schema: map[unknown]
数据源每一行的JSON Schema。
type: "custom" (default: "custom")
数据源类型，固定为custom。
"custom"
include_sample_schema: optional boolean (default: false)
评测是否要求你填充sample命名空间，例如根据数据源生成响应。
LogsDataSourceConfig object { type, metadata }
指定日志查询metadata属性的数据源配置，通常为usecase=chatbot或prompt-version=v2等元数据。
type: "logs" (default: "logs")
数据源类型，固定为logs。
"logs"
metadata: optional map[unknown]
日志数据源的元数据筛选条件。
StoredCompletionsDataSourceConfig object { type, metadata }
已弃用，请改用LogsDataSourceConfig。
type: "stored_completions" (default: "stored_completions")
数据源类型，固定为stored_completions。
"stored_completions"
metadata: optional map[unknown]
已存储补全数据源的元数据筛选条件。
testing_criteria: array of LabelModelGrader { input, labels, model, 3 more } or StringCheckGrader or TextSimilarityGrader or 2 more
此组所有评测运行使用的评分器列表。评分器可使用双花括号引用数据源变量，例如{{item.variable_name}}。引用模型输出时使用sample命名空间，例如{{sample.output_text}}。
LabelModelGrader object { input, labels, model, 3 more }
LabelModelGrader对象，使用模型为评测中的每个条目分配标签。
input: array of SimpleInputMessage { content, role } or EvalMessageObject { content, role, type }
组成提示词或上下文的聊天消息列表，可包含item命名空间的变量引用，例如{{item.name}}。
SimpleInputMessage object { content, role }
content: string
消息内容。
role: string
消息角色，例如"system"、"assistant"或"user"。
EvalMessageObject object { content, role, type }
提供给模型的消息输入，角色表示指令遵循层级。developer或system指令优先于user指令；assistant消息被视为模型在先前交互中生成的消息。
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"
TextSimilarity = TextSimilarityGrader
TextSimilarityGrader对象，基于相似度指标对文本评分。
pass_threshold: number
分数阈值。
Python = PythonGrader
PythonGrader对象，对输入运行Python脚本。
pass_threshold: optional number
分数阈值。
ScoreModel = ScoreModelGrader
ScoreModelGrader对象，使用模型为输入分配分数。
pass_threshold: optional number
分数阈值。
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 \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"data_source_config": {
"item_schema": {
"foo": "bar"
},
"type": "custom"
},
"testing_criteria": [
{
"input": [
{
"content": "content",
"role": "role"
}
],
"labels": [
"string"
],
"model": "model",
"name": "name",
"passing_labels": [
"string"
],
"type": "label_model"
}
]
}'响应
中文说明：以下为原文配置、命令或事件示例，字段名、枚举、标识符及数值保留。
代码内文字译释：
- 聊天机器人效果评测。
{
"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"
}
]
}示例
代码内文字译释：
- 将以下陈述的情感分类为positive（正向）、neutral（中性）或negative（负向）之一。
- 陈述：{{item.input}}。
- 标签评分器示例。
## [中文] 发送POST请求；将示例API凭证及资源标识替换为应用使用的值。
curl https://api.openai.com/v1/evals \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sentiment",
"data_source_config": {
"type": "stored_completions",
"metadata": {
"usecase": "chatbot"
}
},
"testing_criteria": [
{
"type": "label_model",
"model": "o3-mini",
"input": [
{
"role": "developer",
"content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'"
},
{
"role": "user",
"content": "Statement: {{item.input}}"
}
],
"passing_labels": [
"positive"
],
"labels": [
"positive",
"neutral",
"negative"
],
"name": "Example label grader"
}
]
}'响应
中文说明：以下为原文配置、命令或事件示例，字段名、枚举、标识符及数值保留。
代码内文字译释：
- 标签评分器示例。
- 将以下陈述的情感分类为positive（正向）、neutral（中性）或negative（负向）之一。
- 陈述：{{item.input}}。
- positive：正向。
- neutral：中性。
- negative：负向。
- 用于情感分析的评测。
{
"object": "eval",
"id": "eval_67b7fa9a81a88190ab4aa417e397ea21",
"data_source_config": {
"type": "stored_completions",
"metadata": {
"usecase": "chatbot"
},
"schema": {
"type": "object",
"properties": {
"item": {
"type": "object"
},
"sample": {
"type": "object"
}
},
"required": [
"item",
"sample"
]
}
},
"testing_criteria": [
{
"name": "Example label grader",
"type": "label_model",
"model": "o3-mini",
"input": [
{
"type": "message",
"role": "developer",
"content": {
"type": "input_text",
"text": "Classify the sentiment of the following statement as one of positive, neutral, or negative"
}
},
{
"type": "message",
"role": "user",
"content": {
"type": "input_text",
"text": "Statement: {{item.input}}"
}
}
],
"passing_labels": [
"positive"
],
"labels": [
"positive",
"neutral",
"negative"
]
}
],
"name": "Sentiment",
"created_at": 1740110490,
"metadata": {
"description": "An eval for sentiment analysis"
}
}
更多建议：