xDAN-openJet merged reference runtime

本目录是可随 HF merged 仓库发布的完整 Python 源码闭包，不需要安装 ms-swift、PEFT 或原项目。发布选择为 4B checkpoint-5949、9B checkpoint-3000 与 9B checkpoint-5949；各目录必须保留自己的 depth_config.json、完整 Qwen config、tokenizer、chat template、generation config 和 merged safetensors。不得将不同 checkpoint 的权重或 shallow/full 结果拼在一起。

运行

使用 CUDA 对应 PyTorch 2.8.0 构建，安装 requirements.txt。运行依赖 Transformer 私有模型层接口，所以严格要求 transformers==5.16.1；版本升级需重做层级及数值验证。这是原生 PyTorch 单卡单请求参考实现，不是 vLLM 服务。

先把发布仓库的固定 commit完整下载到本机目录。仓库根目录有本目录中的 openjet_runtime/ 与 examples.py 时：

python -m pip install -r requirements.txt
python examples.py ./model-snapshot --device cuda:0 --effort both
python examples.py ./model-snapshot --device cuda:0 --effort high --text

若代码与权重同在下载快照根目录，进入快照后把 ./model-snapshot 改为 .。

from openjet_runtime import OpenJet
from examples import decision_examples

model = OpenJet.from_pretrained("./model-snapshot")
two_candidates, sixteen_candidates = decision_examples()
print(model.decide(two_candidates, effort="low"))
print(model.decide(sixteen_candidates, effort="high"))
print(model.generate_text("Return only the text: red shoes", effort="high", max_new_tokens=32))

examples.py 中两候选工作流、16 候选浏览器和 TYPE 是接口演示，不是声称模型已通过的 benchmark。需要针对业务设计 prompt 和验证答案。

接口和执行语义

decide(request, effort) 输入字段与原 jev.dynamic.prompt.v2 相同：id/group_id/state/instructions/primitive/criteria；每个候选有非空 id 和 description，2–16 个，ID 不重复。标签为 A–P，编译器验证每个标签在真实回答边界恰为一个 token。没有 gold 输入需求。
primitive="choice" 返回 choice 与按输入顺序映射的 probabilities；noul/score_level 使用 contracts.py 中固定 Yes/No 候选，返回 yes_probability。score_level 是单个命题的判断，不能当作完整序数 Score API。
effort="low" 执行 depth_config.exit_depth（这两项发布预期16），共享原 LM final norm 与候选行投影；high 执行 full_depth（预期32），保持原评测中的标准模型前向+完整 LM head 路径。读取 config，不凭参数规模推测层数。
所有输入采用 tokenizer 自带 chat template、enable_thinking=False，超过8192 token直接报错。不会默默截断 state、instructions 或候选。
probabilities 是在当前候选集上的相对 softmax，未经概率校准；合并不自动带来可信置信度或校准保证。
generate_text 为 TYPE 文本保留的贪心参考路径；每个 token 重新计算前缀，方便与原评测逐 token 核对，但不适合宣传 tokens/s。达到上限明确返回 finish_reason="length"。
both 示例分别调用两个 effort；没有自动路由、不承诺共享两次调用的前缀缓存。本次便携发布不包含 KV 广播引擎、vLLM 插件、TypeSafe HTTP server 或多模态输入能力。

合并验收（GPU，不能用静态测试代替）

固定同一 base revision、adapter SHA、tokenizer、chat template、dtype、attention backend 和 Transformers 版本，记录 merge 前后权重身份。保留 adapter 原文件。
同进程/新进程分别加载 base+adapter 和 merged；比较固定2候选、16候选、长输入、80题面板两 effort 的 token IDs、候选排序、logits、probabilities 和最终ID。保存逐题差异与最大绝对差，不能只比 aggregate accuracy。
BF16 merge 会舍入：不能预先声明 bitwise一致或把漂移简单解释为无害；应报告数值误差和所有预测翻转。若超过事先制定的容忍值，停止发布数值等价结论，考虑 FP32 merge/存储再独立评测。
fresh reload 验证 depth_config 与实际层数、模块边界一致。用层 forward hooks 检查 low只执行浅层、high执行全层；hooks会触发候选头保守fallback，不拿该测量做性能报告。
TYPE短样本比较 token序列和EOS；分别测试空输入、非法候选/重复ID、超长输入明确失败。
在干净环境固定 HF revision 下载，运行本目录例子和同一小面板。记录显存、依赖、GPU型号以及权重checksum。成功加载只是第一关，不能当作质量或吞吐验收。

原始数值等价门结果：False，保留原结果；决策完全一致门：True，一致 160/160。独立运行时 GPU 验收状态：passed。若数值门失败，此 BF16 包作为独立重评版本，禁止直接迁移概率/拒答/路由阈值；见 merged-evaluation.json。

源码来历

contracts.py、candidate_projection.py 与 early_exit.py 从已有本地实现原样提取（最后一项仅调整相对 import）；source-provenance.json 记录源路径与两端 SHA256。runtime.py 是最小加载及接口层；high 与 TYPE 分别对应原 HFDecisionEngine._forward_batch 和 package_eval.prefix_next_token 的执行语义。采用现有模型类：qwen3_5 → Qwen3_5ForConditionalGeneration；qwen3_5_text → AutoModelForCausalLM。没有新增学习参数。