ZJUI-AI4H/Hulu-Med

📚 Hulu‑Med이란?

Hulu‑Med은 의료 텍스트, 2D 이미지, 3D 볼륨(예: CT/MRI NIfTI 파일), 및 비디오에 대한 텍스트를 이해하고 생성할 수 있는 오픈소스 멀티모달 의료 비전-언어 모델(VLM)입니다. 저자들은 12개의 해부학적 시스템과 14개의 영상 모달리티를 다루는 1,670만 개의 공개 의료 샘플로 모델을 학습시켰으며, 전체 학습 파이프라인, 데이터 큐레이션 스크립트, 및 모델 가중치를 공개합니다.

---

🎯 핵심 기능

• 포괄적인 멀티모달 추론 – 텍스트, 이미지, 3D 스캔, 수술 비디오의任意 조합에 대해 질문 답변, 보고서 작성, 또는 진단 스타일 추론 수행.
• 투명하고 재현 가능 – 모든 코드, 데이터 목록, 가중치가 Apache‑2.0 라이선스 하에 공개됨.
• 효율적인 추론 – HuggingFace Transformers, vLLM, flash-attention, 텐서 병렬성과 호환되어 빠른 서빙 가능.
• 다양한 모델 크기 – 경량 4B 파라미터 모델부터 235B 파라미터 "Flash-Preview" 변형까지, 사용자가 속도, 메모리, 정확도 간의 적절한 트레이드오프를 선택할 수 있음.

---

📦 모델 주(선택된 변형)

모델	파라미터	베이스 LLM	대략적인 GPU 시간*	HF 링크
Hulu‑Med‑4B	4 B	Qwen3‑VL‑4B	~1 k	🤗
Hulu‑Med‑7B	7 B	Qwen2.5‑7B	~4 k	🤗
Hulu‑Med‑14B	14 B	Qwen3‑14B	~8 k	🤗
Hulu‑Med‑30A3	30 B	Qwen3‑VL‑30A3B	~3.2 k	🤗
Hulu‑Med‑235A22 (Flash‑Preview)	235 B	Qwen3‑VL‑235A22B	~10 k	🤗

*GPU 시간은 단일 노드 학습 실행에 대한 대략적인 추정치입니다.

---

📈 성능은 얼마나 좋은가?

저자들은 30개의 의료 VLM 및 텍스트 데이터셋(예: VQA‑RAD, PathVQA, MedXQA, MMLU‑Pro)에서 벤치마크를 수행했습니다. 전반적으로 Hulu‑Med는 기존 오픈소스 의료 VLM을 능가하며, GPT‑4.0과 같은 독점 모델과의 격차를 줄이는 경우가 많습니다. 하이라이트:

• Hulu‑Med‑7B는 OM.VQA에서 84.2, MedXQA에서 66.8을 달성하여 10B 미만의 오픈 모델 중 최고입니다.
• Hulu‑Med‑235A22는 VQA‑RAD에서 70.5, MedXQA에서 39.8을 달성하여 나열된 모든 경쟁 제품을 능가합니다.
• 순수 텍스트 의료 시험(MMLU‑Pro, Medbullets 등)에서 14B 및 30B 변형은 68–69점을 달성하여 오픈 VLM 중 최고 점수를 기록했습니다.

---

🛠️ 빠른 시작 (HuggingFace Transformers)

from transformers import AutoModelForCausalLM, AutoProcessor
import torch

model_id = "ZJU-AI4H/Hulu-Med-7B"
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    trust_remote_code=True,
    torch_dtype="bfloat16",
    device_map="auto",
    attn_implementation="flash_attention_2",
)
processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)

# 예시: 2D X선 이미지에서 보고서 생성
conversation = [{
    "role": "user",
    "content": [
        {"type": "image", "image": {"image_path": "./demo/xray.jpg"}},
        {"type": "text", "text": "간결한 방사선학 보고서를 작성하세요."},
    ]
}]
inputs = processor(conversation=conversation, return_tensors="pt", add_generation_prompt=True)
inputs = {k: v.to(model.device) if isinstance(v, torch.Tensor) else v for k, v in inputs.items()}
output_ids = model.generate(**inputs, max_new_tokens=1024)
print(processor.batch_decode(output_ids, skip_special_tokens=True)[0])

같은 processor는 3D NIfTI 볼륨(type: "3d")과 비디오(type: "video")에도 작동합니다. 자세한 예시는 README를 참조하세요.

---

⚡ vLLM으로 실행 (고처리량 서빙)

VLLM_USE_PRECOMPILED=1 pip install git+https://github.com/jiangsongtao/vllm.git
pip install decord ffmpeg imageio   # 비디오 지원
```\n설치 후, 모델 경로를 지정하여 vLLM을 시작하고 표준 OpenAI 호환 API를 사용하여 멀티모달 페이로드를 전송합니다.

---
### 📂 저장소 구조 (고수준)
- `scripts/` – 데이터 큐레이션, 전처리, 학습 시작 스크립트.
- `hulu_med/` – 모델 정의 및 멀티모달 대화 형식을 파싱하는 사용자 정의 `processor`.
- `demo/` – README에서 사용되는 예시 이미지, 비디오, 3D 스캔.
- `requirements.txt` – 전체 Python 의존성 목록.
- `LICENSE` – Apache 2.0.

---
### 📜 라이선스 및 인용
코드와 가중치는 **Apache 2.0** 하에 공개됩니다. 연구나 제품에서 모델을 사용하는 경우, 배지에 링크된 arXiv 논문(arXiv:2510.08668)을 인용하세요.

---
### 🔗 유용한 링크
- **논문**: https://arxiv.org/abs/2510.08668
- **HuggingFace 모델 허브**: https://huggingface.co/collections/ZJU-AI4H/hulu-med
- **ModelScope**: https://modelscope.cn/models/Med-Team/Hulu-Med
- **라이브 데모**: https://79aafa693c9637a31d.gradio.live
- **평가 스위트 (MedUniEval)**: https://github.com/ZJUI-AI4H/MedUniEval (뉴스 섹션에서 언급됨)

---
### 🤔 Hulu‑Med를 언제 사용해야 하는가?
- 의료 영상 또는 비디오에 공개된 VLM이 필요한 **임상 AI 연구**.
- 방사선 이미지에서 설명이나 보고서를 생성하는 **교육 도구**.
- 개별 시스템을 조합할 필요 없이 텍스트, 2D, 3D, 비디오 입력을 처리할 수 있는 단일 모델을 원하는 **프로토타입 구축**.

---
### 🚀 다음 단계
1. GPU 예산에 맞는 모델 크기를 선택합니다.
2. 대규모 서빙을 위해 설치 단계(conda + pip) 또는 vLLM 경로를 따릅니다.
3. 제공된 Python 스니펫을 사용하여 텍스트, 이미지, 3D 또는 비디오 입력으로 실험을 시작합니다.
4. 버그 보고, 새로운 공개 의료 데이터셋 추가, 또는 전문 하위 도메인에서 파인튜닝을 통해 기여합니다.