OpenTSLM/OpenTSLM

OpenTSLM: Time-Series Language Models for Reasoning over Multivariate Medical Text- and Time-Series Data

OpenTSLM – 의료 데이터를 위한 시계열 언어 모델

무엇인가요 – OpenTSLM은 대규모 언어 모델(LLM)에 다변량 시계열 데이터(예: ECG, 가속도계, EEG 등)를 입력하고 추론할 수 있도록 확장하는 오픈소스 라이브러리입니다. 본 프로젝트는 다음과 같은 기능을 제공합니다:

사전 학습된 "TSLM" 체크포인트 – Llama 3.2(1 B/3 B) 및 Gemma(270 M/1 B) 기반으로, 임의 길이의 시계열 데이터를 이해하고 자연어로 프롬프트할 수 있습니다.
Python API (OpenTSLM 클래스) – Hugging-Face Hub에서 이러한 체크포인트를 로드하고 추론을 위한 generate 메서드를 제공합니다.
커리큘럼 스타일의 학습 스크립트 – 연구자들이 여러 단계의 작업(다중 선택 QA → 캡션 생성 → 체인 오브 써드 추론)을 순차적으로 미세 조정할 수 있도록 설계되었으며, 인간 활동 인식, 수면 단계 분류, ECG QA, 일반 시계열 캡션 생성을 커버합니다.
데모 스크립트 – 각 벤치마크 데이터셋에서 빠르게 엔드투엔드 실행을 위한 스크립트가 제공됩니다.

빠른 시작 (추론)

pip install opentslm          # 라이브러리 설치

from opentslm import OpenTSLM
from opentslm.time_series_datasets.TSQADataset import TSQADataset
from opentslm.time_series_datasets.util import extend_time_series_to_match_patch_size_and_aggregate
from torch.utils.data import DataLoader
from opentslm.model_config import PATCH_SIZE
import torch

REPO_ID = "OpenTSLM/llama-3.2-1b-tsqa-sp"
model = OpenTSLM.load_pretrained(REPO_ID,
                                 device="cuda" if torch.cuda.is_available() else "cpu")

test_dataset = TSQADataset("test", EOS_TOKEN=model.get_eos_token())
loader = DataLoader(test_dataset,
                    batch_size=1,
                    shuffle=False,
                    collate_fn=lambda b: extend_time_series_to_match_patch_size_and_aggregate(
                        b, patch_size=PATCH_SIZE))

for batch in loader:
    preds = model.generate(batch, max_new_tokens=200)
    for sample, out in zip(batch, preds):
        print("Q:", sample.get("pre_prompt", "N/A"))
        print("A:", sample.get("answer", "N/A"))
        print("Model output:", out)
    break   # 데모는 처음 몇 예시만 표시

이 스크립트는 소프트 프롬프트 튜닝된 모델(sp)을 로드하고 TSQA 테스트 세트에서 몇 가지 추론 단계를 실행합니다.

학습 (커리큘럼 학습)

OpenTSLM는 curriculum_learning.py 드라이버를 제공하여 다섯 단계의 학습 단계를 실행합니다:

단계 1 – MCQ (TSQA 데이터셋에서의 다중 선택 QA)
단계 2 – 캡션 생성 (자유형 시계열 설명, M4 데이터셋)
단계 3 – CoT (인간 활동 인식을 위한 체인 오브 써드 추론)
단계 4 – 수면 CoT (수면 단계 분류)
단계 5 – ECG CoT (ECG 질문 응답)

일반적인 명령어:

python curriculum_learning.py \
    --model OpenTSLMFlamingo \
    --llm_id meta-llama/Llama-3.2-1B \
    --device cuda \
    --stages stage1_mcq stage2_captioning stage3_cot

이 스크립트는 자동으로 이전 단계의 최적 체크포인트를 로드하고, results/<llm_id>/<model_type>/stageX/에 새로운 체크포인트를 저장하며, 메트릭과 예측 결과를 JSONL 파일에 기록합니다.

모델 변형

기반 LLM	크기	변형	리포지토리 ID 패턴
Llama‑3.2	1 B	소프트 프롬프트 (`sp`)	`OpenTSLM/llama-3.2-1b-<dataset>-sp`
Llama‑3.2	3 B	Flamingo (`flamingo`)	`OpenTSLM/llama-3.2-3b-<dataset>-flamingo`
Gemma	270 M	sp	`OpenTSLM/gemma-3-270m-<dataset>-sp`
Gemma	1 B	flamingo	`OpenTSLM/gemma-3-1b-pt-<dataset>-flamingo`

이 라이브러리는 목록에 있는 모델 중 어느 것과도 호환됩니다. Meta 또는 Google 모델 리포지토리에 대한 읽기 권한이 있는 Hugging-Face 토큰만 있으면 됩니다.

핵심 구성 요소

opentslm/ – 핵심 라이브러리 (모델 래퍼, 데이터셋 유틸리티, 설정 상수).
demo/huggingface/ – 각 벤치마크용 즉시 실행 스크립트.
scripts/ – 메모리 사용량 분석, 데이터셋 생성, 보조 도구.
curriculum_learning.py – 다단계 학습/평가를 조율하는 스크립트.
results/ – 체크포인트 및 메트릭의 기본 출력 구조.

라이선스 및 커뮤니티

라이선스: MIT (REUSE 호환).
기여 방법: 가이드라인과 코드 오브 콘덕트가 제공되며, 풀 리퀘스트를 통해 기여를 환영합니다.
문의 / 연구 기회: 이메일 digitalhealthresearch@stanford.edu 또는 스탠포드/ETH 연구소의 학생 연구 페이지를 방문하세요.

OpenTSLM를 사용해야 할 때

임상 시계열 데이터에 대한 자연어 질문(예: "이 ECG에서 나타나는 부정맥은 무엇입니까?")에 답할 수 있는 단일 모델이 필요할 때.
LLM의 추론 능력을 유지하면서 새로운 의료 시계열 데이터셋에 대해 언어 모델을 미세 조정하고 싶을 때.
다중 모달 LLM 연구를 진행하고 있으며, 시계열을 1차 모달리티로 다루는 참조 구현이 필요할 때.

결론: OpenTSLM는 기존의 Llama 또는 Gemma 모델을 "시계열 언어 모델"로 전환하여, 다른 LLM과 마찬가지로 프롬프트할 수 있게 하면서도, 임의 길이의 다변량 신호를 처리할 수 있습니다. 리포지토리는 사전 학습된 체크포인트, 깔끔한 Python API, 그리고 새로운 의료 분야로의 접근 확장을 위한 커리큘럼 학습 파이프라인을 제공합니다.