weemed/IlhaEmbed

<p align="center"> <img src="https://huggingface.co/weemed/IlhaEmbed/resolve/main/assets/ilhaformosalogo.svg" width="100" height="100" alt="IlhaEmbed Logo (17th C. Ilha Formosa Nautical Line-Art)" /> </p>

IlhaEmbed v3 Dual Release: Flagship (311M) & Ultra-Lightweight Edge (97M)

English | 繁體中文說明

Release Summary (2026-09-20): IlhaEmbed is an open-source clinical semantic embedding family specifically designed for Taiwanese traditional Chinese clinical notes, abbreviations, nursing records, and intake categorization. To satisfy diverse deployment profiles—from cloud intake servers to low-power edge kiosks—IlhaEmbed is officially distributed in two distinct architectural variants:

1. 1.IlhaEmbed-311M (Flagship): High-capacity ModernBERT base architecture (311M parameters, 768-dim embeddings). Grounded in 16-category FHIR resource intent anchors, achieving 100.0% (44/44) strict zero-shot prototype routing and 98.15% (106/108) clinical shorthand Top-1 retrieval. Ideal for cloud intake APIs, EMR/EHR servers, and high-precision candidate re-ranking.
2. 2.IlhaEmbed-97M (Ultra-Lightweight Edge): Compact Granite ModernBERT architecture (97M parameters, 384-dim embeddings). Quantized to a 37.28 MB INT8 ONNX footprint (strictly adhering to the <40MB embedded hardware budget) with ultra-low single-text latency of ~3.97ms on standard CPU. Achieves 100.0% (44/44) zero-shot FHIR prototype routing and 100% administrative rejection without clinical precision degradation. Ideal for community health stations (e.g. The Mirror kiosk), browser WebAssembly (ONNX Runtime Web), and offline edge gateways.

Technical Specifications & Benchmark Comparison

Official MTEB Chinese Benchmark Comparison

Evaluated using official MTEB (Massive Text Embedding Benchmark v2.21.0) on Chinese biomedical and semantic tasks, benchmarked head-to-head against the leading open-source model BAAI/bge-small-zh-v1.5:

Score Interpretation: In information retrieval benchmarks, MAP/NDCG@10 in the 0.45–0.52 range represents top-tier open-source performance (e.g. BGE-small, OpenAI text-embedding-3-large). IlhaEmbed delivers competitive retrieval at a fraction of the computational footprint.

Realistic Clinical Shorthand Evaluation (20 Arbitrary Multi-Clause Notes)

To verify real-world robustness beyond curated single terms, IlhaEmbed was tested against 20 dirty, unstructured, multi-clause clinical notes (spanning emergency triage, Taigi spoken complaints, nursing discharge summaries, and ICU notes):

• —Top-1 Dominant Intent Accuracy: 95.0% (19/20)
• —Top-3 Intent Coverage: 100.0% (20/20)
• —Boundary Edge Case: Past checkup completion ("114年成健已做") scored 0.703 for checkup_intent vs 0.692 for care_event. The small 0.011 margin demonstrates why pure semantic embeddings must be paired with downstream temporal validation rules and clinical human-in-the-loop oversight.

Safety & Regulatory Boundary (SaMD Exemption)

• —Intended Use: Assistive terminology alignment, semantic routing, and candidate recommendation (Suggest-with-Review).
• —Non-SaMD Posture: Under Taiwan TFDA / international SaMD regulatory guidance, IlhaEmbed does not diagnose, treat, or autonomously formulate clinical care decisions. All candidate suggestions and FHIR mappings must undergo clinician or qualified operator verification prior to clinical record persistence.
• —Fail-Closed Design: When cosine confidence falls below the calibrated admission threshold (0.35) or margin is insufficient, fragments are safely held in residue for manual review rather than hallucinated into false clinical facts.

Usage

1. Flagship (311M) — Python / Sentence-Transformers

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("weemed/IlhaEmbed-311M")
embeddings = model.encode(
    ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
    normalize_embeddings=True,
)
print(embeddings.shape)  # (4, 768)

2. Edge (97M) — INT8 ONNX CPU Execution

import numpy as np
import onnxruntime as ort
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
session = ort.InferenceSession(
    "model_int8.onnx", providers=["CPUExecutionProvider"]
)

inputs = tokenizer(
    ["皮蛇", "帶狀皰疹"],
    max_length=32,
    padding="max_length",
    truncation=True,
    return_tensors="np",
)
feed = {
    "input_ids": inputs["input_ids"].astype(np.int64),
    "attention_mask": inputs["attention_mask"].astype(np.int64),
}
outputs = session.run(["sentence_embedding"], feed)[0]
normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
print(normed.shape)  # (2, 384)

Data Governance & Open-Source Principles

1. 1.Zero Protected Health Information (PHI): No patient records, electronic medical records (EMR), or private institutional data are included in training datasets or model checkpoints.
2. 2.Open-Access Licensing Compliance: Mined signals are derived exclusively from open government data (MODA, NAER 13 Academic Medical Terminology sets), public-domain exam databases (MOEX licensing exams under Taiwan Copyright Act §9.1.5), and licensed terminology descriptions.
3. 3.No Proprietary Corpora Redistribution: Copyrighted clinical articles and raw hospital document dumps are not redistributed (see SOURCES.md).
4. 4.License: Code and published weights are licensed under Apache-2.0.

<a name="繁體中文說明"></a>

IlhaEmbed (v3.0) 繁體中文完整說明

English | 繁體中文

IlhaEmbed 是專為台灣臨床病歷、護理紀錄、社區健檢表與衛教紀錄打造的高精度開源醫療語意嵌入向量模型系列。其將在地臨床行話、拉丁縮寫、中英夾雜速記以及繁體中文醫學術語投影至統一的語意空間，支援高精度的醫療數據攝取分流（Intake Routing）與術語檢索推薦。

名稱源自 Ilha Formosa（美麗島），專門讀懂這座島嶼的臨床語言。

臨床痛點與核心升級亮點

台灣各級醫療院所的電子病歷、護理交班、社區健檢表上充滿高度在地化的行話與臨床縮寫：

• —L-CT：代表低劑量胸部電腦斷層（肺癌早期篩檢）。
• —MIF：健檢報告中代表傷寒篩檢之糞便檢體未交。
• —皮蛇：在地俚語俗稱，代表帶狀皰疹。
• —成健：代表成人預防保健服務。
• —檳榔：與菸酒並列之台灣本土重要社會史致癌危險因子。
• —定期心內門診-戒菸：跨專科複合追蹤與衛教紀錄。
• —斷腦筋：台語口語醫學語意，代表中風（腦中風）。

通用大語言模型與一般中文語意嵌入模型對此類高度專業且具地域性的縮寫與行話識別率極低。IlhaEmbed v3 正式推出雙版本發布體系，滿足從雲端伺服器到邊緣低功耗設備之多樣化部署需求：

1. 1.IlhaEmbed-311M（高容量旗艦版）：
2. 2.採用 ModernBERT Base (311M 參數)，輸出 768 維度高品質向量。
3. 3.全面鎖定 16 類 FHIR 資源語意原型（Condition, MedicationStatement, Encounter, Observation 等），在 16 類嚴格原型分流基準測試達到 100.0% (44/44) 零樣本準確率。
4. 4.臨床速記與簡稱 Top-1 檢索率達 98.15% (106/108) ，Top-5 達 100.0% 。
5. 5.適合部署於院區資料中心、伺服器端 Intake-Spine 數據前處理與高精度推薦重排。

1. 1.IlhaEmbed-97M（超輕量邊緣版）：
2. 2.採用 Granite ModernBERT Lightweight (97M 參數)，輸出 384 維度精簡向量。
3. 3.經過 25.5k 繁體中文醫學專用詞表剪枝與標準算子 INT8 動態量化，模型檔案大小僅 37.28 MB，嚴格符合社區健康站與手持裝置 <40 MB 的邊緣硬體預算門禁。
4. 4.在 16 類 FHIR 資源原型分流準確率同樣達到 100.0% (44/44) ，行政管理字串防禦拒絕率達 100.0%，純 CPU 推論單筆延遲僅 ~3.97ms （Batch-16 下每筆 1.7ms），真正做到容量縮減但精度不容許降級。
5. 5.適合社區健檢站一體機（如 The Mirror）、離線醫療閘道器與瀏覽器 WebAssembly (WASM) 端執行。

雙版本評測成效對照 (Benchmark Comparison)

MTEB 官方基準實測對照 (Massive Text Embedding Benchmark)

使用官方最新版 MTEB v2.21.0 針對中文醫療與語意任務進行同機同卡嚴謹對照，對比開源主流標竿模型 BAAI/bge-small-zh-v1.5：

評測數值常識說明：在資訊檢索（IR）領域中，MAP / NDCG@10 達 0.45 ～ 0.52 即為全球開源與商業模型（如 BGE-small, OpenAI）之頂尖梯隊。IlhaEmbed 僅以 37MB 體積即在醫療檢索任務超越 BGE-small。

隨意病歷速記檢驗 (真實未美化 20 筆複合速記)

使用正式發布版模型對 20 筆包含門診、急診、台語主訴、護理給藥等真實複合長句進行檢驗：

• —主意圖命中率 (Top-1 Dominant Hit)：95.0% (19/20)
• —前三候選覆蓋率 (Top-3 Intent Coverage)：100.0% (20/20)
• —邊界失效案例分析：「114年成健已做，糞檢MIF未交，建議下次門診補交檢體」 預測 checkup_intent (0.703) 與 care_event (0.692) 僅差 0.011。「已做」與「安排」的時態語意在純向量空間邊界模糊，證明臨床落地時必須保留下游規則過濾與醫事人員覆核（Fail-Closed 殘差機制）。

快速開始 (Quick Start)

1. Python / Sentence-Transformers（支援雙版本）

from sentence_transformers import SentenceTransformer

# 載入 311M 旗艦版（伺服器端、FHIR 16 類零樣本分流與速記重排）
flagship = SentenceTransformer("weemed/IlhaEmbed-311M")
emb_flagship = flagship.encode(
    ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
    normalize_embeddings=True,
)
print("311M 向量維度:", emb_flagship.shape)  # (4, 768)

# 載入 97M 超輕量版（輕量邊緣端推薦）
edge = SentenceTransformer("weemed/IlhaEmbed")
emb_edge = edge.encode(["皮蛇", "帶狀皰疹"], normalize_embeddings=True)
print("97M 向量維度:", emb_edge.shape)  # (2, 384)

2. ONNX Runtime 純 CPU 地端極速部署（97M 邊緣端首選）

import numpy as np
import onnxruntime as ort
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
session = ort.InferenceSession("model_int8.onnx", providers=["CPUExecutionProvider"])

inputs = tokenizer(
    ["皮蛇", "帶狀皰疹"],
    max_length=32,
    padding="max_length",
    truncation=True,
    return_tensors="np",
)
feed = {
    "input_ids": inputs["input_ids"].astype(np.int64),
    "attention_mask": inputs["attention_mask"].astype(np.int64),
}
outputs = session.run(["sentence_embedding"], feed)[0]
normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
print("ONNX 輸出維度:", normed.shape)  # (2, 384)

醫療法規、SaMD 豁免與安全邊界

• —預期用途（Intended Use）：臨床輔助建議、攝取分流與候選重排（Suggest-with-Review Candidate Ranker）。
• —非 SaMD 宣告（Non-SaMD Posture）：依據台灣衛生福利部食品藥物管理署（TFDA）與國際醫療器材軟體（SaMD）法規指引，IlhaEmbed 不具備自主診斷、疾病處方或獨立醫療決策功能。模型輸出之所有建議與 FHIR 映射事實，嚴禁未經醫師、護理師或合格醫事人員覆核即直接作為臨床處置或定稿病歷。
• —Fail-Closed 殘差機制：當模型餘弦相似度或分類邊界餘裕（Margin）低於安全閾值時，片段自動退回殘差隊列（Residue），由臨床人員介入審閱，防範模型幻覺或錯誤歸類產生虛假醫療事實。

資料治理與開源邊界原則

1. 1.零受保護健康資訊（Zero PHI）：模型訓練與評測全流程不包含任何真實病患姓名、身分證號、病歷號或可識別隱私個資。
2. 2.政府開放資料與公眾領域合規：知識蒸餾訊號來自政府開放資料（數發部 MODA、國教院 NAER 13 大類學術醫療名詞庫）及《著作權法》第九條第一項第五款之公務考題。
3. 3.嚴禁散布未授權語料：本開源倉庫與模型權重不散布任何第三方付費商業術語辭庫或未授權醫學期刊論文全文。
4. 4.授權條款：開源程式碼與發布模型權重均採用 Apache-2.0 寬鬆開源授權。