Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
docs: localize OpenAI API guide for Japanese and Korean
zhifu gaodaaa1d4ca4b8
diff --git a/README_ja.md b/README_ja.mdindex d0593dfb0..34d1c95f9 100644--- a/README_ja.md+++ b/README_ja.md@@ -132,7 +132,7 @@ funasr-server --device cudadocker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)+[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/README_ja.md) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/README_ko.md b/README_ko.mdindex d2e83b89f..981b33c24 100644--- a/README_ko.md+++ b/README_ko.md@@ -132,7 +132,7 @@ funasr-server --device cudadocker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)+[Colab quickstart →](./examples/colab/) · [OpenAI API example →](./examples/openai_api/README_ko.md) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [OpenAPI spec →](./examples/openai_api/OPENAPI.md) · [Security guide →](./examples/openai_api/SECURITY.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/examples/openai_api/README.md b/examples/openai_api/README.mdindex fd58bdbf0..cd4b0d6d9 100644--- a/examples/openai_api/README.md+++ b/examples/openai_api/README.md@@ -1,4 +1,4 @@-(English|[简体中文](README_zh.md))+(English|[简体中文](README_zh.md)|[日本語](README_ja.md)|[한국어](README_ko.md))# FunASR OpenAI-Compatible API Serverdiff --git a/examples/openai_api/README_ja.md b/examples/openai_api/README_ja.mdnew file mode 100644index 000000000..94159001d--- /dev/null+++ b/examples/openai_api/README_ja.md@@ -0,0 +1,184 @@+([English](README.md)|[简体中文](README_zh.md)|日本語|[한국어](README_ko.md))++# FunASR OpenAI 互換 API サーバー++FunASR OpenAI 互換 API は `/v1/audio/transcriptions` を提供します。OpenAI スタイルの SDK、エージェントフレームワーク、Dify、n8n、HTTP ノード、社内システムから、プライベートな音声認識サービスとして利用できます。++## クイックスタート++```bash+pip install funasr fastapi uvicorn python-multipart+python server.py --model sensevoice --device cuda --port 8000+```++モデルのロード後にサービスが起動します。ヘルスチェックは `GET /health` です。++コピーして使える連携例が必要な場合は、[クライアントレシピ](CLIENTS.md)、[JavaScript/TypeScript レシピ](JAVASCRIPT.md)、[Gradio ブラウザデモ](GRADIO.md)、[ワークフローレシピ](WORKFLOWS.md)、[Postman コレクション](POSTMAN.md)、[OpenAPI 仕様](OPENAPI.md)、[セキュリティとゲートウェイガイド](SECURITY.md)、[Kubernetes デプロイテンプレート](kubernetes/README.md)を参照してください。++### エンドツーエンド smoke test++別のターミナルで実行します。++```bash+bash smoke_test.sh+# curl/bash を使わないクロスプラットフォーム版:+python smoke_test.py+```++同等の手動コマンド:++```bash+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 [email protected] \+ -F model=sensevoice \+ -F response_format=verbose_json+```++## Gradio ブラウザデモ++ローカルブラウザで音声ファイルのアップロードやマイク入力を試したい場合は、先に API サーバーを起動し、オプションの Gradio フロントエンドを起動します。++```bash+pip install gradio+python gradio_app.py --base-url http://localhost:8000+```++このブラウザデモは smoke test と同じ OpenAI 互換 API エンドポイントを呼び出します。Docker、Kubernetes、本番利用の注意点は [Gradio ブラウザデモ](GRADIO.md)を参照してください。++## OpenAI SDK で使う++```python+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 で使う++```bash+curl http://localhost:8000/v1/audio/transcriptions \+ -F [email protected] \+ -F model=sensevoice++curl http://localhost:8000/v1/audio/transcriptions \+ -F [email protected] \+ -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 ブラウザデモ](GRADIO.md)でローカルアップロードやマイク入力を試すか、[Postman コレクション](POSTMAN.md)をインポートしてください。API ゲートウェイ、開発者ポータル、社内クライアント生成には [OpenAPI 仕様](OPENAPI.md)を利用できます。++## エージェントとローコードワークフロー++**LangChain**、**LlamaIndex**、**AutoGen**、**CrewAI**、**Semantic Kernel**、**Dify**、**n8n**、OpenAI audio API または multipart HTTP を使える任意のシステムで利用できます。++- SDK、JavaScript/TypeScript、Agent tool の書き方は [クライアントレシピ](CLIENTS.md) と [JavaScript/TypeScript レシピ](JAVASCRIPT.md)を参照してください。+- Dify、n8n、HTTP ノード、webhook worker は [ワークフローレシピ](WORKFLOWS.md)を参照してください。+- GUI smoke test は [Postman コレクション](POSTMAN.md)を参照してください。+- schema-driven import には [OpenAPI 仕様](OPENAPI.md)を使えます。++## Docker デプロイ++デフォルトのイメージは CPU モードで起動し、再現しやすい smoke test として使えます。++```bash+cd examples/openai_api+cp .env.example .env++docker compose up --build+```++同等の `docker run`:++```bash+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 依存関係に合わせてイメージを調整した後、次のように起動できます。++```bash+docker run --rm --gpus all -p 8000:8000 \+ -e FUNASR_DEVICE=cuda \+ -e FUNASR_MODEL=sensevoice \+ funasr-api+```++コンテナの検証:++```bash+BASE_URL=http://localhost:8000 bash smoke_test.sh+python smoke_test.py --base-url http://localhost:8000+```++## Kubernetes デプロイ++チーム内で共有したりゲートウェイ経由で公開したりする前に、[セキュリティとゲートウェイガイド](SECURITY.md)を確認し、TLS、認証、アップロード制限、レート制限、ログ方針を整えてください。++永続化されたモデルキャッシュ、ヘルスプローブ、プライベート `ClusterIP` を持つ内部クラスタサービスが必要な場合は、[Kubernetes デプロイテンプレート](kubernetes/README.md)から始めてください。サンプルイメージをビルドして 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` を設定します。 |diff --git a/examples/openai_api/README_ko.md b/examples/openai_api/README_ko.mdnew file mode 100644index 000000000..3a446a7a7--- /dev/null+++ b/examples/openai_api/README_ko.md@@ -0,0 +1,184 @@+([English](README.md)|[简体中文](README_zh.md)|[日本語](README_ja.md)|한국어)++# FunASR OpenAI 호환 API 서버++FunASR OpenAI 호환 API는 `/v1/audio/transcriptions`를 제공합니다. OpenAI 스타일 SDK, 에이전트 프레임워크, Dify, n8n, HTTP 노드, 내부 업무 시스템에서 프라이빗 음성 인식 서비스로 사용할 수 있습니다.++## 빠른 시작++```bash+pip install funasr fastapi uvicorn python-multipart+python server.py --model sensevoice --device cuda --port 8000+```++모델 로드가 끝나면 서비스가 시작됩니다. 헬스 체크는 `GET /health`입니다.++바로 복사해서 쓸 수 있는 연동 예제가 필요하면 [클라이언트 레시피](CLIENTS.md), [JavaScript/TypeScript 레시피](JAVASCRIPT.md), [Gradio 브라우저 데모](GRADIO.md), [워크플로 레시피](WORKFLOWS.md), [Postman 컬렉션](POSTMAN.md), [OpenAPI 명세](OPENAPI.md), [보안 및 게이트웨이 가이드](SECURITY.md), [Kubernetes 배포 템플릿](kubernetes/README.md)을 참고하세요.++### 엔드투엔드 smoke test++다른 터미널에서 실행합니다.++```bash+bash smoke_test.sh+# curl/bash가 없는 환경을 위한 크로스 플랫폼 방식:+python smoke_test.py+```++동일한 수동 명령:++```bash+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 [email protected] \+ -F model=sensevoice \+ -F response_format=verbose_json+```++## Gradio 브라우저 데모++로컬 브라우저에서 파일 업로드나 마이크 입력을 테스트하려면 먼저 API 서버를 시작한 뒤 선택 사항인 Gradio 프런트엔드를 실행합니다.++```bash+pip install gradio+python gradio_app.py --base-url http://localhost:8000+```++이 브라우저 데모는 smoke test와 동일한 OpenAI 호환 API 엔드포인트를 호출합니다. Docker, Kubernetes, 프로덕션 참고 사항은 [Gradio 브라우저 데모](GRADIO.md)를 확인하세요.++## OpenAI SDK로 사용하기++```python+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로 사용하기++```bash+curl http://localhost:8000/v1/audio/transcriptions \+ -F [email protected] \+ -F model=sensevoice++curl http://localhost:8000/v1/audio/transcriptions \+ -F [email protected] \+ -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 브라우저 데모](GRADIO.md)로 로컬 업로드나 마이크 테스트를 진행하거나 [Postman 컬렉션](POSTMAN.md)을 가져오세요. API 게이트웨이, 개발자 포털, 내부 클라이언트 생성을 위해서는 [OpenAPI 명세](OPENAPI.md)를 사용할 수 있습니다.++## 에이전트 및 로우코드 워크플로++**LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, OpenAI audio API 또는 multipart HTTP를 지원하는 모든 시스템에서 사용할 수 있습니다.++- SDK, JavaScript/TypeScript, Agent tool 작성법은 [클라이언트 레시피](CLIENTS.md)와 [JavaScript/TypeScript 레시피](JAVASCRIPT.md)를 참고하세요.+- Dify, n8n, HTTP 노드, webhook worker는 [워크플로 레시피](WORKFLOWS.md)를 참고하세요.+- GUI smoke test는 [Postman 컬렉션](POSTMAN.md)을 참고하세요.+- schema 기반 가져오기는 [OpenAPI 명세](OPENAPI.md)를 사용할 수 있습니다.++## Docker 배포++기본 이미지는 CPU 모드로 시작하므로 재현 가능한 smoke test로 사용할 수 있습니다.++```bash+cd examples/openai_api+cp .env.example .env++docker compose up --build+```++동일한 `docker run` 명령:++```bash+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 의존성에 맞게 이미지를 조정한 뒤 다음처럼 실행할 수 있습니다.++```bash+docker run --rm --gpus all -p 8000:8000 \+ -e FUNASR_DEVICE=cuda \+ -e FUNASR_MODEL=sensevoice \+ funasr-api+```++컨테이너 검증:++```bash+BASE_URL=http://localhost:8000 bash smoke_test.sh+python smoke_test.py --base-url http://localhost:8000+```++## Kubernetes 배포++팀에서 공유하거나 게이트웨이를 통해 노출하기 전에 [보안 및 게이트웨이 가이드](SECURITY.md)를 검토하고 TLS, 인증, 업로드 제한, 속도 제한, 로그 정책을 준비하세요.++영구 모델 캐시, 헬스 프로브, 프라이빗 `ClusterIP`를 갖춘 내부 클러스터 서비스가 필요하다면 [Kubernetes 배포 템플릿](kubernetes/README.md)에서 시작하세요. 예제 이미지를 빌드하고 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`를 설정하세요. |diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.mdindex 247874112..6486cd079 100644--- a/examples/openai_api/README_zh.md+++ b/examples/openai_api/README_zh.md@@ -1,4 +1,4 @@-([English](README.md)|简体中文)+([English](README.md)|简体中文|[日本語](README_ja.md)|[한국어](README_ko.md))# FunASR OpenAI 兼容 API 服务