Phoenix LLM Judge 验证指南:用黄金数据集与 TPR/TNR/Kappa 校准 LLM 评估器
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" } },
];
构建步骤
构建黄金数据集遵循四条规范:
- 从生产痕迹采样:优先抽取真实流量中的错误样例、负面反馈、边界情况(edge cases),而不是自己随手编造。可以从 Phoenix 的 span 数据中导出真实样本,参考 Python 数据集参考 中
client.spans.get_spans_dataframe(project_identifier="my-app")的做法,把生产 traces 拉成 DataFrame 后挑选代表性样本。 - 平衡正负样本:目标约 50/50 的 pass/fail 比例。严重失衡的数据集会让 Accuracy 失真,也会掩盖 TPR/TNR 的偏斜。
- 专家逐条标注:每条样本由人类专家给出 ground truth 标签,这是“黄金”二字的来源——必须人工,不能由另一个 LLM 代标。
- 版本化,永不修改旧版本:数据集是可变的会破坏历史对比。新增样本时创建新版本,而不是就地修改:
# 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 技能总览。