Skip to content

README_ja.md

Latest commit

 

History

History
184 lines (132 loc) · 8.03 KB

README_ja.md

File metadata and controls

184 lines (132 loc) · 8.03 KB

(English|简体中文|日本語|한국어)

FunASR OpenAI 互換 API サーバー

FunASR OpenAI 互換 API は /v1/audio/transcriptions を提供します。OpenAI スタイルの SDK、エージェントフレームワーク、Dify、n8n、HTTP ノード、社内システムから、プライベートな音声認識サービスとして利用できます。

クイックスタート

pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000

モデルのロード後にサービスが起動します。ヘルスチェックは GET /health です。

コピーして使える連携例が必要な場合は、クライアントレシピ、JavaScript/TypeScript レシピ、Gradio ブラウザデモ、ワークフローレシピ、Postman コレクション、OpenAPI 仕様、セキュリティとゲートウェイガイド、Kubernetes デプロイテンプレートを参照してください。

エンドツーエンド smoke test

別のターミナルで実行します。

bash smoke_test.sh
# curl/bash を使わないクロスプラットフォーム版:
python smoke_test.py

同等の手動コマンド:

curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
curl http://localhost:8000/health
curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@sample.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

Gradio ブラウザデモ

ローカルブラウザで音声ファイルのアップロードやマイク入力を試したい場合は、先に API サーバーを起動し、オプションの Gradio フロントエンドを起動します。

pip install gradio
python gradio_app.py --base-url http://localhost:8000

このブラウザデモは smoke test と同じ OpenAI 互換 API エンドポイントを呼び出します。Docker、Kubernetes、本番利用の注意点は Gradio ブラウザデモを参照してください。

OpenAI SDK で使う

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

result = client.audio.transcriptions.create(
    model="sensevoice",  # "paraformer", "paraformer-en", "fun-asr-nano" も利用できます
    file=open("meeting.wav", "rb"),
)
print(result.text)

verbose = client.audio.transcriptions.create(
    model="sensevoice",
    file=open("meeting.wav", "rb"),
    response_format="verbose_json",
)
print(verbose.segments)

curl で使う

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

利用できるモデル

Model GPU 速度 CPU 速度 言語 特徴
sensevoice 170x realtime 17x realtime zh/en/ja/ko/yue 感情・イベントタグ
paraformer 120x realtime 15x realtime zh/en 句読点復元
paraformer-en 120x realtime 15x realtime en 英語認識
fun-asr-nano 17x realtime 3.6x realtime 31 languages LLM-based、タイムスタンプ

API エンドポイント

Endpoint Method 説明
/v1/audio/transcriptions POST OpenAI 互換の音声文字起こし
/v1/models GET モデルエイリアスの一覧
/health GET ヘルスチェック、ロード済みモデル、利用可能モデル
/docs GET FastAPI Swagger ドキュメント

コードを書かずに確認したい場合は、Gradio ブラウザデモでローカルアップロードやマイク入力を試すか、Postman コレクションをインポートしてください。API ゲートウェイ、開発者ポータル、社内クライアント生成には OpenAPI 仕様を利用できます。

エージェントとローコードワークフロー

LangChain、LlamaIndex、AutoGen、CrewAI、Semantic Kernel、Dify、n8n、OpenAI audio API または multipart HTTP を使える任意のシステムで利用できます。

Docker デプロイ

デフォルトのイメージは CPU モードで起動し、再現しやすい smoke test として使えます。

cd examples/openai_api
cp .env.example .env

docker compose up --build

同等の docker run:

docker build -t funasr-api .

docker run --rm -p 8000:8000 \
  -e FUNASR_DEVICE=cpu \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

GPU ホストでは NVIDIA Container Toolkit と CUDA 対応の PyTorch/FunASR イメージが必要です。CUDA 依存関係に合わせてイメージを調整した後、次のように起動できます。

docker run --rm --gpus all -p 8000:8000 \
  -e FUNASR_DEVICE=cuda \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

コンテナの検証:

BASE_URL=http://localhost:8000 bash smoke_test.sh
python smoke_test.py --base-url http://localhost:8000

Kubernetes デプロイ

チーム内で共有したりゲートウェイ経由で公開したりする前に、セキュリティとゲートウェイガイドを確認し、TLS、認証、アップロード制限、レート制限、ログ方針を整えてください。

永続化されたモデルキャッシュ、ヘルスプローブ、プライベート ClusterIP を持つ内部クラスタサービスが必要な場合は、Kubernetes デプロイテンプレートから始めてください。サンプルイメージをビルドして push し、manifests を適用した後、kubectl port-forward と python smoke_test.py --base-url http://localhost:8000 で検証します。

CUDA 対応イメージと GPU スケジューリング設定が整うまでは、デフォルトの CPU モードを維持してください。

設定

引数 デフォルト 説明
--host 0.0.0.0 バインドアドレス
--port 8000 ポート
--device cuda cuda、cpu、mps
--model sensevoice 起動時にプリロードするモデル

Docker 環境変数:

Env デフォルト 説明
FUNASR_PORT 8000 server.py に渡すコンテナポート
FUNASR_DEVICE cpu コンテナのデバイスモード。CUDA 対応依存関係を持つイメージでのみ cuda に設定してください
FUNASR_MODEL sensevoice コンテナ起動時にロードするモデルエイリアス

トラブルシューティング

症状 対処
CUDA が利用できない まず --device cpu で smoke test を通します。
8000 ポートが使用中 --port 9000 に変更し、BASE_URL=http://localhost:9000 bash smoke_test.sh または python smoke_test.py --base-url http://localhost:9000 を実行します。
モデルのダウンロードが遅い 安定したネットワークで再試行するか、ModelScope/Hugging Face から事前にモデルをダウンロードします。
Dify/n8n コンテナから localhost に接続できない ワークフロー実行環境から到達できるホスト名、Compose service name、または Kubernetes service name を使います。
応答に segments がない response_format=verbose_json を設定します。