AIRI 接入 CometAPI 语音识别(ASR/STT):从 API Key 配置到麦克风实时转写实战指南

原创2026-10-15 18:32:32763 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

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

  1. 登录 CometAPI 控制台,创建一个 API Key。
  2. 确认当前账户可以访问音频转写类模型(例如 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 有效且模型可枚举。

第三步:验证配置

  1. 确保 模型名称(Model Name) 中填写的是 CometAPI 模型目录中的精确模型 ID。
  2. 在配置页同一位置的 转写测试台(TranscriptionPlayground) 中,允许浏览器麦克风访问,录制一段短语音,确认页面返回文字。

测试台由 TranscriptionPlayground 组件承载,其提交逻辑调用 Hearing store 的 transcription() 方法,将录音文件以 json 格式提交(见 comet-api-transcription.vue 中的 handleGenerateTranscription)。

若页面顶部出现红色校验失败提示,可点击 "仍然继续"(Continue Anyway)强制保存,但建议先解决校验问题再继续,否则后续转写请求大概率失败。

注意:在服务商配置页测试成功,并不等于麦克风转写已启用。 测试台只是验证服务商连通性与模型可用性;要让语音真正进入对话流程,还需要完成第四步。

第四步:在"听觉"模块启用麦克风转写

  1. 打开 设置 → 模块(Modules)→ 听觉(Hearing)。
  2. 在服务商卡片中选择 CometAPI Transcription(模块页通过 moduleTranscriptionProvidersMetadata 列出所有已配置的转写服务商,见 packages/stage-pages/src/pages/settings/modules/hearing.vue)。
  3. 确认所选模型与第二步配置的 模型名称 一致。
  4. 选择麦克风输入设备,点击 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 不支持提示检查服务商响应。

相关文件速查

登录后查看全文
airi