一個基於 🎈 Streamlit 的互動式工具，用來分析 Twinkle Eval 格式的評估檔案（.json / .jsonl）。

• Twinkle Eval Analyzer (Zeabur 部署) (thanks @BbsonLin)
• Eval Analyzer (GitHub Pages) (thanks @doggy8088)
• Eval Analyzer (Streamlit Cloud) (thanks @thliang01)

圖：gpt-oss-120b 在 MMLU 部分子集上的表現成績預覽

• 支援上傳多個 Twinkle Eval 檔案（json / jsonl）。
• 自動解析評估結果，抽取：
  • dataset
  • category
  • file
  • accuracy_mean
  • source_label（模型名稱 + timestamp）
• 提供整體平均值的計算，缺漏時自動補足。
• 分數閾值篩選：
  • 支援兩種篩選模式：
    • 任一模型符合：只要有任一個模型在該類別符合條件，就顯示該類別和所有模型的分數。
    • 特定模型符合：篩選特定模型符合條件的類別（需選擇要篩選的模型）。
  • 可設定閾值條件：≥ 或 ≤ 特定分數。
  • 根據顯示比例（0–1 或 0–100）自動調整閾值範圍。
  • 篩選後自動更新圖表、分頁顯示及排序。
  • 若無符合條件的類別，顯示提示訊息。
• 視覺化：
  • 各類別的柱狀圖（依模型分組對照）。
  • 可選擇排序方式（平均由高→低、平均由低→高、字母排序）。
  • 支援分頁顯示（自訂每頁顯示類別數量）。
  • 指標可切換為原始值或 0–100 比例。
• 支援 CSV 匯出（下載分頁結果）。

• 基準模型比較：選擇一個基準模型（Baseline）與多個候選模型（Candidates）進行差距分析。
• 差距計算：自動計算 Δ = Candidate 分數 − Baseline 分數。
• 多種排序模式：
  • |Δ| 由大到小：依絕對差距排序，找出差異最大的項目。
  • Δ 由大到小（提升最多）：找出候選模型相對基準提升最多的類別。
  • Δ 由小到大（下降最多）：找出候選模型相對基準下降最多的類別。
  • 依類別名稱：依字母順序排列。
• 差距門檻過濾：可設定最小差距門檻，只顯示 |Δ| ≥ 門檻的類別。
• 視覺化呈現：
  • per-category 排行圖：每個候選模型獨立分面，以水平長條圖顯示各類別的差距。
  • per-candidate 總結：統計各候選模型的 Mean Δ、Median Δ、Win/Lose/Tie 次數及覆蓋率。
  • Top/Bottom-N 清單：顯示每個候選模型提升最多與下降最多的 N 個類別。
• CSV 匯出：支援下載差距排行、總覽表、Top/Bottom-N 清單。

建議使用虛擬環境（如 venv 或 conda）：

pip install -r requirements.txt

streamlit run app.py

1. 在左側 Sidebar 上傳一個或多個 Twinkle Eval 檔案。
2. 選擇要查看的資料集。
3. 設定排序方式、分頁大小、顯示比例（0–1 或 0–100）。
4. 查看圖表與資料表，並可下載 CSV。

1. 在「差距分析設定」中選擇排序方式與差距門檻。
2. 在差距分析區塊選擇基準模型（Baseline）。
3. 選擇一個或多個候選模型（Candidates）進行比較。
4. 查看差距排行圖表與統計總結。
5. 下載差距分析結果（CSV 格式）。

每份 json / jsonl 檔案需符合 Twinkle Eval 格式，至少包含以下欄位：

{
  "timestamp": "2025-08-20T10:00:00",
  "config": {
    "model": { "name": "my-model" }
  },
  "dataset_results": {
    "datasets/my_dataset": {
      "average_accuracy": 0.85,
      "results": [
        {
          "file": "category1.json",
          "accuracy_mean": 0.9
        },
        {
          "file": "category2.json",
          "accuracy_mean": 0.8
        }
      ]
    }
  }
}

或者可以到 Twinkle AI Eval logs collections 下載範例。

重要提醒：此工具目前支援特定的 JSON/JSONL 格式。來自外部資料集（如 Hugging Face 儲存庫）的檔案可能無法直接相容。

• 缺少必要欄位：缺少 config 或 dataset_results 欄位的檔案將無法載入
• 錯誤的檔案命名：請使用 results_*.json 而非 eval_results_*.jsonl 格式
• 外部資料集格式：來自其他工具或儲存庫的評估日誌可能使用不同的架構
• 欄位命名：不同的欄位名稱（例如 accuracy vs accuracy_mean）可能導致解析錯誤

如果遇到「缺少必要欄位」錯誤：

1. 確認您的檔案包含所有必要的頂層欄位
2. 檢查巢狀物件是否遵循預期結構
3. 對於外部資料集，考慮建立轉換腳本或提出議題請求格式支援

我們歡迎支援額外格式的貢獻！請參閱我們的貢獻指南或提交功能請求。

• 圖表：顯示各模型在不同類別的 accuracy_mean 比較。
• 表格：Pivot Table，行為類別，列為模型，值為 accuracy。
• 下載：每頁結果可匯出成 CSV。

• 差距排行圖：水平長條圖顯示各類別相對於基準的差距（Δ），每個候選模型獨立分面。
• 總覽表：顯示各候選模型的平均差距、中位數差距、勝敗次數與覆蓋率。
• Top/Bottom-N 清單：展開式面板顯示每個候選模型提升與下降最多的類別詳細資訊。
• 下載：支援匯出差距排行、總覽表、Top/Bottom-N 清單（CSV 格式）。

MIT