Go 构建 AI 评测样本 CLI：校验 JSONL、抽样回放并生成通过率报告

模型迭代换版本、改系统提示词或是调整检索相关参数之后，大家很容易漏掉一个隐患：评测样本文件本身已经出问题了，比如某一行少了必填字段，另一行把数值型的评分误写成字符串类型，最后算出来的整体通过率看起来还挺规整，完全发现不了底层错误。这个小工具用Go读取JSONL格式样本，先逐条校验每条样本的输入和期望标签，再用固定随机种子抽取指定批量的样本回放，最后输出带明确失败原因的统计报告。

先把评测输入收敛成JSONL

评测文件放在 cases.jsonl，每一行都是独立的JSON对象。示例里的任务是判断客服消息是否需要转人工介入，工具本身不绑定任何模型供应商，只关心输入内容、期望标签和可选的元数据字段。

{"case_id":"refund-001","input":"订单重复扣款，想申请退款","expected":"human","meta":{"scene":"payment"}}
{"case_id":"password-002","input":"忘记密码怎么改","expected":"self_service","meta":{"scene":"account"}}

这里用 case_id 做样本的稳定唯一标识，用 expected 存储业务侧的期望值。不要把评分结果直接覆盖回原始样本文件，不然下次回放的时候很难区分原始输入和上次运行生成的产物。

用Go写一个不依赖第三方库的校验器

标准库的 encoding/json.Decoder 完全能处理逐行JSON解析。为了把错误定位到具体文件位置，校验函数同时接收行号参数，直接拒绝空标识、空输入和不在枚举范围内的未知期望标签。

package main

import (
    "bufio"
    "encoding/json"
    "fmt"
    "io"
    "os"
    "strings"
)

type Case struct {
    CaseID   string            `json:"case_id"`
    Input    string            `json:"input"`
    Expected string            `json:"expected"`
    Meta     map[string]string `json:"meta"`
}

var allowed = map[string]bool{"human": true, "self_service": true}

func readCases(path string) ([]Case, []string, error) {
    file, err := os.Open(path)
    if err != nil { return nil, nil, err }
    defer file.Close()

    scanner := bufio.NewScanner(file)
    scanner.Buffer(make([]byte, 1024), 1024*1024)
    var cases []Case
    var problems []string
    line := 0
    for {
        line++
        if !scanner.Scan() {
            if err := scanner.Err(); err != nil { return nil, nil, err }
            break
        }
        raw := strings.TrimSpace(scanner.Text())
        if raw == "" { continue }
        var item Case
        if err := json.Unmarshal([]byte(raw), &item); err != nil {
            problems = append(problems, fmt.Sprintf("line %d: invalid json", line))
            continue
        }
        switch {
        case item.CaseID == "":
            problems = append(problems, fmt.Sprintf("line %d: missing case_id", line))
        case strings.TrimSpace(item.Input) == "":
            problems = append(problems, fmt.Sprintf("%s: empty input", item.CaseID))
        case !allowed[item.Expected]:
            problems = append(problems, fmt.Sprintf("%s: unsupported expected", item.CaseID))
        default:
            cases = append(cases, item)
        }
    }
    return cases, problems, nil
}

Scanner 默认的单行长度上限很小，而评测样本里经常会带一段很长的上下文内容，这里直接显式调高原生上限。校验失败的行不会进入后续的抽样流程，这样报告里的统计分母只代表结构完全合法的样本，样本文件本身的格式错误会单独列出来提示。

固定种子抽样，保证回放结果可横向对比

全量跑一遍评测的成本太高的时候，可以先抽部分样本快速验证，但随机抽样的结果必须是可复现的。命令行接收 -seed 和 -limit 两个参数，同一份JSONL文件、同一个种子、同一个抽样上限，最后得到的case_id顺序完全一致。

func pick(cases []Case, limit int, seed int64) []Case {
    if limit  len(cases) { limit = len(cases) }
    r := rand.New(rand.NewSource(seed))
    order := r.Perm(len(cases))
    picked := make([]Case, 0, limit)
    for _, index := range order[:limit] {
        picked = append(picked, cases[index])
    }
    sort.Slice(picked, func(i, j int) bool { return picked[i].CaseID 

抽样完成后按 case_id 排序，是为了让报告做差异对比的时候更稳定。随机种子只用来决定选哪些样本，不要把业务规则逻辑塞到种子生成逻辑里；如果样本的场景分布明显不均衡，应该在文件里新增scene分层字段，再按不同分类分别抽取样本。

把模型回放和规则判定拆开

真实项目里可以把回放器直接接到内部的模型网关。为了让示例代码可以完全离线运行，这里用一个占位接口返回模型结果，接口只输出标签和原始返回文本，判定器再独立检查标签是否和期望一致、输出内容是否为空。

type Result struct {
    Label string `json:"label"`
    Text  string `json:"text"`
}

type Checker struct{}

func (Checker) Check(c Case, got Result) (bool, string) {
    if strings.TrimSpace(got.Text) == "" { return false, "empty_output" }
    if got.Label != c.Expected { return false, "label_mismatch" }
    return true, "ok"
}

拆分成两个独立模块之后，换成HTTP客户端拉取、离线假数据或者之前录制的历史响应，都不会影响样本校验的逻辑。生产环境跑回放的时候还要设置连接超时和整体任务超时，记录请求批次、模型版本和响应耗时，不要把完整的用户隐私原文直接写到公开的报告里。

输出通过率和可复查的失败明细

报告至少要统计四个核心数值：合法样本总数、抽样样本数、通过数、失败数。失败项里必须附带 case_id 和对应规则名，不能只笼统显示“失败3条”。一个结构紧凑的报告示例如下：

{
  "seed": 20260727,
  "sampled": 20,
  "passed": 18,
  "failed": 2,
  "pass_rate": 0.9,
  "failures": [
    {"case_id":"refund-014","rule":"label_mismatch"},
    {"case_id":"account-008","rule":"empty_output"}
  ]
}

门禁逻辑可以设置成 pass_rate 的时候返回非零退出状态，让CI直接终止后续的发布流程；阈值本身不是绝对的质量标准，只是用来把效果明显回落的版本挡在发布环节外面。少量高风险场景的样本还可以单独配置为“必须全部通过”，避免平均值掩盖支付、权限这类关键场景的问题。

本地运行与上线前检查

命令行入口逻辑可以保持得非常简单：

go run . -input cases.jsonl -limit 20 -seed 20260727 -report report.json
cat report.json
go test ./...

工具做完验收的时候重点核对三件事：格式错误的坏JSON能不能指出准确的行号；完全相同的参数重复运行能不能得到完全一致的case_id序列；出现不通过的报告的时候进程能不能返回非零状态。上线前再把模型版本、提示词版本、样本集版本都写到报告元数据里，后续出问题才有依据定位这次效果变动到底是改了哪部分内容导致的。

常见问题：AI 评测 CLI 怎么避免误判

为什么不直接用平均分做发布门禁？

平均分会直接掩盖少数关键场景的失败。支付、权限、合规类的样本更适合单独设置硬门槛，剩下的普通样本再参考总体通过率。

抽样种子应该每次自动变化吗？

回归对比阶段建议固定种子，保证前后两次运行的样本池完全一致；需要扩大评测覆盖范围的时候再按计划轮换种子，并且把种子值写到报告里存档，不能让随机生成的不可控结果变成发布的判断依据。

模型输出要不要全部保存？

调试阶段可以保存脱敏之后的原始输出。正式环境至少保留输出摘要、规则判定结果和必要的trace_id，原始文本的保存期限和访问权限要符合对应的业务合规要求。

JSONL 文件很大时怎么处理？

保持逐行扫描的读取逻辑，不要一次性把整个文件加载到内存里；同时设置单行内容的长度上限，超长的上下文可以改成外部引用或是单独的样本附件存储。

小结

这个CLI的价值不在于替代人工的模型评审，而在于把整个评测流程固定下来：输入先做校验，抽样可重复回放，结果附带规则名，门禁返回标准退出状态。后续样本量和业务复杂度上升之后，再接真正的模型网关、分层抽样逻辑和人工复核流程，也完全可以沿用这四个核心边界。