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