【多媒體 AI 工具實戰】系列 #01（共 3 篇）｜難度：L2-進階

你請 AI 幫你寫了一段「把錄音檔轉成逐字稿」的程式，它丟給你二十行 Python，跑起來好像有輸出。 問題是：這段到底在幹嘛？輸出對不對？哪裡可能悄悄壞掉但你不知道？

這篇的目標不是教你從零寫語音辨識，而是教你看懂 AI 交出來的 Qwen3-ASR 程式、實際跑一次、抓出常見的坑。

一句話說明

Qwen3-ASR 是阿里通義 Qwen 系列的語音辨識模型：丟一段音檔進去，吐出一段文字。

ASR = Automatic Speech Recognition（自動語音辨識），也就是俗稱的「語音轉文字」「逐字稿」。 Qwen3-ASR 的特點是多語言（中英日韓等）、對中文和中英混講的辨識品質好， 而且有兩種用法：呼叫雲端 API（DashScope），或把模型下載到本地用 transformers 跑。

怎麼選：只是想快速轉幾個檔、不想管 GPU → 用 DashScope API。 資料不能外流、要大量處理 → 本地 transformers（但需要 GPU）。

最小範例（雲端 API 版）

這是 AI 最常交給你的樣子——呼叫 DashScope 雲端 API，不需要自己的 GPU：

# 安裝 SDK
uv add dashscope
Code language: PHP (php)

import os
import dashscope

# 從環境變數讀金鑰（不要寫死在程式裡！）
dashscope.api_key = os.environ["DASHSCOPE_API_KEY"]

response = dashscope.MultiModalConversation.call(
    model="qwen3-asr-flash",
    messages=[{
        "role": "user",
        "content": [{"audio": "meeting.wav"}],
    }],
)

# 印出辨識出來的文字
print(response.output.choices[0].message.content)
Code language: PHP (php)

跑完你應該看到 meeting.wav 裡講的話，變成一段文字印在畫面上。

逐行翻譯

import os
import dashscope                                    # 阿里雲的官方 SDK

dashscope.api_key = os.environ["DASHSCOPE_API_KEY"]  # 從環境變數拿金鑰（值放 .env，不進 git）

response = dashscope.MultiModalConversation.call(    # 送出一次辨識請求，等雲端回覆
    model="qwen3-asr-flash",                         # 指定用哪個模型（flash = 快速版）
    messages=[{                                       # 對話格式：告訴模型「這是使用者給的內容」
        "role": "user",
        "content": [{"audio": "meeting.wav"}],       # 內容是一個音檔
    }],
)

print(response.output.choices[0].message.content)   # 從回傳結構裡把文字挖出來印
Code language: PHP (php)

看到 response.output.choices[0].message.content 這一長串不用怕， 它就是照著回傳的資料結構一層一層往裡挖，最後那層 content 才是你要的逐字稿文字。

看不懂 choices[0] 為什麼是 [0]？把整個 response 貼給 AI 問：
「這個回傳物件的結構長怎樣？幫我畫出來，並標出逐字稿文字在哪一層」

常見變化

AI 可能會用不同寫法，認得出來就好：

變化 1：本地 transformers 版（不呼叫雲端）

from transformers import pipeline

asr = pipeline("automatic-speech-recognition", model="Qwen/Qwen3-ASR-Flash")
result = asr("meeting.wav")
print(result["text"])   # 文字在 result["text"]
Code language: PHP (php)

翻譯：把模型下載到自己機器上跑。pipeline(...) 是「幫我把載入模型、前處理、辨識全包好」的懶人入口。 好處是資料不出門，代價是要下載幾 GB 模型、通常要 GPU 才跑得動。

變化 2：指定語言 / 開時間戳

result = asr(
    "meeting.wav",
    generate_kwargs={"language": "zh"},   # 明講是中文，避免它猜錯語言
    return_timestamps=True,                # 順便回傳每段話的時間戳
)
Code language: PHP (php)

翻譯：language="zh" 是「告訴它這段是中文」；return_timestamps=True 讓輸出帶上「第幾秒到第幾秒講了什麼」，做字幕時很有用。

變化 3：長音檔先切段再逐段辨識

chunks = split_audio("podcast.mp3", chunk_seconds=30)  # 先切成一段一段
texts = [asr(c)["text"] for c in chunks]               # 每段各自辨識
full_text = " ".join(texts)                            # 再拼回完整逐字稿
Code language: PHP (php)

翻譯：一小時的 podcast 不能整個塞進去（會爆記憶體或超時），所以先切成 30 秒一段分批處理，最後拼起來。

實務要點：AI 沒說但你要知道的

這些是 Qwen3-ASR（以及所有 ASR）最容易踩的四個坑：

轉檔的標準做法（AI 通常會用 ffmpeg）：

# 把任意音檔轉成 16kHz 單聲道 wav
ffmpeg -i input.m4a -ar 16000 -ac 1 output.wav
Code language: CSS (css)

-ar 16000 = 取樣率設 16kHz；-ac 1 = 轉成單聲道。這兩個是 ASR 最常要求的規格。

🚩 紅旗：看到這些要警覺

1. 金鑰寫死在程式裡

dashscope.api_key = "sk-abc123..."   # 🚩 金鑰直接寫在程式裡
Code language: PHP (php)

為什麼危險：這段一進 git 或貼給別人，金鑰就永久外洩了，別人可以拿去消耗你的額度。

跟 AI 這樣說：「把 API 金鑰改成從環境變數讀，並建立 .env.example 列出需要哪些變數」

2. 沒管取樣率就直接送

result = asr("recording_44khz.mp3")   # 🚩 沒確認取樣率就送進去
Code language: PHP (php)

為什麼危險：取樣率不符時，辨識結果可能整段錯亂、缺字，但程式不會報錯——你會拿到一份看起來完整、其實錯很多的逐字稿。

跟 AI 這樣說：「在辨識前先確認音檔是 16kHz 單聲道，不是的話用 ffmpeg 先轉檔」

3. 長音檔沒切段

text = asr("two_hour_meeting.mp3")["text"]   # 🚩 兩小時檔案整個塞進去
Code language: PHP (php)

為什麼危險：可能超時、記憶體爆掉，或只辨識到前面幾分鐘就默默停了，你以為轉完了其實只有開頭。

跟 AI 這樣說：「這是長音檔，請先切成 30 秒左右一段分批辨識，再把結果拼回去」

4. 網路請求沒有 timeout / 錯誤被吞掉

try:
    response = dashscope.MultiModalConversation.call(...)
except Exception:
    pass   # 🚩 API 失敗了也悄悄跳過，你不會知道
Code language: PHP (php)

為什麼危險：雲端 API 可能因為網路、額度、檔案太大而失敗。錯誤被吞掉的話，你會拿到空白或不完整的結果卻以為成功。

跟 AI 這樣說：「不要吞例外，失敗時要記 log 或把錯誤拋出來，讓我知道哪個檔失敗了」

Vibe Coder 驗收檢查點

拿到 AI 的程式後，實際跑一次比讀十遍都有用：

• [ ] 準備一段測試音檔：找一段你知道內容的短音檔（10-30 秒），最好中英文都有，方便比對
• [ ] 確認金鑰不在程式裡：搜尋程式碼有沒有 api_key = "sk-...，有就退回改成讀環境變數
• [ ] 設好環境變數再跑：export DASHSCOPE_API_KEY=你的金鑰，然後跑程式
• [ ] 比對輸出：印出來的文字跟你知道的內容對不對？有沒有缺字、亂碼、語言錯（中文變拼音）
• [ ] 確認編碼正常：中文有沒有變成 中文 或問號亂碼（正常應該直接顯示中文字）
• [ ] 試一個長檔：拿一個 5 分鐘以上的檔跑，看它是完整轉完還是只轉了前面一小段
• [ ] 問 AI 有沒有漏處理：把程式貼給 AI 問「這段有沒有沒處理的錯誤情況？長音檔和取樣率有考慮嗎？」

看不懂就這樣問 AI

「用白話一段一段解釋這段 Qwen3-ASR 的程式在幹嘛，我是初學者，特別說明音檔是怎麼送進去、文字是從哪裡拿出來的」

「這段程式有沒有處理：取樣率不符、長音檔、API 失敗這三種情況？如果沒有，幫我補上」

「幫我加一段：辨識前先用 ffmpeg 把音檔轉成 16kHz 單聲道 wav，並在轉檔失敗時給清楚的錯誤訊息」

小結

• Qwen3-ASR = 語音轉文字，可走雲端 DashScope API（快、免 GPU）或本地 transformers（資料不外流、要 GPU）
• 看懂最小範例的關鍵：音檔怎麼送進去、文字從回傳的哪一層挖出來
• 四大實務坑：取樣率 16kHz、格式轉檔、長音檔切段、標點/時間戳後處理
• 最重要的驗收動作：準備一段你知道內容的音檔，實際跑一次、逐字比對

下一篇我們會接著看怎麼把辨識出來的逐字稿再加工利用。