AIRI 本地语音合成实战：使用 Kokoro TTS 实现 WebGPU/WASM 端侧文字转语音

AIRI 本地语音合成实战使用 Kokoro TTS 实现 WebGPU/WASM 端侧文字转语音【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiKokoro 是 AIRI 内置的本地 TTSText-to-Speech语音合成方案基于 Kokoro-82M 模型在浏览器端直接完成推理无需云端 API Key语音数据不出设备。本文围绕 AIRI 官方 Kokoro 配置文档 的完整配置流程展开并结合仓库源码provider 定义、Web Worker 推理管线、适配器与测试深入讲解模型选择、音色管理、下载与验证、故障排查以及底层实现原理读完即可在 AIRI 中完成本地语音合成的全流程配置与排障。Kokoro 是什么为什么在 AIRI 中选择它KokoroKokoro-82M是一个轻量级开源 TTS 模型AIRI 将其作为本地模型集成模型文件在首次使用时下载到本机之后推理完全在本地运行。官方文档给出的选择理由是——如果你希望在本地处理语音内容并且设备满足模型运行条件可以选择 Kokorodocs/content/zh-Hans/docs/manual/config/providers/speech/kokoro.md。从源码中的 provider 定义可以确认其定位// packages/stage-ui/src/libs/providers/providers/kokoro-local/index.ts export const providerKokoroLocal defineProvider({ id: kokoro-local, name: Kokoro TTS, description: Local text-to-speech using Kokoro-82M., tasks: [text-to-speech], icon: i-lobe-icons:speaker, requiresCredentials: false, // 不需要任何 API Key ... })三个关键事实requiresCredentials: false—— 配置时不需要填写任何 API Key、Secret 或 Endpoint任务类型为text-to-speech—— 它被注册为语音合成TTS服务商而不是语音识别STT模型基座为 Kokoro-82M—— 推理时统一以kokoro-82m作为模型名ONNX 权重来自onnx-community/Kokoro-82M-v1.0-ONNX见 constants.ts。与云端 TTS 服务商不同Kokoro 的代价是占用本机的下载空间、内存和计算资源因此官方文档明确警告不要在设备资源不足时强行启用。第一步准备本地运行环境按照官方文档配置前需要完成环境准备在支持 WebGPU 的环境中打开 AIRI。Kokoro 优先使用 WebGPU 加速推理浏览器必须支持该 API首次使用等待模型下载完成。模型文件会在第一次使用时按所选量化版本下载到本地无需 API Key但会占用本机下载空间、内存和计算资源。若设备不支持 WebGPU也并非完全不可用仓库为 Kokoro 提供了webgpu与wasm两种运行平台WASM 路径可以在没有 WebGPU 的环境下降级运行详见后文底层原理。模型下载与默认选择模型并非只有一个版本而是按平台 × 量化精度拆分为 7 个可选模型constants.ts模型 ID名称运行平台量化方式中文描述来自 i18nfp16-webgpuFP16 (WebGPU)WebGPUfp16半精度需 WebGPU 且支持 fp16fp32-webgpuFP32 (WebGPU)WebGPUfp32基于 WebGPU 的全精度模型建议在支持的设备上使用fp32FP32 (WASM)WASMfp32全精度模型fp16FP16 (WASM)WASMfp16半精度量化q8Q8 (WASM)WASMq88-bit 量化q4Q4 (WASM)WASMq44-bit 量化q4f16Q4F16 (WASM)WASMq4f164-bit 量化 (FP16)设置页对模型选择给出的提示是较小的模型加载更快但质量可能略有下降settings.yaml对应 i18n 文案为settings.pages.providers.provider.kokoro-local.fields.field.model.description。默认模型由 WebGPU 能力自动决定getDefaultKokoroModel支持 WebGPU 且fp16 可用→ 默认fp16-webgpu性能与质量均衡支持 WebGPU 但fp16 不可用→ 默认fp32-webgpu不支持 WebGPU → 默认q4f16WASM 平台上体积最小的量化档加载最快。模型列表在 UI 上还会根据设备能力自动过滤fp16-webgpu仅在 WebGPU 与 fp16 都支持时出现kokoroModelsToModelInfo。第二步在 AIRI 中配置 Kokoro官方文档的配置路径为打开设置 → 服务商 → 语音合成 → Kokoro选择 AIRI 提供的可用 Kokoro 模型。对应的设置页面实现在 kokoro-local.vue页面行为可以完整印证文档描述页面挂载时自动探测 WebGPU通过getCachedWebGPUCapabilities()读取缓存的能力检测结果supported与fp16Supported两个标志并用它决定默认模型kokoro-local.vue自动拉取模型列表providersStore.fetchModelsForProvider(providerId)获取当前设备可用的模型选项以下拉框ComboboxSelect形式展示首次进入自动保存默认模型若配置中尚无 model会写入getDefaultKokoroModel()的返回值保证校验通过配置校验通过后自动加载模型validateProviderConfig→loadProviderModel→loadVoicesForProvider即选择模型后模型与音色列表会自动就绪切换模型自动重载页面 watch 模型变化切换后重新校验、重新加载模型并刷新音色列表kokoro-local.vue。provider 配置结构在源码中定义如下kokoro-local/index.tscreateProviderConfig: () { const capabilities getWebGpuState() return z.object({ model: z.string().default(getDefaultKokoroModel(capabilities.supported, capabilities.fp16Supported)), voiceId: z.string().default(), }) },即配置仅包含两个字段model模型 ID有默认值和voiceId音色 ID默认空。同时 provider 提供了listModels/listVoices/loadModel等额外方法供设置页与语音合成模块调用kokoro-local/index.ts。支持的多语言音色Kokoro 的音色与语言绑定provider 内部维护了语言代码映射kokoro-local/index.ts从源码可见支持以下语言语言代码语言语言代码语言en-usEnglish (US)frFrenchen-gbEnglish (UK)hiHindijaJapaneseitItalianzh-cnChinese (Mandarin)pt-brPortuguese (Brazil)esSpanish音色列表由 worker 在模型就绪后通过getVoices返回每个音色包含language、name、gender三个属性types.tsUI 上会拼接成音色名性别, 语言的形式展示例如测试代码中出现的af_heart音色键kokoro.test.ts。第三步验证配置官方文档的验证步骤选择模型和音色模型准备完成后选择音色再到设置 → 发声启用输入短文本试听能正常播放即表示模型已准备完成。其中设置 → 发声用于在 AIRI 的语音播报链路中启用 Kokoro 作为发声源。试听环节则由设置页内嵌的SpeechPlayground实验平台完成kokoro-local.vue默认试听文本是中文您好这是 Kokoro 文本转语音TTS系统的测试。i18n 文案settings.pages.providers.provider.kokoro-local.playground.default-text见 settings.yaml试听流程在源码中的实际调用链为kokoro-local.vueSpeechPlayground 输入文本 选中音色 → handleGenerateSpeech(input, voiceId) → providersStore.getProviderInstance(kokoro-local) // 获取 provider 实例 → speechStore.speech(provider, model, input, voiceId, config) → provider.speech().fetch() // 内部生成并返回 WAVprovider 的speech()实现值得注意——它模拟了 OpenAI 兼容的 TTS 接口kokoro-local/index.tsspeech: () ({ baseURL: http://kokoro-local/v1/, model: kokoro-82m, fetch: async (_input, init) { const body JSON.parse(init.body) as { input?: string, voice?: string } if (!body.voice) throw new Error(Voice parameter is required) const adapter await adapterPromise if (!(body.voice in adapter.getVoices())) throw new Error(Unknown Kokoro voice: ${body.voice}) const buffer await adapter.generate(body.input ?? , body.voice) return new Response(buffer, { status: 200, headers: { Content-Type: audio/wav }, }) }, }),请求体要求包含input文本与voice音色voice 必填且必须是模型已加载的音色集合中的合法值合成结果以WAV 格式返回Content-Type: audio/wav因此能正常播放即可确认链路通畅。底层原理Worker 推理管线与降级策略Kokoro 的推理不占用主线程而是在独立 Web Worker 中完成worker.ts。Worker 通过统一的推理协议与主线程通信支持四类消息load-model、run-inference、unload-model、cancelworker.ts。模型加载与精度降级链加载模型时worker 调用KokoroTTS.from_pretrained(MODEL_IDS.KOKORO, ...)并内置了两套降级链worker.ts// dtype 降级请求的精度不可用时依次尝试更低精度 const DTYPE_FALLBACK { fp16: [fp32, q8, q4], fp32: [q8, q4], q8: [q4, fp32], q4: [q4f16, fp32], q4f16: [q4, fp32], } // 设备降级WebGPU 失败时退回 WASM const DEVICE_FALLBACK { webgpu: [wasm], wasm: [], cpu: [], }加载时会按请求的 (dtype, device) → dtype 降级 → device 降级的顺序逐一尝试全部失败才报错成功时会通过model-ready消息回传实际生效的 dtype 与 deviceactualDtype/actualDevice供上层记录worker.ts。这意味着即使设备不支持所选的 WebGPU 精度档模型仍可能以更低精度或 WASM 方式成功加载页面无需用户手动干预。下载进度与取消机制下载过程中 worker 通过progress消息持续回报进度阶段、百分比、文件、已下载/总大小设置页据此更新推理状态worker.ts由于无法同步中断 transformers.js 的推理调用取消采用标记丢弃策略主线程发cancel消息后worker 把对应 requestId 记入cancelledRequestIds待结果返回时直接丢弃worker.ts生成结果以Float32Array 原始 PCM 采样率的形式通过postMessage的可转移对象transfer list直接传给主线程避免 WAV 编解码开销主线程侧再由toWav()编码为 WAVworker.ts、adapters/kokoro.ts。适配器状态机、资源协调与设备丢失恢复主线程侧的适配器createKokoroAdapter负责 Worker 生命周期管理adapters/kokoro.ts状态机idle → loading → ready → running异常进入error彻底放弃后进入terminated单例通过getKokoroAdapter()获取终态后下次访问自动重建adapters/kokoro.ts全局加载队列与 GPU 资源协调模型加载进入全局 load queue 串行化优先级LOAD_PRIORITY.TTS并依据MODEL_VRAM_ESTIMATES估算显存占用默认回退 165MB向 GPU 协调器申请分配令牌供其他模型按 LRU 做内存压力管理adapters/kokoro.tsWebGPU 设备丢失device loss恢复worker 崩溃被分类为DEVICE_LOST时计数deviceLossCount并上报 GPU 协调器超过阈值DEVICE_LOSS_WASM_THRESHOLD后后续加载自动从 webgpu提升为 wasm避免反复失败每次崩溃还会按退避延迟自动重启 worker最多MAX_RESTARTS次adapters/kokoro.ts超时保护模型加载与生成各有 120 秒超时KOKORO_LOAD/KOKORO_GENERATE见 constants.ts超时即抛错避免界面永久挂起取消不触发重启取消AbortError是调用方主动发起的生命周期行为不会计入 worker 故障、不会触发重启逻辑已加载模型保持可用kokoro.test.ts。上述行为均有单元测试覆盖包括单例恢复、设备丢失计数、取消信号透传、错误分类加载阶段LOAD_FAILED、推理阶段INFERENCE_FAILED等kokoro.test.ts。排查模型无法加载怎么办官方文档给出的排查思路是检查浏览器是否支持 WebGPU、设备资源是否充足并重新打开页面后等待下载完成。结合源码可以进一步细化确认 WebGPU 支持在浏览器地址栏访问chrome://gpu或运行navigator.gpu检查若返回undefined则不支持 WebGPU。此时应改选 WASM 平台的模型如q4f16或升级浏览器/开启硬件加速Chrome/Edge 需启用使用硬件加速确认 fp16 能力即使支持 WebGPU也可能不支持 fp16 着色器运算。AIRI 的能力检测会给出fp16Supported标志fp16-webgpu在该设备上会被自动过滤改用fp32-webgpu即可确认模型确实已就绪可在 Kokoro 设置页观察模型加载状态与下载进度首次使用需要完整下载 ONNX 权重网络慢时请耐心等待120 秒加载超时是单次上限可重新触发设备资源不足Kokoro 会占用下载空间、内存与计算资源资源不足时不要强行启用。若 WebGPU 反复出现设备丢失device lostAIRI 会自动降级到 WASM 重试重新打开页面WebGPU 上下文异常或 Worker 进入终态后重新打开设置页或重新加载 AIRI 页面会触发全新的模型加载流程观察错误信息加载/推理失败会以LOAD_FAILED/INFERENCE_FAILED等错误码分类上报protocol.ts可结合浏览器控制台查看具体失败原因。小结在 AIRI 中启用 Kokoro 本地语音合成的完整路径是确认设备支持 WebGPU或选择 WASM 模型→ 设置 → 服务商 → 语音合成 → Kokoro 选择模型 → 选择音色 → 设置 → 发声启用 → 输入短文本试听。全程无需 API Key模型首次使用时自动下载。底层由独立的 Web Worker 承担推理配合精度降级链、设备丢失恢复、全局加载队列与资源协调器使端侧 TTS 在资源受限设备上也能尽可能稳定运行。若希望进一步深入可阅读 provider 定义、模型常量、Worker 实现、适配器实现 及其单元测试。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考