快速开始指南

几分钟内启动并运行 Tiny-DL-Inference。

---

前置要求

系统要求

• Node.js: 18.0 或更高版本（推荐 20.x）
• npm: 8.0 或更高版本
• GPU: 支持 WebGPU 的显卡

浏览器支持

需要支持 WebGPU 的浏览器：

• Chrome 113+ 或 Edge 113+（推荐）
• Safari 18+ on macOS Sonoma+

检查 WebGPU 支持：

if (navigator.gpu) {
  console.log('WebGPU 受支持！');
} else {
  console.error('此浏览器不支持 WebGPU');
}

---

安装

从 npm 安装（发布后）

npm install tiny-dl-inference

从源码安装

# 克隆仓库
git clone https://github.com/LessUp/tiny-dl-inference.git
cd tiny-dl-inference

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试验证安装
npm test

---

第一步

1. 基本设置

import { InferenceEngine, ModelLoader } from 'tiny-dl-inference';

// 创建并初始化引擎
const engine = new InferenceEngine();
await engine.initialize();
console.log('引擎初始化成功');

2. 创建张量

// 从数组创建张量
const data = new Float32Array([1.0, 2.0, 3.0, 4.0]);
const tensor = engine.tensorFromArray(data, [1, 4]);

// 或使用零/一创建
import { GPUContext } from 'tiny-dl-inference';
const context = new GPUContext();
await context.initialize();

const zeros = Tensor.zeros(context, [1, 3, 224, 224]);
const ones = Tensor.ones(context, [1, 3, 224, 224]);

3. 加载模型

// 定义你的模型结构
const modelDef = {
  layers: [
    { type: 'conv2d', name: 'conv1', inputs: ['input'], params: { channels: 32, kernelSize: 3 } },
    { type: 'relu', name: 'relu1', inputs: ['conv1'], params: {} },
    { type: 'maxpool', name: 'pool1', inputs: ['relu1'], params: { poolSize: 2 } },
    { type: 'flatten', name: 'flatten', inputs: ['pool1'], params: {} },
    { type: 'dense', name: 'output', inputs: ['flatten'], params: { units: 10 } },
    { type: 'softmax', name: 'softmax', inputs: ['output'], params: { axis: 1 } }
  ],
  weights: {
    'conv1.weight': { data: conv1WeightData, shape: [32, 1, 3, 3] },
    'conv1.bias': { data: conv1BiasData, shape: [32] },
    'output.weight': { data: denseWeightData, shape: [10, 1152] },
    'output.bias': { data: denseBiasData, shape: [10] }
  }
};

await engine.loadModel(modelDef);

4. 运行推理

// 准备输入数据（例如 28x28 灰度图像）
const imageData = new Float32Array(28 * 28).fill(0.5);
const input = engine.tensorFromArray(imageData, [1, 1, 28, 28]);

// 运行推理
const output = await engine.infer(input);
const predictions = await output.download();

console.log('预测结果:', predictions);

// 清理
engine.destroy();

---

MNIST 示例

完整的 MNIST 手写数字分类示例：

import { InferenceEngine, ModelLoader } from 'tiny-dl-inference';

async function classifyDigit(imageData: Float32Array): Promise<number> {
  const engine = new InferenceEngine();
  await engine.initialize();
  
  try {
    // 加载预训练的 MNIST 模型
    const loader = new ModelLoader();
    const model = await loader.loadFromJSON('mnist-model.json');
    await engine.loadModel(model);
    
    // 准备输入：归一化到 [0, 1]
    const normalized = imageData.map(v => v / 255.0);
    const input = engine.tensorFromArray(normalized, [1, 1, 28, 28]);
    
    // 运行推理
    const output = await engine.infer(input);
    const logits = await output.download();
    
    // 获取预测结果（argmax）
    let maxIndex = 0;
    let maxValue = logits[0];
    for (let i = 1; i < logits.length; i++) {
      if (logits[i] > maxValue) {
        maxValue = logits[i];
        maxIndex = i;
      }
    }
    
    return maxIndex;
  } finally {
    engine.destroy();
  }
}

// 使用
const digit = await classifyDigit(yourImageData);
console.log(`预测数字: ${digit}`);

---

内存布局

Tiny-DL-Inference 支持两种内存布局：

NCHW（PyTorch 风格）

const input = engine.tensorFromArray(data, [1, 3, 224, 224], { layout: 'NCHW' });
// 形状：[批次, 通道, 高度, 宽度]

NHWC（TensorFlow 风格）

const input = engine.tensorFromArray(data, [1, 224, 224, 3], { layout: 'NHWC' });
// 形状：[批次, 高度, 宽度, 通道]

注意：当前的 Conv2d 和 MaxPool 执行路径仅支持 NCHW。引擎包含布局转换工具，可处理不同格式。

---

常见陷阱

1. WebGPU 上下文问题

// ❌ 错误：使用错误的上下文
const engine = new InferenceEngine();
await engine.initialize();
const wrongContext = new GPUContext();
await wrongContext.initialize();
const tensor = Tensor.zeros(wrongContext, [1, 4]);
await engine.infer(tensor); // 错误：张量使用不同的上下文

// ✅ 正确
const input = engine.tensorFromArray(data, [1, 4]); // 使用引擎的上下文

2. 形状不匹配

// ❌ 错误：形状与数据长度不匹配
const data = new Float32Array(784); // 28*28
const tensor = engine.tensorFromArray(data, [1, 1, 32, 32]); // 错误！

// ✅ 正确
const tensor = engine.tensorFromArray(data, [1, 1, 28, 28]);

3. 资源清理

// 始终清理以防止内存泄漏
const engine = new InferenceEngine();
await engine.initialize();

// ... 使用引擎 ...

// ✅ 清理
engine.destroy();

---

下一步

• 了解可用算子
• 探索 API 参考
• 阅读优化技术
• 查看更多示例

---

故障排除

WebGPU 不受支持

如果你看到 WebGPUNotSupportedError：

1. 将浏览器更新到最新版本
2. 在浏览器标志中启用 WebGPU（chrome://flags）
3. 检查 GPU 兼容性

内存不足

对于大型模型：

1. 使用较小的批次处理输入
2. 在推理之间使用 engine.destroy()
3. 监控 GPU 内存使用情况

构建错误

确保你有：

• TypeScript 5.0+
• Node.js 18+
• 所有依赖已安装（npm install）