OpenTSLM/OpenTSLM

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

OpenTSLM – 醫療資料用的時間序列語言模型

是什麼 – OpenTSLM 是一個開源套件，擴展大型語言模型（LLM），使其能處理並推理多變量時間序列資料（例如：心電圖、加速度計、腦波等）。本專案提供：

預訓練的「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，並需要一個將時間序列視為第一類模態的參考實作。

結論：OpenTSLM 將現成的 Llama 或 Gemma 模型轉換為「時間序列語言模型」，可像其他 LLM 一樣提示，同時仍能處理任意長度的多變量訊號。該倉儲提供預訓練檢查點、乾淨的 Python API，以及用於擴展至新醫療領域的課程訓練管道。