列出评估器¶
GET /api/v1/agent_eval/evaluator/list
概述¶
分页查询当前工作空间的自定义评估器。
调用前和使用步骤¶
使用目标工作空间的DF-API-KEY;即使只读,也需Agent监测的应用配置管理权限。仅操作当前空间的custom评估器,不暴露系统内置评估器。参数只放在对应Query/路径或JSON Body,禁止使用URL中的body参数。 按createAt和内部序号倒序分页。列表返回完整评估配置,content.data为空数组表示本页没有结果;分页位于顶层pageInfo。先取content.data[].uuid,再调用详情。分页不是快照,期间创建/删除可能改变翻页结果。读取不会初始化内置模板。
请求头¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| DF-API-KEY | string | Y | 目标工作空间的OpenAPI凭据,读取和写入均需Agent监测的应用配置管理权限;所属角色须为owner、wsAdmin或general。 例子: <DF-API-KEY>获取或填写方式: 在目标工作空间的API Key管理中创建并授权,使用DF-API-KEY请求头传递;不要在URL或示例中填真实Key。 |
Query 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| pageIndex | integer | 页码,整数1–2147483647,省略为1。只允许单个ASCII十进制正整数,不传重复键、符号、空值或浮点数。 默认值: 1 $minValue: 1 $maxValue: 2147483647 例子: 1获取或填写方式: 调用方从1开始;结合返回顶层pageInfo.totalCount和pageSize翻页。 |
|
| pageSize | integer | 每页条数,整数1–100,省略为20。仅影响本次分页,不改变配置。 默认值: 20 $minValue: 1 $maxValue: 100 例子: 20获取或填写方式: 调用方按所需分页条数设置。 |
参数补充说明¶
评估器列表位于 content.data。分页信息位于响应顶层的 pageInfo,count 为本页条数,totalCount 为总条数。列表包含评估配置,访问权限与评估器管理一致。
请求例子¶
curl 'https://openapi.guance.com/api/v1/agent_eval/evaluator/list?pageIndex=1&pageSize=20' \
--header 'DF-API-KEY:
响应¶
HTTP 200,application/json。成功包装与字段如下;失败参见公共错误及本页异常处理。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务响应状态,成功为200。 |
| errorCode | string | 成功为空;失败为具体错误码。 |
| message | string | 成功为空;失败为错误消息。 |
| success | boolean | 是否成功。 |
| traceId | string | 本次请求追踪标识,排查问题时保留。 |
| content | object | 包含data和工作空间公共声明。 |
| content.data | array<object> | 当前页完整评估器配置,无结果时为空数组。 |
| content.data[].uuid | string | 评估器UUID,用于后续详情、修改、启停和删除。 |
| content.data[].name | string | 评估器名称。 |
| content.data[].description | string | 业务描述,可能为空字符串。 |
| content.data[].evalType | string | prompt或schema。 |
| content.data[].templateKey | string | Schema系统模板标识;Prompt类型为空。 |
| content.data[].schemaConfig | object | Schema规范化配置;Prompt类型为空对象。 |
| content.data[].schemaConfig.templateVersion | integer | Schema模板版本,当前1;仅Schema配置非空时存在。 |
| content.data[].schemaConfig.schemaDialect | string | Schema方言draft-07;仅Schema配置非空时存在。 |
| content.data[].schemaConfig.validationSource | string | Schema取值来源:output或tool_calls。 |
| content.data[].schemaConfig.targetField | string | Schema校验目标字段,如gen_ai_output_messages或tool_calls。 |
| content.data[].schemaConfig.missingPolicy | string | Schema缺失策略,当前fail。 |
| content.data[].schemaConfig.schema | object | 实际JSON Schema,结构由系统模板及自定义配置确定,内部键为标准Draft 7关键字及业务自定义属性。 |
| content.data[].promptUUID | string | 内置Prompt模板UUID;自定义Prompt和Schema为空。 |
| content.data[].promptName | string | 模板展示名称;没有关联Prompt时Schema可返回其系统模板名称。 |
| content.data[].promptDescription | string | 模板描述;没有关联模板时为空。 |
| content.data[].promptContent | string | 实际评估指令;Schema类型为空。 |
| content.data[].promptOrigin | string | Prompt来源builtin或custom;Schema也可能返回兼容默认builtin,不代表使用Prompt。 |
| content.data[].selectedInputFields | array<string>或null | 旧版选择的输入字段或版本1推导的通用别名;没有配置时可为null,版本1仅选原始路径时可为空数组。 |
| content.data[].selectedInputFields[] | string | 输入证据别名,如gen_ai_input;不是任意原始Trace路径。 |
| content.data[].generationDescription | string | 原始模板生成描述,可能为空。 |
| content.data[].inputTemplateVersion | integer或null | 版本1返回1;旧版及未配置时为null。 |
| content.data[].userPromptTemplate | string | 版本1为保存的输入模板;旧版Prompt为按读取语言生成的输入模板;Schema为空。 |
| content.data[].targetType | string | agent或llm,Schema仅agent。 |
| content.data[].evalScope | string | Prompt为trace或span;Schema为空字符串。 |
| content.data[].resultType | string | boolean或score,Schema仅boolean。 |
| content.data[].resultConfig | object | 输出配置,由resultType决定,不能通过本接口直接写入。 |
| content.data[].resultConfig.values | array<string> | boolean类型存在,固定pass和fail。 |
| content.data[].resultConfig.values[] | string | 布尔评估结果标签pass或fail。 |
| content.data[].resultConfig.min | integer | score类型存在,固定0。 |
| content.data[].resultConfig.max | integer | score类型存在,固定100。 |
| content.data[].sourceType | string | 本组接口只管理custom自定义评估器。 |
| content.data[].targetConfig | object | 保存的过滤、语言及输入配置;部分子字段随类型和输入版本变化。 |
| content.data[].targetConfig.agentRuntime | string | 规范化后的Agent运行环境过滤值,空表示未限定。 |
| content.data[].targetConfig.agentID | string | Agent实例过滤值,可能为空。 |
| content.data[].targetConfig.appID | string | LLM应用公开appId过滤值,可能为空。 |
| content.data[].targetConfig.appName | string | 保存的LLM应用显示名称,用于评估结果的app_name标签;不参与在线候选Trace筛选,筛选应用请设置appID。可能为空。 |
| content.data[].targetConfig.language | string | 已保存的评估输出语言。 |
| content.data[].targetConfig.promptOrigin | string | Prompt类型保存的来源builtin或custom;Schema通常无此键。 |
| content.data[].targetConfig.selectedInputFields | array<string> | 配置了旧版字段选择或版本1时存在,语义同顶层selectedInputFields。 |
| content.data[].targetConfig.selectedInputFields[] | string | 已保存或推导的通用输入字段名。 |
| content.data[].targetConfig.generationDescription | string | Prompt类型保存的生成描述。 |
| content.data[].targetConfig.inputTemplateVersion | integer | 版本1存在,值为1。 |
| content.data[].targetConfig.inputVariables | array<string> | 版本1存在,为从userPromptTemplate解析出的去重变量路径,最多100项。 |
| content.data[].targetConfig.inputVariables[] | string | 原始变量路径或通用别名,如root.input、spans[*].output。 |
| content.data[].status | string | 已保存状态;新建为enabled,状态接口可设enabled或disabled。历史数据可能为draft。 |
| content.data[].samplingRate | integer | 在线采样百分比0–100。 |
| content.data[].dailyCallLimit | integer | 每日调用上限1–1000000。 |
| content.data[].timeoutSeconds | integer | 评估执行超时,单位秒。 |
| content.data[].maxRetries | integer | 在线评估最大重试次数0–5。 |
| content.data[].publishedAt | integer | 发布/启用时间,Unix秒,未发布历史值可为-1。 |
| content.data[].lastScanAt | integer | 最近扫描进度时间,Unix毫秒,历史未设置值可为-1。实际配置修改可能重置,不是该HTTP请求完成时间。 |
| content.data[].createAt | integer | 创建时间,Unix秒。 |
| content.data[].updateAt | integer | 修改时间,Unix秒。 |
| content.declaration | object或null | 本空间公共声明,未配置时可为空对象或null;列表只有content这一层携带,不给data[]逐项补充。 |
| pageInfo | object | 分页信息位于响应顶层,不在content内。 |
| pageInfo.pageIndex | integer | 本次页码。 |
| pageInfo.pageSize | integer | 本次每页条数。 |
| pageInfo.count | integer | 本页实际条数。 |
| pageInfo.totalCount | integer | 当前空间自定义评估器总条数。 |
{
"code": 200,
"content": {
"data": [
{
"uuid": "aeve_0123456789abcdef0123456789abcdef",
"name": "LLM 回答完整性",
"description": "",
"evalType": "prompt",
"templateKey": "",
"schemaConfig": {},
"promptUUID": "",
"promptName": "",
"promptDescription": "",
"promptContent": "判断回答是否完整回应了用户问题。给出通过或不通过的结果及原因。",
"promptOrigin": "custom",
"selectedInputFields": [
"gen_ai_input",
"gen_ai_output"
],
"generationDescription": "",
"inputTemplateVersion": null,
"userPromptTemplate": "gen_ai_input:\n{{gen_ai_input}}\n\ngen_ai_output:\n{{gen_ai_output}}",
"targetType": "llm",
"evalScope": "trace",
"resultType": "boolean",
"resultConfig": {
"values": [
"pass",
"fail"
]
},
"sourceType": "custom",
"targetConfig": {
"agentRuntime": "",
"agentID": "",
"appID": "support_assistant",
"appName": "",
"language": "zh",
"promptOrigin": "custom",
"selectedInputFields": [
"gen_ai_input",
"gen_ai_output"
],
"generationDescription": ""
},
"status": "enabled",
"samplingRate": 20,
"dailyCallLimit": 10000,
"timeoutSeconds": 30,
"maxRetries": 2,
"publishedAt": 1795226400,
"lastScanAt": 1795226400000,
"createAt": 1795226400,
"updateAt": 1795226400
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "example-trace-id",
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
}
错误响应¶
鉴权、限流和公共请求错误参见公共错误定义。
| HTTP 状态 | errorCode | 触发条件 | 消息或响应说明 | 处理方式 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 请求中包含未声明的参数,或已声明请求字段未通过类型/约束校验 | 参数解析失败 | 只提交本页声明的请求头、路径和Query参数;本接口不需要JSON请求体。 |
| 406 | ft.InvalidParameterV2 | pageIndex或pageSize重复、不是合法ASCII十进制正整数或超出范围;URL中携带body参数 | 参数{}的值 {}无效;URL body参数被拒绝时为Send evaluator parameters in the JSON request body. |
每个分页键只传一次,并使用参数表范围内整数;移除URL中的body参数。 |
| 500 | ft.InternalServerError | 读取数据库或序列化配置时发生未处理异常 | 内部错误 | 保留traceId并联系管理员;本接口是读取操作,可在依赖恢复后重试。 |