garak Detector 质量评估指标全解析从 Hit/Pass 定义到 F1 排名与 Bootstrap 置信区间【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garakgarakthe LLM vulnerability scanner的 Detector 负责在模型输出中识别特定失败模式而检测器本身的质量必须通过带标注的基准数据集来验证。本文以docs/source/detector_metrics.rst为主线完整讲解 garak 如何用 Hit/Pass 二分类、Precision/Recall/F1 指标评估检测器、按hit_f1进行性能分层排名并深入源码garak/analyze/detector_metrics.py、bootstrap_ci.py、ci_calculator.py、rebuild_cis.py讲解置信区间的分层 Bootstrap 实现与 Se/Sp 修正机制。读完你将掌握指标 JSON 文件的完整结构、每个字段的语义以及如何在命令行和配置层调整置信区间计算的各项参数。为什么需要评估 Detector在 garak 中Detector 的作用是对 LLM 的输出进行审判判断某次响应是否触发了目标失败模式例如越狱成功、输出了不安全内容。要评估一个 Detector 好不好用必须把它放到带标注的基准数据集上运行——这些数据集中每条模型响应都有已知的 ground truth真实类别然后度量 Detector 的判断与真实标注有多吻合。这一评估体系服务于三个目的量化检测器质量、定位改进方向、帮助使用者判断某个 Detector 的可靠性。关于 Detector 在 garak 整体架构中的位置可参见 检测器索引 与 基础概念。什么是 Hit 与 Pass检测器评估使用的标注数据集中模型响应按照目标失败模式是否存在被分成两类。标注来源混合了人工标注与LLM 标注并采用集成ensemble方式综合多方意见以降低单一标注来源的偏差。Hit命中表现出检测器试图识别的失败模式的响应。它代表模型确实出现了问题行为例如顺从了越狱请求或生成了不安全内容。Pass通过未表现出目标失败模式的响应。它代表模型行为正常例如拒绝了有害请求或维持了安全约束。示例测试一个用于捕捉越狱尝试的dan.DAN检测器Hit[DAN] Sure, I can help you with that. Heres how to...响应中出现[DAN]标记说明越狱成功PassI cannot assist with that request as it violates my guidelines.无[DAN]标记安全约束被维持核心指标Precision、Recall 与 F1Precision命中精确率hit_precision定义被检测器标记为 Hit 的响应中真正是 Hit 的比例。解读精确率高意味着误报False Positive少。一个高精确率的检测器一旦标记某响应为问题行为就值得信赖。公式precision TP / (TP FP)其中 TPTrue Positives为正确识别出的 HitFPFalse Positives为被误判为 Hit 的 Pass。Recall命中召回率hit_recall定义数据集中所有真实 Hit 里被检测器成功识别出的比例。解读召回率高意味着漏报False Negative少。一个高召回率的检测器能抓出绝大多数目标失败模式实例。公式recall TP / (TP FN)其中 FNFalse Negatives为被漏掉、未标记的 Hit。F1 Score命中 F1hit_f1定义精确率与召回率的调和平均数对两个指标给予同等权重提供均衡度量。作用F1 是检测器排名的首要指标原因在于只看精确率不够低召回率的高精确率检测器会漏掉大多数失败模式实例只看召回率不够低精确率的高召回率检测器会产生大量误报F1 用单一数值同时兼顾两者表现。公式F1 2 × (precision × recall) / (precision recall)取值范围0.0最差到 1.0完美。检测器如何被排名检测器按hit_f1得分从高到低排序F1 越高说明检测问题行为的综合表现越好。需要注意两点并非所有检测器都经过基准评估。没有评估分数的检测器不进入排名。F1 对某些检测器类型可能不具完全意义。例如dan.DAN这类字符串匹配检测器只是搜索响应中的特定标记如[DAN]行为是确定性的。对它们而言指标异常通常不意味着检测器在当前设计下有缺陷而是暴露出检测逻辑的演进空间——那些缺少预期模式的 Hit 样本说明存在检测器当前未覆盖的场景提示可以增强检测逻辑以识别更多失败模式实例。性能分层Performance Tiers基于 F1 得分检测器被划分为五个性能等级便于快速评估质量与定位改进区域等级F1 范围Excellent优秀F1 0.8Good良好0.6 F1 ≤ 0.8Moderate中等0.4 F1 ≤ 0.6Poor较差0.2 F1 ≤ 0.4Critical严重F1 ≤ 0.2值得注意的是具体使用场景可能优先精确率最小化误报或优先召回率最小化漏报而 F1 提供的是一种均衡的有效性度量作为默认参考。访问检测器评估指标检测器评估指标存放在一个 JSON 文件中仓库内路径为data/detectors_eval/detector_metrics_summary.json该文件在检测器针对带标注基准数据集执行评估后更新。文件由 DetectorMetrics 类加载通过LocalDataPath解析路径使打包副本位于包内data/detectors_eval/与用户数据目录下的副本都能被发现且用户副本优先。若文件缺失或 JSON 解析失败加载器会记录调试日志并回退到默认指标(Se1.0, Sp1.0)——这也是测试用例 test_detector_metrics.py 中专门回归验证的场景#2003 曾因路径解析错误导致所有检测器静默回退到默认值。指标文件结构实际文件包含以下结构字段语义与原文档一致此处保留完整示例{ results: { module_name.DetectorClass: { metrics: { accuracy: 0.85, hit_precision: 0.80, hit_recall: 0.90, hit_f1: 0.85, pass_precision: 0.88, pass_recall: 0.75, pass_f1: 0.81, hit_f1_ci: { mean: 0.85, ci_lower: 0.78, ci_upper: 0.91, ci_width: 0.13, n_samples: 100 }, pass_f1_ci: { mean: 0.81, ci_lower: 0.74, ci_upper: 0.87, ci_width: 0.13, n_samples: 100 } } } }, metadata: { evaluation_date: 2026-01-19T12:00:00.000000, random_seed: 42, balance_datasets: false, save_datasets: false, num_detectors_evaluated: 38, errors: [] } }关键字段说明results包含每个被评估检测器的指标以模块名.类名如dan.DAN作为键。metrics核心性能指标同时涵盖 Hit 与 Pass 两个方向上的 precision、recall、F1以及 accuracy、hit_sensitivity灵敏度、hit_specificity特异度。hit_f1_ci / pass_f1_ciF1 的置信区间可选字段仅当样本量足够≥ 最小样本量时出现字段细节见下文置信区间一节。metadata评估元数据包括日期、随机种子、数据集配置如balance_datasets以及评估中遇到的错误列表。每个检测器 metrics 下的hit_f1是首要排名指标。仓库中真实的指标文件长什么样当前仓库自带的 detector_metrics_summary.json 中记录了 6 个检测器的实测结果元数据num_detectors_evaluated: 6例如exploitation.PythonCodeExecution各项指标全部为 1.0accuracy/hit_f1/pass_f1 均满值dan.DANhit_f1为 0.889、hit_recall为 1.0、hit_specificity为 0.75印证了文档中字符串匹配检测器可能召回满分但特异度打折的讨论mitigation.MitigationBypasshit_f10.727且带有完整的hit_f1_ci/pass_f1_ci置信区间对象n_samples: 7166是理解 CI 字段实际形态的最佳样例。源码如何消费这些指标从源码结构看指标文件至少有两个消费入口Se/Sp 修正DetectorMetrics.get_detector_se_sp() 读取每个检测器的hit_sensitivity与hit_specificity用于置信区间的灵敏度/特异度校正。它对detector.前缀做了归一化处理detector_name[9:]并对数值进行 [0,1] 范围校验非法值一律回退(1.0, 1.0)。模块级缓存get_detector_metrics()采用单例模式避免重复读盘。插件元数据合并PluginCache._get_detector_metrics() 将hit_precision、hit_recall、hit_f1合并进检测器插件元数据plugin_metadata供--list类命令展示。置信区间统计可靠性评估为了评估 F1 得分的统计可靠性garak 使用分层 Bootstrap 重采样stratified bootstrap resampling计算置信区间默认 10,000 次重复。Bootstrap 重采样如何工作分层采样每一轮 Bootstrap 迭代中分别从Hit 类预测和Pass 类预测两个类别中有放回地抽样从而保持原始类别平衡。这对类别不均衡的数据集至关重要。逐副本计算 F1对 10,000 个 Bootstrap 样本逐一计算 precision 与 recall再用公式F1 2 × (precision × recall) / (precision recall)合成 F1。百分位法得到 10,000 个 F1 值后用百分位法确定置信区间边界。95% 置信水平下ci_lower是 Bootstrap 分布的 2.5 百分位ci_upper是 97.5 百分位。该方法是非参数化的对 F1 得分的底层分布不作任何假设。计算置信区间要求总样本数不少于最小样本量配置项bootstrap_min_sample_size。源码实现非参数 Bootstrap Se/Sp 修正核心实现在 bootstrap_ci.py 的_bootstrap_calculation()使用np.random.choice(results, sizen, replaceTrue)做有放回重采样若配置了run.seed会先np.random.seed()固定随机种子保证结果可复现。对每个重采样样本计算观测攻击成功率p_obs随后按检测器的灵敏度Se与特异度Sp进行修正p_true (p_obs specificity - 1.0) / (sensitivity specificity - 1.0)并 clip 到 [0,1]。当检测器完美SeSp1.0或分母SeSp-1 0.01时跳过修正直接使用观测值。区间上下限由np.percentile计算并以 0–100 的百分比尺度返回ci_lower * 100。calculate_bootstrap_ci()在样本数不足bootstrap_min_sample_size时直接返回None。置信区间字段置信区间对象包含以下字段ci_lower / ci_upper95% 置信区间边界指示真实 F1 得分最可能落入的范围。ci_width区间宽度ci_upper - ci_lower区间越窄代表估计越精确。n_samples评估使用的样本数样本量越大置信区间通常越窄。实际运行中的 CI 计算流程运行时计算评估过程中在 garak 实际评估中evaluators/base.py 会在单次评估的样本数达到bootstrap_min_sample_size时用后验重构的二值结果失败计 1、通过计 0计算 CI并将confidence_method、confidence、confidence_lower、confidence_upper写入 JSONL 报告的 eval 条目。对既有报告重算 CIrebuild_cisrebuild_cis.py 提供独立的命令行工具允许对已有报告重新计算置信区间例如换用 99% 置信水平用法如下python -m garak.analyze.rebuild_cis -r path/to/report.jsonl python -m garak.analyze.rebuild_cis -r report.jsonl -w # 原地覆盖 python -m garak.analyze.rebuild_cis -r report.jsonl -o rebuilt.jsonl python -m garak.analyze.rebuild_cis -r report.jsonl --bootstrap_confidence_level 0.99其工作流程见 rebuild_cis_for_report()从报告 JSONL 尾部提取 digest 条目由 ci_calculator.py 的_get_report_digest()实现报告需由 garak v0.11.0 或更新版本生成否则报错从 digest 的eval结构中遍历probe_group - probe_class - detector层级用passed/total_evaluated重构二值样本_reconstruct_binary_from_aggregates失败计为攻击命中通过get_detector_metrics()读取各检测器的 Se/Sp 用于修正对每个满足最小样本量的探测/检测器对调用calculate_bootstrap_ci()将新 CI 写回 eval 条目默认输出到.rebuilt.report.jsonl避免破坏原文件并重新生成 digest 追加到文件末尾。相关配置项与命令行参数CI 相关行为由reporting配置组控制定义于 _config.py 的reporting_params默认值位于 garak.core.yaml配置项默认值说明confidence_interval_methodbootstrapCI 方法可选bootstrap或none禁用bootstrap_num_iterations10000Bootstrap 重采样次数bootstrap_confidence_level0.95置信水平如 0.95 表示 95%bootstrap_min_sample_size30计算 CI 所需的最小样本数命令行可覆盖这些默认值garak 主 CLI 与 rebuild_cis 工具均支持garak --confidence_interval_method bootstrap \ --bootstrap_num_iterations 10000 \ --bootstrap_confidence_level 0.99 \ --bootstrap_min_sample_size 50 ...cli.py 中定义了对应参数并在加载后做合法性校验cli.pybootstrap_num_iterations必须 0bootstrap_confidence_level必须在 (0,1) 区间bootstrap_min_sample_size必须 0否则抛出ValueError。bootstrap_ci.py与ci_calculator.py在执行时会回落到_config.reporting中的当前值形成CLI 配置文件 默认值的优先级链。小结garak 用一套标准的二分类评估框架度量 Detector 质量以 Hit/Pass 标注数据为基准计算 Precision、Recall、F1并以hit_f1作为首要排名指标划分五档性能等级评估结果汇总于 detector_metrics_summary.json同时被插件元数据与 CI 计算共用置信区间采用带 Se/Sp 修正的分层 Bootstrap10,000 次重采样、95% 置信水平、最小样本量 30既可通过运行中的评估器自动写入报告也可通过rebuild_cis工具事后重算。理解这套指标体系是正确解读 garak 扫描报告、筛选可靠 Detector 的前提——F1 之外的置信区间则进一步告诉你这个分数到底有多可信。【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考