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），以最小的推理成本带来接近最先进的准确度。