AIRI 桌面端本地语音识别（ASR/STT）配置指南：无需云端 API Key 的端侧转写实战-开发者社区

AIRI 桌面端本地语音识别（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 桌面版中专用的**本地语音识别（ASR/STT）**服务商——App (Local)——的完整配置流程、验证方法与故障排查思路。AIRI 桌面版（Electron 应用）允许你完全脱离云端转写服务，仅使用本机磁盘与计算资源完成语音到文本的转写，适合注重隐私、希望减少对云端 API 依赖的用户。读完本文，你将掌握在设置 → 服务商 → 语音识别中启用本地转写、在设置 → 听觉中接入听觉通道、以及通过短语音输入快速验证配置是否生效的完整闭环。

为什么选择桌面端本地语音识别

AIRI 的语音识别（语音转文字，STT/ASR）服务商分为云端与本地两类：云端服务商（如 OpenAI Whisper、Azure Speech 等）需要配置 API Key 并将音频上传至远端推理；而本地服务商则在本机完成模型加载与推理。

选择本地转写带来的直接收益包括：

无需云端 API Key：不产生按量计费的转写费用，也不依赖网络可达性；
隐私可控：语音数据不出设备，音频内容不经过任何第三方服务；
离线可用：模型就绪后，转写过程不依赖互联网。

作为代价，本地模型会占用本机磁盘空间与 CPU/GPU 等计算资源，转写延迟与设备性能直接相关。从源码结构看，本地音频服务商被集中定义在 local-audio 服务商注册表中，其中包括App (Local)与Browser (Local)两组，本文聚焦仅面向桌面版的App (Local)。

第一步：确认桌面端环境

在开始配置前，需要确认两个前提条件：

使用 AIRI 桌面版：App (Local)服务商不会出现在网页版中，仅在桌面版（macOS / Windows 的 Electron 客户端）可见；
设备资源充足：确保本机有足够的磁盘空间用于存放本地模型，并有足够的计算资源（CPU / GPU 与内存）支撑实时推理。

源码佐证：桌面版专属限制

从服务商注册实现可以清晰看到这一点：providerAppLocalAudioTranscription 与providerAppLocalAudioSpeech均通过isAvailableBy: isStageTamagotchi声明可用性条件。isStageTamagotchi来自@proj-airi/stage-shared，用于判断当前是否运行在 AIRI 桌面版（stage-tamagotchi）环境。因此：

在网页版中，该服务商的isAvailableBy校验不通过，服务商列表中不会出现；
在桌面版中，服务商才会被注册并展示。

这也解释了文档中“该服务商不会在网页版出现”这一行为背后的实现逻辑——它并非网络请求失败或隐藏菜单，而是可用性守卫在入口处直接拦截。

第二步：在 AIRI 中配置

配置分为两个阶段：先在服务商目录中完成App (Local)的添加，再在听觉设置中启用。

2.1 添加语音识别服务商

打开 AIRI 桌面版，进入设置 → 服务商 → 语音识别；
在服务商列表中找到App (Local)并添加；
选择可用模型，等待本地模型准备完成。

2.2 认识 App (Local) 服务商的配置项

从 local-audio 服务商实现可以看到，App (Local)的配置结构（zod schema）包含两个可选字段：

字段	类型	默认值	说明
`apiKey`	string（可选）	无	API Key，本地推理通常无需填写，可留空
`baseUrl`	string（可选）	`''`	本地服务地址；配置校验器要求其为非空值

其中baseUrl会被 normalizeBaseUrl 规范化处理：去除首尾空白，若末尾缺少/则自动补全。该服务商通过 createOpenAI 构建一个 OpenAI 兼容的本地推理端点，转写调用会被包装为支持额外参数的transcription方法。

在语音识别服务商目录中，语音识别（Transcription）类别的服务商负责将语音转为文字，用于“听觉”通道；语音合成（TTS）类别的服务商负责将文字转为语音。App (Local)同时提供两类任务：转写服务商声明的任务集合为['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt']，并且其转写能力被标记为generateOutput: true、streamOutput: false、streamInput: false，即一次性生成完整转写文本、不采用流式输出/输入模式。

2.3 在听觉设置中启用

完成模型准备后，进入设置 → 听觉；
将语音识别来源切换为已配置好的本地转写服务商并启用；
此时 AIRI 的听觉通道将使用本地模型处理麦克风捕获的音频。

需要说明的是，本文档描述的App (Local)依赖应用内集成的本地转写引擎；仓库中还存在另一条面向 macOS 的系统级本地转写路径：Apple Speech服务商（apple-speech-transcription）使用 macOS 26 及以上系统的内置语音识别能力，同样无需 API Key，见 Apple Speech 转写服务注册与 i18n 中的服务商描述。若你的运行平台是 macOS 26+，也可将其作为备选方案。

第三步：验证配置

配置完成后，通过一次真实语音输入验证整条链路：

授权麦克风：首次使用时允许 AIRI 使用系统麦克风（macOS 在“系统设置 → 隐私与安全性 → 麦克风”中管理，Windows 在“设置 → 隐私 → 麦克风”中管理）；
进行短语音输入：对 AIRI 说一段简短、清晰的语音；
检查识别结果：识别出的文字能显示在 AIRI 界面中，即表示配置成功。

从源码看验证链路

从源码结构可以推断，桌面版的听觉链路大致如下：

主进程：由 stage-tamagotchi 主进程入口通过依赖注入注册modules:apple-speech-transcription等服务，并将本地转写/语音相关模块纳入核心应用生命周期（见主进程模块依赖声明）；
渲染进程：听觉输入通道由 use-hearing-input-channel 等组合式函数管理，设置界面中的听觉配置组件见 controls-island-hearing-config.vue。

当你在界面中看到识别文字时，意味着“麦克风捕获 → 音频预处理 → 本地模型推理 → 转写文本回传 → 界面渲染”整条链路已全部打通。

排查

若配置后无法正常使用，可按下表逐一排查：

现象	可能原因	排查动作
服务商列表中没有 App (Local)	运行的不是桌面版	确认使用的是 AIRI 桌面版（网页版不提供该服务商）
模型准备失败	磁盘空间不足 / 设备资源不够	检查磁盘剩余空间与 CPU、内存占用，必要时清理空间后重试
无识别文字结果	麦克风权限未授予	检查系统设置中 AIRI 的麦克风权限，授权后重试

常见问题补充

权限问题：麦克风权限被系统拦截时，转写请求不会报出模型错误，而是静默地得不到任何文字结果——这是“没有文字结果”时最先应检查的项目；
资源问题：本地模型首次加载需要下载/解包模型文件并载入内存，首次耗时明显高于后续调用属正常现象；若磁盘过满，模型文件落盘失败会直接导致“模型准备失败”；
服务商缺失：该服务商由可用性守卫（isAvailableBy）控制展示，若当前为网页版，无论怎样刷新都无法看到它，请切换到桌面版。