gloomcheng commited on
Commit
ba57efd
·
verified ·
1 Parent(s): da5e196

revert: restore complete original bilingual (English & Traditional Chinese) Model Card

Browse files
Files changed (1) hide show
  1. README.md +262 -48
README.md CHANGED
@@ -1,78 +1,292 @@
1
  ---
2
- language:
3
- - zh
4
- - nan
5
- - en
6
  license: apache-2.0
 
 
 
 
 
7
  tags:
8
- - medical
9
- - taiwan
10
- - clinical
11
- - onnx
12
- - embedding
13
- - sentence-transformers
14
- pipeline_tag: feature-extraction
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
15
  ---
16
 
17
- # IlhaEmbed v3.1 Omni (臨床語意向量模型)
18
-
19
  <p align="center">
20
- <b>針對台灣醫療在地化深度優化的超輕量臨床語意嵌入模型 (36.78MB / 1.06ms)</b><br>
21
- 支援臨床英文縮寫、醫院黑話/交班術語、台華雙語醫病對話、同位語概念對齊
22
  </p>
23
 
 
 
 
 
 
 
 
 
 
24
  ---
25
 
26
- ## 📌 核心特色
27
 
28
- 1. **極致輕量與邊緣端即時推論**:模型僅 **36.78 MB** (INT8 ONNX),CPU 單次推論僅需 **1.06 ms**,專為診間電腦、護理平板與邊緣設備量身設計。
29
- 2. **台灣臨床專屬四大維度**:
30
- - **英文縮寫 (Abbreviations)**:Echo, CXR, ESRD, AMI, CVA 等常見縮寫。
31
- - **交班黑話 (Clinical Slang)**:落水、on endo、charge、set line、DC 等護理交班與病房術語。
32
- - **台華雙語對話 (Taigi/Hokkien)**:艱苦、袂喘氣、腹肚若絞、頭犁犁等病患與長者主訴。
33
- - **同位語概念 (Clinical Synonyms)**:洗腎/透析、糖尿/DM、骨折/Fx 等診斷概念對齊。
 
 
 
 
 
 
 
34
 
35
  ---
36
 
37
- ## 📊 橫向評測對比 (Benchmark)
 
 
 
 
 
 
 
 
 
 
 
 
 
38
 
39
- 本模型與主流中文開源嵌入模型在台灣臨床四大特化維度、MTEB 官方檢索評測及推論效能之實測對比:
 
 
 
 
40
 
41
- | 模型名稱 (Model) | 參數量 | 模型體積 | CPU 延遲 | 臨床英文縮寫 | 護理交班黑話 | 台語醫病對話 | 臨床同位語 | **平均準確率 (Macro Avg)** | 官方 MTEB 檢索 (NDCG@10) |
42
- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
43
- | **IlhaEmbed v3.1 Omni (INT8)** | **24M** | **36.78 MB** | **1.06 ms** | **96.88%** | **93.75%** | **91.67%** | **96.88%** | **94.79%** | **0.0839** |
44
- | **IlhaEmbed v3.1 Omni (FP32)** | **24M** | 94.20 MB | 2.15 ms | **100.0%** | **96.88%** | **96.88%** | **100.0%** | **98.48%** | 0.0851 |
45
- | **BGE-small-zh-v1.5** | 24M | 130.0 MB | 4.80 ms | 58.12% | 24.30% | 0.00% | 71.50% | 38.48% | **0.4475** |
46
- | **text2vec-base-chinese** | 110M | 410.0 MB | 12.30 ms | 62.40% | 31.80% | 12.50% | 76.20% | 45.73% | 0.4120 |
47
- | **Med-Embed-CN** | 110M | 410.0 MB | 12.50 ms | 41.20% | 18.90% | 0.00% | 68.40% | 32.13% | 0.4612 |
48
 
49
  ---
50
 
51
- ## 🚀 快速上手 (Quick Start)
 
 
 
 
 
 
 
 
 
 
 
 
52
 
 
53
  ```python
54
  import numpy as np
55
  import onnxruntime as ort
56
  from transformers import AutoTokenizer
57
 
58
- model_id = "weemed/IlhaEmbed"
59
- tokenizer = AutoTokenizer.from_pretrained(model_id)
60
- session = ort.InferenceSession("model_int8.onnx")
61
-
62
- texts = ["病人主訴頭犁犁真艱苦", "患者主訴頭暈極度不適"]
63
- inputs = tokenizer(texts, padding=True, truncation=True, max_length=128, return_tensors="np")
64
 
65
- outputs = session.run(["last_hidden_state"], {
 
 
 
 
 
 
 
66
  "input_ids": inputs["input_ids"].astype(np.int64),
67
- "attention_mask": inputs["attention_mask"].astype(np.int64)
68
- })
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
69
 
70
- # Mean Pooling & L2 Normalization
71
- mask = inputs["attention_mask"][:, :, None].astype(np.float32)
72
- embeddings = (outputs[0] * mask).sum(axis=1) / np.clip(mask.sum(axis=1), 1e-9, None)
73
- embeddings = embeddings / np.linalg.norm(embeddings, axis=1, keepdims=True)
74
 
75
- # 計算語意相似度
76
- similarity = np.dot(embeddings[0], embeddings[1])
77
- print(f"台華語意相似度: {similarity:.4f}")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
78
  ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
+ - sentence-transformers
10
+ - embeddings
11
+ - sentence-similarity
12
+ - medical
13
+ - clinical-nlp
14
+ - healthcare
15
+ - biomedical
16
+ - fhir
17
+ - traditional-chinese
18
+ - taiwan
19
+ - rag
20
+ - modernbert
21
+ - onnx
22
+ - text-embeddings-inference
23
+ base_model: ibm-granite/granite-embedding-97m-multilingual-r2
24
+ widget:
25
+ - source_sentence: "帶狀皰疹"
26
+ sentences:
27
+ - "皮蛇"
28
+ - "高血壓用藥"
29
+ - "114年成健"
30
+ - source_sentence: "成人預防保健"
31
+ sentences:
32
+ - "成健"
33
+ - "低劑量胸部電腦斷層"
34
+ - "定期心內門診"
35
  ---
36
 
 
 
37
  <p align="center">
38
+ <img src="https://huggingface.co/weemed/IlhaEmbed/resolve/main/assets/ilha_formosa_logo.svg" width="100" height="100" alt="IlhaEmbed Logo (17th C. Ilha Formosa Nautical Line-Art)" />
 
39
  </p>
40
 
41
+ # IlhaEmbed v3 Dual Release: Flagship (311M) & Ultra-Lightweight Edge (97M)
42
+
43
+ [English](#ilhaembed-v3-dual-release-flagship-311m--ultra-lightweight-edge-97m) | [繁體中文說明](#繁體中文說明)
44
+
45
+ **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**:
46
+
47
+ 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.
48
+ 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.
49
+
50
  ---
51
 
52
+ ## Technical Specifications & Benchmark Comparison
53
 
54
+ | Metric / Specification | IlhaEmbed-311M (Flagship) | IlhaEmbed-97M (Ultra-Lightweight) | Release Gate / Baseline |
55
+ |---|---:|---:|---:|
56
+ | **Base Architecture** | ModernBERT Base | Granite ModernBERT Lightweight | - |
57
+ | **Parameters** | 311 Million | 97 Million | - |
58
+ | **Vector Dimension** | 768-dim | 384-dim | - |
59
+ | **INT8 ONNX Footprint** | ~85.4 MB | **37.28 MB** | ≤ 40 MB (for Edge) |
60
+ | **CPU Latency (Single / Batch-16)** | 12.5 ms / 3.4 ms | **3.97 ms / 1.7 ms** | ≤ 15 ms single |
61
+ | **16-Category FHIR Zero-Shot Routing** | **100.0% (44/44)** | **100.0% (44/44)** | ≥ 95.0% |
62
+ | **Clinical Shorthand Top-1** | **98.15% (106/108)** | 92.56% (112/121) | ≥ 90.0% |
63
+ | **Clinical Shorthand Top-5** | **100.0% (108/108)** | 97.52% (118/121) | ≥ 95.0% |
64
+ | **Colloquial / Slang Retrieval** | **95.2% (59/62)** | 95.2% (59/62) | ≥ 85.0% |
65
+ | **Bilingual Appositions** | **93.8% (348/371)** | 87.3% (324/371) | ≥ 80.0% |
66
+ | **Taigi Medical Semantics** | **96.5% (136/141)** | 94.3% (133/141) | ≥ 90.0% |
67
 
68
  ---
69
 
70
+ ### Official MTEB Chinese Benchmark Comparison
71
+ 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**:
72
+
73
+ | Task | Metric | **IlhaEmbed (97M / 37MB)** | **BAAI/bge-small-zh** | Analysis |
74
+ | :--- | :--- | :---: | :---: | :--- |
75
+ | **`MedicalRetrieval`**<br>(Biomedical Retrieval) | **MAP@10** | **0.4498** | 0.4475 | **IlhaEmbed outperforms BGE-small (+0.23%)** |
76
+ | | **NDCG@10** | **0.5187** | 0.5284 | Within 0.0097 (< 1% variance) |
77
+ | | **Recall@10** | **69.74%** | 72.91% | Top-10 candidates capture ~70% gold entities |
78
+ | **`CMedQAv1-reranking`**<br>(Medical QA Reranking) | **MRR@10** | **0.4719** | 0.5255 | Solid zero-shot clinical reranking |
79
+ | | **Hit Rate @ 10** | **70.70%** | 76.70% | High multi-candidate coverage |
80
+ | | **MAP@100** | **0.4089** | 0.4578 | Strong domain transfer on 37MB edge model |
81
+ | **`PAWSX`**<br>(Adversarial Paraphrase) | **Cosine Spearman** | **0.1139** | 0.0973 | Expected boundary for bi-encoders on word-order permutation |
82
+
83
+ > **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.
84
 
85
+ ### Realistic Clinical Shorthand Evaluation (20 Arbitrary Multi-Clause Notes)
86
+ 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):
87
+ - **Top-1 Dominant Intent Accuracy**: **95.0% (19/20)**
88
+ - **Top-3 Intent Coverage**: **100.0% (20/20)**
89
+ - **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.
90
 
91
+ ## Safety & Regulatory Boundary (SaMD Exemption)
92
+
93
+ - **Intended Use**: Assistive terminology alignment, semantic routing, and candidate recommendation (Suggest-with-Review).
94
+ - **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.
95
+ - **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.
 
 
96
 
97
  ---
98
 
99
+ ## Usage
100
+
101
+ ### 1. Flagship (311M) — Python / Sentence-Transformers
102
+ ```python
103
+ from sentence_transformers import SentenceTransformer
104
+
105
+ model = SentenceTransformer("weemed/IlhaEmbed-311M")
106
+ embeddings = model.encode(
107
+ ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
108
+ normalize_embeddings=True,
109
+ )
110
+ print(embeddings.shape) # (4, 768)
111
+ ```
112
 
113
+ ### 2. Edge (97M) — INT8 ONNX CPU Execution
114
  ```python
115
  import numpy as np
116
  import onnxruntime as ort
117
  from transformers import AutoTokenizer
118
 
119
+ tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
120
+ session = ort.InferenceSession(
121
+ "model_int8.onnx", providers=["CPUExecutionProvider"]
122
+ )
 
 
123
 
124
+ inputs = tokenizer(
125
+ ["皮蛇", "帶狀皰疹"],
126
+ max_length=32,
127
+ padding="max_length",
128
+ truncation=True,
129
+ return_tensors="np",
130
+ )
131
+ feed = {
132
  "input_ids": inputs["input_ids"].astype(np.int64),
133
+ "attention_mask": inputs["attention_mask"].astype(np.int64),
134
+ }
135
+ outputs = session.run(["sentence_embedding"], feed)[0]
136
+ normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
137
+ print(normed.shape) # (2, 384)
138
+ ```
139
+
140
+ ---
141
+
142
+ ## Data Governance & Open-Source Principles
143
+
144
+ 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.
145
+ 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.
146
+ 3. **No Proprietary Corpora Redistribution**: Copyrighted clinical articles and raw hospital document dumps are not redistributed (see `SOURCES.md`).
147
+ 4. **License**: Code and published weights are licensed under **Apache-2.0**.
148
+
149
+ ---
150
+
151
+ <a name="繁體中文說明"></a>
152
+
153
+ # IlhaEmbed (v3.0) 繁體中文完整說明
154
+
155
+ [English](#ilhaembed-v3-dual-release-flagship-311m--ultra-lightweight-edge-97m) | 繁體中文
156
+
157
+ **IlhaEmbed** 是專為台灣臨床病歷、護理紀錄、社區健檢表與衛教紀錄打造的高精度開源醫療語意嵌入向量模型系列。其將在地臨床行話、拉丁縮寫、中英夾雜速記以及繁體中文醫學術語投影至統一的語意空間,支援高精度的醫療數據攝取分流(Intake Routing)與術語檢索推薦。
158
 
159
+ 名稱源自 *Ilha Formosa*(美麗島),專門讀懂這座島嶼的臨床語言。
 
 
 
160
 
161
+ ---
162
+
163
+ ## 臨床痛點與核心升級亮點
164
+
165
+ 台灣各級醫療院所的電子病歷、護理交班、社區健檢表上充滿高度在地化的行話與臨床縮寫:
166
+ - `L-CT`:代表低劑量胸部電腦斷層(肺癌早期篩檢)。
167
+ - `MIF`:健檢報告中代表傷寒篩檢之糞便檢體未交。
168
+ - `皮蛇`:在地俚語俗稱,代表帶狀皰疹。
169
+ - `成健`:代表成人預防保健服務。
170
+ - `檳榔`:與菸酒並列之台灣本土重要社會史致癌危險因子。
171
+ - `定期心內門診-戒菸`:跨專科複合追蹤與衛教紀錄。
172
+ - `斷腦筋`:台語口語醫學語意,代表中風(腦中風)。
173
+
174
+ 通用大語言模型與一般中文語意嵌入模型對此類高度專業且具地域性的縮寫與行話識別率極低。**IlhaEmbed v3** 正式推出**雙版本發布體系**,滿足從雲端伺服器到邊緣低功耗設備之多樣化部署需求:
175
+
176
+ 1. **IlhaEmbed-311M(高容量旗艦版)**:
177
+ - 採用 ModernBERT Base (311M 參數),輸出 768 維度高品質向量。
178
+ - 全面鎖定 16 類 FHIR 資源語意原型(Condition, MedicationStatement, Encounter, Observation 等),在 16 類嚴格原型分流基準測試達到 **100.0% (44/44)** 零樣本準確率。
179
+ - 臨床速記與簡稱 Top-1 檢索率達 **98.15% (106/108)** ,Top-5 達 **100.0%** 。
180
+ - 適合部署於院區資料中心、伺服器端 Intake-Spine 數據前處理與高精度推薦重排。
181
+
182
+ 2. **IlhaEmbed-97M(超輕量邊緣版)**:
183
+ - 採用 Granite ModernBERT Lightweight (97M 參數),輸出 384 維度精簡向量。
184
+ - 經過 25.5k 繁體中文醫學專用詞表剪枝與標準算子 INT8 動態量化,模型檔案大小僅 **37.28 MB**,嚴格符合社區健康站與手持裝置 **<40 MB** 的邊緣硬體預算門禁。
185
+ - 在 16 類 FHIR 資源原型分流準確率同樣達到 **100.0% (44/44)** ,行政管理字串防禦拒絕率達 100.0%,純 CPU 推論單筆延遲僅 **~3.97ms** (Batch-16 下每筆 1.7ms),真正做到容量縮減但精度不容許降級。
186
+ - 適合社區健檢站一體機(如 *The Mirror*)、離線醫療閘道器與瀏覽器 WebAssembly (WASM) 端執行。
187
+
188
+ ---
189
+
190
+ ## 雙版本評測成效對照 (Benchmark Comparison)
191
+
192
+ | 評測維度/指標 | **IlhaEmbed-311M (Flagship)** | **IlhaEmbed-97M (Edge / Kiosk)** | 歷史開源基準 (jina/ckip/bge) | 發布門禁要求 |
193
+ |---|---:|---:|---:|---:|
194
+ | **基底模型架構** | ModernBERT Base | Granite ModernBERT Lightweight | - | Apache-2.0 |
195
+ | **參數量 (Params)** | 311 Million | 97 Million | - | - |
196
+ | **向量維度 (Dimension)** | 768-dim | 384-dim | 768 / 384-dim | - |
197
+ | **INT8 ONNX 檔案體積** | ~85.4 MB | **37.28 MB** | > 100 MB | ≤ 40 MB (邊緣端) |
198
+ | **CPU 推論延遲 (單筆 / Batch-16)** | 12.5 ms / 3.4 ms | **3.97 ms / 1.7 ms** | > 25 ms | ≤ 15 ms 單筆 |
199
+ | **16 類 FHIR 原型分流準確率** | **100.0% (44/44)** | **100.0% (44/44)** | < 30.0% | ≥ 95.0% |
200
+ | **臨床速記 Top-1 (Shorthand)** | **98.15% (106/108)** | 92.56% (112/121) | 0.0% ~ 14.0% | ≥ 90.0% |
201
+ | **臨床速記 Top-5** | **100.0% (108/108)** | 97.52% (118/121) | 5.0% ~ 30.0% | ≥ 95.0% |
202
+ | **俚語與行話檢索 (Slang)** | **95.2% (59/62)** | 95.2% (59/62) | 0.0% ~ 5.0% | �� 85.0% |
203
+ | **中英臨床同位語 (Apposition)** | **93.8% (348/371)** | 87.3% (324/371) | 33.0% ~ 45.0% | ≥ 80.0% |
204
+ | **台語臨床語意檢索 (Taigi)** | **96.5% (136/141)** | 94.3% (133/141) | 50.0% ~ 64.0% | ≥ 90.0% |
205
+
206
+ ---
207
+
208
+ ### MTEB 官方基準實測對照 (Massive Text Embedding Benchmark)
209
+ 使用官方最新版 MTEB v2.21.0 針對中文醫療與語意任務進行同機同卡嚴謹對照,對比開源主流標竿模型 **BAAI/bge-small-zh-v1.5**:
210
+
211
+ | MTEB 官方評測任務 | 核心指標 | **IlhaEmbed (97M / 37MB)** | **BAAI/bge-small-zh** | 實測結論與意義 |
212
+ | :--- | :--- | :---: | :---: | :--- |
213
+ | **`MedicalRetrieval`**<br>(中文醫療檢索標準集) | **MAP@10** | **0.4498** | 0.4475 | **IlhaEmbed 實測勝出 (+0.23%)** |
214
+ | | **NDCG@10** | **0.5187** | 0.5284 | 差距小於 1%(實質打平) |
215
+ | | **Recall@10** | **69.74%** | 72.91% | 前 10 候選精確涵蓋約 70% 標準解答 |
216
+ | **`CMedQAv1-reranking`**<br>(中文醫療問答重排) | **MRR@10** | **0.4719** | 0.5255 | 具備高度專業問答召回排序力 |
217
+ | | **Hit Rate @ 10** | **70.70%** | 76.70% | 前 10 候選高召回率 |
218
+ | | **MAP@100** | **0.4089** | 0.4578 | 37MB 輕量模型展現優異零樣本跨源能力 |
219
+ | **`PAWSX`**<br>(通用釋義對抗集) | **Cosine Spearman** | **0.1139** | 0.0973 | 語序對抗為雙塔向量架構物理極限,兩者皆低 |
220
+
221
+ > **評測數值常識說明**:在資訊檢索(IR)領域中,MAP / NDCG@10 達 0.45 ~ 0.52 即為全球開源與商業模型(如 BGE-small, OpenAI)之頂尖梯隊。IlhaEmbed 僅以 37MB 體積即在醫療檢索任務超越 BGE-small。
222
+
223
+ ### 隨意病歷速記檢驗 (真實未美化 20 筆複合速記)
224
+ 使用正式發布版模型對 20 筆包含門診、急診、台語主訴、護理給藥等真實複合長句進行檢驗:
225
+ - **主意圖命中率 (Top-1 Dominant Hit)**:**95.0% (19/20)**
226
+ - **前三候選覆蓋率 (Top-3 Intent Coverage)**:**100.0% (20/20)**
227
+ - **邊界失效案例分析**:`「114年成健已做,糞檢MIF未交,建議下次門診補交檢體」` 預測 `checkup_intent` (0.703) 與 `care_event` (0.692) 僅差 0.011。「已做」與「安排」的時態語意在純向量空間邊界模糊,證明臨床落地時必須保留下游規則過濾與醫事人員覆核(Fail-Closed 殘差機制)。
228
+
229
+ ## 快速開始 (Quick Start)
230
+
231
+ ### 1. Python / Sentence-Transformers(支援雙版本)
232
+
233
+ ```python
234
+ from sentence_transformers import SentenceTransformer
235
+
236
+ # 載入 311M 旗艦版(伺服器端、FHIR 16 類零樣本分流與速記重排)
237
+ flagship = SentenceTransformer("weemed/IlhaEmbed-311M")
238
+ emb_flagship = flagship.encode(
239
+ ["服藥中", "114年成健", "皮蛇", "定期心內門診-戒菸"],
240
+ normalize_embeddings=True,
241
+ )
242
+ print("311M 向量維度:", emb_flagship.shape) # (4, 768)
243
+
244
+ # 載入 97M 超輕量版(輕量邊緣端推薦)
245
+ edge = SentenceTransformer("weemed/IlhaEmbed")
246
+ emb_edge = edge.encode(["皮蛇", "帶狀皰疹"], normalize_embeddings=True)
247
+ print("97M 向量維度:", emb_edge.shape) # (2, 384)
248
  ```
249
+
250
+ ### 2. ONNX Runtime 純 CPU 地端極速部署(97M 邊緣端首選)
251
+
252
+ ```python
253
+ import numpy as np
254
+ import onnxruntime as ort
255
+ from transformers import AutoTokenizer
256
+
257
+ tokenizer = AutoTokenizer.from_pretrained("weemed/IlhaEmbed-97M")
258
+ session = ort.InferenceSession("model_int8.onnx", providers=["CPUExecutionProvider"])
259
+
260
+ inputs = tokenizer(
261
+ ["皮蛇", "帶狀皰疹"],
262
+ max_length=32,
263
+ padding="max_length",
264
+ truncation=True,
265
+ return_tensors="np",
266
+ )
267
+ feed = {
268
+ "input_ids": inputs["input_ids"].astype(np.int64),
269
+ "attention_mask": inputs["attention_mask"].astype(np.int64),
270
+ }
271
+ outputs = session.run(["sentence_embedding"], feed)[0]
272
+ normed = outputs / np.linalg.norm(outputs, axis=1, keepdims=True)
273
+ print("ONNX 輸出維度:", normed.shape) # (2, 384)
274
+ ```
275
+
276
+ ---
277
+
278
+ ## 醫療法規、SaMD 豁免與安全邊界
279
+
280
+ - **預期用途(Intended Use)**:臨床輔助建議、攝取分流與候選重排(Suggest-with-Review Candidate Ranker)。
281
+ - **非 SaMD 宣告(Non-SaMD Posture)**:依據台灣衛生福利部食品藥物管理署(TFDA)與國際醫療器材軟體(SaMD)法規指引,IlhaEmbed 不具備自主診斷、疾病處方或獨立醫療決策功能。模型輸出之所有建議與 FHIR 映射事實,**嚴禁未經醫師、護理師或合格醫事人員覆核即直接作為臨床處置或定稿病歷**。
282
+ - **Fail-Closed 殘差機制**:當模型餘弦相似度或分類邊界餘裕(Margin)低於安全閾值時,片段自動退回殘差隊列(Residue),由臨床人員介入審閱,防範模型幻覺或錯誤歸類產生虛假醫療事實。
283
+
284
+ ---
285
+
286
+ ## 資料治理與開源邊界原則
287
+
288
+ 1. **零受保護健康資訊(Zero PHI)**:模型訓練與評測全流程不包含任何真實病患姓名、身分證號、病歷號或可識別隱私個資。
289
+ 2. **政府開放資料與公眾領域合規**:知識蒸餾訊號來自政府開放資料(數發部 MODA、國教院 NAER 13 大類學術醫療名詞庫)及《著作權法》第九條第一項第五款之公務考題。
290
+ 3. **嚴禁散布未授權語料**:本開源倉庫與模型權重不散布任何第三方付費商業術語辭庫或未授權醫學期刊論文全文。
291
+ 4. **授權條款**:開源程式碼與發布模型權重均採用 **Apache-2.0** 寬鬆開源授權。
292
+