浏览器端多语种 AI 配音卡在 86%？从 WebGPU、WASM 到模型缓存治理的完整修复实践-阿里云开发者社区

在浏览器中直接运行 AI 配音模型，可以避免把用户的文本、声音和项目素材上传到服务器，同时也能降低后端推理成本。

但将语音模型真正放进浏览器后，我们遇到了一个非常典型的问题：模型加载进度经常停在 86%，生成按钮一直显示“生成中”。中文偶尔可以使用，切换到英文、德语、韩语、泰语或日语后，失败概率却明显增加。

开发者控制台中最关键的错误是：

Unable to cache file QuotaExceededError: Quota exceeded.

QuotaExceededError:
The operation failed because it would cause the application
to exceed its storage quota.

这次修复并不只是调整一个进度数字，而是对浏览器端配音架构进行了一次完整治理，包括模型体积、运行时选择、缓存策略、国内外下载源、加载进度以及异常恢复。

项目地址：

https://github.com/MartinDelophy/ai-video-editor

在线体验：

https://video-editor.ai-creator.top/

一、为什么模型总是停在 86%

页面显示“86%”，并不意味着模型真的只剩下 14% 没有下载。

浏览器端模型通常需要经历下面几个阶段：

下载配置文件、词典和分词资源；
下载 ONNX 模型；
将文件写入 Cache Storage；
创建 ONNX Runtime 推理会话；
为 WebGPU 编译计算图；
执行第一次预热推理。

原来的进度计算只覆盖了部分下载过程。当模型已经下载完成，却在写入缓存或者创建推理会话时失败，界面就会永远停留在最后一次收到的进度，例如 86%。

因此，真正的问题不是“进度条卡住”，而是后续任务抛出异常后，状态机没有正常结束。

二、浏览器存储配额才是主要故障来源

浏览器中的 Cache Storage、IndexedDB 和 Service Worker 缓存，通常共享同一个站点存储配额。

项目使用了多套语音模型运行时：

中文主要使用 Piper；
英文使用 Kokoro；
部分欧洲语言使用 Piper；
韩语、越南语、俄语和泰语使用 MMS；
日语使用 Supertonic。

如果每一种语言都维护自己的缓存规则，用户切换几次语言后，浏览器中可能同时存在：

已经过期的模型；
同一文件的多个镜像副本；
不同量化版本的 ONNX 模型；
Service Worker 的响应缓存；
推理模块自己的资源缓存。

这些文件单独看都不算异常，但累积之后很容易触发 QuotaExceededError。

更隐蔽的问题是：如果同一个模型分别从国内镜像和海外镜像下载，而缓存键直接使用下载 URL，浏览器会把它们视为两个完全不同的文件。

也就是说，内容完全相同的模型可能被保存两次。

三、统一模型缓存身份

修复的关键之一，是将“模型的逻辑身份”和“模型的下载地址”分开。

错误的缓存方式类似：

const cacheKey = modelDownloadUrl;

这种方式会导致 ModelScope 和 Hugging Face 上的同一模型产生两份缓存。

调整后，每个模型使用稳定的逻辑标识：

const cacheIdentity = [
  modelFamily,
  modelRevision,
  language,
  voice,
  quantization
].join(":");

例如：

kokoro:revision-20260804:en:female:q8

无论文件最终来自 ModelScope 还是 Hugging Face，都写入同一个缓存身份。

这样既能支持国内外下载源切换，也能避免重复占用浏览器存储空间。

四、国内与海外使用不同下载源

浏览器本地推理并不代表完全不依赖网络。用户第一次使用某种语言时，仍然需要下载模型文件。

为了提高不同网络环境下的可用性，我们采用了双镜像方案：

中文界面和国内环境优先从 ModelScope 下载；
海外环境优先从 Hugging Face 下载；
主下载源失败后自动尝试备用源；
两个下载源共享同一份缓存身份；
模型地址固定到不可变版本，避免远程文件变化造成兼容问题。

简化后的加载逻辑如下：

async function loadVoiceArtifact(artifact: VoiceArtifact) {
   
  const cached = await readSharedVoiceCache(artifact.cacheIdentity);

  if (cached) {
   
    return cached;
  }

  for (const source of getPreferredSources()) {
   
    try {
   
      const file = await downloadArtifact(source, artifact);
      await writeSharedVoiceCache(artifact.cacheIdentity, file);
      return file;
    } catch (error) {
   
      reportSourceFailure(source, error);
    }
  }

  throw new VoiceModelUnavailableError();
}

这里还有一个重要的产品细节：不能把浏览器底层的 Failed to fetch 直接显示给用户。

用户需要看到的是可操作的信息，例如：

配音模型暂时无法下载，请检查网络后重试，系统已经自动尝试备用下载源。

五、避免超大模型挤爆缓存

英文配音原来使用的 Kokoro FP32 模型体积约为 325MB，并且优先创建 WebGPU 会话。

这种方案理论性能较强，但在真实浏览器环境中存在几个问题：

初次下载时间长；
Cache Storage 占用高；
WebGPU 图编译时间不可预测；
部分显卡驱动兼容性不稳定；
容易与其他语言模型争夺存储空间。

修复后，英文配音改为约 92MB 的 Q8 量化模型，并使用更稳定的 WASM 推理。

const session = await ort.InferenceSession.create(modelBuffer, {
   
  executionProviders: ["wasm"],
  graphOptimizationLevel: "all"
});

量化模型的体积下降后，首次加载速度和缓存成功率都有明显改善。

在视频编辑器场景中，配音推理通常不是持续高频任务。相比追求理论上的最高 GPU 性能，更重要的是：

用户第一次能成功生成；
再次使用时可以直接读取缓存；
切换语言后不会破坏已有模型；
中低配置设备也能稳定运行。

六、缓存不足时只清理过期资源

简单调用 caches.delete() 清空所有缓存虽然容易实现，但会导致用户重新下载刚刚使用过的模型。

因此，我们增加了模型缓存治理策略：

计算当前语言和音色所需的模型身份；
将正在使用的模型标记为受保护资源；
优先删除旧版本模型；
清理最近最少使用的其他语音模型；
保留应用静态资源和当前活跃模型；
重新尝试写入缓存；
如果仍然失败，允许在内存中继续完成本次推理。

伪代码如下：

async function ensureVoiceStorage(activeIdentity: string) {
   
  const estimate = await navigator.storage.estimate();

  if (!estimate.quota || !estimate.usage) {
   
    return;
  }

  const usageRatio = estimate.usage / estimate.quota;

  if (usageRatio < 0.8) {
   
    return;
  }

  await evictStaleVoiceModels({
   
    preserve: [activeIdentity],
    strategy: "least-recently-used"
  });
}

这样能够在不破坏用户当前任务的前提下，主动降低存储配额异常的概率。

七、进度条必须反映真实阶段

不同模型运行时能够提供的进度信息并不完全一致。

如果直接把所有资源数量平均分配，5KB 的配置文件和 90MB 的 ONNX 模型就会占用相同的进度比例，结果自然不准确。

我们调整为按模型字节数计算下载进度，并将加载过程拆成几个明确阶段：

检查本地缓存；
下载模型资源；
初始化推理运行时；
准备配音；
生成语音。

其中，下载阶段根据真实字节数更新：

const progress = loadedBytes / totalBytes;
onProgress(Math.round(progress * 100));

进入推理会话创建阶段后，不再假装仍然处于下载状态，而是切换提示文案：

正在初始化本地配音引擎

这样即使 WebGPU 编译或 WASM 初始化需要一定时间，用户也知道系统正在执行什么操作。

八、为什么需要先让浏览器完成一次渲染

即使状态已经更新，React 的界面也不一定会立刻显示。

如果设置“生成中”状态后马上执行同步或高负载 WASM 推理，浏览器主线程可能来不及绘制页面，用户看到的仍然是旧界面。

因此，在开始重任务前，我们主动让出一次渲染时机：

setGenerationState({
   
  status: "generating",
  progress: 0
});

await new Promise<void>((resolve) => {
   
  requestAnimationFrame(() => resolve());
});

await generateVoice();

这个改动看起来很小，但对于浏览器端 AI 应用非常重要。

用户先看到明确的状态反馈，然后模型才开始执行推理，可以显著减少“页面卡死”的感受。

九、Service Worker 不应该重复保存大模型

Service Worker 很适合缓存 JavaScript、CSS、图标和普通静态资源，但不适合在没有统一策略的情况下自动缓存大型 ONNX 文件。

如果模型加载模块已经缓存了一份响应，而 Service Worker 又克隆响应并再次写入自己的缓存，就可能产生两份大文件。

因此，我们对大型语音模型采用单一缓存责任：

模型管理器负责模型文件缓存；
Service Worker 不再重复缓存大型 ONNX 响应；
静态应用资源继续由 Service Worker 管理；
所有语音运行时共享统一的模型缓存清单。

这让缓存结构更加可预测，也更容易进行版本迁移和空间回收。

十、不同语言不应该强行使用同一套运行时

多语种配音系统并不是“一个模型加一个语言参数”这么简单。

不同模型在音色、体积、浏览器兼容性和推理速度方面各有特点。因此，本项目保留了多运行时架构：

语言类型	主要运行时	执行方式
中文	Piper	WebGPU 优先，WASM 回退
英文	Kokoro Q8	WASM
部分欧洲语言	Piper	WASM
韩语、泰语、越南语、俄语	MMS	WASM
日语	Supertonic	WASM

上层业务不直接关心模型内部实现，而是通过统一接口调用：

interface VoiceRuntime {
   
  prepare(options: VoiceOptions): Promise<void>;
  synthesize(text: string): Promise<AudioBuffer>;
  dispose(): Promise<void>;
}

这样新增语言时，只需要实现对应的运行时适配，不需要修改时间线、素材库和导出流程。

十一、修复后的验证结果

完成架构调整后，我们重点验证了以下场景：

英文首次加载和重复生成；
德语连续生成两次；
韩语本地推理；
泰语模型下载与合成；
日语 Supertonic 初始化；
中文模型国内外下载源切换；
浏览器缓存接近配额上限时的自动清理；
页面刷新后的模型缓存复用。

修复后，多语言模型均能正常完成加载和生成，重复生成不会再次显示完整模型下载过程，控制台中也不再出现未处理的 QuotaExceededError。

十二、这次修复带来的工程经验

这次问题说明，浏览器端 AI 应用不能只关注“模型能不能运行”，还需要把模型当成完整的产品资源进行管理。

需要重点关注：

模型文件是否固定到了不可变版本；
国内外下载源是否具有相同缓存身份；
Service Worker 是否重复缓存大文件；
浏览器配额不足时是否能够自动恢复；
进度条是否反映真实下载字节和执行阶段；
重任务开始前，界面是否获得了渲染机会；
WebGPU 不可用时，是否存在稳定的 WASM 回退；
切换语言后，旧模型是否会无限累积。

浏览器端 AI 的真正难点，往往不在某一次推理，而在下载、缓存、版本、运行时和交互状态能否长期稳定地协同工作。

总结

“模型卡在 86%”只是表面现象。

背后的真实问题是：

大模型重复缓存；
浏览器存储配额耗尽；
国内外镜像缓存身份不一致；
WebGPU 初始化异常缺少回退；
进度状态与真实执行阶段脱节；
主线程繁忙导致界面无法及时刷新。

通过引入量化模型、统一缓存身份、双镜像下载、缓存淘汰策略、WASM 回退和分阶段进度提示，我们最终让中文、英文、日语、韩语、泰语以及多种欧洲语言都能在浏览器中稳定完成本地配音。

如果你也在开发浏览器端 AI 应用，不妨把模型下载和缓存系统视为一项独立的基础设施。模型能够成功运行只是起点，能够在不同设备、网络和存储状态下稳定恢复，才是真正面向用户的实现。