# 接手卡：NLP HW1 示範實作＋一條龍說明文件

最後更新：2026-10-04 16:50（收工時）

## 這是什麼

主理人要「先看 AI 做一次 HW1，再看一份白話一條龍說明，自己再做一次」。
目標：作業拿高分（期末考是弱項，考試也考作業內容）。偏好見 memory `nlp-homework-priority`。
**示範版只給他學，不能直接交。**

## ⚠️ 2026-10-05 01:05 最新狀態：先讀 Tier 2 接手卡

主理人決定**繳交以 Claude 的版本為基礎**，已開 Tier 2：
`C:\D槽\TAICA課程\自然語言處理\HW1\_work\2026-10-04-nlp-hw1-submission\00-resume.md`（唯一真實來源）。
新的繳交版筆記本是 `NLP_HW1_submission_draft.ipynb`（由改版後的 `build_notebook.py` 產生），
半成品備份 `NLP_HW1_submission_partial_1005.ipynb`。下面 10-04 的內容已過時，只留作紀錄。

## ✅ 2026-10-04 20:40 已完成（已過時）

- 正式版 17:33–20:11 全部跑完（ALL DONE，0 錯誤）。備份：`NLP_HW1_DEMO_executed_1004_backup.ipynb`。
- 事後補了一格「第 3 題補充證據：字頻」（`add_freq_cell.py` 單獨執行後插入，index 36；builder 也已加入）。
- 報告 cell 29 已填示範答案（原文在 `report_cell.md`）。筆記本現在 53 格。
- **一條龍說明完成**：`HW1\HW1_一條龍說明.html`（`build_guide.py` 從 `_guide_drafts\` 組裝、填最終數字、內嵌圖片）。
  改內容 → 改 `_guide_drafts\*.html` 或 `build_guide.py` 裡的 R 字典 → 重跑 `build_guide.py`。
- **注意**：`build_notebook.py` 直接跑會覆蓋已執行的筆記本；測試請用 `--dry`。
- **待主理人決定**：是否刪掉約 22 GB 的資料檔（`data\*.gz` 6.5 GB、`wiki_sampled_*.txt` 等約 16 GB）。
  刪了之後若要重跑，要重新下載（約 15 分鐘）。

### 最終主要數字
GloVe 63.11｜Wiki 20% 48.29（語意 55.60／語法 42.21）｜10% 46.87｜5% 45.22｜對照組 41.66｜論壇 26.05
｜5% CBOW 52.71｜5% window10 41.86｜5% 300 維 56.95｜5% 刪停用詞 45.03｜20% 3CosMul 44.61

## 2026-10-04 17:40 更新（已過時，留作紀錄）

- **17:33 已重新啟動正式版**（獨立程式），預計 20:30 左右跑完。看 `run_cells.log`。
- 說明文件草稿（`_guide_drafts\`）新增：`guide_results1.html`（g4 GloVe、g7 自己的字典）、
  `guide_results2.html`（g10 第 3 題）、`guide_results3.html`（g8 報告總原則＋第 1 題、g14 考試 15 題）。
  數字用的是下午那次（partial）的結果；**Word2Vec 多執行緒有隨機性，正式版跑完要逐一比對更新**。
- 還沒寫：intro、g0 全貌、g9（第 2 題）、g11（第 4 題）、g12（第 5 題加分實驗）。
- 另外算了「論壇 vs 維基對照組每百萬字頻率」（結果在 `_extract\word_freq.txt`，已寫進 g10）。
  **要補進示範筆記本第 3 題程式區**：跑完後在 builder 加一格自足的程式，單獨執行那一格再插入輸出（不要整本重跑）。
- `_extract\`：partial 筆記本抽出來的文字輸出與兩張 t-SNE 圖。

## 先前狀態（2026-10-04 16:55，主理人要關機）

- 正式版跑到 cell 37（報告第 2 題）時，**因為主理人要關機，我主動停掉**（不是出錯）。
- 已完成的部分（cell 1–35：TODO1–7＋第 3 題）備份在 **`NLP_HW1_DEMO_partial_1004.ipynb`**，
  寫說明文件時可以先拿裡面的輸出（GloVe／Wiki 20% 成績、兩張 t-SNE、第 3 題表格）。
- `NLP_HW1_DEMO_示範.ipynb` 目前也是同樣的半成品；重跑前要先 `build_notebook.py` 重建乾淨版。
- 抽樣檔、`wiki_sampled_20_clean.txt`、`w2v_wiki20.model` 都還在，但筆記本重跑時會重新產生，不用管。

## 下一步（照順序）

0. **一開工就先重跑整本**（約 3 小時，用下方「重跑正式版」的指令，開獨立程式，不要用 Bash 背景）。
   提醒主理人：跑的期間電腦不要關機、不要睡眠、不要闔上螢幕。
   等的時候用 `NLP_HW1_DEMO_partial_1004.ipynb` 的輸出先寫說明文件的 g4、g7、g10。
1. 確認 `run_cells.log` 最後是 `ALL DONE`。不是的話看 FAILED 的錯誤。
2. 讀筆記本所有輸出（cell 37 之後的：5/10/20%、第 4 題鄰居、top-k、錯題分析、停用詞實驗、CBOW/window/300 維、3CosMul、PCA vs t-SNE、總表）。
3. **填筆記本 cell 29（報告 markdown）**：六題的示範答案＋執行環境（markdown，不用重跑）。
4. **寫一條龍說明文件** `HW1\HW1_一條龍說明.html`：
   - 草稿在 `_guide_drafts\`（g1 觀念、g2 準備、g3 TODO1、g5 抽樣、g6 前處理與參數、g13 繳交、g15 換你做、g16 遇到的問題）。
     裡面 `⟦R:...⟧` 是要用真實結果填的佔位。
   - 還沒寫的節：g4（TODO2/3 GloVe 結果＋t-SNE 圖）、g7（TODO6/7）、g8–g12（報告 1–5 題，各給「要點」不要給可直接抄的成文）、g14（考試可能怎麼問）。
   - 格式照 `~/.claude/rules/html-report-template.md`＋骨架 `report-skeleton.html`（左側目錄、一次一節）。圖用 base64 從筆記本輸出抽出來內嵌。
   - 五歲小孩式、極詳細；每節：結論 → 為什麼 → 細節 →「考試可能問」。
5. 清理：確認不用再重跑後，刪 `data\*.gz`（6.5 GB）和 `wiki_sampled_*.txt`（約 14 GB）。**先問主理人。**
6. 更新 `自然語言處理\_接手卡.md` 的 HW1 段落。

## 已經有的結果（16:49 為止，數字都來自筆記本輸出）

| 模型 | Overall | Semantic | Syntactic |
|---|---|---|---|
| GloVe-100（現成） | 63.11 | 65.34 | 61.26 |
| Wiki 20%（自己訓練，36 分鐘，字典 299,405） | 48.21 | 56.09 | 41.66 |
| Wiki 對照組（7,292 萬字） | 41.98 | 46.95 | 37.85 |
| 論壇 Qatar Living（7,292 萬字） | 26.01 | 12.88 | 36.92 |

- 維基共 5,623,655 篇；20% 抽到 1,124,733 篇；20% 整理後 666,053,126 字。
- 第 3 題重點：論壇語意類慘輸（首都、地理），但比較級／最高級／-ing 贏維基（口語常用）。
  覆蓋率：論壇字典只有 48.6% 的 capital-world、39% 的 currency 題目四個字都在。
- Wiki 20% 的 city-in-state（34.25）比 GloVe（30.81）高。
- GloVe 的 t-SNE：字按「角色」分群（皇室、step-、代名詞、複數），男女配對黏在一起。

## 踩過的坑（下次別再犯）

- **Claude 的 Bash 背景工作約 10 分鐘就會被強制停止**。長時間工作要用
  `Invoke-CimMethod Win32_Process Create` 開獨立程式（見下方指令）。前兩次中斷都是這個原因。
- `build_notebook.py` 裡把程式碼包在三引號字串：`\n`、`\S` 要寫成 `\\n`、`\\S`，否則筆記本裡變真的換行。改完跑 `check_nb.py` 檢查語法。
- 輸出檔要 `newline="\n"`，否則 Windows 會寫 `\r\n`。
- 論壇語料的 gensim loader 用舊版 `smart_open` → ImportError。改成 `return_path=True` 自己用 gzip＋json 讀。
- 模板是 nbformat 4.<5，新 cell 有 id → builder 最後補 id 並設 minor=5。

## 檔案地圖

| 檔案 | 用途 |
|---|---|
| `build_notebook.py` | 從模板產生示範筆記本（只改 TODO／資料載入格，其他 18 格一字不差）。`--dry` 產生彩排版到 `_dry\` |
| `run_nb.py` | 逐格執行、每格存檔、寫 `run_cells.log` |
| `check_nb.py` | 檢查所有 code cell 的語法 |
| `download_wiki.py` | 下載 11 個維基檔到 `data\` |
| `requirements.txt` | 套件版本 |
| `.venv\` | Python 3.12.3 環境（gensim 4.4.0 等） |
| `_dry\` | 彩排版（小資料），可刪 |
| `proto_*.py` | 早期試作，可刪 |

## 重跑正式版的指令（PowerShell）

```powershell
$dir = "C:\D槽\TAICA課程\自然語言處理\HW1\示範實作"
Remove-Item "$dir\run_cells.log" -ErrorAction SilentlyContinue
$cmd = "cmd.exe /c set PYTHONIOENCODING=utf-8 && cd /d `"$dir`" && `"$dir\.venv\Scripts\python.exe`" run_nb.py NLP_HW1_DEMO_示範.ipynb > runner_stdout.log 2>&1"
Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cmd; CurrentDirectory = $dir }
```
（重跑前先 `python build_notebook.py` 重建乾淨的筆記本，否則會帶著舊輸出。）