跳转至

启用或停用评估器



POST /api/v1/agent_eval/evaluator/{evaluator_uuid}/status

概述

设置当前工作空间自定义评估器的启停状态。

调用前和使用步骤

使用目标工作空间的DF-API-KEY;即使只读,也需Agent监测的应用配置管理权限。仅操作当前空间的custom评估器,不暴露系统内置评估器。参数只放在对应Query/路径或JSON Body,禁止使用URL中的body参数。 先读详情核对当前状态,POST JSON设置enabled/disabled。状态未变化时保留原publishedAt/lastScanAt且不重复记录审计;从其他状态启用会更新publishedAt(秒)与lastScanAt(毫秒),Prompt需AI能力可用,Schema需合法文档内引用。停用仅停止新在线调度,已有任务可能仍完成;此接口不清除历史结果,不证明评估已经执行完毕。超时后读回状态再决定是否重试。

路由参数

参数名 类型 必选 说明
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 请求参数

参数名 类型 必选 说明
status string Y 必填enabled或disabled。启用后可对新到数据执行在线评估;停用停止新调度,不代表撤销已经提交的任务。重复设置当前状态不刷新扫描进度,也不重复记录状态变更审计。
允许 null: False
可选值: ['enabled', 'disabled']
例子: disabled
获取或填写方式: 从详情content.status核对当前状态,再选择目标值。

参数补充说明

在 JSON 请求体中传 enabled 启用,传 disabled 停用。重复设置当前状态会保留已有扫描进度。启用 Prompt 评估器时,工作空间须具备可用的 AI 能力。

请求例子

curl 'https://openapi.guance.com/api/v1/agent_eval/evaluator/aeve_0123456789abcdef0123456789abcdef/status' \ --request POST \ --header 'DF-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-binary ' { "status": "disabled" } '

响应

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": "disabled",
        "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 JSON Body缺少status、包含额外字段,或status类型/枚举不符合声明 参数解析失败 JSON Body仅提交status字段,值为enabled或disabled;不在本接口提交配置或模板文本。
406 ft.InvalidParameterV2 status非法;URL中携带body参数;从非enabled状态启用Schema评估器时,已保存Schema含非法的非本地或非Draft 7引用 参数{}的值 {}无效;Schema引用失败为OpenAPI Schema evaluation requires valid local Draft 7 references;URL body参数被拒绝时为Send evaluator parameters in the JSON request body. 状态值只用enabled或disabled,并移除URL body参数;如已保存Schema引用不合法,先通过修改接口修正schemaConfig,再重新启用。
404 ft.ObjectNotExists 目标评估器不存在、属于其他工作空间或是系统内置评估器 Agent evaluator does not exist 使用当前空间Key列出自定义评估器,核对content.data[].uuid;不要使用其他空间或系统内置评估器UUID。
400 ft.NotEnabledAiRobotServer 从非enabled状态启用Prompt评估器时,当前空间AI能力不可用 未启用/或已经关闭 AI 服务 先在控制台启用并确认当前空间AI服务可用;停用不需要此检查,重复设置已有enabled状态也不会再次触发启用检查。
500 ft.InternalServerError 保存数据库记录、写入审计或其他依赖发生未处理异常 内部错误 保留traceId,先读回目标配置或列表确认实际保存状态,再决定是否重试;不要把失败响应当作没有保存。

文档评价

文档内容是否对您有帮助?