framework

mni-ml/framework：TypeScript 前端的 GPU 加速机器学习框架

一款"既能让前端工程师写 AI，又能让 Rust 极客掌控性能"的框架

想象这样的场景：你在 Node.js 环境中敲下 npm install @mni-ml/framework，然后用 TypeScript 定义网络结构、加载数据、训练模型——整个过程就像用 PyTorch 一样流畅，但最终运行在 Rust 原生后端上，GPU 算力毫不打折。这不是概念演示，而是 mni-ml/framework 正在做的事。

mni-ml/framework Logo

mni-ml/framework 官方 Logo：TypeScript 接口 + Rust 高性能后端

---

背景：前端工程师的 AI 困境

过去几年，机器学习框架的生态几乎被 Python 垄断：PyTorch、TensorFlow、JAX，每个都是 Python-first。虽然这些框架功能强大、文档丰富，但前端工程师想要快速验证一个 ML 想法，往往需要跨越语言边界——用 Python 训练，再用 WASM 或 TensorFlow.js 移植到浏览器。这个过程不仅繁琐，而且两端的技术栈割裂，导致很多创新想法在"翻译"过程中折损。

另一方面，随着 WebGPU 标准在 Chrome、Safari 和 Firefox 中逐步落地，浏览器终于有了直接访问 GPU 算力的能力。这为"在浏览器中跑真正的 ML 模型"提供了硬件基础，但缺少与之配套的、易用的 ML 框架。TensorFlow.js 虽然老牌，但 API 偏向底层，训练功能也相对薄弱。

mni-ml/framework 的出现，恰好填补了这个空白。它的核心设计哲学是：用 TypeScript 的优雅语法写 ML 代码，用 Rust 的极致性能跑计算。

---

核心架构：三层分离的设计

mni-ml/framework 采用了清晰的三层架构：

第一层：TypeScript API 层（src/）

这是用户直接打交道的接口层。Tensor 类封装了所有张量操作，Module 类定义了神经网络模块的标准接口（forward/backward），optimizer.ts 提供了 SGD、Adam、AdamW 等常用优化器。API 设计大量借鉴了 PyTorch 的命名习惯：.relu()、.matmul()、.backward()、.zeroGrad()，任何一个有 PyTorch 经验的开发者都能在几分钟内上手。

核心文件包括：

• tensor.ts：张量定义与前向操作封装
• nn.ts：神经网络模块（Linear、Conv1d、Conv2d、Embedding、ReLU、Sigmoid、Tanh）
• optimizer.ts：优化器与学习率调度
• module.ts：Module/Parameter 基类

第二层：Native 加载层（src/native-loader.ts）

这一层负责运行时检测硬件环境，并加载对应的 Rust 原生插件。代码会依次检查 CUDA 驱动（Linux 下查找 libcuda.so，Windows 下查找 nvcuda.dll）、GPU 兼容性，然后从 npm 包中加载预编译的 .node 文件（Node.js 原生 addon）。

// native-loader.ts 中的 CUDA 检测逻辑
function hasCudaDriver(): boolean {
    if (process.platform === 'linux') {
        const searchPaths = ['/usr/lib/x86_64-linux-gnu', '/usr/local/cuda/lib64', ...];
        for (const dir of searchPaths) {
            if (existsSync(join(dir, 'libcuda.so'))) return true;
        }
    }
    return false;
}

平台检测通过后，getPlatformPackages() 返回对应的 npm 包名：CUDA 版（@mni-ml/framework-linux-x64-gnu-cuda）、WebGPU 版（@mni-ml/framework-linux-x64-gnu-webgpu）或纯 CPU 版。这样开发者无需手动配置，一行 npm install 即可搞定。

第三层：Rust 计算层（src/native/）

Rust 层是整个框架的性能核心，负责：

• 自动微分（autograd）：通过计算图记录前向操作，在反向传播时自动求导
• GPU 调度：根据编译特征（cpu/cuda/webgpu），将操作分发到对应后端
• 张量内存管理：高效率的 ndarray 替代方案，配合 smallvec 优化小张量

Rust 依赖包括：

• cudarc：NVIDIA CUDA 绑定（cublas 矩阵运算、nvrtc 即时编译、curand 随机数）
• wgpu：跨平台 WebGPU 抽象（Metal/Vulkan/DX12 统一接口）
• napi：Node.js 原生 addon 绑定，支持 async 函数和 BigInt

# Cargo.toml 核心依赖
cudarc = { version = "0.16", features = ["cublas", "nvrtc", "curand", "cuda-version-from-build-system"] }
wgpu = { version = "24", optional = true }
napi = { version = "2", features = ["napi8"] }

---

核心功能：从 XOR 到神经网络

mni-ml/framework 支持完整的 ML 训练流程：

1. 自动微分（Autograd）

框架维护了一个计算图，每次张量操作（如 add、mul、relu）都会在原生后端记录下来。调用 .backward() 时，后端从当前节点反向遍历图，自动计算所有参数的梯度。整个过程完全在 Rust 中执行，比纯 JS 实现的 autograd 快一到两个数量级。

2. 常用模块

• Linear(inFeatures, outFeatures)：全连接层，权重初始化使用 Xavier uniform
• Conv1d / Conv2d：卷积层，支持 stride 和 padding 参数
• Embedding：词嵌入层，存储 (vocabSize, embedDim) 的权重矩阵
• ReLU / Sigmoid / Tanh：激活函数

3. 优化器

SGD（带动量）、Adam、AdamW，均支持学习率调度（通过 setLearningRate 动态调整）。optimizer.step() 和 optimizer.zeroGrad() 的接口与 PyTorch 完全一致。

4. 跨环境运行

环境	后端	适用场景
Node.js（无 GPU）	CPU（N-API）	服务器端快速验证
Node.js + NVIDIA	CUDA	生产级训练
浏览器	WebGPU	在线推理、交互式 Demo
macOS（Apple Silicon）	WebGPU（Metal）	本地开发

---

上手体验：30 行代码训练一个 XOR 模型

import { Tensor, Linear, Adam, Parameter, softmax, crossEntropyLoss } from '@mni-ml/framework';

// 创建张量
const x = Tensor.rand([32, 10]);
const targets = [[0], [1], [2], /* ... */];

// 构建两层网络
const layer1 = new Linear(10, 64);
const layer2 = new Linear(64, 3);

// 前向传播
let h = layer1.forward(x).relu();
let logits = layer2.forward(h);
let loss = crossEntropyLoss(logits, targets);

// 反向传播
loss.backward();

// 优化
const params = [...layer1.parameters(), ...layer2.parameters()];
const optimizer = new Adam(params, 0.001);
optimizer.step();
optimizer.zeroGrad();

这与 PyTorch 的代码几乎可以一一对应。更重要的是，package.json 中的 exports 字段区分了 browser 和 default 两个入口——前者加载 WebGPU 版本（可在浏览器中运行），后者加载 Node.js 版本（可访问 CUDA）。同一个 npm 包、两套运行策略，无需额外配置。

---

局限与挑战

1. 生态还在早期

项目创建于 2026 年 1 月（距今不到一年），目前版本 0.3.1，远未达到 1.0 稳定版。生态方面：缺少预训练模型加载器（仅 Embedding 支持权重初始化）、缺少数据增强工具、没有量化推理支持。相比 PyTorch 丰富的 torchvision、torchaudio、torchtext，mni-ml 还有很长的路要走。

2. 依赖 Node.js 22.18+

package.json 明确要求 node >= 22.18.0，这是一个较新的大版本。虽然 WebGPU 版本可以跑在浏览器里，但 Node.js 的版本要求意味着在旧环境中无法使用。

3. 调试体验受限

Autograd 和张量操作都下沉到 Rust 层，当计算出错时，TypeScript 侧能拿到的调试信息有限。对于习惯 Python traceback 详细输出的开发者来说，可能需要适应一段时间。

4. WebGPU 性能上限

WebGPU 相比原生 CUDA，在某些场景下仍有约 20-30% 的性能差距。对于追求极致训练速度的场景，直接用 PyTorch 或 JAX 仍然是更务实的选择。

---

行业意义：TypeScript-first ML 框架的新尝试

mni-ml/framework 并不是第一个尝试"用 JS/TS 写 ML"的项目——此前有 TensorFlow.js（Google 维护，生态成熟但偏向推理）、也有纯 Python 后端移植的思路。但 mni-ml 的独特之处在于：它从一开始就将 Rust 高性能计算和 TypeScript 优雅接口作为并列的核心目标，而非事后打补丁。

Rust 后端不仅带来了接近原生 CUDA 的训练速度，还通过 N-API 实现了与 Node.js 生态的无缝集成。相比之下，TF.js 的训练后端（WebGL/WASM）始终在性能上有明显的瓶颈。

从更宏观的角度看，mni-ml/framework 代表了一个趋势：AI 能力正在从 Python 中心向多语言扩展。随着 WebGPU 的成熟和 Rust 在系统编程领域的持续崛起，未来会有更多"前端友好 + 性能卓越"的混合方案出现。mni-ml/framework 正在这个方向上做有价值的探索。

---

快速上手指南

安装：

npm install @mni-ml/framework

浏览器端（WebGPU）：

// ES Module 导入，自动使用 WebGPU 版本
import { Tensor, Linear } from '@mni-ml/framework';

Node.js（自动检测 CUDA/CPU）：

// 导入 Node.js 版本
import { Tensor, Linear } from '@mni-ml/framework';

本地开发（从源码）：

git clone https://github.com/mni-ml/framework.git
cd framework
npm install
# 构建 native 插件（CPU）
npm run build:native
# 或构建 CUDA 版本
npm run build:native:cuda

---

本报告基于 GitHub 仓库 v0.3.1 版本分析，Stars: 1014（2026-10-04）