wasi-nn

一项用于机器学习（ML）的拟议 WebAssembly 系统接口 API。

当前阶段

wasi-nn 目前处于 第 2 阶段。

发起人

• Andrew Brown
• Mingqiu Sun

第 4 阶段推进标准

wasi-nn 必须至少拥有两个完整的独立实现。

目录

• 引言
• 目标
• 非目标
• API 概览
• 详细设计讨论
• 备选方案
• 利益相关方兴趣与反馈
• 参考文献与致谢

引言

wasi-nn 是一个用于执行 ML 推理的 WASI API。其名称源自 ML 模型也被称为神经网络（nn）。ML 模型通常使用大型数据集进行训练，生成描述模型权重的一个或多个文件。随后，该模型被用于计算“推理”，例如将图像分类为一组标签的概率。本 API 目前主要关注推理，而非训练。

为什么要把 ML 推理暴露为 WASI API？尽管推理功能可以编码到 WebAssembly 中，但 wasi-nn 的推出主要有两个动机：

1. 易用性：已经存在一个完整的生态系统来训练和使用模型（例如 TensorFlow、ONNX、OpenVINO 等）；wasi-nn 的设计旨在使用户能够直接使用现有的模型格式。
2. 性能：ML 推理的特性使其非常适合各种硬件加速；如果没有这些硬件加速，推理速度可能会降低数百倍。ML 的硬件加速方式多种多样——SIMD（如 AVX512）、GPU、TPU、FPGA 等——而所有这些加速方式都不太可能（甚至不可能）在 WebAssembly 中得到原生支持。

希望利用主机 ML 能力的 WebAssembly 程序可以通过 wasi-nn 的核心抽象——后端、_图_和 张量——来访问这些能力。用户首先选择一个用于推理的 后端，然后加载以 图 形式表示的模型，并在该 后端 上运行。接着，用户将 张量 输入传递给 图，执行推理，并获取 张量 输出。

wasi-nn 的 后端 对应于现有的 ML 框架，例如 TensorFlow、ONNX、OpenVINO 等。wasi-nn 不要求宿主系统必须支持特定的 后端；该 API 的设计初衷就是尽可能让更多的 ML 框架能够实现它。wasi-nn 的 图 可以作为不透明的字节序列传递，从而支持任意数量的模型格式。这使得 API 具备框架和格式无关性，因为我们期望设备厂商提供 ML 后端 并支持其特定的 图 格式。

用户可以在 wasi-nn 绑定 仓库中找到 wasi-nn 的语言绑定；如有需要其他语言的支持，可在此处提出请求。更多关于 wasi-nn 的信息请参见：

• 博文：WebAssembly 中的机器学习：在 Wasmtime 中使用 wasi-nn
• 博文：在 Wasmtime 中实现 WASI 提案：wasi-nn
• 博文：使用 ONNX、WebAssembly 系统接口和 wasi-nn 进行 PyTorch 和 TensorFlow 的神经网络推理
• 录播演讲：使用 Wasm 进行机器学习（wasi-nn）
• 录播演讲：闪电演讲：使用 wasi-nn 实现高性能神经网络推理

目标

wasi-nn 的首要目标是让用户能够从 WebAssembly 中使用现有模型进行 ML 推理（即易用性），同时获得最佳性能。虽然目前的重点是推理，但我们计划在未来保留进行 ML 训练的可能性（可在 issue 中提出训练需求！）。

另一个设计目标是使 API 具备框架和模型无关性；这样就可以用多种 ML 框架和模型格式来实现该 API。当传入不受支持的模型编码方案时，load 方法会返回错误信息。这种方法类似于浏览器处理图像或视频编码的方式。

非目标

wasi-nn 并非旨在提供对单个 ML 操作的支持（即“模型构建者”API）。ML 领域仍在快速发展，新的操作和网络拓扑不断涌现。要在 API 中定义一套不断变化的操作集将是一项挑战。因此，我们的方法是从“模型加载器”API 开始，灵感来源于 WebNN 的模型加载器提案。

API 概览

以下示例描述了用户如何使用 wasi-nn：

// 加载模型。
let encoding = wasi_nn::GRAPH_ENCODING_...;
let target = wasi_nn::EXECUTION_TARGET_CPU;
let graph = wasi_nn::load(&[bytes, more_bytes], encoding, target);

// 配置执行上下文。
let context = wasi_nn::init_execution_context(graph);
let tensor = wasi_nn::Tensor { ... };
wasi_nn::set_input(context, 0, tensor);

// 执行推理。
wasi_nn::compute(context);
wasi_nn::get_output(context, 0, &mut output_buffer, output_buffer.len());

请注意，上述细节将取决于所使用的模型和后端；这段伪 Rust 代码仅用于说明总体思路，未包含任何错误检查。有关更详细的示例，请参阅 AssemblyScript 和 Rust 绑定。

详细设计讨论

有关 API 的详细信息，请参阅 wasi-nn.wit。

wasi-nn 是否应支持模型训练？

理想情况下，是的。然而，在短期内，暴露（并实现）以推理为中心的 API 已经足够复杂，因此可以将支持训练的 API 推迟到以后再实现。此外，模型通常是在部署之前离线训练的，目前尚不清楚使用 WASI 进行模型训练相比原生训练有何优势。（相反，推理 API 则很有意义：在 Wasm 部署中执行机器学习推理是一个已知的用例）。相关讨论请参见这里，欢迎根据上述目标就此提出拉取请求或议题。

wasi-nn 是否应支持模型检查？

理想情况下，是的。能够检查模型将使用户在运行时确定模型输入和输出的张量形状。与机器学习训练一样（如上所述），这一功能也可以在未来添加。

曾考虑的替代方案

还有其他方式可以从 WebAssembly 程序中执行机器学习推理：

1. 用户可以为机器学习任务指定一个__自定义宿主 API__；这类似于此处所采用的方法。其优缺点与其他“规范 vs. 自定义”权衡一致：用户可以根据自身用例精确定制 API 等，但将难以在不同实现之间轻松切换。
2. 用户可以将__框架和/或模型编译为 WebAssembly__；这类似于此处和此处的做法。这种方法的主要缺点是性能：即使 WebAssembly 最近增加了 128 位 SIMD 指令，它仍然缺乏针对机器学习推理或访问机器学习优化硬件的高效原语。由此带来的性能损失可能高达几个数量级。

利益相关方的兴趣与反馈

在进入阶段 3 之前待办事项。

参考文献与致谢

非常感谢以下人士提供的宝贵反馈和建议：

• Brian Jones
• Radu Matei
• Steve Schoettler

wasi-nn 快速上手指南

wasi-nn 是 WebAssembly 系统接口 (WASI) 中用于机器学习推理的 API 提案。它允许 WebAssembly 程序调用宿主环境的机器学习能力（如 TensorFlow, ONNX, OpenVINO 等后端），在利用硬件加速的同时保持模型格式的通用性。

环境准备

在使用 wasi-nn 之前，请确保满足以下系统和软件要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)。
• 运行时支持: 需要支持 wasi-nn 提案的 WebAssembly 运行时。目前 Wasmtime 是主要的支持者。
  • 注意：wasi-nn 处于 WASI Phase 2 阶段，功能可能随版本更新而变化。
• 开发工具链:
  • Rust 工具链 (推荐使用，官方示例多为 Rust)。
  • 或者 AssemblyScript 工具链。
• 模型文件: 准备好已训练好的模型文件 (例如 .onnx, .bin 等格式)，wasi-nn 专注于推理而非训练。
• 后端依赖: 根据你选择的后端（如 ONNX Runtime, TensorFlow, OpenVINO），宿主系统可能需要安装相应的底层库。

安装步骤

1. 安装支持 wasi-nn 的 Wasmtime

你需要安装最新版本的 Wasmtime，并确保其编译时启用了 wasi-nn 特性（官方预编译二进制通常已包含，或需从源码编译）。

# 使用官方安装脚本 (Linux/macOS)
curl https://wasmtime.dev/install.sh -sSf | bash

# 验证安装并检查版本
wasmtime --version

提示: 如果你需要特定的后端支持（如 ONNX），在安装 Wasmtime 时可能需要通过 Cargo 从源码构建并开启相应 feature，例如：

cargo install wasmtime-cli --features wasi-nn --locked

2. 设置项目依赖 (以 Rust 为例)

创建一个新的 Rust 项目并添加 wasi-nn 绑定库。

cargo new wasi-nn-demo
cd wasi-nn-demo

编辑 Cargo.toml，添加 wasi-nn crate：

[dependencies]
wasi-nn = "0.2" # 版本号请参考 crates.io 最新状态

3. 准备模型文件

将你的模型文件（例如 model.onnx）放入项目目录中，以便后续加载。

基本使用

以下是一个基于 Rust 的最小化使用示例，演示如何加载模型、设置输入张量、执行推理并获取输出。

代码示例 (src/main.rs)

use wasi_nn::{GraphEncoding, ExecutionTarget, Tensor};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 读取模型文件字节流
    // 假设当前目录下有一个 model.onnx 文件
    let model_bytes = std::fs::read("model.onnx")?;

    // 2. 加载模型 (Load)
    // 指定编码格式 (如 ONNX) 和执行目标 (如 CPU)
    let graph = wasi_nn::load(
        &[&model_bytes], 
        GraphEncoding::Onnx, 
        ExecutionTarget::Cpu
    )?;

    // 3. 初始化执行上下文 (Init Context)
    let context = wasi_nn::init_execution_context(graph)?;

    // 4. 设置输入张量 (Set Input)
    // 构造输入数据，这里假设是一个简单的 f32 数组
    let input_data: Vec<f32> = vec![0.1, 0.2, 0.3, 0.4]; 
    let tensor = Tensor {
        dimensions: &[1, 4], // 维度形状
        r#type: wasi_nn::TensorType::Fp32,
        data: &input_data,
    };
    
    // 将张量设置为第 0 号输入
    wasi_nn::set_input(context, 0, tensor)?;

    // 5. 执行推理 (Compute)
    wasi_nn::compute(context)?;

    // 6. 获取输出 (Get Output)
    let mut output_buffer = vec![0u8; 1024]; // 预分配输出缓冲区
    let bytes_written = wasi_nn::get_output(context, 0, &mut output_buffer)?;
    
    println!("推理完成，输出字节数: {}", bytes_written);
    // 此处可根据模型输出类型解析 output_buffer
    
    Ok(())
}

编译与运行

使用 wasm32-wasi 目标编译代码，并通过 wasmtime 运行：

# 添加 wasm32-wasi 目标
rustup target add wasm32-wasi

# 编译为 WebAssembly
cargo build --target wasm32-wasi --release

# 运行 (确保模型文件在当前目录)
wasmtime run --dir=. target/wasm32-wasi/release/wasi-nn-demo.wasm

注意: 运行命令中的 --dir=. 是为了让 Wasm 模块能够访问当前目录下的模型文件。如果使用了特定的后端（如 ONNX），请确保运行 Wasmtime 的环境中已安装对应的运行时库。