前提條件
在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。
安裝 SDK
需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
npm install ./dashscope-sdk-nodejs-0.1.0.tgz
快速開始
以下呼叫範例可共用。依下表替換範例中的模型 ID。
| 模型 | 範例中的模型 ID |
|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.1-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message |
下載示例音頻,保存為 input.mp3,並轉換為 16 kHz、16-bit、單聲道 PCM:
ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm
將以下示例保存為 example.mjs,運行 node example.mjs。
import { readFile } from 'node:fs/promises'
import { setTimeout as sleep } from 'node:timers/promises'
import { RecognitionClient } from 'dashscope-sdk-nodejs/asr'
const pcm = await readFile('input.pcm')
const asr = new RecognitionClient({
apiKey: process.env.DASHSCOPE_API_KEY,
workspaceId: process.env.DASHSCOPE_WORKSPACE_ID,
baseUrl: 'dashscope-intl.aliyuncs.com',
model: 'qwen-audio-3.1-asr-flash-streaming',
format: 'pcm',
sampleRate: 16000,
})
asr.on('sentenceEnd', sentence => console.log('Final sentence:', sentence.text))
asr.on('error', err => console.error(err.code, err.message))
try {
await asr.start()
for (let offset = 0; offset < pcm.length; offset += 3200) {
asr.sendAudio(pcm.subarray(offset, offset + 3200))
await sleep(100)
}
await asr.finish()
} finally {
asr.close()
}
請求參數
Qwen-Audio-ASR-Streaming
RecognitionClient 的構造參數如下。
參數 | 類型 | 必填 | 說明 |
|---|
apiKey
| string
| 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId
| string
| 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl
| string
| 否 | 服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。 |
model
| string
| 否 | 模型 ID,默認 qwen-audio-3.1-asr-flash-streaming。 |
format
| 'pcm' | 'wav' | 'mp3' | 'opus' | 'speex' | 'aac' | 'amr'
| 否 | 音頻格式,默認 pcm;WAV 使用 PCM 編碼,Opus/Speex 使用 Ogg 封裝,AMR 使用 AMR-NB。 |
sampleRate
| number
| 否 | 實際音頻採樣率(Hz),默認 16000。 |
vocabularyId
| string
| 否 | 預編譯熱詞列表 ID。 |
languageHints
| string[]
| 否 | 識別語言提示,最多使用前 4 個值;未設置時自動識別。 |
multiThresholdModeEnabled
| boolean
| 否 | 多閾值模式,避免 VAD 斷句過長,默認 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]。 |
Qwen-Audio-ASR-Message
RecognitionClient 的構造參數如下。
參數 | 類型 | 必填 | 說明 |
|---|
apiKey
| string
| 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId
| string
| 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl
| string
| 否 | 服務域名,設置為 dashscope-intl.aliyuncs.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。 |
介面參考
Qwen-Audio-ASR-Streaming
主要方法
方法 | 返回值 | 說明 |
|---|
start()
| Promise<void>
| 啓動識別任務,完成後可發送音頻。 |
sendAudio(audio: Buffer | Uint8Array)
| 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 消息。 |
Qwen-Audio-ASR-Message
主要方法
方法 | 返回值 | 說明 |
|---|
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 消息。 |