• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本文解读 AIRI 文档中「桌面端本地语音识别（App (Local) ASR/STT）」的当前可用性状态：该服务商在设置页仍显示 Work in Progress 占位符，尚不能准备或启用任何本地模型。文章结合仓库源码给出实现层面的证据，并整理当前可直接使用的三条替代路径——macOS 原生 Apple Speech、Sherpaw 本地模型、浏览器 Web Speech API，以及云端转写服务商方案，帮助你在语音输入上快速落地。

一、结论先行：App (Local) 转写当前不可用

根据仓库文档 desktop-local.md，AIRI 桌面端的本地语音识别（App/Local 语音转写）目前不可用：

• 其 AIRI 设置页当前展示的是一个 Work in Progress 占位符；
• 因此无法在界面中准备（下载/安装）本地模型，也无法启用该服务商；
• 官方明确警告：不要把它用于需要正常工作的生产配置，该文档存在的唯一目的是把当前可用性说清楚，避免误解。

需要说明的是，仓库内的简体中文翻译版本（zh-Hans 版 desktop-local.md）仍保留了完整的配置流程描述（桌面版环境确认、选择模型、听觉模块启用、验证与排查）；但英文文档与源码中的设置页实现（<WIP />占位符）均表明该服务商尚未正式开放。请以应用内设置页实际显示的状态为准，本文的「不可用」结论以英文文档与源码为准。

二、源码证据：设置页 WIP 与 Provider 定义

「不可用」并非仅停留在文档层面，源码中可以找到完整证据链。

1. 设置页仅渲染 WIP 占位符

桌面端本地转写的设置页实现位于 app-local-audio-transcription.vue，其模板内容只有一行：

<template> <WIP /> </template>

WIP组件来自@proj-airi/stage-ui/components，即「开发中」占位页面。也就是说，用户进入设置 → 服务商 → 语音识别 → App (Local)后看到的只是占位提示，没有模型选择、语言配置或任何可操作的表单字段。同一目录下的浏览器版 browser-local-audio-transcription.vue 同样只渲染<WIP />。

2. Provider 定义：能力存在但界面缺失

服务商的注册定义在 local-audio/index.ts 中，providerAppLocalAudioTranscription的要点如下：

• id：app-local-audio-transcription，i18n 标题为「应用内（本地）」/「App (Local)」；
• tasks：speech-to-text、automatic-speech-recognition、asr、stt；
• capabilities：protocol: 'http'、generateOutput: true，且不支持流式输入/输出（streamInput: false、streamOutput: false）——这意味着它面向的是「一次性上传音频、返回完整文本」的 HTTP 转写形态；
• 可用性判定：isAvailableBy: isStageTamagotchi，即只有桌面端（Electron）主程序环境下才会出现在服务商列表中，网页版不会出现；
• 配置项：仅apiKey（可选）与baseUrl（必填，指向本地转写服务的 HTTP 端点），校验器在baseUrl为空时直接报错；
• 图标：i-lobe-icons:huggingface，暗示其底层依托 Hugging Face Candle 等本地推理方案。

从源码结构看，该 Provider 的「骨架」（注册、配置校验、Provider 工厂）已经就位，缺的是真正可用的设置页与模型生命周期管理，这与「设置页 WIP → 模型无法准备和启用」的文档描述完全吻合。

3. 浏览器版被显式隐藏

同文件中的浏览器版providerBrowserLocalAudioTranscription（local-audio/index.ts）更直接：isAvailableBy: () => false，代码注释明确写道——隐藏该服务商是为了「避免用户选中一个无法配置的选项」，并提到其设置页browser-local-audio-transcription.vue渲染<WIP />，对应 issue 跟踪中的相关条目。也就是说，本地转写（无论 App 端还是 Browser 端）目前都没有开放给用户。

三、从源码看「本地转写」服务商的真实分类

AIRI 的转写（Transcription，即语音转文字 ASR/STT）服务商目录中，本地类条目被划分为两种形态，可以从 settings.yaml 的分类描述中看到设计意图（该分类描述甚至直接以Whisper.cpp作为本地转写示例）：

值得注意的是：「App (Local) 不可用」并不等于「AIRI 没有本地转写」。仓库中还有两个真正落地、可开箱即用的本地转写服务商，它们才是当前推荐的本地方案。

四、当前真正可用的本地转写路径

路径 1：Apple Speech（macOS 原生离线转写）

Apple Speech 是 AIRI 桌面版在 macOS 上提供的设备端语音识别，注册定义见 apple-speech/index.ts：

• 无需 API Key（requiresCredentials: false），完全离线、设备端处理；
• 依赖macOS 26 或更高版本的系统能力（i18n 描述为On-device speech recognition on macOS 26 or later）；
• 支持流式转写（streamInput: true、streamOutput: true、protocol: 'native'），这是它区别于 App (Local) 的显著优势；
• 可配置项为Locale，例如en-US、zh-CN（i18n 字段定义），未配置时默认en-US；
• 音频输入按16 kHz 的 PCM16 单声道处理，VAD 流会被转换为 Float32 并泵入原生识别会话（apple-speech/index.ts）；
• 非 macOS 平台不会加载原生包，主进程返回 inactive 服务（主进程服务），因此该服务商只会出现在 macOS 的桌面版中。

配置方式：桌面版设置 → 服务商 → 语音识别 → Apple Speech，填写 Locale（如zh-CN），再到设置 → 听觉中选择该服务商与麦克风设备即可。

路径 2：Sherpaw（本地模型转写，无需 API Key）

Sherpaw 是 AIRI 的本地语音识别服务商，定义于 sherpaw-transcription/index.ts，同样无需 API Key：

• 配置项只有两个：Model（模型 ID，默认paraformer-zh-en）与Model language（按语言过滤模型列表）；
• 模型由宿主应用（Web/桌面）提供，分为bundled（打包进应用）与remote（运行时下载）两种来源，识别运行在Web Worker + WebAssembly中；
• 默认模型paraformer-zh-en面向中英双语；按 sherpaw-model-assets ADR 的记录，Paraformer、多语言 Zipformer 与 X-ASR INT8 三组模型在打包前合计约745 MB，桌面开发时全部预下载到仓库缓存，桌面发布构建通过SHERPAW_BUNDLE_MODELS=true将其打入安装包，Web 构建则在识别启动时按需下载；
• 从 ADR 的运行时说明可以推断：当前 Sherpaw 传输层在单次流式转写结束后会销毁 Worker 会话，尚未实现跨录制的模型内存复用，因此连续多次短语音输入时可能重复初始化。

配置方式：进入设置 → 服务商 → 语音识别 → Sherpaw，选择模型与语言过滤（界面语言会自动优先推荐对应模型），再到设置 → 听觉启用。

五、替代方案：Web Speech API（浏览器版）

如果你只是想快速试用语音输入，且使用 AIRI 网页版，Web Speech API 是配置成本最低的路径（详见 web-speech-api.md）：

• 无需任何 API Key，识别由浏览器内置能力完成；
• 仅限网页版：它不属于桌面版（Electron）环境，识别能力会因浏览器、网络环境与语言而异。

配置步骤：

1. 确认使用 AIRI 网页版，且当前浏览器支持 Web Speech API、允许麦克风权限；
2. 打开设置 → 服务商 → 语音识别 → Web Speech API；
3. 选择识别语言（Recognition Language），按需开启连续识别（Continuous Recognition）与显示中间结果（Show Interim Results）；
4. 前往设置 → 听觉，选择 Web Speech API 与音频输入设备；
5. 允许浏览器访问麦克风，进行一次短语音输入测试，确认转写文字出现在 AIRI 中。

排查提示：没有转写文字时，依次检查浏览器麦克风权限、所选输入设备与识别语言；若浏览器不支持该 API，请改用本地（Apple Speech / Sherpaw）或云端转写。

六、替代方案：云端转写服务商

若本地方案受硬件或平台限制，AIRI 也内置了多条云端转写路径，各自的服务商文档位于docs/content/en/docs/manual/config/providers/transcription/目录：

• OpenAI 兼容 API（ASR/STT）：openai.md，适用于任何实现 OpenAI 转写接口的服务（如自建 Whisper 服务）；
• Mimo：mimo.md；
• Comet API：comet-api.md；
• 阿里云 NLS：aliyun.md；
• 官方服务（Official）：official.md，需要登录并拥有足够配额。

统一的配置流程（出自 audio.md）：打开设置 → 服务商 → 语音识别，选择服务商并填入凭据 → 打开设置 → 听觉，选择已配置的服务商与模型 → 选择正确的麦克风，点击开始监听（Start Monitoring），说一句简短的话，确认文字出现在识别结果区域。

七、统一启用入口：听觉（Hearing）模块与麦克风权限

无论选择哪条转写路径，最终的「开关」都在设置 → 听觉（Hearing）模块：

1. 在听觉页面选择转写服务商（Apple Speech / Sherpaw / Web Speech API / 云端服务商）与模型；
2. 选择正确的音频输入设备（麦克风）；
3. 授予 AIRI（或浏览器）麦克风权限——桌面版需检查操作系统级权限，网页版需检查浏览器权限；
4. 点击开始监听并说一句短句，识别文本能正确显示即表示配置成功。

值得留意的是，AIRI 的转写与语音合成（TTS）是两条独立配置链路（分别对应「听觉」与「语音」模块），可以只启用其一，互不影响。

八、常见问题排查

结合 audio.md 与各服务商文档，最常见的失败场景与处理建议如下：

九、相关文档与资源

• 服务商可用性说明（本主题原始出处）：desktop-local.md
• 浏览器本地转写（同为 WIP）：browser-local.md
• Web Speech API 配置指南：web-speech-api.md
• 语音输入输出的总览配置：audio.md
• 公共配置说明（字段与校验规则）：common.md
• 本地转写 Provider 定义：local-audio/index.ts
• Apple Speech 桌面端实现：apple-speech/index.ts 与 主进程服务
• Sherpaw 本地模型转写：sherpaw-transcription/index.ts 与 模型资产生命周期 ADR

小结：App (Local) 桌面端本地语音识别在 AIRI 中仍处于 WIP 状态，不能用于正式配置；若希望「不上云」地使用语音转文字，请优先选择 Apple Speech（macOS 26+）或 Sherpaw 本地模型，网页版可搭配 Web Speech API，需要更多语言覆盖时再接入云端转写服务商。使用前请以设置页实际显示的服务商与状态为准。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手