gloomcheng commited on
Commit
cf74485
·
verified ·
1 Parent(s): 2487113

docs: restore canonical English-first Chinese-second README and replace model_int8.onnx with 37MB compact edge model

Browse files
Files changed (2) hide show
  1. README.md +180 -67
  2. model_int8.onnx +2 -2
README.md CHANGED
@@ -1,113 +1,226 @@
1
  ---
2
  license: apache-2.0
3
  language:
4
- - zh
5
- - en
6
- tags:
7
- - medical
8
- - healthcare
9
- - sentence-transformers
10
- - clinical-nlp
11
- - fhir
12
- - traditional-chinese
13
- - modernbert
14
- - edge-ai
15
- pipeline_tag: feature-extraction
16
  library_name: sentence-transformers
 
 
 
 
 
 
 
 
17
  ---
18
 
19
- # IlhaEmbed: 台灣臨床與在地醫學語意嵌入模型
20
 
21
- [English](#english-summary) | [繁體中文說明](#繁體中文說明)
22
 
23
- **IlhaEmbed** 是專為台灣臨床病歷、護理紀錄、社區健檢表與衛教紀錄打造的高精度開源醫療語意嵌入向量模型系列。其將在地臨床行話、拉丁縮寫、中英夾雜速記以及繁體中文醫學術語投影至統一的語意空間,支援高精度的醫療數據前處理、分流(Intake Routing)與術語檢索推薦。
24
 
25
- 名稱源自 *Ilha Formosa*(美麗島),專門讀懂這座島嶼的臨床語言。
 
26
 
27
  ---
28
 
29
- ## 雙版本規格與基準 (Specifications & Benchmarks)
30
-
31
- | 指標/規格 | **IlhaEmbed-311M (Flagship)** | **IlhaEmbed-97M (Edge)** |
32
- |---|---:|---:|
33
- | **基底架構** | ModernBERT Base | Granite ModernBERT Lightweight |
34
- | **參數量** | 311 Million | 97 Million |
35
- | **向量維度** | 768-dim | 384-dim |
36
- | **INT8 ONNX 大小** | ~85 MB | **~133 MB** |
37
- | **推論延遲 (CPU 單筆)** | 12.5 ms | **3.9 ms** |
38
- | **16 類 FHIR 原型分流準確率** | **100.0% (44/44)** | **100.0% (44/44)** |
39
- | **處方藥典檢索 Top-1 (RxNorm)** | - | **85.99%** (Top-5: 94.97%) |
40
- | **跨源藥物檢索 Top-1 (DrugBank)** | - | **63.47%** (Top-5: 69.70%) |
41
- | **臨床速記檢索 Top-1 (Shorthand)** | **98.15% (106/108)** | **92.56% (112/121)** |
42
- | **在地俚語行話檢索 Top-1 (Slang)** | **95.2% (59/62)** | **95.16% (59/62)** |
43
- | **台語臨床語意檢索 Top-1 (Taigi)** | **96.5% (136/141)** | **93.62% (132/141)** |
44
 
45
  ---
46
 
47
- ## 快速開始 (Quick Start)
 
 
 
 
 
 
48
 
49
- ### 1. Python (Sentence-Transformers)
50
 
 
51
  ```python
52
  from sentence_transformers import SentenceTransformer
53
 
54
- # 載入模型(自動處理詞表與池化)
55
- model = SentenceTransformer("weemed/IlhaEmbed")
 
 
 
 
 
56
 
57
- queries = ["皮蛇", "帶狀皰疹", "114年成健", "定期心內門診-戒菸"]
58
- embeddings = model.encode(queries, normalize_embeddings=True)
 
 
 
59
 
60
- print("向量形狀:", embeddings.shape) # (4, 384)
61
- # 計算「皮蛇」與「帶狀皰疹」相似度
62
- sim = embeddings[0] @ embeddings[1]
63
- print("語意相似度:", sim)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
64
  ```
65
 
66
- ### 2. ONNX Runtime (CPU 邊緣極速推論)
 
 
 
 
 
 
 
67
 
68
- 模型已內嵌池化層,推論直接輸出 `sentence_embedding`:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
69
 
70
  ```python
71
  import numpy as np
72
  import onnxruntime as ort
73
  from transformers import AutoTokenizer
74
- from huggingface_hub import hf_hub_download
75
 
76
- tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed")
77
- onnx_path = hf_hub_download("weemed/IlhaEmbed", "model_int8.onnx")
78
- session = ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"])
79
 
80
- inputs = tokenizer(["皮蛇", "帶狀皰疹"], padding=True, truncation=True, return_tensors="np")
 
 
 
 
 
 
81
  feed = {
82
  "input_ids": inputs["input_ids"].astype(np.int64),
83
  "attention_mask": inputs["attention_mask"].astype(np.int64),
84
  }
85
-
86
- embeddings = session.run(["sentence_embedding"], feed)[0]
87
- # L2 歸一化
88
- embeddings = embeddings / np.linalg.norm(embeddings, axis=1, keepdims=True)
89
- print("ONNX 向量輸出:", embeddings.shape)
90
  ```
91
 
92
  ---
93
 
94
- ## 醫療使用宣告與安全邊界 (Intended Use)
95
 
96
- - **用途**:臨床輔助建議、數據攝取分流與術語檢索(Suggest-with-Review Candidate Ranker)。
97
- - **非醫材宣告**:本模型不具備自主診斷、處方或獨立決策功能。模型輸出之所有建議嚴禁未經合格醫事人員覆核直接作為臨床決策。
98
- - **資料合規**:模型全流程不包含任何可識別個人隱私(Zero PHI)。
99
 
100
  ---
101
 
102
- <a name="english-summary"></a>
103
-
104
- # English Summary
105
 
106
- **IlhaEmbed** is a domain-specific clinical text embedding model series designed for Traditional Chinese electronic health records (EHR), nursing notes, and medical terminologies in Taiwan.
 
 
 
107
 
108
- ### Key Highlights
109
- - **Specialized Vocabulary**: Accurately embeds Taiwan-specific clinical shorthand, Latin abbreviations, bilingual jargon, and colloquialisms.
110
- - **Dual Release**:
111
- - **311M (Flagship)**: ModernBERT base for server-side FHIR intent routing and re-ranking.
112
- - **97M (Edge)**: Ultra-lightweight ModernBERT optimized for on-device CPU / kiosk inference with multi-head attention pooling.
113
- - **License**: Apache-2.0.
 
1
  ---
2
  license: apache-2.0
3
  language:
4
+ - zh
5
+ - en
 
 
 
 
 
 
 
 
 
 
6
  library_name: sentence-transformers
7
+ pipeline_tag: sentence-similarity
8
+ tags:
9
+ - embeddings
10
+ - traditional-chinese
11
+ - medical
12
+ - taiwan
13
+ - onnx
14
+ base_model: ibm-granite/granite-embedding-97m-multilingual-r2
15
  ---
16
 
17
+ # IlhaEmbed v3 Dual Release: Flagship (311M) & Ultra-Lightweight Edge (97M)
18
 
19
+ [English](#ilhaembed-v3-dual-release-flagship-311m--ultra-lightweight-edge-97m) | [繁體中文說明](#繁體中文說明)
20
 
21
+ **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**:
22
 
23
+ 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.
24
+ 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.
25
 
26
  ---
27
 
28
+ ## Technical Specifications & Benchmark Comparison
29
+
30
+ | Metric / Specification | IlhaEmbed-311M (Flagship) | IlhaEmbed-97M (Ultra-Lightweight) | Release Gate / Baseline |
31
+ |---|---:|---:|---:|
32
+ | **Base Architecture** | ModernBERT Base | Granite ModernBERT Lightweight | - |
33
+ | **Parameters** | 311 Million | 97 Million | - |
34
+ | **Vector Dimension** | 768-dim | 384-dim | - |
35
+ | **INT8 ONNX Footprint** | ~85.4 MB | **37.28 MB** | ≤ 40 MB (for Edge) |
36
+ | **CPU Latency (Single / Batch-16)** | 12.5 ms / 3.4 ms | **3.97 ms / 1.7 ms** | ≤ 15 ms single |
37
+ | **16-Category FHIR Zero-Shot Routing** | **100.0% (44/44)** | **100.0% (44/44)** | ≥ 95.0% |
38
+ | **Clinical Shorthand Top-1** | **98.15% (106/108)** | 92.56% (112/121) | ≥ 90.0% |
39
+ | **Clinical Shorthand Top-5** | **100.0% (108/108)** | 97.52% (118/121) | ≥ 95.0% |
40
+ | **Colloquial / Slang Retrieval** | **95.2% (59/62)** | 95.2% (59/62) | ≥ 85.0% |
41
+ | **Bilingual Appositions** | **93.8% (348/371)** | 87.3% (324/371) | ≥ 80.0% |
42
+ | **Taigi Medical Semantics** | **96.5% (136/141)** | 94.3% (133/141) | ≥ 90.0% |
43
 
44
  ---
45
 
46
+ ## Safety & Regulatory Boundary (SaMD Exemption)
47
+
48
+ - **Intended Use**: Assistive terminology alignment, semantic routing, and candidate recommendation (Suggest-with-Review).
49
+ - **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.
50
+ - **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.
51
+
52
+ ---
53
 
54
+ ## Usage
55
 
56
+ ### 1. Flagship (311M) — Python / Sentence-Transformers
57
  ```python
58
  from sentence_transformers import SentenceTransformer
59
 
60
+ model = SentenceTransformer("weemed/IlhaEmbed-311M")
61
+ embeddings = model.encode(
62
+ ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
63
+ normalize_embeddings=True,
64
+ )
65
+ print(embeddings.shape) # (4, 768)
66
+ ```
67
 
68
+ ### 2. Edge (97M) — INT8 ONNX CPU Execution
69
+ ```python
70
+ import numpy as np
71
+ import onnxruntime as ort
72
+ from transformers import AutoTokenizer
73
 
74
+ tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
75
+ session = ort.InferenceSession(
76
+ "model_int8.onnx", providers=["CPUExecutionProvider"]
77
+ )
78
+
79
+ inputs = tokenizer(
80
+ ["皮蛇", "帶狀皰疹"],
81
+ max_length=32,
82
+ padding="max_length",
83
+ truncation=True,
84
+ return_tensors="np",
85
+ )
86
+ feed = {
87
+ "input_ids": inputs["input_ids"].astype(np.int64),
88
+ "attention_mask": inputs["attention_mask"].astype(np.int64),
89
+ }
90
+ outputs = session.run(["sentence_embedding"], feed)[0]
91
+ normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
92
+ print(normed.shape) # (2, 384)
93
  ```
94
 
95
+ ---
96
+
97
+ ## Data Governance & Open-Source Principles
98
+
99
+ 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.
100
+ 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.
101
+ 3. **No Proprietary Corpora Redistribution**: Copyrighted clinical articles and raw hospital document dumps are not redistributed (see `SOURCES.md`).
102
+ 4. **License**: Code and published weights are licensed under **Apache-2.0**.
103
 
104
+ ---
105
+
106
+ <a name="繁體中文說明"></a>
107
+
108
+ # IlhaEmbed (v3.0) 繁體中文完整說明
109
+
110
+ [English](#ilhaembed-v3-dual-release-flagship-311m--ultra-lightweight-edge-97m) | 繁體中文
111
+
112
+ **IlhaEmbed** 是專為台灣臨床病歷、護理紀錄、社區健檢表與衛教紀錄打造的高精度開源醫療語意嵌入向量模型系列。其將在地臨床行話、拉丁縮寫、中英夾雜速記以及繁體中文醫學術語投影至統一的語意空間,支援高精度的醫療數據攝取分流(Intake Routing)與術語檢索推薦。
113
+
114
+ 名稱源自 *Ilha Formosa*(美麗島),專門讀懂這座島嶼的臨床語言。
115
+
116
+ ---
117
+
118
+ ## 🌟 臨床痛點與核心升級亮點
119
+
120
+ 台灣各級醫療院所的電子病歷、護理交班、社區健檢表上充滿高度在地化的行話與臨床縮寫:
121
+ - `L-CT`:代表低劑量胸部電腦斷層(肺癌早期篩檢)。
122
+ - `MIF`:健檢報告中代表傷寒篩檢之糞便檢體未交。
123
+ - `皮蛇`:在地俚語俗稱,代表帶狀皰疹。
124
+ - `成健`:代表成人預防保健服務。
125
+ - `檳榔`:與菸酒並列之台灣本土重要社會史致癌危險因子。
126
+ - `定期心內門診-戒菸`:跨專科複合追蹤與衛教紀錄。
127
+ - `斷腦筋`:台語口語醫學語意,代表中風(腦中風)。
128
+
129
+ 通用大語言模型與一般中文語意嵌入模型對此類高度專業且具地域性的縮寫與行話識別率極低。**IlhaEmbed v3** 正式推出**雙版本發布體系**,滿足從雲端伺服器到邊緣低功耗設備之多樣化部署需求:
130
+
131
+ 1. **IlhaEmbed-311M(高容量旗艦版)**:
132
+ - 採用 ModernBERT Base (311M 參數),輸出 768 維度高品質向量。
133
+ - 全面鎖定 16 類 FHIR 資源語意原型(Condition, MedicationStatement, Encounter, Observation 等),在 16 類嚴格原型分流基準測試達到 **100.0% (44/44)** 零樣本準確率。
134
+ - 臨床速記與簡稱 Top-1 檢索率達 **98.15% (106/108)**,Top-5 達 **100.0%**。
135
+ - 適合部署於院區資料中心、伺服器端 Intake-Spine 數據前處理與高精度推薦重排。
136
+
137
+ 2. **IlhaEmbed-97M(超輕量邊緣版)**:
138
+ - 採用 Granite ModernBERT Lightweight (97M 參數),輸出 384 維度精簡向量。
139
+ - 經過 25.5k 繁體中文醫學專用詞表剪枝與標準算子 INT8 動態量化,模���檔案大小僅 **37.28 MB**,嚴格符合社區健康站與手持裝置 **<40 MB** 的邊緣硬體預算門禁。
140
+ - 在 16 類 FHIR 資源原型分流準確率同樣達到 **100.0% (44/44)**,行政管理字串防禦拒絕率達 100.0%,純 CPU 推論單筆延遲僅 **~3.97ms**(Batch-16 下每筆 1.7ms),真正做到容量縮減但精度不容許降級。
141
+ - 適合社區健檢站一體機(如 *The Mirror*)、離線醫療閘道器與瀏覽器 WebAssembly (WASM) 端執行。
142
+
143
+ ---
144
+
145
+ ## 📊 雙版本評測成效對照 (Benchmark Comparison)
146
+
147
+ | 評測維度/指標 | **IlhaEmbed-311M (Flagship)** | **IlhaEmbed-97M (Edge / Kiosk)** | 歷史開源基準 (jina/ckip/bge) | 發布門禁要求 |
148
+ |---|---:|---:|---:|---:|
149
+ | **基底模型架構** | ModernBERT Base | Granite ModernBERT Lightweight | - | Apache-2.0 |
150
+ | **參數量 (Params)** | 311 Million | 97 Million | - | - |
151
+ | **向量維度 (Dimension)** | 768-dim | 384-dim | 768 / 384-dim | - |
152
+ | **INT8 ONNX 檔案體積** | ~85.4 MB | **37.28 MB** | > 100 MB | ≤ 40 MB (邊緣端) |
153
+ | **CPU 推論延遲 (單筆 / Batch-16)** | 12.5 ms / 3.4 ms | **3.97 ms / 1.7 ms** | > 25 ms | ≤ 15 ms 單筆 |
154
+ | **16 類 FHIR 原型分流準確率** | **100.0% (44/44)** | **100.0% (44/44)** | < 30.0% | ≥ 95.0% |
155
+ | **臨床速記 Top-1 (Shorthand)** | **98.15% (106/108)** | 92.56% (112/121) | 0.0% ~ 14.0% | ≥ 90.0% |
156
+ | **臨床速記 Top-5** | **100.0% (108/108)** | 97.52% (118/121) | 5.0% ~ 30.0% | ≥ 95.0% |
157
+ | **俚語與行話檢索 (Slang)** | **95.2% (59/62)** | 95.2% (59/62) | 0.0% ~ 5.0% | ≥ 85.0% |
158
+ | **中英臨床同位語 (Apposition)** | **93.8% (348/371)** | 87.3% (324/371) | 33.0% ~ 45.0% | ≥ 80.0% |
159
+ | **台語臨床語意檢索 (Taigi)** | **96.5% (136/141)** | 94.3% (133/141) | 50.0% ~ 64.0% | ≥ 90.0% |
160
+
161
+ ---
162
+
163
+ ## 🚀 快速開始 (Quick Start)
164
+
165
+ ### 1. Python / Sentence-Transformers(支援雙版本)
166
+
167
+ ```python
168
+ from sentence_transformers import SentenceTransformer
169
+
170
+ # 載入 311M 旗艦版(伺服器端、FHIR 16 類零樣本分流與速記重排)
171
+ flagship = SentenceTransformer("weemed/IlhaEmbed-311M")
172
+ emb_flagship = flagship.encode(
173
+ ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
174
+ normalize_embeddings=True,
175
+ )
176
+ print("311M 向量維度:", emb_flagship.shape) # (4, 768)
177
+
178
+ # 載入 97M 超輕量版(輕量邊緣端推薦)
179
+ edge = SentenceTransformer("weemed/IlhaEmbed")
180
+ emb_edge = edge.encode(["皮蛇", "帶狀皰疹"], normalize_embeddings=True)
181
+ print("97M 向量維度:", emb_edge.shape) # (2, 384)
182
+ ```
183
+
184
+ ### 2. ONNX Runtime 純 CPU 地端極速部署(97M 邊緣端首選)
185
 
186
  ```python
187
  import numpy as np
188
  import onnxruntime as ort
189
  from transformers import AutoTokenizer
 
190
 
191
+ tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
192
+ session = ort.InferenceSession("model_int8.onnx", providers=["CPUExecutionProvider"])
 
193
 
194
+ inputs = tokenizer(
195
+ ["皮蛇", "帶狀皰疹"],
196
+ max_length=32,
197
+ padding="max_length",
198
+ truncation=True,
199
+ return_tensors="np",
200
+ )
201
  feed = {
202
  "input_ids": inputs["input_ids"].astype(np.int64),
203
  "attention_mask": inputs["attention_mask"].astype(np.int64),
204
  }
205
+ outputs = session.run(["sentence_embedding"], feed)[0]
206
+ normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
207
+ print("ONNX 輸出維度:", normed.shape) # (2, 384)
 
 
208
  ```
209
 
210
  ---
211
 
212
+ ## 🔒 醫療法規、SaMD 豁免與安全邊界
213
 
214
+ - **預期用途(Intended Use)**:臨床輔助建議、攝取分流與候選重排(Suggest-with-Review Candidate Ranker)。
215
+ - **非 SaMD 宣告(Non-SaMD Posture)**:依據台灣衛生福利部食品藥物管理署(TFDA)與國際醫療器材軟體(SaMD)法規指引,IlhaEmbed 不具備自主診斷、疾病處方或獨立醫療決策功能。模型輸出之所有建議與 FHIR 映射事實,**嚴禁未經醫師、護理師或合格醫事人員覆核即直接作為臨床處置或定稿病歷**。
216
+ - **Fail-Closed 殘差機制**:當模型餘弦相似度或分類邊界餘裕(Margin)低於安全閾值時,片段自動退回殘���隊列(Residue),由臨床人員介入審閱,防範模型幻覺或錯誤歸類產生虛假醫療事實。
217
 
218
  ---
219
 
220
+ ## 🛡️ 資料治理與開源邊界原則
 
 
221
 
222
+ 1. **零受保護健康資訊(Zero PHI)**:模型訓練與評測全流程不包含任何真實病患姓名、身分證號、病歷號或可識別隱私個資。
223
+ 2. **政府開放資料與公眾領域合規**:知識蒸餾訊號來自政府開放資料(數發部 MODA、國教院 NAER 13 大類學術醫療名詞庫)及《著作權法》第九條第一項第五款之公務考題。
224
+ 3. **嚴禁散布未授權語料**:本開源倉庫與模型權重不散布任何第三方付費商業術語辭庫或未授權醫學期刊論文全文。
225
+ 4. **授權條款**:開源程式碼與發布模型權重均採用 **Apache-2.0** 寬鬆開源授權。
226
 
 
 
 
 
 
 
model_int8.onnx CHANGED
@@ -1,3 +1,3 @@
1
  version https://git-lfs.github.com/spec/v1
2
- oid sha256:9da09372f38401938c6275e6641d6312ca52e3e08f4c15bbe696f4e89b61f295
3
- size 133463094
 
1
  version https://git-lfs.github.com/spec/v1
2
+ oid sha256:44cd7c10f351d4ac0ccc3e8424fe92bc9cb8e5f24f2e253eaf8fd72d530cd3b3
3
+ size 39364887