Skip to content

armgit / Edge0

Public Imported from GitHub
0

Run 35B MoE models in ~2.5 GB of RAM. Weights stream from SSD; a trained router predicts loads a step ahead. Mac, iPhone, Android, Windows supported

Python

docs: drop the local prerouter notes from the tree

linyubupa6cc13ef3943b
diff --git a/docs/prerouter-decode-fix-2026-09-14.md b/docs/prerouter-decode-fix-2026-09-14.md
deleted file mode 100644
index 713df05..0000000
--- a/docs/prerouter-decode-fix-2026-09-14.md
+++ /dev/null
@@ -1,418 +0,0 @@
-# prerouter decode 修复记录(2026-09-14)
-> 说明:本文引用的临时验证脚本(`scripts/verify_*.py`、`scripts/ab_*.py`、`scripts/bench_*_ab.py`、`scripts/diag_*.py`、`scripts/quality_*.py`)是一次性的
-> 测量脚手架,已在收尾时从仓库清理;复现口径见正文(配对方式、段长、轮数、环境噪声说明)。
-
-
-范围:`edge0-35b`(qwen)。8b(ling)的同类层级问题未改,见文末。
-§3.6 的两个执行开销修复落在**共享**的 `prerouter/stager.py` 上,两个 tier 同时受益。
-
----
-
-## 1. 修前实测到的三个问题
-
-用真实引擎跑(2 请求 × 8 decode token + 32 token 对照),两组独立信号一致
-(脚本自己比"routed vs staged 集合"和引擎内建的 `staged_dropped` 计数器)。
-
-### P1 跨请求状态污染
-- 同进程第 2 个请求的 prefill,`stage_all` 提交了 33 个消费者层,且 owner 20 的
- `prerouter_m_in` 指纹与**上一个请求最后一个 decode step 逐位相同**
- (`1398.39453125`)→ 新请求第 1 个 token 的路由,是用上一个请求的隐状态算出来的预测。
-- 根因:`StreamingSwitchGLU.reset()` 文档写着 "Per-request reset … so the next request
- starts clean",但**全仓库零调用点**;`block.prerouter_m_in / prerouter_oh` 只在单 token
- 前向里写、从不清理。(参考部署 `~/Documents/qwen35-v7-deploy/streaming_experts_qwen35.py`
- 里连这个方法都没有,是 edge0 自己加的、漏接的线。)
-
-### P2 每个请求第 1 个 token:消费者层 4/4 补零
-- 首步没有预测可用(head 特征只在单 token 前向抓取),路由按训练语义回落 gate
- (pos-0 fallback),但 `_prefill_end` 仍用**最后一个 prefill token 的实际 top-k**
- 填槽位,两边几乎不重合(实测 L7:路由 `(96,132,166,182)` vs 槽位 `(14,117,184,229)`,
- 交集 0)→ 32 个消费者层各丢 4 个专家。
-- 缺失专家在 staged 路径下映射到溢出零行(`streaming/layer.py:597`
- `slot_of_list = [n] * num_experts` + `_build_asm` 用 `_zero_slot` 补行):
- **静默补零,不报错、不补算**。
-
-### P3 层 0–6 / 39:每个 token 持续丢专家
-- 这 8 层没有 head 供给(覆盖是 6→7 … 38→39),每步都用 gate 路由,却仍被
- `_step_pre` 用"上一个 token 的实际集合"填槽位。
-- 实测每步丢 3.0–3.75 / 4(L0 在 16 次调用里累计 60/64),8 层合计稳态
- **25.75 / 步**,占全模型 160 个 routed 槽位的 **16%**。
-- 参考部署原话即为此设计:"Current router as the predictor … **No correctness handling**"
- —— 这是既定近似(省掉这些层专家的加载换速度),不是失误。
-
-### 影响的量化(修前)
-- 每步 `staged_dropped` 稳态约 25.75(16%)。
-- 旧路径 vs 全精确(同 prompt、同 routing、只换加载路径):前 16 个 token 相同,
- **第 17 个 token 起分叉,64 个里 48 个不同**,`max|Δlogit|` 从 2.5 涨到 15.8。
-- 两段文本都通顺 → 结论只能是"不是同一条轨迹",**不能**说"质量更差"。
-
----
-
-## 2. 改动清单
-
-| 文件 | 改动 |
-|---|---|
-| `src/edge0/engine/qwen.py` | `_reset_state`:清 per-block 特征捕获 + 每层 `reset()`(P1);`_prefill_end`:有 prerouter 时改调 `prefetch_from_prefill()`(P2);`load_installed`:非消费者层关闭 `_staged_mode`(P3);`_step_pre`/`_step_post`:这些层不再填槽、不再做无效 prefetch、跳过 `sync_actuals`;修正 `_forward` 里关于"首步已消费真实预测"的错误注释 |
-| `src/edge0/prerouter/stager.py` | 报告 §6 的两个执行开销修复:头权重一次性 stack + 每步 3 次 einsum(`head_batch`,可关);`stream_layers` 为空时跳过无人使用的 `core.eval` + `tolist`。另修正 `records` 里 `zip(metas, metas)` 把 consumer 记成 owner 的笔误 |
-| `src/edge0/streaming/layer.py` | 新增 `StreamingSwitchGLU.prefetch_from_prefill()`(只预热缓存,不填槽位)。未修改任何已有方法 |
-| `src/edge0/models/base.py` | 新增 `ModelConfig.history_slots: bool = False` |
-| `src/edge0/cli.py` | `--history-slots`(demo / chat / serve)+ `_engine_kwargs` 映射 |
-| `docs/prerouter.md` | "zero drop" 的适用范围写准;补首步、非消费者层、per-request reset 说明 |
-| `docs/models/edge0-35b.md` | staged 只覆盖 L7–L38;补 `history_slots` / `--history-slots` |
-| `tests/test_registry.py` | 断言 `history_slots` 默认 False 且可覆盖 |
-
-设计原则:**只有"路由来自预测"的层用 staged 槽位**。它的路由与槽位集合严格相同(零丢);
-其余层走精确路径。
-
----
-
-## 3. 验证结果(真实引擎,每配置一个进程、一个引擎)
-
-### 3.1 prerouter 仍在被使用(新默认)
-插桩读 `pg_state.pred_inds[li]` 与该层实际用的槽位 `_staged_at_use`:
-
-| 步骤 | 有预测的消费者层 | 用了槽位的层 | 用的槽位 == 预测 |
-|---|---|---|---|
-| step 1 | 0/32 | 0 | 0(按设计回落 gate,走 exact) |
-| step 2 | 32/32 | 32 | **32/32** |
-| step 3 | 32/32 | 32 | **32/32** |
-| step 8 | 32/32 | 32 | **32/32** |
-
-预测与**原生 gate 自己的 top-4** 只在 2.2–2.6/4 上重合(集合完全相等:step2 5/32、
-step3 2/32、step8 0/32)→ 路由确实由 head 改写,不是复读 gate。
-
-### 3.2 与全精确路径等价
-同 prompt、32 步 greedy:`fixed`(新默认)与 `staged=False`(全精确)
-**token 完全相同、每步 logits 逐位相同**(`max|Δlogit| = 0`)。
-
-### 3.3 退路开关
-`--history-slots`(= 旧行为)逐位可复现:两次跑 token 序列完全一致,第 17 步起与精确
-路径分叉(16/32 不同),`staged_dropped` = 806(32 步)。
-
-### 3.4 速度:同进程配对测量(V1/V2/V3 部分可信;V0 对比已撤回,见下)
-
-方法按 `docs/experiments/prerouter-decode-speed-2026-09-14.md` §2/§9.3:本机跨进程单轮 A/B
-的组间差异可达 ±15%、甚至反号,所以用**同进程、交替、配对差值**。本表:一个引擎、3 臂
-运行时切换(只改 `_staged_mode` 与 stager 的 `stream_layers`)、每臂先跑 12 步预热再计时
-48 步、4 轮交替顺序、取中位数;`loads`/`dropped` 取层内计数器增量。
-
-**补充教训(本轮新增)**:同进程配对也不总够 —— 当两个臂**路由到不同的专家集合**、而
-LRU/页缓存是共享的时候,臂之间会互相预热,"谁先跑谁吃亏",符号可以跨进程翻转(见下)。
-
-| 臂 | 含义 | 中位 ms/step | tok/s | loads/step | dropped |
-|---|---|---|---|---|---|
-| V0 | 无头(gate 路由 + 精确加载) | 56.18 | 17.82 | 160 | 0 |
-| V1 | 有头不收割(预测路由 + 精确加载) | **49.13** | **20.36** | 160 | 0 |
-| V2 | 有头 + 收割(= 新默认) | 50.57 | 19.78 | **32** | 0 |
-
-配对差值(本轮):`V1 − V0 = −7.05 ms`、`V2 − V0 = −5.61 ms`、`V2 − V1 = +1.44 ms`。
-
-⚠️ **`V0` vs `V1`(原生路由 vs 预测路由)这个对比不可用,已撤回。** 复测三次,同脚本、
-同进程内配对,符号**翻转**:
-
-| 第几次 | V0 ms/step | V1 ms/step | V2 ms/step | 结论 |
-|---|---|---|---|---|
-| 第 1 次 | 56.18(各轮 78.0/57.9/54.4/51.9) | 49.13 | 50.57 | V1 更快 |
-| 第 2 次 | 68.61(62.4/74.1/68.6) | 49.54 | 51.66 | V1 更快 |
-| 第 3 次(含 V3 异步臂) | 45.86(46.4/41.5/45.3/60.5) | 51.11 | 50.87 | **V0 更快** |
-
-`V0` 在 45.9–68.6 ms 之间摆动,`V1` 稳定在 49.1–51.1 ms。原因:两臂**专家集合不同**
-(gate vs 预测路由),而共享 LRU/页缓存被**别的臂预热过**——预测集被 V2 预热,gate 集是冷的,
-于是"谁先跑谁吃亏",符号随机器状态翻转。这就是报告 §2 记的 ±15% / 符号翻转那一类陷阱。
-**故不再声称 prerouter 在 35b 上快 14%;同进程共享缓存的臂切换量不了这个量。**
-
-站得住的是**计数器级结论**(不依赖计时噪声):
-
-| 臂 | loads/step | load_wall | stage_wall | stage_wait | 合计装载成本 |
-|---|---|---|---|---|---|
-| V1 有头不收割 | 160 | 9.8 ms | 0 | 0 | **9.8 ms** |
-| V2 收割(`staged_sync=True`,= 默认) | 32 | 4.9 ms | 5.0 ms | 0 | **9.9 ms** |
-| V3 收割(异步 `staged_sync=False`) | 32 | 5.0 ms | 4.9 ms | 0 | **9.9 ms** |
-
-- 收割把**同一批 build 从"前向中"搬到"步边界"**:总装载时间一步没少(9.8 → 9.9 ms),
- `stage_wait=0`(消费者从未等待)。计时上 `V2−V1 = +1.44 ms`、`V3−V1 = +0.94 ms`
- (同向小亏)→ **收割在 35b/本机是搬运,不是节省**;同步/异步两档无差别。
-- 结构性原因:填槽由 `stage_all` 在**前向结束时**发起,消费者在**下一个 token 一开头**
- 消费,中间没有可重叠的算力。要真正藏住装载,必须让填槽在**同一个 token 的前向期间**
- 发起(报告 §10.2 的 Fix 3:用 `after_layer_cb` 交错头的 einsum)。
-- 8b 报告测得收割 +2.0 ms/步(184→56 loads/步),与本机 35b 相反 → 两端不可混用。
-
-### 3.4a 已废弃:跨进程单趟数字(保留备查)
-
-每配置一个进程、单趟、warmup 后计时 64 步:新默认 18.79 tok/s / 2.80 GiB / dropped 0;
-旧行为(`--history-slots`)13.60 / 2.90 GiB / 806;全精确(`staged=False`)18.39 /
-2.04 GiB / 0。跨进程单轮,按 §3.4 的方法学不可信,只用于"修前 → 修后"的粗判。
-
-### 3.5 `--no-prerouter` 为什么"看起来更快"(当时的误读已修正)
-
-那时测到 OFF 20.59 vs ON 15.41 tok/s(+34%),一度读成"prerouter 拖慢"。实际是:
-`--no-prerouter` 在 35b 上**不是**"无头 + 精确加载",而是"无头 + 全部 40 层 history 槽位",
-144 步里丢 15131 个槽位(≈105/步,占 160 个 routed 槽位的 66%)——**丢掉的专家既不加载
-也不计算**,所以它天然少干约 2/3 的 MoE 活。这不是"省",是缺。
-
-同工对比:这个量**本机量不了**(见 §3.4 的撤回)。本机能确定的只有:OFF 的 20.59 tok/s
-是"66% 补零"换来的,不能当"原生路由 + 精确计算"的基线;公平基线是
-`prerouter=None + staged=False`(跨进程单趟 18.70 tok/s,同口径粗判)。
-`+84%` 出自 `paper/make_figs.py` 所引 `qwen35-v7-deploy/K8_K4_K2_TEST.md` §4.7/4.8
-(`6.8 → 12.5 tok/s`)——那是**装载主导**的部署机;本机同模型 18–22 tok/s,装载只占
-≈10 ms/50 ms,regime 不同,数字不可互推。
-
-### 3.6 报告 §6 的两个执行开销修复(已落到共享 stager)
-
-改动都在 `src/edge0/prerouter/stager.py::PrerouterStager`,两个 tier 共用:
-- **fix 1 批量头**:owner 头形状一致 → 权重一次性 stack,每步 3 次 einsum,取代
- "每头 3 个小算子"的循环(33 头 ≈ 99 个小算子/步 → 3 个)。`head_batch=False`
- 或 `EDGE0_HEAD_BATCH=0` 回到循环,便于 A/B。
-- **fix 2 免无谓同步**:`stream_layers` 为空(`staged=False`)时,`_select` 之后不再做
- `core.eval` + `tolist` —— 那份 host 侧专家 ID 没人消费。路由缓存照写(惰性数组即可),
- 所以 `staged=False` 与 `--no-prerouter` 都受益。
-
-验证(35b 真实引擎):
-- 同一批特征上批量头 vs 逐头循环:`max|Δlogit| = 0.000e+00`,路由集合一致。
-- 同进程、**两臂都先预热**的 greedy-80:`head_batch=True` 与 `False` **token 完全一致**。
-- fix 2 回归:`staged=False` 下 greedy-32 与改动前记录**逐 token 相同**,`dropped=0`。
-
-⚠️ "先预热"不是形式主义:本机**进程内第一跑(冷缓存)与之后所有跑是两条轨迹**。
-同一配置连跑 6 次:第 1 跑与第 2–6 跑在第 36 步分叉(1 个消费者层路由不同),
-第 2–6 跑彼此逐位一致;先插一次预热跑后 6/6 完全一致。该现象在 default /
-`head_batch=False` / `staged=False` / `history-slots` 四种配置下**表现完全一样**
-(legacy 在第 22 步分叉)→ **与本次修复无关,是既有的冷/热启动差异**。
-后果:拿"第一跑"和"reset 后的跑"直接比 token 会得到假分叉;同进程 greedy 对照
-必须两臂都先预热。跨进程对照则是"冷 vs 冷",反而一致。
-
----
-
-### 3.7 收益到底在哪:档位旋钮隔离(本轮结论,取代 §3.4 的速度论断)
-
-对照部署参考 `~/Documents/qwen35-v7-deploy/engine_qwen.py:97-99`、
-`streaming_experts_qwen35.py:292-297,486`——**跑出 +84% 的那台机器用的是**:
-`cache_slots=900`、`hot_per_layer=8`、`hot_update_interval=32`、
-`staged_sync` 默认 **False**(`QWEN_STAGED_SYNC=0`);而 edge0 的 35b 档
-`staged_k4` 是 `cache_slots=64`、`hot_per_layer=0`、`hot_update_interval=4`、
-`staged_sync=True`。
-
-隔离实验(一个引擎一进程、先插预热跑、每轮位置轮转、各 4 轮;除最后一臂外全部
-prerouter ON + 收割):
-
-| 臂 | 配置差异 | 中位 ms/step | tok/s | loads/步 | load_ms | stage_ms | 峰值 |
-|---|---|---|---|---|---|---|---|
-| `sync64h0` | = 今天的默认 | 52.66 | 18.99 | 32 | 5.6 | 6.2 | 2.91 GiB |
-| `async64h0` | `staged_sync=False` | 60.17 | 16.62 | 32 | 5.7 | 6.4 | 2.91 |
-| `async900h0` | 再加 `cache_slots=900` | **38.98** | **25.66** | 12 | 1.8 | 3.4 | 4.05 |
-| `async900h8` | 再加 `hot_per_layer=8`、interval 32 | 39.02 | 25.63 | 11 | 1.8 | 3.2 | 4.56 |
-| `native900h8` | 部署档 + **无 prerouter** | 49.53(各轮 119.4/62.4/36.6/36.4) | 20.19 | 39 | 6.1 | 0 | 3.55 |
-
-1. **真正的大头是 `cache_slots` 64 → 900**:52.66 → 38.98 ms/step(**+35% tok/s**),
- 现场装载从 140 次/步掉到 12 次/步。
-2. `staged_sync=False` **单独无感**(60.17,甚至更慢);`hot_per_layer=8` 在 900 之上
- **再加无收益**(39.02 vs 38.98),只多 0.5 GiB。`predicted_experts`(预测喂钉选)
- 在 edge0 **和部署里都没被赋值**(`layer.py:138` 只声明、865-868 只读),是同一处
- 从未接线的能力,不是移植漏掉的。
-3. **prerouter 的中位速度在 warm 稳态下 ≈ 0**:同档 `async900h8` 39.0 vs
- `native900h8` 36.4–36.6(后两轮,页缓存已热)。§3.4 里"部署档下 +83%"
- (pre_pin 22.4 vs nat_pin 12.2 tok/s)**作废**:那是 native 臂踩到冷轮
- (81.9/83.9 ms)的假象,本轮 4 轮轮转复测不成立。
-4. prerouter 真正体现的是**稳定性**:无 prerouter 的臂 4 轮里 119.4 → 62.4 → 36.6 →
- 36.4 ms(冷/热差 3 倍以上),有 prerouter 的臂始终 37.8–42.3 ms。它把"装载暴露时间"
- 从不可控变可控——在装载本身是瓶颈且不可预测的环境(冷盘 / 网络盘 / 并发挤缓存)才
- 转化为速度,那正是部署机 6.8→12.5 tok/s 所处的区间;本机跑热后进入"装载不是瓶颈"
- 的区间,收益自然趋 0。
-
-**本机可下的结论只有三条**:(a) 功能正确(§3.1–3.3、§3.6);(b) 收割/同步异步在本机是
-搬运不是节省(§3.4 计数器);(c) 想在本机拿到真实提速,先改档位 —— `cache_slots`
-64 → 900(+1.1 GiB)实测 +35%,与 prerouter 无关。"prerouter 快 x%" 只能表述为
-装载主导环境下的收益,需慢存储复测(报告 §10.3)。
-
----
-
-## 4. 没有碰的部分
-
-L7–L38 的 `预测 → 槽位 → 路由` 链路、`stage_all`/`state.swap`、head 数学
-(`prerouter/heads.py`)、prefill 的 E3b / 热路径、共享 LRU 与 hot pins、LoRA、量化、
-serve/chat 路径、以及 ling 的 `BailingSparseMoE` 从 `pg_cache` 自选路由那条链。
-`streaming/layer.py` 只有新增方法,没有改已有方法。
-
-冒烟:`edge0 chat` 正常出文;`--no-prerouter` 正常;
-`pytest tests/` 59 passed(唯一失败 `test_repo_hygiene::test_no_hardcoded_local_paths`
-是仓库里既有的硬编码路径,命中清单不含本次修改的文件)。
-
----
-
-## 5. ling(8b)落地(已完成)
-
-§5 原列的三个待办项已全部处理,对应改动:
-
-| 文件 | 改动 |
-| --- | --- |
-| `src/edge0/engine/ling.py` | `load_installed`:消费层作用域(`li < start_layer+1` 的层 `_staged_mode=False`,`history_slots=True` 时不作用);`_step_pre`/`_step_post`:非消费层在作用域默认下走精确路径、不做历史暂存也不做无谓的 `sync_actuals`;`_prefill_end`:有 prerouter 时 prefill 尾部 `stage_all` 供首步消费(8b 在 prefill 期就抓得到特征,不需要 35b 那样的 router 回退),只有 legacy `history_slots` 才 `stage_from_prefill` 且只给非消费层;`_reset_state`:清 `layer.m_in_cache` / `block.last_topk` / `block.prev_topk_oh` 并对所有流式层调 `reset()` |
-| `src/edge0/prerouter/stager.py` | 批量头的 dtype 从 `_head_of(...)._dtype` 改为从堆叠的 `w1.dtype` 取(ling 的头是 `BailingPrerouter`,按 `fc1.weight.dtype` 定精度,没有 `_dtype` 属性 → 修前直接 `AttributeError`) |
-| `src/edge0/streaming/options.py` | `prod_k8()` 默认改为 `staged=True`(分层零丢弃的收割路径) |
-| `tests/test_registry.py` | 旧断言 `staged is (name == "edge0-35b")` 改为两档都 `staged=True` + `history_slots is False` |
-| `docs/models/edge0-8b.md`、`docs/prerouter.md` | staged 说明改为"仅消费层 L8–23";补首步分档语义、per-request reset 字段名、`--history-slots` |
-
-### 5.1 验证(每配置一个进程、一个引擎,脚本 `scripts/verify_ling_fix.py`)
-
-> 本表是 `cache_slots=64`(当时默认)下测的;缓存放大后的数字见 §5.3/§5.4。
-
-| 配置 | tok/s | 峰值内存 | dropped | loads/步 | 与 exact 逐 token 一致 |
-| --- | --- | --- | --- | --- | --- |
-| **default(新)** | **27.47** | 1.41 GiB | **0** | 5656(101 步 → 56/步) | **是** |
-| history(legacy 全层历史暂存) | 34.58 | 1.56 GiB | 1589 | 0 | 否 |
-| exact(`staged=False`,parity 基准) | 26.17 | 0.86 GiB | 0 | 18584(101 步 → 184/步) | — |
-| nopg(`prerouter=None`) | 31.50 | 1.46 GiB | 10481 | 0 | 否 |
-
-- **丢弃率**:`scripts/diag_staged_drops.py` → consumed=62976,`dropped=0`(0.00%);L1–7 每步 8 次精确 load,L8–23 全部由预测供给。
-- **质量**:`scripts/quality_ab_staged.py` 4/4 prompt `identical=True, first_divergence=None`;greedy 32 步 token 序列与 exact 完全相同。
-- **P1 跨请求污染已消**:同进程先跑请求 1 再跑请求 2,与全新进程只跑请求 2 相比,token 序列与首步 logits 完全一致(`p2_first=592203.875` 两边相同)。
-- **速度(配对,`scripts/verify_pair_final.py`,SEG=100×10 轮)**:PG 对 gate 路由精确基线 **10/10 轮全胜,中位 −1.97 ms/步、均值 −3.15 ms/步(≈+5%)**。
-- **内存**:默认路径峰值 1.41 GiB(exact 0.86 GiB;槽位 buffer + 头权重占 ≈0.55 GiB),24 GB 机器上无压力。
-
-### 5.2 与报告 §7 的 −5.11 ms/步 的关系(口径修正)
-
-报告 §6/§7 那个 −5.11 ms 的基线是"**无头 + gate 路由 + 精确 load**",因此它同时包含了
-**路由来源差异**(预测路由 vs gate 路由)和**收割差异**。做成同路由(都跑头、都由
-prerouter 供路由、都零丢弃)的干净配对后,收割本身只有 −0.19 ms/步(≈打平),
-而"有 prerouter 供路由 + 收割" 对 "关掉 prerouter 用 gate + 精确" 是 −1.97 ms/步(中位)。
-即:**prerouter 的收益主要在路由来源,槽位收割在本机(热缓存、load 延迟低)只值约 0–5%**。
-两处数字都保留,口径已注明。
-
-### 5.3 真正的瓶颈:全局专家 LRU 只有 64 槽(同日追加,收益比收割大一个量级)
-
-`install.py:54` 给全部 23 个 MoE 层**共用一个** `SharedExpertCache(cache_slots)`,键是
-`(layer, expert)`。`cache_slots=64` ÷ 23 层 = **每层 2.8 个槽**,而一个 decode step 要碰
-**184 个不同键**(23 层 × top-8)——比单 token 的工作集还小,复用窗口短于一个 token,
-命中率结构性为 0(实测 `hits=0`,每步重建 184 个 1.27 MiB 的专家包,52 µs/个)。
-
-同进程配对(`scripts/verify_cache_pair.py`,生产路径、无 wrapper、3 轮交替、
-greedy 输出三种容量下逐位相同、drops=0):
-
-| cache_slots | ms/步 | tok/s | 命中/步 | 精确 load | stage 重建 | load_wall | stage_wall | 峰值内存 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 64(原) | 40.02 | 24.99 | 0.0 | 56.0 | 56.0 | 5.21 ms | 3.05 ms | 1.39 GiB |
-| **1024(新)** | **31.44** | **31.81** | 43.9 | 12.1 | 18.4 | 1.22 ms | 1.56 ms | 2.39 GiB |
-| 2048 | 33.81 | 29.58 | 49.8 | 6.2 | 9.4 | 1.34 ms | 1.98 ms | 3.28 GiB |
-
-**1024 对 64:−8.58 ms/步(−21.4%),3/3 轮全胜。** 2048 没有更多收益(复用窗口饱和),
-所以 `prod_k8()` 落在 `cache_slots=1024`(≈44 槽/层、≈1.3 GiB 专家包、短上下文峰值
-2.6 GiB,`peak_active_mem_mb` 1400 → 2700)。收益拆开看:L1–7(无预测、纯靠 LRU)
-每步 56 次重建 → 12 次,约 4 ms;消费层那 44% 的"新预测集"重建 → 命中,约 1.5 ms。
-
-**为什么预测到的专家也没命中**:每层下一个 token 的预测集只有约 **56%** 落在上一步那 8 个
-槽位里(`stage_delta_hits`),剩下 44% 必须另找来源;而全局 64 槽连一个 token 都放不下,
-所以这部分只能重建。也就是说"每层缓存 8 个"只够覆盖一步之内,跨 token 复用必须靠更大的 LRU。
-
-prefill 未被牺牲:同进程配对(`scripts/verify_prefill_cache.py`,3101-token 提示、
-3 轮交替)warm prefill 1102(64 槽)vs 1132 tok/s(1024 槽)= **+2.7%**,同上下文解码
-22.6 → 26.7 tok/s(+18.3%)。README 里 8b 行按同口径(`BENCH_LONG=1`)重测为
-解码 27.7–30.7 tok/s、峰值 2.4 GiB(短上下文)。
-
-### 5.4 缓存修好之后:收割不再值钱
-
-四臂配对(`scripts/verify_four_arm.py`,`cache_slots=1024`,SEG=100 × 8 轮交替,
-四臂全部零丢弃):
-
-| 臂 | ms/步 | tok/s | loads/步 | 命中/步 | load_wall | stage_wall | 对 OFF |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| OFF(无 prerouter,gate 路由 + 精确装载) | **28.40** | **35.22** | 36.0 | 148 | 2.44 ms | 0 | — |
-| PGE(prerouter 路由 + 精确装载) | 29.78 | 33.58 | 26.6 | 157 | 1.86 ms | 0 | +1.38 ms(1/8 胜) |
-| SYNC(prerouter + 槽位,默认) | 30.07 | 33.26 | 11.1 | 45 | 0.81 ms | 0.97 ms | +1.67 ms(**0/8 胜**) |
-| ASYNC(`staged_sync=False`) | 30.41 | 32.88 | 10.6 | 45 | 0.76 ms | 1.01 ms | +2.02 ms(0/8 胜) |
-
-结论:缓存能命中以后,整条精确路径的装载只剩 2.44 ms/步,而跑一趟头(批量 einsum +
-`core.eval` + host sync)≈1.4 ms/步——没有足够多的装载可省了。**prerouter 的剩余价值在
-"路由来源"(预测驱动选择,即发布行为),不在槽位收割**;`--no-prerouter` 在本机快约 5%,
-但改变路由/输出,属于模型语义选择,不由我改默认。
-
-### 5.5 未做
-
-- 8b 的**质量评测**(题库/人工评分)仍未做:现有的"质量"结论是同 prompt 下与精确路径
- 逐位一致(token-level parity),不是 benchmark 分数。
-- `pytest tests/` 59 passed;唯一失败 `test_repo_hygiene::test_no_hardcoded_local_paths`
- 的命中现在只剩环境文件(`artifacts/html-deleted-20260911.txt`、`.venv-mlx0305/pyvenv.cfg`、
- `paper/.tools/**`),仓库源码与 `scripts/` 下的路径已清干净。
-- `staged_k4()`(35b,40 层 × 256 专家)与 `staged_k8()` 仍是 `cache_slots=64`:同样的
- 超订问题更严重(35b 一步要碰 40×4=160 个键),但改 35b 属于另一个 tier,未动。
-
----
-
-## 6. 第二轮(干净 clone `edge0_new`,HEAD `ae1ee2d`):开关语义 + ling 同步 + 四组实测
-
-### 6.1 开关修复:关掉 prerouter 必须是精确路径
-
-`--no-prerouter` 原来在**两个 tier 上都会留下 staged 槽位**(`options.staged=True` 时
-`stream_layers` 仍含所有层),于是关掉预测头后走的不是精确路径,而是"上一 token 实际
-top-k 填槽"的历史路径:edge0-8b 一次请求实测 `staged_dropped = 3593`;35b 早先
-"`--no-prerouter` 快 34%"也是同一原因(它少算了约 2/3 的专家)。§3.5 的修正说的就是这件事,
-但当时只改了消费层作用域、没修"关"这一侧。
-
-修法(`src/edge0/engine/{ling,qwen}.py::load_installed`)——作用域统一成一条规则:
-**槽位只给"路由来自预测"的层**(consumer `start_layer+1` 起);`prerouter is None`
-时没有任何预测,所以**没有任何层保留槽位**,走精确装载。`history_slots=True`
-(`--history-slots`)是显式 opt-in 回旧行为。
-
-| 配置 | staged 层 | `staged_dropped` |
-|---|---|---|
-| edge0-8b prerouter ON(作用域默认) | 16(L8–23) | 0 |
-| edge0-8b `--no-prerouter`(修复后) | **0** | **0** |
-| edge0-35b prerouter ON | 32(L7–38) | 0 |
-| edge0-35b `--no-prerouter`(修复后) | **0** | **0** |
-
-开关只有一个:`--no-prerouter`(demo / chat / serve 三处同名同义),没有反向 flag。
-
-### 6.2 ling(edge0-8b)同步 P1/P2/P3
-
-`src/edge0/engine/ling.py` 做了与 35b 同口径的三件事:`_reset_state` 清
-`layer.m_in_cache` / `block.last_topk` / `block.prev_topk_oh` + 每层 `reset()`(P1);
-`_prefill_end` 有 prerouter 时只 `stage_all()`,历史填槽只作用于非消费层且仅
-`history_slots=True` 时(P2);`_step_pre`/`_step_post` 按 `first_pg_consumer`
-作用域化,非消费层不填槽、不做无效 prefetch(P3)。`prod_k8()` 默认 `staged=True`
-(`cache_slots=64` 保持低内存档;收割关掉时预测不参与装载,收益结构性为 0)。
-
-### 6.3 四组实测(同机、先预热、每轮轮转、3 轮取中位)
-
-| 臂 | ms/步 | tok/s | MLX 峰值 | 进程 RSS | staged 层 | dropped |
-|---|---|---|---|---|---|---|
-| qwen prerouter ON | 49.06 | 20.38 | 2.89 GiB | 11.69 GiB | 32/40 | 0 |
-| qwen `--no-prerouter` | 50.21 | 19.92 | 2.07 GiB | 11.78 GiB | 0/40 | 0 |
-| ling prerouter ON | **35.66** | **28.04** | 1.48 GiB | 4.94 GiB | 16/23 | 0 |
-| ling `--no-prerouter` | 43.99 | 22.73 | 1.03 GiB | 4.86 GiB | 0/23 | 0 |
-
-- **速度**:ling 开 prerouter **快 8.33 ms/步(+23%,配对 3/3 轮一致 −6.0/−9.3/−8.6)**;
- qwen 两边打平(−1.15 ms,配对 −11.6/+1.2/−3.0),与 §5.4 结论一致(35b 本机装载不是瓶颈)。
-- **内存**:prerouter 多占 +0.82 GiB(35b)/ +0.45 GiB(8b)MLX 峰值(槽位 + 头);
- 进程 RSS 基本持平(11.69 vs 11.78 / 4.94 vs 4.86 GiB)。
-- **质量**:收割开 vs 关(prerouter 都开,只有装载调度不同)**token 逐位一致**——
- qwen 两个 prompt 各 32 token IDENTICAL;ling 同样 IDENTICAL。
-- **跨请求重置**:同进程 req1→req2 与冷进程单跑 req2 的 token 序列 IDENTICAL;
- ling 首步 logits digest 完全相同(−390314.312)。qwen 的 digest 有数值级差异
- (−307200.0 vs −299008.0)但 32 token 全同,属"进程首跑与后续跑存在数值抖动"这一
- 既有现象,不是跨请求残留。
-- 与 no-prerouter 对比时 token 会不同(路由来源从 gate 换成预测头,属模型语义,不是回归);
- 两边文本都通顺。
-
-### 6.4 ling 的 demo 默认
-
-`Ling8BConfig.demo_no_prerouter = True` + `edge0.registry.demo_kwargs()`:
-`edge0 demo` / `examples/demo.py` 对 edge0-8b 默认走 gate 路由的精确路径;
-`chat` / `serve` 保持档位默认(预测路径)。冒烟(各 8 token):`demo`(ling) 无
-`prerouter installed` 行、`demo --no-prerouter` 无、`chat`(ling) 有、
-`chat --no-prerouter` 无、`examples/demo.py`(ling) 无。
-`pytest tests/` = 65 passed, 1 skipped。
-
-### 6.5 逐缺陷复核(同一 clone 上的实测签名)
-
-| 缺陷 | 判据 | qwen(35b) | ling(8b) |
-|---|---|---|---|
-| **P1 跨请求残留** | 同进程 req1→req2 的 token 序列 vs 冷进程单跑 req2 | 32 token 全同(首步 logits digest 有数值级差异,属"进程首跑"既有抖动) | 32 token 全同,digest 完全相同(−390314.312) |
-| **P2 首步** | prefill 结束有没有把"最后一个 prefill token 的实际 top-k"当预测填槽;首步是否零专家 | `prefetch_submitted=128`、`stage_builds=0`(改为预取预测集,不填槽);首步 `staged_used=0`、`staged_fallback=32`(32 层走精确路径)、`staged_dropped=0` | `stage_builds=128`(预测在 prefill 就绪);首步 `staged_used=128`、`staged_fallback=0`、`staged_dropped=0` |
-| **P3 非消费层丢专家** | staged 层集合 + `staged_dropped` | L7–38(32 层),L0–6/L39 不填槽,`dropped=0` | L8–23(16 层),L1–7 不填槽(owner 6 不存在 ⇒ L7 永远 gate,已知边界),`dropped=0` |
-
-两个 tier 的"首步正确签名"本来就不同:qwen 的特征只在单 token 前向捕获,首步按训练态走
-gate(pos-0 fallback)并由 prefill 预取预测集;ling 的特征在 prefill 内就绪,首步直接消费
-预测。这是数据流决定的,不是两个 tier 不一致。
-
-诚实附注:qwen 首步预取命中仅 5/128(首步路由是 gate、预取的是预测集,重合度低),即首步
-基本还是按需装载 —— 正确性优先的取舍,也是 35b 在本机 prerouter 提速 ≈0 的原因之一。
-
-
-
-
diff --git a/docs/prerouter-switch-semantics-2026-09-14.md b/docs/prerouter-switch-semantics-2026-09-14.md
deleted file mode 100644
index e465cc1..0000000
--- a/docs/prerouter-switch-semantics-2026-09-14.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# prerouter 开关语义与生效判据(edge0-8b / ling)
-
-> 只看一件事:**开关打开时必须真的走 prerouter,关掉时必须真的完全不走**。
-> 本文不讨论收益、不提速、不比快慢;只定义"开/关"的语义、生效的判据、以及
-> 会让开关名不副实的故障。
->
-> 日期:2026-09-14;对象:`edge0-8b`(Ling 3.0 hybrid);代码以当前工作树为准。
-
----
-
-## 1. 有三个不同层次的"开关",先别混
-
-| 层次 | 开关 | 位置 | 作用 |
-|---|---|---|---|
-| 总开关 | `--no-prerouter`(默认**开**) | `src/edge0/cli.py:65-66` → `kw["prerouter"] = None` | 决定是否构建/使用预测头 |
-| 模型内派生 | `prerouter_enabled` | `src/edge0/engine/ling.py:53`(`cfg.prerouter is not None`) | 传给 vendored 模型,逐层派生下面两个标志 |
-| 逐层角色 | `has_prerouter`(本层**有头**,预测下一层)<br>`use_prerouter`(本层**消费**预测) | `backends/mlx/_impl/bailing_hybrid.py:712-724` | 决定谁跑头、谁从预测里选专家 |
-| 装载侧 | `staged` / `staged_n` / `staged_sync` | `src/edge0/streaming/options.py`(`prod_k8()`) | 是否把预测出的专家**提前装进槽**;**不改变路由来源** |
-
-逐层派生规则(8b 的 `start_layer=7`, 24 层):
-
-```python
-has_prerouter = enabled and li >= start_layer - 1 and li < n_layers - 1 # li in [6, 22]
-use_prerouter = enabled and li >= start_layer and li < n_layers # li in [7, 23]
-```
-
-- **谁提供预测**:`owners`,显式写死在 `src/edge0/models/edge0_8b/__init__.py:53`
- → `owners=tuple(range(7, 23))` = **16 个头(7..22)**,owner `li` 预测 `li+1`。
- 实测烘好的头文件 `~/Documents/edge0-8b/prerouter_edge0_8b.safetensors`:48 个数组
- (每头 `fc1/fc2/linear_init`),layers = 7..22,元数据 `owners=[7..22]`。
-- **谁消费预测**:`use_prerouter` → L7..23;实际有供给的是 **L8..23**(见 §7 边界)。
-- stager 只遍历 `state.owners`(`src/edge0/prerouter/stager.py:176`),头集合由 `owners` 决定,
- 与 `has_prerouter` 的派生范围无关。
-
-**路由判定点**(唯一一处,`bailing_hybrid.py:682-693`):
-
-```python
-if self.use_prerouter and prev_prerouter_logits is not None:
- idx, w = self._select_from_logits(prev_prerouter_logits) # ON:路由来自预测
-else:
- idx, w = self.gate(x) # 否则:本层自己的 gate
-```
-
-`prev_prerouter_logits` 在模型前向循环里取值(`bailing_hybrid.py:808-813`):
-
-```python
-if layer.use_prerouter and prerouter_cache is not None and li in prerouter_cache:
- prev_prerouter_logits = prerouter_cache[li]
-```
-
-→ **注意这三个条件是与关系:标志为真但缓存里没有这一层的条目时,会静默回退到 gate**
-(不报错、不打日志)。这是开关最容易名不副实的地方,见 §4。
-
----
-
-## 2. 开:必须成立的五个条件
-
-| # | 条件 | 代码位置 | 判据(怎么看出真的开了) |
-|---|---|---|---|
-| 1 | 头被构建:`owners` 16 个 | `ling.py:95-105`(`install_prerouter` / `len(heads)`) | 启动打印 `prerouter installed: 16 heads, start=7, K=8` |
-| 2 | 每个 consumer 每步都拿到预测:`pg_cache[li]` 已写入 | `stager.py:302-308`(`_store`) | `pg_cache` 条目数 == 有供给的 consumer 数(8..23 = 16) |
-| 3 | 首步就有预测(消费层从 token 1 就消费) | `ling.py` 的 `_prefill_end` → `stage_all()` | 第一步输出与 gate 路由不同;`consumed` 从第 1 步起增长 |
-| 4 | 每个请求重置干净 | `ling.py` 的 `_reset_state`(`pg_cache` + `m_in_cache`/`last_topk`/`prev_topk_oh`) | 同一进程连续两请求 == 冷进程单跑(见 §5) |
-| 5 | 装载侧作用域正确:只有 `li >= start_layer + 1` 用槽 | `ling.py:78-80` 作用域 `_staged_mode` | 消费层 `slots == routing`;`dropped == 0` |
-
-条件 3 的特征来源(`stager.py:276-295`(`_features`)):`layer.m_in_cache`(本层 post-attention 后的
-MLP 输入,取最后位置)+ `block.last_topk` 的 one-hot(当前 token)+ `block.prev_topk_oh`
-的 one-hot(上一 token);prefill 结束的首次 staging 用倒数第 2 个位置当"上一 token"。
-
----
-
-## 3. 关:`--no-prerouter` 必须做到的全停清单
-
-`--no-prerouter` → `prerouter=None` → `prerouter_enabled=False` → 两个派生标志全为 False。
-
-| 必须为"零"的项 | 位置 | 判据 |
-|---|---|---|
-| 不构建任何头 | `ling.py:95-105`(`if cfg.prerouter and ...`) | 启动**没有** `prerouter installed` 那行 |
-| stager 不存在 | `ling.py:95`(`pg_state = pg_stager = None`) | 无 `pg_cache` 写入 |
-| 前向缓存传 None | `ling.py:211`(`prerouter_cache=self._pg_stager.pg_cache` 只在存在时) | 模型循环里 `prerouter_cache is None` → 永不取值 |
-| 逐层 `use_prerouter=False` | `bailing_hybrid.py:717-724` | 所有 MoE 层走 `self.gate(x)` |
-| 无头前向、无预测槽装载 | 头不存在 → 无从执行 | 头/预测相关计数全 0 |
-| 不保留任何 staged 槽位 | `ling.py:80-89`(`prerouter is None` ⇒ 全部层 `_staged_mode=False`) | `stream_layers` 为空、`staged_dropped == 0`、装载按需发生(`loads` 仍 > 0) |
-
-**关的等价物**:与 `exact`(精确装载)档在路由来源上一致 —— 两者都是 gate 路由,
-且(修复后)都不保留 staged 槽位,即 `--no-prerouter` **就是**精确路径本身。
-修复前它反而会留下全部层的槽位(走历史路径,见 §4"关掉仍填槽"一行)。
-
----
-
-## 4. 六种"开关开着/关着但没生效"的故障(均已修复,列出以防回归)
-
-| 故障 | 现象 | 根因 | 修法 |
-|---|---|---|---|
-| **静默回退** | 部分层悄悄用 gate,得到既不 ON 也不 OFF 的**第三态**(混合路由) | `pg_cache` 缺该层条目时 `if` 条件不成立,无日志无异常(`bailing_hybrid.py:808-813`) | 必须保证"每个有供给的 consumer 每步都有条目";用 `consumed/dropped` 判据守住 |
-| **首步被覆盖** | 第一步路由错一位 | `_prefill_end` 里 `stage_from_prefill()` 用"最后一个 prefill token 的实际 top-k"顶掉了刚算出的预测 | 有 prerouter 时只跑 `stage_all()`,不再 `stage_from_prefill` |
-| **跨请求残留** | 第 2 个请求第一步用第 1 个请求的 hidden state 跑头 | `_reset_state` 未清 `layer.m_in_cache` / `block.last_topk` / `block.prev_topk_oh` | 逐 owner 清这三个字段 + 清 `pg_cache` |
-| **非消费层错位** | L1-7 丢 17-26% 真实专家(`history_slots` 档实测 `dropped=1589`),输出劣化 | L1-7 没有预测,却用"上一 token 实际 top-k"填槽并当预测消费 | 作用域 `_staged_mode`:只有 `li >= start_layer+1` 走槽 |
-| **关掉仍填槽** | 关掉 prerouter 后走的不是精确路径,而是同一条"上一 token 实际 top-k"历史路径(8b 实测 `dropped=3593`;35b 少算约 2/3 专家),输出劣化 | 作用域只对"非消费层"关槽(`li < first_pg_consumer`),而 `prerouter=None` 时 `first_pg_consumer=0` → 一层都没关 | `prerouter is None` ⇒ 全部层 `_staged_mode=False`(精确装载);`history_slots=True` 才回旧行为 |
-| **头批次崩溃** | 开了直接 `AttributeError`(等于开关不可用) | 批量头路径读 `_head_of(...)._dtype`,而 ling 的头是 `BailingPrerouter`(无该属性) | 从堆叠后的权重取 dtype(`w1.dtype`) |
-
-判定口径:`dropped` = 槽里装了、但该层路由没用上的专家数(应当恒为 0);
-`consumed` = 槽被消费的次数。
-
----
-
-## 5. 生效验证(实测)
-
-| 检查项 | 结果 | 含义 |
-|---|---|---|
-| 槽位与路由一致性 | `consumed=62976`,`dropped=0`,rate 0.00% | 预测装进去的专家 100% 被该层路由消费,无错位 |
-| 跨请求重置 | 同进程(请求 1 后跑请求 2)== 冷进程(只跑请求 2):token 序列一致,首步 logits digest 均为 `p2_first=592203.875` | 条件 4 成立,无残留污染 |
-| 与精确路径 parity | 4/4 prompt `identical=True, first_divergence=None`;greedy-32 token 序列一致 | ON 的价值路径与"精确路径"逐 token 相同 |
-| 四档对照(路由来源 / `dropped` / parity) | `default`(预测路由)= 0 / True;`history`(L1-7 也用历史槽)= 1589 / False;`exact`(无 prerouter,gate 路由)= 0 / 不适用;`nopg`(预测算了但不消费)= 10481 / False | 只有"预测路由 + 作用域正确"这一档是生效态 |
-
----
-
-## 6. 30 秒自检
-
-```bash
-# 开(默认):应打印 prerouter installed: 16 heads, start=7, K=8
-edge0 chat --name edge0-8b --model-dir ~/Documents/edge0-8b \
- --prompt "用一句话说明什么是MoE。" --max-new 32
-
-# 关:不应出现上面那行
-edge0 chat --name edge0-8b --model-dir ~/Documents/edge0-8b --no-prerouter \
- --prompt "用一句话说明什么是MoE。" --max-new 32
-```
-
-判定:**开**=有 `installed` 行 + `dropped == 0` + 输出与 `--no-prerouter` 不同;
-**关**=无 `installed` 行 + 无 `pg_cache` 写入 + 输出等于 gate 路由(`exact` 档)。
-
----
-
-## 7. 已知边界(不是 bug,是配置事实,但会被误读成"开关没生效")
-
-1. **L7 是"有消费无供给"的缝隙。** consumer 从 `start_layer=7` 起算(L7..23),而 `owners`
- 显式从 7 开始(预测 8..23)。因此 **L7 永远拿不到预测、永远走 gate**;`has_prerouter`
- 的派生规则会从 `start_layer-1 = 6` 起算,但 8b 的显式 `owners` 覆盖了它(没有 owner 6,
- 烘好的文件里也确实没有 layer 6)。想消除这条缝隙要么把 `start_layer` 写 8,要么让
- `owners` 含 6,属于配置决策。
-2. **16 个头 ≠ 22。** `src/edge0/models/edge0_8b/__init__.py:10-13` 的文件头注释写的是
- "22 heads (explicit owners 1..22), start_layer 1",与同文件 `:49-58` 的 spec
- (`start_layer=7, owners=7..22`)和烘好的 artifact 元数据(`owners=[7..22]`,48 个数组、
- layers 7..22)**都不一致**。那行注释描述的是 start-1 变体;按 §1 的代码事实,正确写法是
- **16 heads(owners 7..22)、start_layer 7**。