OpenMed OpenMRS与DHIS2集成指南：非洲健康数据去标识化落地-平芜编程栈

OpenMed OpenMRS与DHIS2集成指南：非洲健康数据去标识化落地

【免费下载链接】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是一个本地优先的医疗 AI 开源项目，专注临床命名实体识别（Clinical NER）与 HIPAA PII 去标识化，100% 在设备端运行，不经过云端、不让患者数据离开你的网络。本文将带你完成OpenMed 与 OpenMRS、DHIS2 的集成：从机构本地 EMR（OpenMRS）拉取病历，在本地完成去标识化，再导出可审查的 DHIS2 聚合/追踪器载荷，实现非洲健康数据上报的隐私安全落地。🌍

为什么选择本地去标识化？

非洲许多医疗机构的网络不稳定、电力受限，且南非 POPIA、尼日利亚 NDPA 等数据保护法规对健康数据有特殊要求。传统"先把原始病历传到云端再脱敏"的方案风险极高——原始 PHI（受保护健康信息）一旦离网就可能无法召回。

OpenMed 的核心思路是：去标识化发生在数据离网之前。OpenMRS 适配器和 DHIS2 导出器都运行在机构自己的机器上，只有脱敏后的副本才能离开机构网络：

KenyaEMR / UgandaEMR（机构局域网） ↓ REST 或 FHIR2 拉取 OpenMed 部署在机构机器上 拉取 → 去标识化 → 审查清单 ↓ 仅脱敏后的载荷 目标 OpenMRS / FHIR 事务 Bundle / NDJSON / DHIS2 聚合与追踪器

整个流程不缓存原始载荷、不向日志写入原始 PHI，且导入模块时不发起任何网络请求。官方对这条链路的完整说明见 docs/openmrs-adapter.md。

整体数据流：7 个阶段工件

官方提供了一个完全合成、离线、可复现的参考实现（虚构的 Mtoni 区，3 家机构、50 名患者），入口在 examples/africa-openmrs-dhis2/run_demo.py。运行一次会生成 7 个阶段工件，每一道边界都有"无 PHI 门禁"：

阶段	工件	隐私边界
1	`01-raw-openmrs.json`	仅限机构内部的合成原始数据
2	`02-deidentified-fhir-bundle.json`	标准 FHIR 事务 Bundle
3	`03-openmrs-deidentification-manifest.json`	无 PHI 的路径与计数清单
4	`04-dhis2-aggregate.json`	泛化到区级的聚合导入体
5	`05-dhis2-tracker.json`	泛化到区级的追踪器导入体
6	`06-dhis2-export-manifest.json`	无 PHI 的转换摘要
7	`07-demo-manifest.json`	前 6 个文件的稳定哈希

关键安全设计（源码见 run_demo.py 的边界校验）：

🔒区级泛化：任何机构级（level-4）orgUnit都会被替换为区级（level-3）祖先，精确的geometry/latitude/longitude直接删除，区级 UID 以外的一律"失败关闭"（fail closed），数据不出网。
🔒小单元抑制：数值 ≤4 的聚合单元格自动剔除，避免通过小样本反推个人。
🔒确定性输出：相同种子与参数两次运行产出字节级一致的工件，便于审计与回归测试。

本地运行离线参考 Demo（3 步）

无需 Java、Docker、凭据、模型下载或联网。只需在开发环境中安装 OpenMRS 附加依赖：

uv pip install "openmed[openmrs]"

第 1 步：生成合成数据集（可单独预览输入形态）：

python examples/africa-openmrs-dhis2/synthetic_data.py \ --seed 875 --patient-count 50 \ --output /tmp/openmed-africa-recording.json

第 2 步：运行完整流程：

python examples/africa-openmrs-dhis2/run_demo.py \ --output-dir /tmp/openmed-africa-reference \ --seed 875 --patient-count 50

第 3 步：审查 7 个工件。命令行只打印计数，绝不打印载荷内容或种子标识符；合成数据的边界约定见 fixtures/README.md。

⚠️ 注意：01-raw-openmrs.json故意保留了合成姓名、身份证号、GPS 坐标，用于让你检查隐私边界的"输入"。切勿用真实患者数据替换它，也绝不把它传到国家报告系统。

如果你想在隔离实验室里体验真实 API 往返，仓库附带了可选的live容器档案（OpenMRS Reference Application + DHIS2 Core，仅绑定 127.0.0.1），定义在 examples/africa-openmrs-dhis2/docker-compose.yml，官方部署文档见 docs/deploy/africa-reference-deployment.md。

对接真实 KenyaEMR / UgandaEMR：OpenMRS 适配器

生产场景中，适配器同时支持legacy REST API和FHIR2 R4 模块（源码位于 openmed/interop/）。典型流程：

配置连接：在 base URL 中包含 OpenMRS 应用上下文（常见为/openmrs），使用最小权限服务账号，凭据从密钥存储读取；
拉取资源：先拉Patient、Encounter、Observation三类 FHIR2 资源，保证 Bundle 内部引用都有目标；
去标识化：每条结果附带 OperationOutcome 风格的"已变换路径"清单——审计时看路径计数，而不是原文；
干跑写回：先dry_run=True审查 ID 与变换路径，确认无泄漏后再执行真实写入。

完整的环境变量驱动脚本可以直接参考 examples/openmrs_deid_handoff.py，它演示了OPENMRS_BASE_URL、OPENMRS_PATIENT_UUID等配置项的用法，以及"拉取→导出 NDJSON→干跑写回"的最小闭环。

两条实用红线：

不要把患者姓名、电话、身份证号等直接标识符用作 Bundle 的doc_id——它会派生确定性 URL 并残留在运维元数据中；
TLS 校验保持开启，生产环境安装机构 CA，而不是关闭证书校验。

DHIS2 导出：地理、日期与小单元策略

DHIS2 不接收"任意 FHIR Bundle"，因此 OpenMed 的导出器是传输无关的：读取本地 JSON 载荷 + 组织单元层级快照，在内存中应用隐私策略，返回确定性的 JSON（策略实现位于 openmed/clinical/，API 文档见 docs/dhis2-export.md）。

导出前必须按顺序完成 5 步：

将机构聚合/追踪器 JSON 导出到受保护的本地工作区；
导出/api/organisationUnits本地快照（包含id、level、parent.id）；
运行export_dhis2：自由文本先经 HIPAA Safe Harbor 管线脱敏、精确地理删除、机构 UID 泛化为区级祖先、日期偏移或粗化、小单元抑制；
本地审查端点载荷与"无值"清单；
之后才把端点载荷交给机构既有的鉴权上传工具。

命令行参考（只写本地文件，绝不上传）：

python examples/dhis2_district_export.py \ --aggregate facility-aggregate.json \ --tracker facility-tracker.json \ --org-units organisation-units.json \ --output-dir deidentified-dhis2

可调节的核心隐私旋钮：

配置项	作用	推荐值
`generalization_level`	机构 UID 泛化到的层级（默认 3 = 区级）	先确认本地层级编号
`small_cell_threshold`	低于该值的聚合单元格被抑制	`5`
`date_mode`	`shift`（确定性偏移）或`coarsen`（粗化到月/年首日）	按数据用途选择
`period_granularity`	报告周期粗化粒度	`month`或`year`

清单（manifest）只含策略设置、计数与结构路径，不包含注释、属性值、用户名、组织 UID 或被抑制的单元值——这正是审计审查的证据来源。

合规映射：从技术控制到法律审查

OpenMed 的策略档位是技术控制，不是法律认证。针对非洲部署，官方给出了意图→策略映射（详见 docs/africa-onboarding.md）：

部署意图	策略档位	行为要点
最保守的出口/接收方未知	`strict_no_leak`	直接标识符+准标识符+临床概念全部遮罩
机构内授权诊疗流程	`clinical_minimal_redaction`	遮罩直接标识符，保留多数日期/地点/临床概念
已批准的研究/公卫数据集	`research_limited_dataset`	遮罩直接标识符，需小单元与再识别风险评估
健康数据假名化起点	`gdpr_art9_health`	可逆映射，映射表必须独立受保护

策略的真实定义在 openmed/core/policies/ 下的 JSON 中，上线前务必逐字段审查动作，而不是只看档位名。配套的国家级检查清单（如 ke-dpa-identifier-checklist.md）可作为字段级复核的起点。

设施端硬件与上线清单 📋

官方建议的机构边缘起点（试点基线，非生产保证）：

独立 OpenMed 边缘节点：4 核现代 CPU、8 GB 内存、加密 SSD；
EMR 与边缘节点合并部署：8 核、16 GB、加密 SSD；
电力与网络：UPS、测试过的关机流程、局域网运行、出站传输排队——保证断电或 WAN 中断时去标识化仍然可用。

上线前逐项确认：

包与模型工件已锁定、传输并校验哈希，断网目标机能成功运行；
本地语言与本地标识符格式的合成泄漏测试集通过（含姓名、电话格式、地址、机构标识符、身份证号）；
选定的策略动作已逐字段审查，POPIA/NDPA 等法律审查已记录；
OpenMRS / DHIS2 映射在非生产环境验证过，凭据最小权限且不进源码库；
日志、追踪、错误与审计导出中确认无原始 PHI。

小结

OpenMed 把"去标识化"从云端后置改成了设施边缘的前置门禁：OpenMRS 适配器负责拉取与写回，DHIS2 导出器负责地理泛化与小单元抑制，中间每一道边界都有无 PHI 清单与失败关闭机制。从离线参考 Demo 到真实 KenyaEMR/UgandaEMR 接入，整条链路都可以先在本地、用合成数据完整演练一遍，再逐步走向生产。🚀

延伸阅读：