OpenMed Comparator Harness：面向医疗去标识化系统的离线、可复现基准对比框架

OpenMed Comparator Harness面向医疗去标识化系统的离线、可复现基准对比框架【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmedopenmed.eval.comparator是 OpenMed 提供的本地化基准对比框架harness用于在完全离线的前提下将 OpenMed 与用户自备的去标识化de-identification基线做同口径横向评测。它不下载任何模型、不访问任何远程服务、不写入任何遥测数据并且每个 runner 都被强制运行在 OpenMed 的出站 socket 守卫之后——即使某个适配器忘记声明自己依赖网络也会被拦截。读完本文你将掌握如何按 Adapter 契约接入自己的本地检测器、如何构造仅含合成数据的 Fixture 集、如何运行run_comparator_benchmark得到召回率/精确率/关键泄漏率/延迟/内存等聚合指标以及如何用openmed.eval.comparator_report把结果投影成只含计数、可长期留存的 JSON/Markdown 评估证据。设计定位为什么需要离线基准OpenMed 的定位是 Local-first 医疗 AI其去标识化能力运行在设备或自有网络内患者数据不出网。因此任何评测行为也必须遵守同样的隐私约束。Comparator harness 的设计目标由此确立永不联网harness 自身不下载模型、不调用服务、不写遥测永不外泄报告只含聚合指标与摘要哈希不含源文本、fixture 标识符、预测文本或适配器异常文本完全可复现支持注入固定时钟、内存采样器与generated_at时间戳可产出字节级一致的测量结果防御性失活当适配器声明requires_networkTrue或预置了unavailable_reason时直接标记为not_available而不是冒险联网。这些约束在源码中表现为两处硬保证一是run_comparator_benchmark内部通过network_blocked_if_offline(local_onlyTrue)包裹整个适配器执行循环见 openmed/eval/comparator.py二是文档开头明确声明Every runner executes behind OpenMeds outbound-socket guard。也就是说网络依赖型适配器在本 harness 中永远拿不到分只会以not_available状态出现。Adapter 契约接入你自己的本地检测器构建适配器的核心是ComparatorAdapter一个稳定的名称 一个本地 runner 函数。首选 runner 签名是runner(text, language)返回包含start、end、label字段的 span 类记录from openmed.eval.comparator import ( ComparatorAdapter, ComparatorBudget, ComparatorFixture, run_comparator_benchmark, ) def local_baseline(text: str, language: str): Run an already-installed local detector. del language return [] # Replace with local predictions; never call a remote service. fixture ComparatorFixture( fixture_idsynthetic-case-001, textSynthetic note for SYNTHETIC_NAME; code SYNTHETIC_ID., gold_spans(), metadata{synthetic: True, phi_free: True}, ) report run_comparator_benchmark( [fixture], [ComparatorAdapter(namelocal-baseline, runnerlocal_baseline)], budgetComparatorBudget(max_latency_ms400.0, max_memory_bytes900_000_000), )源码层面的 runner 适配逻辑openmed/eval/comparator.py会根据inspect.signature自动匹配多种形态runner 签名形态调用方式3 个及以上位置参数runner(fixture_as_benchmark, model_name, device)兼容 OpenMed 旧式 runner2 个位置参数或含*argsrunner(text, language)仅含 keyword-only 的languagerunner(text, language...)1 个位置参数runner(text)无参数runner()这也回答了原文档中的一句关键声明Existing OpenMed benchmark runners with the signature(fixture, model_name, device)are also accepted.——两种风格可以并存复用。ComparatorAdapter的完整字段见 openmed/eval/comparator.py包括name报告中的稳定标识必须匹配安全标识符正则[A-Za-z0-9][A-Za-z0-9 ._:/()-]{0,127}runner/predict二者任选其一作为可调用体version默认localmodel_name、device默认None/cpu用于旧式三参 runner 与可复现性哈希requires_network布尔默认False为True时直接判not_availableunavailable_reason预置不可用原因此时同样跳过执行metadata仅作为摘要哈希的输入不会原样进入报告。此外run_comparator_benchmark的adapters参数还接受裸映射{name: ..., runner: ...}、可调用对象或任何暴露name/runner属性的对象由_coerce_adapter统一归一化。Fixture 契约只有合成、无 PHI 的语料才能进基准ComparatorFixture是基准的最小样本单元。它的设计非常克制兼容 fixture 里故意置空 gold spans、替换元数据防止基线偷看答案。其构造与校验逻辑openmed/eval/comparator.py有以下要点synthetic与phi_free两个标志必须显式为True——既可以是构造参数也可以是metadata中的精确布尔值。两者都缺失或为假时fail closed直接抛ComparatorFixtureError原始文本只用于进程内适配器调用绝不进入to_dict()、报告或异常信息其__repr__只暴露text_length、gold_span_count、language等安全描述fixture_id与language需通过安全正则标识符最长 128 字符、语言标签形如en/zh-CN等gold spans 会经过normalize_eval_spans归一化并做边界校验start 0、end start、end len(text)。从文件加载 FixtureJSON 与 JSONL 文件均可用load_comparator_fixtures加载加载过程仅限本地且受限openmed/eval/comparator.py单文件上限 32 MiB_MAX_FIXTURE_FILE_BYTES每条 fixture 的文本上限 2,000,000 字符、单条 span 数量上限 100,000集合上限 10,000 条 fixture#开头的 JSONL 行会被当作注释跳过顶层既可以是数组也可以是{fixtures: [...]}结构每个映射必须携带synthetic: true与phi_free: true顶层或metadata内均可缺失即拒绝。已有的BenchmarkFixture可通过ComparatorFixture.from_benchmark_fixture转换接入但必须携带同样的显式元数据标志。fixture 的fixture_id在集合内还必须唯一_validate_unique_fixtures。运行基准一次调用、全适配器同序执行run_comparator_benchmark的完整签名openmed/eval/comparator.py为run_comparator_benchmark( fixtures, # 内联 fixture、BenchmarkFixture、映射或本地 JSON/JSONL 路径 adapters, # ComparatorAdapter / 兼容映射 / 可调用对象集合 *, suitesynthetic-comparator, # 报告套件名 budgetNone, # ComparatorBudget(max_latency_ms..., max_memory_bytes...) critical_labelsNone, # 关键泄漏标签集合默认见下 clockNone, # 单调时钟测试可注入 memory_samplerNone, # 字节采样器测试可注入 generated_atNone, # 显式时间戳不隐式生成 seed0, # 进程内标准库 random 的种子 metadataNone, # 仅以摘要形式进入报告 ) - ComparatorReport执行时每个适配器看到完全相同的 fixture 序列。任何适配器抛出ComparatorAdapterUnavailable或ImportError都会被捕获并标记为not_available其他异常则统一转为ComparatorExecutionError消息固定为安全文本不携带底层异常内容。可复现性三重保障固定注入测试或复现任务中传入固定clock、memory_sampler与generated_at可得到字节级一致输出稳定哈希报告携带输入/配置可复现性哈希reproducibility_hashfixture ID、适配器模型/设备设置、可用性声明、JSON 兼容的字符串键 provenance 元数据都会被折进哈希但不作为原始值上报串行化保护带种子的标准库随机状态与出站 socket 守卫激活期间重叠的进程内运行会被_RANDOM_CONTEXT_LOCK串行化防止一次运行覆盖另一次运行的进程全局状态。默认关键泄漏标签集合_DEFAULT_CRITICAL_LABELS可通过critical_labels覆盖为SSN、ID_NUM、API_KEY、ACCOUNT_NUMBER、PASSWORD、PIN、CREDIT_CARD、CVV、IBAN、BIC。测量指标六类聚合全部只报汇总每个适配器在全部 fixture 上运行完毕后得到ComparatorMetricsopenmed/eval/comparator.py报告只包含聚合值指标说明recall/precision/f1精确 labeloffset 的 span 级指标compute_exact_span_f1character_recall字素感知grapheme-aware覆盖率指标与既有评估原语一致compute_character_recallcritical_leakage关键标识标签上的字素加权残余泄漏率同时给出 missed critical-span 数与分母计数latencyp50 / p95 / p99 与样本数毫秒可选延迟预算只对 p95 检查memory进程内存基线、峰值、增量与样本数可选内存预算只对峰值字节检查within_budget预算是否满足True/False/ 无预算时None关键泄漏的计算在_critical_leakageopenmed/eval/comparator.py中完成先筛选出 gold 中属于关键标签的 span再用compute_leakage_rate得到泄漏字符数/总字符数并逐个统计完全没有被任何预测覆盖的关键 span 数。内存采样默认走resource.getrusage(RUSAGE_SELF).ru_maxrssmacOS 直接返回字节数Linux 上按 KiB×1024 换算见 openmed/eval/comparator.py。隐私安全输出报告里有什么和没什么同样重要ComparatorReportschema 版本openmed.eval.comparator.v1是基准运行的直接产物支持to_json()、write_json()、to_markdown()、write_markdown()等方法。它的内容边界是硬性的报告中包含fixture 内容摘要digest、计数、标签、指标、provenance 摘要、关键标签集合、预算、种子、可复现性哈希。报告中绝不包含fixture 标识符、源文本、预测文本predicted surfaces、任意适配器元数据、适配器异常文本。此外还有多层防御openmed/eval/comparator.py 与各 dataclass 的__post_init__报告可见的 suite / adapter / version / language / fixture 标识符都受正则限制且只能是非标记non-markup标识符字符fixture 文件大小、用例数、文本长度、span 数、适配器数均有上限适配器 ≤ 256、关键标签 ≤ 256fixture 摘要必须是sha256:64 位小写十六进制形态可复现性哈希在构造时会被重算验证不匹配即拒绝整个报告校验失败时抛出 source-safe 错误即错误信息本身不携带任何可能外泄的字段值。把结果沉淀为评估证据Counts-Only 报告渲染基准运行得到的矩阵matrix在内存中有用但它可能携带 fixture 标识符、适配器元数据、嵌套报告与异常细节不宜直接外发。openmed.eval.comparator_report提供一层白名单投影build_comparator_report把ComparatorMatrixReport或普通 JSON 字典映射成CountsOnlyComparatorReport——一个刻意与 harness 的ComparatorReport区分开的公开类型避免 import 渲染器时遮蔽基准结果from openmed.eval import ( build_comparator_report, render_comparator_report_json, render_comparator_report_markdown, ) report build_comparator_report( matrix, environment{ python: 3.12, platform: local, runner_version: synthetic-v1, }, ) json_text render_comparator_report_json(report) markdown_text render_comparator_report_markdown(report)渲染产物见 openmed/eval/comparator_report.py具备以下特征每行系统只含 4 个固定指标leakage_rate/character_recall/exact_span_f1/relaxed_span_f1、它们可用的数字计数字段、fixture 数、状态与失败数报告内嵌指标定义表DEFAULT_METRIC_DEFINITIONS与 SHA-256 环境指纹fingerprint_environment/default_environment失败总数按高层级类别分组统计dependency、execution、not_available、timeout、validation、other失败消息永不渲染内置公开名称OpenMed、presidio、philter、pydeid、gliner_biomed、cpu、cuda、metal、mps等保持可读自定义 suite / model / device / system 标识符会被替换为确定性 SHA-256 标识符防止类名称的短值跨越报告边界_safe_identifier构造后报告映射深度不可变MappingProxyType序列化时会重新校验 artifact 类型、schema 版本、行数上限≤ 256、数值边界与 JSON 缩进0–8大额失败计数用算术累加而非逐事件分配内存。环境映射只作为哈希输入。要跨机器复现同一 artifact请显式传入 environment 映射或直接传预计算的sha256:64 位小写十六进制指纹。渲染器不访问网络、不加载模型与 fixture 内容。实际写盘可用write_comparator_report(path)按后缀自动选择 JSON 或 Markdown。矩阵模式OpenMed 与第三方基线并排除了单适配器基准openmed.eval.comparators还提供run_comparator_matrixopenmed/eval/comparators.py把 OpenMed 与一组适配器在同一 fixture 套件上并排运行产出ComparatorMatrixReport。默认适配器集合DEFAULT_COMPARATOR_ADAPTERS包括presidio、philter、pydeid、gliner_biomedOpenMed 自身的行名为OPENMED_SYSTEM_NAME OpenMed。适配器 runner 若抛出ImportError或ComparatorUnavailable会被记为not_available而不是让整个矩阵运行失败——这与单适配器基准的容错语义保持一致。该矩阵正是build_comparator_report的主要输入来源构成了基准 → 矩阵 → 计数报告 → 归档的完整链路。测试验证确定性由单测锁定仓库在 tests/unit/eval/test_comparator.py 中锁定了上述行为。例如test_comparator_scores_required_metrics_with_shared_budget同时验证固定clock与memory_sampler下延迟 p95、内存峰值、预算判定within_budget is True、关键泄漏率弱 runner 的critical_leakage 1.0全部符合预期test_comparator_report_is_deterministic_and_source_safe则验证报告在相同注入参数下可复现且不泄露源文本。tests/unit/eval/test_comparator_report.py、test_comparator_matrix.py分别覆盖渲染器与矩阵路径。若需要字节级一致的测量请在测试或复现任务中一律注入clock、memory_sampler与generated_at。结论与边界Comparator harness 为 OpenMed 用户提供了一条可对拍、可留痕、可复现的本地评估路径写一个本地 runner、配一份合成 fixture、跑一次run_comparator_benchmark再用comparator_report渲染出只含计数的归档件。需要再次强调它的定位边界报告是评估证据evaluation evidence不是合规认证也不是临床决策保证。同时所有参与基准的语料必须是合成且 PHI-free 的——这与 OpenMed 患者数据不出网的 Local-first 原则一脉相承也让每一次对拍都成为可以放心存入审计链路的证据。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考