Synthea

Synthea 快速上手教程

Synthea 上手建议：先装 JDK，再用 JAR 或源码跑一次默认生成，然后打开输出目录看 FHIR / CSV 数据，最后按需要调整人口、疾病模块和导出格式。

1. 准备环境

Synthea 是 Java 项目，需要先安装 JDK。较新版本通常建议使用 JDK 17 或更高版本。

java -version

如果看到类似 openjdk 17.x.x，说明环境就绪。

2. 方式一：用 JAR 快速跑

如果只想快速生成数据，可以直接下载官方发布的带依赖 JAR 包，例如：

java -jar synthea-with-dependencies.jar

这会按默认配置生成一批合成患者数据。

3. 方式二：用源码跑（更灵活）

git clone https://github.com/synthetichealth/synthea.git
cd synthea

如果项目使用 Gradle：

./gradlew build
./gradlew run

如果仓库提供了 run_synthea 脚本，也可以直接执行：

./run_synthea -p 100

具体命令以当前仓库 README 和构建脚本为准。

4. 常用命令示例

生成 100 名患者：

./run_synthea -p 100

指定随机种子，保证结果可重复：

./run_synthea -p 50 -a 30-60 -g MALE

限定年龄和性别：

./run_synthea -p 50 -a 30-60 -g MALE

指定地区和城市：

./run_synthea -p 100 Massachusetts
./run_synthea -p 100 Washington Seattle

自定义输出目录：

./run_synthea -p 100 --exporter.baseDirectory="./output_ca"

开启 FHIR 导出：

./run_synthea -p 100 --exporter.fhir.export=true

也可以同时开启 CSV、C-CDA 或批量 FHIR 导出。

5. 查看生成的数据

生成完成后，数据通常输出到 output/ 目录，或你通过 --exporter.baseDirectory 指定的目录。

常见输出包括：

• FHIR JSON：适合导入 HAPI FHIR、EHR 测试系统。
• CSV：适合做数据分析、机器学习训练。
• C-CDA：适合测试临床文档交换。
• 患者目录：每个患者通常有独立文件，包含就诊、诊断、用药、检验等记录。

6. 和 HAPI FHIR 联调

如果你想把 Synthea 数据喂给 HAPI FHIR，可以这样走：

./run_synthea -p 10 --exporter.fhir.export=true

生成后进入输出目录，找到 FHIR JSON 文件，再用 curl 或脚本上传到本地 FHIR 服务器：

curl -X POST http://localhost:8080/fhir \
  -H "Content-Type: application/json" \
  -d @Patient-xxxxx.json

注意：Synthea 生成的可能是多个资源文件，生产化导入时建议用脚本批量处理，并校验 resourceType。

7. 配置要点

主要配置在：

src/main/resources/synthea.properties

可以调整：

• exporter.fhir.export
• exporter.csv.export
• exporter.ccda.export
• exporter.fhir.bulk_data
• 输出目录
• 模块启用状态

修改后重新运行即可。

8. 常见坑

• JDK 版本不匹配：太旧的 JDK 可能无法运行新版本 Synthea。
• 默认地区偏美国：人口模型、疾病发生率、地理数据默认基于美国，国内场景需要自行适配。
• 输出目录找不到：注意查看运行日志，确认实际输出路径。
• FHIR 版本要对齐：导入 HAPI FHIR 前确认资源是 R4、STU3 还是其他版本。
• 不要当真实临床数据用：Synthea 数据只适合测试、研究、教学和算法验证。
• 大规模生成会占磁盘：生成数万患者时，输出文件可能很多，建议先小批量验证。