v2.10.0 — VisTW 繁體中文視覺評測

⚠️ 視覺評測的分數會上升。 mmbench、mmstar、mmmu、pope、vistw_mcq 都受 #166 修復影響，與舊版分數不可直接比較，請重跑基準。

新增：VisTW 繁體中文台灣在地視覺評測

arXiv 2503.10427，NTU MiuLab，CC BY 4.0。本專案第一個繁中視覺評測 —— 既有的 MMBench、MMStar、MMMU、POPE 全是英文或簡體中文為主。

子集	內容	評測方法
MCQ	21 學科圖片選擇題	沿用既有 vision_mcq
Dialogue	開放式問答，LLM judge 0–10 分	新增 vistw_dialogue + vistw_judge

Dialogue 採兩階段設計（生成 → 評分），兩階段都走既有的 evaluator 路徑，evaluator 未改動。好處是 judge 呼叫仍然並行，且換 judge 重評不必重跑生成。

🔴 修復：VisionMCQExtractor 抓不到「答案: $A」

官方 VisTW 的 prompt 教模型輸出「答案: $字母」，模型照抄那個 $，我們抓不到。

更嚴重的是：抓不到之後會退而用較寬鬆的 pattern 抓到推理文字中的其他字母，把正確作答判成答錯。那比 unparsed 危險 —— unparsed 至少會出現在 unparsed_rate 裡，抓錯字母完全無聲。

實測 253 題：75.89%（11 題 unparsed）→ 81.82%（0 題 unparsed）。11 題 unparsed 全部是這個 bug，不是模型答不出來。

影響 mmbench、mmstar、mmmu、pope、vistw_mcq 五個 benchmark。

🔴 修復：--benchmark 崩潰

2.9.0 移除 main.py 的 runner class 時把 import copy 一併帶走，而 --benchmark 的金鑰清理還在用它，導致 NameError。

Changed

VisTW 範本的 max_tokens 2048 → 8192。推理型 VLM 會在寫出答案前用掉大量 token：實測 2048 時 19% 因截斷而 unparsed、分數低估 19 個百分點；不設上限則會推理到代理層逾時。

對比驗證

與官方實作在相同模型、相同端點、相同 253 題下對比：

	Twinkle Eval	官方
accuracy	81.01%	80.56%
差異	+0.45 個百分點	✅ 在 ±2% 容差內

完整方法、四項對齊修改、以及對比過程中揪出 #166 的經過，都記錄在 docs/evals/vistw.md §6。

v2.9.0 — 評測正確性修復（分數會變動）

⚠️ 本版會改變評測分數。 含 metadata 欄位的資料集（GPQA、SuperGPQA、MMLU-Redux、vision_mcq）分數預期下降，因為先前的 prompt 夾帶了學科分類。與舊版分數不可直接比較，請重跑基準。

🔴 題目 metadata 被當成選項送進 prompt（#143）

文字與 logit 路徑以「排除 question/answer 後其餘欄位全印」組題目，導致 id、domain、discipline、category 進入 prompt。學科分類欄位等同免費提示，會高估分數。

shuffle_options 預設為 false，預設路徑就是壞的，且自 2.8.0 以前即如此。

僅解決選擇題路徑；非選擇題資料集（NIAH 洩漏 needle_depth、RAGAS 洩漏 answer_type）另行追蹤於 #146。

🔴 選項重排的兩個缺陷

• #140：硬編碼 A/B/C/D。MMLU-Pro（A–J）、SuperGPQA 開啟 shuffle_options 時 E 之後的選項被靜默丟棄
• #141：重排時丟棄 image_path，導致 vision_mcq + shuffle_options 評測到零題

🔴 system_prompt 只對 box/math 生效（#144）

其餘方法設了也不送。templates/regex_match.yaml 官方範本自己就設了 prompt 卻從未送出。vision 路徑更是在任何設定下都送不出。

⚠️ 設了 system_prompt 的非 box/math 設定，prompt 現在會真的送達，分數會變動。box/math 未設時不再送出空的 system message，既有分數可能小幅變動。

Changed

• #142：TwinkleEvalRunner 兩份實作去重，四條 import 路徑維持可用
• 新增 VisTW-MCQ 繁體中文台灣在地視覺評測（Milestone #23 Phase 1）
• 新增 /run-eval 與 /add-benchmark 兩個 Claude Code skill

完整內容見 CHANGELOG。

v2.8.1 — 安全性與資料遺失修復

從 PR #136 拆出的獨立 bug fix 批次（#158），作者 @dave-apmic / S.Feng。內容為不改變評測分數的修復。

🔴 重要修復

• --benchmark 把完整 API 金鑰寫進 benchmark_results_*.json —— 該路徑未經清理（原則 E 破口）
• finalize 刪除合併後的 JSONL —— rank0 的 shard 路徑與合併輸出路徑相同（原則 D 資料遺失）
• _prepare_config_for_saving() 就地破壞 self.config —— 同一個 runner 無法重複執行

其他修復

• HTML exporter 在 usage_total_tokens 為 None 時崩潰；模型輸出未經 html.escape() 會注入報告
• cli.py 的 sys.path hack 遮蔽 HuggingFace datasets 套件
• text2sql 的 SQL 執行逾時從未生效
• gated dataset 檢查的運算子優先序錯誤

⚠️ 行為變更

• --dry-run 與評測啟動不再做 Google 連線檢查（修好 §4 與 §12 兩個契約；代價是診斷延後到上傳階段）
• Google Sheets 匯出移除金鑰欄位 —— 既有試算表的歷史列仍有截斷金鑰且會位移一欄，建議封存
• --download-dataset 對非 gated 的 403 改為 exit 1
• text2sql 逾時真的生效，gold SQL 逾時會退回 Exact Match，可能小幅改變分數

注意

秒級時間戳只套用到 log 檔名。results_*.json 與 JSONL 仍是分鐘精度，同分鐘啟動兩次會出問題（JSON 被覆蓋、JSONL 累加導致下游重複計數）。

完整內容見 CHANGELOG。

v2.8.0 — VLM Phase 1: Vision MCQ Evaluation

VLM Phase 1 — Vision MCQ Evaluation

第一個 Vision Language Model 評測方法上線。Twinkle Eval 現可評測 VLM 在多模態選擇題（MMBench / MMStar / MMMU / POPE）的表現。

Added

• vision_mcq 評測方法（Milestone #22，PR #134）
  • VisionMCQExtractor：支援字母答案（A–Z）與 Yes/No 二元答案（POPE 等幻覺偵測 benchmark）
  • 優先解析 \boxed{} / \box{}（推理型 VLM 的標準輸出格式）
  • 採用 findall + 取最後一個 match 策略，正確處理 VLM 先回顯選項列表再給最終答案的常見情境
  • Pattern 順序經精細調整：parenthesized / bare-letter-at-end 優先於 line-start，避免 "A) cat / B) dog / C) bird / D" 被誤抓為 C
• Evaluator vision 路由
  • _encode_image_to_data_uri()：magic-byte MIME 偵測（PNG / JPEG / GIF / WebP / BMP）、symlink resolve、50MB 大小上限保護
  • 支援本地檔案（base64 data URI）與 HTTP/HTTPS URL（直接傳遞給 OpenAI Chat Completions）
  • uses_vision = True flag 自動分流
• 4 個 Vision Benchmark：MMBench、MMStar、MMMU、POPE
• Example Dataset：datasets/example/vision_mcq/（10 筆 MMStar 樣本，含 jpg 圖片）
• docs/evals/vision_mcq.md：含 VLMEvalKit 分數對比與速度對比
• 61 個 vision_mcq 測試（tests/test_vision_mcq.py），含大量 VLM 真實輸出格式的 regression cases
• Optional dependency vision = ["Pillow>=10.0.0"]

Changed

• datasets/file.py：多模態附帶資源（圖片、音檔、影片）改為統計後一次性 log_info，避免逐檔 warn 噪音
• CLAUDE.md §13 新增「強制 Reviewer Agent」規定：所有 coding agent 在任何 PR push 之前，必須先 spawn 獨立的 reviewer agent 檢查 diff，blocker 必須先處理才能 push

使用方式

llm_api:
  type: "openai"
  base_url: "http://localhost:8000/v1"
  api_key: "your-api-key"

model:
  name: "your-vlm-model"
  max_tokens: 1024

evaluation:
  dataset_paths:
    - "datasets/example/vision_mcq/"
  evaluation_method: vision_mcq
  strategy_config:
    image_field: "image_path"
    max_image_size: null
    image_detail: "auto"

需要 vision-capable 的 OpenAI 相容 API 端點（vLLM + Qwen2-VL、OpenAI GPT-4o、NVIDIA Build VLM 等）。

v2.7.1 — Fix vLLM 0.18+ reasoning field compatibility

Fixed

• vLLM 0.18+ reasoning 欄位相容性（PR #127 by @cyc00518）：vLLM 0.18+ 將 reasoning_content 改名為 reasoning，新增 _get_reasoning_text() helper 優先讀取 reasoning，None 時才回退 reasoning_content，相容 vLLM <0.13 / 0.13.x / >=0.18 三種版本

Changed

• CLAUDE.md 新增 bug fix 必須立即推 PATCH 版號的規範

Full Changelog: v2.7.0...v2.7.1

v2.7.0 — ASR Evaluation (WhisperModel + WER/CER)

Milestone #21: ASR — Automatic Speech Recognition Evaluation

New Features

• WhisperModel: 新增 Whisper API (/v1/audio/transcriptions) LLM 後端，相容 OpenAI、Groq、faster-whisper-server
• ASRExtractor + ASRScorer: 自動依語言選擇 WER（英文）或 CER（中文/日文/韓文），含 text normalization pipeline
• Chat Completions 多模態支援: 透過現有 OpenAIModel 搭配 audio_url 內容，支援 Qwen2-Audio 等多模態模型
• 4 個 ASR Benchmark: LibriSpeech、Aishell-1、Fleurs、Common Voice（總計 23 個可下載 benchmark）
• Optional dependency: pip install twinkle-eval[asr]（jiwer）

Benchmark Results

使用 Breeze-ASR-25 + Common Voice TW 50 筆測試：

• CER: 3.80%
• 並行加速: 7.5x（vs sequential）

Full Changelog

v2.6.0...v2.7.0

v2.6.0 — Benchmark Download, CLI Enhancement, Regex Match

What's New

Benchmark Download Registry (Milestone #20)

• --download-dataset 支援 19 個 benchmark 短名稱（mmlu、gsm8k、bbh 等）
• --download-dataset all 一鍵下載全部
• --download-dataset list 列出所有可用資料集
• 支援 GitHub-based 下載（BIRD、Spider 2.0-lite、LongBench）
• Gated dataset（GPQA）互動式 HF token 提示

CLI Enhancement (Milestone #19)

• --init 重構：--init（列出範本）、--init <name>（單一）、--init all（全部）
• --dry-run：預覽評測計畫，不呼叫 API
• --validate：驗證設定檔與資料集格式
• --resume TIMESTAMP：從中斷點繼續評測
• 設定檔範本搬入 twinkle_eval/templates/

Regex Match Evaluation Method (Milestone #18)

• RegexMatchExtractor + StringMatchScorer
• BBH (BIG-Bench Hard) 為首個 use case
• 66 個 unit tests

Full Changelog: v2.5.0...v2.6.0

v2.5.0 — Text-to-SQL Evaluation (Spider 1.0 / BIRD / Spider 2.0-lite)

Text-to-SQL Evaluation

Unified text2sql evaluation method supporting three major text-to-SQL benchmarks:

New Features

• SQL Extractor: extracts SQL from LLM responses (```sql blocks, plain SELECT, mixed text)
• SQL Scorer: two scoring modes
  • Execution Accuracy (EX): executes predicted + gold SQL against SQLite, compares result sets (default)
  • Exact Match (EM): normalized SQL string comparison
• Read-only SQLite execution: mode=ro + PRAGMA query_only = ON

Supported Benchmarks

Benchmark	Example Size	Databases	Notes
Spider 1.0	10 rows	concert_singer, pets_1	Cross-domain text-to-SQL
BIRD	10 rows	california_schools, financial	With external knowledge (evidence)
Spider 2.0-lite	10 rows	book_store	SQLite-only subset (85 questions in full)

Spider 2.0: Only lite version supported — full version requires BigQuery/Snowflake cloud credentials.

Config Example

evaluation:
  evaluation_method: "text2sql"
  strategy_config:
    text2sql_scoring_mode: "exec"
    text2sql_db_base_path: "datasets/example/spider/databases"

Test Results (Devstral-Small-2-24B-Instruct-2512, EX mode)

Dataset	Accuracy
Spider 1.0	90%
BIRD	60%
Spider 2.0-lite	80%

Full Changelog: v2.4.0...v2.5.0

v2.4.0 — RAGAS Evaluation (LLM-as-Judge for RAG Pipelines)

New Benchmark: RAGAS (Retrieval-Augmented Generation Assessment)

Evaluate RAG pipeline quality using LLM-as-judge, measuring faithfulness, answer relevancy, context precision, and context recall.

Key Design

• LLM-as-Judge: The model in config.yaml acts as the judge (not the model being evaluated)
• Consolidated prompt: 1 LLM call per sample (vs official RAGAS's 6-8 multi-step calls), ~1/6 API cost
• No extra dependencies: Self-implemented scoring logic, no langchain/ragas dependency
• 36 tests: full coverage of extractor, scorer, presets, example dataset

Usage

evaluation:
  dataset_paths:
    - "datasets/example/ragas/"
  evaluation_method: "ragas"

4 Metrics (each 0.0–1.0)

Metric	What it measures
faithfulness	Are response claims supported by retrieved context?
answer_relevancy	How relevant is the response to the question?
context_precision	Is the retrieved context relevant?
context_recall	Does context cover the reference answer?

Example Dataset

10 rows from explodinggradients/WikiEval (5 good + 3 ungrounded + 2 poor answers) for sanity checking.

Full Changelog: v2.3.0...v2.4.0

v2.3.0 — NIAH (Needle in a Haystack) Benchmark

New Benchmark: NIAH (Needle in a Haystack)

Tests LLM long-context retrieval by inserting a "needle" fact at varying depths in a long "haystack" document.

Features

• 3 data sources: Kamradt Original (EN), NeedleBench (ZH+EN), LongBench (ZH)
• 3 scoring modes: substring match (default), exact match, token-level F1
• Custom dataset generator: --generate-niah CLI tool to create NIAH tests from your own text
• Config template: config.niah.template.yaml
• 49 tests: full coverage of extractor, scorer, generator, presets, example datasets

Usage

evaluation:
  dataset_paths:
    - "datasets/example/niah/kamradt/"
  evaluation_method: "niah"

Generator

twinkle-eval --generate-niah \
    --haystack my_docs.txt \
    --needle "The secret code is 42." \
    --question "What is the secret code?" \
    --answer "42" \
    --context-lengths 1024,4096,16384 \
    --needle-depths 0,25,50,75,100

Other Changes

• CLAUDE.md: require full pytest tests/ run before PR submission (§6.6, §13)

Full Changelog: v2.2.0...v2.3.0