edgejev 0.1.0__py3-none-any.whl

edgejev/__init__.py

@@ -0,0 +1,10 @@
+"""EdgeJev —— 在自己的设备上跑 Jev 式的类型化决策：快、小、运行时不需要 torch。
+
+    edgejev build --backend laya --out ./jev-int8
+    from edgejev import Agent
+    Agent("./jev-int8").system_one(state, questions)
+"""
+from .agent import Agent, load
+
+__all__ = ["Agent", "load"]
+__version__ = "0.1.0"

edgejev/agent.py

@@ -0,0 +1,101 @@
+"""运行时：只依赖 onnxruntime + tokenizers + numpy。跨 Linux / macOS / Windows。"""
+import json
+import os
+from typing import Any, Dict, Optional, Union
+
+from . import backends, post, providers
+from .tokenize import Encoder
+
+CONFIG_NAME = "edgejev.json"
+
+
+class Agent:
+    """本地 System One 决策。
+
+        from edgejev import Agent
+        ag = Agent("./jev-int8")
+        ag.system_one("客户被扣了两次款", {
+            "dept": {"type": "choice", "instructions": "转给哪个组",
+                     "criteria": {"billing": "支付扣款", "technical": "程序缺陷"}}})
+    """
+
+    def __init__(self, model_dir: str, threads: Optional[int] = None,
+                 provider: Optional[str] = None):
+        cfg_path = os.path.join(model_dir, CONFIG_NAME)
+        if not os.path.exists(cfg_path):
+            raise FileNotFoundError(
+                "%s 里没有 %s，这个目录需要用 `edgejev build` 生成。" % (model_dir, CONFIG_NAME))
+        with open(cfg_path, encoding="utf-8") as f:
+            self.cfg = json.load(f)
+
+        self.backend = backends.get(self.cfg.get("backend", "laya"))
+        self.runtime = self.cfg.get("runtime", "onnx")
+        self.temperature = self.cfg.get("temperature", [1.0, 1.0, 1.0])
+        self.temperature_by_options = self.cfg.get("temperature_by_options", {})
+        self.model_name = self.cfg.get("model_name", "edgejev")
+
+        if self.runtime == "torch-vlm":
+            from .runtimes.torch_vlm import TorchVLM
+            self.vlm = TorchVLM(self.cfg["source_model"], template=self.cfg.get("template", "plain"))
+            self.provider_note = self.vlm.note
+            self.slots = self.vlm.slot_ids(self.backend)
+            return
+
+        import onnxruntime as ort
+        ids_map = {k: self.cfg[k] for k in self.cfg if k.endswith("_id")}
+        ids_map["mask_token"] = self.cfg.get("mask_token", "<mask>")
+        self.enc = Encoder.from_file(os.path.join(model_dir, "tokenizer.json"), ids_map)
+
+        so = ort.SessionOptions()
+        so.intra_op_num_threads = threads or (os.cpu_count() or 4)
+        so.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        provs, self.provider_note = providers.detect(provider)
+        self.sess = ort.InferenceSession(
+            os.path.join(model_dir, self.cfg["onnx_file"]), so, providers=provs)
+
+    def system_one(self, state: Union[str, dict, list],
+                   questions: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
+        """对一份 state 并行评估一组带类型的问题。返回与官方 /v1/systemone 同构的结果。"""
+        if not questions:
+            raise ValueError("questions 不能为空")
+        qids = list(questions.keys())
+        qs = [post.to_internal(questions[q]) for q in qids]
+
+        if self.runtime == "torch-vlm":
+            return self._vlm_system_one(state, qids, qs)
+
+        prep = self.backend.prepare(self.enc, state, qs, self.cfg)
+        outputs = self.sess.run(None, prep["feed"])
+        logits, act = self.backend.read_logits(outputs, prep)
+
+        answers = post.assemble(qs, qids, logits, act, prep["k"],
+                                self.temperature, self.temperature_by_options)
+        return {"model": self.model_name, "answers": answers,
+                "usage": {"input_tokens": prep["input_tokens"], "output_tokens": 0}}
+
+    def _vlm_system_one(self, state, qids, qs):
+        """视觉后端：每题一次前向（提示里只放一道题，读最后位置的字母槽）。"""
+        import numpy as np
+
+        image = None
+        answers = {}
+        for qid, q in zip(qids, qs):
+            opts = self.backend.options_from_question(q)
+            prompt = self.backend.build_plain_prompt(opts, q["ins"], 1)
+            if image is None:
+                from .runtimes.torch_vlm import _to_pil
+                image = _to_pil(state)
+            logits = self.vlm.last_logits(image, prompt)
+            probs, allowed = self.backend.readout(logits, self.slots, len(opts))
+            conf = round(self.backend.choice_confidence(probs), 4)
+            a = post.format_answer(q, np.asarray(probs), conf, None)
+            a["allowed_mass"] = round(allowed, 7)   # 量级在 1e-4，4 位精度会把不同输入显示成同一个数
+            answers[qid] = a
+        return {"model": self.model_name, "answers": answers,
+                "usage": {"input_tokens": 0, "output_tokens": 0}}
+
+    predict = system_one
+
+
+def load(model_dir: str, **kw) -> Agent:
+    return Agent(model_dir, **kw)

edgejev/backends/__init__.py

@@ -0,0 +1,20 @@
+"""后端注册表。新增一个后端＝加一个模块并在这里登记。"""
+from . import laya, playjev
+
+_REGISTRY = {"laya": laya, "playjev": playjev}
+
+try:
+    from . import kev
+    _REGISTRY["kev"] = kev
+except Exception:      # kev 适配器是可选的
+    pass
+
+
+def get(name):
+    if name not in _REGISTRY:
+        raise ValueError("未知后端 %r，已注册：%s" % (name, ", ".join(sorted(_REGISTRY))))
+    return _REGISTRY[name]
+
+
+def names():
+    return sorted(_REGISTRY)

edgejev/backends/base.py

@@ -0,0 +1,24 @@
+"""后端适配器协议。
+
+不同的开源 Jev 复现，序列构造和打分头完全不同：
+
+* laya   —— mmBERT 编码器，每题一个 batch 行，读 [MASK] 标记位的隐状态
+* kev    —— Qwen 解码器 + LoRA，多题打包进一条序列，block-causal 掩码，
+            PointerHead 用 <decide> 的隐状态去打各个 </opt> 位置的分
+
+所以后端必须自己负责：把 (state, questions) 变成模型输入、说明 ONNX 的输入输出签名、
+以及构建期怎么从上游 checkpoint 导出。后处理（温度、熵置信度、答案格式）是共用的。
+"""
+from typing import Any, Dict, List, Protocol
+
+
+class Backend(Protocol):
+    name: str
+    #: ONNX 图的输入名，顺序无关
+    input_names: List[str]
+
+    def prepare(self, enc, state, questions: List[Dict], cfg: Dict) -> Dict[str, Any]:
+        """返回 {"feed": {onnx输入名: ndarray}, "k": [每题的选项数]}。"""
+
+    def read_logits(self, outputs, meta: Dict) -> Any:
+        """从 ONNX 输出里取出 [问题数, 最大选项数] 的 logits 和可选的 act 概率。"""

edgejev/backends/laya.py

@@ -0,0 +1,108 @@
+"""laya 后端：mmBERT 编码器 + 两层 transformer head + marker 打分。
+
+序列格式： [CLS] <type> question: 指令 [SEP] [MASK] opt0 [MASK] opt1 ... [SEP] state [SEP]
+每个选项前的 [MASK] 位置记为 marker，scorer 读这些位置的隐状态各出一个 logit。
+每个问题占 batch 的一行，所以 N 个问题 = encoder 跑 batch=N。
+
+与上游 laya（PyTorch）逐位一致：fp32 模式下最大概率偏差 0.00000。
+"""
+import json
+from typing import Dict, List, Union
+
+import numpy as np
+
+QTYPES = {"choice": 0, "score": 1, "noul": 2}
+QTYPE_NAMES = {v: k for k, v in QTYPES.items()}
+
+name = "laya"
+input_names = ["input_ids", "attention_mask", "marker_pos", "marker_mask", "qtype"]
+TOKEN_IDS = ["cls_id", "sep_id", "mask_id", "pad_id"]
+
+
+def serialize_state(state: Union[str, dict, list]) -> str:
+    return state if isinstance(state, str) else json.dumps(state, ensure_ascii=False)
+
+
+def render_criterion(value) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, separators=(", ", ": "), default=str)
+
+
+def render_options(q: Dict) -> List[str]:
+    t, crit = q["t"], q.get("crit")
+    if t == "choice":
+        return [k if v is None or v == "" else "%s: %s" % (k, render_criterion(v))
+                for k, v in crit.items()]
+    if t == "score":
+        return ["level %d: %s" % (i, render_criterion(c)) for i, c in enumerate(crit)]
+    crit = crit or {}
+    fc, tc = crit.get("false"), crit.get("true")
+    return [
+        "false: " + (render_criterion(fc) if fc not in (None, "") else "no, the statement does not hold"),
+        "true: " + (render_criterion(tc) if tc not in (None, "") else "yes, the statement holds"),
+    ]
+
+
+def build_sequence(enc, state, q: Dict, max_len: int, head_max_len: int,
+                   truncate_left: bool = False):
+    mt = enc.mask_token
+    opts = render_options(q)
+    ins = str(q["ins"]).replace(mt, " ")
+    head_ids = enc.ids("%s question: %s" % (q["t"], ins))
+
+    opt_ids = [[enc.mask_id] + enc.ids(" " + o.replace(mt, " "))[:48] for o in opts]
+    budget = head_max_len - sum(len(o) for o in opt_ids)
+    if budget < 16:
+        per = max(4, (head_max_len - 16) // max(1, len(opt_ids)))
+        opt_ids = [o[:per] for o in opt_ids]
+        budget = head_max_len - sum(len(o) for o in opt_ids)
+    head_ids = head_ids[: max(8, budget)]
+
+    ids = [enc.cls_id] + head_ids + [enc.sep_id]
+    markers = []
+    for o in opt_ids:
+        markers.append(len(ids))
+        ids.extend(o)
+    ids.append(enc.sep_id)
+
+    room = max(0, max_len - len(ids) - 1)
+    st = enc.ids(serialize_state(state).replace(mt, " "))
+    st = st[-room:] if truncate_left else st[:room]
+    ids = ids + st + [enc.sep_id]
+    return ids[:max_len], [m for m in markers if m < max_len]
+
+
+def prepare(enc, state, questions: List[Dict], cfg: Dict) -> Dict:
+    max_len = cfg.get("max_len", 1024)
+    head_max_len = cfg.get("head_max_len", 256)
+    items = []
+    for i, q in enumerate(questions):
+        seq, markers = build_sequence(enc, state, q, max_len, head_max_len)
+        if len(markers) != len(render_options(q)):
+            raise ValueError("第 %d 个问题的选项超出 head_max_len=%d" % (i, head_max_len))
+        items.append((seq, markers, QTYPES[q["t"]]))
+
+    n = len(items)
+    L = max(len(s) for s, _, _ in items)
+    K = max(len(m) for _, m, _ in items)
+    ids = np.full((n, L), enc.pad_id, dtype=np.int64)
+    att = np.zeros((n, L), dtype=np.int64)
+    mpos = np.zeros((n, K), dtype=np.int64)
+    mmask = np.zeros((n, K), dtype=bool)
+    for i, (seq, markers, _) in enumerate(items):
+        ids[i, :len(seq)] = seq
+        att[i, :len(seq)] = 1
+        mpos[i, :len(markers)] = markers
+        mmask[i, :len(markers)] = True
+    feed = {"input_ids": ids, "attention_mask": att, "marker_pos": mpos,
+            "marker_mask": mmask,
+            "qtype": np.array([t for _, _, t in items], dtype=np.int64)}
+    return {"feed": feed, "k": [len(m) for _, m, _ in items],
+            "input_tokens": int(att.sum())}
+
+
+def read_logits(outputs, meta):
+    logits, act = outputs[0], outputs[1]
+    act = np.exp(act - act.max(-1, keepdims=True))
+    return logits, act / act.sum(-1, keepdims=True)

edgejev/backends/playjev.py

@@ -0,0 +1,111 @@
+"""PlayJev 后端：Qwen3.5-0.8B 视觉模型，从游戏画面一次前向读「选项字母」的概率。
+
+与 laya / kev 的区别，三点都很关键：
+
+1. **输入是像素**，不是文本 state。图像经 Qwen2VL 风格的处理器切成 patch。
+2. **读出方式是「字母槽」**：把选项渲染成 `A. name: desc` 的列表，取最后一个位置的
+   全词表 logits，只在 " A" / " B" ... 这 K 个 token 上做 float32 softmax。
+   上游特意用 float32：bf16 在 logit 量级 25–50 时量化步长到 0.125，会让选项打平。
+3. **置信度用 Jev 的 Choice 公式** `(p_max - 1/K) / (1 - 1/K)`，不是 laya 的归一化熵。
+
+⚠️ 这个后端**跑在 torch 上，不走 EdgeJev 的 ONNX + 量化主路径**。原因是 Qwen3.5 的文本塔是
+混合线性注意力（config 里 `layer_types` 有 `linear_attention`），那些层依赖
+`causal_conv1d` / flash-linear-attention 这类带递归状态的自定义核，没有对应的标准 ONNX 算子。
+所以用这个后端时，EdgeJev 只统一了 API 和 `serve`，拿不到「不依赖 torch」和量化加速。
+"""
+from typing import Dict, List, Sequence
+
+import numpy as np
+
+name = "playjev"
+runtime = "torch-vlm"
+
+LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+PROMPT_VERSION = "playjev-letters-v1"
+# 与上游逐字一致。上游注释说明：这段「冻结的 OpenJev 措辞」比
+# "You are a System One decision model" 那种开头高 3–6 个点，所以不要自己加前缀。
+SYSTEM_PROMPT = (
+    "Apply the question to the state. Choose exactly one of the listed options. "
+    "Respond with only its uppercase letter, with no explanation or reasoning."
+)
+DEFAULT_INSTRUCTIONS = "Which move should the player make next?"
+FRAME_PLACEHOLDER = "<|vision_start|><|image_pad|><|vision_end|>"
+PLAIN_ANSWER_CUE = "Answer:"
+
+
+def options_block(options: Sequence[dict]) -> str:
+    if len(options) > len(LETTERS):
+        raise ValueError("%d 个选项超出 %d 个字母槽" % (len(options), len(LETTERS)))
+    lines = []
+    for letter, opt in zip(LETTERS, options):
+        desc = (opt.get("description") or "").strip()
+        lines.append("%s. %s: %s" % (letter, opt["name"], desc) if desc
+                     else "%s. %s" % (letter, opt["name"]))
+    return "\n".join(lines)
+
+
+def render_suffix(options, instructions=DEFAULT_INSTRUCTIONS) -> str:
+    letters = ", ".join(LETTERS[: len(options)])
+    return ("Question: %s\n\nOptions:\n%s\n\nAnswer with one letter: %s."
+            % (instructions, options_block(options), letters))
+
+
+def render_state(n_placeholders: int) -> str:
+    return "<state>\n" + "\n".join([FRAME_PLACEHOLDER] * n_placeholders) + "\n</state>"
+
+
+def build_plain_prompt(options, instructions=DEFAULT_INSTRUCTIONS, n_placeholders=1) -> str:
+    return "%s\n\n%s\n\n%s\n%s" % (SYSTEM_PROMPT, render_state(n_placeholders),
+                                   render_suffix(options, instructions), PLAIN_ANSWER_CUE)
+
+
+def choice_confidence(probs: Sequence[float]) -> float:
+    """Jev 的 Choice 置信度：(p_max - 1/K) / (1 - 1/K)。K=1 时恒为 1。"""
+    k = len(probs)
+    if k == 1:
+        return 1.0
+    return (max(probs) - 1.0 / k) / (1.0 - 1.0 / k)
+
+
+def slot_ids(tokenizer, template="plain") -> List[int]:
+    """解析字母槽的 token id，并校验每个都是单 token 且能往返。"""
+    ids = []
+    for letter in LETTERS:
+        text = (" %s" % letter) if template == "plain" else letter
+        enc = tokenizer.encode(text, add_special_tokens=False)
+        if len(enc) != 1 or tokenizer.decode(enc) != text:
+            raise ValueError("字母槽 %r 在这个 tokenizer 下不是单个可往返的 token" % text)
+        ids.append(enc[0])
+    if len(set(ids)) != len(ids):
+        raise ValueError("字母槽 token 冲突")
+    return ids
+
+
+def readout(last_logits: np.ndarray, slot_token_ids: Sequence[int], k: int):
+    """全词表 logits（最后一个位置）-> (K 个选项的概率, allowed_mass)。
+
+    allowed_mass 是全词表 softmax 落在这 K 个答案槽上的质量，低于 ~0.5 说明模型
+    其实没在回答这道题（比如跑去输出别的 token），是很有用的健康指标。
+    """
+    z = last_logits.astype(np.float64)
+    z = z - z.max()
+    full = np.exp(z)
+    full /= full.sum()
+    sel = full[list(slot_token_ids[:k])]
+    allowed_mass = float(sel.sum())
+    probs = sel / max(sel.sum(), 1e-12)
+    return probs.astype(np.float64), allowed_mass
+
+
+def options_from_question(q: Dict) -> List[dict]:
+    """把 EdgeJev 的带类型问题转成 PlayJev 的选项列表。"""
+    t, crit = q["t"], q.get("crit")
+    if t == "choice":
+        return [{"name": kk, "description": vv if isinstance(vv, str) else None}
+                for kk, vv in crit.items()]
+    if t == "score":
+        return [{"name": "level %d" % i, "description": c if isinstance(c, str) else None}
+                for i, c in enumerate(crit)]
+    crit = crit or {}
+    return [{"name": "false", "description": crit.get("false") or "the statement does not hold"},
+            {"name": "true", "description": crit.get("true") or "the statement holds"}]

edgejev/build.py

@@ -0,0 +1,275 @@
+"""构建期：把上游 checkpoint 转成 EdgeJev 目录（ONNX + tokenizer + 配置）。
+
+只有这一步需要 torch（`pip install 'edgejev[build]'`），转完运行时就不需要了。
+"""
+import json
+import os
+import shutil
+import sys
+
+PRECISIONS = ("int8", "int8-pc", "int8-static", "mixed", "fp32")
+DEFAULT_MODELS = {"laya": "convaiinnovations/laya-multilingual",
+                  "kev": "jaredpalmer/kev-0.5b",
+                  "playjev": "OmniJev/PlayJev-0.8B"}
+
+
+# ---------------------------------------------------------------- laya 导出
+def _export_laya(model_id, subfolder, out_dir):
+    """返回 (fp32_onnx_path, cfg_dict, tokenizer_json_path, decision_node_cut)。"""
+    import torch
+    from torch.export import Dim
+    import laya
+    from laya.common import QTYPES, build_sequence, collate_items
+
+    ag = laya.load(model_id, device="cpu", subfolder=subfolder)
+    ag.model.eval().float()
+    cfg, tok = ag.cfg, ag.tok
+
+    qs = [{"t": "choice", "ins": "which team", "crit": {"a": "1", "b": "2", "c": "3"}},
+          {"t": "score", "ins": "how severe", "crit": ["low", "med", "high"]},
+          {"t": "noul", "ins": "is it urgent", "crit": None}]
+    items = []
+    for q in qs:
+        seq, mk = build_sequence(tok, "a short piece of state text", q,
+                                 cfg.get("max_len", 1024), cfg.get("head_max_len", 256))
+        items.append({"ids": seq, "markers": mk, "qtype": QTYPES[q["t"]]})
+    b = collate_items([items], tok.pad_token_id)
+    args = (b["input_ids"], b["attention_mask"], b["marker_pos"], b["marker_mask"], b["qtype"])
+
+    path = os.path.join(out_dir, "_fp32.onnx")
+    B, L, K = Dim("B", min=1, max=64), Dim("L", min=8, max=1024), Dim("K", min=2, max=255)
+    # 必须 dynamo：旧的 TorchScript 导出器会把 head 里 nn.MultiheadAttention 的 batch/seq
+    # 固化成导出时的形状，换个输入长度就抛 Reshape 错误，而且用同一批次做比对发现不了。
+    torch.onnx.export(
+        ag.model, args, path,
+        input_names=["input_ids", "attention_mask", "marker_pos", "marker_mask", "qtype"],
+        output_names=["logits", "act_logits"],
+        dynamic_shapes={"input_ids": {0: B, 1: L}, "attention_mask": {0: B, 1: L},
+                        "marker_pos": {0: B, 1: K}, "marker_mask": {0: B, 1: K},
+                        "qtype": {0: B}},
+        opset_version=20, dynamo=True, external_data=False)
+
+    import onnx
+    m = onnx.load(path)
+    del m.graph.value_info[:]       # dynamo 留下的标注与推断冲突，会挡住量化
+    onnx.save(m, path)
+
+    tmp = os.path.join(out_dir, "_tok")
+    tok.save_pretrained(tmp)
+    tok_json = os.path.join(tmp, "tokenizer.json")
+    if not os.path.exists(tok_json):
+        sys.exit("这个 checkpoint 不是 fast tokenizer，导不出 tokenizer.json")
+
+    conf = {"backend": "laya", "model_name": cfg.get("model_name", "laya"),
+            "source_model": model_id, "max_len": cfg.get("max_len", 1024),
+            "head_max_len": cfg.get("head_max_len", 256),
+            "temperature": cfg.get("temperature", [1.0, 1.0, 1.0]),
+            "temperature_by_options": cfg.get("temperature_by_options", {}),
+            "cls_id": tok.cls_token_id, "sep_id": tok.sep_token_id,
+            "mask_id": tok.mask_token_id, "pad_id": tok.pad_token_id,
+            "mask_token": tok.mask_token}
+    return path, conf, tok_json, "type_emb.weight"
+
+
+def _write_playjev(model_id, subfolder, out_dir):
+    """playjev 不导 ONNX：Qwen3.5 的线性注意力层没有对应的 ONNX 算子。
+
+    这里只落一份配置，运行时直接用 transformers 加载；EdgeJev 统一的是 API 和 serve。
+    """
+    from huggingface_hub import snapshot_download
+
+    local = os.path.exists(model_id)
+    if not local:
+        print("  预拉权重 ...", flush=True)
+        snapshot_download(model_id)
+    conf = {"backend": "playjev", "runtime": "torch-vlm", "template": "plain",
+            "model_name": "playjev", "source_model": model_id,
+            "temperature": [1.0, 1.0, 1.0], "temperature_by_options": {}}
+    return None, conf, None, None
+
+
+EXPORTERS = {"laya": _export_laya, "playjev": _write_playjev}
+
+
+# ------------------------------------------------------------------- 量化
+class _Calib:
+    """给静态量化用的标定数据。
+
+    动态量化在运行时按实际张量算激活 scale，padding 一变 scale 就变，
+    于是**同一条输入跟谁一批会影响它的答案**（实测 logits 能差 2.4）。
+    静态量化把 scale 在这里固定下来，换来批次无关、可复现的结果。
+    """
+
+    def __init__(self, enc, cfg, backend, n=64):
+        import itertools
+        states = ["The customer was charged twice and is asking for a refund.",
+                  "客户反馈 App 打开就闪退，已经第三次提工单了。",
+                  "Server returned 502 for every request during the sale. " * 6,
+                  "请问企业版一年多少钱？有没有教育优惠？"]
+        qs = [{"t": "choice", "ins": "which team", "crit": {"a": "one", "b": "two", "c": "three"}},
+              {"t": "score", "ins": "how severe", "crit": ["low", "med", "high"]},
+              {"t": "noul", "ins": "is it urgent", "crit": None},
+              {"t": "choice", "ins": "pick", "crit": {c: None for c in "abcdefgh"}}]
+        self.data = []
+        for st, q in itertools.islice(itertools.product(states, qs), n):
+            self.data.append(backend.prepare(enc, st, [q], cfg)["feed"])
+        # 也放几个多题批次，让激活范围覆盖 batch>1 的情形
+        for st in states:
+            self.data.append(backend.prepare(enc, st, qs[:3], cfg)["feed"])
+        self.it = iter(self.data)
+
+    def get_next(self):
+        return next(self.it, None)
+
+    def rewind(self):
+        self.it = iter(self.data)
+
+
+def quantize(src, dst, precision, decision_marker=None, calib=None):
+    import onnx
+    from onnxruntime.quantization import (QuantType, quantize_dynamic, quantize_static,
+                                          CalibrationMethod, QuantFormat)
+
+    if precision == "int8-static":
+        if calib is None:
+            raise ValueError("静态量化需要标定数据")
+        print("  [实验性] int8-static 目前会大幅掉点：MinMax 标定下实测 AG News 25.8%"
+              "（随机基线 25%）、emotion 29.8%，且比动态量化慢约 4 倍。"
+              "它能做到批次无关，但标定方法还没调好——生产请用 int8 或 fp32。", flush=True)
+        quantize_static(src, dst, calib, quant_format=QuantFormat.QDQ,
+                        activation_type=QuantType.QInt8, weight_type=QuantType.QInt8,
+                        per_channel=True, calibrate_method=CalibrationMethod.MinMax)
+        return []
+
+    # 有符号 int8 是唯一值得选的：x86 的 AVX512-VNNI 只对 QInt8 有快路径，
+    # 实测同体积的 QUInt8 慢将近一倍（27.9ms vs 15.6ms）。ARM 走 SDOT，差距没这么大。
+    per_channel = precision in ("int8-pc", "mixed")
+    exclude = []
+    if precision == "mixed" and decision_marker:
+        g = onnx.load(src, load_external_data=False).graph
+        cut = next((i for i, n in enumerate(g.node) if decision_marker in n.input), None)
+        if cut is not None:
+            exclude = [n.name for n in g.node[cut:] if n.op_type in ("MatMul", "Gemm")]
+    quantize_dynamic(src, dst, weight_type=QuantType.QInt8,
+                     per_channel=per_channel, nodes_to_exclude=exclude)
+    return exclude
+
+
+# ------------------------------------------------------------------- 自检
+def verify(out_dir):
+    """多形状自检：不同问题数、不同 state 长度、不同选项数都要跑通。
+
+    这一步是硬性的——导出器把形状固化成导出时的批次是真实会发生的 bug，
+    只在换输入形状时才暴露，所以不能只靠一次数值比对。
+    """
+    from .agent import Agent
+
+    print("\n自检 ...", flush=True)
+    ag = Agent(out_dir)
+    print("  provider: %s" % ag.provider_note)
+    cases = [
+        ("三题 / 短 state", "short state",
+         {"a": {"type": "choice", "instructions": "x", "criteria": {"p": "1", "q": "2", "r": "3"}},
+          "b": {"type": "score", "instructions": "y", "criteria": ["l", "m", "h"]},
+          "c": {"type": "noul", "instructions": "z"}}),
+        ("单题 / 长 state", "a much longer piece of state text " * 30,
+         {"only": {"type": "noul", "instructions": "is this long"}}),
+        ("八选项 / 中文", "客户说账号被扣了两次款，很生气。",
+         {"k": {"type": "choice", "instructions": "选一个",
+                "criteria": {c: None for c in "abcdefgh"}}}),
+    ]
+    ok = True
+    for name, state, qs in cases:
+        try:
+            r = ag.system_one(state, qs)
+            assert set(r["answers"]) == set(qs)
+            print("  [OK] %s" % name)
+        except Exception as e:
+            ok = False
+            print("  [失败] %s: %s" % (name, str(e)[:160]))
+
+    # 批次无关性：同一条输入单独跑和跟别人一批跑，结果应该一致。
+    # 动态量化做不到这一点（激活 scale 随 padding 变），所以这里只警告不失败。
+    import numpy as np
+    from .backends import laya as _laya
+    q = {"t": "noul", "ins": "is this urgent", "crit": None}
+    texts = ["short one", "a considerably longer piece of state text " * 8]
+    solo = []
+    for t in texts:
+        p = _laya.prepare(ag.enc, t, [q], ag.cfg)
+        solo.append(ag.sess.run(None, p["feed"])[0][0, :2].copy())
+    items = [_laya.build_sequence(ag.enc, t, q, ag.cfg["max_len"], ag.cfg["head_max_len"])
+             for t in texts]
+    L = max(len(s_) for s_, _ in items)
+    ids = np.full((2, L), ag.enc.pad_id, dtype=np.int64)
+    att = np.zeros((2, L), dtype=np.int64)
+    mp = np.zeros((2, 2), dtype=np.int64); mm = np.zeros((2, 2), dtype=bool)
+    for i, (s_, m_) in enumerate(items):
+        ids[i, :len(s_)] = s_; att[i, :len(s_)] = 1
+        mp[i, :len(m_)] = m_; mm[i, :len(m_)] = True
+    lgb = ag.sess.run(None, {"input_ids": ids, "attention_mask": att, "marker_pos": mp,
+                             "marker_mask": mm, "qtype": np.full(2, 2, dtype=np.int64)})[0]
+    drift = max(float(np.abs(lgb[i, :2] - solo[i]).max()) for i in range(2))
+    if drift < 1e-3:
+        print("  [OK] 批次无关性（单条与批量一致，漂移 %.1e）" % drift)
+    else:
+        print("  [注意] 批次会影响结果：logits 漂移 %.2f。动态量化按实际张量算激活 scale，"
+              "padding 一变 scale 就变。要可复现请用 --precision int8-static 或 fp32，"
+              "或者固定 batch=1。" % drift)
+    return ok
+
+
+def run(backend="laya", model=None, subfolder=None, out=None, precision="int8",
+        keep_fp32=False):
+    if backend not in EXPORTERS:
+        sys.exit("后端 %r 还没有构建器，目前支持：%s" % (backend, ", ".join(EXPORTERS)))
+    try:
+        import torch  # noqa: F401
+    except ImportError:
+        sys.exit("缺少转换依赖，请先： pip install 'edgejev[build]'")
+
+    model = model or DEFAULT_MODELS[backend]
+    os.makedirs(out, exist_ok=True)
+    print("加载 %s（后端 %s）..." % (model, backend), flush=True)
+    fp32_path, conf, tok_json, marker = EXPORTERS[backend](model, subfolder, out)
+
+    if fp32_path is None:          # 不走 ONNX 的后端（playjev）
+        with open(os.path.join(out, "edgejev.json"), "w", encoding="utf-8") as f:
+            json.dump(conf, f, ensure_ascii=False, indent=2)
+        print("  运行时 %s（不导 ONNX，无量化）" % conf["runtime"])
+        print("\n完成 -> %s" % out)
+        print('  from edgejev import Agent; Agent("%s").system_one(image, questions)' % out)
+        return
+    print("  fp32 %.0f MB" % (os.path.getsize(fp32_path) / 1e6), flush=True)
+
+    final = os.path.join(out, "model.onnx")
+    if precision == "fp32":
+        shutil.move(fp32_path, final)
+    else:
+        print("量化 (%s) ..." % precision, flush=True)
+        calib = None
+        if precision == "int8-static":
+            from .tokenize import Encoder
+            from . import backends as _b
+            shutil.copyfile(tok_json, os.path.join(out, "tokenizer.json"))
+            ids_map = {k: conf[k] for k in conf if k.endswith("_id")}
+            ids_map["mask_token"] = conf.get("mask_token", "<mask>")
+            calib = _Calib(Encoder.from_file(os.path.join(out, "tokenizer.json"), ids_map),
+                           conf, _b.get(backend))
+        excl = quantize(fp32_path, final, precision, marker, calib)
+        if excl:
+            print("  决策路径保持 fp32 的节点：%d 个" % len(excl))
+        if not keep_fp32:
+            os.remove(fp32_path)
+    print("  model.onnx %.0f MB" % (os.path.getsize(final) / 1e6), flush=True)
+
+    shutil.copyfile(tok_json, os.path.join(out, "tokenizer.json"))
+    shutil.rmtree(os.path.join(out, "_tok"), ignore_errors=True)
+    conf.update(onnx_file="model.onnx", precision=precision)
+    with open(os.path.join(out, "edgejev.json"), "w", encoding="utf-8") as f:
+        json.dump(conf, f, ensure_ascii=False, indent=2)
+
+    if not verify(out):
+        sys.exit("自检未通过，产出的模型不可用")
+    print("\n完成 -> %s" % out)
+    print('  from edgejev import Agent; Agent("%s").system_one(state, questions)' % out)