OpenMed 临床文本去标识化实战指南基于deidentify()的 PHI/PII 脱敏、掩码与日期偏移【免费下载链接】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本篇技术指南以 OpenMed 的核心隐私入口openmed.deidentify()为主线系统讲解如何在完全本地、无需联网的环境下对临床自由文本进行 PHI/PII 检测与改写覆盖五种脱敏方法掩码、删除、替换、哈希、日期偏移、置信度阈值与内置安全扫描、一致性替代与可逆映射、策略化配置以及与extract_pii、reidentify、审计和 REST/MCP 服务的完整衔接。读完本文你将能够直接在自己的病历脱敏、出院小结匿名化、共享前 PHI 处理管线中落地一套可验证、可审计、可恢复的去标识化方案。一、为什么deidentify()是 OpenMed 隐私工作的核心入口OpenMed 是一个本地优先的医疗 AI 仓库其核心场景之一就是临床 NER 与 HIPAA PII 去标识化。openmed.deidentify检测文本中的 PHI/PII并将其改写为安全内容使文本可以被共享、存储或分析而不会暴露患者信息。它的关键特性是完全在设备端运行只需要一次性的模型下载之后没有任何网络调用、遥测或原始 PHI 离开当前进程。在 OpenMed 的隐私体系中deidentify是最重要的入口点——其他一切能力策略、审计、多语言、日期偏移都叠加在它之上。这一点在 skills/deidentifying-clinical-text/SKILL.md 中开宗明义而其实现位于 openmed/core/pii.py核心函数deidentify定义于第 2599 行。何时使用本技能需要改写文本替换、掩码、删除、哈希或日期偏移标识符时使用deidentify只需要定位 PHI 片段、不改写文本时使用extract_pii见 skills/extracting-pii-entities/SKILL.md需要把已掩码的文本恢复回原始内容时使用reidentify见 skills/reidentifying-text/SKILL.md。二、快速开始一次典型的脱敏调用import openmed note ( Patient John Doe (MRN 1234567) was seen on 2024-03-02 by Dr. Alice Reed. Contact: john.doeexample.com, 617-555-0142. ) result openmed.deidentify( note, methodmask, # mask | remove | replace | hash | shift_dates confidence_threshold0.7, # safety default; raise to reduce false negatives impact policyhipaa_safe_harbor, # optional bundled profile (see below) ) print(result.deidentified_text) # Patient [NAME] (MRN [ID_NUM]) was seen on [DATE] by Dr. [NAME]. ... for e in result.pii_entities: # NEVER log e.text / e.original_text — those are raw PHI. Use offsets label. print(e.canonical_label, e.start, e.end, round(e.confidence, 3))DeidentificationResult字段全解deidentify返回一个DeidentificationResult对象字段名需要精确记忆注意不是.text/.entities字段含义.deidentified_text改写后的 PHI 安全字符串即你要的输出.pii_entitieslist[PIIEntity]——每个实体含start、end、canonical_label、confidence、action、surrogateoriginal_text/text保存的是原始 PHI.mapping红action 后占位符 → 原文 的映射仅当keep_mappingTrue时存在敏感数据.method实际应用的方法.metadata运行元数据模型、策略、计数等从源码 openmed/core/pii.py 可以看到DeidentificationResult还持有original_text、timestamp并且to_dict()会输出num_entities_redacted等字段便于序列化到日志或下游系统但序列化时务必剔除原始文本字段。其内部还实现了_repr_html_在 Jupyter/IPython 中可以直接高亮渲染每个 PII 片段。PIIEntity定义于 openmed/core/pii.py除了文档中提到的字段外还包含redacted_text脱敏后的替换文本、hash_value哈希方法下的稳定摘要、reversible_id可逆伪匿名化句柄、sources检测来源/探测器溯源与threshold实际生效的置信度阈值——这些字段正是审计功能的底层依据。三、五种脱敏方法选型与底层实现method效果可逆适用场景maskJohn Doe→[NAME]配合keep_mappingTrue默认明确表明发生了脱敏remove整个片段被删除否追求最小足迹输出replace类型匹配的假值John Doe→Mark Lee配合keep_mappingTrue保持笔记可读/可解析见 skills/generating-synthetic-surrogates/SKILL.mdhash每个值的稳定哈希可关联重复项否单向不暴露身份的前提下做队列关联shift_dates移动日期保持间隔不适用需要时间结构的研究场景见 skills/shifting-clinical-dates/SKILL.md源码中的方法集合更丰富阅读 openmed/core/pii.py 可见DeidentificationMethod类型别名实际支持七种方法除上述五种外还包括aadhaar_mask把有效的印度 Aadhaar 号码渲染为XXXX XXXX NNNN格式其他实体使用普通占位符format_preserve为结构化标识符生成保持原有形状与分隔符的合成值对不支持的标签进行掩码。hash方法的实现细节在 openmed/core/pii.py对实体文本取sha256摘要并截取前 8 位十六进制作为稳定的hash_value从而让同一患者的多次出现关联到同一哈希值——这正是队列关联而不泄露身份的实现原理。shift_dates的底层实现_shift_dateopenmed/core/pii.py支持临床文档中常见的多种日期格式MM/DD/YYYY美式、DD/MM/YYYY法/意式、DD.MM.YYYY德式、YYYY-MM-DDISO以及带本地化月份名的Month DD, YYYY/DD Month YYYY解析失败时回退为[DATE_SHIFTED]占位符。当传入keep_yearTrue时月份和日期被平移但年份保持不变且会处理闰年 2 月 29 日的边界钳制这在需要保留研究中的年份语义时非常关键。四、标准工作流六步落地脱敏管线选择方法与策略。优先从内置policy档案起步hipaa_safe_harbor、gdpr_pseudonymization、research_limited_dataset等让每个标签的动作由策略自动决定。从源码看deidentify在未显式传入policy时默认使用hipaa_safe_harbor见 openmed/core/pii.py 与第 2145 行的默认值。策略定制见 skills/configuring-privacy-policies/SKILL.md。审慎设置confidence_threshold。默认0.7。脱敏场景要偏向过度脱敏漏掉一个标识符就是泄露而多脱敏一个 token 只是噪音。内置的安全扫描safety sweep对应参数use_safety_sweepTrue会在阈值以下仍然捕获结构化 IDSSN、类 MRN、邮箱。这正是阈值是安全旋钮而非精度旋钮的设计哲学。运行deidentify。通过偏移量与标签而非原始文本检查result.pii_entities确认覆盖情况。需要稳定替代值时传入consistentTrue, seedint使相同输入每次映射到相同的假值可复现管线。源码注释明确seed会隐含consistentTrue且显式的date_shift_days与患者键控偏移仍优先于shift_dates的自动偏移。需要可逆性时传入keep_mappingTrue并将result.mapping存放在安全保险库中——绝不能与脱敏输出放在一起。验证而非假设。使用auditTrue检查残余风险见 skills/auditing-deidentification-runs/SKILL.md并使用 18 项标识符清单核对见 skills/auditing-safe-harbor-checklist/SKILL.md。关于confidence_threshold的补充说明extract_pii与deidentify的默认阈值不同前者默认0.5检测场景追求召回覆盖见 openmed/core/pii.py后者默认0.7脱敏场景偏向安全。如果你的脱敏管线需要更激进的覆盖可以显式降低confidence_threshold——但要记住误报成本低、漏报是事故。五、一致性替代与可逆脱敏# 同一人物的每次出现都映射到同一个假身份可复现 r openmed.deidentify(note, methodreplace, consistentTrue, seed42) # 可逆脱敏映射必须保密且与输出分离存放 r openmed.deidentify(note, methodmask, keep_mappingTrue) restored openmed.reidentify(r.deidentified_text, r.mapping) assert restored notereidentify的实现openmed/core/pii.py有一个值得注意的细节它支持出现次数感知的映射。当多个不同的原始值碰撞到同一个替代表面时_build_reidentification_mapping同文件第 3740 行附近会为每个出现位置生成带序号的私有映射键如occurrence:00000001:[NAME]从而在不改变脱敏文本的前提下保证不同拼写的原文可以分别恢复。这意味着即使多个患者姓名在replace模式下撞车只要映射被妥善保管reidentify依然能精确还原每一个出现位置。需要强调的安全边界keep_mapping的输出与 PHI 同等敏感——映射能重新识别出每一个人必须加密存储、受访问控制并与输出数据物理隔离。六、与 OpenMed 其他能力的衔接仅检测openmed.extract_pii(text)→PredictionResult其.entities给出片段不改写。可先预览覆盖范围再决定是否脱敏。恢复openmed.reidentify(deidentified_text, mapping)—— 要求脱敏时使用keep_mappingTrue且需要恰当的授权。策略通过 skills/configuring-privacy-policies/SKILL.md 选择或定制policy档案。审计deidentify(..., auditTrue)→AuditReport包含偏移量、哈希、探测器溯源与残余风险——绝不含明文。其他调用面同一引擎MCP 工具openmed_deidentify实现于 openmed/mcp/server.py与 REST/库调用共用同一套输入规范化与语言校验网关REST 端点POST /pii/deidentifyopenmed/service/app.py以及流式端点POST /pii/deidentify/stream同文件第 1176 行返回application/x-ndjson流该端点需要pii:write权限见 openmed/service/auth.py注意OpenMed 没有 CLI 脱敏命令如需批处理请走 Python API、REST 或 skills/batch-processing-clinical-text/SKILL.md 中描述的批处理路径。七、边界情况与常见陷阱属性名。是result.deidentified_text与result.pii_entities不是.text/.entities。extract_pii返回PredictionResult其片段在.entities。原始 PHI 永不离开片段对象。PIIEntity.text与.original_text含真实标识符不得打印、记录或缓存。审计与日志只使用偏移量、canonical_label与哈希。阈值是安全旋钮不是精度旋钮。降低它会让脱敏更多在脱敏中误报很廉价漏报才是事故。shift_dates只针对日期可配合keep_year/date_shift_days详见 skills/shifting-clinical-dates/SKILL.md它不会触碰姓名或 ID。源码中非日期实体在shift_dates模式下会退化为掩码占位符。keep_mapping的输出与 PHI 同等敏感。必须加密、受访问控制并与输出分离存放。多语言非英语笔记请传入lang及替代值用的locale参见 skills/deidentifying-multilingual-text/SKILL.md。不要拿英语模型跑其他语言。源码中lang支持en, fr, de, it, es, nl, hi, te, pt, ar, ja, tr等 ISO 639-1 代码且印地语/泰卢固语的混合拉丁-天城文/拉丁-泰卢固文笔记会自动走脚本感知的印度临床路径。脱敏要验证不能假设。发布门槛应基于泄露/残余风险而不是只盯 F1。八、标准与参考HIPAA 去标识化45 CFR 164.514(b)——Safe Harbor 与专家判定HHS 官方指引见 docs/compliance/hipaa-safe-harbor-attestation.md 在仓库内的落地说明。HHS Safe Harbor 18 项标识符指引见 skills/auditing-safe-harbor-checklist/SKILL.md。OpenMed 源码openmed/core/pii.py中的deidentify、extract_pii、reidentify、DeidentificationResult、PIIEntityopenmed/core/pii.py。通过本文的六步工作流、七种方法选型含源码中额外的aadhaar_mask与format_preserve、一致性替代与可逆映射机制你可以在完全离线的环境下构建一条覆盖检测 → 改写 → 审计 → 恢复全链路的临床文本去标识化管线且每一步都有源码级依据可查、可验证。【免费下载链接】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），仅供参考