Phoenix LLM Judge 验证指南:用黄金数据集与 TPR/TNR/Kappa 校准 LLM 评估器

原创2026-09-22 23:03:541,657 阅读
文章标签:人工智能LLMOps可观测性链路追踪AI 评测模型评测大模型提示工程数据可视化MLOps后端前端

Phoenix LLM Judge 验证指南:用黄金数据集与 TPR/TNR/Kappa 校准 LLM 评估器

本文围绕 Phoenix 评估体系中的 Validation(验证) 环节展开:在把任何 LLM 评估器(LLM Judge)投入生产之前,先用人工标注的黄金数据集度量它与人类判断的一致性,并以 TPR/TNR/Accuracy/Kappa 等量化指标作为放行门槛。读完本文,你将掌握验收标准、指标计算公式、黄金数据集的构建与版本化规范、基于 Phoenix Experiments 的 Python 与 TypeScript 验证流程,以及误分类定位和生产估算修正方法。

为什么要在部署前验证 LLM Judge

LLM-as-a-Judge 并非天然可信:同一个评估器在不同提示词、不同 judge 模型、不同判据下,判断会漂移,甚至出现系统性偏向。Phoenix evals 技能栈的核心原则之一就是 “Validate judges”(验证 judge),要求评估器与人类标签的一致性达到 TPR/TNR 大于 80% 才允许上线,这与 phoenix-evals 技能总览 中 "Code first, LLM for nuance, validate against humans" 的定位一致:代码评估器是确定性的,LLM 只负责处理微妙语义,而两者都必须经过人工基准的检验。

验证的本质是一场 受控实验:把待测评估器当作被测对象(任务),把人工标注当作 ground truth(评估器),再统计两者的一致程度。这与普通任务实验的“角色”恰好对调(见下文表格),理解这一角色转换是理解整个验证流程的关键。

验收标准:先定门槛,再写评估器

在开始任何验证工作之前,先明确放行门槛。Phoenix 的验证指南给出了如下默认验收标准:

需求 目标值
测试集规模 100+ 条样本
正负样本平衡 约 50/50(pass/fail)
准确率 Accuracy >80%
TPR / TNR 两者均 >70%(完整验证建议 >80%)

需要说明的是:validation.md 的“快速门槛”要求 TPR/TNR 均大于 70%,而 Python 验证参考 与 TypeScript 验证参考 给出的更严格目标是 >80% TPR、>80% TNR。实践中建议以 80% 作为硬性门槛,70% 视为最低容忍线;低于 70% 属于明确危险信号,评估器不应上线。

核心指标:定义、公式与适用场景

验证评估器时使用的四类指标如下:

指标 公式 适用场景
Accuracy(准确率) (TP+TN) / Total 通用场景
TPR(Recall,敏感度/召回率) TP / (TP+FN) 质量保障:能否抓出真实失败
TNR(Specificity,特异度) TN / (TN+FP) 安全关键场景:能否不误伤正常输出
Cohen's Kappa 超出随机水平的一致程度 横向比较不同评估器

其中 TPR 回答的是“真实失败中有多少被评估器检出”(漏报风险),TNR 回答的是“正常输出中有多少没有被误判为失败”(误报风险)。两者需要同时观察:只报 Accuracy 无法暴露“对 90% 的 pass 样本全判对、对 90% 的 fail 样本全判错”这种严重失衡;而 TPR 与 TNR 之间的巨大差距本身就是评估器偏向性的信号。

Cohen's Kappa 则进一步排除了“碰巧一致”的成分,用于在多个候选评估器之间横向比较时给出一个校正后的排序依据,其计算公式为:

kappa = (p_o - p_e) / (1 - p_e)

其中 p_o 是观察到的一致率,p_e 是随机一致期望率。Kappa < 0.6 即视为不可接受。

快速验证脚本:十分钟跑出全部指标

以下是 验证指南 提供的开箱即用脚本,基于 scikit-learn 一次性输出分类报告、Kappa 与 TPR/TNR:

from sklearn.metrics import classification_report, confusion_matrix, cohen_kappa_score

print(classification_report(human_labels, evaluator_predictions))
print(f"Kappa: {cohen_kappa_score(human_labels, evaluator_predictions):.3f}")

# Get TPR/TNR
cm = confusion_matrix(human_labels, evaluator_predictions)
tn, fp, fn, tp = cm.ravel()
tpr = tp / (tp + fn)
tnr = tn / (tn + fp)

其中 human_labels 是人工标注的 0/1 标签数组,evaluator_predictions 是评估器对同一批样本的输出标签数组,顺序必须一一对应。cm.ravel() 按 [TN, FP, FN, TP] 顺序展开混淆矩阵,Python 验证参考 中还给出了等价但更紧凑的写法:

from sklearn.metrics import classification_report, confusion_matrix

print(classification_report(human_labels, evaluator_predictions))

cm = confusion_matrix(human_labels, evaluator_predictions)
tn, fp, fn, tp = cm.ravel()
tpr = tp / (tp + fn)
tnr = tn / (tn + fp)
print(f"TPR: {tpr:.2f}, TNR: {tnr:.2f}")

classification_report 输出中的 recall 行即对应 TPR,specificity 需从混淆矩阵自行计算。若按 Python 环境准备参考 的约定,请确保环境已安装 scikit-learn(pip install scikit-learn)。

黄金数据集:结构与构建规范

验证的根基是 黄金数据集(Golden Dataset)——由人类专家标注、代表真实生产分布的小型基准集。其单条样本结构如下:

golden_example = {
    "input": "What is the capital of France?",
    "output": "Paris is the capital.",
    "ground_truth_label": "correct",
}

在 TypeScript 侧,TypeScript 验证参考 约定将人工标签存放在 metadata.groundTruthLabel 字段中,并建议使用独立的数据集名称(例如 "my-app-qa-evaluator-validation"),避免验证实验与任务实验在 Phoenix 中混在一起:

import type { Example } from "@arizeai/phoenix-client/types/datasets";

const goldenExamples: Example[] = [
  { input: { q: "Capital of France?" }, output: { answer: "Paris" },        metadata: { groundTruthLabel: "correct" } },
  { input: { q: "Capital of France?" }, output: { answer: "Lyon" },         metadata: { groundTruthLabel: "incorrect" } },
  { input: { q: "Capital of France?" }, output: { answer: "Major city..." }, metadata: { groundTruthLabel: "incorrect" } },
];

构建步骤

构建黄金数据集遵循四条规范:

  1. 从生产痕迹采样:优先抽取真实流量中的错误样例、负面反馈、边界情况(edge cases),而不是自己随手编造。可以从 Phoenix 的 span 数据中导出真实样本,参考 Python 数据集参考 中 client.spans.get_spans_dataframe(project_identifier="my-app") 的做法,把生产 traces 拉成 DataFrame 后挑选代表性样本。
  2. 平衡正负样本:目标约 50/50 的 pass/fail 比例。严重失衡的数据集会让 Accuracy 失真,也会掩盖 TPR/TNR 的偏斜。
  3. 专家逐条标注:每条样本由人类专家给出 ground truth 标签,这是“黄金”二字的来源——必须人工,不能由另一个 LLM 代标。
  4. 版本化,永不修改旧版本:数据集是可变的会破坏历史对比。新增样本时创建新版本,而不是就地修改:
# GOOD - create new version
golden_v2 = golden_v1 + [new_examples]

# BAD - never modify existing
golden_v1.append(new_example)

在 Phoenix 数据集层面,对应做法是使用 create_dataset 的 upsert 语义配合新的数据集名称(如 qa-test-v2)保存快照,详见 Python 数据集参考 中关于版本化的说明:“Version with tags or new names (e.g., qa-test-v2) when you want a clean snapshot, not just incremental edits”。

关于黄金数据集的规模,两条参考给出了略有差异的指引:validation.md 要求测试集 100+ 条;而 TypeScript 验证参考 指出 20–50 条精心挑选的样本已足够(前提是覆盖边界情况、平衡且全部人工标注)。实践中:迭代期可从 20–50 条起步快速闭环,正式放行前扩充到 100+ 条做最终验收。

用 Phoenix Experiments 执行验证实验

单纯在脚本里算指标可以快速验证,但要让验证过程可复现、可追踪、可回归,应把验证搬进 Phoenix Experiments:数据集 + 任务 + 评估器全部记录在 Phoenix 中,每次 judge 改动都能对比历史实验。

角色对调:评估器成为被测任务

普通任务实验 评估器验证实验
Task = Agent 逻辑 Task = 运行待测评估器
Evaluator = judge 输出 Evaluator = 与人工 ground truth 精确匹配
Dataset = Agent 示例 Dataset = 人工标注的黄金样本

Python:评估器作为任务(元评估)

Python 数据集参考 给出了“元评估(meta evaluation)”模式的完整实现:待测评估器被当作实验的 task,而一个 exact_match 启发式评估器负责比对评估器输出与人工标注:

from phoenix.evals import create_evaluator

# The evaluator IS the task being tested
def run_refusal_eval(input, evaluator):
    result = evaluator.evaluate(input)
    return result[0]

# A simple heuristic checks judge vs human agreement
@create_evaluator(name="exact_match")
def exact_match(output, expected):
    return float(output["score"]) == float(expected["refusal_score"])

# Run: evaluator is the task, exact_match evaluates it
experiment = await AsyncClient().experiments.run_experiment(
    dataset=annotated_dataset,
    task=partial(run_refusal_eval, evaluator=refusal),
    experiment_name="judge-v1",
    evaluators=[exact_match],
    concurrency=10,
)

exact_match 评估器在 phoenix-evals 包 中有对应的源码实现,其核心逻辑是 correct = output == expected 并返回 Score(score=float(correct)),注意该实现不做任何文本归一化,因此验证实验中比对的是原始输出字符串,需要保证 judge 输出的标签格式与人工标签完全一致(或提前归一化)。

TypeScript:完整验证实验

TypeScript 验证参考 给出了端到端的验证实验代码:创建/获取黄金数据集 → 将待测评估器作为 task → 用精确匹配作为实验评估器 → 从实验运行结果手工计算混淆矩阵与 TPR/TNR:

import { createClient } from "@arizeai/phoenix-client";
import { createOrGetDataset, getDatasetExamples } from "@arizeai/phoenix-client/datasets";
import { asExperimentEvaluator, runExperiment } from "@arizeai/phoenix-client/experiments";
import { myEvaluator } from "./myEvaluator.js";

const client = createClient();

const { datasetId } = await createOrGetDataset({ client, name: VALIDATOR_DATASET, examples: goldenExamples });
const { examples } = await getDatasetExamples({ client, dataset: { datasetId } });
const groundTruth = new Map(examples.map((ex) => [ex.id, ex.metadata?.groundTruthLabel as string]));

// Task: invoke the evaluator under test
const task = async (example: (typeof examples)[number]) => {
  const result = await myEvaluator.evaluate({ input: example.input, output: example.output, metadata: example.metadata });
  return result.label ?? "unknown";
};

// Evaluator: exact-match against human ground truth
const exactMatch = asExperimentEvaluator({
  name: "exact-match", kind: "CODE",
  evaluate: ({ output, metadata }) => {
    const expected = metadata?.groundTruthLabel as string;
    const predicted = typeof output === "string" ? output : "unknown";
    return { score: predicted === expected ? 1 : 0, label: predicted, explanation: `Expected: ${expected}, Got: ${predicted}` };
  },
});

const experiment = await runExperiment({
  client, experimentName: `evaluator-validation-${Date.now()}`,
  dataset: { datasetId }, task, evaluators: [exactMatch],
});

// Compute confusion matrix
const runs = Object.values(experiment.runs);
const predicted = new Map((experiment.evaluationRuns ?? [])
  .filter((e) => e.name === "exact-match")
  .map((e) => [e.experimentRunId, e.result?.label ?? null]));

let tp = 0, fp = 0, tn = 0, fn = 0;
for (const run of runs) {
  if (run.error) continue;
  const p = predicted.get(run.id), a = groundTruth.get(run.datasetExampleId);
  if (!p || !a) continue;
  if (a === POSITIVE_LABEL && p === POSITIVE_LABEL) tp++;
  else if (a === NEGATIVE_LABEL && p === POSITIVE_LABEL) fp++;
  else if (a === NEGATIVE_LABEL && p === NEGATIVE_LABEL) tn++;
  else if (a === POSITIVE_LABEL && p === NEGATIVE_LABEL) fn++;
}
const total = tp + fp + tn + fn;
const tpr = tp + fn > 0 ? (tp / (tp + fn)) * 100 : 0;
const tnr = tn + fp > 0 ? (tn / (tn + fp)) * 100 : 0;
console.log(`TPR: ${tpr.toFixed(1)}%  TNR: ${tnr.toFixed(1)}%  Accuracy: ${((tp + tn) / total * 100).toFixed(1)}%`);

这段代码同时演示了两个关键设计:每次验证使用独立实验名(evaluator-validation-${Date.now()}),保证 Phoenix 中每次验证可独立检索;跳过失败 run(if (run.error) continue),避免把任务执行异常误算为评估错误。

验证实验的结果解读

指标 目标 指标偏低意味着
TPR(敏感度) >80% 漏掉真实失败(假阴性多)
TNR(特异度) >80% 误伤正常输出(假阳性多)
Accuracy >80% 整体能力不足

在 Python 侧可通过 experiment.aggregate_scores 直接读取汇总分数(如 {'accuracy': 0.85, 'faithfulness': 0.92}),逐条查看可用 for run in experiment.runs: print(run.output, run.scores),详见 Python 实验参考。

用已知 TPR/TNR 修正生产估算

验证的成果不仅能决定放行与否,还能反哺生产估算。由于评估器存在漏报(FN)与误报(FP),生产环境中观测到的通过率是“有偏”的。Python 验证参考 给出了修正公式:

def correct_estimate(observed, tpr, tnr):
    """Adjust observed pass rate using known TPR/TNR."""
    return (observed - (1 - tnr)) / (tpr - (1 - tnr))

其中 observed 是生产观测到的 pass 率,tpr/tnr 来自验证阶段。原理是:观测通过率 = 真实通过率 × TPR + 真实失败率 × (1 − TNR),解方程即得真实通过率的无偏估计。当 TPR 与 TNR 都接近 1 时,修正幅度趋近于零;两者越差,修正越重要——这正是“Kappa < 0.6 不可接受”的另一种体现。

定位误分类样本:FP/FN 定向排查

验证不只是看汇总数字,还要逐个审查误分类样本,据此改进提示词或判据。Python 侧用掩码即可切出两类错误:

# False Positives: Evaluator pass, human fail
fp_mask = (evaluator_predictions == 1) & (human_labels == 0)
false_positives = dataset[fp_mask]

# False Negatives: Evaluator fail, human pass
fn_mask = (evaluator_predictions == 0) & (human_labels == 1)
false_negatives = dataset[fn_mask]

对 FP 样本,通常意味着 judge 判据过松、提示词缺少约束条件;对 FN 样本,则意味着判据过严或提示词对某些合法形态不敏感。将这些样本汇入下一版黄金数据集,正是“Custom > generic, Build from your failures”(从你的失败中构建评估器)原则的具体落地,详见 phoenix-evals 技能总览 中的关键原则。

危险信号清单

验证结果出现以下任一迹象,都说明评估器尚不具备上线条件:

  • 全部 pass 或全部 fail:说明 judge 过松或过严,丧失了判别力;
  • 结果随机:对同一类样本时对时错,通常是判据(criteria)描述不清晰,LLM 无法稳定执行;
  • TPR 或 TNR < 70%:低于最低容忍线,需要改进;
  • TPR 与 TNR 差距过大:存在系统性偏向(要么过于宽容,要么过于苛刻);
  • Kappa < 0.6:一致性超出随机水平的程度不足,横向对比时应优先淘汰此类评估器。

何时重新验证

评估器的有效性会随时间与配置变化失效,以下任一变化发生时都必须重新执行完整验证流程:

  • 提示词模板变更(prompt template changes)
  • judge 模型变更(judge model changes)
  • 判据/标准变更(criteria changes)
  • 生产环境 FP/FN 突然飙升(production FP/FN spike)
  • 例行节奏:每月至少重新验证一次

从源码与文档结构看,提示词模板、judge 模型与判据正是 LLM 评估器行为的全部可变因素——评估器源码 中 ClassificationEvaluator 同时承载 prompt_template、llm 与 choices,三者任一改动都会改变评估器的判定边界,因此被列为重新验证的触发条件是完全对应的。

小结:验证是评估器上线的唯一门票

完整的评估器生命周期应是:错误分析 → 构建评估器 → 黄金数据集验证 → 达标放行 → 变更后重新验证。验证环节用四类量化指标(Accuracy、TPR、TNR、Cohen's Kappa)把“LLM judge 是否可信”从主观判断变成客观门槛:黄金数据集要平衡、要版本化、要人工标注;验证实验要在 Phoenix Experiments 中把评估器当作被测任务运行;上线后要用已知 TPR/TNR 修正生产估算,并持续监控 FP/FN。遵循这些规范,LLM 评估器才能真正成为可依赖的质量防线,而不是另一个需要被监控的“黑盒”。

进一步阅读:验证指标定义、Python 评估器验证、TypeScript 评估器验证、Python 实验运行、Python 数据集管理、phoenix-evals 技能总览。

登录后查看全文
phoenix