OpenMed DHIS2 脱敏导出实战:在机构本地完成聚合数据与 Tracker 导入对象的隐私处理

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

OpenMed DHIS2 脱敏导出实战:在机构本地完成聚合数据与 Tracker 导入对象的隐私处理

导读

本文讲解 OpenMed 提供的 DHIS2 导出器(export_dhis2):它可以在数据离开机构之前,在本地内存中完成 DHIS2 聚合数据值集(data value sets)与 Tracker 导入对象(tracked entities / events)的脱敏转换,输出可供 /api/dataValueSets 与 /api/tracker 导入接口直接消费的确定性 JSON。读完本文,你将掌握机构到区县(facility-to-district)的完整导出流程、DHIS2ExportConfig 全部隐私参数的含义与取值、组织单元层级泛化与日期/小单元格处理的底层原理,以及如何通过清单(manifest)在上传前完成人工审查门禁。

设计原则:无传输的本地导出器

OpenMed 的 DHIS2 导出器刻意保持"传输无关"(transport-free):它从本地 JSON 读取载荷(payload)与组织单元层级快照,在内存中应用隐私策略,返回确定性 JSON。上传凭证、HTTP 请求以及 DHIS2 服务端的实时元数据变更,全部留在 OpenMed 之外——导出器不包含 HTTP 客户端,也绝不会主动联系任何 DHIS2 实例(这一点在源码模块 docstring 中明确声明,见 openmed/clinical/exporters/dhis2.py)。

输出格式遵循 DHIS2 的 /api/dataValueSets 与 /api/tracker 导入结构:

  • aggregate.json 是一个本地集合,其 dataValueSets 成员是逐个数据值集请求体;
  • tracker.json 包含 tracker 导入所接受的 trackedEntities 与 events 数组。

项目仓库中的测试夹具给出了这两种载荷的真实形状,可直接作为输入格式参考:tests/unit/clinical/fixtures/dhis2/aggregate_payload.json 与 tests/unit/clinical/fixtures/dhis2/tracker_payload.json。

Facility-to-district 流程

请严格按以下顺序执行:

  1. 导出到受保护工作区:将机构的聚合(aggregate)与 tracker JSON 导出到受保护的本地工作区。
  2. 导出组织单元快照:导出本地 /api/organisationUnits 快照,其中须包含所有被引用的单元及其祖先,且带 id、level、parent.id 三个字段。仓库测试夹具 tests/unit/clinical/fixtures/dhis2/organisation_units.json 展示了一个 country(1)/province(2)/district(3)/facility(4) 四级结构的快照样例。
  3. 运行 export_dhis2:先脱敏自由文本,再移除精确几何信息,将细粒度 orgUnit 引用替换为配置的祖先层级,然后对日期做平移或粗化,最后抑制小规模聚合单元格。
  4. 本地检查:在本地检查端点载荷与不含值的清单。
  5. 再交给上传器:只有通过检查后,才把端点请求体交给机构现有的、已认证的上传程序。

默认目标是 level 3,即 country/province/district/facility 树中的"区县"层级。注意:DHIS2 层级是可配置的,导出前必须确认本地层级编号方式。任何未知单元、断裂的父链接、环(cycle)或缺失目标层级祖先的情况都会失败关闭(fail closed),导出器不会向服务器查询以填补空缺。

组织单元快照的校验逻辑

快照加载与校验由 OrgUnitHierarchy 类完成(源码见 openmed/clinical/exporters/dhis2.py 的 OrgUnitHierarchy.from_snapshot),它执行以下严格检查:

  • 快照必须包含 organisationUnits 数组,且不能为空;
  • 每个单元必须有非空 id(兼容 uid 字段)与正整数 level;
  • 不允许出现重复 id;
  • parent 可以是字符串 id、包含 id/uid 的对象,或 null(顶层单元);
  • 所有父链接必须指向快照内存在的单元,且父层级必须低于子层级(parent.level < unit.level);
  • 沿父链遍历不得成环。

在泛化阶段,generalize() 会沿父链向上查找目标层级祖先;若遇到环、父链断裂或未达到目标层级,均抛出 DHIS2ExportError。测试用例 tests/unit/clinical/test_dhis2_exporter.py 中的 test_snapshot_parent_links_and_levels_are_validated 与 test_unknown_org_unit_fails_closed_without_echoing_the_uid 分别验证了链接校验与"未知单元失败关闭"行为——错误信息只提示"absent from the local snapshot",不会把 UID 回显到错误中,避免敏感标识泄漏。

Python API 使用

以下是官方文档给出的最小可用示例(保持原样,可直接运行):

import json
from pathlib import Path

from openmed.clinical.exporters import DHIS2ExportConfig, export_dhis2

aggregate = json.loads(Path("facility-aggregate.json").read_text())
tracker = json.loads(Path("facility-tracker.json").read_text())

result = export_dhis2(
    aggregate,
    tracker,
    "organisation-units.json",
    config=DHIS2ExportConfig(
        generalization_level=3,
        small_cell_threshold=5,
        date_mode="shift",
        # Omit this for a deterministic per-record non-zero shift.
        date_shift_days=30,
    ),
)

Path("aggregate.json").write_text(result.aggregate_json() + "\n")
Path("tracker.json").write_text(result.tracker_json() + "\n")
Path("manifest.json").write_text(result.manifest_json() + "\n")

export_dhis2 的完整签名(见 openmed/clinical/exporters/dhis2.py 的 export_dhis2 定义)还支持以关键字参数覆盖 config 中的单个策略项:generalization_level、small_cell_threshold、date_mode、date_shift_days、period_granularity。这些便利参数会通过 dataclasses.replace 与 config 合并,未传的项保持 config 默认值。org_unit_snapshot 是必填项,可传 JSON 数据(dict/list)、本地路径字符串、pathlib.Path 或可读流。

结果对象

export_dhis2 返回 DHIS2ExportResult,提供以下确定性序列化接口:

  • aggregate_json() / tracker_json() / manifest_json():分别序列化聚合载荷、tracker 载荷与清单;
  • combined_payload:把三个 DHIS2 集合合并到一个传输中立对象(dataValueSets + trackedEntities + events);
  • to_json():把聚合载荷、清单、tracker 载荷打包为单一 JSON。

所有序列化都经过 _canonical_json——sort_keys=True、紧凑分隔符(,、:)、ensure_ascii=False——保证相同输入与配置产出字节级相同的输出。

输入载荷的归一化

导出器对输入形状非常宽容(见 _normalize_aggregate_payload / _normalize_tracker_payload):

  • 聚合载荷可以是单个 dataValueSet 对象、对象数组,或带 dataValueSets 键的封装(envelope);None 视为空集合;
  • tracker 载荷必须是 JSON 对象且至少含 trackedEntities 或 events 之一;缺失的键会自动补为空数组。

自由文本脱敏与自定义 Redactor

默认情况下,以下敏感字符串字段会经过 OpenMed 的 hipaa_safe_harbor 脱敏流水线:

  • comment、storedBy、completedBy 等文本字段;
  • tracker 属性(attributes[].value)与 data-value value 字符串;
  • note 的 value 字符串。

这些敏感字段中的非字符串值会失败关闭(抛出 DHIS2ExportError),唯一例外是 null——DHIS2 用 null 来表示删除属性和数据值的操作,因此被原样保留。

默认 redactor 的调用方式在源码 _default_text_redactor 中可以看到:调用 openmed.core.pii.deidentify(value, method="mask", lang=..., policy=...),其中 lang 与 policy 均来自配置。测试 test_default_redactor_uses_existing_local_deidentification_pipeline 验证了这一调用约定。

如果你已经持有预热好的模型或更严格的流水线,可以传入自定义 text_redactor 可调用对象。该 callable 必须返回:

  • 一个字符串;或
  • 一个带 deidentified_text 字符串属性的对象(_redacted_text 同时支持 Mapping 与任意对象)。

redactor 抛出的任何异常都会被包装为 DHIS2ExportError,且错误信息不含原始值(raw value omitted)。测试 test_sensitive_text_values_fail_closed_on_non_strings 覆盖了 storedBy、comment、attribute、data_value、note 五种敏感位置的失败关闭行为。

地理、日期与小单元格策略

组织单元泛化(generalization)

  • generalization_level=3 会把每个 level-4 的机构 UID 替换为其 level-3 祖先;已处于 level 3 或以上的引用保持不变。
  • 泛化只发生在 orgUnit 字段;泛化路径、被检查/被泛化的单元数量都会计入清单计数(org_units_examined / org_units_generalized)。
  • 导出完成后,_assert_org_units_permitted 会对整个输出递归扫描,确保任何残留引用都不低于配置层级——双重校验保证"泛化遗漏"不可能溜进最终载荷。

精确地理信息移除

geometry、latitude、longitude 三个字段会被删除而非带入脱敏载荷(源码中 _PRECISE_GEOGRAPHY_FIELDS 常量,见 openmed/clinical/exporters/dhis2.py)。即使字段值为 null 也不保留。每次移除都会计数到 precise_locations_removed 并记录到 transformed_paths。测试 test_synthetic_payloads_round_trip_without_phi_or_fine_geography 断言输出事件中不再含这三个键。

日期策略:shift 与 coarsen

  • date_mode="shift"(默认):使用与表格型准标识符脱敏相同的确定性逐记录偏移派生。不传 date_shift_days 时,偏移由 derive_date_shift_days(见 openmed/multimodal/tabular_csv.py)基于记录的规范 JSON、记录序号与种子材料做 SHA-256 哈希派生,得到 -365 ~ 364 之间的非零偏移(0 被强制为 1);默认种子为 openmed-dhis2-v1(date_shift_seed 可改)。设置 date_shift_days 则复用同一个显式非零偏移。
  • date_mode="coarsen":把事件日期替换为当月或当年第一天(period_granularity="month" 或 "year"),并同步粗化兼容的 DHIS2 报告期。
  • date_mode="none":日期保持不变(适合仅需文本脱敏与地理/层级处理的场景)。

被识别的日期字段集合(_DATE_FIELDS)包括:completedAt、completedDate、createdAt、createdAtClient、dueDate、enrolledAt、enrollmentDate、eventDate、incidentDate、occurredAt、scheduledAt、updatedAt、updatedAtClient。

日期字符串必须是 ISO YYYY-MM-DD(可带 T 时间与 Z/时区后缀)。平移会保留时区后缀;粗化时若原值带 T 时间,则时间部分被归一为 T00:00:00 并保留时区。非 ISO 或非法日期直接失败关闭,且不把原始值回显到错误信息(test_malformed_datetime_suffix_fails_closed_without_echoing_raw_value 验证)。

报告期粗化

在 coarsen 模式下,聚合载荷中的 period 字段支持以下 DHIS2 周期格式(_coarsen_period 实现):

输入格式 示例 month 粒度结果 year 粒度结果
日周期 YYYYMMDD / YYYY-MM-DD 20260717 202607 2026
周周期 YYYYWn 2026W29 转为所在月 202607 2026
月周期 YYYYMM 202607 保持不变 2026
季度/半年 YYYYQn / YYYYSn 2026Q3 保持不变 2026
年 YYYY 2026 保持不变 2026

不支持的周期格式会抛出 DHIS2ExportError。对应行为由测试 test_period_and_event_dates_can_be_coarsened_to_month 验证。

小单元格抑制

  • small_cell_threshold=5 会移除数值在 0 到 4 之间的聚合 data value(判定条件为 0 <= value < threshold 的有限数值)。
  • 只有当已批准的策略明确禁用抑制时,才使用 0 或构造 None 的 config 禁用(DHIS2ExportConfig(small_cell_threshold=None))。
  • 被抑制的单元格直接从输出中删除,并计入 suppressed_aggregate_values、记录到 transformed_paths;布尔值与非数值不会被抑制。

测试 test_none_convenience_threshold_disables_small_cell_suppression 验证了 None 禁用抑制的便利语义。

确定性输出

导出器对所有集合做规范排序,确保相同输入产出相同输出:

  • dataValueSets 按 dataSet, period, orgUnit, completeDate 排序;
  • dataValues 按 dataElement, categoryOptionCombo, attributeOptionCombo 排序;
  • trackedEntities 按 trackedEntity, trackedEntityType, orgUnit 排序;
  • events 按 event, program, programStage, occurredAt, orgUnit 排序;
  • attributes 按 attribute 排序。

测试 test_payload_collections_are_sorted_for_canonical_output 通过故意反转输入数组来验证排序行为。所有抑制与变换路径都会被记录,但从不记录源值。

清单(Manifest)与上传审查门禁

清单(manifest.json)只包含策略设置、计数与结构路径,不包含评论、属性值、用户名、组织单元 UID 或抑制的单元格值。其结构(见 _ManifestState.to_manifest)包括:

  • schema_version、exporter(固定为 "dhis2");
  • generalization_level、small_cell_threshold;
  • date_policy:mode、fixed_shift_days、keep_year、period_granularity;
  • counts:data_value_sets、aggregate_values_input、aggregate_values_output、suppressed_aggregate_values、tracked_entities、events、org_units_examined、org_units_generalized、precise_locations_removed、text_values_examined、text_values_redacted、dates_examined、dates_transformed、periods_examined、periods_coarsened;
  • transformed_paths:有序(sorted)的结构路径列表。

上传前至少应核对:

  • counts.org_units_generalized 与预期的机构引用数一致;
  • counts.precise_locations_removed 与预期的坐标字段数一致;
  • counts.suppressed_aggregate_values 与低容量审查结果一致;
  • transformed_paths 覆盖所有预期的自由文本与日期字段;
  • 序列化后的端点载荷通过机构的 no-PHI 门禁与 DHIS2 元数据校验。

仓库测试通过 assert_redacted(来自 openmed.interop)对整个序列化输出(聚合 + tracker + 清单)断言原始 PHI(姓名、电话、ID)不再出现,见 tests/unit/clinical/test_dhis2_exporter.py。

命令行参考

仓库提供了开箱即用的 CLI 示例脚本 examples/dhis2_district_export.py,与文档给出的命令一致:

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

该脚本支持的参数与 DHIS2ExportConfig 一一对应:--generalization-level(默认 3)、--small-cell-threshold(默认 5)、--date-mode(shift/coarsen/none,默认 shift)、--date-shift-days(可选)、--period-granularity(month/year,默认 month)。

运行后会在 --output-dir 下生成三个本地文件:

  • aggregate.json:脱敏后的聚合端点载荷;
  • tracker.json:脱敏后的 tracker 端点载荷;
  • manifest.json:PHI-free 的变换清单。

该命令只写本地文件,永不执行上传——将载荷交给机构既有上传器之前,必须完成上文清单审查门禁。

登录后查看全文
openmed