# 细粒度评估 - InvokeOpsFineGrainedEvaluation #### 功能介绍 该接口提供细粒度评估能力，基于评估器维度，无需预先创建评测集和评估任务，只需指定评估器并传入待评估数据即可完成评估，评估结果通过流式（SSE）或非流式方式返回。 适用场景： - 场景1（dataset）：对已有的输入输出数据进行评估评分。 - 场景2（agent）：传入输入调用智能体获取输出后进行评估。 - 场景3（trace）：传入TraceId，从可观测子服务获取trace数据后进行评估。 与现有评估任务流程的区别： - 无需创建评测集，数据直接在请求中传入。 - 无需创建评估任务，即发即评。 - 评估结果默认不持久化，仅在响应中返回。 - 支持SSE流式返回，评估过程中实时推送结果。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-agentarts/Permission.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | agentarts:evaluator:invokeOpsFineGrainedEvaluation | Write | evaluator \* | g:ResourceTag/\ | - | - | #### URI POST /v1/ops/evaluators/{evaluator_id}/evaluations 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | evaluator_id | 是 | String | **参数解释：** 评估器的唯一标识符，用于指定本次评估使用的评估器。通过创建评估器接口返回，或在评估器列表中查看。 **约束限制：** 字符串类型，长度1到36字符，评估器必须已存在。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | scenario | 是 | String | **参数解释：** 评估场景，指定本次评估的数据来源和处理方式。 **约束限制：** 必须为枚举值之一。 **取值范围：** - dataset：评测集评估，直接传入输入输出数据进行评估。 - agent：智能体调用评估，传入输入调用智能体获取输出后进行评估。 - trace：Trace评估，传入TraceId从可观测子服务获取trace数据后进行评估。 **默认取值：** 不涉及。 | | evaluator_version | 是 | String | **参数解释：** 评估器的版本号，用于指定使用评估器的特定版本。 **约束限制：** 不涉及。 **取值范围：** 由英文字母、数字、点(.)及连字符(-)组成的字符串，长度为0\~36个字符。 **默认取值：** 评估器最新版本。 | | data | 是 | [OpsFineGrainedEvaluationData] object | **参数解释：** 待评估的数据，根据评估场景（scenario）的不同，需要传入不同的字段组合。 - scenario=dataset时，需传入items字段（每条为键值对列表，包含评估器Prompt中引用的所有变量，如input、actual_output等）。 - scenario=agent时，需传入evaluation_object_config和items字段（每条为键值对列表，包含输入相关字段如input，API调用智能体获取actual_output后自动填充）。 - scenario=trace时，需传入trace_ids字段。 **约束限制：** 数据条目数最大支持100条。scenario=dataset时需传入items字段；scenario=agent时需传入evaluation_object_config和items字段；scenario=trace时需传入trace_ids字段。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | stream | 否 | Boolean | **参数解释：** 是否启用流式返回。启用后，评估结果通过SSE（Server-Sent Events）协议逐步推送，调用方可实时获取评估进度和结果。 **约束限制：** 不涉及。 **取值范围：** true（流式返回）、false（非流式返回，等待全部评估完成后一次性返回JSON结果）。 **默认取值：** true。 | 表3OpsFineGrainedEvaluationData | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | items | 否 | Array of [OpsFineGrainedEvaluationDatasetItem] objects | **参数解释：** 待评估的数据条目列表，scenario=dataset和scenario=agent时必填。每条数据为键值对列表，字段名和字段数量由评估器Prompt模板决定。 - scenario=dataset时，每条需包含评估器Prompt中引用的所有变量对应的字段（如input、actual_output等）。 - scenario=agent时，每条需包含输入相关字段（如input），API将调用智能体获取actual_output后自动填充。 **约束限制：** 数组长度1到100。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | evaluation_object_config | 否 | [OpsFineGrainedEvaluationObjectConfig] object | **参数解释：** 评估对象（智能体/工作流）的配置信息，用于场景2（agent）和场景3（trace）中指定被评估的智能体。 **约束限制：** id、type、name、version为必填项。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | agent_output_variable | 否 | String | **参数解释：** 评估器中接收智能体输出的变量名，scenario=agent时使用。API调用智能体获取输出后，将输出填入该变量名对应的字段中。若不传，默认为actual_output。 **约束限制：** 不涉及。 **取值范围：** 由英文字母、数字及下划线(_)组成的字符串，长度为1\~100个字符。 **默认取值：** actual_output。 | | trace_ids | 否 | Array of strings | **参数解释：** 待评估的TraceId列表，API将根据TraceId从可观测子服务获取对应的trace数据后进行评估，scenario=trace时必填。 **约束限制：** 数组长度1到100，每个元素字符长度1到100。TraceId必须在可观测子服务中存在，否则返回TRACE_NOT_FOUND错误。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4OpsFineGrainedEvaluationDatasetItem | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | \[数组元素\] | 否 | Array of [OpsFineGrainedEvalFieldKV] objects | **参数解释：** 待评估的单条数据，以键值对列表形式传入，字段名和字段数量由评估器的Prompt模板中引用的变量决定。评估器Prompt中使用*{{key}}*引用对应字段的value。 - scenario=dataset时，需包含评估器Prompt中引用的所有变量对应的字段（如input、actual_output等）。 - scenario=agent时，需包含输入相关的字段（如input），actual_output由API调用智能体后自动填充。 **约束限制：** 不允许为空数组，同一item内key不允许重复。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5OpsFineGrainedEvalFieldKV | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释：** 字段名，与评估器Prompt模板中的变量名对应。 **约束限制：** 字符长度1到100，同一item内不允许重复。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | value | 是 | String | **参数解释：** 字段值。 **约束限制：** 字符长度0到10000。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6OpsFineGrainedEvaluationObjectConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 是 | String | **参数解释：** 评估对象的唯一标识符。通过查询智能体/工作流列表接口获取，或在对应管理页面查看。 **约束限制：** 字符长度1到36。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 **默认取值：** 不涉及。 | | type | 是 | String | **参数解释：** 评估对象的类型。 **约束限制：** 必须为枚举值之一。 **取值范围：** - WORKFLOW：工作流类型 - AGENT：智能体类型 - MULTI_AGENT：多智能体类型 **默认取值：** 不涉及。 | | name | 是 | String | **参数解释：** 评估对象的名称。 **约束限制：** 字符长度1到100。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | version | 是 | String | **参数解释：** 评估对象的版本号。 **约束限制：** 字符长度1到100。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | inputs_mapping | 否 | [OpsFineGrainedEvaluationObjectConfigInputsMapping] object | **参数解释：** 输入数据来源映射定义，scenario=agent时必填。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表7OpsFineGrainedEvaluationObjectConfigInputsMapping | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | input | 否 | String | **参数解释：** 智能体执行时的输入参数来源字段。 **约束限制：** 字符长度1到100。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | workflow_input | 否 | [OpsFineGrainedEvaluationObjectConfigInputsMappingWorkflowInput] object | **参数解释：** 工作流输入参数来源配置。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8OpsFineGrainedEvaluationObjectConfigInputsMappingWorkflowInput | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 否 | String | **参数解释：** 工作流执行时的参数来源。 **约束限制：** 字符长度1到100。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | data | One of: - [OpsFineGrainedEvaluationResult] object - [OpsFineGrainedEvaluationSSEEvent] object | **参数解释：** 细粒度评估结果。data字段根据stream参数的不同，返回不同的结构： - stream=true时，data为OpsFineGrainedEvaluationSSEEvent，为SSE流式事件中的单条评估结果数据（item_completed事件的data部分）。 - stream=false时，data为OpsFineGrainedEvaluationResult，为完整的评估结果，包含所有条目的评估详情。 **取值范围：** 不涉及。 | 表10OpsFineGrainedEvaluationResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | items | Array of [OpsFineGrainedEvaluationItemResult] objects | **参数解释：** 各条评估结果的详细列表。 **取值范围：** 不涉及。 | 表11OpsFineGrainedEvaluationItemResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | **参数解释：** 数据条目的索引，从0开始。 **取值范围：** 不涉及。 | | item_id | String | **参数解释：** 数据条目的标识。scenario=dataset和scenario=agent时为item_N格式，scenario=trace时为对应的trace_id。 **取值范围：** 不涉及。 | | status_code | String | **参数解释：** 单条数据评估执行的状态码。"0"表示评估成功，非"0"表示评估过程中出现异常。 **取值范围：** 由数字组成的字符串，长度为0\~100个字符。 | | error | String | **参数解释：** 评估过程中产生的错误详细信息。仅在status_code非"0"时出现。 **取值范围：** 描述性错误字符串。 | | score | Float | **参数解释：** 评估评分，取值范围0到1。 **取值范围：** 0-1。 | | reason | String | **参数解释：** 评估原因说明。 **取值范围：** 不涉及。 | 表12OpsFineGrainedEvaluationSSEEvent | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | **参数解释：** 当前数据条目的索引，从0开始。 **取值范围：** 不涉及。 | | total | Integer | **参数解释：** 总数据条目数。 **取值范围：** 不涉及。 | | item_id | String | **参数解释：** 数据条目的标识，用于关联评估结果。scenario=dataset和scenario=agent时为item_N格式，scenario=trace时为对应的trace_id。 **取值范围：** 不涉及。 | | status_code | String | **参数解释：** 单条数据评估执行的状态码。"0"表示评估成功，非"0"表示评估过程中出现异常。 **取值范围：** 由数字组成的字符串，长度为0\~100个字符。 | | error | String | **参数解释：** 评估过程中产生的错误详细信息。仅在status_code非"0"时出现。 **取值范围：** 描述性错误字符串。 | | score | Float | **参数解释：** 评估评分，取值范围0到1。 **取值范围：** 0-1。 | | reason | String | **参数解释：** 评估原因说明。 **取值范围：** 不涉及。 | **状态码：400** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表14OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：403** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表16OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：404** 表17响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表18OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：429** 表19响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表20OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：500** 表21响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表22OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | #### 请求示例 - 使用已有评估器对评测集中的输入输出数据进行细粒度评估（场景1：dataset） ``` POST https://api.example.com/v1/ops/evaluators/7ebc91e2-2380-4072-a503-6b20888abb08/evaluations { "scenario" : "dataset", "evaluator_version" : "1.0.0", "data" : { "items" : [ [ { "key" : "input", "value" : "请介绍一下量子计算的基本原理" }, { "key" : "actual_output", "value" : "量子计算是利用量子力学原理进行计算的技术..." }, { "key" : "expected_output", "value" : "量子计算利用量子比特的叠加和纠缠特性..." } ], [ { "key" : "input", "value" : "什么是机器学习？" }, { "key" : "actual_output", "value" : "机器学习是人工智能的一个分支..." } ] ] }, "stream" : true } ``` - 使用已有评估器对智能体输出进行评估，API内部调用智能体获取输出后评估（场景2：agent） ``` POST https://api.example.com/v1/ops/evaluators/7ebc91e2-2380-4072-a503-6b20888abb08/evaluations { "scenario" : "agent", "evaluator_version" : "1.0.0", "data" : { "evaluation_object_config" : { "id" : "5d61ce56-ae88-4dbd-85e7-07a6b1f38b46", "type" : "AGENT", "name" : "my-agent", "version" : "1772677877865", "inputs_mapping" : { "input" : "instruction" } }, "agent_output_variable" : "actual_output", "items" : [ [ { "key" : "input", "value" : "请帮我分析一下这段代码的时间复杂度" } ], [ { "key" : "input", "value" : "写一个快速排序算法" } ] ] }, "stream" : true } ``` - 使用已有评估器对智能体运行产生的trace进行评估，API从可观测子服务获取trace数据后评估（场景3：trace） ``` POST https://api.example.com/v1/ops/evaluators/7ebc91e2-2380-4072-a503-6b20888abb08/evaluations { "scenario" : "trace", "evaluator_version" : "1.0.0", "data" : { "trace_ids" : [ "trace-a64cd819-6f91-4568-9f2f-57ef9562ab7b", "trace-b73de920-7a02-5679-0a3g-68fg0463bc8c" ] }, "stream" : true } ``` #### 响应示例 **状态码：200** 评估请求成功。 - stream=true时，返回SSE流式事件，响应体为OpsFineGrainedEvaluationSSEEvent结构。 - stream=false时，返回完整JSON结果，响应体为OpsFineGrainedEvaluationResult结构。 ``` { "data" : { "items" : [ { "index" : 0, "item_id" : "item_0", "status_code" : "0", "score" : 0.85, "reason" : "回答准确，逻辑清晰" }, { "index" : 1, "item_id" : "item_1", "status_code" : "0", "score" : 0.78, "reason" : "回答基本正确，但存在遗漏" } ] } } ``` **状态码：400** 请求错误 ``` { "error_code" : "AgentArts.100004000", "error_msg" : "请求错误" } ``` **状态码：403** 鉴权失败 ``` { "error_code" : "AgentArts.100004030", "error_msg" : "鉴权失败" } ``` **状态码：404** 资源不存在 ``` { "error_code" : "AgentArts.100004040", "error_msg" : "评估器不存在" } ``` **状态码：429** 请求过于频繁 ``` { "error_code" : "AgentArts.100004290", "error_msg" : "并发评估请求超过限制" } ``` **状态码：500** 评估内部错误 ``` { "error_code" : "AgentArts.100005000", "error_msg" : "评估内部错误" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 评估请求成功。 - stream=true时，返回SSE流式事件，响应体为OpsFineGrainedEvaluationSSEEvent结构。 - stream=false时，返回完整JSON结果，响应体为OpsFineGrainedEvaluationResult结构。 | | 400 | 请求错误 | | 403 | 鉴权失败 | | 404 | 资源不存在 | | 429 | 请求过于频繁 | | 500 | 评估内部错误 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。