Zipformer

クイックスタート

1. Docker のインストール

開発ボードで以下のコマンドを実行して Docker をインストールします：

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. プロジェクトの実行（単一コマンド、デュアルモードプレビュー）

このプロジェクトは中国語・英語の音声認識を提供します。Web 画面はアップロードファイルの全文文字起こしと、途中結果付きのブラウザーマイクによるストリーミング文字起こしに対応します。

ステップ A：イメージの取得

sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-zipformer:latest
sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-zipformer:latest

ステップ B：ワンクリックで実行

対象：RK3588:

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-zipformer:latest

アクセス先： http://<Board_IP>:8000

対象：RK3576:

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-zipformer:latest

アクセス先： http://<Board_IP>:8000

ブラウザーは WebSocket 経由でマイクの PCM を送るため、ホストの /dev/snd マッピングは不要です。

3. コマンドライン推論

python inference.py --platform rk3576 --model_dir model \
    --file samples/test.wav

RK3588 のソースディレクトリで実行する場合は --platform rk3588 を使用してください。

🔌 API ドキュメント

サービスはファイル全体の文字起こし用 REST インターフェースと、ストリーミング PCM 用 WebSocket インターフェースを提供します。REST ルートは http://<Board_IP>:8000/docs の OpenAPI に記載されています。

1. ファイル文字起こしインターフェース

エンドポイント： POST /api/models/zipformer/predict

リクエストパラメータ（Multipart/Form-Data）：

• file：必須の音声ファイル。サービスは推論前にファイルをデコードして 16 kHz にリサンプリングします。アップロード上限は 64 MB です。

使用例：

curl -X POST "http://127.0.0.1:8000/api/models/zipformer/predict" \
    -F 'file=@samples/test.wav'

レスポンス形式（JSON）：

{
  "success": true,
  "model": "zipformer",
  "platform": "rk3576",
  "inference_time_ms": 164.3,
  "result": {
    "text": "example transcript",
    "tokens": [12, 34],
    "timestamps": [3, 8],
    "audio_duration_seconds": 2.4,
    "processed": true
  }
}

2. ストリーミング文字起こしインターフェース

エンドポイント： WS /api/models/zipformer/stream

モノラル 16 kHz、符号付き 16 ビット・リトルエンディアンの PCM をバイナリ WebSocket メッセージとして送信します。収録が完了したら、次を送ります：

{"action":"stop"}

{"action":"reset"} を送ると、現在のストリーミングセッションを破棄して再開始します。サーバーメッセージには以下の種類があります：

• ready：セッションの準備完了を示し、sample_rate: 16000 と format: pcm_s16le を報告します。
• partial：十分な音声を処理した後の更新結果を含みます。
• final：stop 操作後の完成した結果を含みます。
• error：不正な PCM フレーム構造またはランタイム障害を報告します。

3. システム状態と設定

• ヘルスエンドポイント： GET /api/health
• 設定エンドポイント： GET /api/config
• 現在の設定レスポンス： {}。Zipformer に実行中に変更できるランタイム設定がないためです。

POST /api/config に空でないデータを送ると拒否されます。サービス起動時にエンコーダー、デコーダー、joiner、語彙をまとめて読み込みます。

🛠️ 開発者ガイド（本番環境向け推奨事項）

コードの説明

• web_service.py：
  • REST API：アップロード音声をデコードし、全文の文字起こしを返します。
  • WebSocket API：ストリーミングセッションを維持し、ready、partial、final、error メッセージを出力します。
• task_runtime.py：
  • 音声処理：モノラル 16 kHz 音声から Kaldi 互換のフィルターバンク特徴を生成します。
  • ストリーミング状態：チャンク間でエンコーダーキャッシュ、トークン履歴、タイムスタンプを保持します。
  • RKNN 推論：エンコーダー、デコーダー、joiner のパイプラインを実行します。
• inference.py：単発のコマンドラインファイル文字起こしを提供します。

モデルファイル

モデルの変更

1. 上記のファイル名で、変換済みエンコーダー、デコーダー、joiner を model/ に配置します。
2. 三つの RKNN ファイルは同じ語彙およびストリーミングキャッシュ仕様に対応させます。
3. ファイル全体の推論と、バイナリ PCM の WebSocket ストリーミングの両方を検証します。

これらのファイルは 一本の Zipformer パイプラインの各段階であり、別サイズのモデルではありません。上流プロジェクトは現在、各プラットフォームに 一バンドルを提供しており、独立した量子化選択機能はありません。

ローカルイメージのビルド

reComputer-RK-CV のルートディレクトリから実行します：

docker build -f docker/rk3576/zipformer.dockerfile \
    -t rk3576-zipformer:local src/rk3576_zipformer

docker build -f docker/rk3588/zipformer.dockerfile \
    -t rk3588-zipformer:local src/rk3588_zipformer