Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: localize OpenAI API guide for Japanese and Korean

zhifu gaodaaa1d4ca4b8
diff --git a/README_ja.md b/README_ja.md
index d0593dfb0..34d1c95f9 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -132,7 +132,7 @@ funasr-server --device cuda
docker 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.md
index d2e83b89f..981b33c24 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -132,7 +132,7 @@ funasr-server --device cuda
docker 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.md
index 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 Server
diff --git a/examples/openai_api/README_ja.md b/examples/openai_api/README_ja.md
new file mode 100644
index 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 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 model=sensevoice
+
+curl http://localhost:8000/v1/audio/transcriptions \
+ -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.md
new file mode 100644
index 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 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 model=sensevoice
+
+curl http://localhost:8000/v1/audio/transcriptions \
+ -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.md
index 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 服务