9B-5949/RUNTIME.md

# 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` 时：

```bash
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` 改为 `.`。

```python
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，不能用静态测试代替）

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

原始数值等价门结果：`False`，保留原结果；决策完全一致门：`False`，一致 `159/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`。没有新增学习参数。