rewrite: natural Taiwan wording, understated tone, correct spacing

README.md

@@ -19,35 +19,35 @@ base_model: ibm-granite/granite-embedding-97m-multilingual-r2
 
 # IlhaEmbed
 
-**English** | [**繁體中文**](#繁體中文)
+English | [繁體中文](#繁體中文)
 
-A small embedding model that reads Taiwanese clinical text.
+A small embedding model for Taiwanese clinical text.
 
-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.
+Clinical records in Taiwan are full of local shorthand. 斷腦筋 means stroke, 不辣咖 means a blood culture, H/T is hypertension, and V(H/T) means the patient is followed for hypertension at an outside clinic. General-purpose and general Chinese models mostly miss these, because they never saw how doctors, nurses, and care workers in Taiwan actually write. IlhaEmbed was trained for it.
 
-The name comes from Ilha Formosa. It is an embedder for this island's clinical language.
+The name is from Ilha Formosa. It reads this island's clinical language.
 
-## Why IlhaEmbed
+## Highlights
 
-- **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.
+- **Reads local clinical writing.** Slang, abbreviations, Taigi, handwritten shorthand. Where a general model returns noise, this one usually returns the right concept.
+- **Runs on-premise.** 37 MB, INT8, CPU only. No GPU, no cloud, no API key. Patient data stays in the hospital.
+- **Clear provenance.** Apache-2.0 weights, a public and documented base model (IBM Granite ModernBERT), and a pipeline you can trace. Ready for a procurement or security review.
+- **Open and commercial-friendly.** Apache-2.0, no copyleft.
 
 ## What it is for
 
-IlhaEmbed turns messy Taiwanese clinical text into structured meaning. Common uses:
+Turning messy clinical text into structured meaning. Common uses:
 
-- 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.
+- Normalizing clinical text: mapping abbreviations and slang to standard concepts (H/T to 高血壓).
+- Placing dirty data: on import, reading one cell and sending each fact to the field it belongs in (medication, condition, care source, and so on).
+- Matching terms and codes: finding the right ICD, LOINC, or drug concept for a surface term.
+- Searching across fields: finding a record from the clue at hand, without knowing the exact field name.
 
-It is the normalization layer of a clinical pipeline built entirely in Taiwan: Breeze-ASR-26 for speech, IlhaEmbed for meaning, FHIR for structure.
+In a clinical pipeline built in Taiwan, it handles the "understanding" step: Breeze-ASR-26 for speech, IlhaEmbed for meaning, FHIR for structure.
 
-## Benchmarks
+## Results
 
-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.
+Task: jargon top-1. Given a Taiwanese clinical surface term, retrieve its standard concept from a combined pool. Slang, abbreviation, and apposition are each held out separately, self-matches excluded, scores macro-averaged. All four models use the same method and the same pool.
 
 | Model | On-prem | slang | abbrev | apposition | jargon top-1 (macro) |
 |---|---|---|---|---|---|
@@ -56,9 +56,9 @@ Task: jargon top-1. Given a Taiwanese clinical surface term, retrieve its standa
 | ckip-base | yes | 0.00 | 0.01 | 0.36 | 0.12 |
 | bge-small-zh | yes | 0.00 | 0.00 | 0.33 | 0.11 |
 
-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.
+On these local terms the general and general-Chinese models mostly return nothing; this model finds the right concept. It is not meant to top general leaderboards such as MTEB. It does one thing, Taiwanese clinical vocabulary, and it is small enough to run on the ward.
 
-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.
+The method is reproducible. The raw evaluation pairs carry third-party copyright and are not redistributed. A separate Han-Taigi to standard-concept benchmark is still in progress, and will be added once its concept mapping is clean.
 
 ## Usage
 
@@ -79,21 +79,21 @@ model = SentenceTransformer("weemed/IlhaEmbed")
 model.encode(["斷腦筋", "H/T", "定期心內門診-戒菸"])
 ```
 
-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).
+384 dimensions, up to 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
 
-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.
+The base model is IBM Granite ModernBERT (Apache-2.0), permissively licensed. A Taiwanese clinical teacher signal supplies the domain knowledge through knowledge distillation, so the student learns to place Taiwanese slang, abbreviations, and Taigi next to their standard concepts.
 
-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.
+The base model ships a 180k multilingual BPE vocabulary, most of which Traditional Chinese clinical text never uses. Pruning it to the 25.5k tokens that actually appear cut the size by 68 percent (117 MB to 37 MB) with no loss of accuracy: jargon top-1 held, and the real import routing came out bit-identical.
 
 ## Intended use and limits
 
-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.
+This is a tool for semantic representation, not a diagnostic system. It offers likely meanings and matches for a person to confirm, and does not decide clinical facts on its own. It is tuned for Traditional Chinese clinical text in Taiwan. General prose and Simplified Chinese are out of scope.
 
-## License and citation
+## License
 
-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.
+Apache-2.0. Base model: IBM Granite (Apache-2.0). Training-pair sources are listed in `SOURCES.md`. What we release is the trained weights, a distributable derivative; the raw third-party pairs are not included.
 
 ---
 
@@ -101,57 +101,57 @@ Apache-2.0. Base model: IBM Granite (Apache-2.0). Training-pair sources are docu
 
 # IlhaEmbed（繁體中文）
 
-[**English**](#ilhaembed) | **繁體中文**
+[English](#ilhaembed) | 繁體中文
 
 一個讀得懂台灣臨床文字的小型語意模型。
 
-以下這些是台灣臨床人員實際會寫在病歷、備註、社區照護表上的詞。斷腦筋是中風。不辣咖是血液培養。H/T是高血壓，V(H/T)是這位病人在外院看高血壓。通用模型與一般中文模型全都讀不懂，因為它們從沒學過台灣的醫師、護理師、照服員真正怎麼書寫。IlhaEmbed學過。
+台灣的病歷、備註、社區照護表上，有很多在地的寫法。斷腦筋是中風，不辣咖是血液培養，H/T 是高血壓，V(H/T) 是這位病人在外院追蹤高血壓。這些寫法，通用模型和一般中文模型多半讀不出來，因為它們沒看過台灣的醫師、護理師、照服員實際怎麼寫。IlhaEmbed 是針對這件事訓練的。
 
-名字取自Ilha Formosa（美麗島）。它是一個讀這座島臨床語言的語意模型。
+名字取自 Ilha Formosa。它專門讀這座島的臨床語言。
 
-## 為什麼選IlhaEmbed
+## 特點
 
-- **讀得懂台灣臨床語言。** 行話、縮寫、台語、手寫備註簡寫，都是真實病歷裡的文字。通用模型讀成雜訊的地方，它讀出正確概念。
-- **完全地端執行。** 37 MB、INT8、純CPU。免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把凌亂的台灣臨床文字轉成結構化的意義。常見用途：
+把凌亂的臨床文字整理成有結構的意義。常見的用法：
 
-- 臨床文字正規化：把free-text縮寫與行話對應到標準概念（H/T對到高血壓）。
-- 把髒資料路由到結構化欄位：匯入器的語意層，讀一格試算表、把每個事實送到正確的歸宿（用藥、疾病、就醫來源等）。
-- 術語與代碼比對：為一個表面詞找到正確的ICD、LOINC或藥品概念。
-- 跨界搜尋：用護理師手上真正有的線索找到紀錄，而不是要求精確欄位名。
+- 臨床文字正規化：把縮寫、行話對到標準概念（H/T 對到高血壓）。
+- 髒資料歸位：匯入時讀一格內容，把裡面每個事實送到該去的欄位（用藥、疾病、就醫來源等）。
+- 術語、代碼比對：幫一個詞找到對應的 ICD、LOINC 或藥品概念。
+- 跨欄位搜尋：用手上僅有的線索找到紀錄，不必先知道正確的欄位名稱。
 
-它是一條完全在台灣打造的臨床管線的正規化層：Breeze-ASR-26聽音，IlhaEmbed理解，FHIR結構化。
+在一條台灣自己的臨床流程裡，它負責「理解」這一段：Breeze-ASR-26 聽打，IlhaEmbed 理解，FHIR 存成結構。
 
-## 效能指標
+## 成效
 
-任務：jargon top-1。給一個台灣臨床表面詞，於合併概念池中檢索其標準臨床概念。各語域（行話、縮寫、同位語）分別留出、排除自我匹配、macro平均。所有模型使用同一方法與同一概念池。
+測的是 jargon top-1：給一個台灣臨床的表面詞，從概念池裡找出對應的標準概念。行話、縮寫、同位語三類各自留作測試，排除自我匹配，取各類平均。四個模型用同一套方法、同一個池。
 
-| 模型 | 可地端 | 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 |
 
-約為最佳通用模型的四倍、bge的近八倍，就贏在那些模型從沒學過的在地詞彙。IlhaEmbed不以在通用排行榜（MTEB）霸榜為目標。它是專科模型：只贏在通用模型會爆掉的地方，同時小到能在病房裡跑。
+在這些在地詞彙上，通用模型和一般中文模型多半讀不出來，這個模型能對到正確概念。它不是要在通用排行榜（MTEB）上比高下，只把台灣臨床詞彙這一件事做好，而且小到能在病房的機器上跑。
 
-上述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
@@ -161,18 +161,18 @@ model = SentenceTransformer("weemed/IlhaEmbed")
 model.encode(["斷腦筋", "H/T", "定期心內門診-戒菸"])
 ```
 
-維度：384。最大序列：32 tokens。詞表：25.5k（剪枝至繁體中文與臨床）。大小：37 MB（INT8 ONNX）或152 MB（fp32 safetensors）。
+維度 384，最長 32 個 token。詞表 25.5k（剪過，只留繁體中文和臨床會用到的）。大小 37 MB（INT8 ONNX）或 152 MB（fp32 safetensors）。
 
-## 怎麼做出來的
+## 怎麼做的
 
-底模是IBM Granite ModernBERT（Apache-2.0），一個寬鬆授權的基礎。由台灣���床teacher訊號透過知識蒸餾提供領域知識，讓學生學會把台灣行話、縮寫、台語擺到它們的標準概念旁邊。
+基礎模型用 IBM Granite ModernBERT（Apache-2.0），授權寬鬆。用台灣臨床的 teacher 訊號做知識蒸餾，讓學生模型學會把台灣的行話、縮寫、台語，擺到對應的標準概念旁邊。
 
-底模原帶18萬詞的多語BPE詞表，其中大多數繁中臨床文字用不到。我們把它剪到實際會用到的25.5k token，體積因此減少68%（117 MB到37 MB），且準確度零損：jargon top-1不掉，真實管線路由逐位一致。
+基礎模型原本帶 18 萬詞的多語 BPE 詞表，繁中臨床大多用不到。把它剪到實際會用到的 25.5k，體積少了 68%（117 MB 到 37 MB），準確度沒掉：jargon top-1 一樣，實際跑匯入的路由結果逐位相同。
 
-## 適用範圍與限制
+## 適用範圍
 
-IlhaEmbed是語意表示工具，不是診斷系統。它浮現可能的意義與比對供人確認，絕不可在未經審核下自行判定臨床事實。它為台灣的繁體中文臨床文字調校。一般散文或簡體中文不在範圍內。
+這是一個做語意表示的工具，不是診斷系統。它給的是可能的意義和比對，最後由人確認，不會自己下臨床判斷。它針對台灣的繁體中文臨床文字調過，一般文章或簡體中文不在範圍內。
 
-## 授權與引用
+## 授權
 
-Apache-2.0。底模：IBM Granite（Apache-2.0）。訓練配對來源記於`SOURCES.md`。釋出的權重是可散佈的衍生作，原始第三方配對不隨附散佈。
+Apache-2.0。基礎模型 IBM Granite（Apache-2.0）。訓練配對的來源記在 `SOURCES.md`。釋出的是訓練後的權重（可散佈的衍生成果），原始的第三方配對不隨附。