FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

HL7 给出 v2 到 FHIR 的映射表,转换代码得自己写

用约 40 行 Python 把一条 ADT 示例消息转成合法的 Patient 资源,并避开新手常踩的 R4 与 R5 陷阱。

分享微博

要点速览

  • v2-to-FHIR 映射表只说明哪个字段对应哪里,转换逻辑要自己写。
  • python-hl7 支持按规范中从 1 开始的编号访问字段,代码读起来和文档一致。
  • v2-to-FHIR IG 基于 R4,而 fhir.resources 默认是 R5,因此要从 R4B 分支导入。
一张四行表格,展示 PID 段如何映射到 Patient。PID-3 对应 identifier,自己编写的逻辑取 ^ 之前的 123456;PID-5 对应 name,逻辑按 ^ 拆分姓和名;PID-7 对应 birthDate,把 19850412 转成 1985-04-12;PID-8 对应 gender,把 M 转成 male。“自己编写的逻辑”一列被高亮。注:IG 基于 FHIR R4,而非 R5。
v2-to-FHIR 映射表只说明 PID 的哪个字段对应 Patient 的哪个元素,把每个值转成 FHIR 数据的代码,必须自己写。

HL7 关于把 v2 消息转换为 FHIR 的官方指南写得很直白:它描述的是哪个字段对应哪个元素,而不是如何完成转换。它告诉你 PID-8 等同于 gender,但里面没有一行代码负责把字符串 M 变成 male。这部分要自己写。

如果你是医疗项目上的前线部署工程师(FDE),源系统发送 v2 消息,而你的产品读取 FHIR,那么中间这层转换总得有人来写。能写出这层代码、并讲清每个字段去向的人,就是数据一出偏差、客户集成团队第一个找的人。

本指南在一台笔记本上走完整个流程:解析一条 ADT 示例消息,读取 PID 段,按官方映射表转成 Patient 资源,再校验结果。代码大约 40 行。

需要准备什么?

Python 3 和三个库。python-hl7 是轻量库,可把 HL7 v2.x 消息解析为 Python 对象。hl7apy 理解 HL7 的 schema,需要交叉核对时很有用。fhir.resources 基于 Pydantic v2 构建 FHIR 资源。

python -m venv .venv && source .venv/bin/activate
pip install hl7 hl7apy fhir.resources

同时打开 HL7 v2-to-FHIR IG 的两个页面:ADT_A01 消息到 Bundle 的映射,以及 PID 段到 Patient 的映射。

第 1 步:编写一条示例消息

下面这条消息是为本教程构造的,不是真实数据。

MSG = "\r".join([
    "MSH|^~\\&|LAB|HOSP_A|EHR|HOSP_A|202611190830||ADT^A01|MSG0001|P|2.5",
    "PID|1||123456^^^HOSP_A^MR||NGUYEN^AN^VAN||19850412|M",
])

检查: 数一数 PID 行中的 |。第 3 个字段是 123456^^^HOSP_A^MR,第 5 个是姓名,第 7 个是出生日期,第 8 个是 M。数错一位,后面每一步都会出错,而且不会报错。

第 2 步:解析消息,按规范编号读取字段

对消息字符串调用 hl7.parse(),得到一棵对象树,有两种访问方式:当作从 0 开始索引的 Python 列表,或者像函数一样调用,沿用 HL7 从 1 开始计数的惯例。建议用第二种,这样代码里的编号和文档中的字段编号一致。

import hl7

h = hl7.parse(MSG)
pid = h.segment("PID")      # PID 只出现一次
print(pid(3)(1))            # PID-3 的第一个重复
print(str(pid(5)), str(pid(7)), str(pid(8)))

segment() 是一个快捷方法,适用于在消息中只出现一次的段,例如 PID 或 MSH。检查: 第一行打印患者 ID 及 ^ 分隔符后的各组件;第二行打印姓名、出生日期和 M。

第 3 步:把 PID 映射为 Patient

IG 规定,处理 ADT_A01 消息中的 PID 时要新建一个 Patient。在段这一层,映射表把 PID-3 对应到 identifier,PID-5 对应 name,PID-7 对应 birthDate,PID-8 对应 gender。

GENDER = {"M": "male", "F": "female", "U": "unknown"}  # 简化版对照表

def v2_date(s):
    return f"{s[0:4]}-{s[4:6]}-{s[6:8]}"

def pid_to_patient(pid):
    mrn = str(pid(3)(1)).split("^")[0]
    parts = str(pid(5)).split("^")
    return {
        "resourceType": "Patient",
        "identifier": [{"value": mrn}],
        "name": [{"family": parts[0],
                  "given": [p for p in parts[1:3] if p]}],
        "birthDate": v2_date(str(pid(7))),
        "gender": GENDER.get(str(pid(8)), "unknown"),
    }

这是简化版:没有处理转义序列,忽略了 PID-3 和 PID-5 的第二个重复,并假设出生日期总是 8 个字符。GENDER 表也做了删减:在真实项目中,必须对照客户系统实际使用的代码表核实。

第 4 步:按正确的 FHIR 版本校验

新手最容易在这一步出错。v2-to-FHIR IG 的版本是 1.0.0(STU1),基于 FHIR R4。而 fhir.resources 默认是 R5,R4B 和 STU3 作为旧版本保留。直接导入默认版本,就等于用 R5 的 schema 校验 R4 数据。

from fhir.resources.R4B.patient import Patient

patient = Patient.model_validate(pid_to_patient(pid))
print(patient.model_dump_json(indent=2))

按该库 README 的说明,model_validate 从 dict 构建 Patient。也不要把 R4B 和 R4 当成一回事:名字不同,是因为它们是不同的发布版本。映射到基础 Patient 以外的资源时,要再对照 IG 所用的 R4 定义核对一遍。

检查: 把 PID-7 改成 19851345,重新运行,看校验如何响应。如果仍然通过,不要以为数据没问题:在 v2_date 里加上自己的日期检查。

第 5 步:用理解 schema 的解析器交叉核对

python-hl7 不知道 PID-5 叫什么,只知道位置。hl7apy 用 parse_message 解析 ER7 字符串,可以按名称访问子组件,且不区分大小写。

from hl7apy.parser import parse_message

m = parse_message(MSG, find_groups=False)
print(m.pid.patient_name.to_er7())

hl7apy 默认会把段组织成 HL7 分组。传入 find_groups=False 可关闭这一行为,从而直接调用 m.pid。如果你安装的库版本中这个调用不同,请查阅 hl7apy 教程。检查: 打印出的字符串必须与第 2 步中 str(pid(5)) 的结果完全一致。

两个不同的解析器给出相同结果,就多了一层保证:你没有数错字段。

真实消息会在哪里让代码出错?

示例消息只有一个 PID。含多个 OBX 段的消息就不同了:按照映射指南,段的每次重复都要生成对应资源的一个新实例,因此 10 个 OBX 段会变成 10 个 Observation。

这时 segment() 快捷方法就不管用了。必须遍历整棵树,例如 [s for s in h if str(s[0]) == "OBX"],再逐个映射。

第二个出错点是 IG 没有映射的字段。指南允许添加本地映射,并鼓励通过 JIRA 把它们反馈给 HL7。

对 FDE 来说,每一条本地映射都应该是一项写成文档、经客户确认的决定,而不是悄悄藏在代码里的一个 if 语句。

这项技能在客户现场是什么样子?

医院项目启动时,第一件事是向客户要几条去标识化的示例消息,然后对每种消息类型跑一遍第 2 步和第 5 步。

产出是一张逐字段对照表,拿着这张表去和对方的集成团队开会。

这张表也是写进简历的最好证据。当 FDE 岗位描述提到 HL7、FHIR 或接口引擎时,一个包含一组测试消息、一个标注“遵循 v2-to-FHIR IG,R4”的 PID 到 Patient 函数,以及一个能抓出错误出生日期的测试的代码仓库,远比一句“熟悉医疗标准”有说服力。

解析是容易的部分。难的是和客户坐下来,确定他们医院 PID-8 里的 U 到底是什么意思。

这篇文章对你有帮助吗?

7 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力为客户选定的数据格式,是一份必须遵守的契约格式选错很少第一天就出问题,往往等真实数据或 schema 改动偏离双方的默认假设时才暴露。