nokia-applied-research/AnyJev

📦 AnyJev – あらゆる LLM を校正された意思決定モデルに変える

AnyJev（Any Jev）は、オープンソース LLM に型付き質問（例：多肢選択、はい/いいえ、数値評価）をし、モデルの next‑token ロジットから直接確率ベースの意思決定を得られる Python ライブラリです。テキストを生成せず、微調整も不要で、ゼロラベル例でも動作します。数百のラベルがあれば、より高精度な「L2」ヘッドにアップグレードでき、その実行コストは実質的に単一のフォワードパスと同じです。

---

🎯 どのような問題を解決するか？

• LLM の生のロジットは不安定です – 回答オプションの順序を入れ替えるとモデルの予測が変わることが多く、信頼スコアの校正も不十分です。
• スコアが信頼できないため、ほとんどのパイプラインは人間によるレビューにフォールバックし、リソースを浪費します。
• AnyJev はレベルの校正を 3 つ提供します：
  • 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	なし	各オプションのトークンロジットに対する soft‑max を返します（ナイーブベースライン）。	バイアス補正や校正は一切行いません。
L0	なし	オプションリストを K 回回転させ、ロジットを平均し、推定されたラベル事前分布で割ります。順序反転バイアスを除去します。	モデルの不確実性を統計的に校正しません。
L1	質問ごとに 100‑500	L0 の上に温度スケーリングを適合させます。	オプションのランキングは変更しません。
L2	質問ごとに 100‑300	モデル深さの約 ⅔ の隠れ状態で閉形式線形ヘッド（縮小 LDA / ridge）を解きます。入力ごとに 1 回のプロンプト、その後サービング時に安価な行列乗算。	再適合なしでは、別の質問やモデルに転送できません。

L2 ヘッドは小さなアーティファクト（≈100 KB）で、[hidden, K] 行列、バイアス、標準化ベクトル、温度を含みます。CPU で数秒で計算され、単一の切り詰められたフォワード（例：36 ブロックモデルのブロック 24 で停止）で推論に使用されます。

---

📊 報告された結果（BANKING77 20 ウェイベンチマークでの Qwen3‑8B）

メトリック	生のロジット	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×（1 つのプロンプトを早期停止）。L0 は K 回のプリフィルが必要（H100 で K=20 の場合、決定あたり約 0.25 秒）。

---

🛣️ ロードマップ（README 時点）

• ✅ 単一のプリフィルで choice、noul、score 質問を実装。
• ✅ L0（ゼロラベル）および L1 アーティファクト、レベル強制。
• ✅ L2 閉形式ヘッド、自動ラベルフリー適応、observe ループ。
• ✅ 5 つの Qwen3 モデル用の事前構築ヘッドとデモ CLI。
• ⏳ すべての決定をより安価にするための速度最適化。
• ⏳ vLLM / SGLang を介したサービングのサポート（固定ブロックでの残差ストリームを使用）。
• ⏳ 完全なエージェントループ評価（実際のエージェント内で LLM を置き換え）。
• ⏳ ヘッドの公開ハブ、インタラクティブな Space、テクニカルレポート。
• ⏳ より多くのベースモデル（Llama、Gemma、Mistral、DeepSeek）とより大きなオプションセット（>26）への拡張。

---

⚠️ 制限事項（明示的にリスト）

• 精度は教師 LLM に対して測定されており、人間のゴールドスタンダードではありません。
• L2 ヘッドは質問ごと、モデルごとに固有です。質問間や他のモデルには転送できません（現在は Qwen3 ヘッドのみ提供）。
• 校正は、モデルがタスク（迷路ナビゲーション、マインスイーパなど）に単純に答えられない場合を補償できません。
• 1 つのラベルが事前分布を支配する場合、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 の生のノイズの多いロジットを、信頼性が高く確率校正された意思決定に変換する実用的でゼロラベル不要の方法を提供し、軽量な閉形式ヘッド（L2）により、最小限の推論コストで最先端に近い精度を実現します。