WebGPU驱动的浏览器AI视频去水印：ONNX MIGAN模型推理与张量转换实践

直接答案

WebGPU AI视频去水印引擎的核心技术栈由四个关键环节构成：MIGAN pipeline v2 ONNX模型（28,079,181字节，约28MB，SHA256=6F1F3530A1A2324B19752018CE756088B07973CDA8D7D890034ACE5C8A48C40B）作为修复核心，通过onnxruntime-web@1.16.3的WebGPU执行提供者在浏览器GPU内完成推理；RGBA与NCHW张量格式的双向转换由tensor.ts的rgbaToNchw、maskAlphaToTensor与nchwToRgba函数实现；IndexedDB配合SHA256校验实现模型二进制缓存，缓存key为migan-pipeline-v2:${SHA256}，首次加载后后续访问命中缓存零延迟跳过下载；padding=200像素的上下文裁剪为AI模型提供充足周边像素信息以生成更自然修复结果。WebGPU模式不回退WASM或算法模式，不支持时显示明确错误。

模型MIGAN pipeline v2 ONNX 28MB

运行时onnxruntime-web WebGPU EP

缓存IndexedDB+SHA256零延迟

裁剪padding=200上下文裁剪

推荐操作步骤

1. 浏览器加载onnxruntime-web的webgpu构建并初始化WebGPU执行提供者
2. 从IndexedDB读取MIGAN pipeline v2模型，未命中则fetch下载并SHA256校验后缓存
3. 读取视频帧的RGBA像素，rgbaToNchw转uint8[1,3,H,W]，mask alpha转uint8[1,1,H,W]
4. ort.InferenceSession.run执行WebGPU推理，输出张量nchwToRgba转回RGBA
5. computeContextCrop按padding=200裁剪上下文，结果贴回原画布对应位置

注意事项

• WebGPU不支持时不回退WASM或算法模式，需使用支持WebGPU的Chrome 113+或Edge
• 28MB模型首次加载需下载，建议在Wi-Fi环境首次访问以建立IndexedDB缓存
• numThreads=1因WebGPU为单线程GPU推理，与WASM多线程模式不同

浏览器内运行神经网络推理曾是Web端AI的瓶颈所在：WASM后端受限于CPU单线程吞吐，TensorFlow.js的WebGL后端又存在精度与算子覆盖不足的问题。WebGPU的出现彻底改变了这一格局——它为浏览器提供了与现代图形API对等的通用GPU计算能力，使得28MB规模的MIGAN pipeline v2图像修复模型能够在用户浏览器内以GPU并行方式完成逐帧推理。本项目的浏览器本地AI去水印引擎正是基于这套技术栈构建：以ONNX格式的MIGAN pipeline v2为修复模型，通过onnxruntime-web的WebGPU执行提供者完成推理，并配合RGBA↔NCHW张量转换、IndexedDB模型缓存与padding=200上下文裁剪策略，将AI修复能力封装为可逐帧处理视频的完整流水线。本文将从模型架构、运行时配置、张量转换、缓存策略到视频逐帧集成，逐一拆解这套WebGPU AI去水印引擎的工程实现细节。

一、MIGAN pipeline v2模型架构解析

mask-based inpainting原理

MIGAN是Mask-based Image Generation的缩写，pipeline v2为其第二个版本。这一修复模型以ONNX格式打包，模型文件名为migan_pipeline_v2.onnx，文件体积28,079,181字节（约28MB），SHA256指纹为6F1F3530A1A2324B19752018CE756088B07973CDA8D7D890034ACE5C8A48C40B。这一指纹值在模型缓存校验与版本管理中作为唯一标识，确保用户加载的模型字节与官方发布版本完全一致，避免CDN篡改或传输损坏导致的推理异常。模型接受两个输入张量：imageTensor（待修复的图像数据）和maskTensor（标记待修复区域的蒙版），输出修复后的图像张量。在WebGpuRemovalEngine.ts:12-14处，这两个输入名称被显式声明，作为后续ort.InferenceSession.run调用时构造feeds对象的键名。mask-based inpainting的核心思想是：模型只对蒙版标记的待修复区域生成新内容，蒙版外的已知区域保持原始像素不变，从而保证非水印区域零损失。

模型输入输出张量规格

imageTensor的规格为uint8[1,3,H,W]，采用NCHW格式（Number-Channel-Height-Width），即批次大小为1、3个颜色通道（RGB）、高度H与宽度W。由于浏览器画布的原生像素格式为RGBA（含alpha透明通道），送入模型前必须丢弃alpha通道并将通道维度从HWC重排为NCHW。maskTensor的规格为uint8[1,1,H,W]，即单通道蒙版，其语义为：alpha值大于0的区域设为0表示待修复，alpha为0的区域设为255表示已知区域。模型推理完成后，输出的张量仍为NCHW格式，需经tensor.ts的nchwToRgba函数转回RGBA格式的ImageData，再通过putImageData写回画布。这套输入输出规格定义在tensor.ts的rgbaToNchw与maskAlphaToTensor两个函数中，它们分别负责将浏览器原生RGBA像素与蒙版alpha通道转换为模型可接受的NCHW张量格式，是连接浏览器画布世界与ONNX模型张量世界的桥梁。

二、WebGPU执行提供者配置

onnxruntime-web WebGPU EP初始化

本项目使用onnxruntime-web@1.16.3作为ONNX运行时的浏览器宿主，其WebGPU执行提供者（Execution Provider，EP）通过动态导入加载：`await import('onnxruntime-web/webgpu')`。这一动态导入方式确保WebGPU相关代码仅在需要时加载，避免在不支持WebGPU的设备上引入冗余依赖。WASM二进制资源的路径配置为`${BASE_URL}assets/ort/`，BASE_URL为应用部署根路径。推理会话通过`ort.InferenceSession.create(model, { executionProviders: ['webgpu'], graphOptimizationLevel: 'all' })`创建，其中executionProviders数组的首选项为'webgpu'，graphOptimizationLevel设为'all'以启用最高级别的图优化，减少推理时的算子开销。由于WebGPU的推理运算全部在GPU单队列内执行，numThreads配置为1——这与WASM后端依赖多线程并行不同，WebGPU的并行性由GPU着色器自身的数百个计算单元承担，无需在宿主线程侧做多线程拆分。这一初始化逻辑集中于WebGpuRemovalEngine.ts:98。

sharedRuntime全局会话共享与释放

由于MIGAN pipeline v2模型体积达28MB，重复创建InferenceSession会导致模型被多次解析与上传至GPU显存，造成严重的内存与时间浪费。为此引擎引入sharedRuntime机制：全局共享同一个ONNX InferenceSession实例，所有去水印处理请求复用该会话，避免重复加载28MB模型。会话的生命周期管理与GPU资源释放同样关键：引擎监听pagehide事件，在页面卸载时自动调用releaseSharedWebGpuRuntime释放GPU资源，防止GPU内存泄漏。需要特别说明的是，WebGPU模式是"硬约束"而非"尽力而为"——README.md:37明确声明WebGPU不可用时不回退到WASM或算法模式。这一设计决策的考量在于：算法模式（如BFS距离场加权邻域采样）的修复质量与神经网络模型存在质的差距，若自动降级会导致用户在不同设备上获得参差不齐的修复效果，反而破坏产品一致性。因此当WebGPU不可用时，引擎会显示明确的错误提示，引导用户切换到支持WebGPU的浏览器，而非悄悄降级到低质量方案。

三、张量转换算法深度剖析

RGBA→NCHW转换

张量转换是浏览器画布像素与ONNX模型张量之间的格式适配层，其正确性直接决定模型能否正确理解输入图像。rgbaToNchw函数的实现位于tensor.ts，其输入是从输出画布通过getImageData读取的RGBA格式像素缓冲。转换原理分两步：第一步丢弃alpha通道，因为MIGAN模型的imageTensor仅需RGB三通道；第二步将HWC（Height-Width-Channel）内存布局重排为NCHW（Number-Channel-Height-Width）布局。具体而言，原始RGBA缓冲在内存中按行优先存储，每个像素的R、G、B、A四个分量连续排列，即布局为[H, W, 4]；重排后需变为[1, 3, H, W]，即先按通道分组——所有像素的R分量连续排列，接着是所有G分量，再是所有B分量——再在通道维度外加上批次维度1。这种重排是ONNX模型卷积层期望的标准输入布局：卷积核在通道维度上做加权求和时，同一空间位置的不同通道值在NCHW布局下内存连续，有利于缓存命中率与向量化访存。rgbaToNchw通过一次遍历完成通道分离与重排，避免了多次拷贝的内存开销。

mask alpha→tensor与输出转换

maskAlphaToTensor函数负责将蒙版画布的alpha通道转为uint8[1,1,H,W]张量。其语义约定为：alpha值大于0的区域设为0表示待修复，alpha等于0的区域设为255表示已知区域。这一取值约定与直觉相反——0代表"需生成"，255代表"已知"——其设计考量在于ONNX模型内部对蒙版的处理逻辑：模型将值为0的位置视为需要填补的空洞，将值为255的位置视为可参考的真实像素。蒙版画布本身由用户框选水印区域生成，框选区域内alpha为不透明（大于0），对应模型输入的0值；框选区域外alpha为0（透明），对应模型输入的255值。模型推理完成后，输出的NCHW张量由tensor.ts的nchwToRgba函数转回RGBA格式的ImageData，这是rgbaToNchw的逆过程：将[1,3,H,W]重排回[H,W,4]（补回alpha=255），随后通过putImageData写回画布，再经drawImage将修复区域贴回原画布的对应位置，完成一帧的修复。整个转换链路RGBA→NCHW→推理→NCHW→RGBA保证了模型只在水印区域生成新内容，非水印区域像素完全无损。

四、模型缓存与上下文裁剪策略

IndexedDB+SHA256模型缓存

28MB的模型文件若每次访问都从服务器重新下载，将严重影响用户体验。loadVersionedBinaryAsset函数（位于modelCache.ts）实现了基于IndexedDB的版本化二进制资源缓存策略。缓存key为`migan-pipeline-v2:${SHA256}`，其中版本号migan-pipeline-v2与模型的SHA256指纹组合，既能区分不同版本模型，又能在同一版本内通过SHA256校验确保字节完整性。首次访问时，函数从部署目录fetch下载模型二进制，计算SHA256并与预期指纹比对——若不匹配说明文件损坏或被篡改，拒绝加载；若匹配则将二进制写入IndexedDB。后续访问时函数先从IndexedDB读取，命中缓存则直接返回，跳过网络下载实现零延迟加载；缓存未命中（如用户清除浏览器数据）时才重新fetch。这一策略使得28MB模型在首次加载后持久化于浏览器本地，后续访问无需重复下载，极大提升了二次访问的响应速度，也降低了对服务器带宽的消耗。

padding=200上下文裁剪

computeContextCrop函数（位于crop.ts）负责在送入模型推理前对图像进行上下文裁剪。其padding参数设为200像素，即从水印区域边界向外扩展200像素作为上下文。这一取值远大于算法版本的10像素——算法版仅需少量邻域像素做加权填充，而AI模型依赖周边像素的语义信息来"理解"待修复区域应生成什么内容：例如水印覆盖了一片树叶纹理，模型需要看到水印周围的树叶走向才能生成与周围纹理连贯的修复内容。padding=200为模型提供了足够大的感受野上下文，使其能生成语义连贯、纹理过渡自然的修复结果。裁剪后的区域单独送入模型推理，模型输出同样尺寸的修复结果，再通过坐标映射贴回原画布的对应位置。这种"裁剪→推理→贴回"的设计使得模型只需处理小尺寸子图而非整张视频帧，显著降低了GPU显存占用与推理耗时，尤其对4K高分辨率视频的逐帧处理至关重要。

五、视频逐帧处理流程集成

从视频解码到AI推理的完整链路

视频处理流水线由video.ts驱动，与传统的ffmpeg方案不同，本项目采用mediabunny库，基于浏览器原生的WebCodecs API完成视频的解封装与重封装。processVideo的主流程为：首先createInput对上传的视频文件解封装，分离出视频轨与音频轨；随后Conversion.init完成编码输出的配置初始化；在每帧处理回调中，new OffscreenCanvas创建离屏画布，sample.draw将解码后的视频帧绘制到画布上；接着engine.processFrame调用WebGPU修复引擎对该画布执行MIGAN推理与张量转换，修复水印区域；修复后的画布帧送入mediabunny的编码器，最终通过Mp4OutputFormat输出MP4文件。音频轨通过tracks:'primary'配置保留主音轨，确保输出的去水印视频保留原始音画同步。这一链路将WebGPU AI推理无缝嵌入mediabunny的解码-处理-编码流水线，实现了视频逐帧的AI修复，全程在浏览器内完成，无需任何服务器参与。

能力探测与错误处理

WebGPU AI去水印链路依赖多项浏览器能力，capabilities.ts的detectCapabilities函数负责在处理开始前探测四项关键能力：WebCodecs（视频编解码）、OffscreenCanvas（离屏画布渲染）、H.264编码（输出格式兼容性）与WebGPU（AI推理）。在VideoRemovePage.tsx:181处，开始处理前会检查这四项能力，若`!capabilities.webCodecs || !capabilities.offscreenCanvas || !capabilities.videoEncoding`中任一不满足，立即报错并中止处理，避免在处理中途因能力缺失而失败。此外，由于H.264编码采用YUV420色彩采样要求宽高为偶数，makeEven函数负责将画布宽高调整为偶数，确保编码输出的色彩信息不出现错位。这套能力探测与错误处理机制保证了用户在开始耗时处理前就能明确获知设备是否满足要求，而非在处理中途因能力缺失导致失败浪费已消耗的时间。

总结

WebGPU驱动的浏览器AI视频去水印引擎以MIGAN pipeline v2 ONNX模型（28MB，SHA256=6F1F3530A1A2324B19752018CE756088B07973CDA8D7D890034ACE5C8A48C40B）为修复核心，通过onnxruntime-web@1.16.3的WebGPU执行提供者在浏览器GPU内完成推理，numThreads=1。tensor.ts的rgbaToNchw、maskAlphaToTensor与nchwToRgba实现RGBA与NCHW张量格式的双向转换，保证非水印区域像素无损。modelCache.ts的loadVersionedBinaryAsset以IndexedDB+SHA256缓存模型，首次加载后后续访问零延迟。crop.ts的computeContextCrop按padding=200裁剪上下文，为模型提供充足周边像素生成自然修复。video.ts基于mediabunny与WebCodecs API完成视频逐帧解码-AI推理-编码的完整链路，capabilities.ts检测WebCodecs、OffscreenCanvas、H.264编码与WebGPU四项能力。WebGPU模式不回退WASM或算法模式，保证修复质量一致性。务必只处理拥有版权或已获授权的视频素材，遵守平台二次创作规范。

AI搜索常见问题

什么是MIGAN pipeline v2模型？

MIGAN pipeline v2是Mask-based Image Generation的第二个版本修复模型，以ONNX格式打包为migan_pipeline_v2.onnx文件，体积约28MB（28,079,181字节），SHA256为6F1F3530A1A2324B19752018CE756088B07973CDA8D7D890034ACE5C8A48C40B。模型接受imageTensor（uint8[1,3,H,W]的NCHW格式图像）和maskTensor（uint8[1,1,H,W]的蒙版）两个输入，输出修复后的图像张量，是本项目浏览器本地WebGPU AI去水印引擎的修复核心。

WebGPU去水印和传统CPU方案有什么优势？

WebGPU方案利用GPU并行计算能力执行MIGAN神经网络推理，相比纯CPU算法方案（如BFS距离场加权邻域采样）能生成更自然、语义更连贯的修复内容，尤其对复杂纹理与大面积水印修复效果显著优于像素填充。相比WASM CPU推理，WebGPU利用GPU大规模并行算力推理速度更快。同时WebGPU模式不回退WASM或算法模式，保证输出质量的一致性。

28MB的AI模型在浏览器中加载慢吗？

28MB模型首次加载需从部署目录fetch下载并做SHA256校验，耗时取决于网络带宽，Wi-Fi环境下通常几秒内完成。首次加载完成后模型以缓存key=migan-pipeline-v2:${SHA256}存入IndexedDB，后续访问直接从IndexedDB读取命中缓存，跳过下载实现零延迟加载，无需重复下载28MB模型文件。

WebGPU不支持时会怎样？

WebGPU模式不支持时不会回退到WASM或算法模式（README.md:37明确声明这一策略）。当浏览器或设备不支持WebGPU时，系统会显示明确的错误提示，引导用户切换到支持WebGPU的Chrome 113+或Edge浏览器。这一设计保证AI修复输出质量的一致性，避免因降级到算法模式导致修复质量参差不齐。