Code 评估器

返回值契约

evaluate 函数每次处理一条数据项，返回结果必须包含以下两个字段。

评估结果页会同时展示原始分数、分数范围与归一化分数，因此建议 score 使用固定区间（例如二值制的 0 与 1，或百分制的 0 到 100），避免同一评估器在不同数据上返回不同量纲的分值。explanation 应写明触发该分数的具体原因，例如缺失了哪个字段、命中了哪个敏感词，而不是笼统的“不符合要求”。

变量映射规则

编辑区下方的变量映射表格由平台自动解析 evaluate 函数的入参生成，无需手工声明。规则是：没有默认值的参数为必填变量，有默认值的参数为可选变量。

以 Python 模板为例，input 与 output 因无默认值被标记为必填，context 因带有默认值 None 被标记为可选。JavaScript 中不存在默认值语法时，三个参数都会被判定为必填，若希望某个变量可选，可写作 function evaluate(input, output, context = null)。

参数名不限于 input（必有）、output（必有）、context，返回参数 score（必有）与 explanation（必有），其他可自定义。声明后，这些变量会出现在创建评估任务时的字段映射中，逐一指定其从哪个数据字段取值即可。还可以在变量映射表中为每个变量填写描述，说明该变量期望接收什么内容。配置完成后单击右上角保存。

常见检查场景的示例代码集中在代码示例中，涵盖格式校验、数值容差比对、工具调用核对与扣分制质检。

格式校验

要求 Agent 输出为合法 JSON，且必须包含 title 与 items 两个字段，items 至少有一项。

def evaluate(input, output, context=None):
    import json

    text = output if isinstance(output, str) else json.dumps(output, ensure_ascii=False)

    try:
        data = json.loads(text)
    except Exception as e:
        return {"score": 0, "explanation": "输出不是合法 JSON：%s" % e}

    if not isinstance(data, dict):
        return {"score": 0, "explanation": "输出 JSON 顶层不是对象"}

    missing = [k for k in ("title", "items") if k not in data]
    if missing:
        return {"score": 0, "explanation": "缺失必需字段：%s" % ", ".join(missing)}

    if not isinstance(data["items"], list) or len(data["items"]) == 0:
        return {"score": 0, "explanation": "items 不是数组或为空数组"}

    return {"score": 1, "explanation": "JSON 合法且包含 title 与 %d 条 items" % len(data["items"])}

数值容差比对

比对 Agent 给出的数值答案与标准答案，允许千分之一的相对误差。expected 是自定义变量，在创建评估任务时映射到数据集中的标准答案列。

def evaluate(output, expected, tolerance=0.001):
    import re

    def to_number(v):
        if isinstance(v, (int, float)):
            return float(v)
        m = re.search(r"-?\d+(?:\.\d+)?", str(v).replace(",", ""))
        return float(m.group()) if m else None

    got, want = to_number(output), to_number(expected)

    if want is None:
        return {"score": 0, "explanation": "标准答案中未解析到数值"}
    if got is None:
        return {"score": 0, "explanation": "模型输出中未解析到数值"}

    denominator = abs(want) if want != 0 else 1.0
    diff = abs(got - want) / denominator

    if diff <= tolerance:
        return {"score": 1, "explanation": "数值匹配：期望 %g，实际 %g" % (want, got)}
    return {"score": 0, "explanation": "数值偏差超限：期望 %g，实际 %g，相对误差 %.2f%%" % (want, got, diff * 100)}

注意 tolerance 带有默认值，因此在变量映射中会被标记为可选。若不在任务中映射该变量，代码将使用默认值。

工具调用核对

检查 Agent 是否调用了必需工具。该示例将工具上下文序列化为字符串后，检查每个必需工具名是否在其中出现，context 通常映射到链路数据的 trace.tool_context。需要注意，这种匹配方式不区分工具名的出现位置：如果必需工具名恰好出现在其他工具调用的参数或返回内容中，也会被计入“已调用”，结果可能偏高，评估结论需结合真实数据复核。

def evaluate(output, context=None, required_tools="search,summarize"):
    import json

    expected = [t.strip() for t in str(required_tools).split(",") if t.strip()]
    if not expected:
        return {"score": 1, "explanation": "未声明必需工具，默认通过"}

    raw = context if isinstance(context, str) else json.dumps(context or {}, ensure_ascii=False)

    called = set()
    for name in expected:
        if name in raw:
            called.add(name)

    missing = [t for t in expected if t not in called]
    hit_rate = len(called) / len(expected)

    if not missing:
        return {"score": 1, "explanation": "全部必需工具均已调用：%s" % ", ".join(expected)}
    return {
        "score": round(hit_rate, 2),
        "explanation": "缺少工具调用：%s（命中 %d/%d）" % (", ".join(missing), len(called), len(expected)),
    }

扣分制质检

JavaScript 版本，采用百分制扣分模型，同时检查敏感表述、输出长度与格式要求，一次性给出综合分与扣分明细。

function evaluate(input, output, context = null) {
  const text = typeof output === 'string' ? output : JSON.stringify(output)
  const banned = ['稳赚不赔', '保证收益', '百分之百', '绝对安全']

  let score = 100
  const reasons = []

  const hits = banned.filter((w) => text.includes(w))
  if (hits.length > 0) {
    score -= 40 * hits.length
    reasons.push(`命中禁用表述：${hits.join('、')}`)
  }

  if (text.trim().length < 20) {
    score -= 30
    reasons.push(`回答过短，仅 ${text.trim().length} 字`)
  }

  if (!/风险提示|仅供参考/.test(text)) {
    score -= 20
    reasons.push('缺少风险提示语')
  }

  score = Math.max(0, score)

  return {
    score,
    explanation: reasons.length === 0 ? '通过全部质检项' : reasons.join('；'),
  }
}
module.exports = evaluate