FunASR/docs/deployment_matrix_ja.md

FunASR デプロイ選択マトリクス

プロダクト、デモ、ベンチマーク、社内ワークフローに合わせて最短のデプロイ経路を選ぶためのガイドです。まずは要件を満たす最小構成から始め、throughput、latency、integration 要件が明確になったら重い runtime に移行してください。

クイック判断表

Path	向いている用途	最初に読むもの	運用メモ
Colab notebook	ブラウザ smoke test、初回評価、共有 demo	Colab クイックスタート	ローカル環境不要。初回はモデルをダウンロードし、GPU runtime の方が高速です。
Python API	Notebook、offline job、最初の model evaluation	README quick start	最小構成。batching、retry、file 管理は呼び出し側で扱います。
OpenAI 互換 API	Private speech API、Agent、Dify/LangChain/AutoGen style clients	OpenAI API example	OpenAI audio API に対応した既存 app に最も接続しやすい経路です。
Docker Compose API	再現可能な local smoke test、小さな internal service	OpenAI API Docker docs	デフォルトは CPU。CUDA を使う前に CUDA-capable image へ調整してください。
Kubernetes API	Cluster service 向け internal speech API	Kubernetes template	private ClusterIP から開始。公開範囲を広げる前に auth、TLS、network policy、GPU scheduling を追加します。
Runtime WebSocket service	Live captions、meeting、call-center stream	Runtime service docs	partial result、endpointing、long-lived audio stream が重要な場合に使います。
vLLM acceleration	Fun-ASR-Nano の native ファイル文字起こし、または split-engine デコード	公式 native 検証（英語）、split-engine guide	2 つの経路は checkpoint と API が異なります。非自己回帰の Paraformer には適用しません。
MOSS-Transcribe-Diarize	長時間の複数話者 transcription、timestamp、speaker label	Third-party MOSS guide	OpenMOSS の Apache-2.0 model を FunASR AutoModel に統合済みです。local HF（backend="hf"）、vLLM（backend="vllm"）、または SGLang Omni（backend="sglang"）を選択できます。model の公開・保守主体は OpenMOSS のままです。
MCP server	Claude/Cursor/desktop agent の speech tool	MCP example	ASR 結果を local tool として Agent に渡したい場合に便利です。
Subtitle generator	長時間 audio/video から SRT/VTT 作成	Subtitle example	readability が重要な場合は verbose segment と speaker label を使います。
Batch ASR script	Archive、meeting、dataset、繰り返し offline run	Batch example	production では queue、manifest、retry log を追加してください。

よくある選択

Fun-ASR-Nano を vLLM で動かしたい

• Split-engine: 基本モデル FunAudioLLM/Fun-ASR-Nano-2512 を使い、FunASR 側で音声を処理して LLM decoder を vLLM で実行します。split-engine guideを参照してください。
• Native: vLLM 自身が音声モデルを実行します。公式 checkpoint は FunAudioLLM/Fun-ASR-Nano-2512-vllm です。基本モデル用の設定や checkpoint と相互に置き換えないでください。

公式 native 検証記録（英語）は、モデル revision a4362c943d48951f98ca2a62181cc028970270c5、vLLM 0.27.1、既存の H100 環境での機能確認です。 モデル revision は FunASR パッケージのバージョンではありません。依存関係を含む準備・起動手順は検証記録を参照してください。

確認した API はファイル入力の /v1/audio/transcriptions です。/v1/realtime、クリーンインストール、長時間音声、話者分離、本番の処理容量はこの検証の対象ではありません。FunASR SDK や別の checkpoint の検証として扱わず、実運用の音声・負荷で別途評価してください。

5分で FunASR を試したい

ブラウザだけで試すなら Colab クイックスタート を使います。ローカルで作業する場合は README の Python API から始めます。どのモデルを使うか迷う場合は モデル選択ガイド を参照してください。

Cloud transcription の local replacement が欲しい

OpenAI 互換 API を使います。主な入口は次のとおりです。

• /v1/audio/transcriptions: ファイル文字起こし
• /v1/models: モデル一覧
• /health: ヘルスチェック
• Swagger docs: API の確認

まず sensevoice で smoke test を実行し、既存 SDK や HTTP client を OpenAI API example に合わせて接続してください。

再現可能な container demo が欲しい

Docker Engine と Docker Compose plugin を用意し、FunASR リポジトリのルートからローカルの SenseVoice CPU service を起動します。このコマンドは既存の .env を上書きしません。明示した port、device、model は、この起動に限り環境から継承した値より優先されます。ホスト側は loopback のみで待ち受けますが、認証 gateway ではありません。共有前に security guide（英語） を確認してください。

FUNASR_HOST_PORT=127.0.0.1:8000 FUNASR_DEVICE=cpu FUNASR_MODEL=sensevoice \
  docker compose -f examples/openai_api/docker-compose.yml up --build

Compose はそのターミナルで実行したままにします。別のターミナルを開き、同じリポジトリのルートで Python 3.10 以降を使って確認します。smoke client は標準ライブラリのみを使うため、ホストへの FunASR のインストールは不要です。

python3 examples/openai_api/smoke_test.py --base-url http://127.0.0.1:8000 --model sensevoice --response-format verbose_json

現在のディレクトリに sample.wav がなければ公開の中国語音声をダウンロードし、既存ファイルがあれば再利用します。health、model metadata、文字起こし JSON が表示されます。テキストは自分で確認してください。終了コードの成功だけでは認識精度や同時実行性能は検証できません。client は Authorization を送信せず、security guide の文字起こし専用 gateway はこの smoke が使う metadata route を拒否します。ローカル endpoint で実行し、機密音声や未加工の出力を残さないでください。

CPU image は example server をコピーしますが、FunASR は PyPI からインストールします。依存バージョンは固定されていません。再現性を主張する前に実際の package version と image digest を記録してください。FUNASR_DEVICE の変更だけでは CUDA 依存や container の GPU access は追加されません。GPU image と scheduling は別途用意して検証し、HTTP deployment guide（英語） とモデルの要件を確認してください。

Streaming または live captioning が必要

Runtime WebSocket service を使います。本番投入前に chunk size、VAD、endpointing、punctuation、speaker diarization、reconnect、client backpressure を実音声で検証してください。

Readiness checklist

• model alias を決め、deployment note に固定します。
• FunASR version、model version、device、CUDA/PyTorch version、Docker image tag、command line を記録します。
• public smoke sample と realistic private sample を少なくとも 1 つずつ実行します。
• request ごとに audio duration、model、device、latency、response format、error type をログ化します。
• trusted network の外へ API を出す前に upload-size limit、authentication、TLS、rate limit を入れます。Security guide も確認してください。
• 詰まったら deployment path、command/config、logs、model、device、audio characteristics を添えて Deployment Help issue を開いてください。