AIRI 浏览器本地语音识别（Browser Local ASR/STT）配置指南：零云端 API Key 的本地转写方案-开发者社区

AIRI 浏览器本地语音识别（Browser Local ASR/STT）配置指南：零云端 API Key 的本地转写方案

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

导读

本文围绕 AIRI 网页版提供的Browser (Local)语音识别服务商，完整讲解其启用前置条件（WebGPU / 内存检测）、配置步骤、验证方法与故障排查，并结合仓库源码解析该服务商在卡片显示、模型加载与转写调用链上的底层实现。读完本文，你将掌握在网页版中不向第三方服务商发送音频、仅靠浏览器本地模型完成语音转文字的完整实战方案，并能自行判断设备是否满足运行条件。

为什么选择浏览器本地语音识别

AIRI 的 Browser (Local) 语音识别（ASR/STT）直接调用浏览器内的本地模型完成语音转写，不需要任何云端 API Key，也无需把音频上传到第三方服务商。如果你使用的是 AIRI 网页版，并且希望最大限度保护语音数据的隐私，这是最直接的选择。

需要注意一个关键前提：该服务商只在网页版中出现，桌面端不会显示。从源码可以看到，providerBrowserLocalAudioTranscription的可用性判断函数isBrowserAndMemoryEnough()第一行即排除了桌面端环境（isStageTamagotchi()返回 true 时直接返回 false），参见本地音频服务商定义。

第一步：确认浏览器环境

在 AIRI 网页版中，"Browser (Local)" 服务商卡片并非无条件显示，而是由运行时能力检测决定。满足以下任一条件，卡片才会出现：

浏览器支持 WebGPU；
浏览器不支持 WebGPU 时，设备物理内存至少为 8 GB。

这一判断逻辑对应源码中的isBrowserAndMemoryEnough()（local-audio/index.ts）：

async function isBrowserAndMemoryEnough() { if (isStageTamagotchi()) return false // 桌面端不提供该服务商 if (await isWebGPUSupported()) return true // WebGPU 可用，直接通过 if ('navigator' in globalThis && globalThis.navigator != null && 'deviceMemory' in globalThis.navigator && typeof globalThis.navigator.deviceMemory === 'number') { // The browser model needs at least 8 GB of system memory without WebGPU. return globalThis.navigator.deviceMemory >= 8 } return false }

其中的 WebGPU 检测并非简单布尔判断，而是由 WebGPU 能力检测模块统一封装：该模块基于gpuu/webgpu的check()结果，单例缓存检测结论，并提供 fp16 支持度、估算 VRAM、适配器厂商/架构信息等诊断字段；VRAM 估算按「用户覆盖值 >adapter.limits.maxBufferSize * 4启发式 > 0」的优先级解析，相关行为均有对应的单测覆盖，见 detect.test.ts。

设备兼容性警告：本地模型运行会占用设备资源（CPU/内存/GPU）。若服务商卡片未出现，或出现后识别无法启动，请改用Web Speech API、云端 ASR，或桌面端本地方案。其中 Web Speech API 同样是浏览器内的转写方案（基于浏览器原生SpeechRecognition，无需 API Key），其可用性判断与配置在 browser-web-speech-api 服务商定义中可以看到：仅当window存在且包含webkitSpeechRecognition或SpeechRecognition时才可用。

第二步：在 AIRI 中配置

配置入口为网页版设置界面：

打开设置 → 服务商 → 语音识别 → Browser (Local)；
等待模型准备完成（本地模型首次加载需要下载并初始化），然后选择要使用的模型；
前往设置 → 听觉中启用该服务商作为转写来源。

服务商配置项说明

从服务商定义看，Browser (Local) 语音识别（以及同族的语音合成服务商）共用同一个配置 Schema（local-audio/index.ts）：

配置项	类型	默认值	说明
`apiKey`	string	可选	密码框输入，本地方案通常无需填写，留空即可
`baseUrl`	string	`''`	本地服务端点地址；留空时使用默认端点

baseUrl在创建 provider 前会被normalizeBaseUrl()规范化：先trim()去除首尾空白，再保证以/结尾，最终通过createOpenAI()构造兼容 OpenAI 协议的服务端（local-audio/index.ts）。配置校验器会强制要求baseUrl非空，若为空会提示"Base URL is required"——在正常 UI 流程中该值由系统自动填充，出现该报错通常意味着内部缺陷。

能力特征

源码中声明了该服务商在转写任务上的能力矩阵（local-audio/index.ts）：

协议：http；
生成输出（generateOutput）：支持；
流式输出 / 流式输入：均不支持（streamOutput: false、streamInput: false），即它属于一次性提交音频、返回完整转写结果的模式，而非边说话边出字的连续流式转写。若你需要实时流式转写，应优先考虑 Web Speech API（其能力矩阵中streamOutput与streamInput均为 true，见 browser-web-speech-api/index.ts）。

第三步：验证配置

完成配置后按以下步骤验证链路是否打通：

在网页版中允许浏览器访问麦克风（浏览器会弹出权限请求，须点允许）；
说一段短语音；
若转写文字能够显示，即表示配置成功。

麦克风采集与转写触发走的是 AIRI 的听觉（hearing）模块。从听觉状态模块的调用链可以看到，转写前音频会被编码为 PCM16（toPCM16FromFloat32），再交给所选服务商执行generateTranscription/ 流式转写；浏览器端常见的Failed to fetch/Load failed错误会被统一重写为带排查提示的文案，指引用户去浏览器控制台的 Network 面板查看 CORS、网络超时、DNS 等真实原因（hearing.ts）。

排查指南

现象	排查方向
服务商卡片未出现	确认当前使用的是网页版而非桌面端；确认浏览器支持 WebGPU，或设备内存 ≥ 8 GB（可访问`chrome://gpu`或`about:gpu`查看 WebGPU 状态）
卡片出现但识别无法启动	检查浏览器麦克风权限是否被拒绝；确认模型是否已加载完成
转写请求报错	打开浏览器开发者工具 Network 面板，结合`Failed to fetch`提示定位 CORS、网络超时、DNS 等具体原因
需要实时流式转写	该服务商不支持流式输入/输出，请改用 Web Speech API 或云端 ASR 方案

小结

AIRI 的 Browser (Local) 语音识别为网页版用户提供了一条无 API Key、音频不出设备的转写路径：WebGPU 或 8 GB 以上内存是卡片显示的门槛，模型加载完成后即可在「设置 → 听觉」中启用。其底层实现由服务商注册表（registry.ts）驱动能力检测与配置校验，WebGPU 检测结论在 stage-shared/webgpu 中集中缓存复用。需要连续流式转写或设备条件不足时，Web Speech API 与云端 ASR 是文档推荐的替代方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AIRI 浏览器本地语音识别（Browser Local ASR/STT）配置指南：零云端 API Key 的本地转写方案