当前位置：首页 > news >正文

WASM 推理项目的技术债务：哪些设计决策现在回头看需要重构

news 2026/7/25 7:28:51

WASM 推理项目的技术债务：哪些设计决策现在回头看需要重构

一、最大的债：把所有逻辑塞进一个 WASM 模块

项目初期，为了快速验证可行性，我把模型加载、推理、文本处理全部塞进了一个 WASM 模块。

// ============================================================ // 当时的做法：一个 WASM 模块包含所有逻辑 // ============================================================ #[wasm_bindgen] pub struct OmnibusWasm { // 模型加载器 model: Model, // 文本预处理 tokenizer: Tokenizer, // 推理引擎 engine: InferenceEngine, // 后处理 postprocessor: PostProcessor, // 缓存 cache: LruCache<String, Vec<f32>>, } #[wasm_bindgen] impl OmnibusWasm { pub fn new() -> Self { /* 所有初始化全部堆在一起 */ } pub fn load_model(&mut self, data: &[u8]) { /* ... */ } pub fn infer(&mut self, text: &str) -> String { /* ... */ } }

这样做的问题是：

编译一次要 40 秒，改一行预处理代码也要重新编译整个 WASM 模块。
浏览器加载一个 3MB 的.wasm文件，哪怕用户只用文本预处理功能。
内部耦合严重：改 postprocessor 的逻辑居然会莫名影响 model 的加载行为（因为共享了wasm_bindgen的 JS 桥接层内存）。

重构方向：拆成三个独立 WASM 模块：

wasm-tokenizer.wasm（~200KB）：轻量级分词器
wasm-inference.wasm（~2.5MB）：推理引擎，按需加载
wasm-postproc.wasm（~150KB）：后处理

二、把 wasm-bindgen 的类型转换和业务逻辑混在一起

另一个教训是#[wasm_bindgen]的边界没划清楚。

// ============================================================ // 问题代码：wasm-bindgen 转换散落在业务逻辑中 // ============================================================ #[wasm_bindgen] pub fn analyze_text(input_js: JsValue) -> JsValue { // 在业务逻辑里直接做 JS ↔ Rust 的类型转换 let input: String = serde_wasm_bindgen::from_value(input_js).unwrap(); // 业务逻辑 let tokens = tokenize(&input); let features = extract_features(&tokens); let result = classify(&features); // 又是类型转换 serde_wasm_bindgen::to_value(&result).unwrap() } // ============================================================ // 更好的做法：隔离 JS 桥接层 // ============================================================ // 纯 Rust 业务逻辑层（不依赖 wasm_bindgen） pub fn analyze_text_pure(input: &str) -> AnalysisResult { let tokens = tokenize(input); let features = extract_features(&tokens); classify(&features) } // JS 桥接层（只做类型转换和函数委托） #[wasm_bindgen] pub fn analyze_text(input_js: JsValue) -> Result<JsValue, JsValue> { let input: String = serde_wasm_bindgen::from_value(input_js) .map_err(|e| JsValue::from_str(&e.to_string()))?; let result = analyze_text_pure(&input); // 委托给纯 Rust 实现 serde_wasm_bindgen::to_value(&result) .map_err(|e| JsValue::from_str(&e.to_string())) }

这种隔离的好处：analyze_text_pure可以在不依赖浏览器环境的情况下做单元测试。原来的版本每次测试都要模拟 WASM 环境，又慢又不可靠。

三、没有设计优雅的 JS 错误传播

WASM 模块的错误处理最初用的是最简单的办法——返回JsValue：

// ============================================================ // 最初的错误处理：直接返回 JsValue，JS 端毫无信息 // ============================================================ #[wasm_bindgen] pub fn load_model(data: &[u8]) -> Result<(), JsValue> { // 出错了? 扔一个 JsValue::from_str("error") let model = Model::load(data).map_err(|e| JsValue::from_str(&e.to_string()))?; // ... Ok(()) }

JS 端拿到的是一个无法区分错误类型的字符串。前端想针对"模型格式不对"和"内存不足"做不同的 UI 提示，完全做不到。

重构方案：用serde序列化结构化错误：

// ============================================================ // 结构化错误，JS 端可以精确区分 // ============================================================ #[derive(Serialize)] pub struct WasmError { /// 错误码，JS 端通过此字段做分支逻辑 pub code: ErrorCode, /// 人类可读的错误描述 pub message: String, /// 额外的调试信息（只在内测环境返回） pub detail: Option<String>, } #[derive(Serialize)] pub enum ErrorCode { ModelFormatError, OutOfMemory, InvalidInput, InferenceFailed, NetworkError, } #[wasm_bindgen] pub fn load_model(data: &[u8]) -> Result<(), JsValue> { let model = Model::load(data).map_err(|e| { let wasm_err = WasmError { code: ErrorCode::ModelFormatError, message: "模型文件格式不支持".to_string(), detail: Some(e.to_string()), }; serde_wasm_bindgen::to_value(&wasm_err).unwrap() })?; Ok(()) }

// JS 端现在可以精确处理了 try { await loadModel(modelData); } catch (error) { switch (error.code) { case 'ModelFormatError': showError('模型文件格式不支持，请检查文件'); break; case 'OutOfMemory': showError('模型太大，请关闭其他标签页后重试'); break; default: showError(`未知错误: ${error.message}`); } }

生产教训：这套错误体系上线后发现一个意外问题——detail字段在生产环境里暴露了 WASM 内存布局信息。有个用户通过重复触发 OutOfMemory 错误反推出了模型权重的 offsets。后来我们在detail上加了个开关：RUST_LOG=debug才输出详细信息，生产环境只返回code和message。

四、没有为增量加载设计模型格式

最初的模型加载是"全量二进制 blob"——一次性把模型文件全部读入 WASM 内存。对于大模型，这意味着 3~5 秒的白屏时间。

// ============================================================ // 问题：一次性全量加载，启动慢 // ============================================================ #[wasm_bindgen] pub fn load_model(data: &[u8]) -> Result<(), JsValue> { // 整个模型文件作为 &[u8] 传入 // 15MB 的模型 → 15MB WASM 内存分配 → 3 秒用户等待 let model = Model::load(data)?; Ok(()) }

重构方向：设计分片加载格式，把模型按权重矩阵分块：

// ============================================================ // 分片加载：用户可以先用轻量部分，后台加载剩余 // ============================================================ pub struct IncrementalModel { loaded_layers: Vec<Option<Layer>>, total_layers: usize, } impl IncrementalModel { /// 加载一个分片（比如一层神经网络的权重） pub fn load_shard(&mut self, layer_id: usize, data: &[u8]) -> Result<(), ModelError> { let layer = Layer::from_bytes(data)?; self.loaded_layers[layer_id] = Some(layer); Ok(()) } /// 检查是否所有层都已加载 pub fn is_fully_loaded(&self) -> bool { self.loaded_layers.iter().all(|l| l.is_some()) } /// 即使部分层未加载，也可以做推理 /// 缺失层用默认值（全零）代替，结果不准确但可用 pub fn infer_partial(&self, input: &[f32]) -> Vec<f32> { let mut hidden = input.to_vec(); for layer in &self.loaded_layers { match layer { Some(l) => hidden = l.forward(&hidden), None => break, // 遇到未加载的层就停止 } } hidden } }

实测数据：全量加载模式下，15MB 模型在 Chrome 上的加载耗时是 3.2 秒（含 WASM 编译），用户可感知的白屏时间约 4 秒。分片加载后，198KB 的 tokenizer 模块 120ms 即可用，用户无需等待即可开始输入。推理引擎在后台 5 片并行加载，总耗时 2.8 秒，但因为异步进行，用户完全无感。唯一的代价是前 2.8 秒内的推理精度会低 8% 左右（缺失层用零值填充）。

分片加载上线后，移动端 4G 网络下的首屏可用时间从 7.3 秒降到了 3.1 秒，用户的跳出率从 42% 降到了 18%。这一个优化带来的体验提升，比我们之前做的所有前端优化加起来都大。