Skip to main content
非即時語音辨識（Paraformer）

Paraformer非即時語音辨識Python SDK

本文介紹Paraformer非即時語音辨識Python SDK的參數和介面細節。

本文檔僅適用於華北2（北京）地區。如需使用模型，需使用華北2（北京）地區的API Key。
阿里雲百鍊為華北2（北京）地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
使用者指南：非即時語音辨識

前提條件

已開通服務並擷取API Key。請配置API Key到環境變數，而非寫入程式碼在代碼中，防範因代碼泄露導致的安全風險。
當您需要為第三方應用或使用者提供臨時存取權限，或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時，建議使用臨時鑒權Token。與長期有效 API Key 相比，臨時鑒權 Token 具備時效性短（60秒）、安全性高的特點，適用於臨時調用情境，能有效降低API Key泄露的風險。使用方式：在代碼中，將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。

快速開始

核心類（Transcription）提供了非同步提交任務、同步等待任務結束和非同步查詢任務執行結果的介面。可通過如下兩種調用方式進行非即時語音辨識：
  • 非同步提交任務+同步等待任務結束：提交任務後，阻塞當前線程直到任務結束並擷取識別結果。
  • 非同步提交任務+非同步查詢任務執行結果：提交任務後，在需要的時候通過調用查詢任務介面擷取任務的執行結果。

非同步提交任務+同步等待任務結束

  1. 調用核心類（Transcription）的async_call方法並設定請求參數。
    • 檔案轉寫服務對通過API提交的任務採取儘力服務原則進行處理。任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內。任務開始處理後，語音辨識將以數百倍加速完成。
    • 每一個任務完成後，識別結果和URL下載連結有效期間為24小時，逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。
  2. 調用核心類（Transcription）的wait方法同步等待任務結束。 任務的狀態包括PENDING、RUNNING、SUCCEEDED和FAILED。當任務處於PENDING或RUNNING狀態時，wait介面將被阻塞。當任務處於SUCCEEDED或FAILED狀態時，wait介面不再阻塞並返回任務的執行結果。 wait返回TranscriptionResponse。 
from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import json

# 若沒有將API Key配置到環境變數中，需將下面這行代碼注釋放開，並將apiKey替換為自己的API Key
# dashscope.api_key = "apiKey"
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # “language_hints”只支援paraformer-v2模型
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transcription done!')

非同步提交任務+非同步查詢任務執行結果

  1. 調用核心類（Transcription）的async_call方法並設定請求參數。
    • 檔案轉寫服務對通過API提交的任務採取儘力服務原則進行處理。任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內。任務開始處理後，語音辨識將以數百倍加速完成。
    • 每一個任務完成後，識別結果和URL下載連結有效期間為24小時，逾時後無法查詢任務或通過先前查詢結果中的URL下載結果。
  2. 迴圈調用核心類（Transcription）的fetch方法直到擷取最終的任務結果。 當任務狀態為SUCCEEDED或FAILED時，停止輪詢並處理結果。 fetch返回TranscriptionResponse。 
from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# 若沒有將API Key配置到環境變數中，需將下面這行代碼注釋放開，並將apiKey替換為自己的API Key
# import dashscope
# dashscope.api_key = "apiKey"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # “language_hints”只支援paraformer-v2模型
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == 'FAILED':
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transcription done!')

請求參數

請求參數通過核心類（Transcription）的async_call方法進行設定。
說話人分離功能（diarization_enabled）僅適用於單聲道音頻，多頻道音訊不支援說話人分離。如果您的音頻為多聲道格式，需先將其轉換為單聲道後再啟用說話人分離。可使用ffmpeg進行轉換：ffmpeg -i input.wav -ac 1 output_mono.wav。
參數類型預設值是否必須說明
modelstr
是指定用於音視頻檔案轉寫的Paraformer模型名。參見支援的模型。
file_urlslist[str]
是音視頻檔案轉寫的URL列表，支援HTTP / HTTPS協議，單次請求僅支援1個URL。若錄音檔案儲存體在阿里雲OSS，使用SDK方式不支援使用以 oss://為首碼的臨時 URL。
vocabulary_idstr
否最新熱詞ID，支援最新v2系列模型並配置語種資訊，此次語音辨識中生效此熱詞ID對應的熱詞資訊。預設不啟用。使用方法請參考定製熱詞。
channel_idlist[int][0]否指定在多音軌音頻檔案中需要識別的音軌索引，索引從 0 開始。例如，[0] 表示識別第一個音軌，[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數，則預設處理第一個音軌。
指定的每一個音軌都將獨立計費。例如，為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
disfluency_removal_enabledboolFalse否過濾語氣詞，預設關閉。
timestamp_alignment_enabledboolFalse否是否啟用時間戳記校準功能，預設關閉。
special_word_filterstr
否指定在語音辨識過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。若未傳入該參數，系統將啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的*。若傳入該參數，則可實現以下敏感詞處理策略：
  • 替換為 *：將匹配的敏感詞替換為等長的 *；
  • 直接過濾：將匹配的敏感詞從識別結果中完全移除。
該參數的值應為一個 JSON 字串，其結構如下所示：
{
  "filter_with_signed": {
    "word_list": ["測試"]
  },
  "filter_with_empty": {
    "word_list": ["開始", "發生"]
  },
  "system_reserved_filter": true
}
JSON欄位說明：
  • filter_with_signed
    • 類型：對象。
    • 是否必填：否。
    • 描述：配置需替換為*的敏感詞列表。識別結果中匹配的詞語將被等長的 * 替代。
    • 樣本：以上述JSON為例，“幫我測試一下這段代碼”的語音辨識結果將會是“幫我**一下這段代碼”。
    • 內部欄位：
      • word_list: 字串數組，列出需被替換的敏感詞。
  • filter_with_empty
    • 類型：對象。
    • 是否必填：否。
    • 描述：配置需從識別結果中移除（過濾）的敏感詞列表。識別結果中匹配的詞語將被完全刪除。
    • 樣本：以上述JSON為例，“比賽這就要開始了嗎？”的語音辨識結果將會是“比賽這就要了嗎”。
    • 內部欄位：
      • word_list: 字串數組，列出需被完全移除（過濾）的敏感詞。
  • system_reserved_filter
    • 類型：布爾值。
    • 是否必填：否。
    • 預設值：true。
    • 描述：是否啟用系統預置的敏感詞規則。設為true時，將同時啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百鍊敏感詞表匹配的詞語將被替換為等長的*。
language_hintslist[str]["zh", "en"]否指定待識別語音的語言代碼。該參數僅適用於paraformer-v2模型。支援的語言代碼：
  • zh: 中文
  • en: 英文
  • ja: 日語
  • yue: 粵語
  • ko: 韓語
  • de：德語
  • fr：法語
  • ru：俄語
diarization_enabledboolFalse否自動說話人分離，預設關閉。僅適用於單聲道音頻，多頻道音訊不支援說話人分離。啟用該功能後，識別結果中將顯示speaker_id欄位，用於區分不同說話人。
如果啟用說話人分離功能，建議音頻時間長度不超過2小時，否則可能導致識別失敗或逾時。
有關speaker_id的樣本，請參見識別結果說明。
speaker_countint
否說話人數量參考值。取值範圍為2至100的整數（包含2和100）。開啟說話人分離功能後（diarization_enabled設定為true）生效。預設自動判斷說話人數量，如果配置此項，只能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。

響應結果

TranscriptionResponse

TranscriptionResponse封裝了任務的基本資料（task_id和task_status）和執行結果（output屬性對應的內容，參見TranscriptionOutput）。
async_call方法返回的TranscriptionResponse樣本如下，不包含submit_time、scheduled_time等資訊：
{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING"
    },
    "usage":null
}
如果需要擷取submit_time、scheduled_time等資訊，應使用wait()或fetch()方法，而不是直接從 async_call() 的傳回值中訪問。wait()或fetch()方法返回的TranscriptionResponse樣本如下：
{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}
需要關注的參數：

參數

說明

status_code

HTTP請求狀態代碼。

code

  • 最外層的code不必關注。

  • output.results下面的code，代表錯誤碼。可以結合message欄位，對照錯誤碼排查問題。

message

  • 最外層的message不必關注。

  • output.results下面的message，代表錯誤資訊。可以結合code欄位，對照錯誤碼排查問題。

task_id

任務ID。

task_status

任務狀態。

有PENDING、RUNNING、SUCCEEDED和FAILED這四種狀態。

當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為SUCCEEDED，需通過subtask_status欄位判斷具體子任務結果。

results

子任務識別結果。

subtask_status

子任務狀態。

有PENDING、RUNNING、SUCCEEDED和FAILED這四種狀態。

file_url

被識別音訊URL。

transcription_url

音頻識別結果對應的URL。

識別結果儲存為JSON檔案，您可以通過transcription_url對應的連結下載檔案或直接通過HTTP請求讀取該檔案中的內容。JSON檔案的內容請參見識別結果說明。

TranscriptionOutput

TranscriptionOutput對應TranscriptionResponse的output屬性，代表當前任務執行結果。
  • PENDING狀態
  • RUNNING狀態
  • SUCCEEDED 狀態
  • FAILED 狀態
{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}
需要關注的參數：

參數

說明

code

代表錯誤碼。可以結合message欄位，對照錯誤碼排查問題。

message

代表錯誤資訊。可以結合code欄位，對照錯誤碼排查問題。

task_id

任務ID。

task_status

任務狀態。

有PENDING、RUNNING、SUCCEEDED和FAILED這四種狀態。

當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為SUCCEEDED，需通過subtask_status欄位判斷具體子任務結果。

results

子任務識別結果。

subtask_status

子任務狀態。

有PENDING、RUNNING、SUCCEEDED和FAILED這四種狀態。

file_url

被識別音訊URL。

transcription_url

音頻識別結果對應的URL。

識別結果以JSON格式儲存在一個JSON檔案中，您可以通過transcription_url對應的連結下載檔案或直接通過HTTP請求讀取該檔案中的內容。JSON檔案的內容請參見識別結果說明。

識別結果說明

識別結果儲存為JSON檔案。 
{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, 這裡是阿里巴巴語音實驗室。",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, 這裡是阿里巴巴語音實驗室。",
                    "sentence_id":1,
                    "speaker_id":0, //當開啟自動說話人分離功能時才會顯示該欄位
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // 這裡省略其它內容
                    ]
                }
            ]
        }
    ]
}
需要關注的參數如下：

參數

類型

說明

audio_format

string

源檔案中音訊格式。

channels

array[integer]

源檔案中音訊音軌索引資訊，對單軌音頻返回[0]，對雙軌音頻返回[0, 1]，以此類推。

original_sampling_rate

integer

源檔案中音訊採樣率（Hz）。

original_duration

integer

源檔案中的原始音頻時間長度（ms）。

channel_id

integer

轉寫結果的音軌索引，以0為起始。

content_duration

integer

音軌中被判定為語音內容的時間長度（ms）。

Paraformer語音辨識模型服務僅對音軌中被判定為語音內容的時間長度進行語音轉寫，並據此進行計量計費，非語音內容不計量、不計費。通常情況下語音內容時間長度會短於原始音頻時間長度。由於對是否存在語音內容的判定是由AI模型給出的，可能與實際情況存在一定誤差。

transcript

string

段落層級的語音轉寫結果。

sentences

array

句子層級的語音轉寫結果。

words

array

詞層級的語音轉寫結果。

begin_time

integer

開始時間戳（ms）。

end_time

integer

結束時間戳記（ms）。

text

string

語音轉寫結果。

speaker_id

integer

當前說話人的索引，以0為起始，用於區分不同的說話人。

僅在啟用說話人分離功能時，該欄位才會顯示於識別結果中。

punctuation

string

預測出的詞之後的標點符號（如有）。

關鍵介面

核心類（Transcription）

Transcription可以通過“from dashscope.audio.asr import Transcription”方式引入。
成員方法方法簽名說明
async_call
@classmethod
def async_call(cls,
               model: str,
               file_urls: List[str],
               phrase_id: str = None,
               api_key: str = None,
               workspace: str = None,
               **kwargs) -> TranscriptionResponse
非同步提交語音辨識任務。該方法返回TranscriptionResponse。
wait
@classmethod
def wait(cls,
         task: Union[str, TranscriptionResponse],
         api_key: str = None,
         workspace: str = None,
         **kwargs) -> TranscriptionResponse
阻塞當前線程直到非同步任務結束（任務狀態為SUCCEEDED或FAILED）。該方法返回TranscriptionResponse。
fetch
@classmethod
def fetch(cls,
          task: Union[str, TranscriptionResponse],
          api_key: str = None,
          workspace: str = None,
          **kwargs) -> TranscriptionResponse
非同步查詢當前任務執行結果。該方法返回TranscriptionResponse。

錯誤碼

如遇報錯問題，請參見錯誤碼進行排查。 若問題仍未解決，請加入開發人員群反饋遇到的問題，並提供Request ID，以便進一步排查問題。 當任務包含多個子任務時，只要存在任一子任務成功，整個任務狀態將標記為SUCCEEDED，需通過subtask_status欄位判斷具體子任務結果。 錯誤返回樣本： 
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

更多樣本

更多樣本，請參見GitHub。

常見問題

功能特性

Q：是否支援Base64編碼方式的音頻？

不支援Base64編碼方式的音頻。僅支援可通過公網訪問的 URL 所指向的音訊識別，不支援識別二進位流，也不支援直接識別本地檔案。

Q：如何將音頻檔案以公網可訪問的URL形式提供？

通常遵循以下幾個步驟（這裡為您提供一種思路，具體情況因不同儲存產品而異，推薦將音頻上傳至阿里雲OSS）：
如以下這幾種：
  • Object Storage Service服務（推薦）：
    • 使用雲端服務商的Object Storage Service服務（如阿里雲OSS），將音頻檔案上傳到儲存桶中，並設定為公開訪問。
    • 優點：高可用性、支援 CDN 加速、易於管理。
  • Web 服務器：
    • 將音頻檔案放置在支援 HTTP/HTTPS 訪問的 Web 服務器上（如 Nginx、Apache）。
    • 優點：適合小型專案或本地測試。
  • 內容分發網路（CDN）：
    • 將音頻檔案託管在 CDN 上，通過 CDN 提供的 URL 訪問。
    • 優點：加速檔案傳輸，適合高並發情境。
根據選擇的儲存/託管方式，將音頻上傳，如：
  • Object Storage Service服務：
    • 登入雲端服務商的控制台，建立儲存桶。
    • 上傳音頻檔案，並設定檔案許可權為“公用讀取”或產生臨時訪問連結。
  • Web 服務器：
    • 將音頻檔案放置在伺服器指定目錄下（如 /var/www/html/audio/）。
    • 確保檔案可以通過 HTTP/HTTPS 訪問。
例如：
  • Object Storage Service服務：
    • 檔案上傳後，系統會自動產生一個公網存取 URL（通常格式為 https://<bucket-name>.<region>.aliyuncs.com/<file-name>）。
    • 如果需要更友好的網域名稱，可以綁定自訂網域名並開啟 HTTPS。
  • Web 服務器：
    • 檔案的存取 URL 通常是伺服器位址加上檔案路徑（如 https://your-domain.com/audio/file.mp3）。
  • CDN：
    • 配置 CDN 加速後，使用 CDN 提供的 URL（如 https://cdn.your-domain.com/audio/file.mp3）。
公網環境下，確保產生的 URL 可以正常訪問，例如：
  • 在瀏覽器中開啟 URL，檢查是否能播放音頻檔案。
  • 使用工具（如 curl 或 Postman）驗證 URL 是否返回正確的 HTTP 響應（狀態代碼 200）。
使用SDK時，若錄音檔案儲存體在阿里雲OSS，不支援使用以 oss://為首碼的臨時 URL。 使用RESTful API時，若錄音檔案儲存體在阿里雲OSS，支援使用以 oss://為首碼的臨時 URL：
  • 臨時 URL 有效期間48小時，到期後無法使用，請勿用於生產環境。
  • 檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高並發及壓測情境。
  • 生產環境建議使用阿里雲OSS 等穩定儲存，確保檔案長期可用並規避限流問題。

Q：多久能擷取識別結果？

任務提交後將進入排隊（PENDING）狀態，排隊時間取決於隊列長度和檔案時間長度，無法明確給出，通常在數分鐘內，請耐心等待。並且音頻時間長度越長，所需時間越久。

故障排查

如遇代碼報錯問題，請根據錯誤碼中的資訊進行排查。

Q：識別結果和語音播放不同步怎麼辦？

將請求參數timestamp_alignment_enabled設為true將啟用時間戳記校準功能，能夠讓識別結果和語音播放同步。

Q：一直輪詢不到結果？

可能是限流原因，請耐心等待。若需擴容，請加入開發人員群進行申請。

Q：無法識別語音（無識別結果）是什麼原因？

  • 請檢查音頻是否符合要求（格式、採樣率）。
  • 若是使用了paraformer-v2模型，檢查language_hints的設定是否正確。
  • 以上都沒問題，可通過定製熱詞，提升對特定詞語的識別效果。

Q：說話人分離結果全部標記為同一個Speaker怎麼辦？

請按以下步驟排查：
  1. 檢查音頻是否為單聲道格式。說話人分離功能僅支援單聲道音頻，多頻道音訊不支援說話人分離。可使用ffprobe查看音頻聲道數：ffprobe -i input.wav -show_entries stream=channels -of default=noprint_wrappers=1。
  2. 如果音頻為多聲道，需先轉換為單聲道：ffmpeg -i input.wav -ac 1 output_mono.wav。
  3. 確認已正確設定說話人分離參數：diarization_enabled=true，並根據實際說話人數設定speaker_count參數（取值範圍2至100）。

更多問題

請參見GitHub QA。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多