OpenMed 非洲医疗部署实战指南:离线小模型、POPIA/NDPA 合规与 OpenMRS/DHIS2 集成
OpenMed 非洲医疗部署实战指南:离线小模型、POPIA/NDPA 合规与 OpenMRS/DHIS2 集成
导读
本文面向把 OpenMed 集成进非洲临床与公共卫生系统的工程团队,系统讲解一条"一次准备、全程离线"的小模型落地路径:从 33M 参数解剖 NER 模型的选型与预取、wheelhouse 离线分发、断点续传与校验和验证,到 local_only 完全断网运行;同时结合 OpenMed 政策档案与源码实现,说明如何映射 POPIA(南非)与 NDPA(尼日利亚)合规意图,并通过 to_bundle() 与站点自有的 FHIR→DHIS2 映射,完成 OpenMRS 与 DHIS2 两类主流系统的对接。读完本文,你将掌握在连接性、电力、硬件与数据保护要求差异巨大的站点上,端到端落地 OpenMed 的完整技术方案与生产检查清单。
安全红线:文中所有命令与代码均使用合成临床文本。切勿将真实患者数据粘贴到公开 issue、托管 notebook、翻译服务或共享终端日志中。
场景与设计原则
非洲各医疗站点的差异极大:有的站点网络连接脆弱,有的站点电力和硬件资源受限,还有的站点受严格的数据保护法管辖。OpenMed 的本地优先(local-first)架构天然契合这些约束——模型推理完全在设备或院内服务器上完成,患者数据不离开机构网络。本文的部署策略围绕三条主线展开:
- 体积优先:选择最小的可用推理模型,控制下载量与峰值内存;
- 离线优先:在联网机器上准备一次,通过可校验的方式分发到断网环境;
- 合规留痕:把法律要求映射为技术政策档案,并为每次脱敏产出可审查的审计报告。
低带宽快速启动:选择 33M 解剖模型
示例使用 OpenMed/OpenMed-NER-AnatomyDetect-ElectraMed-33M,这是一个 33M 参数的英文解剖学 token 分类模型(token classification)。其必需的模型与 tokenizer 产物合计约 67 MB,相比 registry 中 109M 或 434M 的条目,是首轮下载的更优选择。注意:该模型识别英文文本中的解剖学实体;仓库中该模型附带的斯瓦希里语 README 属于产品与开发者翻译,不意味着该英文 checkpoint 是斯瓦希里语临床 NER 模型——如需本地语言覆盖,应另行评估多语言模型路径(参见 docs/languages.md)。
下载前确认体积:openmed models size
下载前先用命令确认本地 registry 的估算值。该命令默认离线执行,设置 OPENMED_OFFLINE=1 可显式表明意图:
OPENMED_OFFLINE=1 openmed models size \
OpenMed/OpenMed-NER-AnatomyDetect-ElectraMed-33M
表格应报告约 67.9 MB 下载量与 256 MB 峰值 RAM 估算。该命令由 openmed/cli/typer_app.py 中的 models size 子命令实现,底层调用 build_models_size_report()(见 openmed/cli/main.py),输出模型、任务、下载体积(download_mb)、磁盘占用(disk_mb)、峰值内存(peak_ram_mb)与状态列。
常用参数组合:
openmed models size --budget-mb 100:仅列出下载体积不超过 100 MB 的 registry 模型,用于横向比较;openmed models size --format json:输出机器可读的 JSON 报告,便于脚本化决策;--remote:仅在你有可靠网络、且确实需要拉取 Hugging Face Hub 最新元数据时使用(离线场景默认不要加)。
如果没有任何模型满足预算,CLI 会输出 No models fit the 100 MB download budget. 并返回非零退出码——这在 CI 或部署脚本中可当作硬性门禁使用。
联网机器上一次安装
在可联网的机器上,使用 Python 3.11 创建虚拟环境,并保留该环境配置以便在相同操作系统与 CPU 架构的机器上复现:
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "openmed[hf]"
面向多台相同诊所机器的 wheelhouse 分发
当需要批量部署多台相同配置的诊所机器时,先在联网机器上一次下载全部 Python 包到 wheelhouse:
python -m pip download --dest wheelhouse "openmed[hf]"
在离线机器上,用 --no-index --find-links 安装,全程不访问包索引:
python -m pip install --no-index --find-links wheelhouse "openmed[hf]"
⚠️ 注意:wheelhouse 体积可能远超模型本身,因为其中包含 PyTorch 及其平台依赖。必须为每个目标 OS、CPU 架构与 Python 版本分别构建 wheelhouse,不能跨不兼容的机器复制同一份。
可断点续传的模型预取
只下载推理所需的文件。huggingface_hub 的 snapshot_download() 会对已缓存文件续传并校验内容哈希,max_workers=2 可避免压垮脆弱连接:
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="OpenMed/OpenMed-NER-AnatomyDetect-ElectraMed-33M",
local_dir="models/anatomy-33m",
allow_patterns=[
"config.json",
"model.safetensors",
"special_tokens_map.json",
"tokenizer.json",
"tokenizer_config.json",
"vocab.txt",
],
max_workers=2,
)
allow_patterns 白名单只拉取推理必需的最小文件集(跳过训练脚本、onnx 转出物等),进一步压缩传输量。如果连接中途断开,直接重跑同一脚本即可——已完成的文件会被命中缓存,只补传缺失部分。
通过不可靠本地链路传输
对间歇性本地链路,用 rsync 保留部分进度:
rsync --archive --partial --append-verify \
models/anatomy-33m/ clinic-host:/opt/openmed/models/anatomy-33m/
USB 或经批准的加密可移动介质同样适用。
校验和验证
使用前必须验证传输完整性。在联网机器上生成校验清单:
find models/anatomy-33m -type f -print0 \
| sort -z \
| xargs -0 shasum -a 256 > anatomy-33m.sha256
将校验文件随部署记录一起保存;在目标机器上执行 shasum -a 256 -c anatomy-33m.sha256 复核。校验和是供应链完整性的第一道防线,也是生产检查清单的第一项。
完全断网运行
在目标机器上设置本地模式,并让三个环境变量共同声明"禁止任何联网尝试":
export OPENMED_OFFLINE=1
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
随后运行冒烟测试(smoke test):
from openmed import OpenMedConfig, analyze_text
config = OpenMedConfig(device="cpu", local_only=True)
result = analyze_text(
"Tenderness extends from the left kidney to the lower abdomen.",
model_id="./models/anatomy-33m",
config=config,
)
for entity in result.entities:
print(entity.label, entity.text, round(entity.confidence, 3))
关键点:model_id 传入本地路径且 local_only=True 时,任何缺失文件都会在本地直接失败,而不会触发 Hub 下载——这正是断网部署想要的严格行为。务必在断网状态下跑通此冒烟测试,再引入任何临床工作流。
POPIA 与尼日利亚 NDPA 合规指针
法律要点
- 南非 POPIA(Protection of Personal Information Act):将健康信息视为"特殊个人信息"(special personal information),处理门槛更高。应以南非官方发布的法案原文与信息监管机构(Information Regulator)关于处理特殊个人信息的指南为依据。
- 尼日利亚 NDPA(Data Protection Act 2023):将健康状况、基因数据及用于唯一身份识别的生物特征数据定义为"敏感个人数据",由尼日利亚数据保护委员会(NDPC)负责监管与最新指引。
OpenMed 政策档案是技术控制,不是法律认证
必须反复强调:OpenMed 的政策档案(policy profiles)是技术控制手段,不构成法律认证。仓库中没有任何内置档案名为 popia 或 ndpa,选择某个档案本身不等于:确立合法处理依据、满足透明义务、完成数据保护影响评估(DPIA)、授权跨境传输或设定合法保留期限。最终配置与数据流必须由机构内负责的信息官或数据保护官(DPO)审批。
将部署意图映射到现有档案
| 部署意图 | 现有档案 | 检入配置的实际行为 | 上线前需审查 |
|---|---|---|---|
| 最大保守导出或接收方未知 | strict_no_leak |
使用严格阈值、高召回并集、强制安全扫描,并掩蔽直接标识符、准标识符与临床概念 | 效用有意保持较低;核实被掩蔽的临床概念仍满足用途 |
| 提供方边界内授权的护理工作流 | clinical_minimal_redaction |
掩蔽直接标识符,同时保留大量日期、地点、年龄与临床概念 | 安全扫描非强制;需书面说明保留字段的必要性与授权依据 |
| 获批的研究或公共卫生数据集 | research_limited_dataset |
掩蔽直接标识符,保留较多准标识符与临床概念,并要求安全扫描 | 评估再识别风险、小单元风险、链接风险、保留期限、访问控制与发布规则 |
| 健康数据假名化的起点 | gdpr_art9_health |
使用严格阈值,替换直接标识符,掩蔽准标识符与临床概念,并保留可逆映射 | 映射必须单独保护;本档案不构成 POPIA 或 NDPA 法律意见 |
真相来源是 openmed/core/policies/ 目录下的 JSON 档案——审查实际动作,不要只信档案名。仓库还包含
za_popia.json、ng_ndpa.json、ke_dpa.json、eg_pdpl.json等管辖地档案(见 docs/compliance/za-popia-identifier-checklist.md、docs/compliance/ng-ndpa-identifier-checklist.md),以及非洲 Malabo 基线档案africa_malabo_baseline.json,可结合 docs/compliance/africa-malabo-baseline.md 阅读。
逐个查看选中档案的完整动作:
python -m json.tool openmed/core/policies/strict_no_leak.json
python -m json.tool openmed/core/policies/clinical_minimal_redaction.json
python -m json.tool openmed/core/policies/research_limited_dataset.json
python -m json.tool openmed/core/policies/gdpr_art9_health.json
以 strict_no_leak.json 为例(openmed/core/policies/strict_no_leak.json),其顶层字段清晰描述了行为语义:posture: "maximum_recall_no_leak"、arbitration_mode: "high_recall_union"、safety_sweep_mandatory: true、keep_mapping: false,并把 DIRECT_IDENTIFIER、QUASI_IDENTIFIER、SENSITIVE_ATTRIBUTE、CLINICAL_CONCEPT 四类标签全部映射为 mask,同时为上百个细粒度实体标签(PERSON、PHONE、DATE、ID_NUM、ANATOMY、MEDICATION……)逐一指定动作——这就是"严格阈值 + 高召回并集 + 强制安全扫描 + 全量掩蔽"的落地点。
显式应用档案并索取审计报告
显式传入选中的档案,并在需要审查证据时以 audit=True 请求 PHI 安全(不包含原文)的审计报告:
from openmed import deidentify
result = deidentify(
"Synthetic patient Amina Example called +254 700 000 000.",
policy="strict_no_leak",
method="mask",
)
print(result.deidentified_text)
audit_report = deidentify(
"Synthetic patient Amina Example called +254 700 000 000.",
policy="strict_no_leak",
method="mask",
audit=True,
)
print(audit_report.policy)
print(audit_report.export_review_bundle())
deidentify() 的签名见 openmed/core/pii.py:支持 mask、remove、replace、hash、shift_dates、format_preserve、aadhaar_mask 等脱敏方法;policy 参数控制仲裁模式、动作选择、安全扫描强制性与可逆映射;audit=True 时返回确定性的 AuditReport 而非普通 DeidentificationResult。
export_review_bundle()(openmed/core/audit.py)导出不含原文文本的可审查载荷:政策名、文档长度、输入/输出哈希、repro_hash(用于验证审计报告未被篡改),以及每个 span 的起止位置、标签、来源、置信度、阈值、动作、替身值与文本哈希——这正好满足"审计导出不含原始 PHI"的合规要求。
上线前必须记录的内容
- 每条数据流的目的与合法处理依据;
- 保留、掩蔽、替换或删除的数据字段,以及各自存在的必要性;
- 是否存在假名映射、谁能访问、存放位置;
- 数据驻留位置、处理者/子处理者、跨境传输与备份位置;
- 保留与删除计划、访问审查、事件响应与数据主体请求处理流程;
- 一份覆盖当地姓名、电话格式、地址、机构标识符、国民身份证号与语言特征的合成泄漏测试集。
OpenMRS 集成:通过 FHIR 导出器
OpenMRS 在 /openmrs/ws/fhir2/R4 暴露 R4 FHIR API。OpenMed 的 to_bundle() 助手可以构建确定性的事务 Bundle,但它不负责认证、发送数据、合成缺失资源或校验站点 OpenMRS 的 profile。
to_bundle 的源码语义
to_bundle() 定义于 openmed/clinical/exporters/fhir/bundle.py,其行为是:
- 每个资源获得由
doc_id+ 资源索引种子化生成的稳定urn:uuidfullUrl,同一输入多次运行产生字节级相同的输出(这对校验和验证与审计复现至关重要); - 所有指向 Bundle 内资源的字面引用(
"ResourceType/id")被重写为对应fullUrl,避免悬空内部引用; - 对
transaction/batch类型,每个 entry 携带服务器建资源所需的request块(method: POST+ 资源类型 URL); - 纯机械组装:绝不合成缺失资源(被脱敏移除的 Patient 就保持缺席),也不做 profile 校验;
- 重复的
resourceType+id会触发ValueError显式拒绝,防止内部引用图被静默破坏。
组装并提交 Bundle
从已经审批、已经脱敏的资源创建 Bundle。下面示例全部使用合成标识符与不含真实患者数据的 Observation:
import json
from pathlib import Path
from openmed.clinical.exporters.fhir import to_bundle
resources = [
{
"resourceType": "Patient",
"id": "synthetic-patient-001",
"identifier": [
{
"system": "https://example.org/openmed/synthetic-id",
"value": "SYN-001",
}
],
},
{
"resourceType": "Observation",
"id": "synthetic-observation-001",
"status": "final",
"code": {"text": "Synthetic pulse rate"},
"subject": {"reference": "Patient/synthetic-patient-001"},
"valueQuantity": {"value": 72, "unit": "beats/min"},
},
]
bundle = to_bundle(resources, doc_id="synthetic-openmrs-demo")
Path("openmed-fhir-bundle.json").write_text(
json.dumps(bundle, indent=2) + "\n",
encoding="utf-8",
)
针对目标 OpenMRS 部署的 implementation guide 与资源支持情况验证 Bundle 后,把凭据写入环境并 POST 事务 Bundle 到 FHIR 基础端点:
export OPENMRS_BASE="https://openmrs.example.org"
export OPENMRS_USER="integration-user"
read -s OPENMRS_PASSWORD
export OPENMRS_PASSWORD
curl --fail-with-body \
--user "$OPENMRS_USER:$OPENMRS_PASSWORD" \
--header "Content-Type: application/fhir+json" \
--data-binary @openmed-fhir-bundle.json \
"$OPENMRS_BASE/openmrs/ws/fhir2/R4"
生产要求:启用 TLS、使用最小权限服务账号、开启不复制原始 PHI的服务端审计日志,并先在非生产 OpenMRS 实例上完成首轮验证。不要假设每个 OpenMRS 发行版都启用相同的 FHIR 资源或 profile。
仓库中另有完整的 OpenMRS 适配器文档 docs/openmrs-adapter.md 与真实可运行的端到端示例 examples/africa-openmrs-dhis2/(含 synthetic_data.py 合成数据生成、run_demo.py 演示脚本与 docker-compose 环境),可作为本文代码的落地参考。
DHIS2 集成:经过审查的映射
DHIS2 常作为聚合(aggregate)或 Tracker 数据仓库使用,不能把任意 FHIR 事务 Bundle 当作其自有元数据模型的即插即用替代品。正确姿势是:保留 OpenMed FHIR Bundle 作为基于标准(FHIR)的交换产物,再由站点自有一份带版本管理的映射,把 FHIR 编码映射到 DHIS2 的 program、program stage、organisation unit 与 data element UID。
下面这个最小适配器读取上面创建的合成 Observation,准备 DHIS2 Tracker 载荷。必须把每个 UID 替换为目标 DHIS2 实例中经审查的元数据:
import json
import os
from pathlib import Path
bundle = json.loads(Path("openmed-fhir-bundle.json").read_text(encoding="utf-8"))
observation = next(
entry["resource"]
for entry in bundle["entry"]
if entry["resource"]["resourceType"] == "Observation"
)
tracker_payload = {
"events": [
{
"program": os.environ["DHIS2_PROGRAM_UID"],
"programStage": os.environ["DHIS2_PROGRAM_STAGE_UID"],
"orgUnit": os.environ["DHIS2_ORG_UNIT_UID"],
"status": "ACTIVE",
"occurredAt": "2026-07-18T00:00:00.000",
"dataValues": [
{
"dataElement": os.environ["DHIS2_PULSE_DATA_ELEMENT_UID"],
"value": observation["valueQuantity"]["value"],
}
],
}
]
}
Path("dhis2-tracker.json").write_text(
json.dumps(tracker_payload, indent=2) + "\n",
encoding="utf-8",
)
先 VALIDATE 再 COMMIT
当前 DHIS2 Tracker 部署使用 POST /api/tracker;importMode=VALIDATE 只校验映射而不写入事件:
export DHIS2_BASE="https://dhis2.example.org"
export DHIS2_USER="integration-user"
read -s DHIS2_PASSWORD
export DHIS2_PASSWORD
curl --fail-with-body \
--user "$DHIS2_USER:$DHIS2_PASSWORD" \
--header "Content-Type: application/json" \
--data-binary @dhis2-tracker.json \
"$DHIS2_BASE/api/tracker?async=false&importMode=VALIDATE&reportMode=FULL"
只有授权操作员在审查 VALIDATE 成功响应之后,才能以 importMode=COMMIT 重放请求。实践建议:
- 当上报目的不要求个体级数据时,优先聚合值或脱敏值;
- FHIR→DHIS2 映射必须放入版本控制,用合成 fixtures 测试;
- 把 DHIS2 元数据 UID 的任何变更都视为部署变更对待。
面向非洲开发者的社区资源
OpenMed 的落地离不开本地社区的协作与经验沉淀。以下是非洲 NLP 与数据科学领域可加入的社区:泛非非洲语言 NLP 研究与开放协作社区 Masakhane;尼日利亚的数据科学与 AI 培训、研究与社区项目组织 Data Science Nigeria;非洲数据科学竞赛平台 Zindi;每年举办 Indaba 年会并在各地举办 IndabaX 活动的非洲机器学习与 AI 研究社区 Deep Learning Indaba;加纳的 Python/PyData/PyLadies 社区 Python Ghana;以及内罗毕的 PSF 社区小组 Python Nairobi。
向社区求助时,请分享:最小合成复现样例、OpenMed 版本、模型标识符、硬件/操作系统、是否启用了 local-only 模式。切勿分享真实临床记录、密钥、token 或生产 URL。
生产检查清单
上线前逐项确认:
- [ ] 包与模型产物已固定版本、已传输、已通过校验和验证;
- [ ] 目标主机在禁用网络的情况下运行成功;
- [ ] 覆盖本地语言与本地标识符的合成泄漏 fixtures 全部通过;
- [ ] 选定的 OpenMed 政策动作已逐字段审查;
- [ ] POPIA、NDPA 或其他适用法律的审查记录已由责任机构存档;
- [ ] OpenMRS 或 DHIS2 映射已在非生产环境验证;
- [ ] 凭据为最小权限、已轮换、且不在源码控制中;
- [ ] 日志、trace、错误与审计导出不含原始 PHI;
- [ ] 备份、保留、删除、事件响应与恢复流程已经过测试。
这份清单与本文的"体积—离线—合规留痕"三条主线一一对应:前三条守住部署与运行的物理边界,中间三条守住法律与技术控制边界,最后三条守住运维与审计闭环。完成全部勾选后,OpenMed 便能在电力与带宽受限、数据保护要求严格的非洲站点上,以完全本地的方式稳定运行。