OpenMed 非洲医疗部署实战指南:离线小模型、POPIA/NDPA 合规与 OpenMRS/DHIS2 集成

原创2026-09-17 19:14:061,886 阅读
文章标签:医疗健康NLP数据脱敏人工智能隐私合规AI 技能MCP 服务本地部署

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)架构天然契合这些约束——模型推理完全在设备或院内服务器上完成,患者数据不离开机构网络。本文的部署策略围绕三条主线展开:

  1. 体积优先:选择最小的可用推理模型,控制下载量与峰值内存;
  2. 离线优先:在联网机器上准备一次,通过可校验的方式分发到断网环境;
  3. 合规留痕:把法律要求映射为技术政策档案,并为每次脱敏产出可审查的审计报告。

低带宽快速启动:选择 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"的合规要求。

上线前必须记录的内容

  1. 每条数据流的目的与合法处理依据;
  2. 保留、掩蔽、替换或删除的数据字段,以及各自存在的必要性;
  3. 是否存在假名映射、谁能访问、存放位置;
  4. 数据驻留位置、处理者/子处理者、跨境传输与备份位置;
  5. 保留与删除计划、访问审查、事件响应与数据主体请求处理流程;
  6. 一份覆盖当地姓名、电话格式、地址、机构标识符、国民身份证号与语言特征的合成泄漏测试集。

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:uuid fullUrl,同一输入多次运行产生字节级相同的输出(这对校验和验证与审计复现至关重要);
  • 所有指向 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 便能在电力与带宽受限、数据保护要求严格的非洲站点上,以完全本地的方式稳定运行。

登录后查看全文
openmed