实时语音识别(ASR)
更新时间: 2026/11/06 18:19:06
网易云信大模型 API(简称 AIHub)支持通过 WebSocket 持续发送音频、实时接收识别文本,适用于实时字幕、语音输入等场景。
本文以 Qwen-Audio-ASR-Streaming 实时识别协议为例,演示单声道、16 kHz、16-bit PCM 音频的接入方式。
本文档聚焦 AIHub 接入差异。Qwen 厂商的实时识别协议细节以官方文档为准,本文的连接地址、API Key 和单连接单任务的使用方式以本文为准。
准备工作
获取凭证与模型
- AIHub API Key:使用 AIHub 下发的 Key。
- ASR 模型名称:该 Key 已获授权的实时语音识别模型名称。
下文中的 <ASR_MODEL> 需替换为开通时提供的模型名称。使用其他模型时,须确认其音频格式和采样率要求。
服务地址
textwss://ai.yunxinapi.com/hub/alibaba/api-ws/v1/inference
鉴权方式
在 WebSocket 握手请求中设置:
httpAuthorization: Bearer <AIHUB_API_KEY>
- 建议从业务服务端发起连接,并将 Key 保存在服务端。
- 请勿将 Key 放入 URL、前端公开代码或日志。
- 该接口不支持
X-AIHub-Target-Channel-Id请求头,携带该头会导致握手失败。
实现流程
- 建立 WebSocket 连接,立即发送
run-task文本消息。 - 收到
task-started后,开始发送二进制音频消息。 - 发送音频期间,同时接收
result-generated,处理临时结果和最终句子。 - 音频发送完毕后,发送
finish-task文本消息,继续接收剩余识别结果。 - 收到
task-finished表示任务成功结束。收到task-failed或 AIHub 错误消息表示失败,停止发送音频。
任务生命周期:
- 每个连接只运行一个任务。
- 一个任务可以包含多段连续语音、产生多个最终句子;句子结束不表示任务结束。
- 任务终态后连接会关闭,下一任务请新建连接。
- 不要在同一连接中重复发送
run-task。
步骤一:启动任务
将以下 JSON 作为一条 WebSocket 文本消息发送:
json{
"header": {
"action": "run-task",
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"streaming": "duplex"
},
"payload": {
"task_group": "audio",
"task": "asr",
"function": "recognition",
"model": "<ASR_MODEL>",
"parameters": {
"format": "pcm",
"sample_rate": 16000
},
"input": {}
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
| - header | Object | 请求头对象 |
| action | string | 固定为 run-task |
| task_id | string | 客户端生成的唯一任务 ID,建议使用 UUID 的 32 位十六进制字符串;后续结束指令使用同一 ID |
| streaming | string | 固定为 duplex |
| - payload | Object | 业务参数对 |
| task_group | string | 固定为 audio |
| task | string | 固定为 asr |
| function | string | 固定为 recognition |
| model | string | 已获授权的 ASR 模型名称,目前支持以下模型:qwen-audio-3.1-asr-flash-streaming |
| - parameters | Object | 音频参数对象 |
| format | string | 音频编码格式,示例为 pcm |
| sample_rate | integer | 实际音频采样率(Hz),示例为 16000 |
| input | Object | 固定为 {} |
以上字段均应填写。可选识别参数放入 payload.parameters,具体支持范围取决于已开通模型,参见 百炼客户端事件说明。
任务就绪事件示例:
json{
"header": {
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"event": "task-started",
"attributes": {}
},
"payload": {}
}
步骤二:发送音频
音频使用 WebSocket 二进制消息发送,直接发送音频字节,无需 base64 或 JSON 包装。
音频格式要求:
示例要求无文件头的原始 PCM:
| 参数 | 要求 |
|---|---|
| 声道 | 单声道 |
| 采样率 | 16 kHz |
| 位深 | 16-bit signed |
| 字节序 | little-endian |
发送节奏建议:
建议按音频播放速度分块发送:
- 上述 PCM 每 100 ms 对应 3200 字节,可每隔约 100 ms 发送一块。
- 实际麦克风采集时,按采集节奏发送。
- 音频格式、声道数和采样率须与声明一致。
- 将 WAV 文件改名为
.pcm不会移除 WAV 文件头或转换编码。
音频转换:
如需转换已有音频,可使用 FFmpeg:
bashffmpeg -i input.wav -ac 1 -ar 16000 -acodec pcm_s16le -f s16le sample.pcm
步骤三:处理识别结果
服务端以 JSON 文本消息返回事件。
result-generated 示例:
json{
"header": {
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"event": "result-generated"
},
"payload": {
"output": {
"sentence": {
"begin_time": 0,
"end_time": 1800,
"text": "你好,欢迎使用语音识别。",
"sentence_end": true,
"heartbeat": false
}
},
"usage": {
"duration": 2
}
}
}
| 字段 | 类型 | 客户端处理方式 |
|---|---|---|
| - header | Object | 请求头对象 |
| event | String | 按事件类型分发处理 |
| task_id | String | 关联本次任务 |
| - payload | Object | 业务参数对象 |
| - output | Object | 输出结果对象 |
| - sentence | Object | 当前句子对象 |
| text | String | 当前句子的识别文本 |
| sentence_end | Boolean | false:临时结果,后续可能修订;更新当前句展示,避免将每个临时结果累加成重复文本true:当前句的最终结果,可保存该句,继续等待后续句子或任务终态 |
| heartbeat | Boolean | true:心跳结果,跳过文本处理 |
| begin_time | Integer | 音频开始时间(毫秒);未确定的值可能为空 |
| end_time | Integer | 音频结束时间(毫秒);未确定的值可能为空 |
| - usage | Object | 当前任务对象 |
| duration | Integer | 当前任务的累计计费音频时长(秒);部分事件中可能为空或缺失 |
不同事件携带的字段可能不同,客户端应允许附加字段,并对可选字段做空值处理。完整结果字段见百炼服务端事件说明。
步骤四:结束任务
发送最后一块音频后,发送一条 finish-task 文本消息:
json{
"header": {
"action": "finish-task",
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"streaming": "duplex"
},
"payload": {
"input": {}
}
}
task_id必须与本连接的run-task一致。- 只发送一次结束指令,随后停止发送音频,继续读取结果。
- 请勿在发完
finish-task后立即断开,否则可能丢失最后一句。
成功终态示例:
json{
"header": {
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"event": "task-finished"
},
"payload": {
"output": {},
"usage": null
}
}
task-finished 不保证再次携带时长或识别文本;应保留此前收到的最终句子和最新有效时长。
完整示例
示例使用 Python 3.11+,从终端安全输入 Key,读取原始 PCM 文件,在发送音频的同时接收结果,只打印最终句子。60 秒等待超时为示例客户端设置,可按业务需要调整。
安装依赖:
bashpython3 -m pip install 'websockets>=15,<16'
保存为 asr_client.py:
import argparse
import asyncio
import contextlib
import getpass
import json
import uuid
from pathlib import Path
from websockets.asyncio.client import connect
URL = "wss://ai.yunxinapi.com/hub/alibaba/api-ws/v1/inference"
async def receive_event(ws):
raw = await asyncio.wait_for(ws.recv(), timeout=60)
event = json.loads(raw)
if event.get("error"):
error = event["error"]
raise RuntimeError(
f"AIHub: {error.get('code')}, request_id={error.get('request_id')}"
)
header = event.get("header", {})
if header.get("event") == "task-failed":
raise RuntimeError(
f"ASR: {header.get('error_code')}: {header.get('error_message')}"
)
return event
async def send_audio(ws, audio_path, task_id):
with audio_path.open("rb") as audio:
while chunk := audio.read(3200):
await ws.send(chunk) # bytes -> 二进制消息
await asyncio.sleep(0.1)
await ws.send(json.dumps({
"header": {
"action": "finish-task", "task_id": task_id, "streaming": "duplex"
},
"payload": {"input": {}}
}))
async def receive_results(ws):
while True:
event = await receive_event(ws)
name = event.get("header", {}).get("event")
if name == "result-generated":
sentence = ((event.get("payload") or {}).get("output") or {}).get(
"sentence"
) or {}
if sentence.get("sentence_end") and not sentence.get("heartbeat"):
print(sentence.get("text", ""), flush=True)
elif name == "task-finished":
return
async def recognize(model, audio_path, key):
task_id = uuid.uuid4().hex
async with connect(
URL, additional_headers={"Authorization": f"Bearer {key}"},
open_timeout=20
) as ws:
await ws.send(json.dumps({
"header": {
"action": "run-task", "task_id": task_id, "streaming": "duplex"
},
"payload": {
"task_group": "audio", "task": "asr", "function": "recognition",
"model": model, "input": {},
"parameters": {"format": "pcm", "sample_rate": 16000}
}
}))
event = await receive_event(ws)
if event.get("header", {}).get("event") != "task-started":
raise RuntimeError("未收到 task-started")
sender = asyncio.create_task(send_audio(ws, audio_path, task_id))
receiver = asyncio.create_task(receive_results(ws))
try:
done, _ = await asyncio.wait(
[sender, receiver], return_when=asyncio.FIRST_COMPLETED
)
for task in done:
task.result() # 及时抛出发送或接收异常
if receiver not in done:
await receiver # finish-task 已发出,继续等待 task-finished
finally:
for task in (sender, receiver):
task.cancel()
for task in (sender, receiver):
with contextlib.suppress(asyncio.CancelledError, Exception):
await task
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--model", required=True, help="已开通的 ASR 模型名称")
parser.add_argument("audio", type=Path, help="16 kHz 单声道 16-bit 原始 PCM")
args = parser.parse_args()
if not args.audio.is_file() or args.audio.stat().st_size == 0:
parser.error("音频文件不存在或为空")
key = getpass.getpass("AIHub API Key: ").strip()
if not key:
parser.error("API Key 不能为空")
asyncio.run(recognize(args.model, args.audio, key))
运行:
bashpython3 asr_client.py --model '<ASR_MODEL>' sample.pcm
识别文本属于业务数据,示例打印仅用于展示;接入自己的系统时请按业务的数据保护要求处理。
常见问题
| 场景 | 客户端到的内容 | 建议处理 |
|---|---|---|
| WebSocket 握手失败 | HTTP 非 101,可能附带 JSON 错误 |
检查正式地址、Key、请求头;按状态码处理,连接尚未建立 |
| 连接已建立,但启动任务失败 | AIHub JSON 错误文本消息,随后关闭连接,通常为 1008 |
根据 error.code 修正参数或权限;保留 error.request_id 供排障 |
| ASR 任务失败 | header.event=task-failed |
读取 header.error_code、header.error_message;停止发送并关闭连接 |
| 未收到任务终态便断开 | WebSocket 关闭或网络异常 | 不能视为成功;保存已确认句子,根据业务需要决定是否新建任务重试 |
AIHub 错误示例:
json{
"error": {
"code": "invalid_request_body",
"message": "first WebSocket message must be run-task",
"request_id": "req_example"
}
}
常见错误码:
| 错误码 | 含义 | 处理建议 |
|---|---|---|
invalid_request_body |
首条消息或参数错误 | 修正请求参数 |
model_not_granted |
模型未授权 | 检查模型授权配置 |
no_active_channel |
模型暂不可用 | 退避重试 |
upstream_unreachable |
识别服务连接失败 | 退避重试 |
- 参数、权限类错误应先修正。
- 临时网络或服务故障可使用退避策略重新建立连接,生成新的
task_id。 - 该接口不提供断点续传,重新发送音频会创建新任务,业务侧应处理重复识别结果及可能产生的重复费用。
任务失败示例:
json{
"header": {
"task_id": "6b72fb0ac9414c658cfc174f11a74e71",
"event": "task-failed",
"error_code": "CLIENT_ERROR",
"error_message": "invalid audio format"
},
"payload": {}
}
用量说明
- 按服务返回的有效音频时长及已开通模型的价格计费,单位为秒。
payload.usage.duration表示本任务累计值,不要将多条事件的该字段相加。- 连接持续时间、发送字节数和文本长度不作为客户计算用量的依据;具体费用以 AIHub 用量账单为准。
- 任务失败或主动断开时,已经处理的音频仍可能产生费用。
参考文档
- Qwen-Audio-ASR-Streaming 实时语音识别 WebSocket 接入指南
- Paraformer 实时语音识别 WebSocket 接入指南
- 客户端事件与识别参数
- 服务端事件与结果字段
官方文档用于查询模型参数和事件字段。通过 AIHub 接入时,连接地址、API Key 和单连接单任务的使用方式以本文为准。




