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

README rewrite + architecture doc: platform-neutral framing

linyubupa5669d6adc000
diff --git a/README.md b/README.md
index 3778a0d..7533ab2 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,50 @@
# edge0
**edge0** 是一个开源的流式 MoE 推理框架:把「SSD 专家 offload +
-并行 LoRA + prerouter 路由预判」方案抽象成可扩展的通用框架,后端隔离设计
-(当前 MLX / Apple Silicon,后续将适配其它平台),开箱支持两个模型:
+并行 LoRA + prerouter 路由预判」抽象成可扩展的通用框架。后端隔离设计,
+当前实现 MLX 后端(Apple Silicon),更多平台(CUDA 等)按同一套核心抽象接入。
+
+开箱支持两个模型 tier:
| 模型 | 说明 | 推理档 |
|---|---|---|
| `edge0-35b` | Qwen3.6-35B-A3B 4bit(40 层,256 专家) | prerouter K=4 |
| `edge0-10b` | Ling-10B bailing_hybrid(24 层,128 专家) | prerouter K=8 |
-设计目标:
-
-- **像 transformers 一样使用**:`AutoModel` / `AutoConfig` / `AutoEngine` 按模型名自动选类;
-- **后端隔离**:全部 MLX 代码收在 `edge0/backends/mlx/`,核心逻辑只依赖后端门面,
- 为未来 CUDA 后端预留平级插槽(`backends/cuda/`);
-- **适配器统一为 safetensors**:LoRA 与 prerouter 权重均为带元数据的 `.safetensors`;
-- **旧术语零残留**:预路由头在代码与文档中一律称 `prerouter`。
+## 设计
+
+- **像 transformers 一样使用**:`AutoModel` / `AutoConfig` / `AutoEngine`
+ 按模型名自动选类;
+- **后端隔离**:全部 MLX 代码收在 `edge0/backends/mlx/`,核心逻辑
+ (模型 spec / prerouter / 流式专家池 / server)只依赖后端门面
+ (`edge0/backends/base.py` 的 `core` / `nn` 门面),新增后端实现同一门面
+ 即可平级接入(`backends/cuda/` 预留插槽),核心代码零改动;
+- **适配器统一为 safetensors**:LoRA 与 prerouter 权重均为带元数据
+ (来源、轮次、owners)的 `.safetensors`,放模型目录或 `artifacts/`
+ 均可自动解析;
+- **模型 + 适配器同目录布局**:一个模型目录同时放基模(`config.json` /
+ `model*.safetensors` / tokenizer)和该模型的适配器,换轮次只换适配器
+ 文件,基模不动、不 merge。
+
+## 核心机制
+
+- **SSD 专家 offload**:MoE 专家权重从磁盘 mmap 按需流式加载,
+ 激活集驻留 LRU,长尾专家按层预取 —— 大模型小显存跑得动;
+- **prerouter 路由预判**:前一 token 的隐层状态经轻量头预测下一 token
+ 的专家路由,SSD 预取与下一层前向重叠,路由零等待
+ (qwen 系 `start_layer=7`,ling 系同);
+- **并行 LoRA**:适配器不合并进基模,前向时旁路叠加,
+ 基模保持只读 mmap、多套适配器共享同一份基模;
+- **数值防护**:per-layer hidden clip(`LING_HIDDEN_CLIP`,默认 1000)
+ 阻断 fp16 溢出 → 全 NaN logits → token-0 死循环的塌缩链。
## 快速开始
```bash
-# 1) 安装(Python ≥3.10,Apple Silicon + mlx)
+# 1) 安装(Python ≥3.10;MLX 后端需 mlx 环境当前支持的平台)
python3.12 -m venv .venv && .venv/bin/pip install -e '.[dev]'
-# 2) 一键试玩:自动探测开发机上的 checkpoint;也可以显式传路径或 tier 名
+# 2) 一键试玩:自动探测本机 checkpoint;也可以显式传路径或 tier 名
edge0 demo
edge0 demo /path/to/qwen35/model
edge0 demo edge0-10b
@@ -42,16 +63,40 @@ edge0 chat /path/to/model --prompt "你好,用一句话介绍珠海。"
`python -m edge0 ...` 与 `edge0 ...` 完全等价。
+### Python API
+
+```python
+from edge0 import AutoEngine
+
+eng = AutoEngine.from_pretrained("/path/to/model") # tier 自动识别
+ids = eng.encode_chat([{"role": "user", "content": "你好"}], think=True)
+tokens = eng.generate(ids, max_new_tokens=512)
+print(eng._tok.decode(tokens))
+eng.reset() # 每请求前清状态(跨请求 KV / prerouter 缓存)
+```
+
### 模型与适配器
-- **checkpoint**:qwen35 / ling v7 的原始模型目录(含 `config.json`、`model.safetensors`、
- `tokenizer.json`)。`edge0 serve <dir>` 按 `config.json` 自动识别 tier。
-- **适配器**(LoRA + prerouter,`artifacts/` 目录内自动使用,无需手动指定):
- - `artifacts/lora_edge0_35b_k4.safetensors` + `artifacts/prerouter_edge0_35b_k4.safetensors`
- - `artifacts/lora_edge0_10b.safetensors` + `artifacts/prerouter_edge0_10b.safetensors`
- - 旧版 npz 迁移:`edge0 convert-adapters`
+- **checkpoint**:原始模型目录(`config.json`、`model*.safetensors`、
+ tokenizer)。`edge0 serve <dir>` / `AutoEngine.from_pretrained(<dir>)`
+ 按 `config.json` 自动识别 tier。
+- **适配器**(LoRA + prerouter,safetensors)放两处任一,自动解析:
+ - **模型目录内**(推荐):与基模同目录,如
+ `lora_edge0_35b.safetensors` + `prerouter_edge0_35b.safetensors`;
+ - `artifacts/`(仓库根,gitignored):`edge0 convert-adapters` 从
+ 训练侧 npz 一次性转换。
+- 当前默认适配器轮次:35b = round9,10b = round6(pgstart-sel1m,
+ owners L7–22 与 `start_layer=7` 一致)。
+
+### 稳定性验证
+
+两个 tier 均通过长连测(temp 0.7 采样、think 开关混合、多 prompt):
+
+- `!` 死循环塌缩 0/N(NaN clip 防护生效);
+- 碎片退化 0/N(低层 prerouter 噪声通过 `start_layer=7` 消除);
+- 跨请求状态污染 0/N(每请求 `reset()` + 首 token greedy)。
-### 验证
+## 验证
```bash
pytest # 单元测试(不含真实权重)
diff --git a/docs/architecture.md b/docs/architecture.md
index 1eb557f..5be2094 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,7 +1,9 @@
# 架构总览
-**edge0** 是一个面向 Apple Silicon 的开源流式 MoE 推理框架,把生产部署中验证过的
+**edge0** 是一个开源的流式 MoE 推理框架,把生产部署中验证过的
「SSD 专家 offload + 并行 LoRA + prerouter 路由预判」方案抽象成可扩展的通用框架。
+后端隔离设计:当前实现 MLX 后端(Apple Silicon),核心逻辑与后端解耦,
+其它平台按同一套门面接入。
开箱支持两个模型:`edge0-35b`(Qwen3.5-MoE,K=4)与 `edge0-10b`(Ling 3.0
hybrid,K=8)。