修改评估器¶
POST /api/v1/agent_eval/evaluator/{evaluator_uuid}/modify
概述¶
局部更新当前工作空间的自定义评估器。
调用前和使用步骤¶
使用目标工作空间的DF-API-KEY;即使只读,也需Agent监测的应用配置管理权限。仅操作当前空间的custom评估器,不暴露系统内置评估器。参数只放在对应Query/路径或JSON Body,禁止使用URL中的body参数。 先获取详情,仅提交需要变更的JSON字段;至少一个字段。省略保留,允许为空的文本用空字符串清除,数值0有实际含义。对象/数组作为完整值校验,尤其schemaConfig显式传入时未传子项回退模板默认,不是与原对象合并。evalType不能改变,不能把Schema字段提交给Prompt或反向混用。版本1使用inputTemplateVersion=1和userPromptTemplate,从模板推导变量,不传selectedInputFields。模板仅引用数据路径,不支持执行表达式;root为根记录,spans为按时间排列的执行记录,可用spans[*].output等路径。旧版custom模式须传非空selectedInputFields;旧版builtin模式可省略,沿用系统输入。 相同配置重复提交不更新记录或产生变更审计。只改name/description不重置扫描进度;enabled评估器其他配置实际改变会将lastScanAt置为当前毫秒时间,应先确认评估范围。此接口不等同启用,现有status保持;本页samplingRate=0示例只停止新采样。失败/超时先读回再重试,避免覆盖他人并发修改;此接口没有配置版本冲突令牌。 appName仅保存应用显示名称并写入评估结果标签,不作为候选Trace过滤条件;限制目标LLM应用须设置appID。
路由参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| 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。 |
Body 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| schemaConfig.schema | object | JSON Schema Draft 7对象,定义待评估数据结构。仅允许文档内且可解析的$ref,禁止远程/文件引用;可省略使用所选系统模板Schema。该对象描述被采集数据,不是本接口请求体的Schema。 例子: {"type": "object", "required": ["answer"], "properties": {"answer": {"type": "string", "minLength": 1}}}获取或填写方式: 从已采集Agent输出/工具数据结构设计JSON Schema;也可复制详情content.schemaConfig.schema后完整修改。 |
|
| schemaConfig.missingPolicy | string | 缺少待校验输入时的处理策略,仅支持fail。省略使用系统模板默认fail。 例子: fail获取或填写方式: 填写固定值fail;不能使用ignore、skip等未支持策略。 |
|
| name | string | 工作空间内唯一的评估器名称,去除首尾空白后须有内容,最长128字符。创建必填;修改时省略保留。 允许 null: False 最小长度: 1 最大长度: 128 例子: LLM 回答完整性获取或填写方式: 调用方命名;先用列出评估器检查已有名称。 |
|
| description | string | 评估器描述,最长512字符。创建省略为空;修改省略保留,空字符串清除,服务端去除首尾空白。 允许 null: False 最大长度: 512 允许空字符串: True 例子: 检查客服应用回答完整性获取或填写方式: 调用方填写业务目标说明。 |
|
| targetType | string | prompt支持agent或llm,创建省略为agent;schema只允许agent。修改省略保留。 允许 null: False 可选值: ['agent', 'llm'] 例子: llm获取或填写方式: Agent监测数据选择agent,LLM应用Trace选择llm。 |
|
| promptOrigin | string | 仅prompt类型可传。builtin使用当前工作空间内置Prompt模板,custom使用自定义指令。创建省略builtin;修改省略保留。 允许 null: False 可选值: ['builtin', 'custom'] 例子: custom获取或填写方式: 自定义指令选custom;内置模板选builtin并提供模板UUID。 |
|
| promptUUID | string | 仅prompt且promptOrigin=builtin时使用,创建时必填,须为当前工作空间的内置Prompt模板UUID,最长48字符。自定义模式不要传。 允许 null: False 最小长度: 1 最大长度: 48 例子: aepm_0123456789abcdef0123456789abcdef获取或填写方式: 从控制台Agent监测的评估器配置选择内置Prompt模板,或读取同空间已有内置Prompt评估器详情的content.promptUUID;当前OpenAPI未提供模板目录接口,不能使用评估器UUID代替。 |
|
| promptContent | string | 仅prompt类型。创建必填,1–65535字符,服务端去除首尾空白;自定义和内置模板模式都要提交实际评估指令。修改省略保留。 允许 null: False 最小长度: 1 最大长度: 65535 例子: 判断回答是否完整回应了用户问题。给出通过或不通过的结果及原因。获取或填写方式: 自定义模式由调用方编写;内置模式在控制台选择模板后确认评估指令,也可复用现有评估器详情content.promptContent。 |
|
| inputTemplateVersion | integer | 仅prompt类型。可选整数1,表示变量输入模板模式。新建不传则使用旧版字段选择模式;修改不传沿用已保存版本,不支持以null退回旧版。 允许 null: False 可选值: [1] 例子: 1获取或填写方式: 希望明确选择原始Trace路径时传1,并同时提供userPromptTemplate;已有版本1评估器可先读详情。 |
|
| userPromptTemplate | string | 仅版本1使用的输入模板,1–65535字符,须包含1–100个去重后的有效变量路径。支持root、spans路径及通用别名,不执行表达式;不能与selectedInputFields同时提交。创建版本1必填,修改省略沿用已有模板。 允许 null: False 最小长度: 1 最大长度: 65535 例子: "输入:{{root.input}}\n输出:{{root.output}}"获取或填写方式: 在目标应用已采集的Trace中确认字段;LLM原始输入/输出用{{root.input}}与{{root.output}},Agent用{{root.gen_ai_input_messages}}与{{root.gen_ai_output_messages}}。数组支持spans[*]和索引,参见本页版本1示例。 |
|
| selectedInputFields | array | 仅旧版prompt输入模式可传。custom模式创建时必填,为1–5个不重复字段;builtin省略使用内置输入。版本1由模板推导,不得显式传入;修改省略保留。 允许 null: False 最小长度: 1 最大长度: 5 例子: ["gen_ai_input", "gen_ai_output"]获取或填写方式: 从gen_ai_input、gen_ai_output、trace_context、tool_calls、span_context选取所需证据。前两项为根输入/输出,其余为执行过程、工具调用和Span上下文。 |
|
| selectedInputFields[*] | string | 旧版输入字段名,必须属于上述五项且数组内不重复。 可选值: ['gen_ai_input', 'gen_ai_output', 'trace_context', 'tool_calls', 'span_context'] 例子: gen_ai_input获取或填写方式: 按评估所需证据选择固定字段,不填写任意Trace路径。 |
|
| generationDescription | string | 仅prompt类型,记录生成模板时的原始业务描述,最长4000字符;创建省略为空,修改省略保留,空字符串清除。此字段本身不触发模板生成。 允许 null: False 最大长度: 4000 允许空字符串: True 例子: 判断回答是否满足用户明确提出的目标获取或填写方式: 调用方填写并保存模板生成背景,也可读取详情content.generationDescription。 |
|
| templateKey | string | 仅schema类型。创建必填,修改省略保留。支持structured_output_compliance、tool_call_arguments_completeness、citation_evidence_structure、agent_task_result_compliance四个系统模板标识,最长64字符。 允许 null: False 最小长度: 1 最大长度: 64 例子: structured_output_compliance获取或填写方式: 按目标检查选择:结构化输出、工具参数基础结构、引用证据结构或任务结果合规;可从已建Schema评估器详情content.templateKey取得,不使用Prompt模板UUID。 |
|
| schemaConfig | object | 仅schema类型的配置对象;创建省略或空对象使用所选系统模板默认配置。修改省略保持;显式提交时作为整份输入重新规范化,未提供schema/missingPolicy的项回退当前所选模板默认值,不与旧对象逐项合并。 允许 null: False 例子: {"schema": {"type": "object", "required": ["answer"], "properties": {"answer": {"type": "string", "minLength": 1}}}, "missingPolicy": "fail"}获取或填写方式: 由调用方按本页schemaConfig.schema与missingPolicy说明组装,或先读详情content.schemaConfig再修改。 |
|
| evalScope | string | 仅prompt类型,trace评估整条Trace,span评估Span;创建省略为trace,修改省略保留。schema类型不要传。 允许 null: False 可选值: ['trace', 'span'] 例子: trace获取或填写方式: 按评估范围选择固定值。 |
|
| resultType | string | prompt支持boolean或score,创建默认boolean;schema只支持boolean。修改省略保留;改变类型时resultConfig由服务端重建。boolean产出通过/不通过,score产出0–100整数评分。 允许 null: False 可选值: ['boolean', 'score'] 例子: boolean获取或填写方式: 按业务是否需要评分选择;不提交resultConfig。 |
|
| agentRuntime | string | Agent运行环境过滤条件,最长256字符的请求值会规范化,实际保存最多128字符;空字符串不限定。常见别名会映射为标准名称,例如ClaudeCode转claude。修改省略保留、空字符串清除。 允许 null: False 最大长度: 256 允许空字符串: True 例子: codex获取或填写方式: 从当前空间Agent监测Trace的agent_runtime字段取得,例如codex、claude、opencode等;不要把示例当本空间已有值。 |
|
| agentID | string | Agent实例过滤条件,最长256字符。创建省略为空;修改省略保留、空字符串清除。 允许 null: False 最大长度: 256 允许空字符串: True 例子: agent_checkout_01获取或填写方式: 从当前空间Agent监测Trace的agent_id字段或控制台实例详情取得。 |
|
| appID | string | LLM目标应用过滤条件,最长256字符。创建省略为空;修改省略保留、空字符串清除。 允许 null: False 最大长度: 256 允许空字符串: True 例子: support_assistant获取或填写方式: 从列出LLM应用的content.data[].appId或当前空间LLM应用详情取得,填写公开appId,不是配置记录uuid。 |
|
| appName | string | LLM应用显示名称,最长256字符,保存后写入评估结果的app_name标签;不参与在线候选Trace筛选,筛选应用使用appID。修改省略保留、空字符串清除。 允许 null: False 最大长度: 256 允许空字符串: True 例子: 客服助手获取或填写方式: 从目标应用控制台名称或已采集Trace的app_name字段取得,作为结果展示标签;实际目标应用筛选另填appID。 |
|
| language | string | 评估输出语言,非空字符串最长32字符。创建省略使用本次请求语言;修改省略保留。读取请求语言只影响展示/生成的旧版输入模板,不改变已保存的评估输出语言。 允许 null: False 最小长度: 1 最大长度: 32 例子: zh获取或填写方式: 按所需评估结果语言填写,例如zh或en;已有值见详情content.targetConfig.language。 |
|
| samplingRate | integer | 在线采样百分比,整数0–100,创建默认20;0停止新采样但不改变enabled/disabled状态。修改省略保留。 允许 null: False $minValue: 0 $maxValue: 100 例子: 20获取或填写方式: 调用方按成本与覆盖率设置;先读详情确认现值。 |
|
| dailyCallLimit | integer | 每日调用上限,整数1–1000000,创建默认10000;修改省略保留。不是历史结果数量,也不是0表示不限。 允许 null: False $minValue: 1 $maxValue: 1000000 例子: 10000获取或填写方式: 调用方按预算设置,并在控制台核对实际执行情况。 |
|
| timeoutSeconds | integer | 单次在线评估超时,单位秒,整数5–300,创建默认30;修改省略保留。不是本HTTP请求的超时时间。 允许 null: False $minValue: 5 $maxValue: 300 例子: 30获取或填写方式: 调用方按目标评估执行时长设置。 |
|
| maxRetries | integer | 在线评估任务最大重试次数,整数0–5,创建默认2;0表示不追加重试。修改省略保留。不是本接口请求的重试次数。 允许 null: False $minValue: 0 $maxValue: 5 例子: 2获取或填写方式: 调用方按评估容错与预算设置。 |
参数补充说明¶
JSON 请求体至少包含一个配置字段。只更新请求中出现的字段。对象或数组字段整体替换,省略字段保留原值。显式 0 会更新数值,允许为空的文本字段可传空字符串清除。评估类型 evalType 由创建时确定。
修改后返回更新后的配置。下面的示例将采样率置为 0,评估器状态保持原值。
请求例子¶
curl 'https://openapi.guance.com/api/v1/agent_eval/evaluator/aeve_0123456789abcdef0123456789abcdef/modify' \
--request POST \
--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": 0,
"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 | 请求字段、类型或约束不符合声明;版本1模板格式或变量路径无效 | 参数解析失败;模板解析错误时message说明具体原因。 | 按参数表纠正;模板使用有效路径和完整双花括号,不发送未声明字段。 |
| 406 | ft.InvalidParameterV2 | Body为空、字段组合或保留配置校验不通过、Prompt/Schema专用字段混用、模板版本组合或Schema配置/引用不合法;URL中携带body参数 | 参数{}的值 {}无效;也可能返回具体原因,例如userPromptTemplate requires inputTemplateVersion 1或OpenAPI Schema evaluation requires valid local Draft 7 references。 |
按本页字段组合修正JSON Body;版本1不同时传selectedInputFields,Schema只用可解析的文档内Draft 7引用;不要用URL body参数提交。 |
| 404 | ft.ObjectNotExists | 目标评估器不存在、属于其他空间或为系统内置评估器;修改时引用的内置Prompt或Schema模板不存在 | Agent evaluator does not exist;模板相关消息为Agent evaluation Prompt does not exist、Agent evaluation Prompt template does not exist或Agent Schema evaluation template does not exist。 | 先用本空间Key列出评估器核对目标UUID;若修改模板,再按本页来源核对本空间内置Prompt模板UUID或Schema模板标识。 |
| 400 | ft.InvalidAction | 改名与工作空间已有评估器名称冲突,包括并发修改 | Evaluator name already exists | 先列出现有评估器,选择未使用的名称;失败后先读回详情确认状态再重试。 |
| 500 | ft.InternalServerError | 保存数据库记录、写入审计或其他依赖发生未处理异常 | 内部错误 | 保留traceId,先读回目标配置或列表确认实际保存状态,再决定是否重试;不要把失败响应当作没有保存。 |