nokia-applied-research/AnyJev

📦 AnyJev – 將任何 LLM 變成校準的決策模型

AnyJev（Any Jev）是一個 Python 函式庫，讓您可以向開源 LLM 提出型別化問題（例如多選、是/否或數值評分），並直接從模型的 next‑token logits 獲得基於機率的決策。它不生成文字，不需要微調，且可以在零標籤範例下運作。使用數百個標籤，您可以升級到更高準確度的「L2」頭，其運行成本基本上等同於一次前向傳播。

---

🎯 它解決了什麼問題？

• LLM 的原始 logits 不穩定 – 翻轉答案選項的順序通常會翻轉模型的預測，且信心分數校準不佳。
• 由於分數不可信，大多數流程會退回人工審查，浪費資源。
• AnyJev 提供三個層級的校準：
  • L0 – 零標籤校正，移除選項順序偏差。
  • L1 – 使用每個問題 100-500 個標籤的溫度縮放。
  • L2 – 在 100-300 個標籤上訓練的閉式線性頭（收縮 LDA / ridge），以單次截斷前向傳播的成本提供校準的機率。

---

🚀 快速開始（來自 README）

pip install "anyjev[hf]"

from anyjev import Decider, Question
from anyjev.backends.hf import HFBackend

d = Decider(HFBackend("Qwen/Qwen3-8B"))

# 定義型別化問題
route = Question.choice(
    "哪個團隊應該處理這個？",
    ["billing", "technical", "sales", "other"],
    name="route"
)
risky = Question.noul("這個工具呼叫是否具有破壞性？", name="risky")
done  = Question.score("任務完成度如何？", bins=5, name="done")

# 執行決策
state = {"conversation": [...], "tool_call": {...}}
result = d.decide(state, [route, risky, done])
print(result["route"].distribution)   # {'billing': 0.81, 'technical': 0.07, ...}
print(result["risky"].p_true)          # 0.12
print(result["done"].value)            # 0.35
print(result.level)                     # "L0"

稍後添加標籤以升級到 L1/L2：

# 為一個問題收集 100‑500 個標籤範例
d.calibrate(risky, states, labels)      # L1 – 溫度縮放
d.fit_head(route, states, labels)       # L2 – 閉式頭

d.save_artifacts("qwen3-8b.json")      # 儲存頭（≈100 KB）

現在 d.decide(..., level="auto") 將在存在頭時自動使用 L2，否則回退到 L1 或 L0。

---

🧠 運作方式（高層級）

層級	所需標籤	功能	不做什麼
raw	無	返回每個選項的 token logits 的 soft‑max（樸素基線）。	任何偏差校正或校準。
L0	無	將選項列表旋轉 K 次，平均 logits，並除以估計的標籤先驗。移除順序翻轉偏差。	不使模型的不確定性在統計上校準。
L1	每個問題 100‑500	在 L0 之上擬合溫度縮放。	不改變選項的排名。
L2	每個問題 100‑300	在模型深度約 ⅔ 處的隱藏狀態上求解閉式線性頭（收縮 LDA / ridge）。每個輸入一次提示，然後在服務時進行廉價的矩陣乘法。	無法轉移到不同的問題或模型，除非重新擬合。

L2 頭是小型工件（≈100 KB），包含 [hidden, K] 矩陣、偏差、標準化向量和溫度。它們在 CPU 上幾秒內計算，然後用於推理，只需一次截斷前向傳播（例如，在 36 塊模型中的第 24 塊停止）。

---

📊 報告結果（Qwen3‑8B 在 BANKING77 20 路基準上）

指標	原始 logits	AnyJev L0（零標籤）	AnyJev L1（100‑500 標籤）	AnyJev L2（100‑300 標籤）
答案順序翻轉率	0.230	0.073	0.077	–
準確度	0.747	0.803	0.807	–
期望校準誤差	0.240	0.184	0.095	–
自動可決策 @ ≤5 % 誤差（可安全自動化的流量比例）	7.7 %	46.3 %	52.0 %	–

延遲：L2 的成本約為 Qwen3‑8B 完整前向傳播的 ≈0.68×（一個提示提前停止）。L0 需要 K 次預填充（在 H100 上，K=20 時每次決策約 0.25 秒）。

---

🛣️ 路線圖（截至 README）

• ✅ 使用單次預填充實現 choice、noul、score 問題。
• ✅ L0（零標籤）和 L1 工件；層級強制。
• ✅ L2 閉式頭、自動無標籤適應、observe 迴圈。
• ✅ 五個 Qwen3 模型的預建頭和演示 CLI。
• ⏳ 速度最佳化，使每個決策更便宜。
• ⏳ 支援透過 vLLM / SGLang 服務（使用固定塊處的殘差流）。
• ⏳ 完整代理迴圈評估（在真實代理中替換 LLM）。
• ⏳ 頭的公共中心、互動式 Space 和技術報告。
• ⏳ 擴展到更多基礎模型（Llama、Gemma、Mistral、DeepSeek）和更大的選項集（>26）。

---

⚠️ 限制（明確列出）

• 準確度是相對於教師 LLM 測量的，而非人類黃金標準。
• L2 頭是每個問題和每個模型特定的；它們不會跨問題或跨模型轉移（目前僅提供 Qwen3 頭）。
• 校準無法彌補模型根本無法回答任務的情況（例如迷宮導航、踩地雷）。
• 當一個標籤主導先驗時，L0 可能損害準確度。
• 該函式庫目前每個選擇最多支援 26 個選項（跨度讀出計畫中）。
• 5 % 風險下的覆蓋率估計在 n = 300 測試項目時具有高變異性。
• 所有決策都在隔離中評估，而非在端到端代理迴圈中。

---

📦 安裝與授權

• 使用可選的 Hugging‑Face 後端安裝：pip install "anyjev[hf]"。
• 套件發布在 PyPI（anyjev），支援 Python 3.8+。
• 授權： Apache‑2.0。

---

📚 進一步閱讀與引用

• 完整方法描述：docs/method_v3.md。
• 基準測試：docs/results_bench.md、docs/results_exit.md。
• 演示腳本：demo/jev_mode、demo/games（2048、踩地雷）。
• 引用方式：

@software{anyjev2026,
  title  = {AnyJev: Turn any LLM into a Jev-style decision model},
  author = {Zhang, Jiamu and Yang, Tianze and Shi, Yucheng and Wu, Liang},
  year   = {2026},
  url    = {https://github.com/nokia-applied-research/AnyJev}
}

---

底線： AnyJev 提供了一種實用、無需標籤的方式，將任何開源 LLM 的原始、嘈雜 logits 轉換為可信賴的、機率校準的決策，以及一個輕量級閉式頭（L2），以最小的推理成本帶來接近最先進的準確度。