接入新模型家族,Edge0 只认这三件事:Config、build_model、build_engine
接入新模型家族,Edge0 只认这三件事:Config、build_model、build_engine
Edge0 开源之后,社区讨论最密集的两个话题,一是"3GB 内存怎么跑起 35B 的 MoE"(SSD 专家卸载 + prerouter 路由预判 + Recover-LoRA),二是"我手里的新模型怎么接进这套流式推理管线"。前者有论文和 benchmark 背书,后者则完全落在框架的扩展机制上:无论你是要接入 Qwen 家族的下一代混合注意力架构,还是想把 Ling 这类无 model_type 的 checkpoint 变成 edge0 serve 可跑的档位,框架只认三样东西——一个 Config 子类、一个 build_model、一个 build_engine。本文以本地仓库 Edge0-35B-A3B-preview 为实证样本,把这条契约从头到尾拆开:适配器模块怎么建、两个构建函数的分工边界在哪、TYPE_ALIASES 如何让模型被"目录即解析",以及单元测试如何把整条链路钉死在回归线内。
适配器模块与 Config 子类怎么建
先看这套契约的第一条:一个模型家族对应 src/edge0/models/ 下的一个包(如 edge0_35b/),包的 __init__.py 就是适配器本体。框架对适配器的要求只有三个导出项:
Config——ModelConfig的子类,自带from_pretrained;build_model(model_dir, **overrides)—— 组装好的模型骨架;build_engine(model_dir, **overrides)—— 可生成文本的引擎。
ModelConfig 在框架的 models/base.py 中定义,它的字段就是"跑通一个模型档位所需的全部信息":moe_spec(MoE 规格)、options(流式层选项,如 staged_k4() 预置)、prerouter(路由预判头规格)与 prerouter_top_k、lora / lora_r / lora_alpha(LoRA 权重路径与超参)、gen(采样默认)、prefill_chunk / hot_window 等流式与预取行为,以及 port 和 target_tok_s / peak_active_mem_mb 两个验收指标。子类只需实现 _defaults(model_dir) 一个类方法,返回本家族的默认配置;from_pretrained 是基类提供的模板方法——先取默认值,再逐字段校验并 replace 用户传入的 override,未知字段直接抛 TypeError 并列出全部已知字段。
这层设计与本地模型仓库的配置文件是一一对应的。看本仓库的 config.json:model_type 为 qwen3_5_moe,text_config 里 num_hidden_layers: 40、num_experts: 256、moe_intermediate_size: 512、shared_expert_intermediate_size: 512、num_experts_per_tok: 8,layer_types 是 linear_attention 与 full_attention 按 4 层间隔混排——这正是 MoESpec(专家数、top_k、中间维度、量化规格)与 LayerOptions(流式层选项)需要从 checkpoint 提取或与之对齐的全部结构信息;而 generation_config.json 里的 temperature: 1.0、top_k: 20、top_p: 0.95、do_sample: true 则原样映射为 Config 的 gen 采样默认值。换句话说,写一个 _defaults 的过程,就是把一个 checkpoint 的 config.json 翻译成框架运行时能直接消费的结构化规格。
还有一个容易踩的细节是路径解析。ModelConfig.artifact(name, model_dir) 规定适配器权重(LoRA、prerouter)优先从模型目录内解析,找不到才回退到项目根下 gitignore 的 artifacts/ 缓存。本仓库正是前者:lora_edge0_35b.safetensors 与 prerouter_edge0_35b.safetensors 与基座权重同目录存放,_defaults 里填好这两个文件名,运行时即可自动定位,无需任何额外配置。
build_model 与 build_engine 的分工
三件套里最容易混淆的是两个构建函数。框架的定义很克制:build_model 负责"骨架",build_engine 负责"能跑"。以 edge0-35b 的适配器为例,build_model 内部先 Config.from_pretrained 拿到配置,再调用引擎模块的 load_installed——它把流式专家层、LoRA、prerouter 头一次性装配进模型对象;而 build_engine 则直接构造 Qwen35Engine(cfg.model_dir, cfg),返回一个带 prefill/decode 采样循环、可供 ChatSession 直接驱动的生成引擎。两者共用同一条 from_pretrained 构造路径,这正是 DRY 的体现:用户传的 override(如 --no-prerouter、--no-lora)在两个入口里行为完全一致。
为什么要把两个函数分开?因为"模型"和"引擎"的生命周期与职责不同:AutoModel.from_pretrained 给你一个可前向、可装配的模型对象(用于调试、检查权重、对接自定义逻辑);AutoEngine.from_pretrained 给你一个端到端可生成的服务单元(对接 edge0 serve、OpenAI 兼容 API)。而如果你的模型家族数学与现有引擎不同——比如 edge0-8b 的 SIGMOID_GROUP 路由与混合 MLA 注意力——框架允许你在 src/edge0/engine/ 下写自己的引擎(参照 engine/qwen.py / engine/ling.py),再在 build_model / build_engine 里引用它即可,无需改动任何注册机制。
本地仓库的 model.safetensors.index.json 把"骨架"到底要装什么暴露得很清楚:权重键以 language_model.model.layers.N.mlp.switch_mlp.{gate_proj,up_proj,down_proj} 组织专家 FFN,同层还有 shared_expert(共享专家)与 shared_expert_gate(共享专家门控)、mlp.gate(路由 gate),以及 linear_attn.*(线性注意力子层)与 self_attn.*(全注意力子层)。这意味着 build_model 装配出的模型必须同时处理"流式专家卸载 + 共享专家常驻 + 混合注意力"三类结构——StreamingSwitchGLU 负责前者,共享层与 router 按框架约定常驻内存,这也印证了社区文章反复强调的部署约束:共享层与 Router 必须常驻,被流式化的是专家权重。
TYPE_ALIASES 注册与自动解析机制
三件套之后是最后一道工序:注册。适配器文件末尾调用 register_model("edge0-35b", sys.modules[__name__]) 并把 Config 暴露为模块属性。注册表有去重保护——同名二次注册抛 ValueError;同时必须确保该包被导入,edge0/models/__init__.py 里显式 import 每个档位,AutoConfig.from_pretrained 也会在解析前兜底执行 from edge0 import models。
真正让"接入"变成"零配置"的是 TYPE_ALIASES。它把 checkpoint 的 model_type(或架构名)映射到注册名:
TYPE_ALIASES = {
"qwen3_5_moe_text": "edge0-35b",
"qwen3_5_moe": "edge0-35b",
"bailing_hybrid": "edge0-8b",
"bailing_moe_linear": "edge0-8b",
"BailingMoeV3ForCausalLM": "edge0-8b",
}
_resolve_name 的查找顺序是:显式传入的 name → 模型目录 config.json 的 model_type(没有 model_type 时读 architectures[0],再失败才回退到目录 basename)→ 注册表 → 别名表 → 否则抛 KeyError 并列出所有已注册模型。这一设计在本仓库里就有两个活标本:config.json 的 model_type: qwen3_5_moe 直接命中别名,走的是"目录即解析"路径——AutoEngine.from_pretrained(model_dir=...) 不用传名字就能把档位认出来;而 Ling 家族(edge0-8b 基座)在 config.json 里只带 architectures 不带 model_type,因此别名表里额外挂了 BailingMoeV3ForCausalLM 这样的架构名,演示了第二级回退。目录 basename 只是最后手段,所以官方建议把目录名与注册名对齐,但并非硬性要求。
单元测试验证的完整闭环
契约写完不等于接完,框架把"接入是否合规"做成了可自动校验的测试面,全部为纯逻辑单测、无需真实权重。tests/test_registry.py 覆盖六类断言:
- 注册与别名:
MODEL_REGISTRY包含新注册名,TYPE_ALIASES解析正确; - Config 默认值:
AutoConfig.from_pretrained(name=...)返回的moe_spec/options/prerouter/prerouter_top_k符合预期; - Profile 逐字段:专家数、top_k、量化位宽、端口、验收指标(
target_tok_s、peak_active_mem_mb)逐项核对; - Overrides 与拒绝:
from_pretrained(..., prerouter=None, lora="")生效,未知字段抛TypeError; - 适配器契约:遍历
MODEL_REGISTRY,断言每个条目都暴露Config/build_model/build_engine三件套——这是对"接入新模型家族只认三件事"的机器可读定义; - 未知名称:
test_unknown_name_lists_registry用断言钉住报错信息包含已注册模型列表。
配合 tests/test_moe_spec.py 的权重键模板、block_of 数值索引、bundle_projs 布局切换测试,以及路由数学与 vendored 模型 bit-for-bit 对齐的 parity 测试,一套"注册 → 配置 → 装配 → 路由一致性"的闭环就成型了。本地仓库同样给出可验证的输入侧证据:config.json 的量化配置(4-bit、group_size 64、affine,gate 单独升到 8-bit)必须与 MoESpec 的 QuantSpec 完全一致,否则 safetensors 的 biases / scales 键在 model.safetensors.index.json 里的存在性检查就会在运行时失败——这也是测试面要提前钉住的原因。
模型目录:契约落地的最后一块拼图
三件套最终服务的对象是一个"可直接运行的模型目录"。目录至少需要满足:config.json 存在且 model_type(或架构名)已被注册或覆盖;权重为 safetensors 格式,键前缀匹配 moe_spec.key_template(如 language_model.model.layers.N.mlp.switch_mlp);LoRA / prerouter 权重是带元数据的 safetensors 文件。本仓库恰好是完整样例:基座(config.json + 4 个 model-*.safetensors 分片 + tokenizer_config.json 与 chat_template.jinja)与两个适配器(lora_edge0_35b.safetensors、prerouter_edge0_35b.safetensors)同目录,下载即就绪,edge0 serve <dir> 开箱即跑。
回看整条链路,框架刻意把"接入"压缩成最薄的一层:配置即声明(Config 说清规格)、构建即装配(build_model 装骨架)、引擎即服务(build_engine 给生成能力),而注册与别名让这一切对用户完全透明。对任何想把手头稀疏 MoE checkpoint 搬进流式管线的团队而言,理解这三件事,就等于理解了 Edge0 整个扩展模型——剩下的,就是照着一个已有的适配器模块,改名字、改规格、改引擎引用,然后让测试替你验收。