OpenMed Apache Beam 批处理脱敏面向有界管道的本地优先 Redaction Transform 实战指南【免费下载链接】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 为 Apache Beam 提供了一套小而严的脱敏契约Redaction Contract在**有界批处理管道bounded batch pipeline**中将每个元素交给 worker 本地加载的脱敏模型处理而整个运行过程受记录数、字节数与重试次数三重边界约束。本文以 docs/integrations/beam.md 为主体结合 契约实现源码 与 单元测试完整讲解如何安装、配置、运行 Beam 脱敏 Transform如何在不安装 Beam 的情况下用直接合成 harness 验证序列化与重试行为以及这套契约如何在日志、异常与报告中做到零 PHI 泄漏。为什么需要一套有界的 Beam 脱敏契约Beam 管道天然会把数据分发到多个 worker而脱敏de-identification又天然涉及患者隐私文本PHI。如果脱敏逻辑里出现未捕获的异常或某个 redactor 把一条合法输入放大成无限大的输出最终都会流入 runner 的集中式日志——这正是隐私事故的高发点。OpenMed 的做法是把脱敏封装成一个受严格边界约束的 PTransform元素类型固定、字节与记录数受限、重试有上限、状态只保留计数器和字节总量。无论输入如何恶意循环引用、超大整数、非 JSON 值契约都会在脱敏之前以稳定且不含值value-free的错误拒绝它。这一设计在 beam.py 模块 docstring 中有明确说明。安装Beam 是可选项Beam SDK 对 OpenMed 而言是可选依赖。契约模块本身可以脱离 Beam 独立导入、配置并借助run_synthetic_harness完成序列化与重试行为验证——这意味着 CI 或离线环境完全不需要安装 Beam 就能测试脱敏逻辑pip install openmed[beam]从 pyproject.toml 可以看到该 extra 声明的版本区间为apache-beam2.73,3。适配器注册表 openmed/interop/init.py 中登记了beam适配器指向openmed.interop.beam_transform模块并注明其 extras 为beam。未安装 Beam 时的行为也很明确导入openmed或openmed.interop永远不会强制引入apache_beam只有当真正执行expand()时_require_beam()才会抛出ImportError并提示安装openmed[beam]测试用例验证了这一行为。核心契约元素形状、默认边界与 JSON 兼容性元素形状Element ShapeTransform 接受两种元素字符串元素整个字符串作为待脱敏文本映射Mapping元素配置一个text_field只变换该字段其余字段与记录外层结构保持不变。若该字段值为None契约会原样保留而不触发 redactor见 BeamRedactionSpec docstring。从 测试用例 可见{id: 7, note: Jane Roe called 555-0100}经过处理后得到{id: 7, note: [PERSON] called [PHONE]}id原封不动。默认边界Default Bounds契约对单次运行给出明确限额源码常量 与文档一致边界项默认值说明max_records10,000单次运行处理的记录上限max_input_bytes10 MiB序列化后输入总字节上限max_output_bytes10 MiB序列化后输出总字节上限max_record_bytes1 MiB单条输入/输出记录序列化字节上限max_attempts3单条记录的脱敏尝试次数上限另外还有一组**硬上限hard ceilings**不可配置逾越记录数最大 1,000,000_MAX_RECORDS、输入/输出字节最大 256 MiB_MAX_INPUT_BYTES/_MAX_OUTPUT_BYTES、单条记录最大 16 MiB_MAX_RECORD_BYTES、重试次数最大 10_MAX_ATTEMPTS、重试退避最大 60 秒_MAX_RETRY_BACKOFF_SECONDS、每条记录最大 span 数 10,000_MAX_SPANS_PER_RECORD。测试 验证了超限即抛ValueError的行为。记录内容的兼容性约束记录必须是有界bounded且 JSON 兼容的值None、布尔、有限数值、字符串以及有界的嵌套列表、元组或字符串键字典。映射记录的键必须是字符串。_copy_record_value源码会递归做防御性拷贝拒绝循环引用通过active_containers集合检测、拒绝超过 4096 bit 的整数_MAX_RECORD_INT_BITS、拒绝非有限浮点数、拒绝深度超过 32 的嵌套_MAX_RECORD_DEPTH、拒绝超过 10,000 个元素_MAX_RECORD_ITEMS、拒绝超过 4,096 字符的键。任何此类问题都统一归约为无值的BeamRedactionError例如record could not be inspected测试用例。快速开始在 Beam 管道中接入脱敏 Transform下面是最小可运行示例与文档一致它把一个合成记录集合送入管道note字段被脱敏其余外层结构保持不变import apache_beam as beam from openmed.interop.beam import BeamRedactionSpec, BeamRedactionTransform spec BeamRedactionSpec( text_fieldnote, policyhipaa_safe_harbor, max_records10_000, ) with beam.Pipeline() as pipeline: redacted ( pipeline | beam.Create([{record_id: synthetic-1, note: synthetic note}]) | BeamRedactionTransform(spec) )BeamRedactionTransform在expand()中把spec包装进一个 worker 本地的_BeamRedactionDoFn源码每个DoFn实例只做一次模型加载之后对经手的所有元素复用同一 loadersetup()逻辑见 beam.py。这正是本地优先的关键模型在 worker 上加载患者数据不出运行管道所在的网络。直接传参方式除了传入完整的BeamRedactionSpecBeamRedactionTransform也允许把常见字段直接作为关键字参数传入text_field、policy、method、各边界参数、extra_kwargs、deidentifier、loader_factory。注意两者不能混用——同时提供spec与任何直接选项会抛出TypeError源码。BeamRedactionSpec 参数详解BeamRedactionSpec是契约的核心配置对象源码__post_init__会在构造时完成全部校验与归一化参数默认值说明text_fieldtext映射记录中待脱敏的字段名必须匹配安全标识符模式且不得形如patient-123456这类标识符形态防元数据误报policyhipaa_safe_harbor脱敏策略名经canonical_policy_name归一化合法策略定义见 openmed/core/policy.pymethodmask脱敏方法合法值为aadhaar_mask、format_preserve、hash、mask、remove、replace、shift_dates_DEIDENTIFICATION_METHODSmax_records10,000记录数上限max_input_bytes10 MiB输入字节上限max_output_bytes10 MiB输出字节上限max_record_bytes1 MiB单条记录字节上限max_attempts3重试上限≤ 10retry_backoff_seconds0.0重试退避秒数必须是有穷数且落在[0, 60]默认 0 表示确定性直接运行下不启用退避extra_kwargs{}转发给脱敏器的附加选项见下文安全约束spec还提供几个有价值的只读接口input_schema/output_schema稳定的模式标识符分别为string_or_mapping与same_as_inputto_deidentify_kwargs()把 method、policy 与extra_kwargs转成确定性的脱敏器调用参数to_dict()返回PHI-free的元数据只含边界、option 数量与 option 键指纹fingerprint()基于全部配置含 option 值指纹的确定性 SHA-256 指纹。这些元数据接口在 测试 中均验证了绝不暴露键值与原始值。Worker 本地模型加载与离线安全配置默认离线路径文档与源码都强调构造 Transform 不需要网络。默认的 OpenMed deidentifier 被配置为cache-only 加载只读本地模型缓存禁用凭证发现hf_token关闭 mapping 与 audit 保留keep_mappingFalse、auditFalse开启安全扫描use_safety_sweepTrue。这些默认值由_offline_config()构造的OpenMedConfig(local_onlyTrue, hf_token)与 redaction 调用点 共同保证并且 测试 明确断言了这四项开关的值。离线/气隙部署的两种姿势预置模型在每个 worker 上预先 stage 模型使 cache-only 加载命中本地缓存注入本地 deidentifier通过deidentifier参数传入自定义可调用对象或通过loader_factory注入已加载的 loader彻底绕开默认加载路径——这也是单元测试的标准做法。为什么 worker 不能通过网络覆盖这些配置extra_kwargs里列了 7 个保留键audit、config、keep_mapping、loader、method、policy、use_safety_sweep_RESERVED_EXTRA_KEYS。一旦传入即抛ValueError因此worker 无法用loader替换本地 loaderworker 无法用config削弱 cache-only 的离线默认配置worker 无法用policy/method篡改策略与方法。测试用例 逐一验证了这些保留键的拒绝行为包括循环引用对象被识别为 unsupported or unbounded。extra_kwargs有界、可序列化、值不可见extra_kwargs是转发给脱敏器的附加选项其核心设计是在构造时做快照snapshot之后与原对象完全解耦。_snapshot_extra_kwargs源码与_snapshot_extra_value源码保证只接受纯数据值None、布尔、有穷数值、字符串、字节以及有界的嵌套列表、元组或字符串键字典快照在构造时拷贝完成调用方后续改动原字典不会影响 specto_deidentify_kwargs()返回的副本改动也不回写测试快照结果是 pickle 安全的内部用_FrozenOptions/_FrozenList标记保持形状可随 spec 一起序列化下发到 worker。文档记载的快照上限为128 个顶层选项、4,096 个嵌套值、4 MiB 聚合键/字符串/字节数据。需要说明的是当前仓库源码 beam.py 中实际实现的常量略有收紧顶层选项最多 64 个_MAX_EXTRA_KWARGS、嵌套值最多 1,000 个_MAX_EXTRA_ITEMS、嵌套深度最多 16 层_MAX_EXTRA_DEPTH、单个键最长 128 字符_MAX_EXTRA_KEY_CHARS、单个字符串/字节最长 64 KiB_MAX_EXTRA_STRING_CHARS。以所安装版本的源码为准。报告只暴露数量与指纹无论 spec 元数据、运行报告还是异常信息extra_kwargs的原始键与值永远不出现。报告只暴露option 数量extra_key_countoption 键排序后的 SHA-256 指纹extra_keys_fingerprint。测试 用json.dumps(spec.to_dict())断言敏感值不出现在任何元数据中repr(spec)也只显示元数据。无 Beam 验证直接合成 harnessrun_synthetic_harness契约最大的便利在于不启动 Beam runner 也能跑通同一套逻辑。run_synthetic_harness源码复用与 Beam worker 完全一致的schema 校验规范 JSON 序列化ensure_asciiTrue、键排序、紧凑分隔符、禁用 NaN见_canonical_json记录数与字节边界有上限的重试循环。from openmed.interop.beam import BeamRedactionSpec, run_synthetic_harness result run_synthetic_harness( [{note: synthetic note}], specBeamRedactionSpec(text_fieldnote), deidentifiermy_local_deidentifier, ) print(result.redacted_records) print(result.report())它本身不做任何网络操作默认路径即 cache-only 加载。BeamRedactionResult源码包含脱敏后的记录元组、BeamRedactionCounters聚合计数器、输入/输出/spec 三个 SHA-256 指纹以及序列化输出report()返回的字典只含 schema 元数据、指纹与计数器。计数器含义BeamRedactionCounters源码暴露 8 个计数器records_processed、records_changed、records_failed、attempts、retries、spans_redacted、input_bytes、output_bytes。其构造校验已变更失败 ≤ 已处理以及重试 ≤ 尝试防止状态被篡改后流出非法统计。测试 演示了一个首次失败、第二次成功的 flaky deidentifierattempts3, retries1同时断言原始 PHI 不出现在report()与repr(result)中。有界重试与退避_redact_with_retries源码实现重试循环每尝试一次attempts加一失败后若未达上限则retries加一若retry_backoff_seconds非零则time.sleep退避直接合成运行默认0.0保持确定性、避免测试耗时耗尽尝试后抛出BeamRedactionError异常信息中只有record_fingerprintsha256:...这样的摘要指纹绝不含原始文本测试KeyboardInterrupt/SystemExit这类解释器控制异常会被原样透传不吞不包装测试。输出扩展预算契约还要防住脱敏器把合法输入放大成无限输出这一面单条输出记录上限为min(max_record_bytes * 8, 64 MiB)_MAX_OUTPUT_EXPANSION 8_MAX_OUTPUT_RECORD_BYTES输出总字节受max_output_bytes、max_input_bytes * 8、256 MiB三者最小值约束输出文本长度还受min(最大允许字符, max(4096, 原文长度 * 8))约束_MIN_OUTPUT_CHARS 4,096。超出即抛无值的BeamRedactionErrorredacted record/batch exceeds the output byte limit测试 验证了输出增长受限的行为。日志、异常与报告中的零 PHI保证整个契约的隐私红线可以总结为四句话输入值永不进入日志与异常process()抛出的任何错误都不携带原始元素runner 集中日志因此不会收集到 PHI输出值与脱敏器返回对象永不进入报告BeamRedactionResult.report()只含指纹与计数器记录标识符如record_id、mrn不进入任何元数据text_field等配置还经过_normalize_text_field的标识符形态正则拦截形如patient-123456的字段名直接判为非法实体元数据读取失败被隔离_result_entities对pii_entities/entities的访问异常会被捕获并降级为None不影响脱敏主流程测试。测试 还专门构造了记录迭代抛敏感异常映射取值抛敏感异常loader 初始化抛敏感异常脱敏器抛 BaseException等敌对场景逐一断言 traceback 渲染后也不含任何敏感值。补充另一个轻量适配器 DeidentifyText除BeamRedactionTransform外openmed/interop/beam_transform.py 还提供了更轻量的DeidentifyTextPTransformtext_fieldpolicy 透传deidentify_kwargsloader由setup()托管、不可手工传入。两者共享相同的worker 本地 loader、setup 只加载一次的哲学但DeidentifyText不包含有界契约与报告体系是面向简单接入场景的薄封装。该模块同样在未安装 Beam 时仅于expand()阶段报错源码。适用边界与最佳实践小结适用场景有界批处理管道中的结构化记录脱敏如 ETL 批量清洗、FHIR Bundle 批量导出前的 PHI 预处理要求吞吐可控、边界明确、日志零 PHI不适用场景无界流式管道契约明确面向 bounded pipeline、需要在 worker 上动态联网拉取模型默认离线配置禁止等上线前建议先在本地用run_synthetic_harness配合注入的 deidentifier 做确定性验证含失败重试路径再把同一BeamRedactionSpec原样用于 Beam 管道——两个入口共享同一套校验与边界逻辑气隙部署预置模型到 worker 本地缓存或注入deidentifier/loader_factory并保持extra_kwargs中不出现任何保留键。相关参考契约实现 openmed/interop/beam.py、轻量适配器 openmed/interop/beam_transform.py、适配器注册表 openmed/interop/init.py、依赖声明 pyproject.toml、测试 tests/unit/interop/test_beam.py 与 tests/unit/interop/test_beam_transform.py。【免费下载链接】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），仅供参考 OpenMed Apache Beam 批处理脱敏：面向有界管道的本地优先 Redaction Transform 实战指南
OpenMed Apache Beam 批处理脱敏面向有界管道的本地优先 Redaction Transform 实战指南【免费下载链接】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 为 Apache Beam 提供了一套小而严的脱敏契约Redaction Contract在**有界批处理管道bounded batch pipeline**中将每个元素交给 worker 本地加载的脱敏模型处理而整个运行过程受记录数、字节数与重试次数三重边界约束。本文以 docs/integrations/beam.md 为主体结合 契约实现源码 与 单元测试完整讲解如何安装、配置、运行 Beam 脱敏 Transform如何在不安装 Beam 的情况下用直接合成 harness 验证序列化与重试行为以及这套契约如何在日志、异常与报告中做到零 PHI 泄漏。为什么需要一套有界的 Beam 脱敏契约Beam 管道天然会把数据分发到多个 worker而脱敏de-identification又天然涉及患者隐私文本PHI。如果脱敏逻辑里出现未捕获的异常或某个 redactor 把一条合法输入放大成无限大的输出最终都会流入 runner 的集中式日志——这正是隐私事故的高发点。OpenMed 的做法是把脱敏封装成一个受严格边界约束的 PTransform元素类型固定、字节与记录数受限、重试有上限、状态只保留计数器和字节总量。无论输入如何恶意循环引用、超大整数、非 JSON 值契约都会在脱敏之前以稳定且不含值value-free的错误拒绝它。这一设计在 beam.py 模块 docstring 中有明确说明。安装Beam 是可选项Beam SDK 对 OpenMed 而言是可选依赖。契约模块本身可以脱离 Beam 独立导入、配置并借助run_synthetic_harness完成序列化与重试行为验证——这意味着 CI 或离线环境完全不需要安装 Beam 就能测试脱敏逻辑pip install openmed[beam]从 pyproject.toml 可以看到该 extra 声明的版本区间为apache-beam2.73,3。适配器注册表 openmed/interop/init.py 中登记了beam适配器指向openmed.interop.beam_transform模块并注明其 extras 为beam。未安装 Beam 时的行为也很明确导入openmed或openmed.interop永远不会强制引入apache_beam只有当真正执行expand()时_require_beam()才会抛出ImportError并提示安装openmed[beam]测试用例验证了这一行为。核心契约元素形状、默认边界与 JSON 兼容性元素形状Element ShapeTransform 接受两种元素字符串元素整个字符串作为待脱敏文本映射Mapping元素配置一个text_field只变换该字段其余字段与记录外层结构保持不变。若该字段值为None契约会原样保留而不触发 redactor见 BeamRedactionSpec docstring。从 测试用例 可见{id: 7, note: Jane Roe called 555-0100}经过处理后得到{id: 7, note: [PERSON] called [PHONE]}id原封不动。默认边界Default Bounds契约对单次运行给出明确限额源码常量 与文档一致边界项默认值说明max_records10,000单次运行处理的记录上限max_input_bytes10 MiB序列化后输入总字节上限max_output_bytes10 MiB序列化后输出总字节上限max_record_bytes1 MiB单条输入/输出记录序列化字节上限max_attempts3单条记录的脱敏尝试次数上限另外还有一组**硬上限hard ceilings**不可配置逾越记录数最大 1,000,000_MAX_RECORDS、输入/输出字节最大 256 MiB_MAX_INPUT_BYTES/_MAX_OUTPUT_BYTES、单条记录最大 16 MiB_MAX_RECORD_BYTES、重试次数最大 10_MAX_ATTEMPTS、重试退避最大 60 秒_MAX_RETRY_BACKOFF_SECONDS、每条记录最大 span 数 10,000_MAX_SPANS_PER_RECORD。测试 验证了超限即抛ValueError的行为。记录内容的兼容性约束记录必须是有界bounded且 JSON 兼容的值None、布尔、有限数值、字符串以及有界的嵌套列表、元组或字符串键字典。映射记录的键必须是字符串。_copy_record_value源码会递归做防御性拷贝拒绝循环引用通过active_containers集合检测、拒绝超过 4096 bit 的整数_MAX_RECORD_INT_BITS、拒绝非有限浮点数、拒绝深度超过 32 的嵌套_MAX_RECORD_DEPTH、拒绝超过 10,000 个元素_MAX_RECORD_ITEMS、拒绝超过 4,096 字符的键。任何此类问题都统一归约为无值的BeamRedactionError例如record could not be inspected测试用例。快速开始在 Beam 管道中接入脱敏 Transform下面是最小可运行示例与文档一致它把一个合成记录集合送入管道note字段被脱敏其余外层结构保持不变import apache_beam as beam from openmed.interop.beam import BeamRedactionSpec, BeamRedactionTransform spec BeamRedactionSpec( text_fieldnote, policyhipaa_safe_harbor, max_records10_000, ) with beam.Pipeline() as pipeline: redacted ( pipeline | beam.Create([{record_id: synthetic-1, note: synthetic note}]) | BeamRedactionTransform(spec) )BeamRedactionTransform在expand()中把spec包装进一个 worker 本地的_BeamRedactionDoFn源码每个DoFn实例只做一次模型加载之后对经手的所有元素复用同一 loadersetup()逻辑见 beam.py。这正是本地优先的关键模型在 worker 上加载患者数据不出运行管道所在的网络。直接传参方式除了传入完整的BeamRedactionSpecBeamRedactionTransform也允许把常见字段直接作为关键字参数传入text_field、policy、method、各边界参数、extra_kwargs、deidentifier、loader_factory。注意两者不能混用——同时提供spec与任何直接选项会抛出TypeError源码。BeamRedactionSpec 参数详解BeamRedactionSpec是契约的核心配置对象源码__post_init__会在构造时完成全部校验与归一化参数默认值说明text_fieldtext映射记录中待脱敏的字段名必须匹配安全标识符模式且不得形如patient-123456这类标识符形态防元数据误报policyhipaa_safe_harbor脱敏策略名经canonical_policy_name归一化合法策略定义见 openmed/core/policy.pymethodmask脱敏方法合法值为aadhaar_mask、format_preserve、hash、mask、remove、replace、shift_dates_DEIDENTIFICATION_METHODSmax_records10,000记录数上限max_input_bytes10 MiB输入字节上限max_output_bytes10 MiB输出字节上限max_record_bytes1 MiB单条记录字节上限max_attempts3重试上限≤ 10retry_backoff_seconds0.0重试退避秒数必须是有穷数且落在[0, 60]默认 0 表示确定性直接运行下不启用退避extra_kwargs{}转发给脱敏器的附加选项见下文安全约束spec还提供几个有价值的只读接口input_schema/output_schema稳定的模式标识符分别为string_or_mapping与same_as_inputto_deidentify_kwargs()把 method、policy 与extra_kwargs转成确定性的脱敏器调用参数to_dict()返回PHI-free的元数据只含边界、option 数量与 option 键指纹fingerprint()基于全部配置含 option 值指纹的确定性 SHA-256 指纹。这些元数据接口在 测试 中均验证了绝不暴露键值与原始值。Worker 本地模型加载与离线安全配置默认离线路径文档与源码都强调构造 Transform 不需要网络。默认的 OpenMed deidentifier 被配置为cache-only 加载只读本地模型缓存禁用凭证发现hf_token关闭 mapping 与 audit 保留keep_mappingFalse、auditFalse开启安全扫描use_safety_sweepTrue。这些默认值由_offline_config()构造的OpenMedConfig(local_onlyTrue, hf_token)与 redaction 调用点 共同保证并且 测试 明确断言了这四项开关的值。离线/气隙部署的两种姿势预置模型在每个 worker 上预先 stage 模型使 cache-only 加载命中本地缓存注入本地 deidentifier通过deidentifier参数传入自定义可调用对象或通过loader_factory注入已加载的 loader彻底绕开默认加载路径——这也是单元测试的标准做法。为什么 worker 不能通过网络覆盖这些配置extra_kwargs里列了 7 个保留键audit、config、keep_mapping、loader、method、policy、use_safety_sweep_RESERVED_EXTRA_KEYS。一旦传入即抛ValueError因此worker 无法用loader替换本地 loaderworker 无法用config削弱 cache-only 的离线默认配置worker 无法用policy/method篡改策略与方法。测试用例 逐一验证了这些保留键的拒绝行为包括循环引用对象被识别为 unsupported or unbounded。extra_kwargs有界、可序列化、值不可见extra_kwargs是转发给脱敏器的附加选项其核心设计是在构造时做快照snapshot之后与原对象完全解耦。_snapshot_extra_kwargs源码与_snapshot_extra_value源码保证只接受纯数据值None、布尔、有穷数值、字符串、字节以及有界的嵌套列表、元组或字符串键字典快照在构造时拷贝完成调用方后续改动原字典不会影响 specto_deidentify_kwargs()返回的副本改动也不回写测试快照结果是 pickle 安全的内部用_FrozenOptions/_FrozenList标记保持形状可随 spec 一起序列化下发到 worker。文档记载的快照上限为128 个顶层选项、4,096 个嵌套值、4 MiB 聚合键/字符串/字节数据。需要说明的是当前仓库源码 beam.py 中实际实现的常量略有收紧顶层选项最多 64 个_MAX_EXTRA_KWARGS、嵌套值最多 1,000 个_MAX_EXTRA_ITEMS、嵌套深度最多 16 层_MAX_EXTRA_DEPTH、单个键最长 128 字符_MAX_EXTRA_KEY_CHARS、单个字符串/字节最长 64 KiB_MAX_EXTRA_STRING_CHARS。以所安装版本的源码为准。报告只暴露数量与指纹无论 spec 元数据、运行报告还是异常信息extra_kwargs的原始键与值永远不出现。报告只暴露option 数量extra_key_countoption 键排序后的 SHA-256 指纹extra_keys_fingerprint。测试 用json.dumps(spec.to_dict())断言敏感值不出现在任何元数据中repr(spec)也只显示元数据。无 Beam 验证直接合成 harnessrun_synthetic_harness契约最大的便利在于不启动 Beam runner 也能跑通同一套逻辑。run_synthetic_harness源码复用与 Beam worker 完全一致的schema 校验规范 JSON 序列化ensure_asciiTrue、键排序、紧凑分隔符、禁用 NaN见_canonical_json记录数与字节边界有上限的重试循环。from openmed.interop.beam import BeamRedactionSpec, run_synthetic_harness result run_synthetic_harness( [{note: synthetic note}], specBeamRedactionSpec(text_fieldnote), deidentifiermy_local_deidentifier, ) print(result.redacted_records) print(result.report())它本身不做任何网络操作默认路径即 cache-only 加载。BeamRedactionResult源码包含脱敏后的记录元组、BeamRedactionCounters聚合计数器、输入/输出/spec 三个 SHA-256 指纹以及序列化输出report()返回的字典只含 schema 元数据、指纹与计数器。计数器含义BeamRedactionCounters源码暴露 8 个计数器records_processed、records_changed、records_failed、attempts、retries、spans_redacted、input_bytes、output_bytes。其构造校验已变更失败 ≤ 已处理以及重试 ≤ 尝试防止状态被篡改后流出非法统计。测试 演示了一个首次失败、第二次成功的 flaky deidentifierattempts3, retries1同时断言原始 PHI 不出现在report()与repr(result)中。有界重试与退避_redact_with_retries源码实现重试循环每尝试一次attempts加一失败后若未达上限则retries加一若retry_backoff_seconds非零则time.sleep退避直接合成运行默认0.0保持确定性、避免测试耗时耗尽尝试后抛出BeamRedactionError异常信息中只有record_fingerprintsha256:...这样的摘要指纹绝不含原始文本测试KeyboardInterrupt/SystemExit这类解释器控制异常会被原样透传不吞不包装测试。输出扩展预算契约还要防住脱敏器把合法输入放大成无限输出这一面单条输出记录上限为min(max_record_bytes * 8, 64 MiB)_MAX_OUTPUT_EXPANSION 8_MAX_OUTPUT_RECORD_BYTES输出总字节受max_output_bytes、max_input_bytes * 8、256 MiB三者最小值约束输出文本长度还受min(最大允许字符, max(4096, 原文长度 * 8))约束_MIN_OUTPUT_CHARS 4,096。超出即抛无值的BeamRedactionErrorredacted record/batch exceeds the output byte limit测试 验证了输出增长受限的行为。日志、异常与报告中的零 PHI保证整个契约的隐私红线可以总结为四句话输入值永不进入日志与异常process()抛出的任何错误都不携带原始元素runner 集中日志因此不会收集到 PHI输出值与脱敏器返回对象永不进入报告BeamRedactionResult.report()只含指纹与计数器记录标识符如record_id、mrn不进入任何元数据text_field等配置还经过_normalize_text_field的标识符形态正则拦截形如patient-123456的字段名直接判为非法实体元数据读取失败被隔离_result_entities对pii_entities/entities的访问异常会被捕获并降级为None不影响脱敏主流程测试。测试 还专门构造了记录迭代抛敏感异常映射取值抛敏感异常loader 初始化抛敏感异常脱敏器抛 BaseException等敌对场景逐一断言 traceback 渲染后也不含任何敏感值。补充另一个轻量适配器 DeidentifyText除BeamRedactionTransform外openmed/interop/beam_transform.py 还提供了更轻量的DeidentifyTextPTransformtext_fieldpolicy 透传deidentify_kwargsloader由setup()托管、不可手工传入。两者共享相同的worker 本地 loader、setup 只加载一次的哲学但DeidentifyText不包含有界契约与报告体系是面向简单接入场景的薄封装。该模块同样在未安装 Beam 时仅于expand()阶段报错源码。适用边界与最佳实践小结适用场景有界批处理管道中的结构化记录脱敏如 ETL 批量清洗、FHIR Bundle 批量导出前的 PHI 预处理要求吞吐可控、边界明确、日志零 PHI不适用场景无界流式管道契约明确面向 bounded pipeline、需要在 worker 上动态联网拉取模型默认离线配置禁止等上线前建议先在本地用run_synthetic_harness配合注入的 deidentifier 做确定性验证含失败重试路径再把同一BeamRedactionSpec原样用于 Beam 管道——两个入口共享同一套校验与边界逻辑气隙部署预置模型到 worker 本地缓存或注入deidentifier/loader_factory并保持extra_kwargs中不出现任何保留键。相关参考契约实现 openmed/interop/beam.py、轻量适配器 openmed/interop/beam_transform.py、适配器注册表 openmed/interop/init.py、依赖声明 pyproject.toml、测试 tests/unit/interop/test_beam.py 与 tests/unit/interop/test_beam_transform.py。【免费下载链接】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），仅供参考