OpenMed 딥다이브
— 임상 텍스트를 로컬에서 분석하는 의료 AI

1프로젝트 한줄 요약

병원·연구소에는 "사람이 쓴 글"로 된 의료 데이터가 산더미입니다 — 퇴원 요약지, 처방전, 검사 소견. 이걸 컴퓨터가 다루려면 먼저 "이 단어는 병명, 저 단어는 약 이름"처럼 의미를 붙여야 하고, 동시에 "이 이름·주민번호는 가려야 한다"는 개인정보 보호도 해야 합니다. 보통은 이걸 클라우드 의료 API에 보내 처리하는데, 그 순간 환자 정보가 외부 서버로 나갑니다.

OpenMed는 이 두 가지(의료 개체 추출 + 개인정보 비식별화)를 내 컴퓨터 안에서 끝냅니다. analyze_text("...") 한 줄이면 질병·약물·해부학·유전자 같은 개체를 뽑아 주고, deidentify("...") 한 줄이면 이름·날짜·주민번호를 가려 줍니다. 모델은 HuggingFace의 OpenMed 조직에 공개된 의료 모델 카탈로그에서 골라 쓰고, 네트워크 없이 로컬 폴더만 가리켜도 동작합니다.

from openmed import analyze_text

result = analyze_text(
    # 만성 골수성 백혈병에 imatinib을 시작했다는 임상 문장
    "Patient started on imatinib for chronic myeloid leukemia.",
    model_name="disease_detection_superclinical",
)
# DISEASE   chronic myeloid leukemia   0.98
# DRUG      imatinib                   0.95

2왜 주목받는가

주목 이유는 크게 셋입니다. ① 규제·프라이버시 압박 — 환자 정보(PHI)를 외부 클라우드로 보내는 것 자체가 HIPAA·GDPR 리스크라, "데이터를 안 내보내는" 도구 수요가 큽니다. ② 모델 생태계 — 의료 모델을 공통 API로 묶으며, 품질과 이용 조건은 각 모델·데이터셋별로 확인해야 합니다. ③ 온디바이스 가속 — Apple Silicon의 MLX와 지원 모델의 CoreML·ONNX 경로를 제공합니다. 속도와 메모리는 모델·정밀도·기기별로 측정해야 합니다.

클라우드 의료 API와의 비교

핵심 차별점 셋

3기술 스택 전체 지도

OpenMed의 설계 철학은 "얇은 핵심 + 갈아끼우는 백엔드 + 선택적 확장"입니다. 코어 의존성은 pysbd·faker·jieba·pyyaml·jsonschema 5개이고, 무거운 ML 런타임(transformers·mlx·coreml)은 전부 선택 설치(extras)로 빠져 있습니다. 필요한 백엔드만 골라 깔면 됩니다.

언어 / 빌드

선택 설치(extras) — 필요한 만큼만

4개 추론 백엔드 (갈아끼우는 엔진)

인프라 — REST 서비스 & Docker

라이브러리를 넘어 FastAPI 기반 REST 서비스로도 돌릴 수 있습니다. Docker 이미지는 python:3.11-slim 베이스에 CPU 전용 PyTorch를 깔고, uvicorn으로 openmed.service.app을 8080 포트에 띄웁니다. HEALTHCHECK로 /health를 주기 점검하고, OPENMED_SERVICE_KEEP_ALIVE 환경변수로 유휴 모델을 자동 내려 메모리를 회수합니다.

# 서비스 실행
uvicorn openmed.service.app:app --host 0.0.0.0 --port 8080

# 또는 Docker로
docker build -t openmed:1.5.5 .
docker run --rm -p 8080:8080 -e OPENMED_PROFILE=prod openmed:1.5.5

# 엔드포인트: /health  /analyze  /pii/extract  /pii/deidentify
#            /models/loaded  /models/unload (모델 생명주기 관리)

Apple 생태계 — Swift / MLX / OpenMedKit

같은 모델을 아이폰·아이패드·맥 앱에 그대로 넣을 수 있는 게 큰 강점입니다. swift/ 아래에 SPM 패키지 OpenMedKit과 데모 앱 2개(OpenMedDemo, OpenMedScanDemo)가 있습니다. 앱에 다음 한 줄로 의존성을 추가하면, PII 탐지·임상 추출이 완전 오프라인으로 기기 안에서 돕니다.

// Swift Package에 OpenMedKit 추가
dependencies: [
    .package(url: "https://github.com/maziyarpanahi/openmed.git", from: "1.5.5"),
]

4아키텍처 심화 분석

OpenMed의 진짜 배울 점은 "임상 텍스트 → 토큰 분류 → 개체 디코딩/병합 → 출력"의 파이프라인을, 백엔드와 언어에 독립적으로 추상화한 방식입니다. 어떤 엔진(torch/mlx/coreml)을 쓰든, 어떤 언어든, 같은 analyze_text() / extract_pii() 진입점으로 흐릅니다.

전체 데이터 흐름도

설계 패턴 ① — 백엔드 추상화 (한 이름, 모든 하드웨어)

core/backends.py가 "어느 엔진으로 돌릴지"를 한 곳에서 결정합니다. Privacy Filter 계열에서 MLX 아티팩트를 요청했는데 MLX를 쓸 수 없으면, 계열별로 매핑된 PyTorch 모델로 대체하고 경고합니다. 모든 모델이 같은 가중치로 자동 변환되는 것은 아닙니다. 개발자 코드는 그대로 두고 실행 환경만 바뀌어도 동작하는 "write once, run anywhere"의 ML 버전입니다.

설계 패턴 ② — 모델 레지스트리 (별명과 실제 체크포인트 매핑)

HuggingFace의 긴 체크포인트 경로를 매번 외울 수는 없습니다. core/model_registry.py(약 22KB)는 disease_detection_superclinical 같은 친근한 별명 → 실제 HF 체크포인트 매핑을 큐레이션해 둡니다. 처음 쓸 때 모델을 내려받아 로컬 캐시에 두고, 그다음부터는 네트워크 없이 씁니다.

망 분리 환경이라면 model_id="./models/..."처럼 로컬 디렉토리를 가리켜 HF Hub에 접속하지 않고 로드할 수 있습니다.

설계 패턴 ③ — 스마트 개체 병합 (토큰 조각 재조립)

Transformer는 단어를 서브워드 토큰으로 쪼개 처리합니다. 그래서 01/15/1970 같은 날짜가 01, /, 15... 로 흩어지기 쉽습니다. core/pii_entity_merger.py(약 28KB)는 이렇게 조각난 토큰을 다시 하나의 개체로 붙여, 날짜·주민번호가 토막 나지 않게 합니다. 비식별화 품질을 좌우하는 숨은 핵심입니다.

설계 패턴 ④ — 비식별화 4전략

core/anonymizer/는 찾아낸 PII를 어떻게 처리할지 4가지 방법을 제공합니다. 상황(연구용 공유, 로그 보관, 종단 추적)에 따라 고릅니다.

설계 패턴 ⑤ — Privacy Filter 계열 (같은 코드, 다른 가중치)

비식별화 모델 중 일부는 OpenAI Privacy Filter 아키텍처를 공유합니다. gpt-oss 계열의 희소 MoE 트랜스포머에 로컬 어텐션·sink 토큰·RoPE+YaRN·tiktoken o200k_base를 쓰는 구조입니다. 코드는 똑같고 학습 데이터(가중치)만 다른 3가지 변형이 있으며, 모두 같은 extract_pii() API로 부릅니다 — model_name=만 바꾸면 됩니다.

REST 서비스 내부 구조

5디렉토리 구조 해부

"얇은 코어 + 백엔드별 폴더 + 서비스/앱 분리" 철학이 구조에 그대로 보입니다. 두뇌는 openmed/core/에 모여 있고, 엔진은 torch/ mlx/ coreml/ zero_shot/으로 갈라지며, 배포 형태(서비스·Swift 앱)는 바깥에 있습니다.

6학습 포인트

① 트랜스포머 토큰 분류로 하는 NER

"문장 → 토큰별 라벨 → 개체로 합치기"는 정보 추출의 기본기입니다. OpenMed는 의료 도메인으로 이걸 실전 수준까지 끌고 갑니다. transformers의 토큰 분류 파이프라인이 어떻게 NER이 되는지, 라벨 체계(DISEASE/DRUG...)가 어떻게 정의되는지 통째로 볼 수 있습니다.

② 백엔드 독립성 — 한 번 짜고 어디서나

같은 모델을 CPU·GPU·MLX·CoreML로 돌리는 추상화는, 의존성 역전과 어댑터 패턴의 ML판입니다. backends.py 한 파일이 "어느 엔진을 고를지"를 캡슐화해, 상위 코드가 하드웨어를 몰라도 되게 합니다.

③ PII 비식별화와 HIPAA

"무엇이 개인정보인가", "어떻게 가려야 재식별이 안 되나"는 실무에서 가장 까다로운 주제입니다. HIPAA의 18개 Safe Harbor 식별자, 마스킹 vs 가짜치환 vs 해시의 트레이드오프, 형식 보존의 필요성을 코드로 익힐 수 있습니다.

④ 토큰화와 개체 병합의 함정

서브워드 토큰화 때문에 날짜·번호가 조각나는 문제는 NER 품질의 숨은 적입니다. pii_entity_merger.py는 이 "조각을 다시 붙이는" 후처리가 왜 필수인지, 어떻게 구현하는지 보여 주는 좋은 교본입니다.

⑤ ML을 서비스로 — FastAPI · 모델 생명주기 · Docker

모델을 "라이브러리"가 아니라 "API 서비스"로 만들 때 생기는 문제 — 사전 로드, 메모리 회수, 헬스체크, 컨테이너화 —를 한 레포에서 다룹니다. runtime.py의 파이프라인 공유와 keep_alive.py의 유휴 언로드가 특히 실전적입니다.

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크