通过语音 Node.js SDK 调用 Qwen-Audio-ASR-Message,发送音频、处理识别结果,并在任务中更新识别上下文。
安装 SDK
需要 Node.js 18 或以上版本。下载 SDK 0.1.0 安装包后,在项目目录运行:
快速开始
在控制台获取 API Key,并配置为环境变量 DASHSCOPE_API_KEY。
下载示例音频,保存为 input.mp3,并转换为 16 kHz、16-bit、单声道 PCM:
example.mjs,运行 node example.mjs。
接口参考
构造参数
RecognitionClient 的构造参数如下。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
apiKey | string | 否 | API Key。默认读取 DASHSCOPE_API_KEY。 |
baseUrl | string | 否 | 服务域名,默认 maas.qianwenaiapi.com。 |
model | string | 是 | 模型 ID,设置为 qwen-audio-3.1-asr-flash-message。 |
format | 'pcm' | 'wav' | 'mp3' | 'opus' | 'speex' | 'aac' | 'amr' | 否 | 音频格式,默认 pcm;WAV 使用 PCM 编码,Opus/Speex 使用 Ogg 封装,AMR 使用 AMR-NB。 |
sampleRate | number | 否 | 音频采样率,使用 16000 Hz。 |
vocabularyId | string | 否 | 预编译热词列表 ID。 |
languageHints | string[] | 否 | 识别语言提示,最多使用前 4 个值;未设置时自动识别。 |
disfluencyRemovalEnabled | boolean | 否 | 过滤语气词并润色结果,默认 false。 |
maxSentenceSilence | number | 否 | VAD 断句静音阈值(ms),范围 [200,6000],默认 800。 |
heartbeat | boolean | 否 | 静音保活开关,默认 false;开启后需持续发送静音音频。 |
context | AsrContextMessage[] | 否 | 识别上下文。消息格式为 { role, content: [{ type: "input_text", text }] },role 为 user 或 assistant;每种角色最多 5 条,文本共少于 400 字符,按对话轮次排列。 |
parameters | Partial<RecognitionParameters> | 否 | 其他识别参数,如 vad_model、keep_dialect 和 vocabulary。 |
connectTimeoutMs | number | 否 | 建连超时(ms),默认 10000。 |
taskTimeoutMs | number | 否 | 任务启动或结束的等待超时(ms),默认 60000;0 表示不限制。 |
parameters.vad_model | 'near_meeting_16k' | 'far_field_meeting_16k' | 否 | 近场或远场 VAD,默认 far_field_meeting_16k。 |
parameters.keep_dialect | boolean | 否 | 保留方言表达,默认 false。 |
parameters.vocabulary | Record<string, number> | 否 | 即时热词:键为词,值为权重 [1,5] 或 50。 |
parameters.speech_noise_threshold | number | 否 | VAD 灵敏度阈值,范围 [-1,1]。 |
parameters.intermediate_result_enabled | boolean | 否 | 返回识别中间结果,默认 false。 |
主要方法
| 方法 | 返回值 | 说明 |
|---|---|---|
start() | Promise<void> | 启动识别任务,完成后可发送音频。 |
sendAudio(audio: Buffer | Uint8Array) | void | 按配置的格式和采样率发送音频帧。 |
updateContext(context: AsrContextMessage[]) | void | 在任务启动后、结束输入前更新识别上下文。 |
finish() | Promise<void> | 结束音频输入并等待任务完成,文本通过回调返回。 |
close(code?: number, reason?: string) | void | 关闭连接并释放任务资源。 |
回调事件
通过 on(event, listener) 注册回调;完整事件字段见服务端事件。
| 事件 | 负载 | 说明 |
|---|---|---|
started | { taskId: string } | 任务已启动,可发送输入。 |
result | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 中间或最终句子,已过滤心跳结果。 |
sentenceEnd | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 最终句子,sentence_end === true。 |
finished | { taskId: string; duration?: number; usage?: RecognitionUsage } | 任务已结束,本地任务状态已清理。 |
failed / error | DashScopeError | 调用错误,包含 code、message 和请求标识。 |
close | { code: number; reason: string } | 底层连接关闭通知。 |
event | ServerEvent | 原始服务端 JSON 消息。 |