Eval CLAUDE.md

Twinkle Eval — 專案規範手冊（CLAUDE.md）

本文件是所有開發者與 coding agent 的強制閱讀文件。 在修改任何程式碼之前，必須先完整閱讀本文件，確保所有變更符合本專案的設計理念與規範。 若提議的變更與本文件有所衝突，必須先至 GitHub 開立 Issue 進行討論，而非直接提交 PR 要求合入。

---

目錄

1. 專案定位與設計理念
2. 核心設計原則（不得違反）
3. 架構總覽
4. 模組職責邊界
5. 擴充規範——如何正確新增功能
6. 新增評測 Benchmark 的完整規範
7. 必須先開 Issue 的情況
8. 程式碼風格規範
9. 設定檔規範（config.yaml）
10. 輸出格式規範
11. 依賴管理規範
12. CLI 設計規範
13. 提交 PR 前的 Checklist
14. 專案現況快照
15. 貢獻者

---

1. 專案定位與設計理念

1.1 誕生背景

2025 年初，推理模型（reasoning model）開始大量出現。這類模型在輸出正式答案之前，會先產生大量的推理過程（chain-of-thought），導致每次 API 呼叫的回應時間遠高於傳統模型。

然而，當時現有的評測框架（如 iKala/ievals）採用同步、逐題呼叫的設計，面對推理模型時評測時間會等比例放大，一個完整的 benchmark 動輒耗費數小時。對於正在進行模型訓練迭代的團隊而言，這意味著每次訓練完都需要等待過久才能得到評測反饋，白白浪費 GPU 運行時間與開發週期。

Twinkle Eval 因此而生：以並行 API 請求為核心手段，讓評測速度不再是訓練迭代的瓶頸。實測相比 iKala/ievals 快 9–17 倍，使團隊能夠快速取得評測結果、驅動下一輪訓練決策。

1.2 核心設計哲學

「輕量、單機、即裝即用」是這個專案的根本設計方向。

本專案從一開始就以「pip install twinkle-eval 後，在單台機器上即可執行完整評測」為設計約束。這個約束是刻意的：

• 不依賴叢集基礎設施：不需要 SLURM、Kubernetes、或任何分散式排程系統才能運作
• 不需要特殊硬體：評測本身不需要 GPU，只需要能呼叫 API 的網路環境
• 降低使用門檻：任何人在任何環境（本機、Colab、CI/CD）都能直接執行

多節點分散式評測（如 SLURM 支援）若作為 PR 提交，定位是擴充功能（extension），不得影響單機執行路徑的正確性與簡潔性。核心程式碼必須在不依賴任何分散式元件的情況下完整運作。

1.3 關鍵設計邊界：本專案永遠不啟動模型端點

Twinkle Eval 不負責啟動、部署、或管理任何 LLM 服務。

本專案的職責範圍嚴格限定於：

「拿著評測題目，去呼叫已經在外部運行的 API 端點，取得回答，並計算評測指標。」

使用者需要自行在外部啟動模型服務（vLLM、Ollama、OpenAI、NVIDIA Build 等），再將端點的 base_url 填入 config.yaml，Twinkle Eval 才開始工作。

這個邊界意味著：

• 本專案程式碼中不得出現任何啟動 vllm serve、ollama run 或其他模型服務的邏輯
• 本專案不管理模型的生命週期（啟動、關閉、重啟）
• 若 API 端點無回應，本專案的責任是報錯退出，而非嘗試修復或重啟服務

任何試圖在程式碼內部啟動模型服務的 PR，在未開 Issue 討論並取得 maintainer 明確同意前，不得合入。

1.4 核心目標

• 高效：以並行請求大幅縮短評測時間，讓評測不再是訓練迭代的瓶頸
• 客觀：透過選項隨機排列，消除模型對選項位置的偏好（參考 Changing Answer Order Can Decrease MMLU Accuracy）
• 穩定性量化：支援多次執行並計算標準差，反映模型一致性
• 易擴充：模組化設計，讓新增 LLM 後端、評測策略、輸出格式都不需修改核心邏輯
• API 相容優先：以 OpenAI 相容 API 為統一介面，不綁定特定模型或服務商