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

WASM 推理项目的技术债务哪些设计决策现在回头看需要重构一、最大的债把所有逻辑塞进一个 WASM 模块项目初期为了快速验证可行性我把模型加载、推理、文本处理全部塞进了一个 WASM 模块。// // 当时的做法一个 WASM 模块包含所有逻辑 // #[wasm_bindgen] pub struct OmnibusWasm { // 模型加载器 model: Model, // 文本预处理 tokenizer: Tokenizer, // 推理引擎 engine: InferenceEngine, // 后处理 postprocessor: PostProcessor, // 缓存 cache: LruCacheString, Vecf32, } #[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) - ResultJsValue, 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// // 最初的错误处理直接返回 JsValueJS 端毫无信息 // #[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: OptionString, } #[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_LOGdebug才输出详细信息生产环境只返回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: VecOptionLayer, 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]) - Vecf32 { 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%。这一个优化带来的体验提升比我们之前做的所有前端优化加起来都大。五、总结复盘这个项目四个最大的技术债务单体 WASM 模块是早期最大的设计失误。应该从一开始就按功能域拆分独立模块。JS 桥接层和业务逻辑必须隔离。这是可测试性和可维护性的基础。错误传播要结构化。JsValue::from_str(error)对前端开发者极其不友好。大文件的加载策略要从第一天就开始设计。全量加载是上线即死的技术债。这些事情现在改起来成本已经很高了要重构测试、更新 JS 调用方、重新做兼容性测试。但如果现在不改三个月后的成本会更高——这就是技术债务的本质你今天不想付出的代价明天会加倍讨回来。计划下个 sprint 先处理前两个拆分模块 隔离 JS 桥接后两个放到 v0.4.0。