jevlike：用于文本选项的开源 Jev 风格单次评分器

快速要点

jevlike 提供了一个轻量级、开源的 Jev 风格单次评分器实现，可为可变长度的文本选项列表分配概率，实现无需逐 token 生成的快速、确定性选择。

仓库提供的内容

一个最小模型，接受一个 上下文 字符串和任意长度的选项列表，并在一次前向传播中返回每个选项的概率。
两个经典交互环境（Doom 和国际象棋）的参考实现，展示模型如何直接从视觉块中评分控制器按钮。
一个合成数据生成器、训练脚本、评估工具和命令行预测器，支持快速实验。
通过 Hugging Face transformers 库可选支持冻结的预训练编码器（例如 Qwen2.5‑0.5B）。
MIT 许可的代码，任何下载的数据集或预训练权重有独立的许可条款。

核心架构详解

每个选项变成一个查询向量，即代表其文本的一小段数字列表。该查询为上下文 token 分配注意力权重，这些权重为该选项生成一个上下文向量。一个共享的点积将每个选项和上下文对转换为一个分数。一个 softmax 将分数转换为总和为一的概率分布，作用于选项维度。

选项查询 – 每个选项被嵌入（默认为字节级，或通过冻结编码器）为一个固定大小的向量，作为查询。
上下文上的注意力 – 查询关注上下文的 token 嵌入，生成一个特定于选项的上下文向量。
评分头 – 一个共享的线性点积层为每个（选项，上下文）对计算一个标量分数。
Softmax 归一化 – 分数通过选项维度的 softmax，生成一个概率分布。

该设计模仿了 TypeSafe 的 Jev 系统中描述的“选项注意力头”，但完全公开且可扩展。

数据格式与准备

输入文件为 JSONL，每行一个对象：

{"context":"The customer needs a refund.","options":["refund","sales","technical support"],"label":0}

label 是正确选项的零基索引。
每行的选项数量可变，但最少为两个。
对于自定义数据集，确保每行包含推理时可能出现的所有选项，并将相关记录一起划分，以避免泄露。

快速上手（合成演示）

# 创建虚拟环境并安装开发依赖
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'

# 生成合成数据
jevlike-data synthetic --output data/synthetic

# 在合成训练集上训练
jevlike-train data/synthetic/train.jsonl \
  --validation data/synthetic/validation.jsonl \
  --output runs/synthetic.pt

# 在合成测试集上评估
jevlike-eval runs/synthetic.pt data/synthetic/test.jsonl

# 对新菜单进行预测
jevlike-predict runs/synthetic.pt \
  --context "Choose the exact badge amber badger. Badge: amber badger." \
  --option "azure crane" \
  --option "amber badger" \
  --option "gold heron"

评估报告包括 top‑1 和 top‑3 准确率、预期校准误差以及随机上下文对照。一个有用的模型应优于对照组。

使用冻结的预训练编码器

uv pip install -e '.[transformers]'
jevlike-train data/synthetic/train.jsonl \
  --validation data/synthetic/validation.jsonl \
  --output runs/qwen-head.pt \
  --encoder hf \
  --hf-model Qwen/Qwen2.5-0.5B \
  --rank 256 \
  --batch-size 8

检查点仅存储训练好的评分头和编码器标识符；编码器权重在运行时从 Hugging Face 加载。
--rank 控制评分头的宽度（更高 rank = 更多参数，更高内存）。

现实世界示例

Doom 控制器评分

仓库附带一个联合检查点，可从原始图像块中评分七个 Doom 控制器按钮。
一个十秒的演示影片将 Doom 战斗与国际象棋控制器移动棋子结合，说明相同的选项注意力头可处理视觉和文本输入。
Doom 检查点在十次记录的对局中平均获得 0.60 次击杀 和 ‑97.50 奖励。

国际象棋走法选择

仅国际象棋的检查点对代表走法的五个键进行评分，在 50 场采样对局中对随机走法取得 4 胜、46 平、0 负。
对 Stockfish level 0，取得 0 胜、2 平、48 负，表明战略能力有限，但确认模型可处理视觉棋盘状态。

作者实验中的性能数据

合成菜单：使用单次评分器达到约 98 % 的 top‑1 准确率。
Wikispeedia 下一点击任务（目标不相交划分）：
- 冻结的 Qwen2.5‑0.5B 编码器 + 评分器 → 26 % 准确率。
- 随机编码器对照 → 约 8 % 准确率。
- 从头训练的小模型（40 k 点击）→ 29 % 准确率。
速度：在八选项情况下，单次评分器比强制生成 400 个 token 的小型解码器快约 100 倍。

这些数据为本地实验结果，并非与 TypeSafe 的专有 Jev 模型的直接对比。

Hacker News 评论中的社区洞察

扩散模型作为 Jev 风格评分器 – 一位用户链接了一个 VLLM PR，将扩散模型重新用于单次选项评分，在 DGX Spark 上实现每决策约 0.2 秒，语言检测任务中准确率很高。
开源 Qwen‑2.5‑1B‑RLCD – 另一条评论强调了最近发布的一个更快的设备端推理模型，适用于 JSON 工作负载，表明向轻量级、类型安全模型发展的趋势。
用例多样性 – 多位评论者强调，价值在于获得校准的概率权重，而非生成文本，从而支持技能冲突检测、扩散管道的飞行前成本估算以及多模态工作流中的路由决策等应用。
澄清概念 – 有评论指出，原始 TypeSafe 公告较为模糊；README 中的三句话描述（“接收一段文本和 N 个文本选项……单次……”）更清晰地捕捉了核心思想。

需要注意的局限性

该项目是研究起点，并非 TypeSafe Jev 的完整复现。
准确率高度依赖于数据质量、划分策略和所选编码器。
默认的字节编码器成本低，但缺乏深层语言理解。
使用冻结的预训练编码器可能需要大量下载和额外的 GPU 内存。
模型在推理时需要完整的选项列表，对于极大规模候选集可能不切实际。
报告的速度提升是与小型解码器对比，而非大型商业模型。

如何扩展或适配 jevlike

通过 --encoder hf 标志将字节编码器替换为更大的多语言模型（例如 LLaMA‑2、Mistral）。
增加 --rank 以提升评分头的容量，实现更细微的选项区分。
通过将视觉编码器的视觉嵌入输入到相同的选项注意力机制中，实验多模态输入（如 Doom/国际象棋演示所示）。
将预测器集成到需要概率路由或置信度感知分类的流水线中，而非确定性文本生成。
与基线分类器（逻辑回归、微调 BERT）进行基准测试，量化特定任务中速度与准确率之间的权衡。

许可与署名

代码采用 MIT 许可证发布。
数据集和预训练模型保留其原始许可条款；请查阅相应来源（例如 Wikispeedia 的 SNAP，Hugging Face 模型卡片）。