Breeze ASR 25 - Docker

專案說明

基於 MediaTek Research 的 Breeze ASR 25 進行 Docker 容器化改造，提供跨平台（macOS、Windows、Linux）的語音辨識解決方案。

原始專案：https://github.com/mtkresearch/Breeze-ASR-25

---

🐳 Docker 架構改造

核心改進

系統架構

Project Structure:
├── Dockerfile                  # Python 3.11 + 系統依賴 + 所有 Python 套件
├── docker-compose.yml         # 編排、掛載、環境變數管理
├── docker_run.py              # 增強版轉錄腳本
├── requirements.txt           # 版本鎖定依賴
├── data/
│   ├── input/                 # 📥 音頻輸入（唯讀）
│   ├── output/                # 📤 轉錄結果（讀寫）
│   └── models/                # 💾 模型快取（讀寫）
└── docs/
    ├── DOCKER_GUIDE.md        # 完整使用指南
    ├── QUICK_START.md         # 快速參考
    └── IMPLEMENTATION_NOTES.md # 實作決策

---

快速開始

1. 前置需求

• Docker 和 Docker Compose 已安裝
• ~2GB 硬碟空間（首次模型下載）

2. 準備音頻

mkdir -p data/input
# 支援格式：.wav, .mp3, .flac, .ogg
cp your_audio.mp3 data/input/

3. 執行轉錄

docker-compose build
docker-compose up

4. 檢查結果

ls data/output/
# output_audio.json    # JSON 格式（含時間戳）
# output_audio.srt     # SRT 字幕格式
# output_audio.txt     # 純文字

---

技術細節

環境隔離

• Dockerfile：Python 3.11-slim 基礎
  • 系統依賴：libsndfile1、libsndfile1-dev、ffmpeg
  • Python 依賴：版本鎖定（torch 2.1.2, transformers 4.40.0 等）
  • Health Check：驗證所有套件可導入

跨平台相容

• docker-compose.yml 使用相對路徑（./data/）
• 自動適配 macOS、Windows WSL2、Linux 路徑差異
• 掛載設定：
  • ./data/input → /app/data/input (唯讀)
  • ./data/output → /app/data/output (讀寫)
  • ./data/models → /app/models (持久快取)

轉錄優化

• docker_run.py 增強功能：
  • 單檔和批量處理支援
  • 時間戳精確提取（毫秒級）
  • 三種輸出格式：JSON、SRT、TXT
  • CPU 推理優化（OMP/OpenBLAS 線程管理）

已知限制

• ⚠️ .m4a 格式不支援（用 .mp3 替代）
• CPU 推理速度較 GPU 慢，適合短音頻或離線處理

---

📖 詳細文件

• DOCKER_GUIDE.md - 完整使用指南、進階用法、故障排除
• QUICK_START.md - 常用命令速查表
• IMPLEMENTATION_NOTES.md - 實作決策與架構說明

---

進階使用

自訂輸出格式

# 輸出 SRT 字幕
docker-compose run --rm breeze-asr python docker_run.py \
  --input_dir /app/data/input \
  --output_dir /app/data/output \
  --output_format srt

# 輸出所有格式
docker-compose run --rm breeze-asr python docker_run.py \
  --output_format all

互動模式

docker-compose run --rm breeze-asr /bin/bash
# 容器內直接執行命令

---

模型資訊

Breeze ASR 25 基於 Whisper-large-v2 微調：

• 強化繁體中文語境辨識
• 採用混合語言向量解碼
• 強化時間戳對齊

原始論文：A Self-Refining Framework for Enhancing ASR Using TTS-Synthesized Data

---

相關連結

• 原始專案：https://github.com/mtkresearch/Breeze-ASR-25
• 模型卡：https://huggingface.co/MediaTek-Research/Breeze-ASR-25

---

最後更新：2026-05-28