AIRI 接入 CometAPI 语音识别(ASR/STT):从 API Key 配置到麦克风实时转写实战指南
AIRI 接入 CometAPI 语音识别(ASR/STT):从 API Key 配置到麦克风实时转写实战指南
本指南讲解如何在自托管 AI 伴侣项目 AIRI 中配置 CometAPI 音频转写(ASR/STT)服务:从获取 API Key、在服务商设置页填入参数、通过转写测试台验证,到在"听觉"模块中启用麦克风实时转写,全程覆盖配置路径与故障排查方法。读完本文,你将掌握 CometAPI 转写服务在 AIRI 中的完整接入流程,并了解其底层调用链(OpenAI 兼容转写接口、置信度过滤与自动发送机制),为后续接入其他 OpenAI 兼容转写服务打下基础。
为什么选择 CometAPI 作为语音识别服务
CometAPI 通过 OpenAI 兼容接口提供音频转写能力。如果你已经在 CometAPI 控制台中管理过模型与凭据,那么可以直接复用同一个 API Key 在 AIRI 中完成语音识别配置,无需额外注册或创建新的密钥体系——这正是接入成本最低的场景。
从仓库源码看,AIRI 将 CometAPI 拆分为三个服务商定义,分别覆盖不同任务:
comet-api:聊天(Chat)与模型列表;comet-api-speech:文本转语音(TTS);comet-api-transcription:语音转文本 / 自动语音识别(ASR/STT)。
三者共享同一份 API Key 与 Base URL 配置,定义位于 packages/provider-inference/src/providers/cloud/comet-api/index.ts,并在 packages/provider-inference/src/providers/index.ts 中统一注册。转写服务商的声明如下(tasks 明确标注了 speech-to-text、asr、stt):
export const providerCometAPITranscription = defineProvider<CometApiConfig, 'comet-api-transcription'>({
id: 'comet-api-transcription',
name: 'CometAPI Transcription',
tasks: ['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt'],
capabilities: {
transcription: { protocol: 'http', generateOutput: true, streamOutput: false, streamInput: false },
},
// ...
validators: createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.ModelList] }),
})
注意 capabilities.transcription 中的关键信息:CometAPI 转写采用 HTTP 协议、一次性生成输出(generateOutput),不支持流式输出(streamOutput: false)也不支持流式输入(streamInput: false)。这意味着 AIRI 需要先录制完一段音频再整段提交转写,而不是边说话边出文字。这一点会在下文"听觉"模块的置信度阈值设置中体现。
第一步:获取 API Key
- 登录 CometAPI 控制台,创建一个 API Key。
- 确认当前账户可以访问音频转写类模型(例如 Whisper 系列),随后复制密钥并妥善保存。
API Key 安全警告:不要将 API Key 提交到代码仓库、不要出现在截图或日志中,也不要分享给任何人。AIRI 设置页中的 API Key 输入框使用
type: 'password'的掩码输入(见 packages/provider-inference/src/providers/cloud/comet-api/index.ts 中createProviderConfig对apiKey的meta.type: 'password'声明),请在界面上同样注意保密。
第二步:在 AIRI 中配置转写服务商
打开 设置 → 服务商(Providers)→ 语音识别(Transcription)→ CometAPI Transcription,进入配置页。该页面由 packages/stage-pages/src/pages/settings/providers/transcription/comet-api-transcription.vue 实现,包含三个配置区域:
基础设置(Basic Settings)
- API Key:粘贴第一步获取的密钥,占位符默认为
sk-...。 - 模型名称(Model Name):填写 CometAPI 模型目录中的精确模型 ID,例如
whisper-1(Hearing 模块的占位提示中也给出了whisper-1、gpt-4o-transcribe这类参考值)。模型 ID 必须与 CometAPI 目录中完全一致,否则验证阶段会失败。
高级设置(Advanced Settings)
- Base URL:保持默认值
https://api.cometapi.com/v1/。仅当使用代理或兼容网关时才需要修改。该默认值同时硬编码在服务商定义的配置 schema 中(z.string('Base URL').optional().default('https://api.cometapi.com/v1/'))与设置页输入框的占位符中,两者保持一致。
配置项的底层实现
服务商配置 schema 中只有两个字段:
const cometApiConfigSchema = z.object({
apiKey: z.string('API Key'),
baseUrl: z.string('Base URL').optional().default('https://api.cometapi.com/v1/'),
})
当创建转写 Provider 实例时,AIRI 会同时装配模型提供器与转写提供器,并把额外选项合并进转写请求:
createProvider(config) {
const provider = merge(
createModelProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }),
createTranscriptionProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }),
)
const transcription = provider.transcription.bind(provider)
provider.transcription = (model, extraOptions) => ({ ...transcription(model), ...extraOptions })
return provider
}
extraOptions 的合并机制为 Hearing 模块按需注入 language、prompt 等转写参数预留了通道。另外,服务商还通过 OpenAI 兼容校验器做 ModelList(模型列表) 校验,即验证阶段会实际请求 CometAPI 的模型目录接口,确认 Key 有效且模型可枚举。
第三步:验证配置
- 确保 模型名称(Model Name) 中填写的是 CometAPI 模型目录中的精确模型 ID。
- 在配置页同一位置的 转写测试台(TranscriptionPlayground) 中,允许浏览器麦克风访问,录制一段短语音,确认页面返回文字。
测试台由 TranscriptionPlayground 组件承载,其提交逻辑调用 Hearing store 的 transcription() 方法,将录音文件以 json 格式提交(见 comet-api-transcription.vue 中的 handleGenerateTranscription)。
若页面顶部出现红色校验失败提示,可点击 "仍然继续"(Continue Anyway)强制保存,但建议先解决校验问题再继续,否则后续转写请求大概率失败。
注意:在服务商配置页测试成功,并不等于麦克风转写已启用。 测试台只是验证服务商连通性与模型可用性;要让语音真正进入对话流程,还需要完成第四步。
第四步:在"听觉"模块启用麦克风转写
- 打开 设置 → 模块(Modules)→ 听觉(Hearing)。
- 在服务商卡片中选择 CometAPI Transcription(模块页通过
moduleTranscriptionProvidersMetadata列出所有已配置的转写服务商,见 packages/stage-pages/src/pages/settings/modules/hearing.vue)。 - 确认所选模型与第二步配置的 模型名称 一致。
- 选择麦克风输入设备,点击 Start 开始监听,运行 Hearing 测试(该测试会显示实时音量电平、VAD 语音概率曲线与转写文本)。
听觉模块的转写链路
从源码看,实时转写由 packages/stage-ui/src/stores/modules/hearing.ts 的 Hearing store 驱动。关键流程如下:
- 录音编码:麦克风流被编码为 16kHz 单声道 WAV(
encodeWav(audio, { sampleRate: 16000, channels: 1 })),随后通过generateTranscription(来自@xsai/generate-transcription)以 multipart 文件方式提交给 CometAPI 转写接口。 - 模型解析:
resolveActiveTranscriptionModel优先使用 Hearing 模块当前选中的模型,其次回退到服务商配置中的model字段。 - 语言与提示词:
resolveTranscriptionProviderOptions会从服务商配置读取language/prompt,未配置时自动取当前 UI 语言(如zh-Hans→zh)作为转写语言提示,降低多语言自动检测的漂移概率。 - 置信度过滤(可选):Hearing 模块提供"置信度阈值"滑块(范围
-3(禁用)到0,步长 0.1)。启用后,转写请求会改用verbose_json响应格式,并按avg_logprob过滤低置信度片段(filterTranscriptionByConfidence)。由于 CometAPI 转写为一次性生成模式,该阈值设置正是为这类"非流式转写"服务商准备的。 - 自动发送(Auto-send):开启后,转写文本会在延迟(默认 2000ms,可设 0–10000ms)后自动发送到聊天;关闭则可在发送前人工校对编辑。注意自动发送会消耗 Token。
- 转述润色(Rephrase):可选将转写文本交给聊天模型重新组织后再发送,默认关闭,且空的服务商值表示复用意识模块的聊天模型。
代码路径中的任务能力声明
comet-api-transcription 被列入"已定义服务商"清单并由测试断言,见 packages/stage-ui/src/libs/providers/providers/provider-definitions.test.ts。i18n 中其显示名为 "Comet API"、描述 "CometAPI.com",见 packages/i18n/src/locales/en/settings.yaml。
故障排查
测试台无法完成请求
- 检查 API Key 是否正确粘贴(留意是否有复制了前后空格或换行);
- 检查 账户权限:确认账户已开通音频转写模型的访问权限;
- 检查 网络连接:能否正常访问
https://api.cometapi.com/v1/,是否需要为 Base URL 配置代理或兼容网关。
测试台返回了文字,但麦克风没有转写结果
- 确认已在 设置 → 模块 → 听觉 中选择了 CometAPI 转写服务商,且模型与配置页一致——仅在服务商页测试成功不会启用麦克风转写;
- 确认 AIRI 已获得系统麦克风权限(浏览器地址栏旁的权限提示),并在 Hearing 模块中选对了音频输入设备;
- 若开启了置信度阈值过滤但没有文字输出,尝试将阈值调回"禁用"(-3),或参考 Hearing 页面的 verbose-json 不支持提示检查服务商响应。
相关文件速查
- 服务商定义与默认配置:packages/provider-inference/src/providers/cloud/comet-api/index.ts
- 服务商注册表:packages/provider-inference/src/providers/index.ts
- 转写服务商设置页:packages/stage-pages/src/pages/settings/providers/transcription/comet-api-transcription.vue
- 听觉模块设置页:packages/stage-pages/src/pages/settings/modules/hearing.vue
- 转写核心 Store(编码、提交、置信度过滤、自动发送):packages/stage-ui/src/stores/modules/hearing.ts
- 服务商定义测试:packages/stage-ui/src/libs/providers/providers/provider-definitions.test.ts