MedFusion OSS

Open-core medical AI runtime for training, validation, and reproducible result artifacts.

MedFusion OSS 聚焦一件事：把医学 AI 的研究流程从“能训练”升级到“可验证、可复盘、可交付”。

核心定位：executable runtime + structured validation outputs

---

为什么是 MedFusion OSS

很多项目能把模型跑起来，但训练后的结果组织、验证结构和报告产物不稳定。 MedFusion OSS 优先保证主链闭环：

• 配置先校验：validate-config
• 训练可执行：train
• 结果可复盘：build-results

标准输出包括： logs/history.json / metrics/metrics.json / metrics/validation.json / reports/summary.json / reports/report.md + 可视化 artifacts。

---

OSS 与 Pro 的关系

MedFusion 采用 open-core 路线：

• OSS = upstream core runtime / workbench（像 Chromium）
• Pro = commercial distribution / doctor-facing workbench（像 Chrome）

OSS 不是 demo 壳，而是长期技术主干。

---

快速开始

如果你的目标是“自己新建一份 YAML 模型配置”，先看 如何新建模型与 YAML。 当前官方边界是：

• 普通用户复制主链模板
• 高级用户走 Builder / 代码做结构实验
• 真正新的能力先扩 runtime，再扩 YAML

以下命令默认在 MedFusion OSS 仓库根目录 执行。 --config configs/... 这类官方相对配置路径，在你从仓库外执行时也会优先回退到这个仓库根目录。 logging.output_dir 和 --output-dir 这类相对输出路径也会统一锚定到这个仓库根目录，而不是你当前 shell 的 cwd。 csv_path / image_dir 这类主链数据路径，同样会按仓库根目录稳定解析。

如果你完全没有私有数据，推荐先走“公共数据快速验证”。 先成功跑通一次，再迁移到自己的 YAML，阻力最小。

如果你想要一个固定的本地 / CI 自检入口，而不是手敲整串命令，直接运行：

bash test/smoke.sh

它会按官方 BreastMNIST quickstart 主链执行 prepare -> validate-config -> train -> build-results，并检查标准产物是否都已经落盘。

如果你更希望从 Web 入口开始理解这套系统，当前默认入口是：

uv run medfusion start

它会先把你带到 Getting Started 引导页，帮助你完成第一次成功闭环；真正长期做实验和复现时，仍然建议回到 YAML + medfusion 这条主链。

如果你希望从 CLI 直接完成一次完整闭环，当前推荐命令是：

uv run medfusion run --config configs/starter/quickstart.yaml

它会默认执行 validate-config -> train -> build-results。如果你需要分阶段调试，仍然可以继续单独使用 validate-config、train 和 build-results。

1) 公共数据快速验证（推荐第一步）

uv run medfusion public-datasets list
uv run medfusion public-datasets prepare medmnist-breastmnist --overwrite
uv run medfusion run --config configs/public_datasets/breastmnist_quickstart.yaml

2) 本地数据路径

uv run medfusion run --config configs/starter/quickstart.yaml

这里的 validate-config 不只是“看有没有报错”。 它现在会先把这份 YAML 对应的主线 contract 打印出来，包括：

• 当前会调用的训练 schema / model_type
• 关键模块组合，例如 vision_backbone、fusion_type
• 结果输出目录与 best.pth、summary.json、validation.json
• 下一步建议命令：train、build-results、import-run

也就是说，新手先看 validate-config 的输出，就能知道“这份 YAML 到底会跑什么、结果会写到哪里”，不需要先翻源码。

如果你需要分阶段排查问题，再退回下面这条拆解命令链：

uv run medfusion validate-config --config configs/starter/quickstart.yaml
uv run medfusion train --config configs/starter/quickstart.yaml
uv run medfusion build-results \
  --config configs/starter/quickstart.yaml \
  --checkpoint outputs/quickstart/checkpoints/best.pth

3) 专项 demo：三相 CT + 临床小样本

v1 demo 适用于小样本可行性验证，不用于宣称泛化性能。

输入要求：

• manifest CSV：每行一个病例，至少包含 case_id、三相 DICOM 目录、mvi_binary
• 三相目录：arterial_series_dir、portal_series_dir、noncontrast_series_dir
• 临床字段：由 demo config 中 data.clinical_feature_columns 指定

运行方式：

uv run medfusion validate-config --config configs/demo/three_phase_ct_mvi_dr_z.yaml
uv run medfusion train --config configs/demo/three_phase_ct_mvi_dr_z.yaml
uv run medfusion build-results \
  --config configs/demo/three_phase_ct_mvi_dr_z.yaml \
  --checkpoint outputs/three_phase_ct_mvi_dr_z/checkpoints/best.pth

说明：

• 主线输出会生成 logs/history.json、metrics/metrics.json、 metrics/validation.json、reports/summary.json、reports/report.md
• risk score 当前表示 MVI-related risk score
• 它不是生存风险，也不是临床可直接使用的评分
• 热图默认会导出两种解释视角： predicted_class 用于解释“模型为什么给出当前最终判断”， positive_class 用于解释“如果专门寻找 MVI 阳性证据，模型会关注哪里”

热图视角说明：

• predicted_class 更接近“为什么这次报告写成这样”
• positive_class 更接近“如果从 MVI 风险角度补充观察，哪里更可疑”
• 两者不是重复图片，而是在回答两个不同问题
• 对医生展示时，建议把 predicted_class 作为主图， 把 positive_class 作为“阳性风险补充解释图”
• 对当前 demo 而言，只要某个病例被纳入热图导出， 每一期默认都会生成这两个视角； 但如果该病例的 predicted_class 本身就是阳性， 那么两种视角在语义和图像上可能接近甚至重合

---

预期输出（3 分钟自检）

运行完成后，你至少应该看到类似结构：

outputs/<run_name>/
├── checkpoints/
│   └── best.pth
├── logs/
│   └── history.json
├── metrics/
│   ├── metrics.json
│   └── validation.json
├── reports/
│   ├── summary.json
│   └── report.md
└── artifacts/

summary.json 会包含可直接复盘/汇报的结构化信息（示例）：

{
  "run_name": "quickstart",
  "task": "classification",
  "primary_metric": "auc",
  "primary_metric_value": 0.87,
  "checkpoint": "outputs/quickstart/checkpoints/best.pth",
  "artifacts": ["metrics.json", "validation.json", "report.md"]
}

---

Non-goals（当前不承诺）

MedFusion OSS 当前不是：

• 通用公开 benchmark 排行平台
• 临床部署/医疗器械合规软件
• 可视化拖拽式 AutoML 产品

它现在的目标很明确：把训练与验证结果闭环做扎实，且可复盘、可对接。

---

运行主链

flowchart LR
  A[validate-config] --> B[train]
  B --> C[build-results]
  C --> D[metrics/metrics.json]
  C --> E[metrics/validation.json]
  C --> F[reports/summary.json]
  C --> G[reports/report.md]

Loading

---

架构概览（README 简版）

flowchart TB
  A[CLI / YAML Config] --> B[Runtime Assembly]
  B --> C[Data Pipeline]
  B --> D[Model Graph]
  C --> E[Trainer]
  D --> E
  E --> F[Evaluation]
  F --> G[Structured Artifacts]
  B --> H[Base Web/API]

Loading

工程接入时建议重点关注两类边界：

• 可替换点：backbone / fusion / head / trainer
• 契约点：config schema + artifact schema（metrics/metrics.json / metrics/validation.json / reports/summary.json / reports/report.md）

代码级架构详解见：

• CORE_RUNTIME_ARCHITECTURE.md
• OUTPUTS_DIRECTORY_GOVERNANCE.md

---

项目结构

oss/
├── med_core/      # 核心 runtime（models, trainers, evaluation, cli, web）
├── configs/       # 配置模板
├── tests/         # 测试
├── examples/      # 示例
├── scripts/       # 回归与辅助脚本
└── docs/          # 文档

---

开发与验证

# 最小回归（推荐日常）
bash scripts/full_regression.sh --quick

# 对齐 CI
bash scripts/full_regression.sh --ci

# 完整本地回归
bash scripts/full_regression.sh --full

其中最关键的基础回归包括：

• tests/test_config_validation.py
• tests/test_export.py

---

文档入口

• 如何新建模型与 YAML
• 快速上手
• CLI & Config 工作流
• 公共数据集路径
• Examples Guide
• 文档站首页
• 任务手册（按目标执行）
• Why MedFusion OSS（定位对比）
• OSS roadmap

---

贡献与许可

• 贡献指南：CONTRIBUTING.md
• 许可证：MIT
• Issues: https://github.com/iridyne/medfusion/issues
• Discussions: https://github.com/iridyne/medfusion/discussions