跳到主要内容

语音转文本

语音转文本分为完成录音和实时流式两套接口。

完成录音​

所选 API 服务为 ctx.apiSpeechToText。DSH 的 speechToText 注册表启用时，本插件也会向其中注册该服务。若要通过 DSH 语音输入使用它，请保留该注册表，并选择 API 提供方而不是内置的 SenseVoice 提供方。DSH 的默认转录提供方只能选择其中一个。

const transcript = await ctx.apiSpeechToText.transcribe(
  {audio: wavBytes, language: 'zh'},
  signal,
)

结果包含文本、录音时长 audioSeconds 和请求耗时 inferenceSeconds。语言使用 auto 时不发送语言提示。OpenAI 兼容提供方将字节以 recording.wav 上传至 POST /audio/transcriptions。

实时流式转录​

只有所选提供方实现实时转录时，ctx.streamingSpeechToText 才存在，因此应使用可选注入。

const session = await ctx.streamingSpeechToText.startStreaming({
  language: 'zh',
  format: 'pcm16',
  signal,
})

for await (const event of session.events) {
  if (event.type === 'delta') showPartial(event.text)
  if (event.type === 'final') acceptTranscript(event.text)
  if (event.type === 'error') throw event.error
}

使用 session.append(chunk) 发送音频，调用 session.commit() 请求转录当前缓冲区，结束时调用 session.close()。

OpenAI 兼容实现使用 Realtime 转录 WebSocket。支持 pcm16（默认 24 kHz 单声道）、g711_ulaw 和 g711_alaw，还可传入词汇或风格 prompt 及会话模型覆盖。实时会话为长连接，不经过请求并发门控。

选择接口​

已有长度有限的完整录音，并且需要一个权威结果时，使用完成录音转写。它会经过共享并发门控，并报告录音时长和推理耗时。音频仍在到达时，若部分文本会改变交互，则使用实时转写。

两项服务有意分离。存在 apiSpeechToText 并不表示一定存在 streamingSpeechToText。使用方也不应通过反复上传不断增长的录音来模拟实时转写，除非产品明确接受这种行为。

实时会话生命周期​

按捕获顺序追加音频块，并保持与创建会话时声明的格式一致。delta 事件只适合作为临时 UI 状态；只有 final 事件应提交为完成的转录文本。即使异步迭代器随后关闭，使用方仍应显示或记录 error 事件。

在话语边界调用 commit()，要求提供方处理当前缓冲区。捕获结束时只调用一次 close()；所有者被释放时，通过传入的信号中止。由于实时会话不经过请求门控，调用方负责限制打开数量。

音频与语言边界​

提供方无关的文件接口只携带字节和语言提示，不会重采样或检查任意容器。请提供已配置端点所期望的编码。实时 PCM 的每个追加块都必须保持协商后的采样格式。只有在提供方自动检测优于已知语言提示时才使用 auto。