Upload README.md with huggingface_hub

README.md

@@ -26,7 +26,11 @@ base_model:
 
 Apple CoreML 版本的 CKIP BERT-base 繁體中文 NLP 模型，可在 iOS/macOS 上透過 Apple Neural Engine (ANE) 執行。
 
-從 [ckiplab/ckip-transformers](https://github.com/ckiplab/ckip-transformers) 轉換，經由 [ckip-mlx](https://huggingface.co/FakeRockert543/ckip-mlx) 中繼。
+- 📦 原始碼：[GitHub — FakeRocket543/ckip-coreml](https://github.com/FakeRocket543/ckip-coreml)
+- 🤗 模型權重：[HuggingFace — FakeRockert543/ckip-coreml](https://huggingface.co/FakeRockert543/ckip-coreml)（本頁）
+- 🧪 MLX 版本（桌面推薦）：[HuggingFace — FakeRockert543/ckip-mlx](https://huggingface.co/FakeRockert543/ckip-mlx)
+
+從 [ckiplab/ckip-transformers](https://github.com/ckiplab/ckip-transformers) 轉換而來。CoreML fp16 是所有框架中最快的，比 CKIP 官方快 **6.3 倍**。
 
 ## 模型說明
 
@@ -46,72 +50,165 @@ Apple CoreML 版本的 CKIP BERT-base 繁體中文 NLP 模型，可在 iOS/macOS
 | fp16 | 194 MB | WS 100% / POS 99.97% / NER 99.99% | **推薦預設** ⚡ |
 | q8 | 98 MB | WS 99.96% / POS 98.83% / NER 99.76% | 低記憶體 iPhone |
 
-## 速度
+## 從零開始使用（完整步驟）
 
-測試環境：Apple M4 Max / 128GB / macOS 26.3.1
-測試資料：維基百科「臺灣」條目，36,245 字
+### 1. 環境準備
 
-| Framework | fp32 | fp16 |
-|-----------|-----:|-----:|
-| **CoreML** | 2,879 ms | **2,352 ms** ⚡ |
-| MLX | 2,869 ms | 3,092 ms |
-| HF Transformers (MPS) | 3,532 ms | 3,096 ms |
-| CKIP 官方 (MPS) | 14,926 ms | 11,850 ms |
+需要 macOS + Apple Silicon。CoreML Tools 目前需要 Python 3.13（不支援 3.14）。
+
+```bash
+# 取得原始碼
+git clone https://github.com/FakeRocket543/ckip-coreml.git
+cd ckip-coreml
+
+# 建立虛擬環境（需要 Python 3.13）
+python3.13 -m venv .venv && source .venv/bin/activate
+
+# 安裝依賴
+pip install coremltools numpy huggingface_hub
+```
+
+### 2. 下載模型
+
+```bash
+# 從 HuggingFace 下載全部 .mlpackage
+huggingface-cli download FakeRockert543/ckip-coreml --local-dir .
+```
+
+下載後目錄結構：
+
+```
+ckip-coreml/
+├── ckip_ws_fp16.mlpackage      # 斷詞 fp16（推薦）
+├── ckip_ws_fp32.mlpackage
+├── ckip_ws_q8.mlpackage
+├── ckip_pos_fp16.mlpackage     # 詞性 fp16
+├── ckip_pos_fp32.mlpackage
+├── ckip_pos_q8.mlpackage
+├── ckip_ner_fp16.mlpackage     # 實體 fp16
+├── ckip_ner_fp32.mlpackage
+├── ckip_ner_q8.mlpackage
+├── ckip_ws.mlpackage           # 原始版本 (=fp32)
+├── ckip_pos.mlpackage
+└── ckip_ner.mlpackage
+```
+
+### 3. 準備詞表
 
-CoreML fp16 是所有框架中最快的，比 CKIP 官方快 **6.3 倍**。
+CoreML 模型不包含詞表，需要從 MLX 版本取得，或自行下載 BERT 中文詞表：
 
-## 使用方式
+```bash
+# 方法一：從 MLX repo 下載 vocab.txt
+huggingface-cli download FakeRockert543/ckip-mlx models/vocab.txt --local-dir .
+mv models/vocab.txt vocab.txt && rm -rf models
 
-### Python
+# 方法二：從原始 BERT 下載
+# wget https://huggingface.co/bert-base-chinese/resolve/main/vocab.txt
+```
+
+### 4. 執行斷詞（Python）
 
 ```python
 import coremltools as ct
 import numpy as np
 
+# 載入詞表
+vocab = {}
+with open("vocab.txt") as f:
+    for i, line in enumerate(f):
+        vocab[line.strip()] = i
+
+# 載入模型（推薦 fp16）
 model = ct.models.MLModel("ckip_ws_fp16.mlpackage")
 
+# Tokenize（BERT 單字切分）
 text = "台積電今天股價上漲三十元"
-input_ids = np.array([[101] + [vocab[ch] for ch in text] + [102]])
-attention_mask = np.ones_like(input_ids)
+ids = [101] + [vocab.get(ch, 100) for ch in text] + [102]  # 101=[CLS], 102=[SEP], 100=[UNK]
+input_ids = np.array([ids], dtype=np.int32)
+attention_mask = np.ones_like(input_ids, dtype=np.int32)
 
+# 推論
 out = model.predict({"input_ids": input_ids, "attention_mask": attention_mask})
 preds = np.argmax(out["logits"], axis=-1)[0]
+
+# 解碼斷詞結果（B=0: 詞首, I=1: 詞中）
+words, cur = [], ""
+for i, ch in enumerate(text):
+    p = preds[i + 1]  # +1 跳過 [CLS]
+    if p == 0 and cur:
+        words.append(cur)
+        cur = ch
+    else:
+        cur += ch
+if cur:
+    words.append(cur)
+
+print(words)
+# ['台積電', '今天', '股價', '上漲', '三十', '元']
+```
+
+### 5. 執行詞性標注（Python）
+
+```python
+import json
+
+pos_model = ct.models.MLModel("ckip_pos_fp16.mlpackage")
+out = pos_model.predict({"input_ids": input_ids, "attention_mask": attention_mask})
+preds = np.argmax(out["logits"], axis=-1)[0]
+
+# POS id2label 對照表（從 MLX config.json 取得，或用以下常見標籤）
+# 完整對照表見 GitHub repo 的 models/pos/config.json
+for i, ch in enumerate(text):
+    print(f"{ch} → label_id={preds[i + 1]}")
 ```
 
-### Swift / iOS
+### 6. 在 Swift / iOS 中使用
 
 ```swift
-let model = try MLModel(contentsOf: modelURL)
+import CoreML
+
+// 載入模型
+let config = MLModelConfiguration()
+config.computeUnits = .all  // 使用 ANE + GPU + CPU
+let model = try MLModel(contentsOf: modelURL, configuration: config)
+
+// 準備輸入
+let inputIds = try MLMultiArray(shape: [1, seqLen as NSNumber], dataType: .int32)
+let attentionMask = try MLMultiArray(shape: [1, seqLen as NSNumber], dataType: .int32)
+
+// 填入 token IDs（[CLS] + 單字 IDs + [SEP]）
+for (i, id) in tokenIds.enumerated() {
+    inputIds[i] = NSNumber(value: id)
+    attentionMask[i] = 1
+}
+
+// 推論
 let input = try MLDictionaryFeatureProvider(dictionary: [
-    "input_ids": MLMultiArray(inputIds),
-    "attention_mask": MLMultiArray(attentionMask)
+    "input_ids": inputIds,
+    "attention_mask": attentionMask
 ])
 let output = try model.prediction(from: input)
-```
+let logits = output.featureValue(for: "logits")!.multiArrayValue!
 
-## 量化精度詳細測試
+// 取 argmax 得到預測標籤
+```
 
-以維基百科「臺灣」條目 36,245 字測試，與 fp32 逐 token 比對（共 36,389 tokens）：
+## 速度
 
-### fp16
-- WS: 1 token 不同 (100.00%)
-- POS: 11 tokens 不同 (99.97%)
-- NER: 3 tokens 不同 (99.99%)
+測試環境：Apple M4 Max / 128GB / macOS 26.3.1
+測試資料：維基百科「臺灣」條目，36,245 字，10 runs median
 
-### q8
-- WS: 13 tokens 不同 (99.96%)
-- POS: 425 tokens 不同 (98.83%)
-- NER: 89 tokens 不同 (99.76%)
+| Framework | fp32 | fp16 |
+|-----------|-----:|-----:|
+| **CoreML** | 2,879 ms | **2,352 ms** ⚡ |
+| MLX | 2,869 ms | 3,092 ms |
+| HF Transformers (MPS) | 3,532 ms | 3,096 ms |
+| CKIP 官方 (MPS) | 14,926 ms | 11,850 ms |
 
 ## 跨框架驗證
 
 CoreML fp32 與 MLX fp32、HF Transformers fp32 的 WS/POS/NER 輸出**完全一致**，確認轉換正確。
 
-## 相關專案
-
-- [FakeRockert543/ckip-mlx](https://huggingface.co/FakeRockert543/ckip-mlx) — MLX 版本（桌面推薦）
-- [FakeRocket543/ckip-coreml](https://github.com/FakeRocket543/ckip-coreml) — 原始碼與轉換腳本
-
 ## 授權
 
 [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html)，依循原始 [ckiplab/ckip-transformers](https://github.com/ckiplab/ckip-transformers) 授權。