model card: natural voice, no em-dashes, real numbers

README.md

@@ -19,70 +19,55 @@ base_model: ibm-granite/granite-embedding-97m-multilingual-r2
 
 # IlhaEmbed
 
-**English** | [**繁體中文**](#繁體中文)
+A small embedding model that reads Taiwanese clinical text.
 
-**The clinical embedding model that reads how Taiwan actually writes medicine.**
+These are words that clinical staff in Taiwan actually write in charts, remarks, and community-care sheets. 斷腦筋 means stroke. 不辣咖 means a blood culture. H/T is hypertension, and V(H/T) means the patient is seen at an outside clinic for hypertension. General-purpose models and general Chinese models read none of these, because they never learned how doctors, nurses, and care workers in Taiwan really write. IlhaEmbed learned it.
 
-`斷腦筋` is a stroke. `不辣咖` is a blood culture. `H/T` is hypertension, `V(H/T)` means the patient
-attends an outside clinic *for* hypertension. Generic and general-Chinese embedders read none of these —
-they were never trained on how Taiwanese clinicians, nurses, and care workers really write in charts,
-remarks, and community-care sheets. **IlhaEmbed was.**
-
-*Ilha* — from *Ilha Formosa*, "beautiful island." An embedder that understands this island's clinical
-mother tongue.
+The name comes from Ilha Formosa. It is an embedder for this island's clinical language.
 
 ## Why IlhaEmbed
 
-| | What it means for you |
-|---|---|
-| 🩺 **Reads Taiwan's clinical language** | Slang, abbreviations, Taigi, hand-written remark shorthand — the dirty free-text in every real Taiwanese medical record. Where a generic embedder returns noise, IlhaEmbed returns the right concept. |
-| 🔒 **Runs fully on-premise** | 37 MB, INT8, CPU-only ONNX. No GPU, no cloud, no API key — **no patient data ever leaves the hospital.** Built for the offline reality of clinical infrastructure. |
-| 🧾 **Transparent, auditable lineage** | Apache-2.0 weights, a documented base model (IBM Granite ModernBERT), and a fully traceable training pipeline. Provenance you can hand to a procurement or infosec review, not a black box. |
-| 🪶 **Open and commercial-ready** | Apache-2.0 — use it, ship it, embed it in a product, no copyleft strings. |
+- **Reads Taiwan's clinical language.** Slang, abbreviations, Taigi, the handwritten shorthand in real records. Where a general model returns noise, this one returns the right concept.
+- **Runs fully on-premise.** 37 MB, INT8, CPU only. No GPU, no cloud, no API key. Patient data never leaves the hospital.
+- **Transparent lineage.** Apache-2.0 weights, a documented base model (IBM Granite ModernBERT), and a training pipeline you can trace. Provenance you can hand to a procurement or security review, not a black box.
+- **Open and commercial-ready.** Apache-2.0, with no copyleft obligations.
 
-## What it's for
+## What it is for
 
-IlhaEmbed turns messy Taiwanese clinical text into structured meaning. Drop-in for:
+IlhaEmbed turns messy Taiwanese clinical text into structured meaning. Common uses:
 
-- **Clinical text normalization** — map free-text abbreviations/slang to canonical concepts (`H/T` → 高血壓).
-- **Dirty-data → structured routing** — the semantic layer of an importer that reads a spreadsheet cell and routes each fact to its correct home (medication, condition, care source…).
-- **Terminology / code matching** — retrieve the right ICD / LOINC / drug concept for a surface term.
-- **De-siloing search** — find the record from the clue a nurse actually has, not the exact field name.
+- Clinical text normalization: mapping free-text abbreviations and slang to standard concepts (H/T to 高血壓).
+- Routing dirty data into structured fields: the semantic layer of an importer that reads a spreadsheet cell and sends each fact to its correct home (medication, condition, care source, and so on).
+- Terminology and code matching: retrieving the right ICD, LOINC, or drug concept for a surface term.
+- Cross-boundary search: finding a record from the clue a nurse actually has, not the exact field name.
 
-It is the normalization layer of a fully Taiwan-origin clinical pipeline:
-**`Breeze-ASR-26` (speech) → `IlhaEmbed` (meaning) → `FHIR` (structure).**
+It is the normalization layer of a clinical pipeline built entirely in Taiwan: Breeze-ASR-26 for speech, IlhaEmbed for meaning, FHIR for structure.
 
 ## Benchmarks
 
-**Task: jargon top-1** — given a Taiwan-clinical surface term, retrieve its canonical clinical concept
-from a combined concept pool. Each register (slang, abbreviation, apposition) is held out separately;
-self-matches excluded; macro-averaged over registers. Same methodology and pool for every model.
+Task: jargon top-1. Given a Taiwanese clinical surface term, retrieve its standard clinical concept from a combined concept pool. Each register (slang, abbreviation, apposition) is held out separately, self-matches are excluded, and the score is macro-averaged. Every model uses the same method and the same pool.
 
-| Model | Deployable on-prem | slang | abbrev | apposition | **jargon top-1 (macro)** |
+| Model | On-prem | slang | abbrev | apposition | jargon top-1 (macro) |
 |---|---|---|---|---|---|
-| **IlhaEmbed** | ✅ 37 MB CPU | **0.84** | **0.82** | **0.90** | **0.85** |
-| jina-embeddings-v2-base-zh | ❌ | 0.06 | 0.14 | 0.45 | 0.22 |
-| ckip-base | ✅ | 0.00 | 0.01 | 0.36 | 0.12 |
-| bge-small-zh | ✅ | 0.00 | 0.00 | 0.33 | 0.11 |
+| **IlhaEmbed** | yes, 37 MB CPU | **0.84** | **0.82** | **0.90** | **0.85** |
+| jina-embeddings-v2-base-zh | no | 0.06 | 0.14 | 0.45 | 0.22 |
+| ckip-base | yes | 0.00 | 0.01 | 0.36 | 0.12 |
+| bge-small-zh | yes | 0.00 | 0.00 | 0.33 | 0.11 |
 
-**~4× the best general model, ~8× bge** — on exactly the vocabulary generic and general-Chinese embedders
-were never trained to read. We do **not** claim to top general leaderboards (MTEB): IlhaEmbed is a
-*specialist* that wins where generic models fail, while staying small enough to run on the ward.
+That is about four times the best general model and about eight times bge, on exactly the vocabulary those models were never trained to read. IlhaEmbed does not aim to top general leaderboards such as MTEB. It is a specialist: it wins where general models fail, and it is small enough to run on the ward.
 
-*(Evaluation methodology described above; the register-held-out protocol is reproducible. The raw
-evaluation pairs carry third-party copyright and are not redistributed. A dedicated Han-Taigi →
-standard-concept benchmark is in progress and reported separately once its concept mapping is clean.)*
+The register-held-out method above is reproducible. The raw evaluation pairs carry third-party copyright and are not redistributed. A separate Han-Taigi to standard-concept benchmark is in progress and will be reported once its concept mapping is clean.
 
 ## Usage
 
 ```python
-# ONNX (deployment path — no torch, CPU)
+# ONNX (deployment path, no torch, CPU)
 from tokenizers import Tokenizer
 import onnxruntime as ort, numpy as np
 
 tok = Tokenizer.from_file("tokenizer.json")
 sess = ort.InferenceSession("model_int8.onnx")
-# ... encode (max_len 32), run, mean-pool, L2-normalize → 384-d vector
+# encode (max_len 32), run, mean-pool, L2-normalize, giving a 384-d vector
 ```
 
 ```python
@@ -92,23 +77,21 @@ model = SentenceTransformer("weemed/IlhaEmbed")
 model.encode(["斷腦筋", "H/T", "定期心內門診-戒菸"])
 ```
 
-- **Dimensions:** 384 · **Max sequence:** 32 tokens · **Vocab:** 25.5k (pruned to Traditional-Chinese + clinical) · **Size:** 37 MB (INT8 ONNX) / 152 MB (fp32 safetensors).
+Dimensions: 384. Max sequence: 32 tokens. Vocab: 25.5k (pruned to Traditional Chinese and clinical). Size: 37 MB (INT8 ONNX) or 152 MB (fp32 safetensors).
 
 ## How it was built
 
-- **Base:** IBM Granite ModernBERT (Apache-2.0) — a transparent, permissively-licensed foundation.
-- **Distillation:** a Taiwan-clinical teacher signal supplies the domain knowledge; the student learns to place Taiwanese slang, abbreviations, and Taigi near their canonical concepts.
-- **Vocabulary pruning:** the base 180k multilingual BPE vocab was pruned to the 25.5k tokens Traditional-Chinese clinical text actually uses — a **68% size cut (117 MB → 37 MB) with zero accuracy loss** (jargon top-1 held; real-pipeline routing bit-identical).
+The base model is IBM Granite ModernBERT (Apache-2.0), a permissively licensed foundation. A Taiwanese clinical teacher signal supplies the domain knowledge through knowledge distillation, so the student learns to place Taiwanese slang, abbreviations, and Taigi near their standard concepts.
 
-## Intended use & limitations
+The base model ships a 180k multilingual BPE vocabulary, most of which Traditional Chinese clinical text never uses. We pruned it to the 25.5k tokens that actually appear, which cut the size by 68 percent (117 MB to 37 MB) with no loss of accuracy: jargon top-1 held, and real-pipeline routing stayed bit-identical.
 
-IlhaEmbed is a **semantic representation tool**, not a diagnostic system. It surfaces likely meanings and matches for a human to confirm — it must never auto-decide clinical facts without review. It is tuned for Traditional-Chinese Taiwanese clinical text; general or Simplified-Chinese prose is out of scope.
+## Intended use and limits
 
-## License & citation
+IlhaEmbed is a tool for semantic representation, not a diagnostic system. It surfaces likely meanings and matches for a person to confirm; it must never decide clinical facts on its own without review. It is tuned for Traditional Chinese clinical text in Taiwan. General prose or Simplified Chinese is out of scope.
 
-Apache-2.0. Base model: IBM Granite (Apache-2.0). Training-pair sources documented in `SOURCES.md`; the released weights are a distributable derivative, the raw third-party pairs are not redistributed.
+## License and citation
 
-*IlhaEmbed — reads the clinical mother tongue of this island.*
+Apache-2.0. Base model: IBM Granite (Apache-2.0). Training-pair sources are documented in `SOURCES.md`. The released weights are a distributable derivative; the raw third-party pairs are not redistributed.
 
 ---
 
@@ -118,59 +101,55 @@ Apache-2.0. Base model: IBM Granite (Apache-2.0). Training-pair sources document
 
 [**English**](#ilhaembed) | **繁體中文**
 
-**讀得懂台灣臨床怎麼寫的語意模型。**
+一個讀得懂台灣臨床文字的小型語意模型。
 
-`斷腦筋` 是中風。`不辣咖` 是血液培養。`H/T` 是高血壓，`V(H/T)` 是這位病人在外院看高血壓。通用模型與一般中文
-模型全都讀不懂——它們從沒學過台灣的醫師、護理師、照服員真正怎麼在病歷、備註、社區照護表上書寫。**IlhaEmbed 學過。**
+以下這些是台灣臨床人員實際會寫在病歷、備註、社區照護表上的詞。斷腦筋是中風。不辣咖是血液培養。H/T是高血壓，V(H/T)是這位病人在外院看高血壓。通用模型與一般中文模型全都讀不懂，因為它們從沒學過台灣的醫師、護理師、照服員真正怎麼書寫。IlhaEmbed學過。
 
-*Ilha* 取自 *Ilha Formosa*（美麗島）。一顆讀得懂這座島臨床母語的語意模型。
+名字取自Ilha Formosa（美麗島）。它是一個讀這座島臨床語言的語意模型。
 
-## 為什麼選 IlhaEmbed
+## 為什麼選IlhaEmbed
 
-| | 對你的意義 |
-|---|---|
-| 🩺 **讀得懂台灣臨床語言** | 行話、縮寫、台語、手寫備註簡寫——每一份真實台灣病歷裡的髒 free-text。通用模型讀成雜訊的地方，IlhaEmbed 讀出正確概念。 |
-| 🔒 **完全地端執行** | 37 MB、INT8、純 CPU ONNX。免 GPU、免雲端、免 API key——**病人資料永不離開醫院。** 為臨床基礎設施的離線現實而生。 |
-| 🧾 **透明可稽核的血統** | Apache-2.0 權重、有文件的底模（IBM Granite ModernBERT）、可完整追溯的訓練管線。是可以交給採購與資安審查的來源證明，不是黑盒子。 |
-| 🪶 **開源且可商用** | Apache-2.0——自己用、包進產品、隨貨出貨都行，沒有 copyleft 綁約。 |
+- **讀得懂台灣臨床語言。** 行話、縮寫、台語、手寫備註簡寫，都是真實病歷裡的文字。通用模型讀成雜訊的地方，它讀出正確概念。
+- **完全地端執行。** 37 MB、INT8、純CPU。免GPU、免雲端、免API key。病人資料不離開醫院。
+- **透明的血統。** Apache-2.0權重、有文件的底模（IBM Granite ModernBERT）、可追溯的訓練管線。是可以交給採購與資安審查的來源證明，不是黑盒子。
+- **開源且可商用。** Apache-2.0，沒有copyleft綁約。
 
 ## 用來做什麼
 
-IlhaEmbed 把凌亂的台灣臨床文字轉成結構化的意義。可直接用於：
+IlhaEmbed把凌亂的台灣臨床文字轉成結構化的意義。常見用途：
 
-- **臨床文字正規化**——把 free-text 縮寫／行話對應到標準概念（`H/T` → 高血壓）。
-- **髒資料 → 結構化路由**——匯入器的語意層：讀一格試算表、把每個事實路由到它正確的歸宿（用藥、疾病、就醫來源…）。
-- **術語／代碼比對**——為一個表面詞找到正確的 ICD／LOINC／藥品概念。
-- **打破資訊孤島的搜尋**——用護理師手上真正有的線索找到紀錄，而不是要求精確欄位名。
+- 臨床文字正規化：把free-text縮寫與行話對應到標準概念（H/T對到高血壓）。
+- 把髒資料路由到結構化欄位：匯入器的語意層，讀一格試算表、把每個事實送到正確的歸宿（用藥、疾病、就醫來源等）。
+- 術語與代碼比對：為一個表面詞找到正確的ICD、LOINC或藥品概念。
+- 跨界搜尋：用護理師手上真正有的線索找到紀錄，而不是要求精確欄位名。
 
-它是一條**全台灣血統**臨床管線的正規化層：
-**`Breeze-ASR-26`（聽音）→ `IlhaEmbed`（理解）→ `FHIR`（結構）。**
+它是一條完全在台灣打造的臨床管線的正規化層：Breeze-ASR-26聽音，IlhaEmbed理解，FHIR結構化。
 
 ## 效能指標
 
-**任務：jargon top-1**——給一個台灣臨床表面詞，於合併概念池中檢索其標準臨床概念。各語域（行話 slang／縮寫 abbrev／同位語 apposition）分別留出、排除自我匹配、macro 平均；所有模型使用同一方法學與同一概念池。
+任務：jargon top-1。給一個台灣臨床表面詞，於合併概念池中檢索其標準臨床概念。各語域（行話、縮寫、同位語）分別留出、排除自我匹配、macro平均。所有模型使用同一方法與同一概念池。
 
-| 模型 | 可地端部署 | slang | abbrev | apposition | jargon top-1（macro） |
+| 模型 | 可地端 | slang | abbrev | apposition | jargon top-1（macro） |
 |---|---|---|---|---|---|
-| **IlhaEmbed** | ✅ 37 MB CPU | **0.84** | **0.82** | **0.90** | **0.85** |
-| jina-embeddings-v2-base-zh | ❌ | 0.06 | 0.14 | 0.45 | 0.22 |
-| ckip-base | ✅ | 0.00 | 0.01 | 0.36 | 0.12 |
-| bge-small-zh | ✅ | 0.00 | 0.00 | 0.33 | 0.11 |
+| **IlhaEmbed** | 是，37 MB CPU | **0.84** | **0.82** | **0.90** | **0.85** |
+| jina-embeddings-v2-base-zh | 否 | 0.06 | 0.14 | 0.45 | 0.22 |
+| ckip-base | 是 | 0.00 | 0.01 | 0.36 | 0.12 |
+| bge-small-zh | 是 | 0.00 | 0.00 | 0.33 | 0.11 |
 
-**約為最佳通用模型的 4 倍、bge 的近 8 倍**——就贏在通用與一般中文模型從未學過的在地詞彙。我們**不宣稱**在通用排行榜（MTEB）霸榜：IlhaEmbed 是**專科模型**，只贏在通用模型會爆掉的地方，同時小到能在病房裡跑。
+約為最佳通用模型的四倍、bge的近八倍，就贏在那些模型從沒學過的在地詞彙。IlhaEmbed不以在通用排行榜（MTEB）霸榜為目標。它是專科模型：只贏在通用模型會爆掉的地方，同時小到能在病房裡跑。
 
-*（評估方法學如上，register-held-out 協定可重現；原始評估配對含第三方著作權，不隨附散佈。專門的「漢字台語→標準概念」基準進行中。）*
+上述register-held-out方法可重現。原始評估配對含第三方著作權，不隨附散佈。專門的「漢字台語對到標準概念」基準進行中，待概念對應乾淨後另行報告。
 
 ## 使用方式
 
 ```python
-# ONNX（部署路徑——免 torch、CPU）
+# ONNX（部署路徑，免torch、CPU）
 from tokenizers import Tokenizer
 import onnxruntime as ort, numpy as np
 
 tok = Tokenizer.from_file("tokenizer.json")
 sess = ort.InferenceSession("model_int8.onnx")
-# ... 編碼（max_len 32）、推論、mean-pool、L2 normalize → 384 維向量
+# 編碼（max_len 32）、推論、mean-pool、L2 normalize，得到384維向量
 ```
 
 ```python
@@ -180,20 +159,18 @@ model = SentenceTransformer("weemed/IlhaEmbed")
 model.encode(["斷腦筋", "H/T", "定期心內門診-戒菸"])
 ```
 
-- **維度：** 384 · **最大序列：** 32 tokens · **詞表：** 25.5k（剪枝至繁中＋臨床）· **大小：** 37 MB（INT8 ONNX）／152 MB（fp32 safetensors）。
+維度：384。最大序列：32 tokens。詞表：25.5k（剪枝至繁體中文與臨床）。大小：37 MB（INT8 ONNX）或152 MB（fp32 safetensors）。
 
 ## 怎麼做出來的
 
-- **底模：** IBM Granite ModernBERT（Apache-2.0）——透明、寬鬆授權的基礎。
-- **蒸餾：** 由台灣臨床 teacher 訊號提供領域知識；學生學會把台灣行話、縮寫、台語擺到它們的標準概念旁邊。
-- **詞彙剪枝：** 把底模 180k 的多語 BPE 詞表剪到繁中臨床文字真正會用到的 25.5k token——**體積砍 68%（117 MB → 37 MB）、準確度零損**（jargon top-1 不掉；真實管線路由逐位一致）。
+底模是IBM Granite ModernBERT（Apache-2.0），一個寬鬆授權的基礎。由台灣臨床teacher訊號透過知識蒸餾提供領域知識，讓學生學會把台灣行話、縮寫、台語擺到它們的標準概念旁邊。
+
+底模原帶18萬詞的多語BPE詞表，其中大多數繁中臨床文字用不到。我們把它剪到實際會用到的25.5k token，體積因此減少68%（117 MB到37 MB），且準確度零損：jargon top-1不掉，真實管線路由逐位一致。
 
 ## 適用範圍與限制
 
-IlhaEmbed 是**語意表示工具**，不是診斷系統。它浮現可能的意義與比對供人確認——絕不可在未經審核下自動判定臨床事實。它為繁體中文的台灣臨床文字調校；一般或簡體中文散文不在範圍內。
+IlhaEmbed是語意表示工具，不是診斷系統。它浮現可能的意義與比對供人確認，絕不可在未經審核下自行判定臨床事實。它為台灣的繁體中文臨床文字調校。一般散文或簡體中文不在範圍內。
 
 ## 授權與引用
 
-Apache-2.0。底模：IBM Granite（Apache-2.0）。訓練配對來源記於 `SOURCES.md`；釋出的權重是可散佈的衍生作，原始第三方配對不隨附散佈。
-
-*IlhaEmbed——讀得懂這座島的臨床母語。*
+Apache-2.0。底模：IBM Granite（Apache-2.0）。訓練配對來源記於`SOURCES.md`。釋出的權重是可散佈的衍生作，原始第三方配對不隨附散佈。