语音识别 (ASR) - Qualcomm Dragonwing Documentation

ASR 服务使用完全运行在 Qualcomm NPU 上的设备端模型将音频转写为文本。它同时支持基于文件的批量转写以及通过 WebSocket 的实时流式转写。

前置条件

请先部署并运行 Audio Analytics 容器。设置说明参见运行 Audio Analytics 容器。

音频格式要求

属性	要求
格式	仅支持 WAV
采样率	要求 16 kHz。如果您的音频采样率不同,请通过创建请求中的 `parameters` 声明。
声道	单声道(自动转换)
文件大小上限	25 MB

可用模型

查询 models 端点以获取可用 ASR 模型列表:

curl http://localhost:8085/audio-analytics/v1/api/transcriptions/models

响应:

[
  {
    "name": "whisper-small-quantized",
    "display_name": "Whisper Small (Quantized)",
    "description": "OpenAI whisper-small-quantized model for general transcription"
  }
]

在转写请求中使用该响应中的 name 值。

端点

方法	端点	描述
`GET`	`/transcriptions/models`	列出可用的 ASR 模型
`POST`	`/transcriptions/create`	转写一个文件或启动一个流式会话
`POST`	`/transcriptions/close`	关闭一个活动的流式会话
`POST`	`/transcriptions/flush`	立即处理已缓冲的音频

文件转写

上传一个 WAV 文件,并在单次响应中接收完整的转写结果:

curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -F "file=@recording.wav" \
  -F "model=whisper-small-quantized" \
  -F "language=en" \
  -F "stream=false"

响应:

{
  "text": "The transcribed text from your audio file.",
  "language": "en",
  "language_name": "English",
  "type": "transcript.text.done"
}

将 language 设置为模型支持的语言代码,或省略以进行自动检测。

文件转写并流式返回结果

上传完整的 WAV 文件,在文件处理过程中通过 WebSocket 实时接收转写结果:

curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -F "file=@recording.wav" \
  -F "model=whisper-small-quantized" \
  -F "language=en" \
  -F "stream=true"

服务器确认上传后开始处理。连接到 WebSocket 以接收结果。 WebSocket 结果:

{ "state": "connection_established" }
{ "type": "transcript.text.done", "text": "The transcribed text.", "language": "en", "language_name": "English", "state": "transcription" }

实时音频流

实时流式发送原始音频块,并在说话过程中接收转写结果。

第 1 步 —— 创建会话

如果您的音频不是 16 kHz 单声道 PCM,请通过 parameters 声明音频格式:

curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -H "Content-Type: application/json" \
  -d '{
    "model": "whisper-small-quantized",
    "language": "en",
    "stream": true,
    "vad": 1200,
    "parameters": [
      {"key": "sampling_rate", "value": "44100"},
      {"key": "channels", "value": "1"},
      {"key": "format", "value": "pcm_s16le"}
    ]
  }'

响应:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "asr_initialized",
  "text": "Successfully started Transcription Engine. Please connect to the WebSocket to send audio data & receive transcription output.",
  "language": "en",
  "type": "transcript.event"
}

vad 参数设置在判定语音结束之前的静音等待毫秒数。省略该参数将禁用 VAD,并需要通过 /transcriptions/flush 或 /transcriptions/close 手动管理话语结束。

第 2 步 —— 连接 WebSocket 并发送音频

连接到 ws://localhost:8085/stream。服务器会在任何转写消息到达之前先发送一条 connection_established 消息:

{ "state": "connection_established" }

通过 WebSocket 以 8192 字节的分块发送音频:

const ws = new WebSocket('ws://localhost:8085/stream');

ws.send(JSON.stringify({
  "message_type": "transcriptions_session_audio",
  "message_source": "audio_analytics_api",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "input_audio",
  "data": "<BASE64_ENCODED_PCM>"
}));

第 3 步 —— 接收结果

服务器针对每段话语按以下顺序发送消息:

{ "type": "transcript.event", "state": "speech_start", "session_id": "..." }
{ "type": "transcript.text.delta", "text": "Partial text...", "language": "en", "session_id": "..." }
{ "type": "transcript.event", "state": "speech_end", "session_id": "..." }
{ "type": "transcript.text.done", "text": "Complete utterance text.", "language": "en", "state": "transcription", "session_id": "..." }

在 transcript.text.done 之后,引擎会重置并监听下一段话语。会话会一直保持,直到您调用 /transcriptions/close。

第 4 步 —— 关闭会话

curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/close \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'

响应:

{
  "text": "",
  "language": null,
  "type": "asr_closed",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "asr_closed"
}

同一时间只能有一个活动的 ASR 会话。在已有会话活跃时启动第二个会话会返回 HTTP 409 Conflict。请先关闭现有会话。

语音活动检测 (VAD)

VAD 控制服务器在流式会话期间如何检测话语结束。当检测到的静音达到配置的时长时,服务器会针对当前话语发送 speech_end,然后是 transcript.text.done。会话本身保持打开状态并为下一段话语重置 —— VAD 不会关闭会话。

参数	描述
`vad`	触发 `speech_end` 之前的静音等待毫秒数。例如,`1200` = 1.2 秒静音触发话语结束。省略以禁用 VAD,并通过 `/transcriptions/flush` 或 `/transcriptions/close` 手动管理话语结束。

如果在容器配置中由 SESSION_TIMEOUT_S 设定的时长内(默认:30 秒)没有收到任何音频,会话会自动关闭,与 VAD 状态无关。

刷新已缓冲的音频

在不关闭会话的情况下,立即转写已缓冲的音频:

curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/flush \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'

Python 示例

import requests

def transcribe_file(audio_file, language=None):
    url = "http://localhost:8085/audio-analytics/v1/api/transcriptions/create"
    data = {
        "model": "whisper-small-quantized",
        "stream": "false"
    }
    if language:
        data["language"] = language
    with open(audio_file, "rb") as f:
        response = requests.post(url, files={"file": f}, data=data, timeout=60)
    response.raise_for_status()
    return response.json()["text"]

print(transcribe_file("sample.wav"))

故障排查

转写质量差: 请使用 16 kHz 单声道 WAV 文件,并确保音频清晰、背景噪声尽量少。

下一步

文本到语音

在设备端从文本合成语音

​前置条件

​音频格式要求

​可用模型

​端点

​文件转写

​文件转写并流式返回结果

​实时音频流

​第 1 步 —— 创建会话

​第 2 步 —— 连接 WebSocket 并发送音频

​第 3 步 —— 接收结果

​第 4 步 —— 关闭会话

​语音活动检测 (VAD)

​刷新已缓冲的音频

​Python 示例

​故障排查

​下一步

文本到语音

语言翻译

前置条件

音频格式要求

可用模型

端点

文件转写

文件转写并流式返回结果

实时音频流

第 1 步 —— 创建会话

第 2 步 —— 连接 WebSocket 并发送音频

第 3 步 —— 接收结果

第 4 步 —— 关闭会话

语音活动检测 (VAD)

刷新已缓冲的音频

Python 示例

故障排查

下一步