跳转至

创建并启用评估器



POST /api/v1/agent_eval/evaluator/create

概述

保存评估配置并启用评估器。

调用前和使用步骤

使用目标工作空间的DF-API-KEY;即使只读,也需Agent监测的应用配置管理权限。仅操作当前空间的custom评估器,不暴露系统内置评估器。参数只放在对应Query/路径或JSON Body,禁止使用URL中的body参数。 此接口保存配置后直接启用,返回HTTP200只证明配置保存成功,不代表已有Trace完成评估;后续在线调度受采样、每日上限、数据到达和AI能力影响。创建不具备请求幂等Key,同名会被拒绝;响应超时先列出评估器确认,不盲目重试。返回content.uuid供后续管理。版本1使用inputTemplateVersion=1和userPromptTemplate,从模板推导变量,不传selectedInputFields。模板仅引用数据路径,不支持执行表达式;root为根记录,spans为按时间排列的执行记录,可用spans[*].output等路径。旧版custom模式须传非空selectedInputFields;旧版builtin模式可省略,沿用系统输入。

内置Prompt的UUID必须来自本空间控制台模板选择或已存在评估器,且仍须提交promptContent。Schema只支持agent目标和boolean结果,不传Prompt专用字段;四个templateKey的含义见参数表。修改配置前可先在控制台核对采集数据。

版本1完整请求(替换Endpoint、Key和实际appID):

curl '<Endpoint>/api/v1/agent_eval/evaluator/create' \
  --request POST \
  --header 'DF-API-KEY: <DF-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data-binary '{
  "name": "LLM 原始输入输出评估",
  "evalType": "prompt",
  "targetType": "llm",
  "appID": "support_assistant",
  "promptOrigin": "custom",
  "promptContent": "判断回答是否完整回应用户问题,并解释原因。",
  "inputTemplateVersion": 1,
  "userPromptTemplate": "输入:{{root.input}}\n输出:{{root.output}}",
  "language": "zh",
  "samplingRate": 20
}'

Schema完整请求(不依赖Prompt模板UUID):

curl '<Endpoint>/api/v1/agent_eval/evaluator/create' \
  --request POST \
  --header 'DF-API-KEY: <DF-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data-binary '{
  "name": "Agent 输出结构检查",
  "evalType": "schema",
  "targetType": "agent",
  "templateKey": "structured_output_compliance",
  "schemaConfig": {
    "schema": {
      "type": "object",
      "required": [
        "answer"
      ],
      "properties": {
        "answer": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "missingPolicy": "fail"
  },
  "agentRuntime": "codex"
}'

appName仅保存应用显示名称并写入评估结果标签,不作为候选Trace过滤条件;限制目标LLM应用须设置appID。

请求头

参数名 类型 必选 说明
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 Y 工作空间内唯一的评估器名称,去除首尾空白后须有内容,最长128字符。创建必填;修改时省略保留。
允许 null: False
最小长度: 1
最大长度: 128
例子: LLM 回答完整性
获取或填写方式: 调用方命名;先用列出评估器检查已有名称。
evalType string 创建时可选prompt或schema,省略为prompt。创建后不可改变;修改接口不接受此参数。
允许 null: False
可选值: ['prompt', 'schema']
例子: prompt
获取或填写方式: 根据需要进行语义判断还是JSON结构校验选择。
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 请求体提交配置。请求成功后评估器状态为 enabled。Prompt 评估需要工作空间具备可用的 AI 能力。

下面的 LLM 示例使用自定义 Prompt,从目标应用的 Trace 读取输入和输出。将 appID 替换为当前工作空间的应用 ID。返回的 content.uuid 可用于查询、修改、启停和删除。

使用内置 Prompt 时,填写 promptOrigin 为 builtin、当前工作空间的模板 UUID 和评估指令。创建 Schema 评估器时,填写 evalType 为 schema、targetType 为 agent 及其系统模板标识。

请求例子

curl 'https://openapi.guance.com/api/v1/agent_eval/evaluator/create' \ --request POST \ --header 'DF-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-binary ' { "name": "LLM 回答完整性", "evalType": "prompt", "targetType": "llm", "appID": "support_assistant", "promptOrigin": "custom", "promptContent": "判断回答是否完整回应了用户问题。给出通过或不通过的结果及原因。", "selectedInputFields": [ "gen_ai_input", "gen_ai_output" ], "resultType": "boolean", "language": "zh", "samplingRate": 20 } '

响应

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 请求字段、类型或约束不符合声明;版本1模板格式或变量路径无效 参数解析失败;模板解析错误时message说明具体原因。 按参数表纠正;模板使用有效路径和完整双花括号,不发送未声明字段。
406 ft.InvalidParameterV2 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 evaluation Prompt template does not exist 或 Agent Schema evaluation template does not exist 从当前空间控制台的内置Prompt模板或现有评估器详情确认promptUUID;Schema使用本页列出的四个templateKey。不要把评估器UUID当模板UUID。
400 ft.InvalidAction 创建的名称与工作空间已有评估器名称冲突,包括并发创建 Evaluator name already exists 列出现有评估器后选择唯一名称;创建超时先查询确认是否已保存,不盲目重复提交。
400 ft.NotEnabledAiRobotServer 创建Prompt评估器时,当前空间AI能力不可用 未启用/或已经关闭 AI 服务 在控制台启用并确认当前空间AI服务可用后重试;Schema类型创建不需要此Prompt能力检查。
500 ft.InternalServerError 保存数据库记录、写入审计或其他依赖发生未处理异常 内部错误 保留traceId,先读回目标配置或列表确认实际保存状态,再决定是否重试;不要把失败响应当作没有保存。

相关文档

文档评价

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