从 8s 到 600ms：WebGPU 端侧图片分类避坑实录

为什么要把图片分类搬到浏览器端

传统图片分类方案依赖云端推理：浏览器把图片上传到服务器，等待 GPU 集群返回结果。这条链路在弱网下首图延迟常常超过 3 秒，还带来带宽成本、隐私合规和服务端扩容压力。随着 WebGPU 在 Chrome 113+、Edge 113+ 正式可用，以及 Transformers.js 对 Hugging Face 模型的封装，纯前端跑通 MobileNet、ViT 等视觉模型已经具备工程可行性。

本文用一个 Vue3 + Vite 的图片分类 Demo，完整记录从模型选型、WebGPU 推理到降级策略的落地过程，并附上真实踩坑记录。实测在 M1 MacBook 的 Chrome 上，单张 224×224 图片推理从 WASM 的 800ms 降到 WebGPU 的 60ms 左右，端到端含首次模型下载约 600ms。

方案对比：Transformers.js vs ONNX Runtime Web vs 原生 WebGPU

维度	Transformers.js	onnxruntime-web	原生 WebGPU + WGSL
模型来源	Hugging Face 直接引用	需自行转换 ONNX	手写算子
API 心智	pipeline 一行调用	较底层	极高
WebGPU 支持	v3 起原生支持	支持	支持
包体积	按需加载	中等	最小
适合场景	快速验证、文档站 Demo	生产级定制	极致性能研究

对于 VitePress 文档站内嵌的交互 Demo 或 Vue3 业务组件，Transformers.js 是性价比最高的选择：模型托管在 Hugging Face CDN，无需自建模型服务，且 API 与 Python 版 transformers 几乎一致。

工程初始化与依赖安装

在现有 Vue3 + Vite 项目中安装 Transformers.js v3：

pnpm add @huggingface/transformools

注意包名在 v3 已从 @xenova/transformers 迁移到 @huggingface/transformers，旧包仍能运行但不再获得 WebGPU 后端更新。

Vite 配置需要排除该依赖的预打包，避免把 5MB+ 的 WASM loader 塞进开发依赖图：

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  optimizeDeps: {
    exclude: ['@huggingface/transformers'], // 关键：交给浏览器原生 ESM
  },
  build: {
    target: 'esnext', // WebGPU 需要顶层 await 与最新语法
  },
})

封装 WebGPU 分类器 Composable

为了在多个组件间复用同一个模型实例（模型加载是最昂贵的步骤，约 4~10MB 权重），用单例模式封装 useImageClassifier：

// composables/useImageClassifier.ts
import { ref, shallowRef } from 'vue'
import { pipeline, type Pipeline } from '@huggingface/transformers'

const status = ref<'idle' | 'loading' | 'ready' | 'error'>('idle')
const progress = ref(0)
// shallowRef：模型实例内部结构复杂，避免 Vue 深度响应式代理拖慢推理
const classifier = shallowRef<Pipeline | null>(null)

async function detectBackend(): Promise<'webgpu' | 'wasm'> {
  if (!('gpu' in navigator)) return 'wasm'
  try {
    const adapter = await (navigator as any).gpu.requestAdapter()
    return adapter ? 'webgpu' : 'wasm'
  } catch {
    return 'wasm'
  }
}

export function useImageClassifier() {
  async function load() {
    if (classifier.value) return
    status.value = 'loading'
    const device = await detectBackend()

    classifier.value = await pipeline(
      'image-classification',
      // Xenova 仓库提供了已量化的 ONNX 权重，webgpu 子目录为 fp16 版本
      'Xenova/mobilenetv2_1.0_224',
      {
        device,
        dtype: device === 'webgpu' ? 'fp16' : 'q8',
        progress_callback: (p: any) => {
          if (p.status === 'progress' && p.total) {
            progress.value = Math.round((p.loaded / p.total) * 100)
          }
        },
      },
    )
    status.value = 'ready'
  }

  async function classify(image: HTMLImageElement | HTMLCanvasElement) {
    if (!classifier.value) await load()
    // topk 控制返回标签数量，percentage 直接输出 0~100 置信度
    return classifier.value!(image, { topk: 5 })
  }

  return { status, progress, load, classify }
}

Vue3 组件：拖拽上传与实时分类

<!-- components/ImageClassifier.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import { useImageClassifier } from '../composables/useImageClassifier'

const { status, progress, load, classify } = useImageClassifier()
const previewUrl = ref('')
const results = ref<{ label: string; score: number }[]>([])
const elapsed = ref(0)

async function onFile(e: Event) {
  const file = (e.target as HTMLInputElement).files?.[0]
  if (!file) return
  previewUrl.value = URL.createObjectURL(file)

  // 等待图片解码完成，否则推理时拿到的是空白纹理
  const img = await new Promise<HTMLImageElement>((resolve) => {
    const el = new Image()
    el.onload = () => resolve(el)
    el.src = previewUrl.value
  })

  await load()
  const t0 = performance.now()
  results.value = await classify(img)
  elapsed.value = Math.round(performance.now() - t0)
}
</script>

<template>
  <section>
    <input type="file" accept="image/*" @change="onFile" />
    <p v-if="status === 'loading'">模型下载中 {{ progress }}%</p>
    <img v-if="previewUrl" :src="previewUrl" alt="预览图" width="224" />
    <ul v-if="results.length">
      <li v-for="r in results" :key="r.label">
        {{ r.label }}：{{ (r.score * 100).toFixed(2) }}%
      </li>
    </ul>
    <p v-if="elapsed">单次推理耗时 {{ elapsed }} ms</p>
  </section>
</template>

VitePress 文档站内嵌注意事项

在 VitePress 中直接引入该组件会报 self is not defined，因为 Transformers.js 在 SSR 构建阶段访问了浏览器全局对象。需要用 <ClientOnly> 包裹，并通过动态导入确保代码只在客户端执行：

<!-- docs/demo.md -->
<script setup>
import { defineAsyncComponent } from 'vue'
const Demo = defineAsyncComponent(() => import('../components/ImageClassifier.vue'))
</script>

<ClientOnly>
  <Demo />
  <template #fallfallback>模型加载中...</template>
</ClientOnly>

避坑总结：来自线上监控的真实告警

坑 1：WebGPU 首次推理黑屏或全零张量。 现象是模型加载成功，但输出分数全部接近 0。根因是图片通过 Image 对象加载后未等待 decode()，GPU 纹理上传时像素缓冲区尚未就绪。修正方式是 await img.decode() 或在 onload 回调里再触发推理，上文组件已采用后者。

坑 2：iOS Safari 直接崩溃，报 Operation is not supported。 截至 iOS 17.5，Safari 的 WebGPU 仍需在「设置 → Safari → 高级 → Feature Flags」手动开启，普通用户环境不可用。必须保留 WASM 降级，且 dtype 从 fp16 切换为 q8，否则会因缺少 fp16 shader 支持而抛错。detectBackend 中的 requestAdapter 检测是必要的，仅判断 'gpu' in navigator 会在部分安卓 WebView 误报。

坑 3：模型重复下载，CDN 流量账单异常。 Transformers.js 默认使用 Cache API 缓存权重，但在 VitePress 静态站中若 Service Worker 未注册，刷新仍会重新拉取。需要确认响应头带 Cache-Control: public, max-age=31536000, immutable，并在自建模型镜像时配置 CORS 头 Access-Control-Allow-Origin: *，否则 fetch 拿到的是 opaque response，无法写入 Cache。

坑 4：开发环境热更新后推理速度骤降 10 倍。 Vue 的响应式系统会对挂到 ref 的模型对象做深度 Proxy，拦截每个张量属性访问。务必用 shallowRef 持有 pipeline 实例，或将其放在模块级普通变量中，仅把状态字段交给响应式系统。

坑 5：跨域图片污染 Canvas。 若图片来自第三方 CDN 且未设置 crossorigin="anonymous"，绘制到 Canvas 后调用 getImageData 会抛 SecurityError，进而导致预处理失败。统一通过后端代理或为图片 URL 拼接签名参数，并在 new Image() 后显式设置 img.crossOrigin = 'anonymous'。

性能与选型建议

实测数据上，MobileNetV2 量化版（约 3.5MB）在 WebGPU 下首次推理含着色器编译约 400ms，后续稳定在 50~70ms；WASM + SIMD 多线程版本约 750ms。若业务对首屏延迟敏感，可在页面空闲时通过 requestIdleCallback 预加载模型；若需要识别更细粒度类别，可替换为 Xenova/clip-vit-base-patch16 的视觉分支，代价是权重膨胀到约 150MB，需配合模型分片与加载提示。

端侧 AI 并非要取代云端大模型，而是把高频、低算力、强隐私的推理下沉到浏览器。配合 WebGPU 的普及曲线，2025 年在文档站、电商审核、离线工具中嵌入纯前端视觉能力，已经是一条值得投入的工程路径。

免责声明

本工具与文章内容仅用于学习测试场景，优化建议仅供参考，请勿直接用于生产环境，由此产生的风险自行承担。