输入关键词搜索

实时语音识别(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 请求头,携带该头会导致握手失败。

实现流程

  1. 建立 WebSocket 连接,立即发送 run-task 文本消息。
  2. 收到 task-started 后,开始发送二进制音频消息。
  3. 发送音频期间,同时接收 result-generated,处理临时结果和最终句子。
  4. 音频发送完毕后,发送 finish-task 文本消息,继续接收剩余识别结果。
  5. 收到 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 用量账单为准。
  • 任务失败或主动断开时,已经处理的音频仍可能产生费用。

参考文档

官方文档用于查询模型参数和事件字段。通过 AIHub 接入时,连接地址、API Key 和单连接单任务的使用方式以本文为准。

此文档是否对你有帮助?
有帮助
去反馈
  • 准备工作
  • 获取凭证与模型
  • 服务地址
  • 鉴权方式
  • 实现流程
  • 步骤一:启动任务
  • 步骤二:发送音频
  • 步骤三:处理识别结果
  • 步骤四:结束任务
  • 完整示例
  • 常见问题
  • 用量说明
  • 参考文档