jevlike是一个用单次前向传播（one-pass）给一组动态文本选项打分的 PyTorch 小模型框架：输入一段context和N个选项，直接输出每个选项一个概率，而不是逐词生成答案。它的灵魂在于可以互换的编码器——本文带你从零搞懂它的两条路线：从零学 byte 编码的 TinyScorer与冻结 Qwen2.5-0.5B 的 FrozenTransformerScorer，并给出手把手的训练命令与选型清单。

💡 一句话理解：编码器负责"把文字变成向量"，打分头负责"给每个选项打一个分"。jevlike 的妙处是——打分头只有一个，换的只是编码器。

为什么需要"一次打完所有选项"的编码器

传统生成模型要一个字一个字把答案"写"出来，而选择任务（客服工单分类、菜单点击预测、多选项问答）其实只需要回答"哪一个"。jevlike 用一次前向就给出所有选项的概率，README 中测得：在 8 个选项下，单次打分比让一个小 decoder 写 400 个 token 快约 100 倍。

整个流程只有三步，看懂这三步，两条路线的差异就一目了然：

1. 每个选项变成一个查询向量（query）；
2. 该选项对上下文 token分配注意力权重，聚合出一个"上下文向量"；
3. 共享点积把每对（选项, 上下文）变成一个分数，再 softmax 成概率。

这条链路就封装在一个通用的注意力头里，源码见 jevlike/model.py 的AttentionHead。下面这张图正是这条"Q/K/V → 注意力 → 单概率"的数据流：

两条编码器路线一张图看懂

两条路线共用同一个打分头，区别只在"文字怎么变成向量"：

下面分别"上手"。

路线一：TinyScorer——byte 编码从零起步

什么是 byte 编码

byte 编码就是把文本直接按 UTF-8 拆成字节，每个字节值 +1 作为嵌入下标（0 保留给 padding），查一张"字节→向量"的表。它不依赖任何分词器、不需要下载大模型，因此零门槛，但模型必须从零学会这些字节代表什么语义，所以更依赖数据、在语言理解上偏弱。

核心实现只有几行：字节化在 jevlike/data.py 的_bytes()，模型主体在 jevlike/model.py 的TinyScorer——nn.Embedding(257, width)是一张"256 种字节 + 1 padding"的查表，再叠一个位置嵌入。

🎯 默认上下文截断到192 字节、每个选项32 字节。文本更长时，调大--context-tokens/--option-tokens即可。

安装并训练 TinyScorer（一键步骤）

以下命令在仓库根目录执行，会创建合成数据、训练、评估并给一个新菜单打分：

# 1. 准备环境（仅核心依赖即可，CPU 也能跑） uv venv source .venv/bin/activate uv pip install -e '.[dev]' # 2. 生成合成数据集（train/validation/test） jevlike-data synthetic --output data/synthetic # 3. 训练 byte 编码器（默认 --encoder tiny） jevlike-train data/synthetic/train.jsonl \ --validation data/synthetic/validation.jsonl \ --output runs/synthetic.pt # 4. 在留出测试集上评估 jevlike-eval runs/synthetic.pt data/synthetic/test.jsonl # 5. 给一条新菜单逐选项打分 jevlike-predict runs/synthetic.pt \ --context "Choose the exact badge amber badger. Badge: amber badger." \ --option "azure crane" \ --option "amber badger" \ --option "gold heron"

训练入口与全部可调参数见 jevlike/train.py：--width（嵌入宽度，默认 64）、--rank（打分头宽度，默认 64）、--epochs（默认 8）、--device auto|cpu|mps|cuda。

数据长什么样

训练用一行一个 JSON 对象，label是正确选项的从零开始的下标，每行选项数量可以不同（至少 2 个）：

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

路线二：FrozenTransformerScorer——冻结 Qwen2.5-0.5B 当编码器

冻结编码器是什么意思

"冻结"指加载一个预训练编码器后把它的权重锁死不再更新（requires_grad_(False)），只训练顶上那层很小的打分头。好处是白捡大模型已学好的语言语义，样本效率更高；代价是要先下载模型、显存占用更大。

实现见 jevlike/model.py 的FrozenTransformerScorer：AutoModel.from_pretrained载入编码器，取其last_hidden_state，选项用 mask 做均值池化，再喂进同一个AttentionHead。数据由HuggingFaceCollator（带 tokenizer）整理，见 jevlike/data.py。

⚠️注意：checkpoint 里只存"打分头 + 编码器名字"，不存冻结权重。所以加载模型时仍需能访问同一个 Hugging Face 模型。

训练冻结 Qwen 编码器（最快配置方法）

先装可选依赖，再指定编码器与模型名即可：

# 1. 装 transformers 扩展 uv pip install -e '.[transformers]' # 2. 用冻结 Qwen2.5-0.5B 作为编码器训练 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

• --encoder hf切换到冻结编码器路线；--hf-model可换成任意兼容的 Hugging Face 编码器。
• --rank控制打分头宽度：更宽的可训练参数更多、效果上限更高，但更吃内存（所以示例把--batch-size压到 8）。
• 之后照旧jevlike-eval/jevlike-predict，命令与 byte 路线完全一致。

两条路线怎么选：选型对照清单

按你的实际情况对号入座，避免"盲目上大模型"：

• 想先跑通、看流程、CPU 训练→ 选TinyScorer（byte），轻量快、零下载。
• 数据是真实自然语言、语义敏感（如工单分类、页面点击预测）→ 选FrozenTransformerScorer，冻结大模型的语言能力直接可用。
• 样本很少→ 优先冻结编码器，预训练知识能显著省样本。
• 要部署到边缘/低配环境→ byte 编码器更合适。
• 显存紧张但仍想要语义→ 保持--rank偏小、调小--batch-size。

📌 一个直观判断：byte 路线"便宜但弱语义"，冻结路线"贵但懂语言"。很多团队会先用 byte 跑通管线，确认数据无误后再切 hf 编码器冲效果。

真实基准：合成菜单 98% vs Wikispeedia 26%

README 的"What to expect"给出了本地实验的参考数字，帮你建立合理预期（注意：这是本地实验，非你的运行结果）：

• 合成菜单：单次打分器达到约 98%准确率——说明 byte 路线在"结构清晰、模式明确"的数据上完全够用。
• Wikispeedia 下一跳点击（target-disjoint）：冻结 Qwen2.5-0.5B + 打分头达到26%，而"打乱上下文 / 随机编码器"对照只有约 8%——说明冻结路线在真实语义任务上的优势是实打实的。
• 从零训练的小模型在 4 万条点击上达到29%，接近冻结路线，但需要更多数据与训练。

Wikispeedia 数据由脚本自动下载并构建成 JSONL，见 scripts/get_wikispeedia.sh（数据保存在仓库外）。

常见坑与提速建议

• byte 路线准确率上不去？多半是文本被 192 字节截断了——先调--context-tokens/--option-tokens，再看是否需要换冻结编码器。
• --encoder hf报缺依赖？你只装了核心包，记得uv pip install -e '.[transformers]'。
• 加载 checkpoint 失败？冻结路线要求本机仍能访问同一个 HF 模型，确认网络与模型名一致。
• 想验证"模型真在学上下文"？jevlike-eval会额外输出一组shuffled-context 对照（把菜单配错上下文），好模型应显著优于该对照——指标定义见 jevlike/eval.py。
• 评估看三个数：top-1 准确率（首选命中率）、top-3 命中率、ECE（校准误差）。
• 设备选择：--device auto自动挑 CUDA → MPS → CPU；游戏/视觉示例在 jevlike/vision.py 复用同一打分头。

✅ 冒烟测试：pytest -q会跑 tests/test_smoke.py，验证 TinyScorer 确实能从高损失降到低损失、且概率和为 1。

参考文件与延伸阅读

• 模型与打分头：jevlike/model.py（AttentionHead/TinyScorer/FrozenTransformerScorer/make_system）
• 数据与 byte 分词：jevlike/data.py
• 训练入口与参数：jevlike/train.py
• 评估与校准：jevlike/eval.py
• 单条打分：jevlike/predict.py
• Wikispeedia 数据构建：scripts/get_wikispeedia.sh
• 架构总览与命令：README.md

小结：jevlike 把"编码器"和"打分头"解耦——TinyScorer 用 byte 编码从零起步、轻快好上手，FrozenTransformerScorer 冻结 Qwen2.5-0.5B 复用语义、效果更稳。选哪条，取决于你的数据语言复杂度与算力预算；先用 byte 跑通、再用冻结编码器冲效果，是最稳妥的路径。🚀