tokfair ｜分析程式碼與作業說明

這裡放什麼

研究平台頁面上的每一個數字都由這裡的程式碼產生；頁面本身不做任何計算，所以展示與分析不會漂移。要質疑任何一個數字，直接看對應的檔案就好。

檔案	作用
`minitok.py`	離線的 tiktoken 相容編碼器。讀 js-tiktoken 的 rank 表，不需連網
`stimuli.py`	刺激庫與 2×3 完全交叉設計。詞彙欄人工撰寫，字形欄用 OpenCC 生成
`metrics.py`	fertility、parity、byte-fallback rate、boundary F1、Rényi efficiency、成本換算
`stats.py`	配對 bootstrap、Wilcoxon 符號秩、rank-biserial、因子分解
`vocab_audit.py`	詞表考古：字形覆蓋不對稱、多字 token 的分布與內容
`run_study.py`	端到端執行，輸出 `data/study.json`
`build_web.py`	把 study.json 注入頁面樣板，產生單一檔案的靜態頁

為什麼要重做 v1

v1 比較「台灣繁體／中國簡體／香港繁體」三欄，把 token 數差異報成「方言稅」。那個數字不可解釋，因為三欄同時變動兩個因子：

字形（繁／簡）—— 由 Unicode 碼位決定，是詞表覆蓋率問題
詞彙（軟體／软件／軟件）—— 由合併表決定，是字串頻率問題

拆開之後（37 個項目，項目內對比，配對 bootstrap 95% CI）：

cl100k_base 字形繁−簡 +3.14 tok [+2.28, +4.17] p < .001 詞彙台−中 +0.36 tok [−0.09, +0.86] p = .166 v1「方言稅」 +29.1% [+18.4, +43.3] o200k_base 字形繁−簡 +1.60 tok [+1.22, +2.02] p < .001 詞彙港−中 +0.49 tok [+0.18, +0.80] p = .008

那不是方言稅，是字形稅。 o200k 把字形效果壓到一半之後，詞彙效果反而變得可偵測——字形的雜訊小了，訊號才浮出來。

跑起來

git clone https://github.com/lopentu/genai4humanities2026
cd genai4humanities2026/lab/session-9/tokfair

pip install regex opencc-python-reimplemented jieba numpy scipy
bash vendor_ranks.sh                 # 取得離線 BPE rank 表（約 3.4 MB，不入版控）
python run_study.py                  # → data/study.json，並印出摘要
python build_web.py --out ../zh-tokenizer.html

先把課堂上的數字跑出來，確認環境正確，再開始改。 stimuli.py 的 docstring 說明了設計為什麼長這樣， metrics.py 的 docstring 列出每個指標的文獻出處。

已知限制

詞彙欄為作者自撰而非語料抽樣，不能推論到「一般文本」。要做那個推論，請改用維基百科 zh-tw／zh-cn／zh-hk 的自動轉換版本，或 FLORES-200 的 zho_Hant／zho_Hans 平行句對。
香港欄效度最弱。標記 hk_confidence="low" 的項目混入了書面粵語，那是語法差異而非詞彙差異，會污染詞彙效果的估計。
只測兩個 OpenAI tokenizer。「誰訓練詞表」本身就是可測的變項（見作業 A1）。
token 數差異與下游表現差異是兩件事。這裡只量前者。
metrics.py 中的價格與 context 長度是佔位值，引用前請更新。

文獻引用是憑記憶寫的，尚未逐條查核。寫進報告或投影片前請自行確認年份、會議與作者。