# 作業一：Tokenization Unfairness

**生成式 AI 的人文導論** · Lab Session 9 延伸練習
個人或兩人一組（兩人組的工作分配須在報告首頁載明）。成績與繳交方式以 NTU COOL 公布為準。

---

## 這份作業要練的事

一句「繁體中文比簡體中文多花 29% 的 token」是**觀察**，不是**發現**。
把它變成發現，需要四件在這門課裡會反覆出現的東西：

1. **把混淆的因子拆開。** 29% 裡有多少來自字形、多少來自詞彙？兩者的成因與解法完全不同。
2. **指標要有分母、有基準線、有區間。** 沒有區間的百分比無法判斷是否值得在意。
3. **抽樣框要能撐得起結論。** 手寫十五句能支持什麼樣的推論？
4. **語言學論證要做事。** 效果的**方向**通常可以從語言學預測；預測錯了，比預測對了更有資訊。

研究平台（`lab/session-9/zh-tokenizer.html`）與分析程式碼（本目錄）是起點，不是終點。網頁版規格見 `assignment1.html`。

---

## 兩條路徑，擇一

### 路徑 A ｜ 系統擴充

提出一個新的想法，用程式把它實作進這個專案。
**評分看的不是程式量，而是你加的那個變項讓原本看不見的什麼東西變得可見。**

可選題目（也歡迎自己提，但請先與教師確認範圍）：

| # | 題目 | 要回答的問題 |
|---|---|---|
| A1 | 加入其他 tokenizer 家族：Llama-3、Qwen、Gemma、DeepSeek、XLM-R、bert-base-chinese | 字形效果的大小是否隨「誰訓練詞表」而變？中文團隊訓練的詞表是否對繁體較友善？ |
| A2 | 換掉抽樣框：以維基百科 zh-tw／zh-cn／zh-hk 自動轉換版本，或 FLORES-200 的 zho_Hant／zho_Hans 平行句，建立 n ≥ 500 的句對 | 手寫語料得到的效果量，在真實文本分布上還成立嗎？ |
| A3 | 實作 CKIP 斷詞版的 fertility 與 boundary F1，把 tokenizer 當成第三套斷詞標準 | tokenizer 與人類斷詞標準的一致率有多高？繁簡之間是否不同？ |
| A4 | 詞表標註研究：抽樣 200 個多字漢字 token，兩位標註者分類為語素／詞／搭配／短語／碎片／垃圾，報 Cohen's κ | 一個 BPE 詞表**在語言學上**是什麼樣的清單？ |
| A5 | 加入台語漢字、客語漢字、族語羅馬字、注音、全形／半形等條件 | 「公平性」的邊界在哪裡？誰的書寫系統從來沒被計入？ |
| A6 | 實作熵切分（BLT 式 dynamic patching）的小型復刻，與 BPE 在中文上比較切分點 | 動態切分是否比 BPE 更接近人類詞界？ |
| A7 | 偵測訓練不足的 token（undertrained / glitch tokens），量化它們在中文詞表中佔的比例 | 詞表的哪一部分是被浪費掉的？ |

**繳交物**：pull request 或 repo fork（含可執行的 `run_study.py` 路徑）＋ 3–5 頁說明文件。
說明文件須包含：動機、實作的變項、結果、以及**你的擴充推翻或修正了原本的哪一個說法**。

---

### 路徑 B ｜ 評量報告

使用現有系統（可小幅修改輸入），設計並執行一項評量，寫成報告。
**評分看的不是效果有多大，而是你的效果不能是設計的副產品。**

可選題目：

| # | 題目 | 假設範例 |
|---|---|---|
| B1 | 罕見句式／語體：文言文、法律條文、學術中文、注音文、網路火星文 | 語體愈偏離網路白話，tokens/字 愈高；且繁簡差距在文言文中**縮小**（因為兩者都罕見） |
| B2 | 外來詞的詞元化：音譯 vs 意譯（雷射／激光、維他命／维生素、部落格／博客／網誌） | 意譯詞由常用語素組成，應比音譯詞省 token；此效果應大於繁簡效果 |
| B3 | 專名與譯名：川普／特朗普、雪梨／悉尼、梵谷／梵高 | 譯名的 token 成本反映該譯名在訓練語料中的出現頻率，可作為語料組成的間接證據 |
| B4 | 領域混排：中英夾雜、程式碼與中文註解、醫學／法律術語 | 語言切換點會產生額外的 token 邊界成本 |
| B5 | 標點與排版：全形／半形、直書引號、破折號、數字書寫（一千／1000／1,000） | 排版慣例的地域差異本身就是一種稅 |
| B6 | 歷時比較：《紅樓夢》vs 現代白話 vs 2020s 網路中文 | 詞表是 2023 年前後網路語料的快照，愈接近該分布愈省 |
| B7 | 構式完整性：成語、半基模構式（越 X 越 Y）、離合詞、重疊式在詞表中是否成為單位 | BPE 對固化程度不敏感，只對字串頻率敏感；因此四字成語不會是單一 token，而高頻的搭配塊會是 |

**繳交物**：4–6 頁報告 ＋ 可重現的 notebook 或 script。

---

## 兩條路徑共同的最低要求

報告（或說明文件）必須包含以下段落，缺一扣分：

1. **研究問題與假設**：至少一個具方向性的假設，以及它為什麼是語言學上合理的預測。
2. **設計**：說明你控制了什麼、沒控制什麼。若你的比較同時變動兩個因子，請說明為什麼可以接受。
3. **抽樣框與 datasheet**：語料從哪裡來、怎麼選的、n 是多少、有什麼已知偏誤。一頁即可。
4. **指標定義**：每個指標寫出公式或程式碼，並說明分母是什麼。
5. **不確定性**：所有效果須附 95% 區間（bootstrap 或解析式皆可）。**只報百分比而無區間者不予計分。**
6. **至少一個 null 結果或反例**：你預測會有效果但沒有的地方，或與你的假設相反的個案。
7. **限制**：你的結論**不能**推論到什麼。
8. **LLM 使用聲明**：你用了哪些模型做了什麼（寫程式、除錯、翻譯、潤稿皆可，但須誠實列出）。使用 LLM 不扣分，不聲明扣分。

---

## 評分標準（100 分）

| 面向 | 配分 | 好的樣子 |
|---|---|---|
| 問題與假設 | 20 | 假設有方向、可被推翻，且理由來自語言學而非直覺 |
| 設計與控制 | 25 | 因子分離乾淨；控制條件的存在理由說得出來；知道自己的設計會產生什麼假效果 |
| 測量與統計 | 25 | 指標定義清楚；分析單位正確（項目內對比）；區間與效果量齊備 |
| 詮釋與語言學論證 | 20 | 從數字回到語言學問題；能說明機制而不只是相關 |
| 可重現性 | 10 | 別人跑得起來；隨機種子、版本、資料來源齊備 |

**加分（最多 +5）**：發現並記錄研究平台本身的錯誤、或提出一個我們沒想到但可測的反例。

---

## 常見的失分方式

- 只把 token 數畫成長條圖，沒有基準線與區間。
- 用 OpenCC 的 `s2twp` 做字形轉換——那個設定會**同時**轉換詞彙，等於把你想分離的兩個因子又黏回去。請用 `s2t` / `t2s`。
- 拿不平行的語料比較「語義等價」的句子。翻譯品質的差異會被誤讀成 tokenizer 的差異。
- 把「token 數較多」直接說成「表現較差」。那是兩個不同的主張，後者需要下游實驗。
- 香港欄混入書面粵語。那是語法差異，不是詞彙差異，會污染詞彙效果的估計。

---

## 起步

```bash
git clone <course-repo> && cd tokfair
pip install regex opencc-python-reimplemented jieba numpy scipy
bash vendor_ranks.sh          # 取得離線 BPE rank 表
python run_study.py           # 重現課堂上的所有數字
python build_web.py           # 重建研究平台頁面
```

先把課堂數字跑出來，確認環境正確，再開始改。
`stimuli.py` 的 docstring 說明了設計為什麼長這樣；
`metrics.py` 的 docstring 列出每個指標的文獻出處（請自行查核，那些引用是憑記憶寫的）。

有任何設計上的疑問，在 Lab 課後或於 NTU COOL 討論區提出，比自己猜快得多。