OpenMed 非洲参考演示的合成 Fixture 边界:用全虚构数据构建 OpenMRS 到 DHIS2 的离线隐私验证

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

OpenMed 非洲参考演示的合成 Fixture 边界:用全虚构数据构建 OpenMRS 到 DHIS2 的离线隐私验证

这篇指南以 OpenMed 仓库中 examples/africa-openmrs-dhis2 参考演示的 fixture 边界说明文档为主体,解读其核心设计:一条完全虚构、确定性生成、只服务于设施侧测试边界的合成数据链路。读完本文,你能理解该 fixture 生成器的每个参数与产出物、loopback 回放服务器的实现方式,以及它如何支撑"数据不出院"的脱敏验证流程,并掌握在本地复现、检验该边界的完整方法。

1. Fixture 边界要解决的问题

边界说明文档开篇即定义了这条演示链路的安全姿态:

The fixture demo generates a deterministic, fictional OpenMRS FHIR2 recording in memory and serves it only on an ephemeral 127.0.0.1 port. The committed organisation-unit snapshot represents one fictional country, province, district, and three facilities. No Java service, internet access, credentials, or real patient corpus is used.

翻译成设计约束,就是四条硬性边界:

  1. 确定性虚构:数据在内存中生成,同一个种子永远产出同一份"录像"(recording),便于逐字节比对与回归测试;
  2. 仅回环:HTTP 服务只绑定 127.0.0.1 的临时端口(ephemeral port),任何外部主机都无法访问;
  3. 虚构地理层级:提交的机构单位快照只包含一个虚构国家、一个省、一个区、三家具虚构设施,不指向任何真实行政单元;
  4. 零外部依赖:不需要 Java 服务(真实 OpenMRS)、不需要互联网、不需要凭据、不需要任何真实患者语料。

这个边界存在的意义,是让演示能"证明隐私闸门有效":数据生成器故意植入必须在设施边界被剥离的识别信息(姓名、手机号、国号 ID、GPS),如果这些值出现在任何出域工件里,闸门就应该失败。整个设计的可信度依赖"输入是已知全集合的虚构数据"这一前提。

2. 重新生成一份可检视的录像

文档给出的核心操作是从仓库根目录运行生成器:

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

对照 synthetic_data.py 的 CLI 定义(L337-L346),三个参数的语义如下:

参数 默认值 说明
--seed 875(DEFAULT_SEED) 随机种子,决定诊断抽取与 GPS 抖动等所有随机量
--patient-count 50(DEFAULT_PATIENT_COUNT) 虚构患者数量,必须大于 0,否则抛 ValueError
--output 无(必填) 输出 JSON 路径,父目录不存在时会自动 mkdir -p

main()(L349-L364)将 dataset.recording() 以 indent=2, sort_keys=True, ensure_ascii=False 序列化落盘——键排序 + 固定缩进是"同一 seed 两次运行字节相同"这一可复现性保证的一半,另一半来自 run_demo.py 中统一的 _canonical_json 写盘函数(L419-L428)。

输出录像的顶层结构由 recording()(L139-L148)定义:

{
  "fixture": "fictional-mtoni-district",
  "seed": 875,
  "districtOrgUnit": "ouDistrictMtoni",
  "fhir2": { "Patient": [...], "Encounter": [...], "Observation": [...] },
  "rest":  { "patient": [...], "encounter": [...], "obs": [...] }
}

注意它同时生成 FHIR2(R4)资源与 OpenMRS 传统 REST 资源两套"录像"。这不是冗余:演示流程要分别走 pull_fhir 与 pull_rest 两条适配器路径,两套数据同源同种子,保证两条路径面对的是同一批虚构患者。

3. 合成数据长什么样:故意留出的 PHI

生成器(generate_dataset,L151-L197)构建一个虚构区"fictional-mtoni-district",固定包含三家具名设施:

  • ouFacilityKijani — Kijani Health Centre(-0.31230, 32.58120)
  • ouFacilityMawingu — Mawingu District Clinic(-0.28710, 32.60640)
  • ouFacilityTumaini — Tumaini Community Hospital(-0.33580, 32.62510)

患者按 offset % 3 轮流分配到三家具设施,每位患者携带一组故意可识别的字段:

  • 姓名:从 12 个固定名池(Amina、Amara、Chidi……)取名字,姓氏统一为 Fiction{index:03d},如 Fiction042;
  • MSISDN 手机号:+256 700 {index//1000:03d} {index%1000:03d};
  • 国家 ID:CF-{seed:04d}-{index:06d};
  • GPS 坐标:在所属设施坐标基础上做 ±0.008 度的确定性抖动;
  • 诊断:在三条 ICD-11 MMS 编码(1A00 霍乱、5A11 2 型糖尿病、BA00 原发性高血压,来自 http://id.who.int/icd/release/11/mms 命名空间)中按种子随机抽取;
  • 就诊日期:从 2026-01-05 起逐日递增。

最关键的细节在 Observation 资源里(L277-L280):valueString 会把姓名、电话、国家 ID、GPS 拼进一条自由文本。也就是说 PHI 不只出现在结构化的 name/telecom/extension 字段,还散落在自由文本里——脱敏器必须处理"结构字段 + 自由文本"两种载体,这比只打平结构字段的演示更能检验隐私策略的召回能力。REST 侧同样如此:encounterNotes 与 obs.comment 里都嵌了联系方式与坐标(L312-L333)。

泄漏闸门用的 PHI 映射表

SyntheticDataset.phi_mapping()(L95-L109)为每位患者产出一组"替换令牌 → 原始值"映射:

[FULL_NAME_004]   → "Imani Fiction004"
[GIVEN_NAME_004]  → "Imani"
[FAMILY_NAME_004] → "Fiction004"
[MSISDN_004]      → "+256 700 000 004"
[NATIONAL_ID_004] → "CF-0875-000004"
[GPS_004]         → "-0.30432, 32.58711"
[LATITUDE_004]    / [LONGITUDE_004] → 拆分后的单项坐标

每个患者 8 个令牌,50 名患者即 400 个可检查的"必须被剥离"的值。这份映射是后续所有 assert_redacted 扫描(见第 6 节)的判据:只要任何一个原始值出现在出域工件里,验证就失败。

4. 只在回环上服务的内存回放服务器

演示并不启动真实 OpenMRS。fixture_server.py 用一个 ThreadingHTTPServer 把录像"回放"成 HTTP 服务,关键实现在 openmrs_fixture_server 上下文管理器(L18-L47):

server = ThreadingHTTPServer(("127.0.0.1", 0), handler)  # 端口 0 = 临时端口
...
yield f"http://{host}:{port}/openmrs"
finally:
    server.shutdown()
    server.server_close()
    thread.join(timeout=5)

port=0 让操作系统分配一个空闲端口,进程间不会冲突;finally 保证退出上下文时服务器一定被关停。它暴露两类端点,前缀与真实 OpenMRS 对齐(L59-L78):

  • FHIR2 搜索:/openmrs/ws/fhir2/R4/{Patient|Encounter|Observation}。返回标准 searchset Bundle,支持 _count/page 分页参数,未翻完时附加 next 链接(L81-L125)。未登记的资源类型返回 404 unsupported_resource。
  • 传统 REST 搜索:/openmrs/ws/rest/v1/{patient|encounter|obs}。返回 {results, startIndex} 结构,支持 limit/startIndex 分页(L127-L144)。

分页不是摆设:run_demo.py 的 --page-size 参数(默认 17,L93-L98)专门用来迫使客户端跨多页抓取 50 条记录,验证 OpenMRS 适配器的分页逻辑——而测试还证明改 page size 不影响产物字节(见第 6 节)。

5. 已提交的机构单位快照

organisation_units.json 就是文档所说的"一个虚构国家、省、区 + 三家具设施":

{
  "organisationUnits": [
    { "id": "ouCountryFiction", "level": 1 },
    { "id": "ouProvinceLake",   "level": 2, "parent": { "id": "ouCountryFiction" } },
    { "id": "ouDistrictMtoni",  "level": 3, "parent": { "id": "ouProvinceLake" } },
    { "id": "ouFacilityKijani", "level": 4, "parent": { "id": "ouDistrictMtoni" } },
    { "id": "ouFacilityMawingu","level": 4, "parent": { "id": "ouDistrictMtoni" } },
    { "id": "ouFacilityTumaini","level": 4, "parent": { "id": "ouDistrictMtoni" } }
  ]
}

这份快照是 DHIS2 导出器的"地理策略依据":导出时按 generalization_level=3 向上卷到区县级,因此只有 ouDistrictMtoni 允许出现在最终 payload 中,三个 level-4 设施 UID 属于必须在出域前消失的值。区县 UID 常量 ouDistrictMtoni 在生成器中定义为 DISTRICT_ORG_UNIT(L20),与快照文件互相咬合。

6. 边界如何在完整演示中被强制执行

run_demo.py 把 fixture 边界串成完整流水线:

  1. generate_dataset 生成数据集,ExactSyntheticRedactor(L50-L68)拿到 phi_mapping(),按"先长后短"的顺序做全量字符串替换——生产部署中它会换成经过评审的 OpenMed 隐私策略;
  2. openmrs_fixture_server 在临时回环端口上启动,OpenMRSClient 先拉取未脱敏原始资源(存为 01-raw-openmrs.json,留在设施边界内),再经 OpenMRSAdapter 拉取脱敏后的 FHIR2 与 REST 记录;
  3. 每条脱敏记录先过 assert_redacted,再校验 FHIR transaction Bundle 形状(150 条 entry、全部 POST);
  4. export_dhis2 以 DHIS2ExportConfig(generalization_level=3, small_cell_threshold=5, date_mode="coarsen", period_granularity="month") 生成聚合与 Tracker payload(L170-L175);
  5. _assert_district_only(L392-L402)做"只许区县级"终检:任何设施 UID、"geometry"、"latitude"、"longitude" 残留,或 orgUnit 取值不等于 {ouDistrictMtoni},都直接 raise ValueError 使演示失败。

输出的 7 个阶段工件中,除 01-raw-openmrs.json 外全部再扫描一遍 phi_mapping,连控制台输出都要过 assert_redacted(L234-L247)——这就是文档标题"Synthetic fixture boundary"的完整含义:原始合成 PHI 只存在于第 1 阶段与设施侧内存里,其余一切产物都被证明不含任何种子值。

测试套件 test_africa_reference_demo.py 把这些约束固化为可回归的检查:从 01-raw-openmrs.json 反向提取 ≥250 个种子识别值(L119);断言 orgUnit 集合只含区县 UID、序列化文本中无 geometry/latitude/longitude(L147-L157);并用 page_size=7 与 page_size=19 跑两次全流程,断言所有工件逐字节相同(L167-L175),验证"确定性"承诺。

7. 边界红线:不要把录像带出院

回到 fixtures/README.md 的收尾警告,它划定了两条使用红线:

  • 生成的录像故意包含合成 PHI(真实格式的姓名、MSISDN、国家 ID、GPS),"must remain inside the facility-side test boundary"——它只能停留在设施侧测试边界内,作为隐私闸门的输入对照;
  • 它不是 DHIS2 导出工件——真正的 DHIS2 交付物是经过区县级泛化与 PHI 闸门后的 04-dhis2-aggregate.json / 05-dhis2-tracker.json,而不是这份原始录像。

配套文档 africa-reference-deployment.md 进一步强调:01-raw-openmrs.json 的存在目的仅是让实施者检视"隐私边界之前的输入",严禁以真实患者数据替换,严禁把原始阶段移入国家报告系统;并给出面向 KenyaEMR/UgandaEMR 风格部署的落地映射(确认 FHIR2 模块、在设施机运行适配器、用评审过的隐私策略替换精确合成脱敏器、映射真实的 ICD-11/DHIS2 元数据)。

8. 可选:live 容器剖析(不属于 fixture 路径)

docker-compose.yml 携带一个 live 剖析,提供 demo 级的 OpenMRS Reference Application(3.7.1)与 DHIS2 Core(2.43.0.1)容器,用于隔离实验室里做真实 API 往返测试:

docker compose \
  -f examples/africa-openmrs-dhis2/docker-compose.yml \
  --profile live \
  up -d

注意三条限制,均有测试背书(test_optional_live_compose_profile_is_explicit_and_loopback_only,L194-L204):所有服务必须显式声明 profiles: [live](CI 永不启动该剖析);所有端口必须绑定 127.0.0.1:;容器使用本地示例口令,是 demo 级配置而非加固部署,且该命令不向任何服务上传任何内容。

9. 小结

examples/africa-openmrs-dhis2/fixtures/README.md 用不到二十行文字定义了一个可审计的隐私工程实践:用可复现的虚构数据、回环内存服务、已知全集合的 PHI 令牌表,把"脱敏是否有效"从经验问题变成可断言的测试问题。生成器、回放服务器、区县快照、演示流水线与回归测试五者共同构成这条边界——任何一环(种子、page size、网络可达性)变化都能被字节级比对或闸门断言立刻发现。如果你的场景中也需要在数据离域前证明隐私策略的召回能力,这套"合成录像 + 已知 PHI 全集 + 只许泛化值出域"的模式是值得直接借鉴的工程范式。

登录后查看全文
openmed