语音识别（ASR）

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

前提条件

确保 Audio Analytics 容器已部署并正在运行。有关设置说明，请参阅运行 Audio Analytics 容器。

音频格式要求

属性	要求
格式	仅限 WAV
采样率	需要 16 kHz。如果您的音频采样率不同，请在创建请求中通过 `parameters` 声明。
声道	单声道（自动转换）
最大文件大小	25 MB

可用模型

查询模型端点以获取可用 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 文件，并确保音频清晰、背景噪音最小。

后续步骤

文本转语音

在设备端将文本合成为语音

IQ-9075 EVK

前提条件

音频格式要求

可用模型

端点

文件转录

带流式结果的文件转录

实时音频流

第 1 步 - 创建会话

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

第 3 步 - 接收结果

第 4 步 - 关闭会话

语音活动检测（VAD）

冲刷缓冲的音频

Python 示例

故障排除

后续步骤

文本转语音

语言翻译

​前提条件

​音频格式要求

​可用模型

​端点

​文件转录

​带流式结果的文件转录

​实时音频流

​第 1 步 - 创建会话

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

​第 3 步 - 接收结果

​第 4 步 - 关闭会话

​语音活动检测（VAD）

​冲刷缓冲的音频

​Python 示例

​故障排除

​后续步骤

文本转语音

语言翻译

前提条件

音频格式要求

可用模型

端点

文件转录

带流式结果的文件转录

实时音频流

第 1 步 - 创建会话

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

第 3 步 - 接收结果

第 4 步 - 关闭会话

语音活动检测（VAD）

冲刷缓冲的音频

Python 示例

故障排除

后续步骤