Skip to content

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

docs: align root deployment recipes and CLI help with service contracts

zhifu gao0ae8a84832da
diff --git a/README.md b/README.md
index 4d744c797..76a28661a 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ model = AutoModelVLLM(model="FunAudioLLM/Fun-ASR-Nano-2512", tensor_parallel_siz
results = model.generate(["audio1.wav", "audio2.wav"], language="auto")
```
-> **Deploy as API server:** `funasr-server --device cuda` → OpenAI-compatible endpoint at localhost:8000
+> **Deploy as API server:** [Local SenseVoice CPU recipe](#deploy) · [Nano GPU serving and pinned vLLM setup](./docs/vllm_guide.md)
>
> **Use with AI agents:** [MCP Server](examples/mcp_server/) for Claude/Cursor · [OpenAI API](examples/openai_api/) for LangChain/Dify/AutoGen
>
@@ -253,28 +253,39 @@ Available models: `sensevoice` (default), `paraformer`, `paraformer-en`, `fun-as
## Deploy
+Start a local SenseVoice CPU service from a fresh directory in a POSIX shell with
+Python 3.11. This installs the PyPI release into a separate environment, not this
+source checkout. Keep the unauthenticated service on loopback; use the
+[security guide](./examples/openai_api/SECURITY.md) before exposing it to other clients.
+
```bash
-# OpenAI-compatible API (recommended)
-pip install torch torchaudio
-pip install funasr vllm fastapi uvicorn python-multipart
-funasr-server --device cuda
-# → POST /v1/audio/transcriptions at localhost:8000
-# Joint long-form ASR + anonymous speaker labels (offline HTTP):
-funasr-server --model moss-transcribe-diarize --device cuda:0
+python3.11 -m venv .venv-funasr-http
+. .venv-funasr-http/bin/activate
+python -m pip install torch torchaudio
+python -m pip install funasr fastapi uvicorn python-multipart
+python -m pip check
+funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
```
-[MOSS service, Docker, Kubernetes, vLLM, SGLang, LocalAI, and FunClip guide →](./docs/moss_transcribe_diarize.md)
-
-Verify it with a public sample:
+Wait for model download and server startup. In a second terminal, use the same
+directory and curl 7.76+ to download a public Chinese audio sample and transcribe it.
+The request uses the preloaded model; no fixed transcript or speaker labels are promised.
```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/v1/audio/transcriptions \
+curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
+curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
-F model=sensevoice \
-F response_format=verbose_json
```
+For offline joint ASR and anonymous speaker labels (`moss-transcribe-diarize`), prepare the separate environment
+in the [MOSS service, Docker, Kubernetes, vLLM, SGLang, LocalAI, and FunClip guide →](./docs/moss_transcribe_diarize.md).
+It is an alternative service, not another command in the CPU environment. Stop the
+CPU service before reusing port 8000. For Nano GPU serving, follow the
+[pinned split-engine guide](./docs/vllm_guide.md) and inspect the actual backend logs;
+selecting a model does not by itself prove that vLLM was loaded.
+
```bash
# Docker streaming service
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
diff --git a/README_ja.md b/README_ja.md
index ee5233cce..1d6ecac50 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -62,7 +62,7 @@ VAD 区間への話者割り当てを行います。番号は録音内だけで
初めて使う場合は [Colab クイックスタート](./examples/colab/README_ja.md) から試せます。どのモデルを選ぶか迷う場合は [モデル選択ガイド](./docs/model_selection_ja.md) を参照してください。
-> **APIサーバーとしてデプロイ:** `funasr-server --device cuda` → localhost:8000でOpenAI互換エンドポイント
+> **APIサーバーとしてデプロイ:** [ローカル SenseVoice CPU 手順](#デプロイ) · [Nano GPU 配信と固定版 vLLM 環境](./docs/vllm_guide.md)
>
> **AIエージェント連携:** [MCPサーバー](examples/mcp_server/) Claude/Cursor対応 · [OpenAI API](examples/openai_api/) LangChain/Dify/AutoGen対応
@@ -145,18 +145,43 @@ FunASR はアダプターを提供します。統合経路はオフラインで
## デプロイ
+新しいディレクトリで POSIX shell と Python 3.11 を使い、ローカルの SenseVoice
+CPU サービスを起動します。独立環境に入るのは PyPI のリリースであり、現在の
+ソース checkout ではありません。認証を内蔵しないため loopback で待ち受け、
+他のクライアントへ公開する前に[セキュリティガイド](./examples/openai_api/SECURITY.md)を確認してください。
+
```bash
-# OpenAI互換API(推奨)
-pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
-# オフライン長時間音声 ASR + 匿名 speaker label:
-funasr-server --model moss-transcribe-diarize --device cuda:0
+python3.11 -m venv .venv-funasr-http
+. .venv-funasr-http/bin/activate
+python -m pip install torch torchaudio
+python -m pip install funasr fastapi uvicorn python-multipart
+python -m pip check
+funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
+```
-# Dockerストリーミングサービス
-docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
+モデルのダウンロードと起動を待ちます。別のターミナルで同じディレクトリに入り、
+curl 7.76+ で公開中国語サンプルを取得して認識します。リクエストは事前ロードした
+モデルと一致しますが、固定テキストや話者ラベルを保証する例ではありません。
+
+```bash
+curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
+curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
```
+オフライン ASR と匿名話者ラベルの同時生成(`moss-transcribe-diarize`)には、
[MOSS service / Docker / Kubernetes / vLLM / SGLang / LocalAI / FunClip guide →](./docs/moss_transcribe_diarize.md)
+の独立環境を用意してください。CPU 環境で続けて起動するものではなく、代替サービスです。
+8000 番ポートを再利用する前に CPU サービスを停止します。Nano GPU 配信は
+[固定版の分離エンジンガイド](./docs/vllm_guide.md)に従い、実際の backend ログを確認してください。
+モデルを指定しただけでは vLLM の使用を確認できません。
+
+```bash
+# Dockerストリーミングサービス
+docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
+```
CPU/エッジで Python なしのオフライン ASR が必要な場合は、llama.cpp / GGUF ランタイムを使えます:[funasr.com/deploy/llama-cpp](https://www.funasr.com/en/deploy/llama-cpp.html) · [Fun-ASR-Nano-GGUF](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-GGUF) · [SenseVoiceSmall-GGUF](https://huggingface.co/FunAudioLLM/SenseVoiceSmall-GGUF)。
diff --git a/README_ko.md b/README_ko.md
index 3e48b611b..c09a5b18e 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -61,7 +61,7 @@ CAM++는 `spk_embedding` 벡터를 추출하고, `AutoModel`이 클러스터링
처음 사용한다면 [Colab 빠른 시작](./examples/colab/README_ko.md)으로 먼저 확인할 수 있습니다. 어떤 모델을 선택할지 고민된다면 [모델 선택 가이드](./docs/model_selection_ko.md)를 참고하세요.
-> **API 서버로 배포:** `funasr-server --device cuda` → localhost:8000에서 OpenAI 호환 엔드포인트
+> **API 서버로 배포:** [로컬 SenseVoice CPU 절차](#배포) · [Nano GPU 서빙과 고정 버전 vLLM 환경](./docs/vllm_guide.md)
>
> **AI Agent 연동:** [MCP 서버](examples/mcp_server/) Claude/Cursor 지원 · [OpenAI API](examples/openai_api/) LangChain/Dify/AutoGen 지원
@@ -144,19 +144,44 @@ FunASR는 어댑터를 제공합니다. 통합 경로는 오프라인이고 익
## 배포
+새 디렉터리에서 POSIX shell과 Python 3.11로 로컬 SenseVoice CPU 서비스를 시작합니다.
+현재 소스 checkout이 아니라 PyPI 릴리스를 별도 환경에 설치합니다. 인증을 내장하지
+않으므로 loopback에서만 수신하고, 다른 클라이언트에 공개하기 전에
+[보안 가이드](./examples/openai_api/SECURITY.md)를 확인하세요.
+
+```bash
+python3.11 -m venv .venv-funasr-http
+. .venv-funasr-http/bin/activate
+python -m pip install torch torchaudio
+python -m pip install funasr fastapi uvicorn python-multipart
+python -m pip check
+funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
+```
+
+모델 다운로드와 서버 시작을 기다리세요. 두 번째 터미널에서 같은 디렉터리로 이동한 뒤
+curl 7.76+로 공개 중국어 샘플을 내려받아 전사합니다. 요청은 미리 로드한 모델과
+일치하며, 고정된 텍스트나 화자 라벨을 보장하지 않습니다.
+
```bash
-# OpenAI 호환 API (권장)
-pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
-# 오프라인 장시간 ASR + 익명 speaker label:
-funasr-server --model moss-transcribe-diarize --device cuda:0
+curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
+curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json
+```
+
+오프라인 ASR과 익명 화자 라벨을 함께 생성하려면 (`moss-transcribe-diarize`)
+[MOSS service / Docker / Kubernetes / vLLM / SGLang / LocalAI / FunClip guide →](./docs/moss_transcribe_diarize.md)의
+별도 환경을 준비하세요. 위 CPU 환경에서 이어서 실행하는 명령이 아니라 대체 서비스입니다.
+8000 포트를 다시 쓰기 전에 CPU 서비스를 중지하세요. Nano GPU 서빙은
+[고정 버전 분리 엔진 가이드](./docs/vllm_guide.md)를 따르고 실제 backend 로그를 확인하세요.
+모델 선택만으로 vLLM이 로드되었다고 판단할 수는 없습니다.
+```bash
# Docker 스트리밍 서비스
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
```
-[MOSS service / Docker / Kubernetes / vLLM / SGLang / LocalAI / FunClip guide →](./docs/moss_transcribe_diarize.md)
-
CPU/엣지에서 Python 없이 오프라인 ASR만 필요하다면 llama.cpp / GGUF 런타임을 사용할 수 있습니다: [funasr.com/deploy/llama-cpp](https://www.funasr.com/en/deploy/llama-cpp.html) · [Fun-ASR-Nano-GGUF](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-GGUF) · [SenseVoiceSmall-GGUF](https://huggingface.co/FunAudioLLM/SenseVoiceSmall-GGUF).
**사전 빌드 바이너리:** [Releases](https://github.com/modelscope/FunASR/releases) · [v0.2.6](https://github.com/modelscope/FunASR/releases/tag/runtime-llamacpp-v0.2.6) · [Linux Vulkan tarball](https://github.com/modelscope/FunASR/releases/download/runtime-llamacpp-v0.2.6/funasr-llamacpp-linux-x64-vulkan.tar.gz) · [Windows Vulkan zip](https://github.com/modelscope/FunASR/releases/download/runtime-llamacpp-v0.2.6/funasr-llamacpp-windows-x64-vulkan.zip) · [Windows CUDA zip](https://github.com/modelscope/FunASR/releases/download/runtime-llamacpp-v0.2.6/funasr-llamacpp-windows-x64-cuda.zip) · [Windows Blackwell CUDA zip](https://github.com/modelscope/FunASR/releases/download/runtime-llamacpp-v0.2.6/funasr-llamacpp-windows-x64-cuda-blackwell.zip) · **다운로드와 빠른 시작:** [funasr.com/deploy/llama-cpp](https://www.funasr.com/en/deploy/llama-cpp.html) · **GGUF 모델:** [Hugging Face](https://huggingface.co/FunAudioLLM) · **문서와 벤치마크:** [runtime/llama.cpp/](./runtime/llama.cpp/)
diff --git a/README_zh.md b/README_zh.md
index 46bb71b46..1d63f3bcc 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -103,7 +103,7 @@ model = AutoModelVLLM(model="FunAudioLLM/Fun-ASR-Nano-2512", tensor_parallel_siz
results = model.generate(["audio1.wav", "audio2.wav"], language="auto")
```
-> **部署为 API 服务:** `funasr-server --device cuda` → 本地 OpenAI 兼容接口 localhost:8000
+> **部署为 API 服务:** [本地 SenseVoice CPU 配方](#部署) · [Nano GPU 服务与固定版本 vLLM 环境](./docs/vllm_guide_zh.md)
>
> **接入 AI Agent:** [MCP 服务](examples/mcp_server/) 支持 Claude/Cursor · [OpenAI API](examples/openai_api/README_zh.md) 支持 LangChain/Dify/AutoGen
>
@@ -273,27 +273,36 @@ funasr *.wav --output-format srt --output-dir ./output
## 部署
+在新目录中使用 POSIX shell 和 Python 3.11,启动本地 SenseVoice CPU 服务。
+下面将 PyPI 发布包安装到独立环境,不是安装当前源码 checkout。服务不内置鉴权,
+请保留 loopback 监听;向其他客户端开放前先阅读[安全指南](./examples/openai_api/SECURITY_zh.md)。
+
```bash
-# OpenAI 兼容 API(推荐)
-pip install funasr fastapi uvicorn python-multipart
-funasr-server --model sensevoice --device cuda
-# → POST /v1/audio/transcriptions,地址 localhost:8000
-# 离线长音频联合转写 + 匿名说话人标签:
-funasr-server --model moss-transcribe-diarize --device cuda:0
+python3.11 -m venv .venv-funasr-http
+. .venv-funasr-http/bin/activate
+python -m pip install torch torchaudio
+python -m pip install funasr fastapi uvicorn python-multipart
+python -m pip check
+funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
```
-[MOSS 服务、Docker、Kubernetes、vLLM、SGLang、LocalAI 与 FunClip 部署指南 →](./docs/moss_transcribe_diarize_zh.md)
-
-使用公开样例音频验证服务:
+等待模型下载和服务启动。在第二个终端进入同一目录,使用 curl 7.76+ 下载并转写
+公开的中文样例音频。请求使用已预加载的模型,不保证固定文本或说话人标签。
```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/v1/audio/transcriptions \
+curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
+curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
-F model=sensevoice \
-F response_format=verbose_json
```
+需要离线联合 ASR 与匿名说话人标签(`moss-transcribe-diarize`)时,请按
+[MOSS 服务、Docker、Kubernetes、vLLM、SGLang、LocalAI 与 FunClip 部署指南 →](./docs/moss_transcribe_diarize_zh.md)
+准备独立环境。这是替代服务,不是在上述 CPU 环境中再执行一条命令;复用 8000
+端口前先停止 CPU 服务。Nano GPU 服务请遵循[固定版本的分离引擎指南](./docs/vllm_guide_zh.md),
+并检查实际后端加载日志,不能仅凭模型选择就认定已启用 vLLM。
+
```bash
# Docker 流式服务
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
diff --git a/funasr/bin/server.py b/funasr/bin/server.py
index 3d2d594b6..d1169b9e0 100644
--- a/funasr/bin/server.py
+++ b/funasr/bin/server.py
@@ -1,14 +1,18 @@
"""
FunASR Server — OpenAI-compatible speech recognition API.
+Defaults: host=0.0.0.0, port=8000, device=cuda, model=auto.
+Auto selection: cuda* -> fun-asr-nano; other devices -> sensevoice.
+No API-key authentication is provided; keep local demos on loopback.
+
Usage:
- funasr-server # default: sensevoice on cuda:0, port 8000
- funasr-server --device cpu --port 9000
- funasr-server --model paraformer
- funasr-server --model moss-transcribe-diarize --device cuda:0
- funasr-server --model-path /path/to/local/model
- funasr-server --model-path username/paraformer --hub hf
- funasr-server --cors-origin http://localhost:3000
+ funasr-server --host 127.0.0.1 --model sensevoice --device cpu
+ funasr-server --host 127.0.0.1 --device cpu --port 9000
+ funasr-server --host 127.0.0.1 --model paraformer
+ funasr-server --host 127.0.0.1 --model moss-transcribe-diarize --device cuda:0
+ funasr-server --host 127.0.0.1 --model-path /path/to/local/model
+ funasr-server --host 127.0.0.1 --model-path username/paraformer --hub hf
+ funasr-server --host 127.0.0.1 --cors-origin http://localhost:3000
"""
import argparse
@@ -28,20 +32,29 @@ def build_parser():
description="FunASR OpenAI-Compatible API Server",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
+Defaults: host=0.0.0.0, port=8000, device=cuda, model=auto.
+Auto selection: cuda* -> fun-asr-nano; other devices -> sensevoice.
+For a local example, use the explicit SenseVoice CPU command below.
+Other model/device examples require their own prepared environment.
+
Examples:
- funasr-server # Start with SenseVoice on GPU
- funasr-server --device cpu # Start on CPU
- funasr-server --model paraformer # Use Paraformer model
- funasr-server --model moss-transcribe-diarize --device cuda:0
- funasr-server --port 9000 # Custom port
- funasr-server --model-path /path/to/local/model # Use local model
- funasr-server --model-path username/model --hub hf # Use HuggingFace model
- funasr-server --cors-origin http://localhost:3000 # Allow one browser origin
-
-Then use with OpenAI SDK:
+ funasr-server --host 127.0.0.1 --model sensevoice --device cpu
+ funasr-server --host 127.0.0.1 --model fun-asr-nano --device cuda # Inspect backend logs
+ funasr-server --host 127.0.0.1 --model paraformer
+ funasr-server --host 127.0.0.1 --model moss-transcribe-diarize --device cuda:0
+ funasr-server --host 127.0.0.1 --port 9000 # Custom port
+ funasr-server --host 127.0.0.1 --model-path /path/to/local/model
+ funasr-server --host 127.0.0.1 --model-path username/model --hub hf
+ funasr-server --host 127.0.0.1 --cors-origin http://localhost:3000
+
+For the local SenseVoice example, in a second terminal:
+ python -m pip install openai
+
+Then run Python (api_key is a placeholder, not authentication):
from openai import OpenAI
- client = OpenAI(base_url="http://localhost:8000/v1", api_key="x")
- result = client.audio.transcriptions.create(model="sensevoice", file=open("a.wav","rb"))
+ client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="not-needed")
+ with open("a.wav", "rb") as audio:
+ result = client.audio.transcriptions.create(model="sensevoice", file=audio)
""",
)
parser.add_argument("--host", default="0.0.0.0", help="Bind address (default: 0.0.0.0)")
diff --git a/tests/test_docs_funasr_install_commands.py b/tests/test_docs_funasr_install_commands.py
index b1274c98c..b106919ec 100644
--- a/tests/test_docs_funasr_install_commands.py
+++ b/tests/test_docs_funasr_install_commands.py
@@ -1,11 +1,206 @@
+import io
+import json
import re
+import runpy
import shlex
+import shutil
+import subprocess
+import sys
+import threading
+import wave
+from email.parser import BytesParser
+from email.policy import default as email_policy
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[1]
+ROOT_READMES = {
+ "README.md": "Deploy",
+ "README_zh.md": "部署",
+ "README_ja.md": "デプロイ",
+ "README_ko.md": "배포",
+}
+
+
+def _deployment_blocks(readme):
+ text = (ROOT / readme).read_text()
+ section = text.split(f"## {ROOT_READMES[readme]}\n", 1)[1].split("\n## ", 1)[0]
+ return re.findall(r"^```bash\n(.*?)^```", section, re.M | re.S)
+
+
+def _recipe_commands(block):
+ commands = []
+ for line in block.replace("\\\n", " ").splitlines():
+ lexer = shlex.shlex(line, posix=True, punctuation_chars=True)
+ lexer.whitespace_split = True
+ tokens = list(lexer)
+ current = []
+ for token in tokens:
+ if token == "&&":
+ assert current
+ commands.append(current)
+ current = []
+ else:
+ current.append(token)
+ if current:
+ commands.append(current)
+ return commands
+
+
[email protected](scope="module")
+def server_parser():
+ # Load the real CLI parser without importing FunASR or downloading models.
+ return runpy.run_path(str(ROOT / "funasr/bin/server.py"))["build_parser"]()
+
+
[email protected]("readme", ROOT_READMES)
+def test_root_readme_http_recipe_is_loopback_and_model_consistent(readme, server_parser):
+ blocks = _deployment_blocks(readme)
+ starts = [c for b in blocks for c in _recipe_commands(b) if c[0] == "funasr-server"]
+ assert len(starts) == 1, "MOSS preparation belongs to its separate environment guide"
+ command = starts[0]
+ assert {"--host", "--port", "--model", "--device"}.issubset(command)
+ args = server_parser.parse_args(command[1:])
+ assert (args.host, args.port, args.model, args.device) == ("127.0.0.1", 8000, "sensevoice", "cpu")
+ curl_commands = [c for b in blocks for c in _recipe_commands(b) if c[0] == "curl"]
+ assert len(curl_commands) == 2
+ download, request = curl_commands
+ assert {"--fail", "--location", "-o", "sample.wav"}.issubset(download)
+ assert download[download.index("-o") + 1] == "sample.wav"
+ assert "&&" in next(b for b in blocks if "curl" in b), "Do not send a stale sample after a failed download"
+ assert "--fail-with-body" in request
+ assert f"http://{args.host}:{args.port}/v1/audio/transcriptions" in request
+ forms = [request[i + 1] for i, token in enumerate(request) if token == "-F"]
+ assert forms == ["[email protected]", f"model={args.model}", "response_format=verbose_json"]
+
+
[email protected]("readme", ROOT_READMES)
+def test_root_readme_cpu_install_is_isolated_without_vllm(readme):
+ commands = _recipe_commands(_deployment_blocks(readme)[0])
+ assert commands[:2] == [["python3.11", "-m", "venv", ".venv-funasr-http"],
+ [".", ".venv-funasr-http/bin/activate"]]
+ installs = [c for c in commands if c[:4] == ["python", "-m", "pip", "install"]]
+ assert installs == [["python", "-m", "pip", "install", "torch", "torchaudio"],
+ ["python", "-m", "pip", "install", "funasr", "fastapi", "uvicorn", "python-multipart"]]
+ assert ["python", "-m", "pip", "check"] in commands
+ text = (ROOT / readme).read_text()
+ assert not re.findall(r"`funasr-server[^`]*`", text), "Link to a prepared recipe instead of an unprepared inline launch"
+ suffix = "_zh" if readme == "README_zh.md" else ""
+ for link in [f"./docs/moss_transcribe_diarize{suffix}.md",
+ f"./examples/openai_api/SECURITY{suffix}.md"]:
+ assert f"]({link})" in text
+ assert (ROOT / link).is_file()
+
+
+def test_root_readme_http_commands_are_identical_in_four_languages():
+ recipes = [[_recipe_commands(b) for b in _deployment_blocks(readme)[:2]] for readme in ROOT_READMES]
+ assert all(recipe == recipes[0] for recipe in recipes[1:])
+
+
+def test_server_help_describes_auto_selection_and_a_matching_sdk_recipe(server_parser):
+ default = server_parser.parse_args([])
+ assert (default.host, default.port, default.device, default.model) == ("0.0.0.0", 8000, "cuda", "auto")
+ module = runpy.run_path(str(ROOT / "funasr/bin/server.py"))
+ usage = module["__doc__"]
+ help_text = server_parser.format_help()
+ for text in [usage, help_text]:
+ assert "cuda* -> fun-asr-nano; other devices -> sensevoice" in text
+ assert "default: sensevoice" not in text.lower()
+ commands = re.findall(r"^\s*(funasr-server[^#\n]*)", text, re.M)
+ parsed = [server_parser.parse_args(shlex.split(c)[1:]) for c in commands]
+ assert any(a.model == "sensevoice" and a.device == "cpu" and a.host == "127.0.0.1" for a in parsed)
+ assert all("--host" in shlex.split(c) for c in commands)
+ assert all(a.host == "127.0.0.1" for a in parsed)
+ assert 'with open("a.wav", "rb") as audio:' in help_text
+ assert 'model="sensevoice", file=audio' in help_text
+ assert "python -m pip install openai" in help_text
+ assert "placeholder, not authentication" in help_text
+
+
+def test_readme_venv_activation_works_in_posix_sh(tmp_path):
+ env = tmp_path / ".venv-funasr-http"
+ subprocess.run([sys.executable, "-m", "venv", "--without-pip", str(env)], check=True, timeout=30)
+ activation = _deployment_blocks("README.md")[0].splitlines()[1]
+ result = subprocess.run(["sh", "-c", activation + " && command -v python"],
+ cwd=tmp_path, capture_output=True, text=True, timeout=10)
+ assert result.returncode == 0, result.stderr
+ assert result.stdout.strip() == str(env / "bin/python")
+
+
[email protected]("download_status,transcription_status", [(200, 200), (503, 200), (200, 422)])
+def test_readme_curl_recipe_uploads_exact_sample_and_propagates_errors(
+ tmp_path, download_status, transcription_status
+):
+ assert shutil.which("curl"), "curl is required to check the published shell recipe"
+ buffer = io.BytesIO()
+ with wave.open(buffer, "wb") as audio:
+ audio.setnchannels(1)
+ audio.setsampwidth(2)
+ audio.setframerate(16000)
+ audio.writeframes(b"\0\0" * 160)
+ sample = buffer.getvalue()
+ requests = []
+
+ class Handler(BaseHTTPRequestHandler):
+ def log_message(self, *_args):
+ pass
+
+ def do_GET(self):
+ requests.append(("GET", self.path))
+ body = sample if download_status == 200 else b"sample unavailable"
+ self.send_response(download_status)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def do_POST(self):
+ self.connection.settimeout(5)
+ body = self.rfile.read(int(self.headers["Content-Length"]))
+ message = BytesParser(policy=email_policy).parsebytes(
+ f"Content-Type: {self.headers['Content-Type']}\r\n\r\n".encode() + body
+ )
+ fields = {part.get_param("name", header="content-disposition"): part.get_payload(decode=True)
+ for part in message.iter_parts()}
+ requests.append(("POST", self.path, fields))
+ response = json.dumps({"text": "fixture"} if transcription_status == 200 else {"error": "fixture failure"}).encode()
+ self.send_response(transcription_status)
+ self.send_header("Content-Length", str(len(response)))
+ self.send_header("Content-Type", "application/json")
+ self.end_headers()
+ self.wfile.write(response)
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ try:
+ recipe = _deployment_blocks("README.md")[1]
+ download, request = _recipe_commands(recipe)
+ source_url = next(token for token in download if token.startswith("https://"))
+ target_url = next(token for token in request if token.startswith("http://"))
+ origin = f"http://127.0.0.1:{server.server_port}"
+ recipe = recipe.replace(source_url, origin + "/sample.wav").replace(target_url, origin + "/v1/audio/transcriptions")
+ (tmp_path / "sample.wav").write_bytes(b"stale sample must not be uploaded")
+ result = subprocess.run(["bash", "-c", recipe], cwd=tmp_path, capture_output=True, text=True, timeout=15)
+ assert requests[0] == ("GET", "/sample.wav")
+ if download_status != 200:
+ assert result.returncode != 0
+ assert len(requests) == 1
+ else:
+ assert requests[1] == ("POST", "/v1/audio/transcriptions", {
+ "file": sample, "model": b"sensevoice", "response_format": b"verbose_json",
+ })
+ assert len(requests) == 2
+ assert (result.returncode == 0) == (transcription_status == 200)
+ assert json.loads(result.stdout) == ({"text": "fixture"} if transcription_status == 200 else {"error": "fixture failure"})
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=5)
+ assert not thread.is_alive()
+
DOCS_WITH_CURRENT_FUNASR_INSTALL = [
"examples/industrial_data_pretraining/fun_asr_nano/docs/finetune.md",