OpenMed HL7 v2 去标识化实战指南本地管道式 PHI 脱敏与叙述提取【免费下载链接】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/openmedHL7 v2.x 管道分隔消息是医院信息系统ADT 就诊、ORU 检验结果、ORM 医嘱最常用的交换格式其中承载着患者标识、姓名、地址、电话、出生日期等大量受保护健康信息PHI。本文基于 OpenMed 的 HL7 v2 去标识化模块系统讲解如何在完全不调用网络服务、不运行 MLLP 监听器的情况下用一段本地 Python 代码将常见 ADT/ORU/ORM 消息中的敏感字段批量脱敏并保留段顺序、分隔符、重复组、组件与子组件的原始结构同时介绍配套的 HL7 v2 叙述提取器把脱敏结果渲染为可直接用于临床 NLP 或人工审阅的平铺/分节文本并保留指向原始段字段的精确偏移。读完本文你将掌握redact_hl7v2的完整调用方式、默认字段映射、四种结构化字段动作与自由文本处理管道并能通过自定义字段规则覆盖 Z 段等未知段。核心定位本地的、机械化的、结构感知的脱敏助手OpenMed 的 HL7 v2 去标识化模块的设计哲学可以从模块文档字符串与实现中直接读出openmed/interop/hl7v2.py本地不运行 MLLP 监听器、不校验完整的一致性配置文件、也不调用任何网络服务。整个处理链路全部在内存中完成患者数据不会离开当前进程。机械化mechanical它不是一个完整的 HL7 一致性验证器而是针对常见 ADT、ORU、ORM 消息流做字段级规则驱动的脱敏。结构感知解析器从MSH-1与MSH-2推导分隔符集按段名 字段位置施加规则因此脱敏后消息仍然可以被下游 HL7 系统正常解析。模块在openmed.interop适配器注册表中以hl7v2名称惰性加载测试 tests/unit/interop/test_hl7v2.py 验证了get_adapter(hl7v2)返回的对象暴露了redact_hl7v2接口。这意味着它可以与 OpenMed 的其余互操作工具链如 FHIR 导出、Spark 集成一样通过统一的适配器入口按需获取。快速开始redact_hl7v2接受 HL7 消息文本、文件路径字符串或Path对象返回脱敏后的完整消息文本from openmed.interop.hl7v2 import redact_hl7v2 redacted redact_hl7v2(synthetic_oru.hl7, date_shift_days31)从源码看openmed/interop/hl7v2.pymessage_or_path的判定逻辑是如果传入字符串以MSH开头允许 BOM 前缀则视为消息文本直接处理否则尝试作为 UTF-8 文件路径读取两者都不是则原样返回字符串。完整签名如下openmed/interop/hl7v2.pydef redact_hl7v2( message_or_path: str | Path, *, field_map: Mapping[FieldKey | str, Any] | None None, deidentifier: TextDeidentifier | None None, deidentify_kwargs: Mapping[str, Any] | None None, date_shift_days: int | None None, lang: str en, locale: str | None None, seed: int | None 0, ) - str参数要点参数默认值作用field_mapDEFAULT_FIELD_MAP按(PID, 5)或PID-5键控的字段规则表用于扩展或替换默认规则deidentifieropenmed.core.pii.deidentify用于 OBX/NTE 自由文本的文本去标识回调deidentify_kwargs{}转发给文本去标识器的关键字参数默认强制methodmaskdate_shift_days随机非零偏移消息内所有配置日期共用的一致偏移天数langen转发给替身生成的语种localeNone可选的 Faker locale 覆盖用于替身生成seed0结构化替身的确定性种子保证可重复流水线输出稳定注意date_shift_days与seed的默认行为差异日期偏移未指定时模块会用random.SystemRandom在[-365, 365]区间内随机选取一个非零偏移openmed/interop/hl7v2.py并在整条消息内保持一致而替身种子默认为0刻意保持结构化替身的可重复性。解析器与序列化保留分段结构的底层原理脱敏是否安全可逆取决于解析器对消息结构的保真度。模块实现了三个核心数据类openmed/interop/hl7v2.pyHL7V2Encoding分隔符集从原始 MSH 段推导。MSH-1是字段分隔符第 4 个字符MSH-2依次为组件分隔符、重复分隔符、转义字符、子组件分隔符。MSH-2必须恰好 4 个字符否则抛ValueError(HL7 MSH-2 must contain exactly four encoding characters)。测试 tests/unit/interop/test_hl7v2.py 验证了MSH|、MSH|^这类非法消息会被拒绝。HL7Segment段按分隔符拆分字段字段位置从 1 开始。MSH段特殊处理MSH-1由字段分隔符推导不可 set序列化时fields[0]会重新写入四个编码字符openmed/interop/hl7v2.py。非 MSH 段必须携带消息级编码才能解析。HL7Message消息负责段间结构保真。解析时先自动探测段分隔符\r\n\r\n见 openmed/interop/hl7v2.py记录末尾分隔符与空白行位置——空白行不参与解析但位置被记录下来序列化时原样还原保证逐字节往返一致。测试 tests/unit/interop/test_hl7v2.py 覆盖了前导空白行、内部空白行、尾部多空白行、CRLF 分隔符等 8 种布局全部满足parse(...).serialize() original。一个值得注意的细节是 BOM 处理解析时首个段会lstrip(\ufeff)去掉 UTF-8 BOMopenmed/interop/hl7v2.py这让 Windows 导出的 HL7 文件也能直接处理。自定义分隔符消息同样受支持——测试 tests/unit/interop/test_hl7v2.py 用MSH*$%?*...验证了字段分隔符*、组件分隔符$的消息在脱敏后分隔符与段结构完全保留。支持范围与默认字段映射模块面向 ADT、ORU、ORM 三类常见消息流SUPPORTED_MESSAGE_TYPES (ADT, ORU, ORM)。默认字段映射定义在 openmed/interop/hl7v2.py规则以段名 字段位置为键、以HL7FieldRule为值段字段位置动作标签PID3hashID_NUMPID5surrogate组件级PERSON/LAST_NAME、FIRST_NAME、MIDDLE_NAMEPID7date-shiftDATE_OF_BIRTHPID11surrogateSTREET_ADDRESSPID13hashPHONEPID19hashSSNPD13surrogateORGANIZATIONNK12surrogate组件级PERSONNK14surrogateSTREET_ADDRESSNK15hashPHONENK113surrogateORGANIZATIONGT13surrogate组件级PERSONGT15surrogateSTREET_ADDRESSGT16hashPHONEGT112hashSSNGT113date-shiftDATE_OF_BIRTHIN116surrogate组件级PERSONIN118date-shiftDATE_OF_BIRTHIN119surrogateSTREET_ADDRESSIN136hashACCOUNT_NUMBERIN21hashID_NUMIN22hashSSNOBX5redact_text类型约束OTHERNTE3redact_textOTHER未知段原样通过——除非你为它的某个字段显式配置规则测试 tests/unit/interop/test_hl7v2.py 验证了ZZZ段保持Leave Jane Roe unchanged不变而配置了规则的ZNT-2被脱敏为Call [PERSON] at [PHONE]。这一设计让 Z 段这类机构自定义段在默认情况下既不会报错也不会误伤需要时再针对性加规则。四种结构化字段动作结构化字段即非自由文本字段支持四种动作由FieldAction类型定义openmed/interop/hl7v2.pyclear —— 清空字段值最简单粗暴将字段值替换为空字符串。适用于宁可删掉也不能保留的字段。hash —— 确定性哈希令牌对每个叶子值生成[LABEL_HASH_sha256前12位]形式的令牌例如[ID_NUM_HASH_3f2a9c1b...]。实现细节openmed/interop/hl7v2.pydigest hashlib.sha256( f{rule.hash_salt}|{label}|{value}.encode(utf-8) ).hexdigest() return f[{label}_HASH_{digest[:12]}]同一原始值在同一hash_salt下永远得到同一令牌因此跨消息做实体关联例如同一 MRN 在不同消息中对应同一令牌成为可能通过HL7FieldRule(hash_salt...)可以为每条消息引入额外盐值增加抗字典攻击能力。哈希处理会遍历重复组、组件、子组件的每一层叶子但保留 HL7 分隔符本身因此MRN111^^^GOOD HOSPITAL^MR脱敏后仍然保持三组件的结构。surrogate —— 标签感知替身值调用Anonymizeropenmed/core/anonymizer.py为叶子值生成看起来真实但完全是假的替身同时保留重复组、组件、子组件的布局。替身生成支持lang、locale并可通过seed固定结果以保证流水线可复现openmed/interop/hl7v2.py 用consistentTrue实例化Anonymizer。对于 XPN 风格的姓名复合字段如PID-5、NK1-2、GT1-3、IN1-16默认映射通过component_labels在组件级施加减标签{1: LAST_NAME, 2: FIRST_NAME, 3: MIDDLE_NAME}让姓、名、中间名分别生成符合其语义的替身。date-shift —— 消息内一致的日期偏移每个配置了 date-shift 的日期按同一偏移平移保持消息内部日期间隔不变。实现识别两类格式[openmed/interop/hl7v2.py](https://link.gitcode.com/i/8887f33621da30dba2000dd8b345044c#L29-L34, L626-L658)HL7 原生日期时间YYYYMMDD[HHMMSS[.fff]][/-HHMM]如19800101、202401011200000800ISO 风格日期YYYY-MM-DD或YYYY/MM/DD。合法日期平移后保持原格式与时间部分无法解析的日期返回空字符串宁可清空也不保留可能泄漏的日期。测试 tests/unit/interop/test_hl7v2.py 验证了PID-7出生日期与IN1-18投保人出生日期在date_shift_days45时都从19800101变为19800215偏移一致。该测试还同时验证了19800101原始值在整条消息中不再出现。自由文本字段接入 OpenMed PII 管道两条默认规则处理自由文本OBX-5当且仅当OBX-2值类型为TX或FT时type_field2, allowed_type_values(FT, TX)即DEFAULT_NOTE_VALUE_TYPESNTE-3注释文本无条件。自由文本走redact_text动作调用deidentifier回调默认是 openmed/core/pii.py 的deidentify强制传入methodmask与lang并把调用方提供的deidentify_kwargs与规则的rule.deidentify_kwargs合并后者优先级更高。回调的返回值可以是纯字符串也可以是带deidentified_text属性的对象或 mapping否则抛TypeErroropenmed/interop/hl7v2.py。文本去标识走的是 OpenMed 完整 PII 检测链路支持 mask / remove / replace / hash / shift_dates / format_preserve 等方法默认methodmask置信度阈值默认 0.7 以保障安全。测试 tests/unit/interop/test_hl7v2.py 展示了完整效果OBX-5的自由文本Patient Jane Roe called from 555-0101 about MRN12345.被脱敏为Patient [PERSON] called from [PHONE] about [ID_NUM].而OBX-2NM数值的OBX-5如7.1保持原样——正是allowed_type_values类型约束在起作用。另一个测试tests/unit/interop/test_hl7v2.py验证了lang参数会原样透传给每个文本脱敏调用。离线测试技巧生产环境依赖模型推理但在单元测试/离线校验时可以传入一个确定性 callable 代替真实deidentify例如测试中用SimpleNamespace(deidentified_text...)包装结果。这让你无需加载模型即可回归验证字段映射是否正确。扩展规则覆盖 Z 段与自定义字段通过field_map传入替换映射键可以是元组或字符串两种形式二者等价from openmed.interop.hl7v2 import DEFAULT_FIELD_MAP, HL7FieldRule, redact_hl7v2 field_map { **DEFAULT_FIELD_MAP, ZNT-2: HL7FieldRule(redact_text), (ZID, 4): HL7FieldRule(hash, labelID_NUM), } redacted redact_hl7v2(message_text, field_mapfield_map)键规范化逻辑openmed/interop/hl7v2.py字符串按-分割段名统一大写、位置转 int非法键抛ValueError。值是HL7FieldRule或与其等价的 mapping也允许规则列表同一字段可链式施加多条规则规则对象在构造时会校验动作名并规范化date_shift→date-shift、redact-text→redact_text等别名写法openmed/interop/hl7v2.py。HL7FieldRule的完整字段字段默认值说明action必填clear/hash/surrogate/date-shift/redact_textlabelID_NUM替身/哈希的实体标签component_labels{}组件级标签覆盖1-based 组件位置 → 标签type_fieldNone条件触发读取该字段位置的值类型allowed_type_values()与type_field配合值类型大写在集合内才生效hash_salt哈希盐值deidentify_kwargs{}透传给文本去标识器的额外参数_rule_applies的实现openmed/interop/hl7v2.py显示当type_field的取值类型组件分隔符前的首组件大写命中allowed_type_values集合时规则生效两者任一为空则规则无条件生效。这正是OBX-5只在TX/FT时脱敏的机制你也可以用它实现ZID-4只在某状态码下 hash之类的条件规则。脱敏后的下游使用HL7 v2 叙述提取脱敏后的消息仍保持 HL7 结构可直接回写 HL7 消费方。若下游要做临床 NLP 或人工审阅OpenMed 还提供配套的叙述提取器实现见 openmed/interop/hl7v2_narrative.py它复用本文所述的同一套解析器与脱敏器extract_hl7v2_narrative内部先调用redact_hl7v2且刻意用 identity 函数保持自由文本原样待完整叙述渲染完成后统一再过一遍 PII 管道见 openmed/interop/hl7v2_narrative.py将 ADT/ORU/ORM 消息渲染为可读文本并保留指向源字段的精确偏移from openmed.interop.hl7v2_narrative import extract_hl7v2_narrative result extract_hl7v2_narrative(synthetic_oru.hl7) print(result.text) for span in result.spans_for(OBX, 5): print(span.source.path, result.text_for(span))flat 模式默认紧凑的句子式文本适合下游 NLPsectioned 模式稳定的 Markdown 分节输出Message/Patient/Encounter/Orders/Observations/Notes适合人工审阅界面空节自动省略两种模式都保持消息内顺序并返回节级偏移。每个字段 span 都带有HL7V2FieldSourcesegment三段名、segment_index消息内零基位置、segment_occurrence同名段的 1-based 出现次数、field_position1-based 字段号并提供OBX[2]-5这种紧凑路径openmed/interop/hl7v2_narrative.py。provenance_at(offset)可从叙述文本中任意字符位置反查来源字段。叙述渲染覆盖 MSH、EVN、PID、PV1、ORC、OBR、OBX、NTE 的常见上下文docs/interop/hl7v2-narrative-extraction.md未知段被渲染器忽略但仍可被底层解析器与自定义字段映射覆盖。常见问题与边界非 HL7 输入消息必须以MSH开头且MSH-2恰好 4 个编码字符否则抛ValueError空消息抛ValueError(empty HL7 v2 message)。字段位置从 1 开始MSH-1由分隔符推导、不可修改openmed/interop/hl7v2.py。未配置的字段不动默认映射之外的任何字段包括PID-8管理性别这类非敏感字段原样保留。这不是合规验证器文档明确声明它不校验完整 conformance profile也不调用网络服务若你的部署需要 MLLP 传输或完整消息验证应在其外层接入对应的传输与校验组件。确定性权衡hash与surrogate在固定seed下确定可复现date-shift在未显式指定时随机——如需整条流水线完全确定请显式传入date_shift_days与seed。整体来看openmed.interop.hl7v2是一个小而完整的本地化方案结构化字段四类动作 自由文本 PII 管道 精确结构保真加上叙述提取器即可构成从 HL7 管道消息到可安全外发的脱敏文本/结构化结果的完整闭环。【免费下载链接】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 HL7 v2 去标识化实战指南：本地管道式 PHI 脱敏与叙述提取
OpenMed HL7 v2 去标识化实战指南本地管道式 PHI 脱敏与叙述提取【免费下载链接】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/openmedHL7 v2.x 管道分隔消息是医院信息系统ADT 就诊、ORU 检验结果、ORM 医嘱最常用的交换格式其中承载着患者标识、姓名、地址、电话、出生日期等大量受保护健康信息PHI。本文基于 OpenMed 的 HL7 v2 去标识化模块系统讲解如何在完全不调用网络服务、不运行 MLLP 监听器的情况下用一段本地 Python 代码将常见 ADT/ORU/ORM 消息中的敏感字段批量脱敏并保留段顺序、分隔符、重复组、组件与子组件的原始结构同时介绍配套的 HL7 v2 叙述提取器把脱敏结果渲染为可直接用于临床 NLP 或人工审阅的平铺/分节文本并保留指向原始段字段的精确偏移。读完本文你将掌握redact_hl7v2的完整调用方式、默认字段映射、四种结构化字段动作与自由文本处理管道并能通过自定义字段规则覆盖 Z 段等未知段。核心定位本地的、机械化的、结构感知的脱敏助手OpenMed 的 HL7 v2 去标识化模块的设计哲学可以从模块文档字符串与实现中直接读出openmed/interop/hl7v2.py本地不运行 MLLP 监听器、不校验完整的一致性配置文件、也不调用任何网络服务。整个处理链路全部在内存中完成患者数据不会离开当前进程。机械化mechanical它不是一个完整的 HL7 一致性验证器而是针对常见 ADT、ORU、ORM 消息流做字段级规则驱动的脱敏。结构感知解析器从MSH-1与MSH-2推导分隔符集按段名 字段位置施加规则因此脱敏后消息仍然可以被下游 HL7 系统正常解析。模块在openmed.interop适配器注册表中以hl7v2名称惰性加载测试 tests/unit/interop/test_hl7v2.py 验证了get_adapter(hl7v2)返回的对象暴露了redact_hl7v2接口。这意味着它可以与 OpenMed 的其余互操作工具链如 FHIR 导出、Spark 集成一样通过统一的适配器入口按需获取。快速开始redact_hl7v2接受 HL7 消息文本、文件路径字符串或Path对象返回脱敏后的完整消息文本from openmed.interop.hl7v2 import redact_hl7v2 redacted redact_hl7v2(synthetic_oru.hl7, date_shift_days31)从源码看openmed/interop/hl7v2.pymessage_or_path的判定逻辑是如果传入字符串以MSH开头允许 BOM 前缀则视为消息文本直接处理否则尝试作为 UTF-8 文件路径读取两者都不是则原样返回字符串。完整签名如下openmed/interop/hl7v2.pydef redact_hl7v2( message_or_path: str | Path, *, field_map: Mapping[FieldKey | str, Any] | None None, deidentifier: TextDeidentifier | None None, deidentify_kwargs: Mapping[str, Any] | None None, date_shift_days: int | None None, lang: str en, locale: str | None None, seed: int | None 0, ) - str参数要点参数默认值作用field_mapDEFAULT_FIELD_MAP按(PID, 5)或PID-5键控的字段规则表用于扩展或替换默认规则deidentifieropenmed.core.pii.deidentify用于 OBX/NTE 自由文本的文本去标识回调deidentify_kwargs{}转发给文本去标识器的关键字参数默认强制methodmaskdate_shift_days随机非零偏移消息内所有配置日期共用的一致偏移天数langen转发给替身生成的语种localeNone可选的 Faker locale 覆盖用于替身生成seed0结构化替身的确定性种子保证可重复流水线输出稳定注意date_shift_days与seed的默认行为差异日期偏移未指定时模块会用random.SystemRandom在[-365, 365]区间内随机选取一个非零偏移openmed/interop/hl7v2.py并在整条消息内保持一致而替身种子默认为0刻意保持结构化替身的可重复性。解析器与序列化保留分段结构的底层原理脱敏是否安全可逆取决于解析器对消息结构的保真度。模块实现了三个核心数据类openmed/interop/hl7v2.pyHL7V2Encoding分隔符集从原始 MSH 段推导。MSH-1是字段分隔符第 4 个字符MSH-2依次为组件分隔符、重复分隔符、转义字符、子组件分隔符。MSH-2必须恰好 4 个字符否则抛ValueError(HL7 MSH-2 must contain exactly four encoding characters)。测试 tests/unit/interop/test_hl7v2.py 验证了MSH|、MSH|^这类非法消息会被拒绝。HL7Segment段按分隔符拆分字段字段位置从 1 开始。MSH段特殊处理MSH-1由字段分隔符推导不可 set序列化时fields[0]会重新写入四个编码字符openmed/interop/hl7v2.py。非 MSH 段必须携带消息级编码才能解析。HL7Message消息负责段间结构保真。解析时先自动探测段分隔符\r\n\r\n见 openmed/interop/hl7v2.py记录末尾分隔符与空白行位置——空白行不参与解析但位置被记录下来序列化时原样还原保证逐字节往返一致。测试 tests/unit/interop/test_hl7v2.py 覆盖了前导空白行、内部空白行、尾部多空白行、CRLF 分隔符等 8 种布局全部满足parse(...).serialize() original。一个值得注意的细节是 BOM 处理解析时首个段会lstrip(\ufeff)去掉 UTF-8 BOMopenmed/interop/hl7v2.py这让 Windows 导出的 HL7 文件也能直接处理。自定义分隔符消息同样受支持——测试 tests/unit/interop/test_hl7v2.py 用MSH*$%?*...验证了字段分隔符*、组件分隔符$的消息在脱敏后分隔符与段结构完全保留。支持范围与默认字段映射模块面向 ADT、ORU、ORM 三类常见消息流SUPPORTED_MESSAGE_TYPES (ADT, ORU, ORM)。默认字段映射定义在 openmed/interop/hl7v2.py规则以段名 字段位置为键、以HL7FieldRule为值段字段位置动作标签PID3hashID_NUMPID5surrogate组件级PERSON/LAST_NAME、FIRST_NAME、MIDDLE_NAMEPID7date-shiftDATE_OF_BIRTHPID11surrogateSTREET_ADDRESSPID13hashPHONEPID19hashSSNPD13surrogateORGANIZATIONNK12surrogate组件级PERSONNK14surrogateSTREET_ADDRESSNK15hashPHONENK113surrogateORGANIZATIONGT13surrogate组件级PERSONGT15surrogateSTREET_ADDRESSGT16hashPHONEGT112hashSSNGT113date-shiftDATE_OF_BIRTHIN116surrogate组件级PERSONIN118date-shiftDATE_OF_BIRTHIN119surrogateSTREET_ADDRESSIN136hashACCOUNT_NUMBERIN21hashID_NUMIN22hashSSNOBX5redact_text类型约束OTHERNTE3redact_textOTHER未知段原样通过——除非你为它的某个字段显式配置规则测试 tests/unit/interop/test_hl7v2.py 验证了ZZZ段保持Leave Jane Roe unchanged不变而配置了规则的ZNT-2被脱敏为Call [PERSON] at [PHONE]。这一设计让 Z 段这类机构自定义段在默认情况下既不会报错也不会误伤需要时再针对性加规则。四种结构化字段动作结构化字段即非自由文本字段支持四种动作由FieldAction类型定义openmed/interop/hl7v2.pyclear —— 清空字段值最简单粗暴将字段值替换为空字符串。适用于宁可删掉也不能保留的字段。hash —— 确定性哈希令牌对每个叶子值生成[LABEL_HASH_sha256前12位]形式的令牌例如[ID_NUM_HASH_3f2a9c1b...]。实现细节openmed/interop/hl7v2.pydigest hashlib.sha256( f{rule.hash_salt}|{label}|{value}.encode(utf-8) ).hexdigest() return f[{label}_HASH_{digest[:12]}]同一原始值在同一hash_salt下永远得到同一令牌因此跨消息做实体关联例如同一 MRN 在不同消息中对应同一令牌成为可能通过HL7FieldRule(hash_salt...)可以为每条消息引入额外盐值增加抗字典攻击能力。哈希处理会遍历重复组、组件、子组件的每一层叶子但保留 HL7 分隔符本身因此MRN111^^^GOOD HOSPITAL^MR脱敏后仍然保持三组件的结构。surrogate —— 标签感知替身值调用Anonymizeropenmed/core/anonymizer.py为叶子值生成看起来真实但完全是假的替身同时保留重复组、组件、子组件的布局。替身生成支持lang、locale并可通过seed固定结果以保证流水线可复现openmed/interop/hl7v2.py 用consistentTrue实例化Anonymizer。对于 XPN 风格的姓名复合字段如PID-5、NK1-2、GT1-3、IN1-16默认映射通过component_labels在组件级施加减标签{1: LAST_NAME, 2: FIRST_NAME, 3: MIDDLE_NAME}让姓、名、中间名分别生成符合其语义的替身。date-shift —— 消息内一致的日期偏移每个配置了 date-shift 的日期按同一偏移平移保持消息内部日期间隔不变。实现识别两类格式[openmed/interop/hl7v2.py](https://link.gitcode.com/i/8887f33621da30dba2000dd8b345044c#L29-L34, L626-L658)HL7 原生日期时间YYYYMMDD[HHMMSS[.fff]][/-HHMM]如19800101、202401011200000800ISO 风格日期YYYY-MM-DD或YYYY/MM/DD。合法日期平移后保持原格式与时间部分无法解析的日期返回空字符串宁可清空也不保留可能泄漏的日期。测试 tests/unit/interop/test_hl7v2.py 验证了PID-7出生日期与IN1-18投保人出生日期在date_shift_days45时都从19800101变为19800215偏移一致。该测试还同时验证了19800101原始值在整条消息中不再出现。自由文本字段接入 OpenMed PII 管道两条默认规则处理自由文本OBX-5当且仅当OBX-2值类型为TX或FT时type_field2, allowed_type_values(FT, TX)即DEFAULT_NOTE_VALUE_TYPESNTE-3注释文本无条件。自由文本走redact_text动作调用deidentifier回调默认是 openmed/core/pii.py 的deidentify强制传入methodmask与lang并把调用方提供的deidentify_kwargs与规则的rule.deidentify_kwargs合并后者优先级更高。回调的返回值可以是纯字符串也可以是带deidentified_text属性的对象或 mapping否则抛TypeErroropenmed/interop/hl7v2.py。文本去标识走的是 OpenMed 完整 PII 检测链路支持 mask / remove / replace / hash / shift_dates / format_preserve 等方法默认methodmask置信度阈值默认 0.7 以保障安全。测试 tests/unit/interop/test_hl7v2.py 展示了完整效果OBX-5的自由文本Patient Jane Roe called from 555-0101 about MRN12345.被脱敏为Patient [PERSON] called from [PHONE] about [ID_NUM].而OBX-2NM数值的OBX-5如7.1保持原样——正是allowed_type_values类型约束在起作用。另一个测试tests/unit/interop/test_hl7v2.py验证了lang参数会原样透传给每个文本脱敏调用。离线测试技巧生产环境依赖模型推理但在单元测试/离线校验时可以传入一个确定性 callable 代替真实deidentify例如测试中用SimpleNamespace(deidentified_text...)包装结果。这让你无需加载模型即可回归验证字段映射是否正确。扩展规则覆盖 Z 段与自定义字段通过field_map传入替换映射键可以是元组或字符串两种形式二者等价from openmed.interop.hl7v2 import DEFAULT_FIELD_MAP, HL7FieldRule, redact_hl7v2 field_map { **DEFAULT_FIELD_MAP, ZNT-2: HL7FieldRule(redact_text), (ZID, 4): HL7FieldRule(hash, labelID_NUM), } redacted redact_hl7v2(message_text, field_mapfield_map)键规范化逻辑openmed/interop/hl7v2.py字符串按-分割段名统一大写、位置转 int非法键抛ValueError。值是HL7FieldRule或与其等价的 mapping也允许规则列表同一字段可链式施加多条规则规则对象在构造时会校验动作名并规范化date_shift→date-shift、redact-text→redact_text等别名写法openmed/interop/hl7v2.py。HL7FieldRule的完整字段字段默认值说明action必填clear/hash/surrogate/date-shift/redact_textlabelID_NUM替身/哈希的实体标签component_labels{}组件级标签覆盖1-based 组件位置 → 标签type_fieldNone条件触发读取该字段位置的值类型allowed_type_values()与type_field配合值类型大写在集合内才生效hash_salt哈希盐值deidentify_kwargs{}透传给文本去标识器的额外参数_rule_applies的实现openmed/interop/hl7v2.py显示当type_field的取值类型组件分隔符前的首组件大写命中allowed_type_values集合时规则生效两者任一为空则规则无条件生效。这正是OBX-5只在TX/FT时脱敏的机制你也可以用它实现ZID-4只在某状态码下 hash之类的条件规则。脱敏后的下游使用HL7 v2 叙述提取脱敏后的消息仍保持 HL7 结构可直接回写 HL7 消费方。若下游要做临床 NLP 或人工审阅OpenMed 还提供配套的叙述提取器实现见 openmed/interop/hl7v2_narrative.py它复用本文所述的同一套解析器与脱敏器extract_hl7v2_narrative内部先调用redact_hl7v2且刻意用 identity 函数保持自由文本原样待完整叙述渲染完成后统一再过一遍 PII 管道见 openmed/interop/hl7v2_narrative.py将 ADT/ORU/ORM 消息渲染为可读文本并保留指向源字段的精确偏移from openmed.interop.hl7v2_narrative import extract_hl7v2_narrative result extract_hl7v2_narrative(synthetic_oru.hl7) print(result.text) for span in result.spans_for(OBX, 5): print(span.source.path, result.text_for(span))flat 模式默认紧凑的句子式文本适合下游 NLPsectioned 模式稳定的 Markdown 分节输出Message/Patient/Encounter/Orders/Observations/Notes适合人工审阅界面空节自动省略两种模式都保持消息内顺序并返回节级偏移。每个字段 span 都带有HL7V2FieldSourcesegment三段名、segment_index消息内零基位置、segment_occurrence同名段的 1-based 出现次数、field_position1-based 字段号并提供OBX[2]-5这种紧凑路径openmed/interop/hl7v2_narrative.py。provenance_at(offset)可从叙述文本中任意字符位置反查来源字段。叙述渲染覆盖 MSH、EVN、PID、PV1、ORC、OBR、OBX、NTE 的常见上下文docs/interop/hl7v2-narrative-extraction.md未知段被渲染器忽略但仍可被底层解析器与自定义字段映射覆盖。常见问题与边界非 HL7 输入消息必须以MSH开头且MSH-2恰好 4 个编码字符否则抛ValueError空消息抛ValueError(empty HL7 v2 message)。字段位置从 1 开始MSH-1由分隔符推导、不可修改openmed/interop/hl7v2.py。未配置的字段不动默认映射之外的任何字段包括PID-8管理性别这类非敏感字段原样保留。这不是合规验证器文档明确声明它不校验完整 conformance profile也不调用网络服务若你的部署需要 MLLP 传输或完整消息验证应在其外层接入对应的传输与校验组件。确定性权衡hash与surrogate在固定seed下确定可复现date-shift在未显式指定时随机——如需整条流水线完全确定请显式传入date_shift_days与seed。整体来看openmed.interop.hl7v2是一个小而完整的本地化方案结构化字段四类动作 自由文本 PII 管道 精确结构保真加上叙述提取器即可构成从 HL7 管道消息到可安全外发的脱敏文本/结构化结果的完整闭环。【免费下载链接】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），仅供参考