plugin-asr-openai — OpenAI Whisper API 转写后端

包名: @aalis/plugin-asr-openai
源码: packages/plugin-asr-openai/src/index.ts

概述

语音识别（ASR）的 OpenAI Whisper API 提供者。插件向核心注册 asr 服务，实现只有一个 transcribe 方法：把音频附件封装为 multipart 表单，POST 到 baseUrl 下的 /audio/transcriptions，返回文本与可选的时间戳分段。凡实现 OpenAI 风格 /audio/transcriptions 协议的服务端（如 Groq、本地 ollama-asr 网关）均可经 baseUrl 接入。音频附件支持以下来源：base64 data URL、file:// 或绝对路径（经 process 服务读取）、http(s) URL（经 safeFetch 下载，超时 15 秒、体积上限 20 MiB，超时或超限直接抛错）、storage URI（经 storage 服务读取）。其它格式（含相对路径 data/...）直接抛错。

上传的文件名与类型取按内容判定的格式（util-file-signature，如 audio.mp3、audio/mpeg），不看来源的路径后缀、Content-Type 或 data URL 里写的类型：Whisper 接口按文件名的后缀认格式。接口接受 MP3、WAV、OGG、FLAC、M4A、MP4、WebM；别的格式（AMR、SILK 等）与认不出的，读出来就报「Whisper 接口不接受 <格式> 音频」，插件不做转码。

插件声明

definePlugin({
  name: '@aalis/plugin-asr-openai',
  displayName: 'OpenAI Whisper ASR',
  subsystem: 'media',
  provides: [asr],
  uses: {
    logger,
    config,
    provide,
    proc: optional(processService),
    storage: optional(storage),
  },
  apply(caps) { /* 见源码 */ },
})

配置

字段	类型	默认值	说明
apiKey	string	必填	API Key（secret）
baseUrl	string	'https://api.openai.com/v1'	Base URL
model	string	'whisper-1'	模型
timeoutMs	number	600000	请求超时 (ms)：整段上传+识别的上限，实际生效下限为 1000，更小的值按 1000 处理；与 http(s) 音频下载的 15 秒超时相互独立

apiKey 为必填：没填时插件激活失败，报「缺少配置项 apiKey」，WebUI 把它标成待配置，不注册服务；不使用本插件时应在插件管理中禁用。请求地址为 baseUrl（去除末尾斜杠）直接拼接 /audio/transcriptions，插件不会自动补版本前缀，因此 baseUrl 应写到版本前缀为止（例如 OpenAI 官方为 https://api.openai.com/v1）。登记 asr 服务时的优先级是插件里的常量 50（本地的 whisper.cpp 为 80，排在它前面），只作第一方提供者之间的默认先后，不可配置。转写由 media 调用，用哪个音频后端由 media 的 audio.prefer 定（处理器名为 asr:<插件实例 id>）：指定的处理器存在则直接采用，否则在统一音频池（含具备音频能力的 LLM）中取优先级最高者。服务偏好 servicePreferences.asr 只决定 asr 服务的当前提供者，在 media 的统一音频池里只在优先级相同时决胜。

相关

• 服务契约 @aalis/api-asr：services/asr.md
• 消费方 media 服务：services/media.md

配置校验

apiKey 的显式无效值、baseUrl 的错误类型、非法地址或带查询串或片段的地址（插件在它后面拼路径）会在服务注册前报配置错误。未填 apiKey 仍报缺失；timeoutMs 小于 1000 时仍夹到 1000 毫秒。