brandon-behring/eval-toolkit

# eval-toolkit 一个**支持方法论的二元分类评估工具套件**： 指标、bootstrap 置信区间、校准、数据泄露检测、数据集划分， 阈值选择、数据集加载、可复现性清单，以及 将它们紧密结合的切片感知编排器。纯 numpy/scipy/sklearn 核心；pandas/matplotlib/hypothesis 为可选 扩展；PyTorch / HuggingFace / `datasets` 属于*消费者端*（绝不需要）。 设计上达到库级别 —— 每个公共函数都带有类型注解， 每个数学核心都附有 LaTeX + 文献引用的文档， 内置了统计有效性（bootstrap 置信区间、MDE 估计、配对差异 检验），并且 JSON 输出（`results.json` / `results_full.json` / `manifest.json`）附带版本化的 [JSON Schemas](src/eval_toolkit/schemas/)，以便下游解析器可以根据 格式变化进行拦截。 ## 三层架构 ``` ┌─ Tier 3 ─ Reproducibility scaffolding ─────────────────┐ │ manifest.json + seeds + git_sha + data_hashes + │ │ gpu_info + leakage_report (NeurIPS-aligned) │ ├─ Tier 2 ─ Protocol-based orchestration ────────────────┤ │ Scorer / SliceAwareScorer / LeakageCheck / Splitter │ │ ThresholdSelector / DatasetLoader / SimilarityStrategy│ │ Versioned (opt-in: per-object versions in manifest) │ ├─ Tier 1 ─ Functional core ─────────────────────────────┤ │ pr_auc / roc_auc / ECE variants / Brier / bootstrap_ci│ │ paired_bootstrap_diff / cv_clt_ci / mde_from_ci │ │ reliability_curve / fit_temperature / fit_isotonic │ └────────────────────────────────────────────────────────┘ ``` 根据您的任务需求选择相应的层级。临时分析：只需调用 函数核心。完整评估管道：实现 Protocols。每次 运行：捕获清单。 ## 文档 - **[入门指南](docs/getting-started.md)** — 面向新用户的端到端 演练：安装、定义 Scorer、构建切片、 运行 `evaluate()`、持久化结果、添加声明、渲染图表。 - **[方法论课程](docs/methodology/README.md)** — 关于划分、指标、校准、证据门控、 预测产物等内容的 16 章 教程。 - **[Schema 参考](docs/schemas.md)** — `results.v1.json`、`results_full.v1.json`、`manifest.v1.json` 的逐字段语义说明。 - **[迁移指南](docs/MIGRATION.md)** — v0.6→v0.7，v0.7→v0.8， v0.8→v0.9。 - **[扩展](docs/extending.md)** — 逐 Protocol 指南，用于 自定义 Scorers、Splitters、LeakageChecks、ThresholdSelectors、 DatasetLoaders、EvidenceGates。 - **[仓库策略](docs/repo-strategy.md)** — 包的组织方式、 6 桶目标形态，以及决定何时将子包提取到 其独立仓库的检查清单。 ## 方法论 优秀的二元分类评估应该是怎样的，以及每个 关注点如何映射到将其具体实现的工具套件原语。 - [`docs/methodology/`](docs/methodology/README.md) — 课程 （16 章）。推荐阅读顺序： [`leakage`](docs/methodology/leakage.md) → [`splits`](docs/methodology/splits.md) → [`thresholds`](docs/methodology/thresholds.md) → [`calibration`](docs/methodology/calibration.md) → [`comparison`](docs/methodology/comparison.md) → [`bootstrap`](docs/methodology/bootstrap.md) → [`length_stratification`](docs/methodology/length_stratification.md) → [`text_dedup`](docs/methodology/text_dedup.md) → [`versioning`](docs/methodology/versioning.md) → [`fairness`](docs/methodology/fairness.md) → [`reproducibility`](docs/methodology/reproducibility.md) → [`testing`](docs/methodology/testing.md) → [`reading_list`](docs/methodology/reading_list.md)。 - [`docs/MIGRATION.md`](docs/MIGRATION.md) — 各版本迁移 指南（v0.6→v0.7，v0.7→v0.8）。 - [`docs/roadmap.md`](docs/roadmap.md) — 前瞻性跟踪器； v1.0.0 路线图；消费者缺口文档交叉链接。 ## 扩展 eval-toolkit 如何将您自己的 scorer / 数据泄露检测 / 数据集划分器 / 加载器 / 阈值选择器接入该工具套件。 - [`docs/extending.md`](docs/extending.md) — 逐 Protocol 指南，约 50 行的完整工具套件配方，项目布局指引。 ## 实战示例 - [`docs/examples/prompt_injection_walkthrough.md`](docs/examples/prompt_injection_walkthrough.md) — 在合成的 OWASP LLM01:2025 数据集上进行的端到端提示注入评估；交叉链接至 [展示仓库](https://github.com/brandon-behring/prompt_injection_classifier_showcase) 以获取真实的 Lakera PINT 演练。 - [`docs/examples/pytorch_scorer_example.md`](docs/examples/pytorch_scorer_example.md) — HuggingFace transformer + LoRA `Scorer` 适配器（批量推理， GPU/CPU 布局，确定性模式设置）。 ## 安装 ``` uv venv uv pip install -e .[dev] ``` 对于只需要数学核心功能（无绘图，无 pandas）的消费者： ``` pip install eval-toolkit # core only: numpy/scipy/sklearn pip install "eval-toolkit[plotting]" # adds matplotlib + pillow pip install "eval-toolkit[dataframe]" # adds pandas pip install "eval-toolkit[all]" # everything ``` ## 快速示例 ### 指标 ``` import numpy as np from eval_toolkit import pr_auc, roc_auc, expected_calibration_error rng = np.random.default_rng(42) y = rng.integers(0, 2, size=200) # 裁剪至 [0, 1] — ECE 仅对校准后的概率有意义。 s = np.clip(y + rng.normal(0, 0.3, size=200), 0, 1) print(f"PR-AUC: {pr_auc(y, s):.3f}") print(f"ROC-AUC: {roc_auc(y, s):.3f}") print(f"ECE (10 bins): {expected_calibration_error(y, s, n_bins=10):.3f}") ``` ### Bootstrap 置信区间 ``` from eval_toolkit import bootstrap_ci, paired_bootstrap_diff, pr_auc ci = bootstrap_ci(y, s, pr_auc, n_resamples=1000, seed=42) print(f"PR-AUC: {ci.point_estimate:.3f} 95% CI: [{ci.ci_low:.3f}, {ci.ci_high:.3f}]") # 对两个评分器之间的提升进行 Paired bootstrap（s_baseline 也必须在 [0, 1] 范围内）。 s_baseline = np.clip(rng.normal(0.5, 0.3, size=200), 0, 1) diff = paired_bootstrap_diff(y, s_baseline, s, pr_auc, n_resamples=1000, seed=42) print(f"Δ PR-AUC: {diff.delta:.3f} overlaps zero: {diff.overlaps_zero}") ``` ### 温度缩放 (Guo et al. 2017) ``` from eval_toolkit import fit_temperature logits = rng.normal(size=(500, 2)) labels = (logits[:, 1] > logits[:, 0]).astype(int) result = fit_temperature(logits, labels) print(f"Optimal T: {result['temperature']:.3f}") print(f"NLL: {result['nll_pre']:.3f} -> {result['nll_post']:.3f}") ``` ### 可复现性清单（NeurIPS 兼容） ``` import tempfile from pathlib import Path from eval_toolkit import build_manifest, write_manifest with tempfile.TemporaryDirectory() as run_dir: # data_files: {name: path} → eval_toolkit hashes the files for you; # versioned: any object with a `version` attribute (e.g. a scorer or # leakage check) is captured by name → version in the manifest. manifest = build_manifest( run_id="quickstart-demo", config={"threshold_criterion": "max_f1", "seed": 42}, seeds={"global": 42, "bootstrap": 42}, ) write_manifest(manifest, Path(run_dir)) # → run_dir/manifest.json: schema_version, git_sha, dirty_flag, code_versions, # env (python+platform), seeds, data_hashes, versioned_objects, gpu_info ``` ## 模块 | 模块 | 用途 | |---|---| | `eval_toolkit.metrics` | PR-AUC、ROC-AUC、ECE 变体、Brier 分解、先验偏移投影 | | `eval_toolkit.thresholds` | `ThresholdSelector` Protocol + 6 种参考实现（max-F1、target-recall/precision/FPR、Youden-J、成本敏感） | | `eval_toolkit.operating_points` | 在混合类别的切片上拟合阈值，并将其应用于混合或单类别目标切片，带有来源追溯 | | `eval_toolkit.bootstrap` | BCa + 配对 bootstrap、MDE 估计、两级操作点 bootstrap、K 折 CLT 校正的置信区间 | | `eval_toolkit.calibration` | 可靠性曲线、贝叶斯最优阈值、保序/Platt/温度缩放 | | `eval_toolkit.harness` | `Scorer` Protocol + `evaluate(...)` + `evaluate_folded(...)` 切片感知编排器 | | `eval_toolkit.leakage` | `LeakageCheck` Protocol + 7 种参考实现（精确/近似/编码混淆/交叉划分/标签冲突/分组/时间序列）；`Versioned` 可选 Protocol | | `eval_toolkit.splits` | `Splitter` Protocol + 5 种参考实现（留出法/分层/分组/源不相交/时间序列） | | `eval_toolkit.loaders` | `DatasetLoader` Protocol + 4 种参考实现（DataFrame / SingleSlice / ParquetGlob / HF datasets），带有 Croissant 兼容的 `describe()` | | `eval_toolkit.manifest` | `RunManifest`（NeurIPS 兼容）+ 源角色 / 护栏元数据 + `build_manifest` / `write_manifest` | | `eval_toolkit.claims` | 通用证据门控和 `ClaimReport`，用于声明模式与探索模式的检查 | | `eval_toolkit.text_dedup` | `SimilarityStrategy` Protocol + 5 种策略（TF-IDF / hash / embedding / Jaccard / MinHash-LSH）；`near_dedup` / `cross_dedup` 编排器 | | `eval_toolkit.plotting` | PR 曲线、可靠性图、混淆矩阵、得分直方图、提升置信区间 | | `eval_toolkit.provenance` | 文件哈希、运行目录布局、图表元数据附属文件 | | `eval_toolkit/schemas/` | 内置 JSON Schemas（`results.v1.json`、`results_full.v1.json`、`manifest.v1.json`）— 通过 `importlib.resources.files("eval_toolkit") / "schemas"` 加载（非可导入的 Python 模块） | | `eval_toolkit.paths` | 相对于仓库的路径规范化 | | `eval_toolkit.seeds` | `set_global_seeds` (random + numpy + 可选 torch) | | `eval_toolkit.config` | `frozen_config` 装饰器 + `from_yaml` 加载器 | | `eval_toolkit.docs` | 带格式化器注册表的基于锚点的 markdown 渲染 | ## 快速迭代循环 在开发中，使用以下命令跳过慢速测试： ``` make fast # or: nox -s fast # 底层运行：uv run pytest -m "not slow" -q ``` CI 会在每次推送时运行完整测试套件（包括 `slow`）。`slow` 标记应用于耗时超过约 2 秒的测试（主要是具有较大 `max_examples` 的 Hypothesis 属性测试，以及少量 `n_resamples >= 200` 的 bootstrap 测试）。`make fast` 可将开发者迭代循环保持在约 30 秒以内。 ## 标准 有关完整协调一致的编码标准（格式化、 命名、错误、文档字符串、测试、打包），请参阅 [`STYLE.md`](STYLE.md) 。 ## 版本控制 从 v0.1.0 开始采用 Semver。请参阅 [`CHANGELOG.md`](CHANGELOG.md)。 ## 许可证 MIT — 请参阅 [`LICENSE`](LICENSE)。

标签：AI安全, Atomic Red Team, Brier分数, Chat Copilot, HuggingFace, Hypothesis, JSON Schema, Matplotlib, NumPy, PR AUC, PyTorch, ROC AUC, Scikit-learn, SciPy, 二分类, 二分类评估, 切片评估, 可复现性, 引导置信区间, 性能指标, 提示注入检测器, 数据泄露检测, 数据科学, 数据集加载, 期望校准误差, 机器学习工具包, 机器学习评估, 模型校准, 类型注解, 统计分析, 置信区间, 评估工具包, 评估框架, 资源验证, 逆向工具, 配对差异检验, 阈值选择