AIRI 接入 OpenAI 兼容 ASR/STT 语音识别从配置到源码级验证【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南讲解如何在 AIRI 中接入 OpenAI 官方或任何提供 OpenAI 兼容转写接口的服务商实现语音识别ASR/STT能力把麦克风声音实时转换为文字。读完本文你将掌握 API Key 与 Base URL 的正确填写规则、模型 ID 的选取方法、在听觉模块中的验证流程以及从源码层面理解 AIRI 对 OpenAI 兼容转写请求的校验逻辑与常见排障手段。为什么选择 OpenAI 兼容 ASR/STTAIRI 的语音识别Speech-to-Text / ASR / STT模块支持多种服务商接入方式其中OpenAI 兼容 API是为明确实现了 OpenAI 转写接口Transcription API的服务商准备的统一接入通道。也就是说只要你的服务商对外提供 OpenAI 格式的转写端点就可以复用同一条配置路径接入 AIRI。需要注意的是兼容性并不由表象决定——仅 API 地址以/v1结尾或密钥以sk-开头不能保证服务真正兼容。判断依据应当是服务商文档中是否明确声明支持 OpenAI 的转写audio/transcriptions接口以及你填入的模型 ID 是否真实存在于该服务。如果你使用的是官方 OpenAI 服务可参考官方转写服务说明如果你需要的是阿里云实时识别等非 OpenAI 协议的服务请参考阿里云 NLS、浏览器本地识别 或 Web Speech API 等页面。语音识别ASR与语音合成TTS是相互独立的只配置 ASR 即可使用语音输入不影响文字回复功能参见配置语音输入与输出。第一步获取 API Key登录所选服务商的管理控制台。在API 密钥或开发者设置页面创建 API Key。复制密钥并妥善保存到本地密码管理器。⚠️API Key 安全不要把 API Key 提交到代码仓库、放进截图或发送给任何人。密钥一旦泄露请立即在服务商控制台撤销它并创建新密钥。AIRI 的凭据保存在当前设备本地设置中切勿在日志、Issue 或聊天记录中公开见通用配置说明。第二步在 AIRI 中配置服务商打开设置 → 服务商 → 语音识别。根据你的服务商选择入口官方 OpenAI选择单独的OpenAI服务商AIRI 会自动填入默认 Base URLhttps://api.openai.com/v1/其他兼容服务选择OpenAI 兼容 API该入口没有默认 Base URL需要手动填写服务商文档提供的 API 根地址。填写 API Key 与要使用的 ASR/STT 模型 ID。等待 AIRI 完成配置验证通过后即可在听觉模块中选用。关键字段速查字段含义填写建议API Key服务商签发的访问令牌直接粘贴完整密钥不要加引号、空格或换行。Base URL服务商 API 的根地址官方 OpenAI 保留默认值兼容服务填写完整的https://或http://地址必须以/结尾。模型语音识别使用的模型 ID官方 OpenAI 可直接从列表选择兼容服务优先从列表选择加载失败时按服务商文档手动填写。Base URL 与模型 ID 的源码级约束在 provider-inference 的 OpenAI 音频服务商实现 中可以清楚看到这两种服务商在配置层面的差异官方 OpenAI 的配置 Schema 将 Base URL 默认值写死为https://api.openai.com/v1/源码中的OPENAI_BASE_URL常量OpenAI 兼容服务的 Base URL 默认值为空字符串必须由用户填写两个 Schema 都要求apiKey为必填字段。配置校验逻辑createAudioValidators会依次检查API Key 是否为空——为空直接报 API Key is requiredBase URL 是否为空——为空报 Base URL is required.Base URL 是否为绝对地址——必须携带http://或https://协议头否则报错Base URL 是否以/结尾——必须带尾部斜杠否则报 Base URL must end with a trailing slash (/).此外normalizeBaseUrl会先trim去除首尾空白再在末尾缺少斜杠时自动补上/。因此即使你在界面里少写了尾部斜杠运行时也会被规范化处理——但校验环节仍会提醒你正确的书写格式。支持的转写模型官方 OpenAI 服务商的可用模型是静态维护的清单源码中openAITranscriptionModels数组因为 OpenAI 并不提供转写模型的列表接口。当前内置的模型包括模型 ID说明whisper-1基于开源 Whisper V2 模型的经典转写模型gpt-4o-transcribe高质量转写模型gpt-4o-mini-transcribe更快、成本更低的转写模型gpt-4o-mini-transcribe-2025-12-15GPT-4o Mini Transcribe 的快照版本gpt-4o-transcribe-diarize支持说话人分离diarization的转写模型在服务商设置页面openai-audio-transcription.vue中默认模型为whisper-1。而对于 OpenAI 兼容服务商openai-compatible-audio-transcription.vue 内置了一份相同的VALID_TRANSCRIPTION_MODELS清单用于校验并且有一条重要的防呆规则凡是包含gpt-4字样、但不包含transcribe或whisper的模型名典型的如gpt-4o、gpt-4o-mini聊天模型会被直接判定为非法转写模型检测到非法模型时页面会自动将模型重置为默认的whisper-1。从源码结构看OpenAI 兼容服务商的模型列表接口listModels返回空数组因为兼容服务的/v1/models端点不保证能可靠返回转写模型信息。因此当你使用兼容服务时大概率需要手动输入模型 ID并确保它与服务商文档一致。第三步在听觉模块验证配置完成服务商配置后进入设置 → 听觉验证识别链路在听觉中选择已配置的服务商和模型。选择正确的音频输入设备麦克风。点击开始监听然后对着麦克风说话或播放一段音频。在转写区域确认文字能实时输出识别结果不准确时可调整灵敏度后再次测试。在源码中这一流程由 hearing.ts 状态模块 驱动它同时支持文件转写generate模式与麦克风流式转写stream模式并通过 VAD语音活动检测决定何时把音频片段送入转写接口。服务商设置页内的Transcription Playground测试区会调用hearingStore.transcription()对上传的音频文件执行一次真实转写方便你在接入听觉前先验证凭据与模型是否有效。排查指南没有文字结果时按以下顺序排查麦克风权限确认系统已授予 AIRI 麦克风权限。浏览器环境下麦克风权限被撤销、页面权限被重置都会导致结果为空参考配置语音输入与输出 的常见问题一节。网络层错误在 hearing.ts 的错误处理中浏览器常把 CORS、超时、DNS 解析失败统一包装为Failed to fetch/Load failed。看到这类报错时打开浏览器开发者工具的Network 面板查看具体原因CORS 跨域、网络超时、DNS 失败等。服务商兼容性确认兼容服务确实实现了 OpenAI 转写接口并且你填写的模型 ID 在该服务上真实可用不要把聊天模型的 ID 填入语音识别gpt-4o等模型会被 AIRI 直接拒绝。Base URL 格式与服务商官方文档逐字核对确保是完整的https://绝对地址且以/结尾若配置了代理或防火墙确认其放行了该服务商域名。额度与状态确认账户已开通对应服务且有可用额度API Key 没有复制多余的空格或换行详见通用配置说明 的验证结果一节。另外需要说明的是流式转写会话因用户主动停止监听、页面销毁音频交互或空闲超时而结束时会以AbortError作为预期的控制流信号这类错误不会被当作服务商故障上报——如果你在日志中看到Stopped/Aborted/Closed/Idle timeout等消息属于正常停止路径无需排查。延伸阅读通用配置说明API Key、Base URL 与验证流程的通用语义配置语音输入与输出TTS 与 ASR 的完整配置流程及常见问题官方 OpenAI 转写服务说明阿里云 NLS 与其他语音识别服务商文档源码OpenAI 音频服务商定义见 openai-audio/index.ts设置页见 openai-compatible-audio-transcription.vue 与 openai-audio-transcription.vue运行时状态见 hearing.ts【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AIRI 接入 OpenAI 兼容 ASR/STT 语音识别：从配置到源码级验证
AIRI 接入 OpenAI 兼容 ASR/STT 语音识别从配置到源码级验证【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南讲解如何在 AIRI 中接入 OpenAI 官方或任何提供 OpenAI 兼容转写接口的服务商实现语音识别ASR/STT能力把麦克风声音实时转换为文字。读完本文你将掌握 API Key 与 Base URL 的正确填写规则、模型 ID 的选取方法、在听觉模块中的验证流程以及从源码层面理解 AIRI 对 OpenAI 兼容转写请求的校验逻辑与常见排障手段。为什么选择 OpenAI 兼容 ASR/STTAIRI 的语音识别Speech-to-Text / ASR / STT模块支持多种服务商接入方式其中OpenAI 兼容 API是为明确实现了 OpenAI 转写接口Transcription API的服务商准备的统一接入通道。也就是说只要你的服务商对外提供 OpenAI 格式的转写端点就可以复用同一条配置路径接入 AIRI。需要注意的是兼容性并不由表象决定——仅 API 地址以/v1结尾或密钥以sk-开头不能保证服务真正兼容。判断依据应当是服务商文档中是否明确声明支持 OpenAI 的转写audio/transcriptions接口以及你填入的模型 ID 是否真实存在于该服务。如果你使用的是官方 OpenAI 服务可参考官方转写服务说明如果你需要的是阿里云实时识别等非 OpenAI 协议的服务请参考阿里云 NLS、浏览器本地识别 或 Web Speech API 等页面。语音识别ASR与语音合成TTS是相互独立的只配置 ASR 即可使用语音输入不影响文字回复功能参见配置语音输入与输出。第一步获取 API Key登录所选服务商的管理控制台。在API 密钥或开发者设置页面创建 API Key。复制密钥并妥善保存到本地密码管理器。⚠️API Key 安全不要把 API Key 提交到代码仓库、放进截图或发送给任何人。密钥一旦泄露请立即在服务商控制台撤销它并创建新密钥。AIRI 的凭据保存在当前设备本地设置中切勿在日志、Issue 或聊天记录中公开见通用配置说明。第二步在 AIRI 中配置服务商打开设置 → 服务商 → 语音识别。根据你的服务商选择入口官方 OpenAI选择单独的OpenAI服务商AIRI 会自动填入默认 Base URLhttps://api.openai.com/v1/其他兼容服务选择OpenAI 兼容 API该入口没有默认 Base URL需要手动填写服务商文档提供的 API 根地址。填写 API Key 与要使用的 ASR/STT 模型 ID。等待 AIRI 完成配置验证通过后即可在听觉模块中选用。关键字段速查字段含义填写建议API Key服务商签发的访问令牌直接粘贴完整密钥不要加引号、空格或换行。Base URL服务商 API 的根地址官方 OpenAI 保留默认值兼容服务填写完整的https://或http://地址必须以/结尾。模型语音识别使用的模型 ID官方 OpenAI 可直接从列表选择兼容服务优先从列表选择加载失败时按服务商文档手动填写。Base URL 与模型 ID 的源码级约束在 provider-inference 的 OpenAI 音频服务商实现 中可以清楚看到这两种服务商在配置层面的差异官方 OpenAI 的配置 Schema 将 Base URL 默认值写死为https://api.openai.com/v1/源码中的OPENAI_BASE_URL常量OpenAI 兼容服务的 Base URL 默认值为空字符串必须由用户填写两个 Schema 都要求apiKey为必填字段。配置校验逻辑createAudioValidators会依次检查API Key 是否为空——为空直接报 API Key is requiredBase URL 是否为空——为空报 Base URL is required.Base URL 是否为绝对地址——必须携带http://或https://协议头否则报错Base URL 是否以/结尾——必须带尾部斜杠否则报 Base URL must end with a trailing slash (/).此外normalizeBaseUrl会先trim去除首尾空白再在末尾缺少斜杠时自动补上/。因此即使你在界面里少写了尾部斜杠运行时也会被规范化处理——但校验环节仍会提醒你正确的书写格式。支持的转写模型官方 OpenAI 服务商的可用模型是静态维护的清单源码中openAITranscriptionModels数组因为 OpenAI 并不提供转写模型的列表接口。当前内置的模型包括模型 ID说明whisper-1基于开源 Whisper V2 模型的经典转写模型gpt-4o-transcribe高质量转写模型gpt-4o-mini-transcribe更快、成本更低的转写模型gpt-4o-mini-transcribe-2025-12-15GPT-4o Mini Transcribe 的快照版本gpt-4o-transcribe-diarize支持说话人分离diarization的转写模型在服务商设置页面openai-audio-transcription.vue中默认模型为whisper-1。而对于 OpenAI 兼容服务商openai-compatible-audio-transcription.vue 内置了一份相同的VALID_TRANSCRIPTION_MODELS清单用于校验并且有一条重要的防呆规则凡是包含gpt-4字样、但不包含transcribe或whisper的模型名典型的如gpt-4o、gpt-4o-mini聊天模型会被直接判定为非法转写模型检测到非法模型时页面会自动将模型重置为默认的whisper-1。从源码结构看OpenAI 兼容服务商的模型列表接口listModels返回空数组因为兼容服务的/v1/models端点不保证能可靠返回转写模型信息。因此当你使用兼容服务时大概率需要手动输入模型 ID并确保它与服务商文档一致。第三步在听觉模块验证配置完成服务商配置后进入设置 → 听觉验证识别链路在听觉中选择已配置的服务商和模型。选择正确的音频输入设备麦克风。点击开始监听然后对着麦克风说话或播放一段音频。在转写区域确认文字能实时输出识别结果不准确时可调整灵敏度后再次测试。在源码中这一流程由 hearing.ts 状态模块 驱动它同时支持文件转写generate模式与麦克风流式转写stream模式并通过 VAD语音活动检测决定何时把音频片段送入转写接口。服务商设置页内的Transcription Playground测试区会调用hearingStore.transcription()对上传的音频文件执行一次真实转写方便你在接入听觉前先验证凭据与模型是否有效。排查指南没有文字结果时按以下顺序排查麦克风权限确认系统已授予 AIRI 麦克风权限。浏览器环境下麦克风权限被撤销、页面权限被重置都会导致结果为空参考配置语音输入与输出 的常见问题一节。网络层错误在 hearing.ts 的错误处理中浏览器常把 CORS、超时、DNS 解析失败统一包装为Failed to fetch/Load failed。看到这类报错时打开浏览器开发者工具的Network 面板查看具体原因CORS 跨域、网络超时、DNS 失败等。服务商兼容性确认兼容服务确实实现了 OpenAI 转写接口并且你填写的模型 ID 在该服务上真实可用不要把聊天模型的 ID 填入语音识别gpt-4o等模型会被 AIRI 直接拒绝。Base URL 格式与服务商官方文档逐字核对确保是完整的https://绝对地址且以/结尾若配置了代理或防火墙确认其放行了该服务商域名。额度与状态确认账户已开通对应服务且有可用额度API Key 没有复制多余的空格或换行详见通用配置说明 的验证结果一节。另外需要说明的是流式转写会话因用户主动停止监听、页面销毁音频交互或空闲超时而结束时会以AbortError作为预期的控制流信号这类错误不会被当作服务商故障上报——如果你在日志中看到Stopped/Aborted/Closed/Idle timeout等消息属于正常停止路径无需排查。延伸阅读通用配置说明API Key、Base URL 与验证流程的通用语义配置语音输入与输出TTS 与 ASR 的完整配置流程及常见问题官方 OpenAI 转写服务说明阿里云 NLS 与其他语音识别服务商文档源码OpenAI 音频服务商定义见 openai-audio/index.ts设置页见 openai-compatible-audio-transcription.vue 与 openai-audio-transcription.vue运行时状态见 hearing.ts【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考