Skip to content

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

docs: rebuild the learning, model and serving documentation system

zhifu gaof958aab5b8bd
diff --git a/.github/workflows/product-site.yml b/.github/workflows/product-site.yml
index 0c28c96e4..70fbc2681 100644
--- a/.github/workflows/product-site.yml
+++ b/.github/workflows/product-site.yml
@@ -3,7 +3,13 @@ name: Product site
on:
pull_request:
paths:
+ - 'README*.md'
- 'docs/**/*.md'
+ - 'model_zoo/**/*.md'
+ - 'runtime/**/*.md'
+ - 'examples/openai_api/**/*.md'
+ - 'scripts/gen_api_docs.py'
+ - 'tests/test_*docs*.py'
- 'gh-pages-output/**'
- 'web-pages/product-site/**'
- 'web-pages/scripts/**'
@@ -12,7 +18,13 @@ on:
push:
branches: [main]
paths:
+ - 'README*.md'
- 'docs/**/*.md'
+ - 'model_zoo/**/*.md'
+ - 'runtime/**/*.md'
+ - 'examples/openai_api/**/*.md'
+ - 'scripts/gen_api_docs.py'
+ - 'tests/test_*docs*.py'
- 'gh-pages-output/**'
- 'web-pages/product-site/**'
- 'web-pages/scripts/**'
@@ -35,6 +47,17 @@ jobs:
run: python -m pip install -r web-pages/product-site/requirements-site.txt
- name: Run product-site tests
run: python -m pytest web-pages/product-site/tests -q
+ - name: Run model-free documentation contracts
+ run: >-
+ python -m pytest
+ tests/test_learning_docs_contract.py
+ tests/test_training_docs_contract.py
+ tests/test_python_api_docs_contract.py
+ tests/test_service_docs_contract.py
+ tests/test_generated_api_docs.py
+ tests/test_docs_funasr_install_commands.py
+ tests/test_moss_transcribe_diarize_docs.py
+ -k 'not no_download_toy_against_checkout and not browser_navigation_and_responsive_overflow and not skip_link_preserves_selection_playwright' -q
- name: Build and validate twice
run: |
python web-pages/product-site/build.py --output /tmp/funasr-site-a
@@ -68,6 +91,13 @@ jobs:
run: npm ci
- name: Install Chromium
run: npx playwright install --with-deps chromium
+ - name: Install API browser test driver
+ run: python -m pip install playwright==1.55.0
+ - name: Check generated API interactions
+ working-directory: .
+ run: >-
+ python -m pytest tests/test_generated_api_docs.py
+ -k 'browser_navigation_and_responsive_overflow or skip_link_preserves_selection_playwright' -q
- name: Run browser tests
env:
SITE_PYTHON: python
diff --git a/.github/workflows/update-api-docs.yml b/.github/workflows/update-api-docs.yml
index 25dda74df..1992f9757 100644
--- a/.github/workflows/update-api-docs.yml
+++ b/.github/workflows/update-api-docs.yml
@@ -7,7 +7,10 @@ on:
- 'funasr/**/*.py'
- 'scripts/gen_api_docs.py'
- 'training.html'
- - 'docs/moss_transcribe_diarize*.md'
+ - 'docs/**/*.md'
+ - 'examples/openai_api/**/*.md'
+ - 'runtime/**/*.md'
+ - 'web-pages/product-site/**'
- 'model_zoo/**'
- 'gh-pages-output/**'
- '.github/workflows/update-api-docs.yml'
@@ -27,6 +30,13 @@ jobs:
- name: Generate API docs
run: python3 scripts/gen_api_docs.py
+ - name: Render shared documentation sources
+ run: |
+ python3 -m pip install -r web-pages/product-site/requirements-site.txt
+ python3 web-pages/product-site/build.py --output /tmp/funasr-docs-site
+ python3 web-pages/product-site/validate.py /tmp/funasr-docs-site
+ python3 web-pages/product-site/export_docs.py --site /tmp/funasr-docs-site --output gh-pages-output
+
- name: Deploy to gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
diff --git a/README.md b/README.md
index 2bec4ff32..b75b1fd03 100644
--- a/README.md
+++ b/README.md
@@ -183,7 +183,7 @@ Requirements: Python ≥ 3.8. Install PyTorch + torchaudio first ([pytorch.org](
## Usage
-> Full examples with parameter docs: [Tutorial →](https://modelscope.github.io/FunASR/tutorial.html)
+> [Python tutorial](./docs/tutorial/README.md) · [SDK parameters and outputs](./docs/python_api.md) · [Training](./docs/training.md) · [Model registration](./docs/model_registration.md)
```python
from funasr import AutoModel
@@ -350,6 +350,9 @@ inference on physical Blackwell hardware.
## Community
+Start with [troubleshooting](./docs/troubleshooting.md) before reporting a problem.
+Include your exact model, runtime, environment and a minimal reproduction.
+
| | |
|---|---|
| 📖 [Documentation](https://modelscope.github.io/FunASR/) | 🐛 [Issues](https://github.com/modelscope/FunASR/issues) |
diff --git a/README_zh.md b/README_zh.md
index c2ccd7187..c7196d88d 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -202,7 +202,7 @@ pip install -e ./
## 使用示例
-> 完整参数文档:[教程 →](https://modelscope.github.io/FunASR/zh/tutorial.html)
+> [Python 教程](./docs/tutorial/README_zh.md) · [SDK 参数与输出](./docs/python_api_zh.md) · [训练与微调](./docs/training_zh.md) · [模型注册](./docs/model_registration_zh.md)
```python
from funasr import AutoModel
@@ -343,6 +343,8 @@ Blackwell 实机上完成推理验证。
## 社区
+反馈问题前先查阅[故障排查](./docs/troubleshooting_zh.md),并附上确切模型、运行时、环境与最小复现。
+
| | |
|---|---|
| 📖 [文档](https://modelscope.github.io/FunASR/zh/) | 🐛 [问题反馈](https://github.com/modelscope/FunASR/issues) |
diff --git a/docs/README.md b/docs/README.md
index e43272db8..1967d4213 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,17 +2,27 @@
[中文文档](https://www.funasr.com/docs/) |
[English documentation](https://www.funasr.com/en/docs/) |
-[Model Zoo](../model_zoo/modelscope_models.md) |
+[Model Zoo](../model_zoo/readme.md) |
[Releases](https://github.com/modelscope/FunASR/releases)
## Start Here
| Your task | Guide |
| --- | --- |
+| Install and check the Python environment | [Installation](installation/installation.md) / [中文](installation/installation_zh.md) |
| Choose a model, language, or timestamp capability | [Model selection](model_selection.md) / [中文](model_selection_zh.md) |
-| Run the first transcription | [Quickstart](https://www.funasr.com/en/quickstart.html) / [CLI](cli.md) |
+| Run the first transcription | [Quickstart](tutorial/README.md) / [中文](tutorial/README_zh.md) / [CLI](cli.md) |
+| Configure AutoModel, generate, and streaming cache | [Python SDK](python_api.md) / [中文](python_api_zh.md) |
| Move from Whisper or a cloud API | [Migration](migration_from_whisper.md) / [中文](migration_from_whisper_zh.md) |
+## Train and Extend
+
+| Your task | Guide |
+| --- | --- |
+| Select a recipe, prepare data, train and evaluate | [Fine-tuning](training.md) / [中文](training_zh.md) |
+| Add a custom architecture to AutoModel | [Model registration](model_registration.md) / [中文](model_registration_zh.md) |
+| Locate supported checkpoints and individual licenses | [Model Zoo](../model_zoo/readme.md) / [中文](../model_zoo/readme_zh.md) |
+
## Models and Deployment
| Your task | Guide |
@@ -22,6 +32,18 @@
| Accelerate with the FunASR vLLM split engine | [vLLM](vllm_guide.md) / [中文](vllm_guide_zh.md) |
| Evaluate native vLLM serving | [Validation record](vllm_native_funasr_validation.md) |
| Deploy llama.cpp, TensorRT, Docker or Kubernetes | [Deployment manuals](https://www.funasr.com/en/deploy/) |
+| Choose a service entry point and runtime SDK | [Runtime guide](../runtime/readme.md) / [中文](../runtime/readme_cn.md) |
+| Select a development or serving container | [Docker](installation/docker.md) / [中文](installation/docker_zh.md) |
+| Expose a Python HTTP transcription service | [Server](../examples/openai_api/README.md) / [中文](../examples/openai_api/README_zh.md) |
+
+## Integrate Against a Contract
+
+Python SDK, Python HTTP, native vLLM HTTP and C++ WebSocket are different
+interfaces. Choose the matching protocol before selecting a client.
+
+- [HTTP schema](../examples/openai_api/OPENAPI.md), [JavaScript](../examples/openai_api/JAVASCRIPT.md), [workflow integration](../examples/openai_api/WORKFLOWS.md)
+- [C++ WebSocket protocol](../runtime/docs/websocket_protocol.md) and [ONNX binary output](../runtime/docs/onnxruntime_binary_output.md)
+- [HTTP security](../examples/openai_api/SECURITY.md) and [Kubernetes manifests](../examples/openai_api/kubernetes/README.md)
## Evaluate and Operate
@@ -32,6 +54,10 @@
The product-site documentation is rendered from these Markdown sources. Edit the
source once; the site build updates article content, navigation and local search.
The catalogue lives in [documentation.json](../web-pages/product-site/data/documentation.json).
+The established GitHub Pages tutorial, training and model-registration URLs are
+generated from the same guides. The API reference is separately extracted from
+Python source. Historical C++ release notes remain in the
+[runtime archive](../runtime/release-history.md); they are not current deployment recommendations.
Model weights retain their individual licenses; the FunASR toolkit is MIT licensed.
## Build the Product Documentation
@@ -42,6 +68,8 @@ From the repository root:
python -m pip install -r web-pages/product-site/requirements-site.txt
python web-pages/product-site/build.py --output /tmp/funasr-docs
python web-pages/product-site/validate.py /tmp/funasr-docs
+python scripts/gen_api_docs.py
+python web-pages/product-site/export_docs.py --site /tmp/funasr-docs --output gh-pages-output
python -m http.server --directory /tmp/funasr-docs 8000
```
@@ -52,7 +80,7 @@ For convenience, we provide users with the ability to generate local HTML manual
First, you should install the following packages, which is required for building HTML:
```sh
-pip3 install -U "funasr[docs]"
+pip3 install -U "funasr[doc]"
```
Then you can generate HTML manually.
diff --git a/docs/index.rst b/docs/index.rst
index a5aa91fdb..b3d41aa7d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,13 +13,28 @@ entry to these guides. Source Markdown remains in this repository.
:caption: Get Started
installation/installation
+ installation/installation_zh
installation/docker
+ installation/docker_zh
+ tutorial/README
+ tutorial/README_zh
+ python_api
+ python_api_zh
model_selection
model_selection_zh
cli
migration_from_whisper
migration_from_whisper_zh
+.. toctree::
+ :maxdepth: 1
+ :caption: Train and Extend
+
+ training
+ training_zh
+ model_registration
+ model_registration_zh
+
.. toctree::
:maxdepth: 1
:caption: Models and Deployment
diff --git a/docs/installation/docker.md b/docs/installation/docker.md
index 63bf48564..8f52c3436 100644
--- a/docs/installation/docker.md
+++ b/docs/installation/docker.md
@@ -1,72 +1,72 @@
-([简体中文](./docker_zh.md)|English)
+([简体中文](./docker_zh.md) | English)
-# Docker
+# Docker and runtime images
-## Install Docker
+Choose the execution path before pulling an image. The Python `AutoModel` SDK, a C++ runtime server, and a development environment are different products of the repository. Installing a newer Python package inside a published runtime image does not rebuild its C++ executable or add every Python model to that server.
-### Ubuntu
-```shell
-curl -fsSL https://test.docker.com -o test-docker.sh
-sudo sh test-docker.sh
-```
-### Debian
-```shell
- curl -fsSL https://get.docker.com -o get-docker.sh
- sudo sh get-docker.sh
-```
+## 1. Verify Docker on the host
-### CentOS
-```shell
-curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
-```
+Install Docker using the [Docker Engine instructions](https://docs.docker.com/engine/install/) for Linux or Docker Desktop for macOS/Windows ([Windows reference](https://docs.docker.com/desktop/install/windows-install/)). Avoid piping an unreviewed installation script into a privileged shell.
-### MacOS
-```shell
-brew install --cask --appdir=/Applications docker
+```sh
+docker version
+docker info
```
-### Windows
-Ref to [docs](https://docs.docker.com/desktop/install/windows-install/)
+GPU containers additionally need a compatible host driver and container GPU setup. `--gpus all` requests access; it does not install the driver or make a CPU image GPU-capable. Check image architecture against the host before using it.
-## Start Docker
-```shell
-sudo systemctl start docker
-```
-## Download image
+## 2. Select a runtime or development path
-### Image Hub
+These exact image references are documented in this checkout. They are repository evidence, not a claim that registry availability, security updates, or inference were checked during this documentation review.
-#### CPU
-`registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.1`
+| Path | Repository-documented image or build | Where to continue |
+| --- | --- | --- |
+| Offline C++ CPU service | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7` | [CPU service guide](../../runtime/docs/SDK_advanced_guide_offline.md) |
+| Offline C++ GPU service | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-gpu-0.2.1` | [GPU service guide](../../runtime/docs/SDK_advanced_guide_offline_gpu.md) |
+| Online/two-pass C++ CPU service | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13` | [Online service guide](../../runtime/docs/SDK_advanced_guide_online.md) |
+| Rebuild online CPU runtime from this checkout | [Dockerfile.online.cpu](../../runtime/dockerfile/Dockerfile.online.cpu), with a digest-pinned base | Same online guide; rebuilds the C++ server and installs this source tree |
+| Python SDK development | A separately selected, validated Python/PyTorch environment | [Source installation](./installation.md); record the base image digest and package versions |
-#### GPU
+The maintained source-build path above is distinct from the historical development image advertised by older versions of this page:
`registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-py38-torch1.11.0-tf1.15.5-1.8.1`
-### Pull Image
-```shell
-sudo docker pull <image-name>:<tag>
-```
+That ModelScope development image is retained here as a historical reference, not a recommended current FunASR runtime or a guarantee of compatibility with new model dependencies. The former CPU tag `funasr-runtime-sdk-cpu-0.4.1` is likewise historical; see the [runtime release history](../../runtime/readme.md).
+
+## 3. Inspect a published image without exposing a service
-### Check Image
-```shell
-sudo docker images
+For example, prepare an offline CPU runtime shell. Run these commands in a POSIX shell, in a directory where you want a dedicated model folder:
+
+```sh
+IMAGE=registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
+docker pull "$IMAGE"
+docker image inspect "$IMAGE" --format '{{.Os}}/{{.Architecture}} {{json .RepoDigests}}'
+mkdir -p ./funasr-models
+docker run --rm -it --name funasr-runtime-shell \
+ --mount "type=bind,src=$(pwd)/funasr-models,dst=/workspace/models" \
+ --entrypoint /bin/bash "$IMAGE"
```
-## Run Docker
-```shell
-# cpu
-sudo docker run -itd --name funasr -v <local_dir:dir_in_docker> <image-name>:<tag> /bin/bash
-# gpu
-sudo docker run -itd --gpus all --name funasr -v <local_dir:dir_in_docker> <image-name>:<tag> /bin/bash
+This starts a shell, not a configured transcription service. `exit` removes this temporary container; the bind-mounted model files persist. To inspect or stop it from another terminal:
-sudo docker exec -it funasr /bin/bash
+```sh
+docker ps --filter name=funasr-runtime-shell
+docker stop funasr-runtime-shell
```
-## Stop Docker
-```shell
-exit
-sudo docker ps
-sudo docker stop funasr
+Continue with the matching service guide for model selection, executable options, protocol, and clients. When publishing a test service, bind to loopback (for example `-p 127.0.0.1:10095:10095`) until access controls and transport security are configured. Avoid `--privileged`, host-root mounts, credentials baked into images, and unreviewed public port exposure. Some historical guide commands use broader permissions; assess requirements rather than copying them blindly.
+
+## 4. Build the online CPU runtime from source
+
+From the repository root, after reviewing its Dockerfile and build context:
+
+```sh
+docker build -f runtime/dockerfile/Dockerfile.online.cpu \
+ -t funasr-online-cpu:local .
```
+`funasr-online-cpu:local` is a locally chosen build tag, not a published registry release. The Dockerfile copies the checkout, installs it in editable mode, and compiles `runtime/websocket`. A completed build alone is not a model-inference test. Follow the [online runtime guide](../../runtime/docs/SDK_advanced_guide_online.md) for startup and validation; do not assume it includes later commits without rebuilding.
+
+For SDK development, install the checkout into a reviewed Python/PyTorch container using the [installation guide](./installation.md), then run the [SDK tutorial](../tutorial/README.md). This page does not invent a universal development-image tag or model compatibility matrix.
+
+Model caches, offline preparation, remote-code trust, and separate software/model licenses still apply inside a container; see [installation and security](./installation.md). Keep exact image digests, source commits, and model revisions with your test results. More runtime choices: [runtime overview](../../runtime/readme.md) and [quick start](../../runtime/quick_start.md).
diff --git a/docs/installation/docker_zh.md b/docs/installation/docker_zh.md
index 2fa6a90f9..fc10aa301 100644
--- a/docs/installation/docker_zh.md
+++ b/docs/installation/docker_zh.md
@@ -1,72 +1,72 @@
-(简体中文|[English](./docker.md))
+(简体中文 | [English](./docker.md))
-# Docker
+# Docker 与运行时镜像
-## 安装Docker
+拉取镜像前先选择执行路径。Python `AutoModel` SDK、C++ 运行时服务和开发环境是不同的使用方式。在已发布运行时镜像里升级 Python 包,不会重新编译 C++ 可执行文件,也不会让服务自动支持所有 Python 模型。
-### Ubuntu
-```shell
-curl -fsSL https://test.docker.com -o test-docker.sh
-sudo sh test-docker.sh
-```
-### Debian
-```shell
- curl -fsSL https://get.docker.com -o get-docker.sh
- sudo sh get-docker.sh
-```
+## 1. 检查宿主机 Docker
-### CentOS
-```shell
-curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
-```
+Linux 请按 [Docker Engine 安装说明](https://docs.docker.com/engine/install/)操作,macOS/Windows 使用 Docker Desktop([Windows 参考](https://docs.docker.com/desktop/install/windows-install/))。不要将未经审查的安装脚本通过管道交给高权限 shell 执行。
-### MacOS
-```shell
-brew install --cask --appdir=/Applications docker
+```sh
+docker version
+docker info
```
-### Windows
-请参考[文档](https://docs.docker.com/desktop/install/windows-install/)
+GPU 容器还需要兼容的宿主机驱动和容器 GPU 配置。`--gpus all` 只是请求设备访问权限,不会安装驱动,也不会把 CPU 镜像变成 GPU 镜像。使用前请确认镜像与宿主机架构匹配。
-## 启动Docker
-```shell
-sudo systemctl start docker
-```
-## 下载Docker镜像
+## 2. 选择运行时或开发路径
-### 镜像仓库
+下列精确镜像引用来自当前工作区文档,仅表示仓库中有据可查,不表示本次文档审查已验证镜像仓库可用性、安全更新或模型推理。
-#### CPU
-`registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.1`
+| 路径 | 仓库记录的镜像或构建入口 | 后续指南 |
+| --- | --- | --- |
+| 离线 C++ CPU 服务 | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7` | [CPU 服务指南](../../runtime/docs/SDK_advanced_guide_offline_zh.md) |
+| 离线 C++ GPU 服务 | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-gpu-0.2.1` | [GPU 服务指南](../../runtime/docs/SDK_advanced_guide_offline_gpu_zh.md) |
+| 在线/两遍 C++ CPU 服务 | `registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13` | [在线服务指南](../../runtime/docs/SDK_advanced_guide_online_zh.md) |
+| 从当前源码重建在线 CPU 运行时 | [Dockerfile.online.cpu](../../runtime/dockerfile/Dockerfile.online.cpu),使用 digest 锁定的基础镜像 | 同上;会重编译 C++ 服务并安装当前源码 |
+| Python SDK 开发 | 单独选择并验证的 Python/PyTorch 环境 | [源码安装](./installation_zh.md);记录基础镜像 digest 和依赖版本 |
-#### GPU
+上述持续维护的源码构建路径与本页旧版本推荐的历史开发镜像不同:
`registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-py38-torch1.11.0-tf1.15.5-1.8.1`
-### 拉取镜像
-```shell
-sudo docker pull <image-name>:<tag>
-```
+保留该 ModelScope 开发镜像仅供历史查阅,不将它作为当前 FunASR 运行时推荐,也不保证与新模型依赖兼容。旧 CPU 标签 `funasr-runtime-sdk-cpu-0.4.1` 同属历史记录,参见[运行时版本历史](../../runtime/readme_cn.md)。
+
+## 3. 先检查镜像,不对外暴露服务
-### 查看镜像
-```shell
-sudo docker images
+以进入离线 CPU 运行时 shell 为例。在 POSIX shell 中,切换到希望存放独立模型目录的位置后执行:
+
+```sh
+IMAGE=registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
+docker pull "$IMAGE"
+docker image inspect "$IMAGE" --format '{{.Os}}/{{.Architecture}} {{json .RepoDigests}}'
+mkdir -p ./funasr-models
+docker run --rm -it --name funasr-runtime-shell \
+ --mount "type=bind,src=$(pwd)/funasr-models,dst=/workspace/models" \
+ --entrypoint /bin/bash "$IMAGE"
```
-## 运行Docker
-```shell
-# cpu
-sudo docker run -itd --name funasr -v <local_dir:dir_in_docker> <image-name>:<tag> /bin/bash
-# gpu
-sudo docker run -itd --gpus all --name funasr -v <local_dir:dir_in_docker> <image-name>:<tag> /bin/bash
+这仅启动 shell,不是已经配置好的转写服务。输入 `exit` 后临时容器会被删除,挂载目录中的模型文件会保留。可从另一终端查看或停止容器:
-sudo docker exec -it funasr /bin/bash
+```sh
+docker ps --filter name=funasr-runtime-shell
+docker stop funasr-runtime-shell
```
-## 停止Docker
-```shell
-exit
-sudo docker ps
-sudo docker stop funasr
+模型选择、可执行文件参数、协议与客户端请看对应服务指南。发布测试端口时,先绑定回环地址(例如 `-p 127.0.0.1:10095:10095`),再配置访问控制与传输安全。避免 `--privileged`、挂载宿主机根目录、将凭据烘焙进镜像,以及未经审查地开放公网端口。部分历史指南的命令权限较宽,应按实际需求评估,不要直接照搬。
+
+## 4. 从源码构建在线 CPU 运行时
+
+审查 Dockerfile 与构建上下文后,在仓库根目录执行:
+
+```sh
+docker build -f runtime/dockerfile/Dockerfile.online.cpu \
+ -t funasr-online-cpu:local .
```
+`funasr-online-cpu:local` 是本地构建标签,不是镜像仓库发行版本。Dockerfile 会复制当前工作区、执行可编辑安装,并编译 `runtime/websocket`。构建成功不等于模型推理通过。启动与验证请按[在线运行时指南](../../runtime/docs/SDK_advanced_guide_online_zh.md)执行;源码更新后,已有镜像不会自动包含新提交,需要重建。
+
+开发 Python SDK 时,请在审查过的 Python/PyTorch 容器中按[安装指南](./installation_zh.md)安装源码,再运行 [SDK 教程](../tutorial/README_zh.md)。本页不提供未经仓库验证的通用开发镜像标签或模型兼容矩阵。
+
+容器内仍需遵守模型缓存、离线准备、远程代码信任和软件/模型分别许可的要求,参见[安装与安全说明](./installation_zh.md)。测试记录应包含精确镜像 digest、源码 commit 和模型 revision。更多运行时路径:[概览](../../runtime/readme_cn.md)与[快速开始](../../runtime/quick_start_zh.md)。
diff --git a/docs/installation/installation.md b/docs/installation/installation.md
index c1196e975..fdb5a0fd1 100755
--- a/docs/installation/installation.md
+++ b/docs/installation/installation.md
@@ -1,74 +1,112 @@
-([简体中文](./installation_zh.md)|English)
+([简体中文](./installation_zh.md) | English)
-<p align="left">
- <a href=""><img src="https://img.shields.io/badge/OS-Linux%2C%20Win%2C%20Mac-brightgreen.svg"></a>
- <a href=""><img src="https://img.shields.io/badge/Python->=3.8,<=3.13-aff.svg"></a>
- <a href=""><img src="https://img.shields.io/badge/Pytorch-%3E%3D1.11-blue"></a>
-</p>
+# Install the Python SDK
-## Installation
+Use this guide for `from funasr import AutoModel`. For a packaged C++ service, start with [Docker and runtime images](./docker.md). After installation, continue to the [SDK tutorial](../tutorial/README.md).
-### Install Conda (Optional):
+## 1. Create an isolated environment
+
+The commands below use an already installed Python 3.11 interpreter. This is an environment example, not a promise that every model/backend supports every Python version. [setup.py](../../setup.py) declares `python_requires=">=3.7.0"`, but resolved dependencies and individual models can require newer Python. [pyproject.toml](../../pyproject.toml) defines the build backend, not a locked inference environment.
+
+Linux/macOS:
-#### Linux
```sh
-wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
-sh Miniconda3-latest-Linux-x86_64.sh
-source ~/.bashrc
-conda create -n funasr python=3.8
-conda activate funasr
+python3.11 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
```
-#### Mac
+
+Windows PowerShell:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+```
+
+An existing Conda environment is also suitable; see the [Conda installation reference](https://docs.conda.io/en/latest/miniconda.html#windows-installers). On Apple Silicon, use an arm64 interpreter and matching wheels throughout; do not mix an x86_64 Conda environment with arm64 packages.
+
+## 2. Install PyTorch, then choose one FunASR route
+
+Install matching `torch` and `torchaudio` builds for your interpreter, OS, and accelerator using the [PyTorch installer](https://pytorch.org/get-started/locally/) or [version compatibility reference](https://pytorch.org/get-started/previous-versions/). FunASR's core package does not select these builds for you. Do not infer wheel compatibility solely from a locally installed CUDA toolkit.
+
+### PyPI: use a released package
+
```sh
-wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
-# For M1 chip
-# wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
-sh Miniconda3-latest-MacOSX*
-source ~/.zashrc
-conda create -n funasr python=3.8
-conda activate funasr
+python -m pip install --upgrade funasr
```
-#### Windows
-Ref to [docs](https://docs.conda.io/en/latest/miniconda.html#windows-installers)
-### Install Pytorch (version >= 1.11.0):
+This installs the package available from your configured index, not the current Git checkout. A model or feature documented in this checkout may not be in that release. For reproducible work, replace the unpinned install with the exact version you have validated. Package version for this checkout is recorded in [version.txt](../../funasr/version.txt); it is not evidence of index availability.
+
+### Source: use this checkout and its examples
+
+From the root of an existing FunASR checkout:
```sh
-pip3 install torch torchaudio
+python -m pip install -e .
+git rev-parse HEAD
```
-If there exists CUDAs in your environments, you should install the pytorch with the version matching the CUDA. The matching list could be found in [docs](https://pytorch.org/get-started/previous-versions/).
-### Install funasr
-#### Install from pip
+For a new checkout, the [repository](https://github.com/modelscope/FunASR) can be cloned first:
-```shell
-pip3 install -U funasr
-# For the users in China, you could install with the command:
-# pip3 install -U funasr -i https://mirror.sjtu.edu.cn/pypi/web/simple
+```sh
+git clone https://github.com/modelscope/FunASR.git
+cd FunASR
+python -m pip install -e .
```
-#### Or install from source code
+Editable installation imports code from that directory; record its commit and local modifications. It is not a separate copy of the code. The repository's `examples/`, `runtime/`, and documentation are not all installed as Python package data by a PyPI install.
+
+In this checkout, `modelscope` and `huggingface_hub` are core dependencies, not optional follow-up installs. Model-specific extras remain separate. The `knf` extra provides `kaldi-native-fbank` for supported paths without torchaudio, and `silero` provides Silero VAD; neither is needed for the standard first example. Check [setup.py](../../setup.py) and the chosen model's guide before adding extras. Do not install conflicting model stacks into one environment.
-``` sh
-git clone https://github.com/modelscope/FunASR.git && cd FunASR
-pip3 install -e ./
-# For the users in China, you could install with the command:
-# pip3 install -e ./ -i https://mirror.sjtu.edu.cn/pypi/web/simple
+## 3. Verify the interpreter and imports
+
+Run from the same activated environment you will use for inference:
+
+```sh
+python -c "import sys; print(sys.executable); print(sys.version)"
+python -m pip --version
+python -m pip check
+python -c "import funasr, torch, torchaudio; from funasr import AutoModel; print('funasr:', funasr.__version__, funasr.__file__); print('torch:', torch.__version__, 'torchaudio:', torchaudio.__version__); print('CUDA available:', torch.cuda.is_available()); print('AutoModel import OK')"
```
-### Install modelscope (Optional)
-If you want to use the pretrained models in ModelScope, you should install the modelscope:
+These are dependency/import checks, not a model download or inference test. `funasr.__file__` should point to the intended installation; run outside unrelated checkouts when checking a PyPI environment. CPU is an explicit starting choice in the tutorial. A successful import or accelerator availability check does not validate an individual model on that device.
+
+For a registration/import failure in this source checkout, inspect `funasr.get_import_errors()` or set `FUNASR_IMPORT_DEBUG=1` before starting Python. Missing optional model dependencies do not necessarily block your selected model. See [troubleshooting](../troubleshooting.md) before upgrading the entire environment.
+
+## 4. Models, cache, and offline use
+
+`AutoModel` accepts a model ID/alias or an existing local model directory. `hub="ms"` is the default; `hub="hf"` selects Hugging Face. Model files download separately from the Python package and use the hub client's cache. After loading, `model.model_path` identifies the resolved directory. Ensure enough writable disk space and preserve the complete directory, including configuration, tokenizer, frontend assets, and weights.
+
+For repeatable or disconnected runs:
-```shell
-pip3 install -U modelscope
-# For the users in China, you could install with the command:
-# pip3 install -U modelscope -i https://mirror.sjtu.edu.cn/pypi/web/simple
+1. On an approved connected machine, acquire the exact model snapshot and dependencies. Record the full model ID, hub revision/commit, license, package versions, and file checksums. Also prepare every VAD, punctuation, or speaker model you plan to load.
+2. Transfer complete model directories and dependency artifacts. Replace all hub aliases with those directories and all input URLs with local files. Check configuration references for other remote dependencies.
+3. Use `disable_update=True` to skip FunASR's startup version check. This is **not** an offline switch for hub clients, model code, or missing assets. Validate the prepared environment with outbound network access disabled.
+
+The following Python example requires a complete, reviewed Paraformer-compatible snapshot at `./models/paraformer-zh` and your local `./audio.wav`:
+
+```python
+from pathlib import Path
+from funasr import AutoModel
+
+model_dir = Path("./models/paraformer-zh").resolve()
+audio = Path("./audio.wav").resolve()
+assert model_dir.is_dir(), model_dir
+assert audio.is_file(), audio
+model = AutoModel(
+ model=str(model_dir), device="cpu", disable_update=True,
+ trust_remote_code=False,
+)
+print(model.generate(input=str(audio)))
```
-### FQA
-- For installation on MAC M1 chip, the following error may happen:
-- - _cffi_backend.cpython-38-darwin.so' (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e)))
- ```shell
- pip uninstall cffi pycparser
- ARCHFLAGS="-arch arm64" pip install cffi pycparser --compile --no-cache-dir
- ```
+Source caveat: the ModelScope helper passes `model_revision` to its downloader, but this checkout's Hugging Face helper calls `snapshot_download(model)` without forwarding the revision. Do not rely on `AutoModel(..., hub="hf", model_revision=...)` for pinning here; acquire a pinned snapshot with the hub client and pass its local directory. See the [download implementation](../../funasr/download/download_model_from_hub.py).
+
+## 5. Trust and licensing
+
+- Leave `trust_remote_code=False` unless a chosen model requires code you have reviewed. In the loader, enabling trust can install a model's `requirements.txt`; the ModelScope path can also import the configured `remote_code`. A local model directory is not automatically safe.
+- Use isolated environments, reviewed model artifacts, and minimum filesystem/network permissions. Do not embed hub credentials in scripts, images, logs, or issue reports. Use the hub client's supported authentication mechanism.
+- FunASR software is [MIT licensed](../../LICENSE). Model weights have separate terms; consult the exact model card and the [Model Zoo](../../model_zoo/readme.md). The [model license agreement](../../MODEL_LICENSE) applies only where the model card adopts it. Third-party models retain their own provenance and licenses.
+
+Next: [produce your first transcript](../tutorial/README.md).
diff --git a/docs/installation/installation_zh.md b/docs/installation/installation_zh.md
index 53616fd00..cc1b74062 100755
--- a/docs/installation/installation_zh.md
+++ b/docs/installation/installation_zh.md
@@ -1,75 +1,112 @@
-(简体中文|[English](./installation.md))
+(简体中文 | [English](./installation.md))
-<p align="left">
- <a href=""><img src="https://img.shields.io/badge/OS-Linux%2C%20Win%2C%20Mac-brightgreen.svg"></a>
- <a href=""><img src="https://img.shields.io/badge/Python->=3.8,<=3.13-aff.svg"></a>
- <a href=""><img src="https://img.shields.io/badge/Pytorch-%3E%3D1.11-blue"></a>
-</p>
+# 安装 Python SDK
-## 安装
+本页适用于 `from funasr import AutoModel`。需要打包好的 C++ 服务时,请先看 [Docker 与运行时镜像](./docker_zh.md)。安装完成后进入 [SDK 教程](../tutorial/README_zh.md)。
-### 安装Conda(可选):
+## 1. 创建独立环境
+
+以下命令以已安装的 Python 3.11 为例,不表示所有模型或后端都支持所有 Python 版本。[setup.py](../../setup.py) 声明 `python_requires=">=3.7.0"`,但实际解析出的依赖和具体模型可能要求更高版本。[pyproject.toml](../../pyproject.toml) 定义构建后端,不是锁定的推理环境。
+
+Linux/macOS:
-#### Linux
```sh
-wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
-sh Miniconda3-latest-Linux-x86_64.sh
-source ~/.bashrc
-conda create -n funasr python=3.8
-conda activate funasr
+python3.11 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
```
-#### Mac
+
+Windows PowerShell:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+```
+
+也可以使用已有 Conda 环境,参见 [Conda 安装参考](https://docs.conda.io/en/latest/miniconda.html#windows-installers)。Apple Silicon 应使用架构一致的 arm64 解释器和 wheel,不要将 x86_64 Conda 环境与 arm64 包混用。
+
+## 2. 先安装 PyTorch,再选择一种 FunASR 安装方式
+
+根据解释器、操作系统和加速设备,在 [PyTorch 安装页面](https://pytorch.org/get-started/locally/)或[版本兼容参考](https://pytorch.org/get-started/previous-versions/)中选择匹配的 `torch` 与 `torchaudio`。FunASR 核心包不会替你选择这些构建。不要仅凭本机 CUDA toolkit 版本判断 wheel 是否兼容。
+
+### PyPI:使用已发布的软件包
+
```sh
-wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
-# For M1 chip
-# wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
-sh Miniconda3-latest-MacOSX*
-source ~/.zashrc
-conda create -n funasr python=3.8
-conda activate funasr
+python -m pip install --upgrade funasr
```
-#### Windows
-Ref to [docs](https://docs.conda.io/en/latest/miniconda.html#windows-installers)
-### 安装Pytorch(版本 >= 1.11.0):
+这会从已配置的索引安装可用软件包,不是当前 Git 工作区。当前源码文档中的模型或功能未必已包含在该发行包中。需要复现时,将不锁版本的安装命令改为已验证的精确版本。当前工作区版本记录在 [version.txt](../../funasr/version.txt),不能据此证明索引上已有该版本。
+
+### 源码:使用当前工作区及配套示例
+
+在已有 FunASR 仓库根目录执行:
```sh
-pip3 install torch torchaudio
+python -m pip install -e .
+git rev-parse HEAD
```
-如果您的环境中存在CUDAs,则应安装与CUDA匹配版本的pytorch,匹配列表可在文档中找到([文档](https://pytorch.org/get-started/previous-versions/))。
-### 安装funasr
-#### 从pip安装
+尚无工作区时,可以先克隆[仓库](https://github.com/modelscope/FunASR):
-```shell
-pip3 install -U funasr
-# 对于中国大陆用户,可以使用以下命令进行安装:
-# pip3 install -U funasr -i https://mirror.sjtu.edu.cn/pypi/web/simple
+```sh
+git clone https://github.com/modelscope/FunASR.git
+cd FunASR
+python -m pip install -e .
```
-#### 或者从源代码安装
+可编辑安装会直接导入该目录中的源码,请记录 commit 和本地修改;它不会另存一份代码。仓库中的 `examples/`、`runtime/` 和文档并不都会随 PyPI 包安装。
-``` sh
-git clone https://github.com/modelscope/FunASR.git && cd FunASR
-pip3 install -e ./
-# 对于中国大陆用户,可以使用以下命令进行安装:
-# pip3 install -e ./ -i https://mirror.sjtu.edu.cn/pypi/web/simple
+本工作区已将 `modelscope` 和 `huggingface_hub` 列为核心依赖,不需要再按“可选步骤”安装。模型专属依赖仍需单独处理。`knf` extra 为支持的无 torchaudio 路径提供 `kaldi-native-fbank`,`silero` extra 提供 Silero VAD;标准入门示例不需要它们。添加 extra 前请查看 [setup.py](../../setup.py) 和所选模型指南,避免在同一环境中混装互不兼容的模型依赖。
+
+## 3. 验证解释器和导入
+
+在之后用于推理的同一个已激活环境中执行:
+
+```sh
+python -c "import sys; print(sys.executable); print(sys.version)"
+python -m pip --version
+python -m pip check
+python -c "import funasr, torch, torchaudio; from funasr import AutoModel; print('funasr:', funasr.__version__, funasr.__file__); print('torch:', torch.__version__, 'torchaudio:', torchaudio.__version__); print('CUDA available:', torch.cuda.is_available()); print('AutoModel import OK')"
```
-### 安装modelscope(可选)
+这些命令仅检查依赖和导入,不是模型下载或推理测试。`funasr.__file__` 应指向预期安装位置;检查 PyPI 环境时,请避开其他源码工作区的导入遮蔽。教程显式使用 CPU 起步。导入成功或设备可用不代表某个模型已经在该设备上验证通过。
+
+本源码工作区出现注册或导入失败时,可查看 `funasr.get_import_errors()`,或在启动 Python 前设置 `FUNASR_IMPORT_DEBUG=1`。其他可选模型的缺失依赖不一定影响当前模型。批量升级整个环境前,请先阅读[常见问题](../troubleshooting_zh.md)。
+
+## 4. 模型、缓存与离线使用
+
+`AutoModel` 接受模型 ID/别名或已有的本地模型目录。默认 `hub="ms"` 使用 ModelScope,`hub="hf"` 使用 Hugging Face。权重与 Python 包分开下载,由 hub 客户端管理缓存;加载后可通过 `model.model_path` 查看实际目录。请预留可写磁盘空间,并保留配置、分词器、前端资源与权重组成的完整目录。
-如果您想要使用ModelScope中的预训练模型,则应安装modelscope:
+需要复现或断网运行时:
-```shell
-pip3 install -U modelscope
-# 对于中国大陆用户,可以使用以下命令进行安装:
-# pip3 install -U modelscope -i https://mirror.sjtu.edu.cn/pypi/web/simple
+1. 在允许联网的机器上准备精确模型快照和依赖,记录完整模型 ID、hub revision/commit、许可、软件包版本和文件校验和。VAD、标点、说话人模型也应分别准备。
+2. 传输完整目录与依赖制品,把所有模型别名替换为本地目录,把输入 URL 替换为本地文件,并检查配置是否继续引用远程资源。
+3. 设置 `disable_update=True` 可跳过 FunASR 启动版本检查,但它**不是** hub 客户端、模型代码或缺失资源的离线开关。应在禁用外连的环境中验证准备结果。
+
+以下 Python 示例要求 `./models/paraformer-zh` 中已有完整、审查过的 Paraformer 兼容快照,并准备本地 `./audio.wav`:
+
+```python
+from pathlib import Path
+from funasr import AutoModel
+
+model_dir = Path("./models/paraformer-zh").resolve()
+audio = Path("./audio.wav").resolve()
+assert model_dir.is_dir(), model_dir
+assert audio.is_file(), audio
+model = AutoModel(
+ model=str(model_dir), device="cpu", disable_update=True,
+ trust_remote_code=False,
+)
+print(model.generate(input=str(audio)))
```
-### 常见问题解答
-- 在MAC M1芯片上安装时,可能会出现以下错误:
-- - _cffi_backend.cpython-38-darwin.so' (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e)))
- ```shell
- pip uninstall cffi pycparser
- ARCHFLAGS="-arch arm64" pip install cffi pycparser --compile --no-cache-dir
- ```
+源码限制:ModelScope 辅助函数会将 `model_revision` 传给下载器,但本工作区的 Hugging Face 辅助函数调用 `snapshot_download(model)`,没有转发 revision。因此这里不能依赖 `AutoModel(..., hub="hf", model_revision=...)` 锁定版本;应通过 hub 客户端取得固定快照,再传入本地目录。参见[下载实现](../../funasr/download/download_model_from_hub.py)。
+
+## 5. 信任与许可
+
+- 默认保留 `trust_remote_code=False`,只有模型确实需要且代码已经审查时才开启。加载器在开启信任后可能安装模型的 `requirements.txt`,ModelScope 路径还可能导入配置的 `remote_code`。本地目录并不天然可信。
+- 使用独立环境、审查过的制品和最小文件系统/网络权限。不要把 hub 凭据写进脚本、镜像、日志或问题反馈;使用 hub 客户端支持的认证方式。
+- FunASR 软件采用 [MIT 许可](../../LICENSE),模型权重采用各自条款,请查看精确模型卡和[模型仓库](../../model_zoo/readme_zh.md)。只有模型卡采用时,[模型许可协议](../../MODEL_LICENSE)才适用。第三方模型保留各自来源与许可。
+
+下一步:[完成第一次转写](../tutorial/README_zh.md)。
diff --git a/docs/model_registration.md b/docs/model_registration.md
new file mode 100644
index 000000000..d31aa9e38
--- /dev/null
+++ b/docs/model_registration.md
@@ -0,0 +1,124 @@
+# Model Registration
+
+[简体中文](model_registration_zh.md) | [Documentation](tutorial/README.md) | [Training](training.md) | [Historical registry tutorial](tutorial/Tables.md)
+
+Registration connects a Python implementation to a configuration name. It does not download weights, make an arbitrary Transformers model compatible, provide training/export support, or certify model quality. This guide describes the checked-in [registry](../funasr/register.py), [AutoModel](../funasr/auto/auto_model.py), [hub loader](../funasr/download/download_model_from_hub.py) and [dynamic importer](../funasr/utils/dynamic_import.py).
+
+## Names and Import Order
+
+Use `@tables.register("model_classes", "YourUniqueModelName")` on a class imported before construction. `tables` comes from `funasr.register`. The second argument is the exact, case-sensitive registry key; omitting it uses the Python class name. The decorator returns the original class and records its source location with `inspect`, so define examples in importable `.py` files, not only a REPL or dynamically generated class.
+
+Keys live in process-global dictionaries. An existing key is overwritten, with a debug log rather than an error; imports and their order therefore matter. Use an organization/project-specific name and a collision guard. Avoid names such as `SenseVoiceSmall`, `Paraformer` or `FunASRNano` for unrelated custom models. `tables.print("model")` displays registration metadata; `tables.model_classes[name]` gives the active implementation.
+
+Other tables include `encoder_classes`, `decoder_classes`, `frontend_classes`, `tokenizer_classes`, `dataset_classes`, `index_ds_classes` and `batch_sampler_classes`. Each consumer has its own contract: registering an encoder does not make it a complete `AutoModel` model. The registry also permits new table names, so a typo can create an unused table instead of failing.
+
+## Minimal Local Contract Example
+
+Put the following example in an importable `custom_model_demo.py` in a scratch directory, then run `python custom_model_demo.py` with this checkout installed. It intentionally returns input text, not speech recognition. It does not need weights, audio, a hub download, or GPU. The parameter is present because this `AutoModel.inference` inspects `next(model.parameters()).device`; a parameterless toy fails that path.
+
+```python
+import torch
+from funasr import AutoModel
+from funasr.register import tables
+
+MODEL_NAME = "DocsEchoModelV1"
+if MODEL_NAME in tables.model_classes:
+ raise RuntimeError(f"Registry collision: {MODEL_NAME}")
+
+
[email protected]("model_classes", MODEL_NAME)
+class DocsEchoModel(torch.nn.Module):
+ def __init__(self, **kwargs):
+ super().__init__()
+ self.anchor = torch.nn.Parameter(torch.zeros(1), requires_grad=False)
+
+ def inference(
+ self, data_in, data_lengths=None, key=None,
+ tokenizer=None, frontend=None, **kwargs,
+ ):
+ results = [
+ {"key": sample_key, "text": str(value)}
+ for sample_key, value in zip(key, data_in)
+ ]
+ return results, {}
+
+
+if __name__ == "__main__":
+ model = AutoModel(
+ model=MODEL_NAME,
+ model_conf={},
+ device="cpu",
+ disable_update=True,
+ disable_pbar=True,
+ )
+ result = model.generate(input=["hello", "world"], data_type="text")
+ assert [row["text"] for row in result] == ["hello", "world"]
+ assert all(isinstance(row["key"], str) for row in result)
+ print([row["text"] for row in result])
+```
+
+Expected final printed list: `['hello', 'world']`. This is a wiring check only. The focused documentation test executes this block in a temporary file against the checked-out implementation; it does not validate a speech model.
+
+The presence of `model_conf={}` is intentional: `AutoModel.build_model` skips hub/config resolution when that key is supplied. Thus `model` is the already-registered class key here, not a model directory or hub ID. Import the custom module yourself first; adding `remote_code` to this direct path does not cause it to be imported. Resolved kwargs are merged over `model_conf` and passed to the constructor, including built tokenizer/frontend objects, device and vocabulary/input sizes. Accept appropriate named arguments plus `**kwargs`, as the real models do.
+
+## Inference and Training Contracts
+
+| Interface | Contract in this checkout |
+| --- | --- |
+| Model object | Normally `torch.nn.Module`; must support `.to(...)`, `.eval()` and `.parameters()`. Constructor configuration is model-specific. |
+| `inference` inputs | Without VAD, AutoModel batches input into `data_in` and `key` lists and calls `model.inference(**batch, **kwargs)` under `torch.no_grad()`. With `data_type="fbank"` and one item, it passes the feature object directly and supplies `data_lengths=input_len`. Tokenizer/frontend are resolved objects or `None`. |
+| Model-level return | Return a two-item tuple `(results, meta_data)`: `results` is `list[dict]`, `meta_data` is a dictionary. For ASR use string `key` and `text` fields, preserving the input order/keys. Returning a bare list of result dictionaries is wrong: AutoModel treats its first item as the entire batch result. |
+| Metadata | Optional `load_data`, `extract_feat`, `batch_data_time`. For audio, `batch_data_time` is a positive duration in seconds, not milliseconds; zero causes division by zero in timing code. Omitting it gives the internal `-1` sentinel, as in the non-audio toy, not a meaningful speed measurement. |
+| Public return | `AutoModel.generate(...)` returns the flattened result list. Additional fields such as timestamps are model-specific; registration does not promise them. VAD, punctuation, speaker and streaming integrations need additional compatible behavior and independent tests. |
+| Training | Implement differentiable `forward` matching the dataset collator's named tensor fields. [Trainer](../funasr/train_utils/trainer_ds.py) unpacks `(loss, stats, weight)`; [SenseVoice](../funasr/models/sense_voice/model.py) and [Nano](../funasr/models/fun_asr_nano/model.py) use `force_gatherable`. The toy deliberately has no training forward. |
+| Export | [Export utility](../funasr/utils/export_utils.py) calls the model's `export` and then model-specific methods such as `export_dummy_inputs`, input/output names and dynamic axes. Registration alone does not implement these. |
+
+A custom model must itself implement audio loading, feature preparation, tokenization/decoding and batching where needed. Copy the contract from a close real model, not its capabilities without implementation. For training, also implement/configure the appropriate dataset and loss; see [training](training.md).
+
+## Loading Reviewed Custom Code and Weights
+
+There are two distinct routes:
+
+1. **Direct registration:** import your module; pass its key and `model_conf` as in the toy. Provide compatible tokenizer/frontend/configuration and an existing `init_param` if weights are needed. No hub code import is performed on this path.
+2. **Model-directory resolution:** pass a reviewed local directory or hub ID without `model_conf`. The loader reads `configuration.json` file metadata or `config.yaml`, resolves the model key/assets and loads weights. A simple local `config.yaml` directory normally also needs `model.pt` plus all referenced tokenizer/frontend assets. Arbitrary HF weight folders are not automatically FunASR model directories.
+
+For the second route, this is the ModelScope-path interface, not a self-contained runnable example. `models/custom-asr` must already contain the compatible reviewed configuration and weights, and `custom_asr_model.py` must register the exact configuration key:
+
+```python
+from funasr import AutoModel
+
+model = AutoModel(
+ model="./models/custom-asr",
+ hub="ms",
+ trust_remote_code=True,
+ remote_code="./custom_asr_model.py",
+ device="cpu",
+ disable_update=True,
+)
+print(model.generate(input="data/audio/heldout.wav"))
+```
+
+The current `download_from_ms` imports `remote_code` when `trust_remote_code=True`, defaulting to module name `model` if omitted. The importer supports module/file paths (and URL download), appends the directory to `sys.path` and imports by basename. A relative path is relative to the working directory, not automatically to the weights directory. Basename collisions and Python's import cache can select an already-loaded module; use distinct module names and verify the active class. Import exceptions are printed rather than re-raised by this helper, so inspect errors and registry state.
+
+**The `hub="hf"` path differs:** in this checkout `download_from_hf` can install model requirements under the trust flag but does not call `import_module_from_path`. Do not assume `remote_code` is executed there. Import your reviewed custom module explicitly before constructing with `hub="hf"`, or use the direct-registration route with complete configuration. The local `config.yaml` fallback also handles `init_param` differently between hubs: ModelScope retains an existing explicit path; Hugging Face assigns the directory's `model.pt`. Check the resolved path rather than assuming a selected checkpoint override survived.
+
+## Real Examples and Boundaries
+
+- [SenseVoiceSmall implementation](../funasr/models/sense_voice/model.py) demonstrates a registered model with training, inference and export integration. Retain its model-specific configuration and tokenizer assumptions.
+- [Nano demo1.py](../examples/industrial_data_pretraining/fun_asr_nano/demo1.py) shows `trust_remote_code=True`, `remote_code="./model.py"`, `hub="ms"`; it assumes the recipe directory. Its [local implementation](../examples/industrial_data_pretraining/fun_asr_nano/model.py) registers `FunASRNano` and imports sibling `ctc` and `tools` modules. That can overwrite the [built-in implementation](../funasr/models/fun_asr_nano/model.py); the two are not interchangeable for every feature, including built-in LoRA. Audit the active class and checkpoint keys.
+- [MOSS adapter](../funasr/models/moss_transcribe_diarize/model.py) integrates the third-party OpenMOSS model, and explicitly rejects training in `forward`. It is not evidence that a registered model supports fine-tuning or export.
+- The [original registration tutorial](tutorial/Tables.md) and [general tutorial](tutorial/README.md) remain useful historical references; use the current source behavior above when their examples differ.
+
+## Safety and Verification
+
+`trust_remote_code=True` permits Python execution; the hub loaders can also install a model directory's `requirements.txt`. A local directory is not inherently trustworthy. Review source, dependencies and weight serialization, use isolated environments, and do not load untrusted pickled checkpoints. Never interpolate untrusted URLs, module names or configs into this workflow. Keep a reviewed local snapshot with hashes when remote revision handling cannot be relied on; `model_revision` is not a universal pin across all loader paths here.
+
+Check the active registry key/class/source before loading. Confirm exact model/config/tokenizer compatibility and inspect missing/unexpected weights: `ignore_init_mismatch` defaults to true in AutoModel, and a nonexistent direct `init_param` prints an error rather than guaranteeing construction fails. Validate checkpoint existence yourself. Test one item, multiple items, error handling and the intended pipeline before training/export/deployment. FunASR software's MIT license does not replace model or upstream component licenses.
+
+Focused syntax, repository-link and no-download toy-contract checks:
+
+```bash
+python -m pytest -q tests/test_training_docs_contract.py
+```
+
+These checks do not certify arbitrary custom code, actual ASR quality, GPU training, real-checkpoint restoration or export compatibility.
diff --git a/docs/model_registration_zh.md b/docs/model_registration_zh.md
new file mode 100644
index 000000000..10971c8db
--- /dev/null
+++ b/docs/model_registration_zh.md
@@ -0,0 +1,124 @@
+# 模型注册
+
+[English](model_registration.md) | [文档](tutorial/README_zh.md) | [训练](training_zh.md) | [历史注册教程](tutorial/Tables_zh.md)
+
+注册把 Python 实现与配置名称连接起来,不会下载权重、自动兼容任意 Transformers 模型、提供训练或导出能力,也不代表质量认证。本指南依据当前仓库的[注册表](../funasr/register.py)、[AutoModel](../funasr/auto/auto_model.py)、[模型加载器](../funasr/download/download_model_from_hub.py)和[动态导入工具](../funasr/utils/dynamic_import.py)。
+
+## 名称与导入顺序
+
+对构造前已导入的类使用 `@tables.register("model_classes", "YourUniqueModelName")`,其中 `tables` 来自 `funasr.register`。第二个参数是区分大小写的精确注册键,省略时使用 Python 类名。装饰器返回原类,并通过 `inspect` 记录源码位置,所以应把示例定义在可导入的 `.py` 文件中,而非仅在 REPL 或动态生成类中定义。
+
+注册键保存在进程级字典中。同名键会被覆盖,只记录 debug 日志而不报错,因此导入顺序会影响行为。使用组织或项目专属名称并增加冲突检查,不要给无关自定义模型使用 `SenseVoiceSmall`、`Paraformer`、`FunASRNano` 等已有名称。`tables.print("model")` 显示注册元数据,`tables.model_classes[name]` 给出当前生效实现。
+
+其他表包括 `encoder_classes`、`decoder_classes`、`frontend_classes`、`tokenizer_classes`、`dataset_classes`、`index_ds_classes`、`batch_sampler_classes`。每个调用方都有自己的接口约定,注册 encoder 不等于注册完整 `AutoModel` 模型。注册器也允许创建新表,表名拼错可能生成无人使用的表,而不是报错。
+
+## 最小本地接口示例
+
+在临时目录中创建可导入的 `custom_model_demo.py`,内容如下,然后在已安装当前 checkout 的环境执行 `python custom_model_demo.py`。它只回显文本,不执行语音识别;不需要权重、音频、模型下载或 GPU。保留一个参数是因为当前 `AutoModel.inference` 会读取 `next(model.parameters()).device`,无参数的玩具模型会在此失败。
+
+```python
+import torch
+from funasr import AutoModel
+from funasr.register import tables
+
+MODEL_NAME = "DocsEchoModelV1"
+if MODEL_NAME in tables.model_classes:
+ raise RuntimeError(f"Registry collision: {MODEL_NAME}")
+
+
[email protected]("model_classes", MODEL_NAME)
+class DocsEchoModel(torch.nn.Module):
+ def __init__(self, **kwargs):
+ super().__init__()
+ self.anchor = torch.nn.Parameter(torch.zeros(1), requires_grad=False)
+
+ def inference(
+ self, data_in, data_lengths=None, key=None,
+ tokenizer=None, frontend=None, **kwargs,
+ ):
+ results = [
+ {"key": sample_key, "text": str(value)}
+ for sample_key, value in zip(key, data_in)
+ ]
+ return results, {}
+
+
+if __name__ == "__main__":
+ model = AutoModel(
+ model=MODEL_NAME,
+ model_conf={},
+ device="cpu",
+ disable_update=True,
+ disable_pbar=True,
+ )
+ result = model.generate(input=["hello", "world"], data_type="text")
+ assert [row["text"] for row in result] == ["hello", "world"]
+ assert all(isinstance(row["key"], str) for row in result)
+ print([row["text"] for row in result])
+```
+
+最后输出应为 `['hello', 'world']`。这只是接口连通性验证,专项文档测试会在临时文件中针对当前源码执行这段代码,不验证语音模型。
+
+`model_conf={}` 是有意传入的:只要该键存在,`AutoModel.build_model` 就跳过 hub/配置解析。因此这里的 `model` 是已注册类名,不是目录或 hub ID。必须先自行导入模块;在该直接构造路径中添加 `remote_code` 不会触发导入。解析后的 kwargs 覆盖合并到 `model_conf`,一起传给构造器,包括已构造的 tokenizer/frontend、设备、词表与输入维度。请像真实模型一样接收相应命名参数及 `**kwargs`。
+
+## 推理与训练接口
+
+| 接口 | 当前源码约定 |
+| --- | --- |
+| 模型对象 | 通常为 `torch.nn.Module`,需要支持 `.to(...)`、`.eval()`、`.parameters()`;构造配置由模型决定。 |
+| `inference` 输入 | 不使用 VAD 时,AutoModel 把输入组织成 `data_in` 和 `key` 列表,在 `torch.no_grad()` 下调用 `model.inference(**batch, **kwargs)`。单条 `data_type="fbank"` 输入会直接传入特征对象,并设 `data_lengths=input_len`。tokenizer/frontend 是已构造对象或 `None`。 |
+| 模型层返回值 | 返回二元组 `(results, meta_data)`,其中 `results` 是 `list[dict]`,`meta_data` 是字典。ASR 结果使用字符串 `key`、`text` 并保持输入顺序与标识。不能只返回结果字典列表,否则 AutoModel 会把第一条当成整个 batch 结果。 |
+| 元数据 | 可包含 `load_data`、`extract_feat`、`batch_data_time`。音频的 `batch_data_time` 是以秒为单位的正时长,不能填毫秒或零,零会导致计时代码除零。省略时使用内部 `-1` 哨兵值,如上述非音频示例,并不代表有效速度测量。 |
+| 公开返回值 | `AutoModel.generate(...)` 返回展开后的结果列表。时间戳等附加字段由模型决定,注册并不承诺这些字段。VAD、标点、说话人和流式集成还需额外兼容实现与独立测试。 |
+| 训练 | 实现可微 `forward`,命名张量参数应匹配 dataset collator。[训练器](../funasr/train_utils/trainer_ds.py)解包 `(loss, stats, weight)`;[SenseVoice](../funasr/models/sense_voice/model.py)和 [Nano](../funasr/models/fun_asr_nano/model.py)使用 `force_gatherable`。玩具模型故意不实现训练 forward。 |
+| 导出 | [导出工具](../funasr/utils/export_utils.py)调用模型的 `export`,再使用 `export_dummy_inputs`、输入输出名称、动态轴等模型专属方法。注册本身不会实现这些方法。 |
+
+自定义模型仍需自行实现所需的音频加载、特征处理、分词、解码及 batching。参考相近模型的接口,不能在缺少实现时宣称具有其能力。训练还需适配数据集与损失函数,参见[训练指南](training_zh.md)。
+
+## 加载已审查代码与权重
+
+有两条不同路径:
+
+1. **直接注册构造:**先导入模块,再像玩具示例一样传注册键和 `model_conf`。需要权重时提供兼容的 tokenizer/frontend/配置及真实存在的 `init_param`。该路径不执行 hub 代码导入。
+2. **模型目录解析:**传已审查的本地目录或 hub ID,不传 `model_conf`。加载器读取 `configuration.json` 文件元数据或 `config.yaml`,解析类名和资产并加载权重。简单的本地 `config.yaml` 目录通常还需要 `model.pt` 及配置引用的分词器、前端文件。任意 HF 权重文件夹不会自动成为 FunASR 模型目录。
+
+第二条路径的 ModelScope 接口如下,它不是无需准备即可运行的例子。`models/custom-asr` 必须已有兼容且审查过的配置和权重,`custom_asr_model.py` 必须注册配置指定的精确键:
+
+```python
+from funasr import AutoModel
+
+model = AutoModel(
+ model="./models/custom-asr",
+ hub="ms",
+ trust_remote_code=True,
+ remote_code="./custom_asr_model.py",
+ device="cpu",
+ disable_update=True,
+)
+print(model.generate(input="data/audio/heldout.wav"))
+```
+
+当前 `download_from_ms` 在 `trust_remote_code=True` 时导入 `remote_code`,未指定时默认为模块名 `model`。导入器支持模块/文件路径及 URL 下载,把目录加入 `sys.path` 后按文件基本名导入。相对路径按工作目录解析,不会自动相对权重目录解析。文件基本名冲突及 Python 导入缓存可能选中已加载模块,应使用独立模块名并验证当前类。该辅助函数打印导入异常而不重新抛出,应检查错误日志与注册结果。
+
+**`hub="hf"` 路径不同:**本 checkout 的 `download_from_hf` 在信任开关下可安装模型依赖,但不调用 `import_module_from_path`,不能假定它会执行 `remote_code`。在 `hub="hf"` 构造前显式导入已审查模块,或使用完整配置的直接注册构造路径。两条路径的本地 `config.yaml` 回退对 `init_param` 也不同:ModelScope 保留已有且存在的显式路径,Hugging Face 则指定目录内 `model.pt`。必须检查解析后的真实路径,不要假定 checkpoint 覆盖始终有效。
+
+## 真实示例与边界
+
+- [SenseVoiceSmall 实现](../funasr/models/sense_voice/model.py)展示注册、训练、推理和导出集成,但需保持其模型配置与分词器假设。
+- [Nano demo1.py](../examples/industrial_data_pretraining/fun_asr_nano/demo1.py)使用 `trust_remote_code=True`、`remote_code="./model.py"`、`hub="ms"`,要求 recipe 工作目录。其[本地实现](../examples/industrial_data_pretraining/fun_asr_nano/model.py)注册 `FunASRNano` 并导入同目录的 `ctc`、`tools` 模块,可能覆盖[内置实现](../funasr/models/fun_asr_nano/model.py)。两者并非对所有功能可互换,尤其不能假定保留内置 LoRA,应检查实际类和权重键。
+- [MOSS 适配器](../funasr/models/moss_transcribe_diarize/model.py)集成第三方 OpenMOSS 模型,其 `forward` 明确拒绝训练。注册模型不意味着支持微调或导出。
+- [原始注册教程](tutorial/Tables_zh.md)和[通用教程](tutorial/README_zh.md)保留为历史入口;示例有差异时,以这里说明的当前源码行为为准。
+
+## 安全与验证
+
+`trust_remote_code=True` 允许执行 Python;hub 加载器还可能安装模型目录的 `requirements.txt`。本地目录不天然可信。审核源码、依赖与权重序列化方式,使用隔离环境,不加载不可信的 pickle checkpoint。不要把不可信 URL、模块名或配置直接接入流程。远程 revision 行为不可靠时保留带哈希的已审查本地快照;这里的 `model_revision` 并非所有加载路径都能统一固定版本。
+
+加载前检查当前注册键、类和源码位置。确认模型、配置、分词器兼容,并检查缺失或多余权重:AutoModel 的 `ignore_init_mismatch` 默认为 true,直接传入不存在的 `init_param` 会打印错误,不保证构造失败。应自行验证 checkpoint 存在。训练、导出、部署前分别测试单条、多条、异常输入与目标流水线。FunASR 软件的 MIT 许可证不替代模型或上游组件的许可。
+
+运行专项语法、仓库链接和不下载模型的玩具接口测试:
+
+```bash
+python -m pytest -q tests/test_training_docs_contract.py
+```
+
+这些检查不认证任意自定义代码、真实 ASR 质量、GPU 训练、真实 checkpoint 恢复或导出兼容性。
diff --git a/docs/python_api.md b/docs/python_api.md
new file mode 100644
index 000000000..bc67f1884
--- /dev/null
+++ b/docs/python_api.md
@@ -0,0 +1,212 @@
+# Python SDK: AutoModel
+
+[简体中文](python_api_zh.md) | [Installation](installation/installation.md) | [Model selection](model_selection.md)
+
+`from funasr import AutoModel` runs models inside your Python process. It is not an HTTP client and does not implement the entire OpenAI API. This guide describes the implementation in this checkout, not every historical FunASR release or upstream checkpoint.
+
+## Construction and Inference Are Different
+
+`AutoModel(**kwargs)` resolves a model configuration, looks up its registered implementation, loads weights, and optionally constructs VAD, punctuation, and speaker models. `model.generate(input, input_len=None, progress_callback=None, **cfg)` runs those already-loaded components. Passing a new `model`, `vad_model`, or `device` to `generate()` is not a supported way to rebuild or move the pipeline; construct a separate instance.
+
+The wrapper accepts `**kwargs`, not a universally validated parameter schema. A keyword being accepted does not mean the selected model uses it. Configuration files can override the fallback defaults below. See [AutoModel source](../funasr/auto/auto_model.py), the [registry](../funasr/register.py), [hub resolution](../funasr/download/download_model_from_hub.py), and [alias maps](../funasr/download/name_maps_from_hub.py).
+
+### Construction Parameters
+
+| Parameter | Source fallback | Meaning |
+|---|---|---|
+| `model` | Required | Hub alias, full model ID, or complete local model directory. Aliases are hub-specific, not version pins. |
+| `hub` | `"ms"` | `"ms"`/`"modelscope"` or `"hf"`/`"huggingface"`. The special `"openai"` loader branch concerns Whisper loading, not HTTP API compatibility. |
+| `model_revision` | `"master"` in hub loaders | ModelScope forwards the revision. The generic Hugging Face helper currently ignores it; see reproducibility below. |
+| `device` | `"cuda"` | E.g. `"cuda:0"` or `"cpu"`. Unavailable checked accelerator backends fall back to CPU; explicit `ngpu=0` does too. Fallback sets `batch_size=1`. |
+| `ngpu` | `1` | Zero selects CPU. This is not a multi-GPU serving or sharding configuration. |
+| `ncpu` | `4` | Positive CPU thread count; invalid values use the fallback and values below 1 clamp to 1. Sets process-wide PyTorch threads. |
+| `vad_model`, `punc_model`, `spk_model` | `None` | Optional components, built once. Use `vad_model`, not the rejected typo `vda_model`. |
+| `vad_kwargs`, `punc_kwargs`, `spk_kwargs` | `{}` | Component configuration dictionaries. Device is inherited; hub and CPU threads are inherited unless provided in the component dictionary. |
+| `vad_model_revision`, `punc_model_revision`, `spk_model_revision` | `"master"` each | Separate component revisions, not inherited from the ASR revision. These top-level values replace `model_revision` in the component dictionaries. |
+| `spk_mode` | `"punc_segment"` | Use `"punc_segment"` or `"vad_segment"`. The validation also accepts legacy `"default"`, but the sentence-building branches do not implement it; do not select it. |
+| `disable_update` | `False` | Disables the FunASR package version check only, not model downloading. |
+| `disable_pbar` | `False` | Suppresses wrapper progress bars. |
+| `trust_remote_code` | `False` in hub loaders | Opt-in to model-supplied requirements and code paths. Review the exact files and dependencies first. |
+
+### Per-Call Parameters
+
+| Parameter | Source fallback | Scope and limits |
+|---|---|---|
+| `input` | Required | Audio path, URL, waveform, supported audio bytes, or a list of inputs. Text models such as punctuation accept text. |
+| `input_len` | `None` | The direct inference wrapper forwards it as `data_lengths` only for a single `data_type="fbank"` input; it is not a universal waveform-length control. |
+| `progress_callback` | `None` | `callback(current, total)` after direct inference batches. VAD processing can forward it to component calls; it is not one global monotonic pipeline progress counter. |
+| `batch_size` | `1` | Number of inputs per direct inference call. Actual model batch support varies. |
+| `batch_size_s` | `300` | VAD-path batching budget in seconds, based on longest padded segment times segment count, not a hard file-duration limit. CPU VAD processing uses single-segment batches. |
+| `batch_size_threshold_s` | `60` | VAD batching threshold for segment duration, not a VAD splitting setting. |
+| `merge_vad` | `False` | Enables merging detected VAD regions for this call. |
+| `merge_length_s` | `15` | VAD merge target read before call overrides are merged into ASR config. Set this at construction in this checkout. |
+| `cache` | No wrapper-managed session | Pass a caller-owned dictionary on every streaming call. It is not a hub/model download cache. |
+| `sentence_timestamp` | `False` | Requests sentence records in the VAD pipeline; depends on available timestamps and punctuation, with limited VAD fallback. |
+| `return_spk_res` | `True` | Includes clustered speaker results when VAD and a speaker model are configured. `False` does not avoid construction or segment embedding computation. |
+| `preset_spk_num` | `None` | Optional speaker-count hint for the clustering backend. |
+| `return_spk_center` | `False` | Adds `spk_embedding_center` when clustering runs. Array-valued output may need conversion before JSON serialization. |
+| `return_raw_text` | `False` | Preserves pre-punctuation text where punctuation is applied; does not guarantee this field on every path. |
+
+`generate()` restores saved construction configuration before merging call options. Repeat request-specific options on each call; do not rely on the previous call's language, batch settings, or hotwords. This configuration reset does not establish thread safety or reset every model attribute: for example, a speaker-mode fallback mutates `self.spk_mode`. Serialize access to a shared instance unless your own concurrency tests establish otherwise.
+
+## Local Files and Batching
+
+Install the SDK using the [installation guide](installation/installation.md). The three examples below are standalone scripts with command-line arguments and require prepared local model snapshots and real audio. Their syntax and wrapper contracts are checked without downloading weights; they are not reported as full inference tests.
+
+For this example, invoke the script with a local ASR directory followed by one or more audio paths, for example `python transcribe.py /models/paraformer recording.wav recording2.wav`. The checks fail before model construction if those paths do not exist.
+
+```python
+import argparse
+from pathlib import Path
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+parser.add_argument("model_dir")
+parser.add_argument("audio", nargs="+")
+args = parser.parse_args()
+model_dir = Path(args.model_dir).expanduser().resolve(strict=True)
+if not model_dir.is_dir():
+ raise ValueError("model_dir must be a complete local model directory")
+audio = [str(Path(path).expanduser().resolve(strict=True)) for path in args.audio]
+model = AutoModel(model=str(model_dir), device="cpu", disable_update=True)
+results = model.generate(input=audio, batch_size=1)
+for result in results:
+ print(result.get("key"), result.get("text", ""))
+```
+
+`batch_size=1` processes a list serially through direct inference; raise it only for a model that supports batching and after measuring memory use. `batch_size_s` has a different meaning and only controls the wrapper's VAD path. VAD segmentation is not incremental microphone streaming, and it does not guarantee unlimited recording length or bounded total memory.
+
+Use a one-dimensional mono float32 waveform with a known sample rate. For models using the common audio loader, `fs` in `generate()` describes the array's source sample rate (fallback 16000); the model frontend supplies the target rate. Do not pass a stereo matrix or a list of numbers and assume it will be treated as one waveform: a Python list is normally a list of inputs. File decoding depends on the installed audio backends. Top-level bytes are handled by `load_bytes`: recognized containers are decoded/resampled to 16 kHz, otherwise bytes are interpreted as int16 PCM without sample-rate metadata. Prefer a decoded array with an explicit rate for ambiguous inputs. See [audio loading](../funasr/utils/load_utils.py) and [byte-input tests](../tests/test_load_audio_bytes.py).
+
+`prepare_data_iterator` also accepts manifests. A `.scp` line can be `utterance_id /path/to/audio.wav`; `.jsonl` records use `{"source": "/path/to/audio.wav", "key": "utterance_id"}`. `.json` is not parsed as an arbitrary JSON array by this iterator. Do not expose unrestricted paths or URLs directly to untrusted callers.
+
+## VAD, Timestamps, and Speakers
+
+Run this pipeline example with **ASR, VAD, punctuation, speaker directories, then audio**, in that order. It is intended for a compatible local Paraformer/SeACo-Paraformer, FSMN-VAD, CT-Transformer punctuation, and CAM++ setup, not every model combination.
+
+```python
+import argparse
+from pathlib import Path
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir", "audio"):
+ parser.add_argument(name)
+args = parser.parse_args()
+paths = {name: Path(value).expanduser().resolve(strict=True)
+ for name, value in vars(args).items()}
+if not all(paths[name].is_dir() for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir")):
+ raise ValueError("All model arguments must be complete local directories")
+model = AutoModel(
+ model=str(paths["asr_dir"]),
+ vad_model=str(paths["vad_dir"]),
+ punc_model=str(paths["punc_dir"]),
+ spk_model=str(paths["spk_dir"]),
+ spk_mode="punc_segment",
+ device="cpu",
+ disable_update=True,
+)
+for result in model.generate(input=str(paths["audio"]), return_spk_res=True):
+ print(result.get("text", ""))
+ for sentence in result.get("sentence_info", []):
+ print(sentence.get("start"), sentence.get("end"),
+ sentence.get("spk"), sentence.get("text", ""))
+```
+
+With `vad_model` configured, the wrapper detects regions, sorts them by duration for ASR batching, restores their order, and offsets timestamps to the original recording. Generic speaker clustering runs in this VAD path; setting only `spk_model` does not add diarization to direct inference. `punc_segment` needs usable punctuation and timestamps; missing punctuation or timestamp fields can change the mode to `vad_segment`. VAD boundaries are speech-region boundaries, not necessarily speaker changes. Labels such as `spk=0` are anonymous within a result, not verified identities or stable IDs across recordings.
+
+For `sentence_timestamp=True` without speakers, the current wrapper can return VAD-aligned sentence records when both punctuation and token timestamps are absent, or when punctuation/timestamp lengths fail alignment. Other combinations can return an empty `sentence_info`, including timestamps present but no punctuation result. This flag does not create a forced aligner.
+
+### Result Fields
+
+`generate()` returns a Python `list` of model-result dictionaries, not an OpenAI response object. Do not assume every model produces every field, or index `results[0]` without checking: some VAD empty-text paths can skip a result. No-speech VAD results commonly contain `{"key": ..., "text": "", "timestamp": []}`.
+
+| Field | Meaning |
+|---|---|
+| `key` | Input identifier, often a file stem or manifest key. Random keys are generated in other cases; they are not guaranteed globally unique. |
+| `text` | Decoded text. May contain model-specific rich tags; it is not necessarily plain display text. |
+| `timestamp` | When produced by the ASR paths described here: token/word/character interval pairs `[[start_ms, end_ms], ...]`. Granularity and availability depend on model/checkpoint. |
+| `timestamps` | Nano's CTC-backed alignment can produce dictionaries with `token`, `start_time`, `end_time` in **seconds**. VAD merging offsets these and can also add millisecond `timestamp` pairs. |
+| `sentence_info` | Pipeline sentence dictionaries with `start`/`end` in **milliseconds**, `text`, optional `timestamp`, and `spk` when speaker assignment runs. Some paths also include `sentence`. |
+| `raw_text` | Optional pre-punctuation text, not a guaranteed untouched copy after all possible processing. |
+| `value` | A standalone VAD model's speech intervals, not ASR text. Online VAD can emit incomplete boundaries; follow that model's streaming protocol. |
+
+Additional fields such as `words`, `ctc_timestamps`, or speaker embeddings are model-specific. Do not relabel SDK milliseconds as service seconds without conversion. See [timestamp regression tests](../tests/test_paraformer_timestamp_contract.py) and the model sources below.
+
+## Language, Hotwords, and Alignment Are Model-Specific
+
+| Implementation | Runtime controls in this checkout |
+|---|---|
+| [SeACo-Paraformer](../funasr/models/seaco_paraformer/model.py) | `hotword` (singular), fallback `None`: a whitespace-separated string, local `.txt` path, or supported URL. This parser expects a string, not Nano's list form. The `paraformer-zh` ModelScope alias maps to this implementation's checkpoint. |
+| [Paraformer](../funasr/models/paraformer/model.py) | `pred_timestamp` takes precedence when supplied; otherwise `output_timestamp` falls back to `False`. A checkpoint's saved options may enable timestamps. Do not generalize one Paraformer variant's hotword/timestamp behavior to all variants. |
+| [SenseVoice](../funasr/models/sense_voice/model.py) | `language="auto"`; language tokens include `zh`, `en`, `yue`, `ja`, `ko`. Unknown hints fall back to the auto token. `use_itn=False`; explicit `text_norm` overrides it. `output_timestamp=False`; enabling it uses this implementation's CTC alignment path. Generic decoder hotwords are not consumed here. |
+| [Fun-ASR-Nano](../funasr/models/fun_asr_nano/model.py) | `hotwords=[]` (plural, list of strings), `language=None`, `itn=True`. Language is inserted into a text prompt, not normalized through the SenseVoice token table. CTC timestamps depend on loaded components and complete checkpoint weights, not just an output flag. |
+| [Qwen3-ASR adapter](../funasr/models/qwen3_asr/model.py) | `language=None`; `auto` becomes `None`, and implemented ISO aliases such as `zh`/`en` map to full language names. `context=""` is the contextual prompt, not `hotword`. `return_time_stamps=False` or `output_timestamp=False`; either enables a request for timestamps, but a `forced_aligner` must have been configured at construction. Without it, the adapter warns and skips timestamps. |
+
+These are control conventions, not promises of language coverage, accuracy, or identical checkpoint contents across hubs. Nano disables CTC output when required tensors are missing; see [checkpoint validation](../funasr/models/fun_asr_nano/checkpoint_utils.py). MOSS-Transcribe-Diarize is a third-party **OpenMOSS** model with native joint transcription/diarization and a separate schema/dependency path: use the [MOSS guide](moss_transcribe_diarize.md), not the external VAD/CAM++ example above.
+
+### Text-Level Hotword Correction
+
+The wrapper also supports `postprocess_hotwords` (string/list/dict) and `postprocess_hotword_file` in `generate()`. Explicit mappings can use `{"wrong": "right"}` or a file line `wrong=>right`. `postprocess_hotword_threshold=0.85`, `postprocess_hotword_fuzzy=True`, and `return_postprocess_hotword_matches=False` are the fallbacks. Fuzzy matching may require `pypinyin` and `rapidfuzz`; setting `postprocess_hotword_fuzzy=False` selects explicit replacement only.
+
+This runs **after decoding**, updates text and sentence text, and intentionally leaves timestamps aligned to the original recognition. It neither biases the acoustic decoder nor re-aligns replacements. Inspect replacement details before using corrected text for word-level subtitles. Pass these options per call: `generate()` sends its `cfg`, not the construction defaults, to this postprocessor. See [implementation](../funasr/utils/postprocess_hotwords.py) and [tests](../tests/test_postprocess_hotwords.py).
+
+## Streaming Cache Lifecycle
+
+The following example is specifically for the local **Paraformer streaming** checkpoint, not an offline ASR model made streaming by `cache={}`. Invoke it with the model directory and a nonempty mono 16 kHz audio file. It follows the [upstream repository demo](../examples/industrial_data_pretraining/paraformer_streaming/demo.py) and [streaming implementation](../funasr/models/paraformer_streaming/model.py).
+
+```python
+import argparse
+from pathlib import Path
+import soundfile as sf
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+parser.add_argument("model_dir")
+parser.add_argument("audio")
+args = parser.parse_args()
+model_dir = Path(args.model_dir).expanduser().resolve(strict=True)
+if not model_dir.is_dir():
+ raise ValueError("model_dir must be a complete local streaming model directory")
+speech, sample_rate = sf.read(args.audio, dtype="float32")
+if sample_rate != 16000 or speech.ndim != 1 or len(speech) == 0:
+ raise ValueError("Expected nonempty mono 16 kHz audio")
+model = AutoModel(model=str(model_dir), device="cpu", disable_update=True)
+chunk_size = [0, 10, 5]
+stride = chunk_size[1] * 960
+cache = {}
+for start in range(0, len(speech), stride):
+ end = min(start + stride, len(speech))
+ result = model.generate(
+ input=speech[start:end], cache=cache, is_final=end == len(speech),
+ chunk_size=chunk_size, encoder_chunk_look_back=4,
+ decoder_chunk_look_back=1, batch_size=1,
+ )
+ print(result)
+```
+
+For this implementation, `chunk_size` falls back to `[0, 10, 5]` and `is_final` to `False`. The middle value times 960 gives the input stride: 9600 samples at 16 kHz is 600 ms. Both `encoder_chunk_look_back` and `decoder_chunk_look_back` default to **0** in source; **4** and **1** above are explicit demo settings, not wrapper defaults.
+
+Create a new `cache={}` per stream, pass the same dictionary on every ordered chunk, keep chunk/look-back settings fixed, and set `is_final=True` on the last chunk to flush buffered state. Paraformer streaming currently reinitializes its cache after finalization; discard it anyway when ending, cancelling, or starting a different stream. Do not share caches across recordings or simultaneous users. Keep `batch_size=1`: this implementation asserts one waveform per call. Returned text is for the decoded chunks in that call, not a guaranteed cumulative transcript; retain outputs in the application. WebSocket session protocols and server-side buffering are separate from this dictionary lifecycle.
+
+## Reproducibility and Offline Use
+
+1. Pin the SDK version/commit and dependency versions separately from model artifacts. Record the hub, full model ID, resolved upstream revision, configuration, and weight hashes for ASR and every auxiliary model. An alias or moving `master` is not a reproducible pin.
+2. The generic ModelScope loader forwards `model_revision` to its snapshot downloader. The generic Hugging Face helper accepts it but currently calls **`snapshot_download(model)`**, without `revision`, `local_files_only`, or `check_latest`. Do not claim `hub="hf", model_revision=...` pins that path. Some model adapters have their own loading logic; inspect the selected adapter too.
+3. For offline operation, prepare and verify complete local snapshots while online, including tokenizer/frontend files, configuration, weights, nested encoders/LLMs, and optional aligners. Pass existing local directories for all components. Local paths bypass generic hub resolution, but nested model code can still contact services or need missing dependencies; test under an actual network restriction.
+4. `disable_update=True` only skips the package update check. `check_latest=False` is not an offline guarantee, and these generic helpers do not provide a universal `local_files_only` switch. URL audio and URL hotword inputs still require network access. Cached hub aliases may still trigger hub requests.
+5. Keep `trust_remote_code=False` unless audited model code requires otherwise. ModelScope's generic loader can import `remote_code` (default `"model"`) when trusted; both generic hub loaders can install a model's `requirements.txt` when trusted, while their code-import behavior is not identical. A local snapshot is not automatically safe code.
+
+The FunASR software is [MIT-licensed](../LICENSE); model weights, datasets, third-party adapters, and dependencies can have different licenses. Review the selected model's own license and usage conditions before redistribution or deployment.
+
+## SDK and Service Boundaries
+
+| Interface | Contract to use |
+|---|---|
+| Python `AutoModel` | In-process model configuration, waveform inputs, streaming dictionaries, and model-specific Python results described here. No `base_url`, API key, or HTTP `response_format` contract. |
+| `funasr-server` | Packaged [CLI](../funasr/bin/server.py) creates [the server app](../funasr/bin/_server_app.py). Its `/v1/audio/transcriptions` endpoint is an OpenAI-style speech subset; `/asr` is a separate service-specific endpoint. Form fields, defaults, units, and speaker behavior belong to that server, not `generate()`. |
+| Example OpenAI-compatible server | [The example server](../examples/openai_api/server.py) is a different implementation from the packaged app. Use its [OpenAPI reference](../examples/openai_api/OPENAPI.md), [client recipes](../examples/openai_api/CLIENTS.md), and [security/gateway guide](../examples/openai_api/SECURITY.md), then compare the deployed server's live `/openapi.json`. Do not assume their defaults or response fields are identical. |
+| vLLM | `AutoModelVLLM`, FunASR's model-specific services, and native `vllm serve` are distinct entry points. Neither the SDK's `cache` nor a transcription HTTP endpoint proves realtime-session compatibility. Follow the [vLLM guide](vllm_guide.md) for the chosen route and checkpoint format. |
+| llama.cpp / GGUF | Separate C++ executables and GGUF artifacts, not the Python `AutoModel` kwargs or result schema. Use the [runtime guide](../runtime/llama.cpp/README.md). VAD alone is not speaker diarization. |
+
+The [Hydra inference entry point](../funasr/bin/inference.py) constructs `AutoModel` from configuration and calls `generate()`; it does not turn every CLI/config key into an HTTP form field. Before exposing any service, enforce authentication, TLS, upload limits, timeouts, and access restrictions at the appropriate boundary. A placeholder OpenAI-client API key is not access control.
diff --git a/docs/python_api_zh.md b/docs/python_api_zh.md
new file mode 100644
index 000000000..c4ed878c1
--- /dev/null
+++ b/docs/python_api_zh.md
@@ -0,0 +1,212 @@
+# Python SDK:AutoModel
+
+[English](python_api.md) | [安装](installation/installation_zh.md) | [模型选择](model_selection_zh.md)
+
+`from funasr import AutoModel` 在当前 Python 进程内运行模型。它不是 HTTP 客户端,也不实现完整的 OpenAI API。本文说明当前代码版本的实现,不代表所有历史 FunASR 版本或上游 checkpoint 的行为。
+
+## 模型构建与推理调用
+
+`AutoModel(**kwargs)` 解析模型配置、查找注册的实现、加载权重,并按需构建 VAD、标点和说话人模型。`model.generate(input, input_len=None, progress_callback=None, **cfg)` 使用已经加载的组件进行推理。在 `generate()` 中传入新的 `model`、`vad_model` 或 `device`,不是重新构建或迁移模型的受支持方式;需要另建实例。
+
+包装层接收 `**kwargs`,但没有覆盖所有模型的统一参数校验。参数能传进去,不等于选定模型会使用它。配置文件可能覆盖下表中的代码回退默认值。请结合 [AutoModel 源码](../funasr/auto/auto_model.py)、[注册表](../funasr/register.py)、[模型下载与解析](../funasr/download/download_model_from_hub.py) 和 [别名映射](../funasr/download/name_maps_from_hub.py) 阅读。
+
+### 构建参数
+
+| 参数 | 代码回退默认值 | 含义 |
+|---|---|---|
+| `model` | 必填 | 模型平台别名、完整模型 ID 或完整本地模型目录。别名依赖平台,不是版本锁定。 |
+| `hub` | `"ms"` | `"ms"`/`"modelscope"` 或 `"hf"`/`"huggingface"`。特殊的 `"openai"` 分支用于 Whisper 加载,不代表 HTTP API 兼容性。 |
+| `model_revision` | 平台加载器中为 `"master"` | ModelScope 会向下载器转发此版本。通用 Hugging Face 下载助手当前会忽略它,详见复现说明。 |
+| `device` | `"cuda"` | 例如 `"cuda:0"` 或 `"cpu"`。经检查不可用的加速后端会回退到 CPU;显式 `ngpu=0` 也会如此,并设置 `batch_size=1`。 |
+| `ngpu` | `1` | 设为零选择 CPU。它不是多 GPU 服务或模型分片配置。 |
+| `ncpu` | `4` | 正整数 CPU 线程数;非法值使用回退值,小于 1 的值限制为 1。修改进程级 PyTorch 线程数。 |
+| `vad_model`, `punc_model`, `spk_model` | `None` | 可选组件,在构建时加载。正确名称是 `vad_model`,拼错为 `vda_model` 会被拒绝。 |
+| `vad_kwargs`, `punc_kwargs`, `spk_kwargs` | `{}` | 子组件配置字典。设备继承主模型;平台和 CPU 线程数在子字典未指定时继承。 |
+| `vad_model_revision`, `punc_model_revision`, `spk_model_revision` | 各自为 `"master"` | 分别指定子组件版本,不继承 ASR 版本。这些顶层参数会覆盖子字典中的 `model_revision`。 |
+| `spk_mode` | `"punc_segment"` | 使用 `"punc_segment"` 或 `"vad_segment"`。校验还接受历史值 `"default"`,但后续句子构造分支未实现它,请勿选择。 |
+| `disable_update` | `False` | 仅禁用 FunASR 包版本检查,不会禁用模型下载。 |
+| `disable_pbar` | `False` | 隐藏包装层进度条。 |
+| `trust_remote_code` | 平台加载器中为 `False` | 允许模型附带的依赖安装及代码路径;启用前检查实际文件和依赖。 |
+
+### 单次推理参数
+
+| 参数 | 代码回退默认值 | 作用范围与限制 |
+|---|---|---|
+| `input` | 必填 | 音频路径、URL、波形、受支持的音频 bytes,或输入列表。标点等文本模型接收文本。 |
+| `input_len` | `None` | 直接推理包装层仅对单条 `data_type="fbank"` 输入将它转发为 `data_lengths`,不是统一的波形长度控制参数。 |
+| `progress_callback` | `None` | 直接推理每批结束后调用 `callback(current, total)`。VAD 流程可能向子组件调用转发它,因此不能当作整个流水线单调递增的全局进度。 |
+| `batch_size` | `1` | 直接推理每批输入数量。是否支持批量取决于模型。 |
+| `batch_size_s` | `300` | VAD 路径的秒级批处理预算,按最长补齐片段长度乘以片段数量估算,不是文件时长硬上限。CPU 的 VAD 路径按单片段处理。 |
+| `batch_size_threshold_s` | `60` | VAD 片段参与组批的时长阈值,不是 VAD 切分参数。 |
+| `merge_vad` | `False` | 为本次调用启用 VAD 区域合并。 |
+| `merge_length_s` | `15` | VAD 合并目标,在本次参数合并进 ASR 配置之前读取。当前代码版本应在构建时设置它。 |
+| `cache` | 包装层不维护会话 | 每次流式调用都传入调用方持有的字典。它不是模型下载缓存。 |
+| `sentence_timestamp` | `False` | 请求 VAD 流程输出句子记录,依赖实际时间戳与标点,部分情形可回退到 VAD 区域。 |
+| `return_spk_res` | `True` | 配置 VAD 与说话人模型时输出聚类结果。设为 `False` 并不能省去模型构建或片段说话人特征计算。 |
+| `preset_spk_num` | `None` | 向聚类后端提供可选的说话人数提示。 |
+| `return_spk_center` | `False` | 聚类运行时增加 `spk_embedding_center`。数组类型输出在 JSON 序列化前可能需要转换。 |
+| `return_raw_text` | `False` | 在实际应用标点的路径上保留标点前文本,不保证所有路径都返回该字段。 |
+
+`generate()` 在合并本次选项前恢复构建时保存的配置。每次调用都应明确传入本次需要的语言、批处理、热词等选项,不要依赖上一次调用遗留的值。配置重置不代表线程安全,也不重置每个模型属性,例如说话人模式回退会修改 `self.spk_mode`。除非自行验证过并发行为,否则应串行访问共享实例。
+
+## 本地文件与批处理
+
+先按[安装指南](installation/installation_zh.md) 安装 SDK。下面三个示例都是带命令行参数的独立脚本,需要提前准备完整本地模型快照和真实音频。这里只在不下载权重的条件下检查语法与包装层契约,不宣称完成了真实模型推理测试。
+
+第一个示例依次接收本地 ASR 模型目录和一个或多个音频路径,例如 `python transcribe.py /models/paraformer recording.wav recording2.wav`。路径不存在时会在模型构建前失败。
+
+```python
+import argparse
+from pathlib import Path
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+parser.add_argument("model_dir")
+parser.add_argument("audio", nargs="+")
+args = parser.parse_args()
+model_dir = Path(args.model_dir).expanduser().resolve(strict=True)
+if not model_dir.is_dir():
+ raise ValueError("model_dir must be a complete local model directory")
+audio = [str(Path(path).expanduser().resolve(strict=True)) for path in args.audio]
+model = AutoModel(model=str(model_dir), device="cpu", disable_update=True)
+results = model.generate(input=audio, batch_size=1)
+for result in results:
+ print(result.get("key"), result.get("text", ""))
+```
+
+`batch_size=1` 在直接推理路径中逐条处理列表;只有确认模型支持批量并测量过内存占用后再增大它。`batch_size_s` 的含义不同,只控制包装层的 VAD 路径。VAD 切分不是麦克风增量流式识别,也不保证无限录音长度或固定的总内存占用。
+
+波形应为采样率已知的一维单声道 float32 数组。使用通用音频加载器的模型,在 `generate()` 中通过 `fs` 指定数组的原始采样率,回退值为 16000;目标采样率由模型前端决定。不要把立体声矩阵或数字列表默认当作单条波形,Python 列表通常被解释为多条输入。文件解码能力取决于已安装的音频后端。顶层 bytes 由 `load_bytes` 处理:识别出的容器格式会被解码并重采样为 16 kHz,否则按没有采样率元数据的 int16 PCM 解释。输入格式有歧义时,优先使用解码后的数组并明确采样率。参见[音频加载代码](../funasr/utils/load_utils.py) 和 [bytes 输入测试](../tests/test_load_audio_bytes.py)。
+
+`prepare_data_iterator` 也接受清单文件。`.scp` 的一行可以是 `utterance_id /path/to/audio.wav`;`.jsonl` 使用 `{"source": "/path/to/audio.wav", "key": "utterance_id"}`。该迭代器不会把 `.json` 文件当作任意 JSON 数组解析。不要向不可信调用方直接开放任意路径或 URL 输入。
+
+## VAD、时间戳与说话人
+
+下面示例依次接收 **ASR、VAD、标点、说话人模型目录,最后是音频路径**。它面向兼容的本地 Paraformer/SeACo-Paraformer、FSMN-VAD、CT-Transformer 标点与 CAM++ 组合,不适用于任意模型组合。
+
+```python
+import argparse
+from pathlib import Path
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir", "audio"):
+ parser.add_argument(name)
+args = parser.parse_args()
+paths = {name: Path(value).expanduser().resolve(strict=True)
+ for name, value in vars(args).items()}
+if not all(paths[name].is_dir() for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir")):
+ raise ValueError("All model arguments must be complete local directories")
+model = AutoModel(
+ model=str(paths["asr_dir"]),
+ vad_model=str(paths["vad_dir"]),
+ punc_model=str(paths["punc_dir"]),
+ spk_model=str(paths["spk_dir"]),
+ spk_mode="punc_segment",
+ device="cpu",
+ disable_update=True,
+)
+for result in model.generate(input=str(paths["audio"]), return_spk_res=True):
+ print(result.get("text", ""))
+ for sentence in result.get("sentence_info", []):
+ print(sentence.get("start"), sentence.get("end"),
+ sentence.get("spk"), sentence.get("text", ""))
+```
+
+配置 `vad_model` 后,包装层检测语音区域、按时长排序组批识别、恢复原始顺序,再将时间戳偏移到原始录音坐标。通用说话人聚类在这条 VAD 路径运行;只设置 `spk_model` 不会给直接推理增加说话人分离。`punc_segment` 依赖可用的标点和时间戳,缺少标点或时间戳字段可能使模式变为 `vad_segment`。VAD 边界是语音区域边界,不一定是说话人切换点。`spk=0` 等标签是本次结果内的匿名标签,不是已验证的身份,也不是跨录音稳定的 ID。
+
+没有说话人模型而设置 `sentence_timestamp=True` 时,当前包装层可在标点和 token 时间戳均缺失,或标点与时间戳长度无法对齐时,返回按 VAD 区域对齐的句子记录。其他组合可能返回空的 `sentence_info`,包括已有时间戳但没有标点结果的情形。该开关不会创建强制对齐模型。
+
+### 返回字段
+
+`generate()` 返回 Python `list`,其中是模型结果字典,而不是 OpenAI 响应对象。不要假设所有模型都有全部字段,也不要未经检查直接使用 `results[0]`:VAD 路径中的部分空文本分支会跳过一条结果。没有检测到语音时,VAD 流程通常返回 `{"key": ..., "text": "", "timestamp": []}`。
+
+| 字段 | 含义 |
+|---|---|
+| `key` | 输入标识,通常是文件名主干或清单中的 key。其他情况下会生成随机 key,不保证全局唯一。 |
+| `text` | 解码文本,可能包含模型特有的富文本标签,不一定可直接作为纯文本展示。 |
+| `timestamp` | 本文 ASR 路径产生该字段时,通常为 token/词/字的区间对 `[[start_ms, end_ms], ...]`,单位为毫秒。粒度与可用性取决于模型和 checkpoint。 |
+| `timestamps` | Nano 的 CTC 对齐可返回包含 `token`、`start_time`、`end_time` 的字典,单位是**秒**。VAD 合并会偏移这些时间,并可额外生成毫秒单位的 `timestamp`。 |
+| `sentence_info` | 流水线句子字典,`start`/`end` 单位为**毫秒**,包含 `text`、可选 `timestamp`;完成说话人分配时包含 `spk`。部分路径也有 `sentence`。 |
+| `raw_text` | 可选的标点前文本,不保证它是所有可能处理前完全未改动的副本。 |
+| `value` | 独立 VAD 模型的语音区间,而非 ASR 文本。在线 VAD 可能输出尚未闭合的边界,应遵循对应模型的流式协议。 |
+
+`words`、`ctc_timestamps`、说话人特征等额外字段属于模型特有输出。不能不经换算就把 SDK 毫秒值当作服务端秒值。参见[时间戳回归测试](../tests/test_paraformer_timestamp_contract.py) 及下列模型源码。
+
+## 语言、热词和对齐取决于模型
+
+| 实现 | 当前代码版本的运行参数 |
+|---|---|
+| [SeACo-Paraformer](../funasr/models/seaco_paraformer/model.py) | `hotword` 为单数,回退值 `None`:空白分隔的字符串、本地 `.txt` 路径或受支持的 URL。此解析器要求字符串,不是 Nano 的列表形式。ModelScope 的 `paraformer-zh` 别名映射到该实现的 checkpoint。 |
+| [Paraformer](../funasr/models/paraformer/model.py) | 指定 `pred_timestamp` 时优先使用它,否则读取默认 `False` 的 `output_timestamp`。checkpoint 保存的配置可能启用时间戳。不能把某一 Paraformer 变体的热词或时间戳行为推广到所有变体。 |
+| [SenseVoice](../funasr/models/sense_voice/model.py) | `language="auto"`,语言 token 包含 `zh`、`en`、`yue`、`ja`、`ko`。未知提示回退到 auto token。`use_itn=False`,显式 `text_norm` 优先;`output_timestamp=False`,启用后使用该实现的 CTC 对齐路径。此处不读取通用解码热词参数。 |
+| [Fun-ASR-Nano](../funasr/models/fun_asr_nano/model.py) | `hotwords=[]` 为复数,接收字符串列表;`language=None`、`itn=True`。语言直接插入文本提示,不经过 SenseVoice 的语言 token 表归一化。CTC 时间戳取决于已加载的组件和完整权重,而不只是一个输出开关。 |
+| [Qwen3-ASR 适配器](../funasr/models/qwen3_asr/model.py) | `language=None`;`auto` 转为 `None`,实现中已有的 `zh`/`en` 等 ISO 别名转为完整语言名。上下文提示为 `context=""`,不是 `hotword`。`return_time_stamps=False` 或 `output_timestamp=False`,任一启用都会请求时间戳,但必须在构建时配置 `forced_aligner`。未配置时适配器会警告并跳过时间戳。 |
+
+这些是参数约定,不是语言覆盖、准确率或不同平台 checkpoint 内容相同的承诺。Nano 缺少所需张量时会禁用 CTC 输出,见 [checkpoint 校验](../funasr/models/fun_asr_nano/checkpoint_utils.py)。MOSS-Transcribe-Diarize 是第三方 **OpenMOSS** 模型,原生联合完成转写与说话人分离,拥有独立的输出结构和依赖路径。请使用 [MOSS 指南](moss_transcribe_diarize_zh.md),而不是照搬上面的外部 VAD/CAM++ 组合。
+
+### 文本级热词纠正
+
+包装层还支持在 `generate()` 中传入 `postprocess_hotwords`(字符串、列表或字典)和 `postprocess_hotword_file`。显式映射可以写成 `{"wrong": "right"}`,或文件中一行 `wrong=>right`。回退默认值为 `postprocess_hotword_threshold=0.85`、`postprocess_hotword_fuzzy=True`、`return_postprocess_hotword_matches=False`。模糊匹配可能需要 `pypinyin` 和 `rapidfuzz`;设为 `postprocess_hotword_fuzzy=False` 时只做显式替换。
+
+此处理发生在**解码之后**,会更新文本和句子文本,并有意保留与原始识别对齐的时间戳。它既不影响声学解码,也不对替换后的内容重新对齐。将纠正结果用于逐词字幕前,应检查替换明细。这些参数必须按调用传入:`generate()` 向后处理器传递的是本次 `cfg`,不是构建默认配置。参见[实现](../funasr/utils/postprocess_hotwords.py) 和[测试](../tests/test_postprocess_hotwords.py)。
+
+## 流式 Cache 生命周期
+
+下面示例只面向本地 **Paraformer 流式** checkpoint,不代表给离线模型传入 `cache={}` 就能变成流式。运行时依次传入模型目录和非空的单声道 16 kHz 音频文件。示例依据[仓库原有示例](../examples/industrial_data_pretraining/paraformer_streaming/demo.py) 和[流式实现](../funasr/models/paraformer_streaming/model.py)。
+
+```python
+import argparse
+from pathlib import Path
+import soundfile as sf
+from funasr import AutoModel
+
+parser = argparse.ArgumentParser()
+parser.add_argument("model_dir")
+parser.add_argument("audio")
+args = parser.parse_args()
+model_dir = Path(args.model_dir).expanduser().resolve(strict=True)
+if not model_dir.is_dir():
+ raise ValueError("model_dir must be a complete local streaming model directory")
+speech, sample_rate = sf.read(args.audio, dtype="float32")
+if sample_rate != 16000 or speech.ndim != 1 or len(speech) == 0:
+ raise ValueError("Expected nonempty mono 16 kHz audio")
+model = AutoModel(model=str(model_dir), device="cpu", disable_update=True)
+chunk_size = [0, 10, 5]
+stride = chunk_size[1] * 960
+cache = {}
+for start in range(0, len(speech), stride):
+ end = min(start + stride, len(speech))
+ result = model.generate(
+ input=speech[start:end], cache=cache, is_final=end == len(speech),
+ chunk_size=chunk_size, encoder_chunk_look_back=4,
+ decoder_chunk_look_back=1, batch_size=1,
+ )
+ print(result)
+```
+
+该实现的 `chunk_size` 回退值为 `[0, 10, 5]`,`is_final` 回退值为 `False`。中间值乘以 960 得到输入步长:16 kHz 下 9600 个采样点为 600 ms。源码中 `encoder_chunk_look_back` 和 `decoder_chunk_look_back` 的默认值都是 **0**,示例中的 **4** 和 **1** 是显式示例设置,不是包装层默认值。
+
+每条流创建一个新的 `cache={}`,按顺序处理各块时始终传入同一个字典,保持 chunk/look-back 设置固定,并在最后一块传入 `is_final=True`,冲刷缓冲状态。当前 Paraformer 流式实现在结束时会重新初始化 cache,但结束、取消或开始其他流时仍应丢弃旧字典。不要在不同录音或并发用户之间共享 cache。保持 `batch_size=1`,因为该实现断言每次只有一条波形。返回文本对应本次调用解码的块,不保证是累计全文;应用侧需要保留各次输出。WebSocket 会话协议及服务端缓冲机制与这里的字典生命周期是不同层次。
+
+## 版本复现与离线使用
+
+1. SDK 版本/commit、依赖版本与模型文件必须分别锁定。记录 ASR 及每个辅助模型的平台、完整模型 ID、解析后的上游版本、配置和权重哈希。别名或持续变化的 `master` 不是可复现的版本锁定。
+2. 通用 ModelScope 加载器会向快照下载器转发 `model_revision`。通用 Hugging Face 助手虽然接收该参数,当前实际调用却是 **`snapshot_download(model)`**,没有传入 `revision`、`local_files_only` 或 `check_latest`。不能宣称 `hub="hf", model_revision=...` 能锁定这条路径。有些适配器使用自己的加载逻辑,也要检查实际选用的适配器。
+3. 离线运行前,应在联网环境准备并验证完整本地快照,包括 tokenizer/前端文件、配置、权重、嵌套编码器/LLM 以及可选对齐器。为所有组件传入已存在的本地目录。本地路径绕过通用平台下载解析,但嵌套模型代码仍可能联网或缺少依赖,必须在实际网络限制下验证。
+4. `disable_update=True` 只跳过包更新检查。`check_latest=False` 不保证离线,这些通用下载助手也没有统一的 `local_files_only` 开关。URL 音频和 URL 热词仍需联网;已有缓存的模型别名也可能触发平台请求。
+5. 除非审查过的模型代码确实需要,否则保持 `trust_remote_code=False`。ModelScope 通用加载器在信任开启时可以导入 `remote_code`,默认值为 `"model"`;两个通用平台加载器都可能在信任开启时安装模型的 `requirements.txt`,但代码导入行为并不相同。本地快照不等于安全代码。
+
+FunASR 软件采用 [MIT 许可证](../LICENSE);模型权重、数据集、第三方适配器和依赖可能采用不同许可证。再分发或部署前,请检查具体模型自身的许可证和使用条件。
+
+## SDK 与服务接口边界
+
+| 接口 | 应遵循的契约 |
+|---|---|
+| Python `AutoModel` | 本文描述的进程内模型配置、波形输入、流式字典及模型特有的 Python 结果。没有 `base_url`、API key 或 HTTP `response_format` 契约。 |
+| `funasr-server` | 打包的 [CLI](../funasr/bin/server.py) 创建[服务应用](../funasr/bin/_server_app.py)。`/v1/audio/transcriptions` 是 OpenAI 风格的语音接口子集;`/asr` 是另一个服务特有接口。表单参数、默认值、单位及说话人行为属于该服务,不属于 `generate()`。 |
+| OpenAI 兼容示例服务 | [示例服务](../examples/openai_api/server.py) 与打包服务不是同一实现。可查阅它的 [OpenAPI 说明](../examples/openai_api/OPENAPI_zh.md)、[客户端示例](../examples/openai_api/CLIENTS.md) 和[安全/网关指南](../examples/openai_api/SECURITY_zh.md),再核对实际部署服务的 `/openapi.json`。不要假设二者默认值或响应字段相同。 |
+| vLLM | `AutoModelVLLM`、FunASR 模型专用服务与原生 `vllm serve` 是不同入口。SDK 的 `cache` 或一个 HTTP 转写端点,都不能证明兼容实时会话协议。按所选路线与 checkpoint 格式阅读 [vLLM 指南](vllm_guide_zh.md)。 |
+| llama.cpp / GGUF | 独立的 C++ 可执行程序与 GGUF 文件,不使用 Python `AutoModel` 的 kwargs 或结果结构。请参考[运行时指南](../runtime/llama.cpp/README.md)。仅有 VAD 不等于说话人分离。 |
+
+[Hydra 推理入口](../funasr/bin/inference.py) 从配置构建 `AutoModel` 后调用 `generate()`,不会把所有 CLI/配置项变成 HTTP 表单字段。开放服务前,应在相应边界落实鉴权、TLS、上传限制、超时及访问限制。OpenAI 客户端的占位 API key 不是访问控制。
diff --git a/docs/superpowers/plans/2026-09-06-comprehensive-documentation.md b/docs/superpowers/plans/2026-09-06-comprehensive-documentation.md
new file mode 100644
index 000000000..2eadea0a4
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-06-comprehensive-documentation.md
@@ -0,0 +1,32 @@
+# Comprehensive Documentation Implementation Plan
+
+**Goal:** Refactor remaining FunASR documentation into a coherent maintained system.
+**Architecture:** Existing Jinja/Markdown generator, expanded source catalogue,
+generated compatibility pages and curated task-oriented Markdown entry points.
+**Tech Stack:** Python, Jinja2, BeautifulSoup, Markdown, Playwright.
+
+- [x] Inventory repository and existing publication pipelines; create isolated worktree.
+- [x] Rewrite installation/tutorial; check syntax/contracts without claiming model inference.
+- [x] Add source-grounded Python API, training and model registration guides.
+- [x] Rebuild bilingual Model Zoo and runtime indexes; preserve release history.
+- [x] Expand catalogue and source-link coverage for service/security/client guides.
+- [x] Generate GitHub Pages compatibility routes from the same Markdown content.
+- [ ] Improve generated API navigation and keyboard/mobile behavior.
+- [ ] Run source contracts, link/fragment audits, full site and browser regressions.
+- [ ] Back up, sign/DCO, push, inspect exact-head CI, merge and deploy.
+- [ ] Verify both public hosts and save publication evidence.
+
+## Validation
+
+Run on ind-gpu8 in `/tmp/funasr-docs-comprehensive-20260906`:
+
+```sh
+PYTHONPATH=/tmp/funasr-redesign-python python -m pytest web-pages/product-site/tests -q
+PYTHONPATH=/tmp/funasr-redesign-python python web-pages/product-site/build.py --output /tmp/funasr-docs-comprehensive-build
+python web-pages/product-site/validate.py /tmp/funasr-docs-comprehensive-build
+```
+
+Run newly added learning/training/API source-contract tests and the pinned
+Playwright suite. Test compatibility export against a temporary output tree;
+preserve generated API data and all prior published route names. Independently
+review source correctness before publishing, not just string assertions.
diff --git a/docs/superpowers/specs/2026-09-06-comprehensive-documentation.md b/docs/superpowers/specs/2026-09-06-comprehensive-documentation.md
new file mode 100644
index 000000000..31c663b93
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-06-comprehensive-documentation.md
@@ -0,0 +1,30 @@
+# Comprehensive Documentation Refactor
+
+## Scope
+
+Extend the shipped product documentation system to the remaining maintained
+user-facing documentation: installation, SDK tutorial/API, Model Zoo, training,
+model registration, service contracts, security, client integrations, deployment
+and evaluation. Historical research and release records remain accessible but
+are not presented as current deployment recommendations.
+
+## Architecture
+
+- Repository Markdown owns guide content; the bilingual catalogue owns task
+ navigation and source mapping.
+- The website renders these sources. GitHub Pages compatibility routes render
+ the same guides, with a canonical website URL and no duplicated edited body.
+- Generated API reference remains source-derived and links to the authored SDK
+ contract. Preserve old API/tutorial/training/model URLs.
+- SDK, native C++ WebSocket, Python HTTP and native vLLM contracts stay distinct.
+- Preserve upstream model attribution and per-model license boundaries. Never
+ turn historical benchmark numbers into generic capacity promises.
+
+## Acceptance
+
+Core guides have prerequisites, executable examples or exact recipe references,
+expected outputs, limitations and next steps. Catalogue sources and relative
+links resolve; all emitted source fragment links work. Search includes the new
+topics. Desktop/mobile navigation and generated API reference remain usable.
+All relevant tests run on ind-gpu8 before signed DCO publication. Back up before
+push/merge/deploy; validate both public documentation hosts after publication.
diff --git a/docs/training.md b/docs/training.md
new file mode 100644
index 000000000..68f727a80
--- /dev/null
+++ b/docs/training.md
@@ -0,0 +1,148 @@
+# Training and Adaptation
+
+[简体中文](training_zh.md) | [Documentation](tutorial/README.md) | [Model registration](model_registration.md) | [Model selection](model_selection.md)
+
+This guide connects the checked-in recipes to their dataset and trainer implementations. Commands assume the repository root and an environment with this checkout and the selected recipe's dependencies installed. They are templates for your own data and reviewed model assets, not evidence that full training, convergence, GPU memory use, or export has been tested.
+
+## Choose the Work
+
+| Work | What changes | Starting point |
+| --- | --- | --- |
+| Inference | No weights change; decode existing audio | [Inference tutorial](tutorial/README.md) |
+| Adaptation | Fine-tune selected parameters, all parameters, or supported LoRA adapters from pretrained weights | Recipes below; first record a held-out baseline |
+| Training from scratch | Initialize a configured architecture without pretrained weights; prepare tokenizer, features and training schedule | [AISHELL Paraformer recipe](../examples/aishell/paraformer/demo_train_or_finetune.sh) and its [configuration](../examples/aishell/paraformer/conf/paraformer_conformer_12e_6d_2048_256.yaml) |
+
+Full-parameter fine-tuning is not training from scratch. The historical AISHELL script contains author-local paths and supplies `init_param`; replace its paths and deliberately configure initialization before using it for a scratch run. A script under `industrial_data_pretraining` does not reproduce the original industrial pretraining corpus or procedure.
+
+| Family | Real recipe and companion material | Important boundary |
+| --- | --- | --- |
+| SenseVoice | [finetune.sh](../examples/industrial_data_pretraining/sense_voice/finetune.sh), [English README](../examples/industrial_data_pretraining/sense_voice/README.md), [continual adaptation](../examples/industrial_data_pretraining/sense_voice/CONTINUAL_FINETUNING.md) | Rich labels and tokenizer special tokens matter. The script expects user-prepared `data/train_example.jsonl` and `data/val_example.jsonl`; it does not create them. |
+| FunASRNano | [finetune.sh](../examples/industrial_data_pretraining/fun_asr_nano/finetune.sh), [LoRA script](../examples/industrial_data_pretraining/fun_asr_nano/lora_finetune.sh), [fine-tuning guide](../examples/industrial_data_pretraining/fun_asr_nano/docs/finetune.md) | Default script freezes audio encoder/adaptor and unfreezes the LLM; it is not an all-parameter recipe. Pure LoRA additionally uses `llm_conf.use_lora=true`, `lora_only=true`, `llm_conf.freeze=true`. Audit trainable parameters, including any CTC component. |
+| Paraformer | [finetune.sh](../examples/industrial_data_pretraining/paraformer/finetune.sh), [README](../examples/industrial_data_pretraining/paraformer/README.md), [LoRA guide](../examples/industrial_data_pretraining/paraformer/README_LoRA_zh.md) | The industrial recipe explicitly selects `AudioDataset` / `IndexDSJsonl`. Paraformer LoRA is a separate recipe, not Nano's adapter configuration. |
+| MOSS-Transcribe-Diarize | [FunASR adapter source](../funasr/models/moss_transcribe_diarize/model.py) | Third-party OpenMOSS model. This adapter's `forward` raises an inference-only error; MOSS training is not covered here. |
+
+FunASR software is MIT-licensed; model weights, upstream code, datasets and derived checkpoints can have different licenses. Check each asset's terms and data consent before training or redistribution.
+
+## Prepare the Dataset
+
+Keep training, validation and final test sets separate, ideally split by speaker/session as well as utterance. Check duplicate IDs, matching audio/transcript IDs, file readability, decoded duration/sample rate, transcript normalization and language coverage. Resolve relative audio paths from the process working directory, not implicitly from the JSONL file's directory. Prefer stable local audio paths when reproducibility or privacy matters.
+
+### Paraformer: Audio and Text JSONL
+
+The [converter](../funasr/datasets/audio_datasets/scp2jsonl.py) joins `wav.scp` and text by utterance ID. Each input line is `utterance_id value`; transcript text may contain spaces. For a two-second recording the structural example is:
+
+```json
+{"key":"utt001","source":"data/audio/utt001.wav","source_len":200,"target":"hello world","target_len":2}
+```
+
+`key`, `source`, `target` are strings; length fields are integers. `source_len` is `int(samples_at_16kHz / 160)`, approximately 10 ms units, not seconds. The converter's `target_len` is whitespace-word count when spaces exist, otherwise character count; it is not universally a tokenizer count. The [index reader](../funasr/datasets/audio_datasets/index_ds.py) filters by configured source/target/token limits, and the [dataset](../funasr/datasets/audio_datasets/datasets.py) performs feature extraction/tokenization.
+
+Prepare `data/list/train_wav.scp`, `train_text.txt`, `val_wav.scp`, `val_text.txt`, then run from the repository root:
+
+```bash
+python -m funasr.datasets.audio_datasets.scp2jsonl \
+ ++scp_file_list='["data/list/train_wav.scp", "data/list/train_text.txt"]' \
+ ++data_type_list='["source", "target"]' \
+ ++jsonl_file_out=data/list/train.jsonl
+python -m funasr.datasets.audio_datasets.scp2jsonl \
+ ++scp_file_list='["data/list/val_wav.scp", "data/list/val_text.txt"]' \
+ ++data_type_list='["source", "target"]' \
+ ++jsonl_file_out=data/list/val.jsonl
+```
+
+The converter can skip missing audio and emit incomplete records when transcripts are missing. Compare input/output counts and reject incomplete rows; a successful process exit is insufficient. Use trusted CLI configuration only: this historical converter has an `eval` fallback for string-valued lists.
+
+### SenseVoice: Preserve Rich Labels
+
+For the `SenseVoiceCTCDataset` path, add explicit supervision fields to the audio/text schema:
+
+```json
+{"key":"utt001","source":"data/audio/utt001.wav","source_len":200,"target":"你好","target_len":2,"text_language":"<|zh|>","emo_target":"<|NEUTRAL|>","event_target":"<|Speech|>","with_or_wo_itn":"<|woitn|>"}
+```
+
+These strings must be appropriate labels for the recording, not placeholders applied indiscriminately. The [CTC dataset implementation](../funasr/datasets/sense_voice_datasets/datasets.py) defaults missing fields to the values above; defaults are not validated ground truth. The older `SenseVoiceDataset` is a different dataset implementation. Keep the dataset class consistent with the selected model configuration.
+
+[sensevoice2jsonl.py](../funasr/datasets/audio_datasets/sensevoice2jsonl.py) accepts aligned source/target/language/emotion/event files via `scp_file_list` and `data_type_list`. If language, emotion or event labels are missing, it invokes SenseVoice to generate pseudo-labels, which can download/run a model. Its ITN flag uses a punctuation heuristic. Review labels and normalization before training. Do not invent a new language tag without coordinated tokenizer/model changes; see the [continual fine-tuning guide](../examples/industrial_data_pretraining/sense_voice/CONTINUAL_FINETUNING.md).
+
+### FunASRNano: ChatML JSONL
+
+Nano does not consume the plain Paraformer schema in its provided recipe. See the actual [training sample](../examples/industrial_data_pretraining/fun_asr_nano/data/train_example.jsonl) and [validation sample](../examples/industrial_data_pretraining/fun_asr_nano/data/val_example.jsonl). A structural example, whose lengths must be recomputed for real data:
+
+```json
+{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"语音转写:<|startofspeech|>!data/audio/utt001.wav<|endofspeech|>"},{"role":"assistant","content":"你好"}],"speech_length":198,"text_length":1}
+```
+
+`messages` is a list of role/content dictionaries; assistant content is the target transcript. The [recipe converter](../examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py) pairs SCP/transcript lines in order, requires matching IDs, computes `speech_length = int((duration * 1000 - 25) // 10 + 1)`, and obtains `text_length` from `Qwen/Qwen3-0.6B` tokenization. It may fetch that tokenizer or URL audio. Line-count mismatches are only warnings, and bad pairs can be omitted: check the resulting counts and every error.
+
+Use your prepared inputs and output files rather than overwriting the shipped examples:
+
+```bash
+python examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py \
+ ++scp_file=data/list/train_wav.scp \
+ ++transcript_file=data/list/train_text.txt \
+ ++jsonl_file=data/list/nano_train.jsonl
+python examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py \
+ ++scp_file=data/list/val_wav.scp \
+ ++transcript_file=data/list/val_text.txt \
+ ++jsonl_file=data/list/nano_val.jsonl
+```
+
+## Validate Small, Then Launch
+
+1. Pin the checkout and model assets; record dependencies, tokenizer/frontend settings, GPU configuration, data hashes and random seed. Review all downloaded Python and requirements before enabling `trust_remote_code`.
+2. Build tiny, disjoint `data/list/train_smoke.jsonl` and `data/list/val_smoke.jsonl` from validated records. Actually load their audio and tokenize their targets. Check non-empty batches after length filtering, finite loss and the intended trainable parameter names.
+3. Run a short training/validation/checkpoint cycle before scaling. Do not run the historical shell scripts blindly: they set GPU IDs, output paths and working-directory-dependent paths internally and do not generally forward appended CLI overrides.
+
+Here is a root-relative Paraformer smoke-run template derived from the industrial recipe. It requires a compatible GPU, installed training dependencies, the two prepared JSONL files, and a reviewed complete model directory at `models/paraformer`. The token budget `2000` is a starting value for short clips, not a memory guarantee; reduce it only while ensuring individual samples still fit. One epoch is only small if the input dataset is small.
+
+```bash
+CUDA_VISIBLE_DEVICES=0 torchrun --nnodes=1 --nproc_per_node=1 \
+ --master_addr=127.0.0.1 --master_port=29619 \
+ funasr/bin/train_ds.py \
+ ++model=./models/paraformer \
+ ++train_data_set_list=data/list/train_smoke.jsonl \
+ ++valid_data_set_list=data/list/val_smoke.jsonl \
+ ++dataset=AudioDataset ++dataset_conf.index_ds=IndexDSJsonl \
+ ++dataset_conf.data_split_num=1 ++dataset_conf.batch_sampler=BatchSampler \
+ ++dataset_conf.batch_type=token ++dataset_conf.batch_size=2000 \
+ ++dataset_conf.sort_size=16 ++dataset_conf.num_workers=0 \
+ ++train_conf.max_epoch=1 ++train_conf.log_interval=1 \
+ ++train_conf.resume=false ++train_conf.use_deepspeed=false \
+ ++train_conf.validate_interval=1 ++train_conf.save_checkpoint_interval=1 \
+ ++train_conf.keep_nbest_models=1 ++train_conf.avg_nbest_model=1 \
+ ++optim_conf.lr=0.0002 ++output_dir=./outputs/paraformer-smoke
+```
+
+Use a new output directory for every fresh experiment and an available rendezvous port. For SenseVoice or Nano, start from that family's recipe/configuration and schema, not a substitution into this `AudioDataset` command. Nano's scripts locate `funasr-train-ds` on `PATH`; confirm it belongs to the intended installation. The SenseVoice and Paraformer scripts contain DeepSpeed config paths even with `use_deepspeed=false`; verify a real config before enabling DeepSpeed. Full distributed training and resource sizing require separate validation.
+
+## Checkpoints and Resume
+
+The [entry point](../funasr/bin/train_ds.py) calls [Trainer.resume_checkpoint](../funasr/train_utils/trainer_ds.py). In the non-DeepSpeed path, `++train_conf.resume=true` restores `output_dir/model.pt`, including model, optimizer, scheduler and available scaler/progress state. It is a boolean switch, not an arbitrary checkpoint path. If that file is missing, the trainer reports no resume and continues. Confirm restoration in logs.
+
+To continue the smoke run, rerun its command with the same output directory/configuration, `++train_conf.resume=true` and `++train_conf.max_epoch=2`. The epoch limit is total, not additional epochs. `++init_param=...` loads initial weights; it does not restore optimizer/progress state. Use a fresh output directory and `resume=false` for a new adaptation stage with a selected initialization checkpoint.
+
+Non-DeepSpeed saves include `model.pt`, `model.pt.ep{epoch}` or `model.pt.ep{epoch}.{step}`; `model.pt.best` depends on validation ranking. DeepSpeed saves use checkpoint directories/tags and require its corresponding restore/conversion path. Do not treat those directories or incomplete/adaptor-only state as ordinary standalone weights. Preserve configuration, tokenizer/frontend assets and base-model provenance; inspect save exclusions and LoRA settings. A checkpoint file alone is not necessarily a loadable model directory.
+
+## Evaluate and Export
+
+Load a prepared Paraformer model directory and a real selected checkpoint for a one-file sanity check:
+
+```python
+from pathlib import Path
+from funasr import AutoModel
+
+checkpoint = Path("outputs/paraformer-smoke/model.pt")
+assert checkpoint.is_file(), checkpoint
+model = AutoModel(
+ model="./models/paraformer",
+ hub="ms",
+ init_param=str(checkpoint),
+ device="cpu",
+ disable_update=True,
+)
+print(model.generate(input="data/audio/heldout.wav"))
+```
+
+Then decode an untouched held-out set with the same normalization and CER/WER unit definition for baseline and adapted weights. Report per-domain/language results as well as aggregate scores, retained-task regressions, data counts and checkpoint identity. Training loss or trainer validation accuracy is not automatically transcription CER/WER. [Nano's fine-tuning guide](../examples/industrial_data_pretraining/fun_asr_nano/docs/finetune.md) retains the decoding/normalization/scoring references; [decode.py](../examples/industrial_data_pretraining/fun_asr_nano/decode.py) uses VAD and `remote_code="./model.py"`, so it assumes the recipe working directory. That [legacy local class](../examples/industrial_data_pretraining/fun_asr_nano/model.py) can replace the [built-in Nano class](../funasr/models/fun_asr_nano/model.py). Do not assume it preserves built-in LoRA support; verify the active class, adapter injection and loaded keys before evaluation.
+
+Export is a separate compatibility task. [SenseVoice's ONNX example](../examples/industrial_data_pretraining/sense_voice/export.py), [Paraformer export example](../examples/industrial_data_pretraining/paraformer/export.py) and [export utility](../funasr/utils/export_utils.py) are entry points, not universal support promises. The Paraformer example itself selects a contextual checkpoint; inspect and deliberately choose your model. Model-specific export hooks, tokenizer/frontend assets, dynamic shapes and runtime decoding all need validation. Compare the exported runtime against Python on held-out inputs before deployment. No full training, quality benchmark, real-checkpoint resume, model download or export run was performed for this documentation change.
diff --git a/docs/training_zh.md b/docs/training_zh.md
new file mode 100644
index 000000000..ee40dd2f4
--- /dev/null
+++ b/docs/training_zh.md
@@ -0,0 +1,148 @@
+# 训练与适配
+
+[English](training.md) | [文档](tutorial/README_zh.md) | [模型注册](model_registration_zh.md) | [模型选择](model_selection.md)
+
+本指南把仓库中的训练脚本与数据集、训练器实现对应起来。命令默认从仓库根目录执行,环境需安装当前 checkout 及所选 recipe 的依赖。命令是针对自有数据和已审查模型资产的模板,不表示已验证完整训练、收敛、显存需求或导出。
+
+## 先确定任务
+
+| 任务 | 改变什么 | 入口 |
+| --- | --- | --- |
+| 推理 | 不修改权重,识别已有音频 | [推理教程](tutorial/README_zh.md) |
+| 适配 | 从预训练权重开始,微调部分参数、全部参数或受支持的 LoRA 适配器 | 下表中的 recipe;先记录独立留出集基线 |
+| 从头训练 | 不加载预训练权重,准备架构配置、分词器、特征及训练计划 | [AISHELL Paraformer 脚本](../examples/aishell/paraformer/demo_train_or_finetune.sh)及其[配置](../examples/aishell/paraformer/conf/paraformer_conformer_12e_6d_2048_256.yaml) |
+
+全参数微调不等于从头训练。历史 AISHELL 脚本包含作者本机路径,且传入了 `init_param`;必须替换路径并明确配置初始化方式,才能用于从头训练。目录名 `industrial_data_pretraining` 不表示公开脚本可复现原始工业预训练数据和流程。
+
+| 模型系列 | 实际 recipe 与说明 | 使用边界 |
+| --- | --- | --- |
+| SenseVoice | [finetune.sh](../examples/industrial_data_pretraining/sense_voice/finetune.sh)、[中文说明](../examples/industrial_data_pretraining/sense_voice/README_zh.md)、[持续适配](../examples/industrial_data_pretraining/sense_voice/CONTINUAL_FINETUNING_zh.md) | 需要正确的富标签与特殊 token。脚本使用用户准备的 `data/train_example.jsonl`、`data/val_example.jsonl`,不会自动创建这些文件。 |
+| FunASRNano | [finetune.sh](../examples/industrial_data_pretraining/fun_asr_nano/finetune.sh)、[LoRA 脚本](../examples/industrial_data_pretraining/fun_asr_nano/lora_finetune.sh)、[微调指南](../examples/industrial_data_pretraining/fun_asr_nano/docs/finetune_zh.md) | 默认冻结音频编码器和适配模块、解冻 LLM,并非全参数方案。纯 LoRA 另设 `llm_conf.use_lora=true`、`lora_only=true`、`llm_conf.freeze=true`。应检查实际可训练参数,包括可能存在的 CTC 组件。 |
+| Paraformer | [finetune.sh](../examples/industrial_data_pretraining/paraformer/finetune.sh)、[中文说明](../examples/industrial_data_pretraining/paraformer/README_zh.md)、[LoRA 指南](../examples/industrial_data_pretraining/paraformer/README_LoRA_zh.md) | 工业数据微调脚本显式使用 `AudioDataset` / `IndexDSJsonl`。Paraformer LoRA 是独立 recipe,不能套用 Nano 的适配器配置。 |
+| MOSS-Transcribe-Diarize | [FunASR 适配器源码](../funasr/models/moss_transcribe_diarize/model.py) | 属于第三方 OpenMOSS 模型。该适配器的 `forward` 明确抛出仅支持推理的异常;本指南不覆盖 MOSS 训练。 |
+
+FunASR 软件采用 MIT 许可证;模型权重、上游代码、数据集和派生 checkpoint 可能采用不同条款。训练、分发前请检查各项许可和数据授权。
+
+## 准备数据
+
+训练集、验证集和最终测试集应分开,尽量按说话人、录音会话划分,而非只按句子划分。检查重复 ID、音频与文本 ID 对齐、文件可读性、解码后的时长与采样率、文本规整方式及语言覆盖。音频相对路径按进程工作目录解析,不会自动按 JSONL 所在目录解析。需要可复现或隐私保护时优先使用稳定的本地音频路径。
+
+### Paraformer:音频与文本 JSONL
+
+[转换器](../funasr/datasets/audio_datasets/scp2jsonl.py)按 utterance ID 合并 SCP 和文本;输入每行是 `utterance_id value`,文本可以包含空格。以下为两秒音频的结构示例:
+
+```json
+{"key":"utt001","source":"data/audio/utt001.wav","source_len":200,"target":"hello world","target_len":2}
+```
+
+`key`、`source`、`target` 是字符串,长度字段是整数。`source_len` 为 `int(16kHz采样点数 / 160)`,约为 10 ms 单位,不是秒。转换器对有空格的文本按空格统计词数,否则统计字符数,得到 `target_len`;它并不统一等于分词器 token 数。[索引读取器](../funasr/datasets/audio_datasets/index_ds.py)按配置的长度限制过滤数据,[数据集](../funasr/datasets/audio_datasets/datasets.py)再执行特征提取和分词。
+
+准备 `data/list/train_wav.scp`、`train_text.txt`、`val_wav.scp`、`val_text.txt`,从仓库根目录执行:
+
+```bash
+python -m funasr.datasets.audio_datasets.scp2jsonl \
+ ++scp_file_list='["data/list/train_wav.scp", "data/list/train_text.txt"]' \
+ ++data_type_list='["source", "target"]' \
+ ++jsonl_file_out=data/list/train.jsonl
+python -m funasr.datasets.audio_datasets.scp2jsonl \
+ ++scp_file_list='["data/list/val_wav.scp", "data/list/val_text.txt"]' \
+ ++data_type_list='["source", "target"]' \
+ ++jsonl_file_out=data/list/val.jsonl
+```
+
+转换器可能跳过缺失音频,或在缺少文本时输出不完整记录。必须比较输入输出数量并拒绝不完整行,不能只看进程退出状态。CLI 配置应来自可信来源:该历史转换器对字符串列表存在 `eval` 回退分支。
+
+### SenseVoice:保留富标签
+
+使用 `SenseVoiceCTCDataset` 时,在音频文本结构上增加明确的监督字段:
+
+```json
+{"key":"utt001","source":"data/audio/utt001.wav","source_len":200,"target":"你好","target_len":2,"text_language":"<|zh|>","emo_target":"<|NEUTRAL|>","event_target":"<|Speech|>","with_or_wo_itn":"<|woitn|>"}
+```
+
+标签必须对应实际录音,不能不加区分地填入示例值。[CTC 数据集源码](../funasr/datasets/sense_voice_datasets/datasets.py)在缺字段时使用上例默认值,但默认值不是经过验证的标注。旧版 `SenseVoiceDataset` 是另一种实现,应保持数据集类与所选模型配置一致。
+
+[sensevoice2jsonl.py](../funasr/datasets/audio_datasets/sensevoice2jsonl.py)通过 `scp_file_list`、`data_type_list` 接收对齐的音频、文本、语言、情感、事件文件。如果缺少语言、情感或事件标签,它会调用 SenseVoice 生成伪标签,可能下载并运行模型;ITN 标志由标点启发式生成。训练前需审核标签与规整规则。增加新语言标签不是改一个字符串,需要分词器与模型协同修改,参见[持续微调指南](../examples/industrial_data_pretraining/sense_voice/CONTINUAL_FINETUNING_zh.md)。
+
+### FunASRNano:ChatML JSONL
+
+Nano 提供的 recipe 不使用普通 Paraformer 数据结构。实际文件见[训练示例](../examples/industrial_data_pretraining/fun_asr_nano/data/train_example.jsonl)和[验证示例](../examples/industrial_data_pretraining/fun_asr_nano/data/val_example.jsonl)。下面仅展示结构,真实数据必须重新计算长度:
+
+```json
+{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"语音转写:<|startofspeech|>!data/audio/utt001.wav<|endofspeech|>"},{"role":"assistant","content":"你好"}],"speech_length":198,"text_length":1}
+```
+
+`messages` 是 role/content 字典列表;assistant 内容为参考转写。[recipe 转换器](../examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py)按行配对 SCP 和文本并要求 ID 一致,计算 `speech_length = int((duration * 1000 - 25) // 10 + 1)`,用 `Qwen/Qwen3-0.6B` 分词得到 `text_length`。可能下载分词器或 URL 音频。行数不一致只会产生警告,错误样本可能被省略,必须核对输出数量和全部错误。
+
+使用自己的输入输出文件,不要覆盖仓库示例:
+
+```bash
+python examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py \
+ ++scp_file=data/list/train_wav.scp \
+ ++transcript_file=data/list/train_text.txt \
+ ++jsonl_file=data/list/nano_train.jsonl
+python examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py \
+ ++scp_file=data/list/val_wav.scp \
+ ++transcript_file=data/list/val_text.txt \
+ ++jsonl_file=data/list/nano_val.jsonl
+```
+
+## 先做小规模验证
+
+1. 固定 checkout 与模型资产,记录依赖、分词器与前端配置、GPU 配置、数据哈希和随机种子。启用 `trust_remote_code` 前审核下载的 Python 与 requirements。
+2. 用已验证样本准备小而互不重叠的 `data/list/train_smoke.jsonl`、`data/list/val_smoke.jsonl`,实际加载音频、分词,确认长度过滤后仍有非空 batch、loss 有限、可训练参数符合预期。
+3. 扩大规模前先完成短训练、验证和 checkpoint 保存流程。不要直接运行历史 shell 脚本:其内部设置 GPU、输出目录和依赖工作目录的路径,通常不会透传附加在脚本末尾的 CLI 参数。
+
+以下是从工业数据 recipe 提炼的 Paraformer 小规模验证模板,路径以仓库根目录为基准。需要兼容 GPU、已安装训练依赖、上述两个 JSONL 文件,以及位于 `models/paraformer` 的完整且已审查模型目录。`2000` 是用于短音频的起始 token 预算,不是显存保证;调整时仍须确保单条样本能容纳。只有数据集足够小,一个 epoch 才是小规模运行。
+
+```bash
+CUDA_VISIBLE_DEVICES=0 torchrun --nnodes=1 --nproc_per_node=1 \
+ --master_addr=127.0.0.1 --master_port=29619 \
+ funasr/bin/train_ds.py \
+ ++model=./models/paraformer \
+ ++train_data_set_list=data/list/train_smoke.jsonl \
+ ++valid_data_set_list=data/list/val_smoke.jsonl \
+ ++dataset=AudioDataset ++dataset_conf.index_ds=IndexDSJsonl \
+ ++dataset_conf.data_split_num=1 ++dataset_conf.batch_sampler=BatchSampler \
+ ++dataset_conf.batch_type=token ++dataset_conf.batch_size=2000 \
+ ++dataset_conf.sort_size=16 ++dataset_conf.num_workers=0 \
+ ++train_conf.max_epoch=1 ++train_conf.log_interval=1 \
+ ++train_conf.resume=false ++train_conf.use_deepspeed=false \
+ ++train_conf.validate_interval=1 ++train_conf.save_checkpoint_interval=1 \
+ ++train_conf.keep_nbest_models=1 ++train_conf.avg_nbest_model=1 \
+ ++optim_conf.lr=0.0002 ++output_dir=./outputs/paraformer-smoke
+```
+
+每次新实验使用新输出目录,并选用空闲 rendezvous 端口。SenseVoice、Nano 应从各自 recipe、模型配置和数据结构出发,不能只替换上例的模型名而保留 `AudioDataset`。Nano 脚本通过 `PATH` 找到 `funasr-train-ds`,请确认它属于预期安装。SenseVoice、Paraformer 脚本在 `use_deepspeed=false` 时也传入 DeepSpeed 配置路径;启用前必须确认真实配置存在。完整分布式训练和资源需求仍需单独验证。
+
+## Checkpoint 与恢复
+
+[训练入口](../funasr/bin/train_ds.py)调用 [Trainer.resume_checkpoint](../funasr/train_utils/trainer_ds.py)。非 DeepSpeed 分支中,`++train_conf.resume=true` 从 `output_dir/model.pt` 恢复模型、优化器、调度器及存在的 scaler/训练进度状态。这是布尔开关,不是任意 checkpoint 路径。文件不存在时训练器会提示未恢复并继续,必须检查日志确认实际恢复成功。
+
+继续上面的 smoke run 时,保持输出目录和配置,改为 `++train_conf.resume=true`、`++train_conf.max_epoch=2` 后重新执行。epoch 上限是总轮数,不是新增轮数。`++init_param=...` 仅用于初始化权重,不恢复优化器和进度。新适配阶段应使用新输出目录、`resume=false` 和明确选定的初始化权重。
+
+非 DeepSpeed 保存包括 `model.pt`、`model.pt.ep{epoch}` 或 `model.pt.ep{epoch}.{step}`,`model.pt.best` 取决于验证排序。DeepSpeed 使用目录/tag,需要对应恢复或转换流程。不要把这些目录、不完整状态或仅适配器状态当成普通独立权重。保留配置、分词器、前端资产和基座模型来源,检查保存排除项与 LoRA 配置。单个 checkpoint 文件不一定是可加载的模型目录。
+
+## 评估与导出
+
+使用准备好的 Paraformer 模型目录及真实 checkpoint,先检查单条音频:
+
+```python
+from pathlib import Path
+from funasr import AutoModel
+
+checkpoint = Path("outputs/paraformer-smoke/model.pt")
+assert checkpoint.is_file(), checkpoint
+model = AutoModel(
+ model="./models/paraformer",
+ hub="ms",
+ init_param=str(checkpoint),
+ device="cpu",
+ disable_update=True,
+)
+print(model.generate(input="data/audio/heldout.wav"))
+```
+
+随后在未参与训练或选模的留出集上解码,基线与适配模型使用一致的规整方式及 CER/WER 单位定义。报告各领域、各语言和整体结果、原任务退化、样本数量与 checkpoint 身份。训练 loss 或训练器验证 accuracy 不自动等于转写 CER/WER。[Nano 微调指南](../examples/industrial_data_pretraining/fun_asr_nano/docs/finetune_zh.md)保留了解码、规整、评分入口;[decode.py](../examples/industrial_data_pretraining/fun_asr_nano/decode.py)使用 VAD 和 `remote_code="./model.py"`,需要 recipe 工作目录。该[历史本地类](../examples/industrial_data_pretraining/fun_asr_nano/model.py)可能覆盖[内置 Nano 类](../funasr/models/fun_asr_nano/model.py),不能假定它保留内置 LoRA 功能;评估前确认实际类、适配器注入和权重加载结果。
+
+导出是单独的兼容性验证任务。[SenseVoice ONNX 示例](../examples/industrial_data_pretraining/sense_voice/export.py)、[Paraformer 导出示例](../examples/industrial_data_pretraining/paraformer/export.py)及[导出工具](../funasr/utils/export_utils.py)只是入口,不承诺所有模型均支持。Paraformer 示例实际选择 contextual checkpoint,必须检查并明确替换为自己的模型。模型导出 hook、分词器、前端、动态形状和运行时解码都需要验证。部署前在留出输入上比较导出运行时与 Python 输出。本次文档修改未运行完整训练、质量基准、真实 checkpoint 恢复、模型下载或模型导出。
diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md
index bcd329a7f..aeeae4a95 100644
--- a/docs/tutorial/README.md
+++ b/docs/tutorial/README.md
@@ -1,628 +1,153 @@
-([简体中文](https://github.com/modelscope/FunASR/blob/main/docs/tutorial/README_zh.md)|English)
+([简体中文](./README_zh.md) | English)
-FunASR has open-sourced a large number of pre-trained models on industrial data. Each model weight has its own license: record the exact model ID and revision, and follow the license materials on its model card. The [FunASR Model License Agreement](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE) applies only when that model card explicitly links to it. Below, we list some representative models. For a comprehensive list, please refer to our [Model Zoo](https://github.com/modelscope/FunASR/tree/main/model_zoo).
+# Python SDK tutorial
-<div align="center">
-<h4>
- <a href="#Inference"> Model Inference </a>
-|<a href="#Training"> Model Training and Testing </a>
-|<a href="#Export"> Model Export and Testing </a>
-|<a href="#new-model-registration-tutorial"> New Model Registration Tutorial </a>
-</h4>
-</div>
+Start with [installation and environment verification](../installation/installation.md). This path covers one transcript, result inspection, VAD, batching, and model-specific options. For model selection, languages, dependencies, and model cards, use the [Model Zoo](../../model_zoo/readme.md), not a universal capability list. No local setup yet? See the [Colab quickstart](../../examples/colab/README.md).
-<a name="Inference"></a>
-## Model Inference
+FunASR software uses the [MIT license](../../LICENSE). Each model weight has its own license: record the full model ID and revision, and follow its model card. The [FunASR Model License Agreement](../../MODEL_LICENSE) applies only when the model card explicitly links to it. Third-party integrations remain third-party models; for example, MOSS-Transcribe-Diarize is from OpenMOSS, not a FunASR-trained checkpoint.
-### Quick Start
+<a id="Inference" name="Inference"></a>
+## 1. Produce a first transcript
-No local setup? Run the [Colab quickstart](../../examples/colab/) first, then move to the command line when you are ready.
-
-For command-line invocation:
-```shell
-funasr ++model=paraformer-zh ++vad_model="fsmn-vad" ++punc_model="ct-punc" ++input=asr_example_zh.wav
-```
-
-For python code invocation (recommended):
-
-```python
-from funasr import AutoModel
-
-model = AutoModel(model="paraformer-zh")
-
-res = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav")
-print(res)
-```
-
-### API Description
-#### AutoModel Definition
-```python
-model = AutoModel(model=[str], device=[str], ncpu=[int], output_dir=[str], batch_size=[int], hub=[str], **kwargs)
-```
-- `model`(str): model name in the [Model Repository](https://github.com/modelscope/FunASR/tree/main/model_zoo), or a model path on local disk.
-- `device`(str): `cuda:0` (default gpu0) for using GPU for inference, specify `cpu` for using CPU. `mps`: Mac computers with M-series chips use MPS for inference. `xpu`: Uses Intel GPU for inference.
-- `ncpu`(int): `4` (default), sets the number of threads for CPU internal operations.
-- `output_dir`(str): `None` (default), set this to specify the output path for the results.
-- `batch_size`(int): `1` (default), the number of samples per batch during decoding.
-- `hub`(str):`ms` (default) to download models from ModelScope. Use `hf` to download models from Hugging Face.
-- `**kwargs`(dict): Any parameters found in config.yaml can be directly specified here, for instance, the maximum segmentation length in the vad model max_single_segment_time=6000 (milliseconds).
-
-#### AutoModel Inference
-```python
-res = model.generate(input=[str], output_dir=[str])
-```
-- `input`: The input to be decoded, which could be:
- - A wav file path, e.g., asr_example.wav
- - A pcm file path, e.g., asr_example.pcm, in this case, specify the audio sampling rate fs (default is 16000)
- - An audio byte stream, e.g., byte data from a microphone
- - A wav.scp, a Kaldi-style wav list (wav_id \t wav_path), for example:
- ```text
- asr_example1 ./audios/asr_example1.wav
- asr_example2 ./audios/asr_example2.wav
- ```
- When using wav.scp as input, you must set output_dir to save the output results.
- - Audio samples, `e.g.`: `audio, rate = soundfile.read("asr_example_zh.wav")`, data type is numpy.ndarray. Supports batch inputs, type is list:
- ```[audio_sample1, audio_sample2, ..., audio_sampleN]```
- - fbank input, supports batch grouping. Shape is [batch, frames, dim], type is torch.Tensor.
-- `output_dir`: None (default), if set, specifies the output path for the results.
-- `**kwargs`(dict): Inference parameters related to the model, for example,`beam_size=10`,`decoding_ctc_weight=0.1`.
-
-
-### More Usage Introduction
-
-
-#### Speech Recognition (Non-streaming)
-```python
-from funasr import AutoModel
-# paraformer-zh is a multi-functional asr model
-# use vad, punc, spk or not as you need
-model = AutoModel(model="paraformer-zh",
- vad_model="fsmn-vad",
- vad_kwargs={"max_single_segment_time": 60000},
- punc_model="ct-punc",
- # spk_model="cam++"
- )
-wav_file = f"{model.model_path}/example/asr_example.wav"
-res = model.generate(input=wav_file, batch_size_s=300, batch_size_threshold_s=60, hotword='魔搭')
-print(res)
-```
-
-#### Postprocess hotword correction
-
-Model-level `hotword` / `hotwords` boosts a small set of terms during decoding. For large vocabularies (for example thousands of stock names), apply text-level correction after recognition:
+Run the following Python block after installing the SDK and a matching PyTorch/torchaudio environment. The first run needs network access for the model and this public example WAV, plus sufficient disk and memory. It is based on the repository's [Paraformer example](../../examples/industrial_data_pretraining/paraformer/demo.py); it is not a recorded inference result from this documentation review.
```python
from funasr import AutoModel
-model = AutoModel(model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc")
-
-res = model.generate(
- input="asr_example.wav",
- postprocess_hotwords={
- "科大迅飞": "科大讯飞",
- "东方财富": "东方财富",
- },
- postprocess_hotword_threshold=0.85,
- return_postprocess_hotword_matches=True,
-)
-print(res[0]["text"])
-print(res[0].get("postprocess_hotword_matches"))
-```
-
-You can also pass `postprocess_hotword_file` with one target word per line, or an explicit mapping such as `wrong=>right`. Fuzzy matching requires optional `pypinyin` and `rapidfuzz`; explicit mappings work without them.
-
-Notes:
-- Typically, the input duration for models is limited to under 30 seconds. However, when combined with `vad_model`, support for audio input of any length is enabled, not limited to the paraformer model—any audio input model can be used.
-- Parameters related to model can be directly specified in the definition of AutoModel; parameters related to `vad_model` can be set through `vad_kwargs`, which is a dict; similar parameters include `punc_kwargs` and `spk_kwargs`.
-- `max_single_segment_time`: Denotes the maximum audio segmentation length for `vad_model`, measured in milliseconds (ms).
-- `batch_size_s` represents the use of dynamic batching, where the total audio duration within a batch is measured in seconds (s).
-- `batch_size_threshold_s`: Indicates that when the duration of an audio segment post-VAD segmentation exceeds the batch_size_threshold_s threshold, the batch size is set to 1, measured in seconds (s).
-
-Recommendations:
-
-When you input long audio and encounter Out Of Memory (OOM) issues, since memory usage tends to increase quadratically with audio length, consider the following three scenarios:
-
-a) At the beginning of inference, memory usage primarily depends on `batch_size_s`. Appropriately reducing this value can decrease memory usage.
-
-b) During the middle of inference, when encountering long audio segments cut by VAD and the total token count is less than `batch_size_s`, yet still facing OOM, you can appropriately reduce `batch_size_threshold_s`. If the threshold is exceeded, the batch size is forced to 1.
-
-c) Towards the end of inference, if long audio segments cut by VAD have a total token count less than `batch_size_s` and exceed the `threshold` batch_size_threshold_s, forcing the batch size to 1 and still facing OOM, you may reduce `max_single_segment_time` to shorten the VAD audio segment length.
-
-#### Speech Recognition (Fun-ASR-Nano)
-```python
-from funasr import AutoModel
-
+audio = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav"
model = AutoModel(
- model="FunAudioLLM/Fun-ASR-Nano-2512",
- trust_remote_code=True,
- remote_code="./model.py",
- vad_model="fsmn-vad",
- vad_kwargs={"max_single_segment_time": 30000},
- device="cuda:0",
- hub="hf",
+ model="paraformer-zh", hub="ms", device="cpu", ncpu=4,
+ disable_update=True, trust_remote_code=False,
)
-res = model.generate(input="audio.wav", cache={}, batch_size=1, language="中文")
-print(res[0]["text"])
-print(res[0]["timestamps"]) # character-level timestamps
+results = model.generate(input=audio)
+for item in results:
+ print(item.get("key"), item.get("text", ""))
+print("Model directory:", model.model_path)
```
-Notes:
-- Fun-ASR-Nano is trained on tens of millions of hours of data and supports Chinese, English, and Japanese, plus Chinese dialect groups and regional accents.
-- For the separate 31-language checkpoint, use Fun-ASR-MLT-Nano.
-- Supports hotwords: `hotwords=["keyword1", "keyword2"]`
-- Supports speaker diarization: add `spk_model="cam++"` and `punc_model="ct-punc"` to get `sentence_info` with speaker labels.
-- Requires: `pip install tiktoken huggingface_hub`
-
-#### Speech Recognition (Streaming)
-```python
-from funasr import AutoModel
-chunk_size = [0, 10, 5] #[0, 10, 5] 600ms, [0, 8, 4] 480ms
-encoder_chunk_look_back = 4 #number of chunks to lookback for encoder self-attention
-decoder_chunk_look_back = 1 #number of encoder chunks to lookback for decoder cross-attention
+To transcribe your recording, replace `audio` with an existing local WAV path. Start with a short mono recording matching the selected model's sample rate (16 kHz for this example). File decoding depends on installed audio backends; a readable WAV is a simpler first check than an arbitrary media container. NumPy waveform input has no sample-rate header: supply the actual rate with `fs=sample_rate`, as used by the [audio loader](../../funasr/utils/load_utils.py). Do not merely relabel a waveform's rate.
-model = AutoModel(model="paraformer-zh-streaming")
+The remaining Python blocks reuse `AutoModel`, `audio`, and `model` from this first block in the same session. For disconnected use, prepare complete local model directories and local input files using the [offline checklist](../installation/installation.md). `disable_update=True` only skips the SDK's startup version check.
-import soundfile
-import os
+## 2. Understand parameters and results
-wav_file = os.path.join(model.model_path, "example/asr_example.wav")
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = chunk_size[1] * 960 # 600ms
+`AutoModel(...)` constructs the model and optional pipeline components. `model.generate(input=..., **options)` performs inference. Source references: [AutoModel](../../funasr/auto/auto_model.py), [hub aliases](../../funasr/download/name_maps_from_hub.py), and the chosen model's `inference()` implementation.
-cache = {}
-total_chunk_num = int((len(speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
- speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
- is_final = i == total_chunk_num - 1
- res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size, encoder_chunk_look_back=encoder_chunk_look_back, decoder_chunk_look_back=decoder_chunk_look_back)
- print(res)
-```
-Note: `chunk_size` is the configuration for streaming latency.` [0,10,5]` indicates that the real-time display granularity is `10*60=600ms`, and the lookahead information is `5*60=300ms`. Each inference input is `600ms` (sample points are `16000*0.6=960`), and the output is the corresponding text. For the last speech segment input, `is_final=True` needs to be set to force the output of the last word.
+| Parameter | Scope and meaning |
+| --- | --- |
+| `model`, `hub` | Model ID/alias or local directory; hub defaults to ModelScope (`ms`), with `hf` for Hugging Face. Aliases can resolve to different hub repositories. |
+| `device`, `ncpu` | Explicitly use `cpu` to begin; choose an accelerator only after validating its PyTorch build and model support. The loader has CPU fallback paths; `ncpu` controls PyTorch CPU threads. |
+| `vad_model`, `punc_model`, `spk_model` | Optional, separately loaded models. Configure them through `vad_kwargs`, `punc_kwargs`, and `spk_kwargs`. They are not automatically supported by every ASR backend. |
+| `batch_size` | Number of inputs per decoding batch on the ordinary non-VAD path; backend restrictions still apply. |
+| `batch_size_s` | Duration budget in seconds for VAD-segment batching, based on padded segment length, not a count of files. The current CPU VAD path decodes segments individually. |
+| `batch_size_threshold_s` | Segment-duration threshold used by the VAD batching heuristic; not an input duration limit or a universal memory cap. |
+| `output_dir` | Optional backend output directory. The returned Python result is still available; files and formats depend on the model. |
-#### Voice Activity Detection (Non-Streaming)
-```python
-from funasr import AutoModel
-
-model = AutoModel(model="fsmn-vad")
-wav_file = f"{model.model_path}/example/vad_example.wav"
-res = model.generate(input=wav_file)
-print(res)
-```
-Note: The output format of the VAD model is: `[[beg1, end1], [beg2, end2], ..., [begN, endN]]`, where `begN/endN` indicates the starting/ending point of the `N-th` valid audio segment, measured in milliseconds.
+`generate()` returns a list of dictionaries, normally one per input recording. Inspect keys before depending on optional fields:
-#### Voice Activity Detection (Streaming)
```python
-from funasr import AutoModel
+for item in results:
+ print(sorted(item.keys()))
+ print(item.get("text", ""))
+ print(item.get("timestamp", []))
+```
-chunk_size = 200 # ms
-model = AutoModel(model="fsmn-vad")
+For the Paraformer path, `timestamp` contains character/token/word intervals as `[start_ms, end_ms]` pairs when supplied by the checkpoint. Do not assume one pair per displayed character after punctuation or text normalization. Other backends may return `timestamps` with a different schema; follow that backend's guide. Empty speech may produce empty text/timestamps, not a meaningful transcript.
-import soundfile
+## 3. Add VAD, punctuation, and sentence timestamps
-wav_file = f"{model.model_path}/example/vad_example.wav"
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = int(chunk_size * sample_rate / 1000)
+VAD detects speech spans; it does not transcribe them. This standalone call uses the same audio:
-cache = {}
-total_chunk_num = int((len(speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
- speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
- is_final = i == total_chunk_num - 1
- res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size)
- if len(res[0]["value"]):
- print(res)
-```
-Note: The output format for the streaming VAD model can be one of four scenarios:
-- `[[beg1, end1], [beg2, end2], .., [begN, endN]]`:The same as the offline VAD output result mentioned above.
-- `[[beg, -1]]`:Indicates that only a starting point has been detected.
-- `[[-1, end]]`:Indicates that only an ending point has been detected.
-- `[]`:Indicates that neither a starting point nor an ending point has been detected.
-
-The output is measured in milliseconds and represents the absolute time from the starting point.
-#### Punctuation Restoration
```python
-from funasr import AutoModel
-
-model = AutoModel(model="ct-punc")
-res = model.generate(input="那今天的会就到这里吧 happy new year 明年见")
-print(res)
+vad = AutoModel(model="fsmn-vad", device="cpu", disable_update=True)
+vad_results = vad.generate(input=audio)
+for item in vad_results:
+ print(item["key"], item["value"])
```
-#### Timestamp Prediction
-```python
-from funasr import AutoModel
-model = AutoModel(model="fa-zh")
-wav_file = f"{model.model_path}/example/asr_example.wav"
-text_file = f"{model.model_path}/example/text.txt"
-res = model.generate(input=(wav_file, text_file), data_type=("sound", "text"))
-print(res)
-```
+`value` is a list of `[start_ms, end_ms]` speech intervals relative to the recording start. An empty list means no detected spans. See the [FSMN VAD example](../../examples/industrial_data_pretraining/fsmn_vad_streaming/demo.py).
-More examples ref to [docs](https://github.com/modelscope/FunASR/tree/main/examples/industrial_data_pretraining)
+For segmented ASR with punctuation:
-#### Speaker Verification / Diarization (ERes2NetV2)
```python
-from funasr import AutoModel
-
-# Standalone speaker embedding extraction
-model = AutoModel(model="iic/speech_eres2netv2_sv_zh-cn_16k-common", device="cuda:0")
-res = model.generate(input="audio.wav")
-embedding = res[0]["spk_embedding"] # shape: [1, 192]
-```
-
-```python
-from funasr import AutoModel
-
-# ASR with speaker diarization
-model = AutoModel(
- model="paraformer-zh",
- vad_model="fsmn-vad",
- vad_kwargs={"max_single_segment_time": 60000},
- punc_model="ct-punc",
- spk_model="iic/speech_eres2netv2_sv_zh-cn_16k-common",
- device="cuda:0",
+pipeline = AutoModel(
+ model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc",
+ vad_kwargs={"max_single_segment_time": 30000},
+ device="cpu", disable_update=True, trust_remote_code=False,
)
-res = model.generate(input="meeting.wav", batch_size_s=300)
-for sentence in res:
- print(f"[Speaker {sentence['spk']}] {sentence['text']}")
+segmented_results = pipeline.generate(
+ input=audio, batch_size_s=60, batch_size_threshold_s=30,
+ sentence_timestamp=True,
+)
+for item in segmented_results:
+ print(item.get("text", ""))
+ for sentence in item.get("sentence_info", []):
+ print(sentence.get("start"), sentence.get("end"), sentence.get("text", ""))
```
-Notes: `spk_model` can also be `"cam++"` (CAM++ model). ERes2NetV2 provides improved short-duration speaker feature extraction.
-Custom `spk_model` values can be ModelScope model ids or local model paths. The model must load through FunASR `AutoModel` and return `spk_embedding` from its `inference()` method; users still call `AutoModel.generate()`. Downstream speaker clustering uses those embeddings to assign `spk` labels.
-#### Multi-language ASR (Qwen3-ASR)
-```python
-from funasr import AutoModel
+`max_single_segment_time` is in **milliseconds**; the two batching controls are in **seconds**. Segmentation can help with longer files but does not guarantee unlimited duration or bounded memory: the audio-loading stage and each model still consume resources. On memory pressure, use shorter recordings/segments and smaller supported batches, then measure again. Sentence boundaries depend on available timestamp/punctuation alignment and may fall back to VAD segments; inspect the returned data.
-# Qwen3-ASR supports 52 languages with auto language detection
-# hub="hf" for HuggingFace, default hub="ms" for ModelScope
-model = AutoModel(model="Qwen/Qwen3-ASR-1.7B", hub="hf", device="cuda:0")
+For diarization, construct the same pipeline with `spk_model="cam++"` if supported by the chosen components. Iterate each input's `item.get("sentence_info", [])`, then read `sentence.get("spk")`. Do not read `spk` directly from the outer result list. Cluster labels are not verified real-world identities. [Speaker integration example](../../examples/industrial_data_pretraining/sense_voice/demo_spk.py).
-# With forced language
-res = model.generate(input="audio_zh.wav", language="Chinese")
-print(res[0]["text"])
+## 4. Process multiple recordings
-# Auto language detection
-res = model.generate(input="audio.wav")
-print(res[0]["text"], res[0].get("language", ""))
-```
-Notes: Use `pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate`. `qwen-asr==0.0.6` pins `transformers==4.57.6`; newer incompatible Transformers builds may fail with nested `thinker_config` errors. Supports 0.6B and 1.7B model sizes.
+The following deliberately repeats the sample to demonstrate a list input without requiring extra files. Replace the entries with your local WAV paths:
-#### Multi-language ASR (GLM-ASR)
```python
-from funasr import AutoModel
-
-# GLM-ASR-Nano supports 17 languages, optimized for dialects and low-volume speech
-# hub="hf" for HuggingFace, default hub="ms" for ModelScope
-model = AutoModel(model="zai-org/GLM-ASR-Nano-2512", hub="hf", device="cuda:0")
-res = model.generate(input="audio.wav")
-print(res[0]["text"])
-
-# ModelScope (Chinese users)
-model = AutoModel(model="ZhipuAI/GLM-ASR-Nano-2512", hub="ms", device="cuda:0")
-```
-Notes: Requires `transformers>=5.0.0` (install from source: `pip install git+https://github.com/huggingface/transformers`).
-
-
-
-
-
-<a name="Training"></a>
-## Model Training and Testing
-
-### Quick Start
-
-Execute via command line (for quick testing, not recommended):
-```shell
-funasr-train ++model=paraformer-zh ++train_data_set_list=data/list/train.jsonl ++valid_data_set_list=data/list/val.jsonl ++output_dir="./outputs" &> log.txt &
-```
-
-Execute with Python code (supports multi-node and multi-GPU, recommended):
-
-```shell
-cd examples/industrial_data_pretraining/paraformer
-bash finetune.sh
-# "log_file: ./outputs/log.txt"
-```
-Full code ref to [finetune.sh](https://github.com/modelscope/FunASR/blob/main/examples/industrial_data_pretraining/paraformer/finetune.sh)
-
-### Detailed Parameter Description:
-
-```shell
-funasr/bin/train_ds.py \
-++model="${model_name_or_model_dir}" \
-++train_data_set_list="${train_data}" \
-++valid_data_set_list="${val_data}" \
-++dataset_conf.batch_size=20000 \
-++dataset_conf.batch_type="token" \
-++dataset_conf.num_workers=4 \
-++train_conf.max_epoch=50 \
-++train_conf.log_interval=1 \
-++train_conf.resume=false \
-++train_conf.validate_interval=2000 \
-++train_conf.save_checkpoint_interval=2000 \
-++train_conf.keep_nbest_models=20 \
-++train_conf.avg_nbest_model=10 \
-++optim_conf.lr=0.0002 \
-++output_dir="${output_dir}" &> ${log_file}
-```
-
-- `model`(str): The name of the model (the ID in the model repository), at which point the script will automatically download the model to local storage; alternatively, the path to a model already downloaded locally.
-- `train_data_set_list`(str): The path to the training data, typically in jsonl format, for specific details refer to [examples](https://github.com/modelscope/FunASR/blob/main/data/list).
-- `valid_data_set_list`(str):The path to the validation data, also generally in jsonl format, for specific details refer to examples](https://github.com/modelscope/FunASR/blob/main/data/list).
-- `dataset_conf.batch_type`(str):example (default), the type of batch. example means batches are formed with a fixed number of batch_size samples; length or token means dynamic batching, with total length or number of tokens of the batch equalling batch_size.
-- `dataset_conf.batch_size`(int):Used in conjunction with batch_type. When batch_type=example, it represents the number of samples; when batch_type=length, it represents the length of the samples, measured in fbank frames (1 frame = 10 ms) or the number of text tokens.
-- `train_conf.max_epoch`(int):The total number of epochs for training.
-- `train_conf.log_interval`(int):The number of steps between logging.
-- `train_conf.resume`(int):Whether to enable checkpoint resuming for training.
-- `train_conf.validate_interval`(int):The interval in steps to run validation tests during training.
-- `train_conf.save_checkpoint_interval`(int):The interval in steps for saving the model during training.
-- `train_conf.keep_nbest_models`(int):The maximum number of model parameters to retain, sorted by validation set accuracy, from highest to lowest.
-- `train_conf.avg_nbest_model`(int):Average over the top n models with the highest accuracy.
-- `optim_conf.lr`(float):The learning rate.
-- `output_dir`(str):The path for saving the model.
-- `**kwargs`(dict): Any parameters in config.yaml can be specified directly here, for example, to filter out audio longer than 20s: dataset_conf.max_token_length=2000, measured in fbank frames (1 frame = 10 ms) or the number of text tokens.
-
-#### Multi-GPU Training
-##### Single-Machine Multi-GPU Training
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 1 --nproc_per_node ${gpu_num} \
-../../../funasr/bin/train_ds.py ${train_args}
-```
---nnodes represents the total number of participating nodes, while --nproc_per_node indicates the number of processes running on each node.
-
-##### Multi-Machine Multi-GPU Training
-
-On the master node, assuming the IP is 192.168.1.1 and the port is 12345, and you're using 2 GPUs, you would run the following command:
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 2 --node_rank 0 --nproc_per_node ${gpu_num} --master_addr=192.168.1.1 --master_port=12345 \
-../../../funasr/bin/train_ds.py ${train_args}
-```
-On the worker node (assuming the IP is 192.168.1.2), you need to ensure that the MASTER_ADDR and MASTER_PORT environment variables are set to match those of the master node, and then run the same command:
-
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 2 --node_rank 1 --nproc_per_node ${gpu_num} --master_addr=192.168.1.1 --master_port=12345 \
-../../../funasr/bin/train_ds.py ${train_args}
-```
-
---nnodes indicates the total number of nodes participating in the training, --node_rank represents the ID of the current node, and --nproc_per_node specifies the number of processes running on each node (usually corresponds to the number of GPUs).
-
-#### Data prepare
-
-`jsonl` ref to([demo](https://github.com/modelscope/FunASR/blob/main/data/list)).
-The instruction scp2jsonl can be used to generate from wav.scp and text.txt. The preparation process for wav.scp and text.txt is as follows:
-
-`train_text.txt`
-
-```bash
-ID0012W0013 当客户风险承受能力评估依据发生变化时
-ID0012W0014 所有只要处理 data 不管你是做 machine learning 做 deep learning
-ID0012W0015 he tried to think how it could be
-```
-
-
-`train_wav.scp`
-
-
-```bash
-BAC009S0764W0121 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav
-BAC009S0916W0489 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0916W0489.wav
-ID0012W0015 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_cn_en.wav
-```
-
-`Command`
-
-```shell
-# generate train.jsonl and val.jsonl from wav.scp and text.txt
-scp2jsonl \
-++scp_file_list='["../../../data/list/train_wav.scp", "../../../data/list/train_text.txt"]' \
-++data_type_list='["source", "target"]' \
-++jsonl_file_out="../../../data/list/train.jsonl"
-```
-
-(Optional, not required) If you need to parse from jsonl back to wav.scp and text.txt, you can use the following command:
-
-```shell
-# generate wav.scp and text.txt from train.jsonl and val.jsonl
-jsonl2scp \
-++scp_file_list='["../../../data/list/train_wav.scp", "../../../data/list/train_text.txt"]' \
-++data_type_list='["source", "target"]' \
-++jsonl_file_in="../../../data/list/train.jsonl"
-```
-
-
-#### Large-Scale Data Training
-When dealing with large datasets (e.g., 50,000 hours or more), memory issues may arise, especially in multi-GPU experiments. To address this, split the JSONL files into slices, write them into a TXT file (one slice per line), and set `data_split_num`. For example:
-```shell
-train_data="/root/data/list/data.list"
-
-funasr/bin/train_ds.py \
-++train_data_set_list="${train_data}" \
-++dataset_conf.data_split_num=256
-```
-**Details:**
-- `data.list`: A plain text file listing the split JSONL files. For example, the content of `data.list` might be:
- ```bash
- data/list/train.0.jsonl
- data/list/train.1.jsonl
- ...
- ```
-- `data_split_num`: Specifies the number of slice groups. For instance, if `data.list` contains 512 lines and `data_split_num=256`, the data will be divided into 256 groups, each containing 2 JSONL files. This ensures that only 2 JSONL files are loaded for training at a time, reducing memory usage during training. Note: Groups are created sequentially.
-
-**Recommendation:**
-If the dataset is extremely large and contains heterogeneous data types, perform **data balancing** during splitting to ensure uniformity across groups.
-
-#### Training log
-
-##### log.txt
-```shell
-tail log.txt
-[2024-03-21 15:55:52,137][root][INFO] - train, rank: 3, epoch: 0/50, step: 6990/1, total step: 6990, (loss_avg_rank: 0.327), (loss_avg_epoch: 0.409), (ppl_avg_epoch: 1.506), (acc_avg_epoch: 0.795), (lr: 1.165e-04), [('loss_att', 0.259), ('acc', 0.825), ('loss_pre', 0.04), ('loss', 0.299), ('batch_size', 40)], {'data_load': '0.000', 'forward_time': '0.315', 'backward_time': '0.555', 'optim_time': '0.076', 'total_time': '0.947'}, GPU, memory: usage: 3.830 GB, peak: 18.357 GB, cache: 20.910 GB, cache_peak: 20.910 GB
-[2024-03-21 15:55:52,139][root][INFO] - train, rank: 1, epoch: 0/50, step: 6990/1, total step: 6990, (loss_avg_rank: 0.334), (loss_avg_epoch: 0.409), (ppl_avg_epoch: 1.506), (acc_avg_epoch: 0.795), (lr: 1.165e-04), [('loss_att', 0.285), ('acc', 0.823), ('loss_pre', 0.046), ('loss', 0.331), ('batch_size', 36)], {'data_load': '0.000', 'forward_time': '0.334', 'backward_time': '0.536', 'optim_time': '0.077', 'total_time': '0.948'}, GPU, memory: usage: 3.943 GB, peak: 18.291 GB, cache: 19.619 GB, cache_peak: 19.619 GB
-```
-
-
-- `rank`:gpu id。
-- `epoch`,`step`,`total step`:the current epoch, step, and total steps.
-- `loss_avg_rank`:the average loss across all GPUs for the current step.
-- `loss/ppl/acc_avg_epoch`:the overall average loss/perplexity/accuracy for the current epoch, up to the current step count. The last step of the epoch when it ends represents the total average loss/perplexity/accuracy for that epoch; it is recommended to use the accuracy metric.
-- `lr`:the learning rate for the current step.
-- `[('loss_att', 0.259), ('acc', 0.825), ('loss_pre', 0.04), ('loss', 0.299), ('batch_size', 40)]`:the specific data for the current GPU ID.
-- `total_time`:the total time taken for a single step.
-- `GPU, memory`:the model-used/peak memory and the model+cache-used/peak memory.
-
-##### tensorboard
-```bash
-tensorboard --logdir /xxxx/FunASR/examples/industrial_data_pretraining/paraformer/outputs/log/tensorboard
+batch_results = model.generate(input=[audio, audio], batch_size=1)
+for index, item in enumerate(batch_results):
+ print(index, item.get("key"), item.get("text", ""))
```
-http://localhost:6006/
-
-### 训练后模型测试
-
-#### With `configuration.json` file
+Increase `batch_size` only if the selected model supports it and memory permits. A file list such as `wav.scp` is also supported: use one `utterance_id path` per line, resolve paths from the process working directory, and give each recording a unique ID. Set `output_dir` if you need model-written artifacts; it is not required simply to receive the returned list. See [data-list examples](../../data/list/train_wav.scp). Do not confuse independent file batching with streaming chunks of one utterance.
-Assuming the training model path is: ./model_dir, if a configuration.json file has been generated in this directory, you only need to change the model name to the model path in the above model inference method.
-
-For example, for shell inference:
-```shell
-python -m funasr.bin.inference ++model="./model_dir" ++input=="${input}" ++output_dir="${output_dir}"
-```
+## 5. Hotwords and language boundaries
-Python inference
+The ModelScope `paraformer-zh` alias in this checkout resolves to a SeACo Paraformer model, whose implementation accepts singular `hotword` as a space-separated string:
```python
-from funasr import AutoModel
-
-model = AutoModel(model="./model_dir")
-
-res = model.generate(input=wav_file)
-print(res)
+biased_results = model.generate(input=audio, hotword="魔搭 达摩院")
+print([item.get("text", "") for item in biased_results])
```
-#### Without `configuration.json` file
+This is model-level context biasing, not guaranteed word insertion or deterministic replacement. Verify the resolved model and compare against a no-hotword baseline. [SeACo implementation](../../funasr/models/seaco_paraformer/model.py) and [contextual Paraformer example](../../examples/industrial_data_pretraining/contextual_paraformer/demo.py).
-If there is no configuration.json in the model path, you need to manually specify the exact configuration file path and the model path.
-
-```shell
-python -m funasr.bin.inference \
---config-path "${local_path}" \
---config-name "${config}" \
-++init_param="${init_param}" \
-++tokenizer_conf.token_list="${tokens}" \
-++frontend_conf.cmvn_file="${cmvn_file}" \
-++input="${input}" \
-++output_dir="${output_dir}" \
-++device="${device}"
-```
+Postprocessing is a different operation in this source checkout:
-Parameter Introduction
-- `config-path`:This is the path to the config.yaml saved during the experiment, which can be found in the experiment's output directory.
-- `config-name`:The name of the configuration file, usually config.yaml. It supports both YAML and JSON formats, for example config.json.
-- `init_param`:The model parameters that need to be tested, usually model.pt. You can choose a specific model file as needed.
-- `tokenizer_conf.token_list`:The path to the vocabulary file, which is normally specified in config.yaml. There is no need to manually specify it again unless the path in config.yaml is incorrect, in which case the correct path must be manually specified here.
-- `frontend_conf.cmvn_file`:The CMVN (Cepstral Mean and Variance Normalization) file used when extracting fbank features from WAV files, which is usually specified in config.yaml. There is no need to manually specify it again unless the path in config.yaml is incorrect, in which case the correct path must be manually specified here.
-
-Other parameters are the same as mentioned above. A complete [example](https://github.com/modelscope/FunASR/blob/main/examples/industrial_data_pretraining/paraformer/infer_from_local.sh) can be found here.
-
-<a name="Export"></a>
-## Export ONNX
-
-### Command-line usage
-```shell
-funasr-export ++model=paraformer ++quantize=false ++device=cpu
-```
-
-### Python
```python
-from funasr import AutoModel
-
-model = AutoModel(model="paraformer", device="cpu")
-
-res = model.export(quantize=False)
-```
-
-### optimize onnx
-```shell
-# pip3 install -U onnxslim
-onnxslim model.onnx model.onnx
-```
-
-### Test ONNX
-```python
-# pip3 install -U funasr-onnx
-from funasr_onnx import Paraformer
-model_dir = "damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch"
-model = Paraformer(model_dir, batch_size=1, quantize=True)
-
-wav_path = ['~/.cache/modelscope/hub/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/example/asr_example.wav']
-
-result = model(wav_path)
-print(result)
+corrected_results = model.generate(
+ input=audio,
+ postprocess_hotwords={"科大迅飞": "科大讯飞"},
+ return_postprocess_hotword_matches=True,
+)
+for item in corrected_results:
+ print(item.get("text", ""), item.get("postprocess_hotword_matches", []))
```
-More examples ref to [demo](https://github.com/modelscope/FunASR/tree/main/runtime/python/onnxruntime)
-
+Explicit mappings replace matching output text. `postprocess_hotword_file` also accepts one target per line or `wrong=>right` mappings. Fuzzy matching additionally needs `pypinyin` and `rapidfuzz`; explicit mappings do not. The [postprocessor](../../funasr/utils/postprocess_hotwords.py) preserves existing timestamps rather than realigning corrected text, so review replacements before making subtitles or alignment claims.
-<a name="new-model-registration-tutorial"></a>
-## New Model Registration Tutorial
+`hotword`, `hotwords`, and `language` are **not interchangeable universal SDK options**. For example, [Fun-ASR-Nano](../../examples/industrial_data_pretraining/fun_asr_nano/README.md) reads plural `hotwords` and a model-specific language hint. Changing a hint does not turn a monolingual checkpoint into a multilingual one. Use the [Model Zoo](../../model_zoo/readme.md) and the exact checkpoint guide for supported languages, accepted hint values, streaming, alignment, and dependency versions. Avoid copying language counts or installation pins between model families.
-### Viewing the Registry
+## 6. Continue with a specific workflow
-```plaintext
-from funasr.register import tables
+- **Streaming:** [Paraformer streaming example](../../examples/industrial_data_pretraining/paraformer_streaming/demo.py). Keep a separate `cache={}` per stream and set `is_final=True` for the final chunk. For `[0, 10, 5]` at 16 kHz, 600 ms is **9600 samples**, not 960; chunk duration is not an end-to-end latency guarantee. Streaming VAD may return `[start, -1]`, `[-1, end]`, complete spans, or no spans, in milliseconds.
+- **Punctuation and alignment:** [punctuation example](../../examples/industrial_data_pretraining/ct_transformer/demo.py) and [timestamp prediction example](../../examples/industrial_data_pretraining/monotonic_aligner/demo.py). Alignment needs the corresponding text input; it is not equivalent to ASR.
+- **Other model families:** [SenseVoice](../../examples/industrial_data_pretraining/sense_voice/README.md), [Fun-ASR-Nano](../../examples/industrial_data_pretraining/fun_asr_nano/README.md), and [third-party OpenMOSS integration](../moss_transcribe_diarize.md). Discover further entries through the Model Zoo.
+- **CLI and services:** [CLI reference](../cli.md), [runtime overview](../../runtime/readme.md), and [Docker](../installation/docker.md). Python options do not imply an identical server request schema.
-tables.print()
-```
-
-Supports viewing the registry of a specified type: `tables.print("model")`
-
-### Registering Models
-
-```python
-from funasr.register import tables
-
[email protected]("model_classes", "SenseVoiceSmall")
-class SenseVoiceSmall(nn.Module):
- def __init__(*args, **kwargs):
- ...
-
- def forward(
- self,
- **kwargs,
- ):
-
- def inference(
- self,
- data_in,
- data_lengths=None,
- key: list = None,
- tokenizer=None,
- frontend=None,
- **kwargs,
- ):
- ...
+<a id="Training" name="Training"></a>
+## Model Training and Testing
-```
+Use the [Paraformer recipe](../../examples/industrial_data_pretraining/paraformer/README.md), [finetune.sh](../../examples/industrial_data_pretraining/paraformer/finetune.sh), and [training-data examples](../../data/list/train.jsonl). Inspect dataset paths, label alignment, model license, GPU allocation, and output directories before launching. Training is not an installation smoke test. For trained weights, inspect [infer_from_local.sh](../../examples/industrial_data_pretraining/paraformer/infer_from_local.sh): configuration, tokenizer/frontend assets, and checkpoint paths must agree. Keep [validation data](../../data/list/val.jsonl) separate from training data.
-Add `@tables.register("model_classes","SenseVoiceSmall")` before the class name that needs to be registered to complete the registration. The class needs to implement the methods: __init__, forward, and inference.
+<a id="Export" name="Export"></a>
+## Model Export and Testing
-Complete code: [https://github.com/modelscope/FunASR/blob/main/funasr/models/sense_voice/model.py#L443](https://github.com/modelscope/FunASR/blob/main/funasr/models/sense_voice/model.py#L443)
+Follow the model's [Paraformer export example](../../examples/industrial_data_pretraining/paraformer/export.py) and [ONNX Runtime guide](../../runtime/python/onnxruntime/README.md). Export support and extra dependencies are model/backend-specific. Successful export is not evidence of output equivalence: test the exported artifact on representative inputs and compare with the original model before deployment.
-After registration, specify the newly registered model in config.yaml to define the model
+<a id="new-model-registration-tutorial" name="new-model-registration-tutorial"></a>
+## Register a Custom Model
-```python
-model: SenseVoiceSmall
-model_conf:
- ...
-```
+Use the [registry tutorial](./Tables.md) and a real implementation such as [SenseVoice](../../funasr/models/sense_voice/model.py). Registration alone does not establish a working `generate()` contract; the model's inference result must match the downstream components it will use.
-[More detailed tutorial documents](https://github.com/modelscope/FunASR/blob/main/docs/tutorial/Tables.md)
+For failures, return to [troubleshooting](../troubleshooting.md) with interpreter/package versions, resolved model ID/revision, input format, and a minimal reproduction. Do not include private audio or credentials.
diff --git a/docs/tutorial/README_zh.md b/docs/tutorial/README_zh.md
index bf2036d98..5e1ea05b3 100644
--- a/docs/tutorial/README_zh.md
+++ b/docs/tutorial/README_zh.md
@@ -1,610 +1,153 @@
-(简体中文|[English](./README.md))
+(简体中文 | [English](./README.md))
-FunASR开源了大量在工业数据上预训练的模型。每个模型权重都有各自的许可:请记录完整模型 ID 与 revision,并以模型卡中展示的许可材料为准。只有模型卡明确链接 [FunASR 模型许可协议](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE) 时,该协议才适用。下面列举代表性的模型,更多模型请参考 [模型仓库](https://github.com/modelscope/FunASR/tree/main/model_zoo)。
+# Python SDK 教程
-<div align="center">
-<h4>
- <a href="#模型推理"> 模型推理 </a>
-|<a href="#模型训练与测试"> 模型训练与测试 </a>
-|<a href="#模型导出与测试"> 模型导出与测试 </a>
-|<a href="#新模型注册教程"> 新模型注册教程 </a>
-</h4>
-</div>
+先完成[安装与环境验证](../installation/installation_zh.md)。本页按首次转写、结果检查、VAD、批处理、模型专属选项的顺序介绍。模型选择、语言、依赖和模型卡请查阅[模型仓库](../../model_zoo/readme_zh.md),不要将某个示例当成所有模型的通用能力。尚未配置本地环境时,可先看 [Colab 快速体验](../../examples/colab/README_zh.md)。
-<a name="模型推理"></a>
-## 模型推理
+FunASR 软件采用 [MIT 许可](../../LICENSE)。每个模型权重都有各自的许可:请记录完整模型 ID 与 revision,并以对应模型卡为准。只有模型卡明确链接 [FunASR 模型许可协议](../../MODEL_LICENSE) 时,该协议才适用。第三方集成仍属于第三方模型,例如 MOSS-Transcribe-Diarize 来自 OpenMOSS,不是 FunASR 训练的权重。
-### 快速使用
+<a id="模型推理" name="模型推理"></a>
+## 1. 完成第一次转写
-不想先配置本地环境?可以先跑 [Colab 快速体验](../../examples/colab/README_zh.md),确认模型和输出格式后再切到命令行。
+安装 SDK 及匹配的 PyTorch/torchaudio 环境后,运行下面的 Python 代码。首次执行需要联网下载模型和公开示例 WAV,并预留磁盘与内存。示例基于仓库中的 [Paraformer 示例](../../examples/industrial_data_pretraining/paraformer/demo.py),不是本次文档审查中记录的推理结果。
-命令行方式调用:
-```shell
-funasr ++model=paraformer-zh ++vad_model="fsmn-vad" ++punc_model="ct-punc" ++input=asr_example_zh.wav
-```
-
-python代码调用(推荐)
-
-```python
-from funasr import AutoModel
-
-model = AutoModel(model="paraformer-zh")
-
-res = model.generate(input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav")
-print(res)
-```
-
-### 接口说明
-
-#### AutoModel 定义
-```python
-model = AutoModel(model=[str], device=[str], ncpu=[int], output_dir=[str], batch_size=[int], hub=[str], **kwargs)
-```
-- `model`(str): [模型仓库](https://github.com/modelscope/FunASR/tree/main/model_zoo) 中的模型名称,或本地磁盘中的模型路径
-- `device`(str): `cuda:0`(默认gpu0),使用 GPU 进行推理,指定。如果为`cpu`,则使用 CPU 进行推理。`mps`:mac电脑M系列新品试用mps进行推理。`xpu`:使用英特尔gpu进行推理。
-- `ncpu`(int): `4` (默认),设置用于 CPU 内部操作并行性的线程数
-- `output_dir`(str): `None` (默认),如果设置,输出结果的输出路径
-- `batch_size`(int): `1` (默认),解码时的批处理,样本个数
-- `hub`(str):`ms`(默认),从modelscope下载模型。如果为`hf`,从huggingface下载模型。
-- `**kwargs`(dict): 所有在`config.yaml`中参数,均可以直接在此处指定,例如,vad模型中最大切割长度 `max_single_segment_time=6000` (毫秒)。
-
-#### AutoModel 推理
-```python
-res = model.generate(input=[str], output_dir=[str])
-```
-- `input`: 要解码的输入,可以是:
- - wav文件路径, 例如: asr_example.wav
- - pcm文件路径, 例如: asr_example.pcm,此时需要指定音频采样率fs(默认为16000)
- - 音频字节数流,例如:麦克风的字节数数据
- - wav.scp,kaldi 样式的 wav 列表 (`wav_id \t wav_path`), 例如:
- ```text
- asr_example1 ./audios/asr_example1.wav
- asr_example2 ./audios/asr_example2.wav
- ```
- 在这种输入 `wav.scp` 的情况下,必须设置 `output_dir` 以保存输出结果
- - 音频采样点,例如:`audio, rate = soundfile.read("asr_example_zh.wav")`, 数据类型为 numpy.ndarray。支持batch输入,类型为list:
- ```[audio_sample1, audio_sample2, ..., audio_sampleN]```
- - fbank输入,支持组batch。shape为[batch, frames, dim],类型为torch.Tensor,例如
-- `output_dir`: None (默认),如果设置,输出结果的输出路径
-- `**kwargs`(dict): 与模型相关的推理参数,例如,`beam_size=10`,`decoding_ctc_weight=0.1`。
-
-
-### 更多用法介绍
-
-
-#### 非实时语音识别
```python
from funasr import AutoModel
-# paraformer-zh is a multi-functional asr model
-# use vad, punc, spk or not as you need
-model = AutoModel(model="paraformer-zh",
- vad_model="fsmn-vad",
- vad_kwargs={"max_single_segment_time": 60000},
- punc_model="ct-punc",
- # spk_model="cam++"
- )
-wav_file = f"{model.model_path}/example/asr_example.wav"
-res = model.generate(input=wav_file, batch_size_s=300, batch_size_threshold_s=60, hotword='魔搭')
-print(res)
-```
-
-#### ASR 后处理热词替换
-模型层 `hotword` / `hotwords` 用于在解码阶段提升少量高优先级词的识别率;如果词表很大(例如几千个股票名),更适合在识别完成后做文本级纠错:
-
-```python
-from funasr import AutoModel
-
-model = AutoModel(model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc")
-
-res = model.generate(
- input="asr_example.wav",
- postprocess_hotwords={
- "科大迅飞": "科大讯飞",
- "东方财富": "东方财富",
- },
- postprocess_hotword_threshold=0.85,
- return_postprocess_hotword_matches=True,
+audio = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav"
+model = AutoModel(
+ model="paraformer-zh", hub="ms", device="cpu", ncpu=4,
+ disable_update=True, trust_remote_code=False,
)
-print(res[0]["text"])
-print(res[0].get("postprocess_hotword_matches"))
+results = model.generate(input=audio)
+for item in results:
+ print(item.get("key"), item.get("text", ""))
+print("Model directory:", model.model_path)
```
-也支持热词文件 `postprocess_hotword_file`,每行一个目标词,或一行一个显式映射(`错误词=>目标词`)。模糊匹配需要额外安装 `pypinyin` 和 `rapidfuzz`;未安装时仍可使用显式映射。
+识别自己的录音时,将 `audio` 替换为存在的本地 WAV 路径。建议先使用与模型采样率匹配的短单声道录音,本示例为 16 kHz。文件解码能力取决于音频后端,先检查可读 WAV 比直接尝试任意媒体容器更简单。NumPy 波形没有采样率文件头,需要通过 `fs=sample_rate` 传入真实采样率,参见[音频加载器](../../funasr/utils/load_utils.py);不要仅修改采样率标签而不重采样。
-注意:
-- 通常模型输入限制时长30s以下,组合`vad_model`后,支持任意时长音频输入,不局限于paraformer模型,所有音频输入模型均可以。
-- `model`相关的参数可以直接在`AutoModel`定义中直接指定;与`vad_model`相关参数可以通过`vad_kwargs`来指定,类型为dict;类似的有`punc_kwargs`,`spk_kwargs`;
-- `max_single_segment_time`: 表示`vad_model`最大切割音频时长, 单位是毫秒ms.
-- `batch_size_s` 表示采用动态batch,batch中总音频时长,单位为秒s。
-- `batch_size_threshold_s`: 表示`vad_model`切割后音频片段时长超过 `batch_size_threshold_s`阈值时,将batch_size数设置为1, 单位为秒s.
+后续 Python 代码块在同一会话中复用这里的 `AutoModel`、`audio` 和 `model`。断网使用时,请先按[离线检查清单](../installation/installation_zh.md)准备完整本地模型目录和本地输入文件。`disable_update=True` 仅跳过 SDK 启动版本检查。
-建议:当您输入为长音频,遇到OOM问题时,因为显存占用与音频时长呈平方关系增加,分为3种情况:
-- a)推理起始阶段,显存主要取决于`batch_size_s`,适当减小该值,可以减少显存占用;
-- b)推理中间阶段,遇到VAD切割的长音频片段,总token数小于`batch_size_s`,仍然出现OOM,可以适当减小`batch_size_threshold_s`,超过阈值,强制batch为1;
-- c)推理快结束阶段,遇到VAD切割的长音频片段,总token数小于`batch_size_s`,且超过阈值`batch_size_threshold_s`,强制batch为1,仍然出现OOM,可以适当减小`max_single_segment_time`,使得VAD切割音频时长变短。
-
-#### 实时语音识别
-
-```python
-from funasr import AutoModel
+## 2. 理解参数和结果
-chunk_size = [0, 10, 5] #[0, 10, 5] 600ms, [0, 8, 4] 480ms
-encoder_chunk_look_back = 4 #number of chunks to lookback for encoder self-attention
-decoder_chunk_look_back = 1 #number of encoder chunks to lookback for decoder cross-attention
+`AutoModel(...)` 构建模型与可选流水线组件,`model.generate(input=..., **options)` 执行推理。源码入口:[AutoModel](../../funasr/auto/auto_model.py)、[hub 别名映射](../../funasr/download/name_maps_from_hub.py),以及具体模型的 `inference()` 实现。
-model = AutoModel(model="paraformer-zh-streaming")
+| 参数 | 作用范围与含义 |
+| --- | --- |
+| `model`、`hub` | 模型 ID/别名或本地目录;默认 ModelScope (`ms`),`hf` 选择 Hugging Face。同一别名可能对应不同 hub 仓库。 |
+| `device`、`ncpu` | 入门显式使用 `cpu`;验证 PyTorch 构建与模型支持后再选择加速器。加载器存在 CPU 回退路径;`ncpu` 控制 PyTorch CPU 线程数。 |
+| `vad_model`、`punc_model`、`spk_model` | 独立加载的可选模型;通过 `vad_kwargs`、`punc_kwargs`、`spk_kwargs` 配置。并非所有 ASR 后端都自动支持这些组合。 |
+| `batch_size` | 普通非 VAD 路径每个解码 batch 的输入数量,仍受后端限制。 |
+| `batch_size_s` | VAD 分段组 batch 的秒数预算,按填充后的片段长度计算,不是文件数。当前 CPU VAD 路径逐段解码。 |
+| `batch_size_threshold_s` | VAD 组 batch 启发式使用的片段时长阈值,不是输入时长限制或通用内存上限。 |
+| `output_dir` | 可选的后端输出目录;仍会返回 Python 结果。具体文件和格式取决于模型。 |
-import soundfile
-import os
+`generate()` 返回字典列表,通常每条输入录音对应一个结果。使用可选字段前先检查实际键名:
-wav_file = os.path.join(model.model_path, "example/asr_example.wav")
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = chunk_size[1] * 960 # 600ms
-
-cache = {}
-total_chunk_num = int((len(speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
- speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
- is_final = i == total_chunk_num - 1
- res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size, encoder_chunk_look_back=encoder_chunk_look_back, decoder_chunk_look_back=decoder_chunk_look_back)
- print(res)
-```
-
-注:`chunk_size`为流式延时配置,`[0,10,5]`表示上屏实时出字粒度为`10*60=600ms`,未来信息为`5*60=300ms`。每次推理输入为`600ms`(采样点数为`16000*0.6=960`),输出为对应文字,最后一个语音片段输入需要设置`is_final=True`来强制输出最后一个字。
-
-#### 语音端点检测(非实时)
```python
-from funasr import AutoModel
-
-model = AutoModel(model="fsmn-vad")
-
-wav_file = f"{model.model_path}/example/vad_example.wav"
-res = model.generate(input=wav_file)
-print(res)
+for item in results:
+ print(sorted(item.keys()))
+ print(item.get("text", ""))
+ print(item.get("timestamp", []))
```
-注:VAD模型输出格式为:`[[beg1, end1], [beg2, end2], .., [begN, endN]]`,其中`begN/endN`表示第`N`个有效音频片段的起始点/结束点,
-单位为毫秒。
-
-#### 语音端点检测(实时)
-```python
-from funasr import AutoModel
-
-chunk_size = 200 # ms
-model = AutoModel(model="fsmn-vad")
-import soundfile
+Paraformer 路径在权重提供时间戳时,`timestamp` 为字/词元/词级的 `[start_ms, end_ms]` 区间。标点恢复或文本规范化后,不要假定每个可见字符都对应一组区间。其他后端可能返回不同结构的 `timestamps`,请按对应指南解析。无语音时可能返回空文本或空时间戳,不能当成有效转写。
-wav_file = f"{model.model_path}/example/vad_example.wav"
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = int(chunk_size * sample_rate / 1000)
+## 3. 添加 VAD、标点与句级时间戳
-cache = {}
-total_chunk_num = int((len(speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
- speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
- is_final = i == total_chunk_num - 1
- res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size)
- if len(res[0]["value"]):
- print(res)
-```
-注:流式VAD模型输出格式为4种情况:
-- `[[beg1, end1], [beg2, end2], .., [begN, endN]]`:同上离线VAD输出结果。
-- `[[beg, -1]]`:表示只检测到起始点。
-- `[[-1, end]]`:表示只检测到结束点。
-- `[]`:表示既没有检测到起始点,也没有检测到结束点
-输出结果单位为毫秒,从起始点开始的绝对时间。
-
-#### 标点恢复
-```python
-from funasr import AutoModel
-
-model = AutoModel(model="ct-punc")
-
-res = model.generate(input="那今天的会就到这里吧 happy new year 明年见")
-print(res)
-```
+VAD 检测语音区间,本身不做转写。下面独立检测同一音频:
-#### 时间戳预测
```python
-from funasr import AutoModel
-
-model = AutoModel(model="fa-zh")
-
-wav_file = f"{model.model_path}/example/asr_example.wav"
-text_file = f"{model.model_path}/example/text.txt"
-res = model.generate(input=(wav_file, text_file), data_type=("sound", "text"))
-print(res)
+vad = AutoModel(model="fsmn-vad", device="cpu", disable_update=True)
+vad_results = vad.generate(input=audio)
+for item in vad_results:
+ print(item["key"], item["value"])
```
-更多([示例](https://github.com/modelscope/FunASR/tree/main/examples/industrial_data_pretraining))
-#### 说话人确认/分割 (ERes2NetV2)
-```python
-from funasr import AutoModel
+`value` 为相对于录音起点的 `[start_ms, end_ms]` 语音区间列表。空列表表示没有检测到区间。参见 [FSMN VAD 示例](../../examples/industrial_data_pretraining/fsmn_vad_streaming/demo.py)。
-# 单独提取说话人 embedding
-model = AutoModel(model="iic/speech_eres2netv2_sv_zh-cn_16k-common", device="cuda:0")
-res = model.generate(input="audio.wav")
-embedding = res[0]["spk_embedding"] # shape: [1, 192]
-```
+组合分段 ASR 与标点:
```python
-from funasr import AutoModel
-
-# ASR + 说话人分割
-model = AutoModel(
- model="paraformer-zh",
- vad_model="fsmn-vad",
- vad_kwargs={"max_single_segment_time": 60000},
- punc_model="ct-punc",
- spk_model="iic/speech_eres2netv2_sv_zh-cn_16k-common",
- device="cuda:0",
+pipeline = AutoModel(
+ model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc",
+ vad_kwargs={"max_single_segment_time": 30000},
+ device="cpu", disable_update=True, trust_remote_code=False,
)
-res = model.generate(input="meeting.wav", batch_size_s=300)
-for sentence in res:
- print(f"[说话人 {sentence['spk']}] {sentence['text']}")
+segmented_results = pipeline.generate(
+ input=audio, batch_size_s=60, batch_size_threshold_s=30,
+ sentence_timestamp=True,
+)
+for item in segmented_results:
+ print(item.get("text", ""))
+ for sentence in item.get("sentence_info", []):
+ print(sentence.get("start"), sentence.get("end"), sentence.get("text", ""))
```
-注:`spk_model` 也可以使用 `"cam++"` (CAM++ 模型)。ERes2NetV2 在短时说话人特征提取方面有所改进。
-自定义 `spk_model` 可以传 ModelScope 模型 ID 或本地模型路径;模型需要能通过 FunASR `AutoModel` 加载,并在自身 `inference()` 方法中返回 `spk_embedding`,用户侧仍调用 `AutoModel.generate()`。后续说话人聚类会使用这些 embedding 分配 `spk` 标签。
-#### 多语言语音识别 (Qwen3-ASR)
-```python
-from funasr import AutoModel
+`max_single_segment_time` 单位为**毫秒**,两个 batch 时长参数单位为**秒**。分段有助于处理较长文件,但不保证任意时长或固定内存占用;音频加载阶段和各模型仍会消耗资源。内存不足时,可缩短录音/片段或减小模型支持的 batch,再重新测量。句子边界依赖可用的时间戳和标点对齐,可能回退到 VAD 片段,应检查真实结果。
-# Qwen3-ASR 支持52种语言自动语言检测
-# hub="hf" 从 HuggingFace 下载,默认 hub="ms" 从 ModelScope 下载
-model = AutoModel(model="Qwen/Qwen3-ASR-1.7B", hub="hf", device="cuda:0")
+需要说话人分割时,在所选组件支持的前提下,为相同流水线添加 `spk_model="cam++"`。遍历每条输入的 `item.get("sentence_info", [])` 后,再读取 `sentence.get("spk")`;不要从外层结果列表直接读取 `spk`。聚类标签不等于已验证的真实身份。参见[说话人组合示例](../../examples/industrial_data_pretraining/sense_voice/demo_spk.py)。
-# 指定语言
-res = model.generate(input="audio_zh.wav", language="Chinese")
-print(res[0]["text"])
+## 4. 处理多条录音
-# 自动语言检测
-res = model.generate(input="audio.wav")
-print(res[0]["text"], res[0].get("language", ""))
-```
-注:请使用 `pip install -U "qwen-asr==0.0.6" "transformers==4.57.6" accelerate`。`qwen-asr==0.0.6` 锁定 `transformers==4.57.6`;若环境中混入不兼容的新版 Transformers,可能触发嵌套 `thinker_config` 报错。支持 0.6B 和 1.7B 两种模型规格。
+下面故意重复同一示例,演示列表输入,不依赖额外文件。实际使用时替换为本地 WAV 路径:
-#### 多语言语音识别 (GLM-ASR)
```python
-from funasr import AutoModel
-
-# GLM-ASR-Nano 支持17种语言,方言及低音量语音优化
-# hub="hf" 从 HuggingFace 下载,默认 hub="ms" 从 ModelScope 下载
-model = AutoModel(model="zai-org/GLM-ASR-Nano-2512", hub="hf", device="cuda:0")
-res = model.generate(input="audio.wav")
-print(res[0]["text"])
-
-# ModelScope(国内用户)
-model = AutoModel(model="ZhipuAI/GLM-ASR-Nano-2512", hub="ms", device="cuda:0")
-```
-注:需要 `transformers>=5.0.0`(从源码安装:`pip install git+https://github.com/huggingface/transformers`)。
-
-
-
-<a name="核心功能"></a>
-## 模型训练与测试
-
-### 快速开始
-
-命令行执行(用于快速测试,不推荐):
-```shell
-funasr-train ++model=paraformer-zh ++train_data_set_list=data/list/train.jsonl ++valid_data_set_list=data/list/val.jsonl ++output_dir="./outputs" &> log.txt &
-```
-
-python代码执行(可以多机多卡,推荐)
-
-```shell
-cd examples/industrial_data_pretraining/paraformer
-bash finetune.sh
-# "log_file: ./outputs/log.txt"
-```
-详细完整的脚本参考 [finetune.sh](https://github.com/modelscope/FunASR/blob/main/examples/industrial_data_pretraining/paraformer/finetune.sh)
-
-### 详细参数介绍
-
-```shell
-funasr/bin/train_ds.py \
-++model="${model_name_or_model_dir}" \
-++train_data_set_list="${train_data}" \
-++valid_data_set_list="${val_data}" \
-++dataset_conf.batch_size=20000 \
-++dataset_conf.batch_type="token" \
-++dataset_conf.num_workers=4 \
-++train_conf.max_epoch=50 \
-++train_conf.log_interval=1 \
-++train_conf.resume=false \
-++train_conf.validate_interval=2000 \
-++train_conf.save_checkpoint_interval=2000 \
-++train_conf.keep_nbest_models=20 \
-++train_conf.avg_nbest_model=10 \
-++optim_conf.lr=0.0002 \
-++output_dir="${output_dir}" &> ${log_file}
+batch_results = model.generate(input=[audio, audio], batch_size=1)
+for index, item in enumerate(batch_results):
+ print(index, item.get("key"), item.get("text", ""))
```
-- `model`(str):模型名字(模型仓库中的ID),此时脚本会自动下载模型到本地;或者本地已经下载好的模型路径。
-- `train_data_set_list`(str):训练数据路径,默认为jsonl格式,具体参考([例子](https://github.com/modelscope/FunASR/blob/main/data/list))。
-- `valid_data_set_list`(str):验证数据路径,默认为jsonl格式,具体参考([例子](https://github.com/modelscope/FunASR/blob/main/data/list))。
-- `dataset_conf.batch_type`(str):`example`(默认),batch的类型。`example`表示按照固定数目batch_size个样本组batch;`length` or `token` 表示动态组batch,batch总长度或者token数为batch_size。
-- `dataset_conf.batch_size`(int):与 `batch_type` 搭配使用,当 `batch_type=example` 时,表示样本个数;当 `batch_type=length` 时,表示样本中长度,单位为fbank帧数(1帧10ms)或者文字token个数。
-- `train_conf.max_epoch`(int):`100`(默认),训练总epoch数。
-- `train_conf.log_interval`(int):`50`(默认),打印日志间隔step数。
-- `train_conf.resume`(int):`True`(默认),是否开启断点重训。
-- `train_conf.validate_interval`(int):`5000`(默认),训练中做验证测试的间隔step数。
-- `train_conf.save_checkpoint_interval`(int):`5000`(默认),训练中模型保存间隔step数。
-- `train_conf.avg_keep_nbest_models_type`(str):`acc`(默认),保留nbest的标准为acc(越大越好)。`loss`表示,保留nbest的标准为loss(越小越好)。
-- `train_conf.keep_nbest_models`(int):`500`(默认),保留最大多少个模型参数,配合 `avg_keep_nbest_models_type` 按照验证集 acc/loss 保留最佳的n个模型,其他删除,节约存储空间。
-- `train_conf.avg_nbest_model`(int):`10`(默认),保留最大多少个模型参数,配合 `avg_keep_nbest_models_type` 按照验证集 acc/loss 对最佳的n个模型平均。
-- `train_conf.accum_grad`(int):`1`(默认),梯度累积功能。
-- `train_conf.grad_clip`(float):`10.0`(默认),梯度截断功能。
-- `train_conf.use_fp16`(bool):`False`(默认),开启fp16训练,加快训练速度。
-- `optim_conf.lr`(float):学习率。
-- `output_dir`(str):模型保存路径。
-- `**kwargs`(dict): 所有在`config.yaml`中参数,均可以直接在此处指定,例如,过滤20s以上长音频:`dataset_conf.max_token_length=2000`,单位为音频fbank帧数(1帧10ms)或者文字token个数。
-
-#### 多gpu训练
-##### 单机多gpu训练
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 1 --nproc_per_node ${gpu_num} \
-../../../funasr/bin/train_ds.py ${train_args}
-```
---nnodes 表示参与的节点总数,--nproc_per_node 表示每个节点上运行的进程数
-
-##### 多机多gpu训练
-
-在主节点上,假设IP为192.168.1.1,端口为12345,使用的是2个GPU,则运行如下命令:
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 2 --node_rank 0 --nproc_per_node ${gpu_num} --master_addr 192.168.1.1 --master_port 12345 \
-../../../funasr/bin/train_ds.py ${train_args}
-```
-在从节点上(假设IP为192.168.1.2),你需要确保MASTER_ADDR和MASTER_PORT环境变量与主节点设置的一致,并运行同样的命令:
-```shell
-export CUDA_VISIBLE_DEVICES="0,1"
-gpu_num=$(echo $CUDA_VISIBLE_DEVICES | awk -F "," '{print NF}')
-
-torchrun --nnodes 2 --node_rank 1 --nproc_per_node ${gpu_num} --master_addr 192.168.1.1 --master_port 12345 \
-../../../funasr/bin/train_ds.py ${train_args}
-```
-
---nnodes 表示参与的节点总数,--node_rank 表示当前节点id,--nproc_per_node 表示每个节点上运行的进程数(通常为gpu个数)
-
-#### 准备数据
-
-`jsonl`格式可以参考([例子](https://github.com/modelscope/FunASR/blob/main/data/list))。
-可以用指令 `scp2jsonl` 从wav.scp与text.txt生成。wav.scp与text.txt准备过程如下:
-
-`train_text.txt`
-
-左边为数据唯一ID,需与`train_wav.scp`中的`ID`一一对应
-右边为音频文件标注文本,格式如下:
-
-```bash
-ID0012W0013 当客户风险承受能力评估依据发生变化时
-ID0012W0014 所有只要处理 data 不管你是做 machine learning 做 deep learning
-ID0012W0015 he tried to think how it could be
-```
-
-
-`train_wav.scp`
-
-左边为数据唯一ID,需与`train_text.txt`中的`ID`一一对应
-右边为音频文件的路径,格式如下
-
-```bash
-BAC009S0764W0121 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav
-BAC009S0916W0489 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0916W0489.wav
-ID0012W0015 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_cn_en.wav
-```
-
-`生成指令`
-
-```shell
-# generate train.jsonl and val.jsonl from wav.scp and text.txt
-scp2jsonl \
-++scp_file_list='["../../../data/list/train_wav.scp", "../../../data/list/train_text.txt"]' \
-++data_type_list='["source", "target"]' \
-++jsonl_file_out="../../../data/list/train.jsonl"
-```
-
-(可选,非必需)如果需要从jsonl解析成wav.scp与text.txt,可以使用指令:
-
-```shell
-# generate wav.scp and text.txt from train.jsonl and val.jsonl
-jsonl2scp \
-++scp_file_list='["../../../data/list/train_wav.scp", "../../../data/list/train_text.txt"]' \
-++data_type_list='["source", "target"]' \
-++jsonl_file_in="../../../data/list/train.jsonl"
-```
-
-#### 大数据训练
-如果数据量很大,例如5万小时以上,这时候容易遇到内存不足的问题,特别是多gpu实验,这时候需要对jsonl文件进行切分成slice,然后写到txt里面,一行一个slice,然后设置`data_split_num`,例如:
-```shell
-train_data="/root/data/list/data.list"
-
-funasr/bin/train_ds.py \
-++train_data_set_list="${train_data}" \
-++dataset_conf.data_split_num=256
-```
-其中:
-`data.list`:为纯文本,内容是切割后的jsonl文件,例如,`data.list`的内容为:
-```bash
-data/list/train.0.jsonl
-data/list/train.1.jsonl
-...
-```
-`data_split_num`:表示切分slice分组个数,例如,data.list中共512行,data_split_num=256,表示分成256组,每组有2个jsonl文件,这样每次只load 2个jsonl数据进行训练,从而降低训练过程中内存使用。注意是按照顺序分组。
-如果是,非常大,并且数据类型差异比较大,建议切分时候进行数据均衡。
-
-#### 查看训练日志
-
-##### 查看实验log
-```shell
-tail log.txt
-[2024-03-21 15:55:52,137][root][INFO] - train, rank: 3, epoch: 0/50, step: 6990/1, total step: 6990, (loss_avg_rank: 0.327), (loss_avg_epoch: 0.409), (ppl_avg_epoch: 1.506), (acc_avg_epoch: 0.795), (lr: 1.165e-04), [('loss_att', 0.259), ('acc', 0.825), ('loss_pre', 0.04), ('loss', 0.299), ('batch_size', 40)], {'data_load': '0.000', 'forward_time': '0.315', 'backward_time': '0.555', 'optim_time': '0.076', 'total_time': '0.947'}, GPU, memory: usage: 3.830 GB, peak: 18.357 GB, cache: 20.910 GB, cache_peak: 20.910 GB
-[2024-03-21 15:55:52,139][root][INFO] - train, rank: 1, epoch: 0/50, step: 6990/1, total step: 6990, (loss_avg_rank: 0.334), (loss_avg_epoch: 0.409), (ppl_avg_epoch: 1.506), (acc_avg_epoch: 0.795), (lr: 1.165e-04), [('loss_att', 0.285), ('acc', 0.823), ('loss_pre', 0.046), ('loss', 0.331), ('batch_size', 36)], {'data_load': '0.000', 'forward_time': '0.334', 'backward_time': '0.536', 'optim_time': '0.077', 'total_time': '0.948'}, GPU, memory: usage: 3.943 GB, peak: 18.291 GB, cache: 19.619 GB, cache_peak: 19.619 GB
-```
-指标解释:
-- `rank`:表示gpu id。
-- `epoch`,`step`,`total step`:表示当前epoch,step,总step。
-- `loss_avg_rank`:表示当前step,所有gpu平均loss。
-- `loss/ppl/acc_avg_epoch`:表示当前epoch周期,截止当前step数时,总平均loss/ppl/acc。epoch结束时的最后一个step表示epoch总平均loss/ppl/acc,推荐使用acc指标。
-- `lr`:当前step的学习率。
-- `[('loss_att', 0.259), ('acc', 0.825), ('loss_pre', 0.04), ('loss', 0.299), ('batch_size', 40)]`:表示当前gpu id的具体数据。
-- `total_time`:表示单个step总耗时。
-- `GPU, memory`:分别表示,模型使用/峰值显存,模型+缓存使用/峰值显存。
-
-##### tensorboard可视化
-```bash
-tensorboard --logdir /xxxx/FunASR/examples/industrial_data_pretraining/paraformer/outputs/log/tensorboard
-```
-浏览器中打开:http://localhost:6006/
-
-### 训练后模型测试
-
+仅在模型支持且内存允许时增大 `batch_size`。也可输入 `wav.scp` 文件列表,每行使用 `utterance_id path`,路径相对于进程工作目录解析,每条录音使用唯一 ID。需要模型写出文件时设置 `output_dir`,仅接收返回列表不强制要求该参数。参见[数据列表示例](../../data/list/train_wav.scp)。独立文件的批处理不等于同一句话的流式分块。
-#### 有configuration.json
+## 5. 热词与语言边界
-假定,训练模型路径为:./model_dir,如果该目录下有生成configuration.json,只需要将 [上述模型推理方法](https://github.com/modelscope/FunASR/blob/main/examples/README_zh.md#%E6%A8%A1%E5%9E%8B%E6%8E%A8%E7%90%86) 中模型名字修改为模型路径即可
-
-例如:
-
-从shell推理
-```shell
-python -m funasr.bin.inference ++model="./model_dir" ++input=="${input}" ++output_dir="${output_dir}"
-```
-从python推理
+本工作区中 ModelScope 的 `paraformer-zh` 别名映射到 SeACo Paraformer,其实现接受单数 `hotword`,值为以空格分隔的字符串:
```python
-from funasr import AutoModel
-
-model = AutoModel(model="./model_dir")
-
-res = model.generate(input=wav_file)
-print(res)
-```
-
-#### 无configuration.json时
-
-如果模型路径中无configuration.json时,需要手动指定具体配置文件路径与模型路径
-
-```shell
-python -m funasr.bin.inference \
---config-path "${local_path}" \
---config-name "${config}" \
-++init_param="${init_param}" \
-++tokenizer_conf.token_list="${tokens}" \
-++frontend_conf.cmvn_file="${cmvn_file}" \
-++input="${input}" \
-++output_dir="${output_dir}" \
-++device="${device}"
+biased_results = model.generate(input=audio, hotword="魔搭 达摩院")
+print([item.get("text", "") for item in biased_results])
```
-参数介绍
-- `config-path`:为实验中保存的 `config.yaml`,可以从实验输出目录中查找。
-- `config-name`:配置文件名,一般为 `config.yaml`,支持yaml格式与json格式,例如 `config.json`
-- `init_param`:需要测试的模型参数,一般为`model.pt`,可以自己选择具体的模型文件
-- `tokenizer_conf.token_list`:词表文件路径,一般在 `config.yaml` 有指定,无需再手动指定,当 `config.yaml` 中路径不正确时,需要在此处手动指定。
-- `frontend_conf.cmvn_file`:wav提取fbank中用到的cmvn文件,一般在 `config.yaml` 有指定,无需再手动指定,当 `config.yaml` 中路径不正确时,需要在此处手动指定。
-
-其他参数同上,完整 [示例](https://github.com/modelscope/FunASR/blob/main/examples/industrial_data_pretraining/paraformer/infer_from_local.sh)
+这是模型级上下文偏置,不保证一定插入指定词,也不是确定性文本替换。请确认实际解析出的模型,并与不加热词的结果对比。参见 [SeACo 实现](../../funasr/models/seaco_paraformer/model.py)与[上下文 Paraformer 示例](../../examples/industrial_data_pretraining/contextual_paraformer/demo.py)。
+本源码工作区的文本后处理是另一种操作:
-<a name="模型导出与测试"></a>
-## 模型导出与测试
-### 从命令行导出
-```shell
-funasr-export ++model=paraformer ++quantize=false
-```
-
-### 从Python导出
```python
-from funasr import AutoModel
-
-model = AutoModel(model="paraformer")
-
-res = model.export(quantize=False)
-```
-
-### 优化onnx
-```shell
-# pip3 install -U onnxslim
-onnxslim model.onnx model.onnx
-```
-
-### 测试ONNX
-```python
-# pip3 install -U funasr-onnx
-from funasr_onnx import Paraformer
-model_dir = "damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch"
-model = Paraformer(model_dir, batch_size=1, quantize=True)
-
-wav_path = ['~/.cache/modelscope/hub/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/example/asr_example.wav']
-
-result = model(wav_path)
-print(result)
+corrected_results = model.generate(
+ input=audio,
+ postprocess_hotwords={"科大迅飞": "科大讯飞"},
+ return_postprocess_hotword_matches=True,
+)
+for item in corrected_results:
+ print(item.get("text", ""), item.get("postprocess_hotword_matches", []))
```
-更多例子请参考 [样例](https://github.com/modelscope/FunASR/tree/main/runtime/python/onnxruntime)
+显式映射替换输出文本中的匹配项。`postprocess_hotword_file` 还支持每行一个目标词或 `错误词=>目标词` 映射。模糊匹配额外需要 `pypinyin` 和 `rapidfuzz`,显式映射不需要。[后处理实现](../../funasr/utils/postprocess_hotwords.py)保留原有时间戳,不会重新对齐修改后的文本;生成字幕或宣称对齐准确前,请审查替换结果。
-<a name="新模型注册教程"></a>
-## 新模型注册教程
+`hotword`、`hotwords` 和 `language` **不是可互换的通用 SDK 选项**。例如 [Fun-ASR-Nano](../../examples/industrial_data_pretraining/fun_asr_nano/README_zh.md)读取复数 `hotwords` 和模型专属语言提示。修改提示不能把单语言权重变成多语言权重。语言支持、提示取值、流式能力、对齐和依赖版本应按[模型仓库](../../model_zoo/readme_zh.md)及精确模型指南确认,不要跨模型照搬语言数量或安装版本。
+## 6. 进入具体工作流
-### 查看注册表
+- **流式识别:**[Paraformer 流式示例](../../examples/industrial_data_pretraining/paraformer_streaming/demo.py)。每个音频流维护独立 `cache={}`,最后一块设置 `is_final=True`。16 kHz 下 `[0, 10, 5]` 的 600 ms 对应 **9600 个采样点**,不是 960;分块时长不代表端到端延时。流式 VAD 可能返回 `[start, -1]`、`[-1, end]`、完整区间或空区间,单位为毫秒。
+- **标点与对齐:**[标点示例](../../examples/industrial_data_pretraining/ct_transformer/demo.py)与[时间戳预测示例](../../examples/industrial_data_pretraining/monotonic_aligner/demo.py)。对齐需要对应的文本输入,不等同于语音识别。
+- **其他模型系列:**[SenseVoice](../../examples/industrial_data_pretraining/sense_voice/README_zh.md)、[Fun-ASR-Nano](../../examples/industrial_data_pretraining/fun_asr_nano/README_zh.md)、[第三方 OpenMOSS 集成](../moss_transcribe_diarize_zh.md)。更多入口统一在模型仓库查找。
+- **命令行与服务:**[CLI 参考](../cli.md)、[运行时概览](../../runtime/readme_cn.md)和 [Docker](../installation/docker_zh.md)。Python 参数不代表服务请求具有相同结构。
-```plaintext
-from funasr.register import tables
+<a id="模型训练与测试" name="模型训练与测试"></a>
+## 训练与验证入口
-tables.print()
-```
+请使用 [Paraformer 配方](../../examples/industrial_data_pretraining/paraformer/README.md)、[finetune.sh](../../examples/industrial_data_pretraining/paraformer/finetune.sh)和[训练数据示例](../../data/list/train.jsonl)。启动前检查数据集路径、标签对齐、模型许可、GPU 分配和输出目录;训练不是安装冒烟测试。测试训练后权重时,先检查 [infer_from_local.sh](../../examples/industrial_data_pretraining/paraformer/infer_from_local.sh),确保配置、分词器/前端资源和 checkpoint 路径一致。[验证数据](../../data/list/val.jsonl)应与训练数据分开。
-支持查看指定类型的注册表:\`tables.print("model")\`
+<a id="模型导出与测试" name="模型导出与测试"></a>
+## 导出与运行时验证
-### 注册模型
+按照模型的 [Paraformer 导出示例](../../examples/industrial_data_pretraining/paraformer/export.py)和 [ONNX Runtime 指南](../../runtime/python/onnxruntime/README.md)操作。导出支持与额外依赖由具体模型/后端决定。导出成功不表示结果等价;部署前应使用有代表性的输入测试导出制品,并与原模型比较。
-```python
-from funasr.register import tables
-
[email protected]("model_classes", "SenseVoiceSmall")
-class SenseVoiceSmall(nn.Module):
- def __init__(*args, **kwargs):
- ...
-
- def forward(
- self,
- **kwargs,
- ):
-
- def inference(
- self,
- data_in,
- data_lengths=None,
- key: list = None,
- tokenizer=None,
- frontend=None,
- **kwargs,
- ):
- ...
-
-```
-
-在需要注册的类名前加上 `@tables.register("model_classes","SenseVoiceSmall")`,即可完成注册,类需要实现有:__init__,forward,inference方法。
-
-完整代码:[https://github.com/modelscope/FunASR/blob/main/funasr/models/sense\_voice/model.py#L443](https://github.com/modelscope/FunASR/blob/main/funasr/models/sense_voice/model.py#L443)
-
-注册完成后,在config.yaml中指定新注册模型,即可实现对模型的定义
-
-```python
-model: SenseVoiceSmall
-model_conf:
- ...
-```
+<a id="新模型注册教程" name="新模型注册教程"></a>
+## 注册自定义模型
+参见[注册表教程](./Tables_zh.md)和 [SenseVoice 实现](../../funasr/models/sense_voice/model.py)。完成注册不代表 `generate()` 契约已经满足,模型推理结果必须与计划使用的下游组件匹配。
-[关于注册更多详细教程文档](https://github.com/modelscope/FunASR/blob/main/docs/tutorial/Tables_zh.md)
+遇到问题时,带上解释器/依赖版本、实际模型 ID/revision、输入格式和最小复现,回到[常见问题](../troubleshooting_zh.md)。不要在反馈中附带私密音频或凭据。
diff --git a/examples/openai_api/CLIENTS.md b/examples/openai_api/CLIENTS.md
index c73bc3766..8846752f2 100644
--- a/examples/openai_api/CLIENTS.md
+++ b/examples/openai_api/CLIENTS.md
@@ -1,6 +1,24 @@
# Client Recipes for the FunASR OpenAI-Compatible API
-Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For JavaScript, TypeScript, and Next.js examples, see the [JavaScript/TypeScript recipes](JAVASCRIPT.md) or [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md). For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md). For browser upload or microphone demos, use the [Gradio browser demo](GRADIO.md). For no-code API smoke tests, import the [Postman collection](POSTMAN.md). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.md). Before sharing the service, review the [security and gateway guide](SECURITY.md).
+Use this page when the packaged `funasr-server` or the repository's example `server.py` is already running. They share a multipart transcription request subset, but not identical defaults, aliases, or response schemas; see [API boundaries](#api-contract). For in-process `AutoModel.generate()` and model-specific options, use the [Python SDK guide](../../docs/python_api.md) ([中文](../../docs/python_api_zh.md)). For JavaScript, TypeScript, and Next.js examples, see the [JavaScript/TypeScript recipes](JAVASCRIPT.md) or [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md). For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md). For browser upload or microphone demos, use the [Gradio browser demo](GRADIO.md). For no-code API smoke tests, import the [Postman collection](POSTMAN.md). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.md). Before sharing the service, review the [security and gateway guide](SECURITY.md).
+
+## API Contract
+
+The [example server](server.py) defaults to `sensevoice` at startup and when multipart `model` is omitted. The packaged [CLI](../../funasr/bin/server.py) defaults to `--model auto`: its [app](../../funasr/bin/_server_app.py) selects `fun-asr-nano` for device strings starting with `cuda`, otherwise `sensevoice`. The packaged transcription form defaults to `fun-asr-nano`, independently of startup preloading. Always specify `model` explicitly and check the deployed `/v1/models` and `/openapi.json`. The checked-in OpenAPI spec describes the example, not every packaged-server field.
+
+`response_format=verbose_json` selects a response format; **it does not enable diarization or force timestamp generation**. The example copies model-provided `sentence_info` to `segments`, otherwise returns `segments=[]`, and has no `spk` form field. In the packaged server, `spk=true` opts into external speaker processing for non-native diarization models (default `False`). MOSS has native anonymous labels and should not be combined with external VAD or speaker models. Labels are not verified identities or stable IDs across recordings.
+
+For an already-running **packaged `funasr-server` only**, this multipart request opts into speaker processing when supported by its installed dependencies and model:
+
+```bash
+curl -fsS http://localhost:8000/v1/audio/transcriptions \
+ -F model=sensevoice \
+ -F response_format=verbose_json \
+ -F spk=true
+```
+
+Do not send `spk=true` to the example and assume it enables anything. Neither endpoint exposes every `AutoModel.generate()` option as a form field. Review [response formats](#response-formats) for timestamp and duration semantics, and the [example README](README.md#api-contract) ([中文](README_zh.md#api-contract)) for startup instructions and scope.
## Preflight
@@ -16,10 +34,10 @@ If the server is on another machine, replace `localhost` with the reachable host
| Alias | Good first use | Notes |
|---|---|---|
-| `sensevoice` | Private multilingual API | Fast default with language, emotion, and event tags. |
+| `sensevoice` | Private transcription API | Example startup default, not the unconditional packaged default. Services strip rich tags from display text; no dedicated emotion/event fields. |
| `paraformer` | Mandarin production transcription | Includes VAD and punctuation. |
-| `paraformer-en` | English transcription | Smaller English-only route. |
-| `fun-asr-nano` | LLM-based ASR experiments | Pair with vLLM for higher throughput deployments. |
+| `paraformer-en` | English transcription | Registered in the example, not a built-in alias of packaged `funasr-server`. |
+| `fun-asr-nano` | LLM-based ASR experiments | The packaged app tries vLLM and can fall back to AutoModel; the example uses AutoModel. Validate dependencies and checkpoint contents for the chosen route. |
| `moss-transcribe-diarize` | Offline multi-speaker long-form audio | Returns timestamps and anonymous speaker labels in `verbose_json`; do not add external VAD or diarization. |
For MOSS server, Docker, Kubernetes, vLLM, SGLang Omni, LocalAI, and FunClip
@@ -27,6 +45,8 @@ paths, use the [dedicated deployment guide](../../docs/moss_transcribe_diarize.m
## Python OpenAI SDK
+Install this separate HTTP client with `pip install openai`; it is not the FunASR in-process SDK. The recipes use only the transcription subset supported by these services, not the complete OpenAI API.
+
```python
from openai import OpenAI
@@ -122,7 +142,7 @@ Use a multipart HTTP node or custom tool:
| Body type | `multipart/form-data` |
| File field | `file` |
| Text fields | `model=sensevoice`, `response_format=verbose_json` |
-| Result path | `text` for transcript, `segments` for timestamps/speakers |
+| Result path | `text` for transcript; `segments` may be empty and speaker labels are conditional |
When the workflow system cannot send files directly, upload audio to an internal object store first, then run a small worker that downloads the object and calls FunASR with the `requests` recipe above. See [workflow recipes](WORKFLOWS.md) for Dify, n8n, and webhook-worker patterns, or the [Chinese workflow recipes](WORKFLOWS_zh.md).
@@ -134,27 +154,51 @@ When the workflow system cannot send files directly, upload audio to an internal
{"text": "recognized speech"}
```
-`response_format=verbose_json` adds operational fields useful for agents and subtitles:
+`response_format=verbose_json` does not enable diarization. Its fields depend on the deployed entry point:
+
+| Field | Example `server.py` | Packaged `funasr-server` |
+|---|---|---|
+| `duration` | Elapsed seconds around `generate()`, excluding initial model loading; not audio duration. | Audio duration in seconds; fallback can return 0 if audio metadata cannot be read. |
+| `segments` | Converted from model-provided `sentence_info`; otherwise `[]`. | Uses available segments; fallback can synthesize coarse text-based intervals over the audio duration. |
+| `start`, `end` | Segment times in seconds. | Segment times in seconds, not necessarily word-level alignment. |
+| `speaker` | Model-provided label or null when a segment lacks a label. | Included only when a label is present; external clustering needs `spk=true`, while MOSS has native labels. |
+| Other fields | Includes `model`; `language` echoes the requested hint or `auto`. | Includes `task` and segment `id`/`words`; does not add a top-level `model` field in the verbose builder. |
+
+Illustrative **packaged-server** response for a 3.2-second recording, without speaker opt-in. The single coarse segment is not a claim of forced alignment; actual text, language, and segmentation vary:
```json
{
+ "task": "transcribe",
+ "language": "en",
+ "duration": 3.2,
"text": "recognized speech",
"segments": [
- {"start": 0.0, "end": 3.2, "text": "recognized speech", "speaker": 0}
- ],
+ {"id": 0, "start": 0.0, "end": 3.2, "text": "recognized speech", "words": []}
+ ]
+}
+```
+
+Illustrative **example-server** response when no `sentence_info` was returned. Here `0.42` is inference elapsed time, not the recording length:
+
+```json
+{
+ "text": "recognized speech",
+ "segments": [],
"language": "auto",
"duration": 0.42,
"model": "sensevoice"
}
```
+Check segment availability and provenance before generating subtitles. A nonempty `segments` array or `verbose_json` response is not evidence of speaker diarization or token-level alignment. The SDK's millisecond `sentence_info` coordinates are converted to seconds by these service adapters; see the [Python SDK result contract](../../docs/python_api.md).
+
## Production checklist
- Put TLS, authentication, rate limits, and upload-size limits in front of the service before exposing it outside a trusted network; use the [security and gateway guide](SECURITY.md) as the rollout checklist.
- Preload the default model at startup and use `/health` for readiness checks.
- Set client timeouts based on maximum audio duration; long recordings need longer HTTP timeouts.
- Log audio duration, model alias, device, latency, response format, and error type for every request.
-- Pin model aliases and deployment images in production notes so benchmark results remain reproducible.
+- Pin SDK/dependency versions, deployment images, full model IDs and resolved revisions/artifact hashes; aliases alone are not reproducible model pins. See [SDK offline and revision caveats](../../docs/python_api.md).
- For GPU hosts, keep one worker per GPU until you have measured memory headroom and concurrency behavior.
## Troubleshooting quick checks
diff --git a/examples/openai_api/README.md b/examples/openai_api/README.md
index 24a95a8d6..62ea37b0f 100644
--- a/examples/openai_api/README.md
+++ b/examples/openai_api/README.md
@@ -2,16 +2,34 @@
# FunASR OpenAI-Compatible API Server
-Drop-in replacement for OpenAI's `/v1/audio/transcriptions` endpoint. Works with **any agent framework** that supports OpenAI audio API.
+An OpenAI-style `/v1/audio/transcriptions` endpoint for private speech transcription. This example implements a speech API subset, not the entire OpenAI API or a compatibility guarantee for every SDK/framework feature.
+
+This page starts the repository's [example server](server.py). The packaged `funasr-server` is a [different implementation](../../funasr/bin/_server_app.py); see [API boundaries](#api-contract) before reusing its settings. For in-process `AutoModel.generate()` rather than HTTP requests, use the [Python SDK guide](../../docs/python_api.md) ([中文](../../docs/python_api_zh.md)).
+
+## API Contract
+
+| Entry point | Startup model | Omitted multipart `model` | Speaker opt-in |
+|---|---|---|---|
+| `python server.py` in this directory | `sensevoice` | `sensevoice` | No `spk` form field; only preserves speaker labels already returned by the model. |
+| `funasr-server` | `--model auto`: `fun-asr-nano` for a device string starting with `cuda`, otherwise `sensevoice` | `fun-asr-nano` | `spk=true` requests the separate speaker pipeline for non-native diarization models; default is `False`. |
+
+Specify `model` explicitly in requests: startup preloading and the request default are different settings. Query the deployed `/v1/models`; for example, `paraformer-en` is registered by this example but is not a built-in alias of the packaged server. Verify fields with the running `/openapi.json`, not just the checked-in [example schema](OPENAPI.md).
+
+`response_format=verbose_json` selects a response shape; **it does not enable diarization or force timestamp generation**. This example copies `sentence_info` into `segments` if present, otherwise returns `segments=[]`. Speaker labels can be absent or null. MOSS supplies native anonymous labels; it does not need `spk=true` or external VAD/CAM++.
+
+In this example, `duration` is elapsed time around `generate()` in seconds, excluding initial model loading; it is **not audio duration**. The packaged server's verbose response uses audio duration in seconds (its fallback can use 0 when audio metadata is unavailable). Segment `start`/`end` use seconds in both services. The packaged fallback can synthesize coarse segments from text and audio duration; those are not word-level forced alignment. Its verbose schema includes `task` and per-segment `id`/`words`, while this example includes `model`; do not assume identical JSON fields. See [response examples and speaker requests](CLIENTS.md#api-contract).
## Quick Start
+From the repository root:
+
```bash
pip install funasr fastapi uvicorn python-multipart
+cd examples/openai_api
python server.py --model sensevoice --device cuda --port 8000
```
-Server starts in ~20s (model loading). Health check: `GET /health`
+Wait for model loading before checking `GET /health`; download and startup time depend on the checkpoint, cache, network, and hardware. The commands below use this directory unless stated otherwise.
Need copy-paste integration snippets for Python SDK, JavaScript/TypeScript, HTTP clients, agent tools, a browser demo, Postman, OpenAPI imports, Kubernetes deployment, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [JavaScript/TypeScript recipes](JAVASCRIPT.md), [Gradio browser demo](GRADIO.md), [workflow recipes](WORKFLOWS.md), the [Chinese workflow recipes](WORKFLOWS_zh.md), the [Postman collection](POSTMAN.md), the [OpenAPI spec](OPENAPI.md), the [security and gateway guide](SECURITY.md), and the [Kubernetes deployment template](kubernetes/README.md).
@@ -49,6 +67,8 @@ The browser demo calls the same OpenAI-compatible API endpoints as the smoke tes
## Usage with OpenAI SDK (Python)
+Install the separate HTTP client with `pip install openai`. This is not the FunASR Python SDK.
+
```python
from openai import OpenAI
@@ -61,13 +81,14 @@ result = client.audio.transcriptions.create(
)
print(result.text)
-# With timestamps/segments
+# Inspect the verbose response; segments may be empty
result = client.audio.transcriptions.create(
model="sensevoice",
file=open("meeting.wav", "rb"),
response_format="verbose_json",
)
-# Returns: text, segments (with start/end/speaker), duration
+# verbose_json does not enable diarization; see API Contract above
+print(getattr(result, "segments", []))
```
## Usage with curl
@@ -86,13 +107,17 @@ curl http://localhost:8000/v1/audio/transcriptions \
## Available Models
-| Model | Speed (GPU) | Speed (CPU) | Languages | Features |
-|-------|-------------|-------------|-----------|----------|
-| `sensevoice` | 170x realtime | 17x realtime | zh/en/ja/ko/yue | Emotion detection |
-| `paraformer` | 120x realtime | 15x realtime | zh/en | Punctuation |
-| `paraformer-en` | 120x realtime | 15x realtime | en | English only |
-| `fun-asr-nano` | 17x realtime | 3.6x realtime | zh/en/ja + Chinese dialects/accents | LLM-based, timestamps |
-| `moss-transcribe-diarize` | Validate on target GPU | Offline only | Multilingual | Long-form timestamps + anonymous speaker labels |
+These are aliases in this example's `MODEL_CONFIGS`, not a universal SDK or server model list. The endpoint removes rich `<|...|>` tags from returned text; it does not expose dedicated emotion/event fields.
+
+| Model | Example configuration | Response limits |
+|---|---|---|
+| `sensevoice` | SenseVoiceSmall + FSMN-VAD | Does not enable sentence timestamps or external speaker clustering by default. |
+| `paraformer` | `paraformer-zh` + FSMN-VAD + CT punctuation | Punctuation is configured; `verbose_json` alone does not request sentence records. |
+| `paraformer-en` | `paraformer-en` + FSMN-VAD | Example-only alias relative to the packaged server; no punctuation component configured here. |
+| `fun-asr-nano` | Fun-ASR-Nano via `AutoModel`, HF hub + FSMN-VAD | Not a vLLM route in this example. CTC timestamp availability depends on complete checkpoint weights. |
+| `moss-transcribe-diarize` | Third-party OpenMOSS native transcription/diarization adapter | Requires its separate dependency environment; preserves model-provided timestamps and anonymous labels. |
+
+For checkpoint-specific language and license information, use [model selection](../../docs/model_selection.md) and the model's own license. FunASR software's MIT license is not a license for every model weight. Benchmark the selected route on your own workload; these aliases do not define universal speed or capacity.
MOSS uses a pinned third-party HF revision and must not be combined with an
external VAD or speaker model. See the [complete MOSS deployment guide](../../docs/moss_transcribe_diarize.md)
@@ -112,7 +137,7 @@ Prefer no-code API checks? Use the [Gradio browser demo](GRADIO.md) for local up
## Agent Framework Integration
-Works with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, or any framework using OpenAI audio API. See [Client recipes](CLIENTS.md) and [JavaScript/TypeScript recipes](JAVASCRIPT.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers ([中文](WORKFLOWS_zh.md)).
+The multipart HTTP/tool-function pattern can be used to integrate **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, and **n8n**; validate the chosen integration against this service's supported fields. These recipes do not establish compatibility with every framework version or realtime API. See [Client recipes](CLIENTS.md) and [JavaScript/TypeScript recipes](JAVASCRIPT.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers ([中文](WORKFLOWS_zh.md)).
### LangChain Example
```python
@@ -130,7 +155,7 @@ def transcribe_for_agent(audio_path: str) -> str:
## Docker Deployment
-Build the example image from this directory. The default image starts in CPU mode so it can be used as a portable smoke test.
+From the repository root, build the example image with the following commands. The default image starts the example `server.py` in CPU mode, not the packaged `funasr-server`.
```bash
cd examples/openai_api
@@ -178,6 +203,8 @@ Keep the default CPU mode until you have built a CUDA-capable image and configur
## Configuration
+The following defaults belong to this example's `server.py`, not `funasr-server`; compare [API boundaries](#api-contract).
+
| Arg | Default | Description |
|-----|---------|-------------|
| `--host` | 0.0.0.0 | Bind address |
diff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.md
index a73617f57..2f6d0689c 100644
--- a/examples/openai_api/README_zh.md
+++ b/examples/openai_api/README_zh.md
@@ -2,16 +2,34 @@
# FunASR OpenAI 兼容 API 服务
-FunASR OpenAI 兼容 API 提供 `/v1/audio/transcriptions`,可作为私有语音转写服务接入 OpenAI 风格 SDK、Agent 框架、Dify、n8n、HTTP 节点和内部业务系统。
+FunASR OpenAI 兼容 API 提供 `/v1/audio/transcriptions`,可作为私有语音转写服务接入 OpenAI 风格 SDK 或 multipart HTTP 客户端。它实现的是语音接口子集,不是完整 OpenAI API,也不保证兼容所有 SDK/框架功能。
+
+本页启动仓库中的[示例服务](server.py)。打包的 `funasr-server` 是[另一套实现](../../funasr/bin/_server_app.py),复用配置前请先看[接口边界](#api-contract)。如果需要进程内 `AutoModel.generate()` 而非 HTTP 请求,请查看 [Python SDK 指南](../../docs/python_api_zh.md)([English](../../docs/python_api.md))。
+
+## API Contract
+
+| 入口 | 启动预加载模型 | 省略 multipart `model` 时 | 说话人开关 |
+|---|---|---|---|
+| 在本目录运行 `python server.py` | `sensevoice` | `sensevoice` | 没有 `spk` 表单字段,只保留模型本身已经返回的说话人标签。 |
+| `funasr-server` | `--model auto`:设备字符串以 `cuda` 开头时选 `fun-asr-nano`,否则选 `sensevoice` | `fun-asr-nano` | `spk=true` 为非原生说话人模型请求单独的说话人处理,默认 `False`。 |
+
+每次请求都应明确指定 `model`:启动预加载与请求默认值是不同设置。请查询实际服务的 `/v1/models`;例如 `paraformer-en` 在示例服务中注册,却不是打包服务的内置别名。表单字段应以运行中服务的 `/openapi.json` 核对,不能只依赖仓库中的[示例规范](OPENAPI_zh.md)。
+
+`response_format=verbose_json` 只选择响应格式,**不会启用说话人分离,也不会强制生成时间戳**。此示例仅在模型返回 `sentence_info` 时将其转换为 `segments`,否则返回 `segments=[]`。说话人标签可能缺失或为 null。MOSS 原生输出匿名标签,不需要 `spk=true` 或外部 VAD/CAM++。
+
+此示例的 `duration` 是 `generate()` 调用的耗时,单位为秒,不包含初次模型加载,**不是音频时长**。打包服务的 verbose 响应使用秒单位的音频时长,其 fallback 在无法读取音频元数据时可能使用 0。两套服务的片段 `start`/`end` 均为秒。打包服务的 fallback 可能根据文本与音频时长生成粗粒度片段,并非逐词强制对齐。打包服务的 verbose 结构包含 `task` 及片段 `id`/`words`,示例服务则包含 `model`,不能假设 JSON 字段完全相同。参见[响应示例与说话人请求](CLIENTS.md#api-contract)。
## 快速开始
+从仓库根目录执行:
+
```bash
pip install funasr fastapi uvicorn python-multipart
+cd examples/openai_api
python server.py --model sensevoice --device cuda --port 8000
```
-服务通常会在模型加载后启动。健康检查:`GET /health`。
+模型加载后再检查 `GET /health`;下载及启动耗时取决于 checkpoint、缓存、网络和硬件。除非另有说明,下文命令均在本目录执行。
需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)、[Gradio 浏览器 Demo](GRADIO_zh.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md)、[OpenAPI 规范](OPENAPI_zh.md)、[安全与网关指南](SECURITY_zh.md) 和 [Kubernetes 部署模板](kubernetes/README_zh.md)。
@@ -49,6 +67,8 @@ python gradio_app.py --base-url http://localhost:8000
## 使用 OpenAI SDK
+先运行 `pip install openai` 安装独立的 HTTP 客户端;它不是 FunASR Python SDK。
+
```python
from openai import OpenAI
@@ -65,7 +85,8 @@ verbose = client.audio.transcriptions.create(
file=open("meeting.wav", "rb"),
response_format="verbose_json",
)
-print(verbose.segments)
+# verbose_json does not enable diarization; segments may be empty
+print(getattr(verbose, "segments", []))
```
## 使用 curl
@@ -83,13 +104,17 @@ curl http://localhost:8000/v1/audio/transcriptions \
## 可用模型
-| 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 | 中/英/日 + 中文方言/口音 | LLM-based,时间戳 |
-| `moss-transcribe-diarize` | 需在目标 GPU 验证 | 仅离线 | 多语言 | 长音频时间戳 + 匿名说话人标签 |
+下列别名来自此示例的 `MODEL_CONFIGS`,不是整个 SDK 或所有服务统一支持的模型列表。接口会去除返回文本中的 `<|...|>` 富文本标签,不会输出独立的情感/事件字段。
+
+| Model | 示例配置 | 响应限制 |
+|---|---|---|
+| `sensevoice` | SenseVoiceSmall + FSMN-VAD | 默认不启用句子时间戳或外部说话人聚类。 |
+| `paraformer` | `paraformer-zh` + FSMN-VAD + CT 标点 | 已配置标点;仅设置 `verbose_json` 不会请求句子记录。 |
+| `paraformer-en` | `paraformer-en` + FSMN-VAD | 相对于打包服务,这是示例专有别名;此处没有配置标点组件。 |
+| `fun-asr-nano` | `AutoModel` 加载 Fun-ASR-Nano,HF 平台 + FSMN-VAD | 此示例不使用 vLLM;CTC 时间戳依赖完整 checkpoint 权重。 |
+| `moss-transcribe-diarize` | 第三方 OpenMOSS 原生转写/说话人适配器 | 需要独立依赖环境;保留模型返回的时间戳与匿名标签。 |
+
+具体 checkpoint 的语言与许可证信息请查看[模型选择](../../docs/model_selection_zh.md) 和模型自身许可证。FunASR 软件的 MIT 许可证不代表所有模型权重的许可证。请在实际工作负载上测量所选路线,不应把别名当作统一的速度或容量规格。
MOSS 使用固定 revision 的第三方 HF 模型,不能外挂 VAD 或说话人模型。完整的
`funasr-server`、Docker Compose、Kubernetes、vLLM、SGLang Omni、LocalAI 与
@@ -108,7 +133,7 @@ FunClip 路径见 [MOSS 部署指南](../../docs/moss_transcribe_diarize_zh.md)
## Agent 与低代码工作流
-适用场景包括 **LangChain**、**LlamaIndex**、**AutoGen**、**CrewAI**、**Semantic Kernel**、**Dify**、**n8n** 和任何支持 OpenAI audio API 或 multipart HTTP 的系统。
+可以通过 multipart HTTP 或工具函数模式接入 **LangChain**、**LlamaIndex**、**AutoGen**、**CrewAI**、**Semantic Kernel**、**Dify**、**n8n**,但应按本服务支持的字段验证具体集成。这些示例不保证兼容每个框架版本或实时 API。
- SDK、JavaScript/TypeScript 和 Agent tool 写法见 [客户端配方](CLIENTS.md) 与 [JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)。
- Dify、n8n、HTTP 节点和 webhook worker 见 [工作流配方](WORKFLOWS_zh.md)。
@@ -117,7 +142,7 @@ FunClip 路径见 [MOSS 部署指南](../../docs/moss_transcribe_diarize_zh.md)
## Docker 部署
-默认镜像以 CPU 模式启动,适合作为可复现 smoke test。
+从仓库根目录执行下列命令。默认镜像以 CPU 模式启动示例 `server.py`,不是打包的 `funasr-server`。
```bash
cd examples/openai_api
@@ -165,6 +190,8 @@ python smoke_test.py --base-url http://localhost:8000
## 配置
+以下默认值属于示例 `server.py`,不属于 `funasr-server`;参见[接口边界](#api-contract)。
+
| 参数 | 默认值 | 说明 |
|---|---|---|
| `--host` | `0.0.0.0` | 监听地址 |
@@ -188,4 +215,4 @@ Docker 环境变量:
| 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`。 |
+| 响应中没有 `segments` | 设置 `response_format=verbose_json` 可选择包含该字段的响应格式;数组仍可能为空,它不会启用时间戳或说话人分离。参见[接口边界](#api-contract)。 |
diff --git a/gh-pages-output/api-reference.css b/gh-pages-output/api-reference.css
new file mode 100644
index 000000000..aa1048902
--- /dev/null
+++ b/gh-pages-output/api-reference.css
@@ -0,0 +1,186 @@
+:root {
+ color-scheme: light;
+ --ink: #171b19;
+ --muted: #56615b;
+ --green: #137544;
+ --line: #dce3de;
+ --surface: #f5f7f5;
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+ font-size: 16px;
+ line-height: 1.6;
+ color: var(--ink);
+ background: #fff;
+}
+
+* { box-sizing: border-box; letter-spacing: 0; }
+body { margin: 0; }
+[hidden] { display: none !important; }
+a { color: var(--green); text-underline-offset: 0.2em; }
+button, input { font: inherit; }
+button { cursor: pointer; }
+:focus-visible { outline: 3px solid var(--green); outline-offset: 3px; }
+h1, h2, h3, h4, p { margin-top: 0; }
+h1 { font-size: 2rem; line-height: 1.2; margin-bottom: 0.5rem; }
+h2 { font-size: 1.5rem; line-height: 1.4; }
+h3 { font-size: 1.125rem; }
+h4 { font-size: 1rem; margin-bottom: 0.5rem; }
+code { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 0.875em; }
+.muted, .dmod { color: var(--muted); }
+.sr-only, .skip-link:not(:focus) {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ padding: 0;
+ overflow: hidden;
+ clip-path: inset(50%);
+ white-space: nowrap;
+}
+.skip-link:focus { display: block; padding: 0.75rem 1rem; background: #fff; }
+.nav { border-bottom: 1px solid var(--line); }
+.nav .container {
+ max-width: 100rem;
+ margin: auto;
+ padding: 1rem 2rem;
+ display: flex;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 1rem 2rem;
+}
+.nav a { text-decoration: none; }
+.nav-logo { color: var(--ink); font-size: 1.5rem; font-weight: 750; }
+.nav-links { display: flex; flex-wrap: wrap; gap: 0.5rem 1.25rem; min-width: 0; }
+.nav-links a { color: var(--muted); padding: 0.3rem 0; }
+.nav-links a[aria-current] { color: var(--green); box-shadow: 0 2px var(--green); }
+.nav-github { margin-left: auto; color: var(--ink); font-weight: 600; }
+.api-header { max-width: 100rem; margin: auto; padding: 2rem 2rem 1.5rem; }
+.api-header p { color: var(--muted); margin-bottom: 0; font-size: 0.875rem; }
+.api-header p span { margin: 0 0.5rem; }
+.api-layout {
+ display: grid;
+ grid-template-columns: minmax(0, 19rem) minmax(0, 1fr);
+ max-width: 100rem;
+ margin: 0 auto;
+ border-top: 1px solid var(--line);
+ align-items: start;
+}
+.api-sidebar {
+ position: sticky;
+ top: 1rem;
+ max-height: calc(100dvh - 2rem);
+ overflow: auto;
+ min-width: 0;
+ padding: 1.25rem 1rem 2rem;
+ scrollbar-gutter: stable;
+}
+.sb-search {
+ width: 100%;
+ min-width: 0;
+ min-height: 2.75rem;
+ padding: 0.6rem 0.75rem;
+ margin-bottom: 1rem;
+ border: 1px solid #87978d;
+ border-radius: 6px;
+ color: var(--ink);
+ background: #fff;
+}
+.sb-search::placeholder { color: var(--muted); }
+.l1 { margin-bottom: 0.25rem; }
+.l1-title, .l2-title {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ width: 100%;
+ min-height: 2.75rem;
+ padding: 0.55rem 0.5rem;
+ text-align: left;
+ color: var(--ink);
+ background: transparent;
+ border: 0;
+ border-radius: 4px;
+ font-size: 0.8125rem;
+ line-height: 1.5;
+}
+.l1-title { font-weight: 650; }
+.l1-title > span:first-child, .l2-title > span:first-child { min-width: 0; overflow-wrap: anywhere; }
+.l1-title:hover, .l2-title:hover, .l3-item:hover { background: var(--surface); }
+.cnt { margin-left: auto; color: var(--muted); font-variant-numeric: tabular-nums; }
+.arr { margin-left: auto; flex: 0 0 0.75rem; text-align: center; }
+.cnt + .arr { margin-left: 0; }
+[aria-expanded="true"] > .arr { transform: rotate(90deg); }
+.l1-children { padding-left: 0.5rem; }
+.l2-children { margin: 0.25rem 0 0.5rem 0.5rem; border-left: 1px solid var(--line); }
+.l3-item {
+ display: flex;
+ align-items: baseline;
+ gap: 0.5rem;
+ min-height: 2.5rem;
+ padding: 0.5rem;
+ font-size: 0.8125rem;
+ line-height: 1.5;
+ text-decoration: none;
+ color: var(--muted);
+}
+.l3-item > span:last-child { min-width: 0; overflow-wrap: anywhere; }
+.l3m { padding-left: 1rem; }
+.l3-item[aria-current] { color: #095e32; background: #e7f3eb; box-shadow: inset 3px 0 var(--green); }
+.mb { flex: 0 0 1rem; text-align: center; font-family: ui-monospace, monospace; font-size: 0.75rem; font-weight: 700; }
+.badge-c { color: #11613b; }
+.badge-m { color: #4c5550; }
+.badge-f { color: #354941; }
+.search-empty { font-size: 0.875rem; color: var(--muted); }
+.api-content {
+ min-width: 0;
+ min-height: 65vh;
+ padding: 2rem;
+ border-left: 1px solid var(--line);
+ overflow-wrap: anywhere;
+}
+.api-detail { min-width: 0; max-width: 72rem; scroll-margin-top: 1rem; }
+.api-detail:focus { outline-offset: 0.5rem; }
+.api-detail h2 { margin: 0.5rem 0 0.75rem; }
+.api-detail h2 code { font-size: 0.875em; }
+.dtag { font-size: 0.75rem; text-transform: uppercase; font-weight: 700; }
+.dmod { font-size: 0.8125rem; margin-bottom: 1.5rem; }
+.ddoc, .mdoc { max-width: 80ch; }
+.ddoc p, .mdoc p { margin-bottom: 0.75rem; }
+.ddoc ul, .mdoc ul { padding-left: 1.25rem; }
+.ddoc li, .mdoc li { margin-bottom: 0.5rem; }
+.sub { color: var(--muted); }
+.src-block { margin: 1.5rem 0; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); min-width: 0; }
+.src-block summary { cursor: pointer; padding: 0.75rem 0; font-size: 0.875rem; font-weight: 600; }
+.src-block pre {
+ max-width: 100%;
+ margin: 0 0 1rem;
+ padding: 1rem;
+ overflow: auto;
+ white-space: pre;
+ overflow-wrap: normal;
+ color: #f0f4f1;
+ background: #171b19;
+ border-radius: 4px;
+ tab-size: 4;
+}
+.src-block pre code { font-size: 0.8125rem; }
+.src-more { display: inline-block; margin-bottom: 1rem; font-size: 0.8125rem; }
+.mt { margin-top: 2rem; }
+.mblk { padding: 1.25rem 0; border-top: 1px solid var(--line); }
+.mblk > code { font-weight: 600; }
+.gh-link { margin-left: 0.5rem; font-size: 0.8125rem; }
+.mdoc { margin-top: 1rem; }
+.api-welcome { padding: 1rem 0 3rem; }
+.entry-link { font-weight: 600; }
+
+@media (max-width: 760px) {
+ .nav .container { padding: 0.75rem 1rem; gap: 0.5rem 1rem; }
+ .nav-links { order: 3; flex-basis: 100%; gap: 0.5rem 1rem; font-size: 0.875rem; }
+ .api-header { padding: 1.5rem 1rem 1rem; }
+ .api-layout { grid-template-columns: minmax(0, 1fr); }
+ .api-sidebar { position: static; max-height: 20rem; padding: 1rem; border-bottom: 1px solid var(--line); }
+ .api-content { padding: 1.5rem 1rem; border-left: 0; }
+ .l1-title, .l2-title, .l3-item { min-height: 2.75rem; }
+ h2 { font-size: 1.25rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ * { scroll-behavior: auto !important; }
+}
diff --git a/gh-pages-output/index.html b/gh-pages-output/index.html
index 13fe40d9c..f0e12e93f 100644
--- a/gh-pages-output/index.html
+++ b/gh-pages-output/index.html
@@ -17,12 +17,12 @@
<p class="lead">From the first transcript to a service you can operate.</p>
<form action="https://www.funasr.com/en/docs/" method="get" role="search"><label for="query">Search documentation</label><div class="search"><input id="query" name="q" type="search" placeholder="Models, timestamps, MOSS, vLLM..."><button type="submit">Search</button></div></form>
<div class="chapters">
-<section><span class="number">01</span><h2>Get started</h2><a href="https://www.funasr.com/en/docs/model-selection.html">Choose a model</a><a href="tutorial.html">Python quickstart</a><a href="https://www.funasr.com/en/docs/command-line.html">Command-line inference</a><a href="https://www.funasr.com/en/docs/migration.html">Migrate from Whisper</a></section>
-<section><span class="number">02</span><h2>Models and capabilities</h2><a href="https://www.funasr.com/en/models.html">Model catalogue</a><a href="https://www.funasr.com/en/docs/moss-transcribe-diarize.html">MOSS-Transcribe-Diarize · Third-party model by OpenMOSS</a><a href="https://github.com/modelscope/FunASR/tree/main/model_zoo">Model Zoo</a><a href="model-registration.html">Register a model</a></section>
+<section><span class="number">01</span><h2>Get started</h2><a href="https://www.funasr.com/en/docs/installation.html">Installation</a><a href="tutorial.html">Python quickstart</a><a href="https://www.funasr.com/en/docs/python-api.html">Python SDK: AutoModel</a><a href="https://www.funasr.com/en/docs/command-line.html">Command-line inference</a><a href="https://www.funasr.com/en/docs/migration.html">Migrate from Whisper</a></section>
+<section><span class="number">02</span><h2>Models and capabilities</h2><a href="https://www.funasr.com/en/docs/model-selection.html">Choose a model</a><a href="https://www.funasr.com/en/docs/moss-transcribe-diarize.html">MOSS-Transcribe-Diarize · Third-party model by OpenMOSS</a><a href="https://www.funasr.com/en/docs/model-zoo.html">Model Zoo</a><a href="model-registration.html">Register a model</a></section>
<section><span class="number">03</span><h2>Deploy a service</h2><a href="https://www.funasr.com/en/deploy/">Deployment matrix</a><a href="https://www.funasr.com/en/deploy/vllm.html">Native vLLM</a><a href="https://www.funasr.com/en/docs/vllm.html">FunASR split-engine vLLM</a><a href="https://www.funasr.com/en/deploy/llama-cpp.html">llama.cpp and GGUF</a></section>
<section><span class="number">04</span><h2>Operate and extend</h2><a href="https://www.funasr.com/en/docs/troubleshooting.html">Troubleshooting</a><a href="https://www.funasr.com/en/docs/benchmark-method.html">Reproducible benchmarks</a><a href="training.html">Training and fine-tuning</a><a href="api.html">Python API</a></section>
</div>
-<section class="reference"><h2>Guides and reference</h2><p>The documentation hub uses repository Markdown as its source. Existing tutorials and API addresses remain available here.</p><nav aria-label="Reference"><a href="agent.html">Agent integrations</a><a href="use-cases.html">Use cases</a><a href="moss-transcribe-diarize.html">MOSS reference</a><a href="https://github.com/modelscope/FunASR/releases">Release assets</a><a href="ja/" lang="ja">日本語</a><a href="ko/" lang="ko">한국어</a></nav></section>
+<section class="reference"><h2>Guides and reference</h2><nav aria-label="Reference"><a href="https://www.funasr.com/en/docs/service-api.html">HTTP API contract</a><a href="https://www.funasr.com/en/docs/websocket-protocol.html">WebSocket protocol</a><a href="agent.html">Agent integrations</a><a href="use-cases.html">Use cases</a><a href="moss-transcribe-diarize.html">MOSS reference</a><a href="https://github.com/modelscope/FunASR/releases">Release assets</a><a href="ja/" lang="ja">日本語</a><a href="ko/" lang="ko">한국어</a></nav></section>
</main>
<footer><span>FunASR</span><a href="https://github.com/modelscope/FunASR/tree/main/docs">Edit documentation</a><a href="https://www.funasr.com/en/donors.html">Donors</a></footer>
</body>
diff --git a/gh-pages-output/zh/index.html b/gh-pages-output/zh/index.html
index a9e008eee..4dfb23224 100644
--- a/gh-pages-output/zh/index.html
+++ b/gh-pages-output/zh/index.html
@@ -17,12 +17,12 @@
<p class="lead">从第一次转写,到稳定运行的语音服务。</p>
<form action="https://www.funasr.com/docs/" method="get" role="search"><label for="query">搜索文档</label><div class="search"><input id="query" name="q" type="search" placeholder="模型、时间戳、MOSS、vLLM..."><button type="submit">搜索</button></div></form>
<div class="chapters">
-<section><span class="number">01</span><h2>开始使用</h2><a href="https://www.funasr.com/docs/model-selection.html">选择模型</a><a href="tutorial.html">Python 快速开始</a><a href="https://www.funasr.com/docs/command-line.html">命令行推理</a><a href="https://www.funasr.com/docs/migration.html">从 Whisper 迁移</a></section>
-<section><span class="number">02</span><h2>模型与能力</h2><a href="https://www.funasr.com/models.html">模型目录</a><a href="https://www.funasr.com/docs/moss-transcribe-diarize.html">MOSS-Transcribe-Diarize · OpenMOSS 第三方模型</a><a href="https://github.com/modelscope/FunASR/tree/main/model_zoo">Model Zoo</a><a href="../model-registration.html">注册模型</a></section>
+<section><span class="number">01</span><h2>开始使用</h2><a href="https://www.funasr.com/docs/installation.html">安装与环境验证</a><a href="tutorial.html">Python 快速开始</a><a href="https://www.funasr.com/docs/python-api.html">Python SDK: AutoModel</a><a href="https://www.funasr.com/docs/command-line.html">命令行推理</a><a href="https://www.funasr.com/docs/migration.html">从 Whisper 迁移</a></section>
+<section><span class="number">02</span><h2>模型与能力</h2><a href="https://www.funasr.com/docs/model-selection.html">选择模型</a><a href="https://www.funasr.com/docs/moss-transcribe-diarize.html">MOSS-Transcribe-Diarize · OpenMOSS 第三方模型</a><a href="https://www.funasr.com/docs/model-zoo.html">Model Zoo</a><a href="model-registration.html">注册模型</a></section>
<section><span class="number">03</span><h2>部署服务</h2><a href="https://www.funasr.com/deploy/">部署矩阵</a><a href="https://www.funasr.com/deploy/vllm.html">原生 vLLM</a><a href="https://www.funasr.com/docs/vllm.html">FunASR split-engine vLLM</a><a href="https://www.funasr.com/deploy/llama-cpp.html">llama.cpp 与 GGUF</a></section>
-<section><span class="number">04</span><h2>运维与扩展</h2><a href="https://www.funasr.com/docs/troubleshooting.html">常见问题与排障</a><a href="https://www.funasr.com/docs/benchmark-method.html">可复现性能评测</a><a href="../training.html">训练与微调</a><a href="../api.html">Python API</a></section>
+<section><span class="number">04</span><h2>运维与扩展</h2><a href="https://www.funasr.com/docs/troubleshooting.html">常见问题与排障</a><a href="https://www.funasr.com/docs/benchmark-method.html">可复现性能评测</a><a href="training.html">训练与微调</a><a href="../api.html">Python API</a></section>
</div>
-<section class="reference"><h2>教程与参考</h2><p>统一文档中心从仓库 Markdown 生成。本站原有教程和 API 地址继续保留。</p><nav aria-label="参考资料"><a href="../agent.html">Agent 集成</a><a href="use-cases.html">应用场景</a><a href="moss-transcribe-diarize.html">MOSS 参考</a><a href="https://github.com/modelscope/FunASR/releases">发布产物</a><a href="../ja/" lang="ja">日本語</a><a href="../ko/" lang="ko">한국어</a></nav></section>
+<section class="reference"><h2>教程与参考</h2><nav aria-label="参考资料"><a href="https://www.funasr.com/docs/service-api.html">HTTP API 契约</a><a href="https://www.funasr.com/docs/websocket-protocol.html">WebSocket 协议</a><a href="../agent.html">Agent 集成</a><a href="use-cases.html">应用场景</a><a href="moss-transcribe-diarize.html">MOSS 参考</a><a href="https://github.com/modelscope/FunASR/releases">发布产物</a><a href="../ja/" lang="ja">日本語</a><a href="../ko/" lang="ko">한국어</a></nav></section>
</main>
<footer><span>FunASR</span><a href="https://github.com/modelscope/FunASR/tree/main/docs">编辑文档</a><a href="https://www.funasr.com/donors.html">功德榜</a></footer>
</body>
diff --git a/model_zoo/readme.md b/model_zoo/readme.md
index d1cab094e..b42dad748 100644
--- a/model_zoo/readme.md
+++ b/model_zoo/readme.md
@@ -1,38 +1,94 @@
-([简体中文](./readme_zh.md)|English)
-
# Model Zoo
-## Model License
-You are free to use, copy, modify, and share FunASR models under the conditions of this agreement. You should indicate the model source and author information when using, copying, modifying and sharing FunASR models. You should keep the relevant names of models in [FunASR software]. Full model license could see [license](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE)
+[简体中文](./readme_zh.md) | English
+
+Choose the **model**, **checkpoint format**, and **runtime** separately. A model
+listed here is not automatically supported by every server or export backend.
+
+## Start by task
+
+| Task | Model family | Important boundary |
+| --- | --- | --- |
+| Context-aware file transcription | [Fun-ASR-Nano](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512) | The base checkpoint and native vLLM-converted checkpoint are different artifacts. |
+| Broader multilingual file transcription | [Fun-ASR-MLT-Nano](https://huggingface.co/FunAudioLLM/Fun-ASR-MLT-Nano-2512) | Separate checkpoint; do not attribute its language coverage to the base Nano model. |
+| Transcription with emotion and audio-event tags | [SenseVoiceSmall](https://huggingface.co/FunAudioLLM/SenseVoiceSmall) | Tags are model outputs, not speaker identity. Speaker-aware pipelines need the documented companion components. |
+| Mandarin transcription with timestamps | Paraformer | Offline and streaming checkpoints have different inference contracts. |
+| Offline text, timestamps and anonymous speakers together | [MOSS-Transcribe-Diarize](https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize) | Third-party OpenMOSS model; no external VAD or speaker model is needed for its unified path. Not known-person identification. |
+
+Use the [selection guide](../docs/model_selection.md) for workload choices,
+the [SDK contract](../docs/python_api.md) for parameters and return values, and
+the [deployment matrix](../docs/deployment_matrix.md) for serving options.
## Model Usage
-Ref to [docs](https://modelscope.github.io/FunASR/tutorial.html)
-## Model Zoo
-Here we provided several pretrained models on different datasets. The details of models and datasets can be found on [ModelScope](https://www.modelscope.cn/models?page=1&tasks=auto-speech-recognition).
+Start with the [installation guide](../docs/installation/installation.md) and
+[Python tutorial](../docs/tutorial/README.md). Use an explicit hub and record the
+resolved checkpoint/revision, FunASR version, device and inference options.
+Aliases are resolved by [the repository mapping](../funasr/download/name_maps_from_hub.py);
+an alias is convenient, but is not an immutable model revision.
+
+```python
+from funasr import AutoModel
+
+model = AutoModel(model="paraformer-zh", hub="ms", device="cpu")
+result = model.generate(input="meeting.wav")
+print(result[0]["text"])
+```
-### Speech Recognition
-#### Paraformer
+Replace `meeting.wav` with an existing recording. Download time, warmup and
+inference are separate measurements. Preserve the raw result when validating
+timestamps, speaker labels or model-specific tags.
+## Speech Recognition
-FunASR has open-sourced a large number of pre-trained models on industrial data. You are free to use, copy, modify, and share FunASR models under the [Model License Agreement](../MODEL_LICENSE). Below are some representative models, for more models please refer to the [Model Zoo](https://github.com/modelscope/FunASR/tree/main/model_zoo).
+### Paraformer
-(Note: 🤗 represents the Huggingface model zoo link, ⭐ represents the ModelScope model zoo link)
+| SDK alias | Intended use | ModelScope (`hub="ms"`) | Hugging Face (`hub="hf"`) |
+| --- | --- | --- | --- |
+| `paraformer-zh` | Offline Mandarin transcription; ModelScope alias selects SeACo | [SeACo checkpoint](https://modelscope.cn/models/iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary) | [Checkpoint](https://huggingface.co/funasr/paraformer-zh) |
+| `paraformer-zh-streaming` | Chunked streaming with per-session cache | [Checkpoint](https://modelscope.cn/models/iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online/summary) | [Checkpoint](https://huggingface.co/funasr/paraformer-zh-streaming) |
+| `paraformer-en` | Offline English transcription | Resolve through the [hub mapping](../funasr/download/name_maps_from_hub.py). | Resolve through the hub mapping. |
+The legacy [Paraformer VAD/punctuation pipeline](https://modelscope.cn/models/iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary)
+and `paraformer-zh-spk` listing describe pipelines, not the `paraformer-zh` alias target. For explicit
+composition, use `vad_model`, `punc_model` and `spk_model` as documented in the
+[SDK guide](../docs/python_api.md), rather than treating all components as one
+interchangeable ASR checkpoint.
+
+## Pipeline components
+
+| Component | Alias | Model cards | What it does not do |
+| --- | --- | --- | --- |
+| Voice activity detection | `fsmn-vad` | [ModelScope](https://modelscope.cn/models/iic/speech_fsmn_vad_zh-cn-16k-common-pytorch/summary) / [HF](https://huggingface.co/funasr/fsmn-vad) | Does not transcribe speech or identify a speaker. |
+| Punctuation restoration | `ct-punc` | [ModelScope](https://modelscope.cn/models/iic/punc_ct-transformer_cn-en-common-vocab471067-large/summary) / [HF](https://huggingface.co/funasr/ct-punc) | Does not create acoustic timestamps. |
+| Speaker embeddings | `cam++` | [Hub mapping](../funasr/download/name_maps_from_hub.py) | Does not name known people without a separately designed enrollment/matching system. |
+| Timestamp prediction | `fa-zh` | [Hub mapping](../funasr/download/name_maps_from_hub.py) | Must match the documented input/model path; not universal timestamp support for every recognizer. |
+
+See the [full ModelScope inventory](./modelscope_models.md) and
+[Hugging Face inventory](./huggingface_models.md) for additional checkpoints.
+These inventories include historical variants; verify each model card before
+using a checkpoint in a new service.
+
+## Third-party Unified Transcription and Diarization
+
+MOSS-Transcribe-Diarize is published by **OpenMOSS**, not by the FunASR team.
+Its unified offline output includes text, timestamps and anonymous speaker
+labels scoped to a recording. It is not a realtime streaming or known-person
+identification model. Use the [MOSS guide](../docs/moss_transcribe_diarize.md)
+for the adapter, native upstream servers, memory requirements and response
+boundaries.
+
+## Model License
-| Model Name | Task Details | Training Data | Parameters |
-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------:|:--------------------------------:|:----------:|
-| paraformer-zh <br> ([⭐](https://www.modelscope.cn/models/iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary) [🤗](https://huggingface.co/funasr/paraformer-zh) ) | speech recognition, with timestamps, non-streaming | 60000 hours, Mandarin | 220M |
-| paraformer-zh-spk <br> ( [⭐](https://modelscope.cn/models/damo/speech_paraformer-large-vad-punc-spk_asr_nat-zh-cn/summary) [🤗]() ) | speech recognition with speaker diarization, with timestamps, non-streaming | 60000 hours, Mandarin | 220M |
-| <nobr>paraformer-zh-online <br> ( [⭐](https://modelscope.cn/models/iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online/summary) [🤗](https://huggingface.co/funasr/paraformer-zh-streaming) )</nobr> | speech recognition, streaming | 60000 hours, Mandarin | 220M |
-| paraformer-en <br> ( [⭐](https://www.modelscope.cn/models/damo/speech_paraformer-large-vad-punc_asr_nat-en-16k-common-vocab10020/summary) [🤗]() ) | speech recognition, with timestamps, non-streaming | 50000 hours, English | 220M |
-| conformer-en <br> ( [⭐](https://modelscope.cn/models/damo/speech_conformer_asr-en-16k-vocab4199-pytorch/summary) [🤗]() ) | speech recognition, non-streaming | 50000 hours, English | 220M |
-| ct-punc <br> ( [⭐](https://modelscope.cn/models/iic/punc_ct-transformer_cn-en-common-vocab471067-large/summary) [🤗](https://huggingface.co/funasr/ct-punc) ) | punctuation restoration | 100M, Mandarin and English | 1.1G |
-| fsmn-vad <br> ( [⭐](https://modelscope.cn/models/iic/speech_fsmn_vad_zh-cn-16k-common-pytorch/summary) [🤗](https://huggingface.co/funasr/fsmn-vad) ) | voice activity detection | 5000 hours, Mandarin and English | 0.4M |
-| fa-zh <br> ( [⭐](https://modelscope.cn/models/damo/speech_timestamp_prediction-v1-16k-offline/summary) [🤗]() ) | timestamp prediction | 5000 hours, Mandarin | 38M |
+The [FunASR software license](../LICENSE) does not grant one license for every
+model weight. Consult the individual checkpoint's model card/license, publisher,
+training-data notes and the applicable [Model License Agreement](../MODEL_LICENSE).
+Keep upstream attribution when redistributing models or derived artifacts.
-### Third-party Unified Transcription and Diarization
+## Validation and next steps
-| Model Name | Task Details | Publisher | Parameters |
-|:----------:|:------------:|:---------:|:----------:|
-| [MOSS-Transcribe-Diarize](https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize) | Offline transcription, timestamps, and anonymous per-recording speaker labels in one request. It is not a realtime or known-person identification model. See the [deployment guide](../docs/moss_transcribe_diarize.md). | OpenMOSS | See official model card |
+- [Train or fine-tune a supported recipe](../docs/training.md).
+- [Register a custom model](../docs/model_registration.md).
+- [Choose native vLLM or split-engine](../docs/vllm_guide.md); preserve their distinct artifacts and API contracts.
+- [Deploy GGUF models with llama.cpp](../runtime/llama.cpp/README.md); an ONNX export is not a GGUF conversion.
+- [Measure quality and runtime separately](../docs/benchmark/rtf_reproducibility.md), using representative audio and exact versions.
diff --git a/model_zoo/readme_zh.md b/model_zoo/readme_zh.md
index 7cd98edf4..9cc02c776 100644
--- a/model_zoo/readme_zh.md
+++ b/model_zoo/readme_zh.md
@@ -1,32 +1,87 @@
-(简体中文|[English](./readme.md))
-
# 模型仓库
-## 模型许可协议
-您可以在本协议的条件下自由使用、复制、修改和分享FunASR模型。在使用、复制、修改和分享FunASR模型时,您应当标明模型来源和作者信息。您应当在[FunASR软件]中保留相关模型的名称。完整的模型许可证请参见 [模型许可协议](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE)
+简体中文 | [English](./readme.md)
+
+先分别确定**模型、权重格式和运行时**。出现在模型列表中,不代表该模型可被
+所有服务、导出工具或硬件后端直接使用。
+
+## 按任务选择
+
+| 任务 | 模型系列 | 关键边界 |
+| --- | --- | --- |
+| 需要上下文能力的文件转写 | [Fun-ASR-Nano](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512) | 原始 checkpoint 与原生 vLLM 转换版是不同产物。 |
+| 更广的多语言文件转写 | [Fun-ASR-MLT-Nano](https://huggingface.co/FunAudioLLM/Fun-ASR-MLT-Nano-2512) | 独立 checkpoint,不能把它的语言覆盖写成基础 Nano 的能力。 |
+| 带情感、音频事件标签的转写 | [SenseVoiceSmall](https://huggingface.co/FunAudioLLM/SenseVoiceSmall) | 标签不等于说话人身份;说话人感知流水线需按文档组合配套组件。 |
+| 中文转写与时间戳 | Paraformer | 离线模型与流式模型的推理契约不同。 |
+| 一次请求返回转写、时间戳和匿名说话人 | [MOSS-Transcribe-Diarize](https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize) | OpenMOSS 第三方模型;统一离线路径不需要外部 VAD 或说话人模型,不是已知人物识别。 |
+
+具体场景参见[模型选择](../docs/model_selection_zh.md),参数与返回值参见
+[SDK 参考](../docs/python_api_zh.md),服务路径参见[部署矩阵](../docs/deployment_matrix_zh.md)。
## 模型用法
-模型用法参考[文档](../runtime/quick_start_zh.md)
-## 模型仓库
-这里我们提供了在不同数据集上预训练的模型。模型和数据集的详细信息可在 [ModelScope](https://www.modelscope.cn/models?page=1&tasks=auto-speech-recognition)中找到.
+先完成[安装](../docs/installation/installation_zh.md)和
+[Python 教程](../docs/tutorial/README_zh.md)。显式选择 hub,并记录实际下载的
+checkpoint/revision、FunASR 版本、设备和推理选项。
+[模型别名映射](../funasr/download/name_maps_from_hub.py)提供便捷入口,
+但别名本身不是不可变的模型版本。
+
+```python
+from funasr import AutoModel
+
+model = AutoModel(model="paraformer-zh", hub="ms", device="cpu")
+result = model.generate(input="meeting.wav")
+print(result[0]["text"])
+```
+
+将 `meeting.wav` 替换为实际录音。下载、预热和推理耗时分开记录;
+验证时间戳、说话人标签和模型专有标签时,保留原始返回值。
-### 语音识别模型
-#### Paraformer模型
+## 语音识别模型
-(注:[🤗]()表示Huggingface模型仓库链接,[⭐]()表示ModelScope模型仓库链接)
+### Paraformer模型
+
+| SDK 别名 | 用途 | ModelScope (`hub="ms"`) | Hugging Face (`hub="hf"`) |
+| --- | --- | --- | --- |
+| `paraformer-zh` | 中文离线转写;ModelScope 别名指向 SeACo | [SeACo 权重](https://modelscope.cn/models/iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary) | [权重](https://huggingface.co/funasr/paraformer-zh) |
+| `paraformer-zh-streaming` | 带会话 cache 的分块流式推理 | [权重](https://modelscope.cn/models/iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online/summary) | [权重](https://huggingface.co/funasr/paraformer-zh-streaming) |
+| `paraformer-en` | 英文离线转写 | 通过 [hub 映射](../funasr/download/name_maps_from_hub.py)解析。 | 通过 hub 映射解析。 |
+
+旧版 [Paraformer VAD/标点组合](https://modelscope.cn/models/iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary)
+与 `paraformer-zh-spk` 描述的是组合流水线,不是 `paraformer-zh` 别名对应的权重。需要显式组合时,
+按照 [SDK 文档](../docs/python_api_zh.md)设置 `vad_model`、`punc_model`
+和 `spk_model`,不要把所有配套组件视为一个可互换的 ASR checkpoint。
+
+## 流水线组件
+
+| 组件 | 别名 | 模型卡 | 不包含的能力 |
+| --- | --- | --- | --- |
+| 语音活动检测 | `fsmn-vad` | [ModelScope](https://modelscope.cn/models/iic/speech_fsmn_vad_zh-cn-16k-common-pytorch/summary) / [HF](https://huggingface.co/funasr/fsmn-vad) | 不转写语音,也不识别人名。 |
+| 标点恢复 | `ct-punc` | [ModelScope](https://modelscope.cn/models/iic/punc_ct-transformer_cn-en-common-vocab471067-large/summary) / [HF](https://huggingface.co/funasr/ct-punc) | 不生成声学时间戳。 |
+| 说话人向量 | `cam++` | [hub 映射](../funasr/download/name_maps_from_hub.py) | 没有另行设计的注册与匹配系统时,不识别已知人物。 |
+| 时间戳预测 | `fa-zh` | [hub 映射](../funasr/download/name_maps_from_hub.py) | 需符合相应输入与模型路径,不代表所有识别器都支持时间戳。 |
+
+更多 checkpoint 见 [ModelScope 清单](./modelscope_models_zh.md)和
+[Hugging Face 清单](./huggingface_models.md)。清单保留部分历史模型,
+新部署前应核查对应模型卡。
+
+## 第三方统一转写与说话人分离
+
+MOSS-Transcribe-Diarize 由 **OpenMOSS** 发布,不是 FunASR 团队的自有模型。
+统一离线输出包含转写、时间戳和录音内匿名说话人标签;不是实时流式或已知人物身份识别。
+适配器、上游原生服务、显存要求与返回边界见
+[MOSS 部署指南](../docs/moss_transcribe_diarize_zh.md)。
+
+## 模型许可协议
-| 模型名字 | 任务详情 | 训练数据 | 参数量 |
-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------:|:------------:|:----:|
-| paraformer-zh <br> ([⭐](https://www.modelscope.cn/models/iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary) [🤗](https://huggingface.co/funasr/paraformer-zh) ) | 语音识别,带时间戳输出,非实时 | 60000小时,中文 | 220M |
-| SeACoParaformer-zh <br> ( [⭐](https://www.modelscope.cn/models/iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary) [🤗]() ) | 带热词功能的语音识别,带时间戳输出,非实时 | 60000小时,中文 | 220M |
-| paraformer-zh-spk <br> ( [⭐](https://modelscope.cn/models/damo/speech_paraformer-large-vad-punc-spk_asr_nat-zh-cn/summary) [🤗]() ) | 分角色语音识别,带时间戳输出,非实时 | 60000小时,中文 | 220M |
-| paraformer-zh-streaming <br> ( [⭐](https://modelscope.cn/models/iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online/summary) [🤗](https://huggingface.co/funasr/paraformer-zh-streaming) ) | 语音识别,实时 | 60000小时,中文 | 220M |
-| paraformer-zh-streaming-small <br> ( [⭐](https://www.modelscope.cn/models/iic/speech_paraformer_asr_nat-zh-cn-16k-common-vocab8404-online/summary) [🤗]() ) | 语音识别,实时 | 60000小时,中文 | 220M |
-| paraformer-en <br> ( [⭐](https://www.modelscope.cn/models/damo/speech_paraformer-large-vad-punc_asr_nat-en-16k-common-vocab10020/summary) [🤗]() ) | 语音识别,非实时 | 50000小时,英文 | 220M |
+[FunASR 软件许可证](../LICENSE)不等于所有模型权重使用同一许可证。
+请分别查看 checkpoint 的模型卡、许可证、发布方、训练数据说明,以及适用的
+[模型许可协议](../MODEL_LICENSE)。分发权重或派生产物时保留上游归属。
-### 第三方统一转写与说话人分离
+## 验证与下一步
-| 模型名字 | 任务详情 | 发布方 | 模型参数 |
-|:--------:|:--------:|:------:|:--------:|
-| [MOSS-Transcribe-Diarize](https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize) | 单次离线请求输出转写、时间戳和录音内匿名说话人标签;不是实时服务或已知人物身份识别。参见[部署指南](../docs/moss_transcribe_diarize_zh.md)。 | OpenMOSS | 以官方模型卡为准 |
+- [训练与微调](../docs/training_zh.md):选择仓库实际支持的配方。
+- [注册自定义模型](../docs/model_registration_zh.md)。
+- [原生 vLLM 与 split-engine](../docs/vllm_guide_zh.md):两条路径的权重和协议不能混用。
+- [llama.cpp / GGUF](../runtime/llama.cpp/README.md):ONNX 导出不等于 GGUF 转换。
+- [可复现评测](../docs/benchmark/rtf_reproducibility.md):分别记录质量、性能、硬件和版本。
diff --git a/runtime/docs/websocket_protocol.md b/runtime/docs/websocket_protocol.md
index 6eec215cd..023ce4b61 100644
--- a/runtime/docs/websocket_protocol.md
+++ b/runtime/docs/websocket_protocol.md
@@ -51,7 +51,7 @@ Parameter explanation:
## Real-time Speech Recognition
### System Architecture Diagram
-<div align="left"><img src="images/2pass.jpg" width="600"/></div>
+<div align="left"><img src="images/2pass.jpg" width="600" alt="Two-pass WebSocket transcription flow"/></div>
### Sending Data from Client to Server
#### Message Format
diff --git a/runtime/docs/websocket_protocol_zh.md b/runtime/docs/websocket_protocol_zh.md
index 2c16cd048..b6e1a17de 100644
--- a/runtime/docs/websocket_protocol_zh.md
+++ b/runtime/docs/websocket_protocol_zh.md
@@ -54,7 +54,7 @@ message为(采用json序列化)
## 实时语音识别
### 系统架构图
-<div align="left"><img src="images/2pass.jpg" width="600"/></div>
+<div align="left"><img src="images/2pass.jpg" width="600" alt="双遍 WebSocket 转写流程"/></div>
### 从客户端往服务端发送数据
#### 消息格式
diff --git a/runtime/readme.md b/runtime/readme.md
index 723c8c970..aecb2642a 100644
--- a/runtime/readme.md
+++ b/runtime/readme.md
@@ -1,120 +1,76 @@
-# FunASR Runtime Roadmap
-中文文档([点击此处](./readme_cn.md))
+# FunASR Runtime Deployment Guide
-Native ONNX Runtime JSONL transcript and timestamp output: [usage guide](./docs/onnxruntime_binary_output.md)
+[简体中文](./readme_cn.md) | English
-FunASR is a speech recognition framework developed by the Speech Lab of DAMO Academy, which integrates industrial-level models in the fields of speech endpoint detection, speech recognition, punctuation segmentation, and more.
-It has attracted many developers to participate in experiencing and developing. To solve the last mile of industrial landing and integrate models into business, we have developed the FunASR runtime-SDK. The SDK supports several service deployments, including:
+Select a model and protocol before selecting a container or binary. Start at the
+[deployment matrix](../docs/deployment_matrix.md) for versioned commands,
+tested hardware and known limits. Older release notes are preserved in
+[release history](./release-history.md); they are not a current capacity promise.
-- File transcription service, Mandarin, CPU version, done
-- The real-time transcription service, Mandarin (CPU), done
-- File transcription service, English, CPU version, done
-- File transcription service, Mandarin, GPU version, done
-- and more.
+## Choose a serving path
-## File Transcription Service, Mandarin (GPU)
-
-Currently, the FunASR runtime-SDK supports the deployment of file transcription service, Mandarin (GPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
-
-To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
-
-### Whats-new
-- 2024/09/26: File Transcription Service 2.0 GPU released, Fix GPU memory leak, docker image version funasr-runtime-sdk-gpu-0.2.0 (d280bf7e495b)
-- 2024/07/01: File Transcription Service 1.1 GPU released, optimize BladeDISC model compatibility issues, docker image version funasr-runtime-sdk-gpu-0.1.1 (8875cbf9b99e)
-- 2024/06/27: File Transcription Service 1.0 GPU released, supporting dynamic batch processing and multi-threading concurrency. In the long audio test set, the single-thread RTF is 0.0076, and multi-threads' speedup is 1200+ (compared to 330+ on CPU), ref to([docs](./docs/benchmark_libtorch_cpp.md)) , docker image version funasr-runtime-sdk-gpu-0.1.0 (b86066f4d018)
+| Need | Entry point | Boundary |
+| --- | --- | --- |
+| Python HTTP transcription | [OpenAI-compatible server](../examples/openai_api/README.md) | Application API compatibility is separate from model accuracy or realtime support. |
+| Fun-ASR-Nano decoder acceleration | [vLLM guide](../docs/vllm_guide.md) | Native vLLM and FunASR split-engine have different checkpoint/layout and API contracts. |
+| Local portable GGUF inference | [llama.cpp](./llama.cpp/README.md) | Use the platform/backend package and matching GGUF model; build success is not every-device validation. |
+| Native ONNX CPU inference | [ONNX Runtime](./onnxruntime/readme.md) | See the [JSONL/timestamp output contract](./docs/onnxruntime_binary_output.md). |
+| Offline unified transcription and diarization | [MOSS-Transcribe-Diarize](../docs/moss_transcribe_diarize.md) | Third-party OpenMOSS model; offline anonymous speaker labels, not realtime or known-person identity. |
+| Long-lived streaming or two-pass sessions | [C++ WebSocket protocol](./docs/websocket_protocol.md) | Do not send OpenAI HTTP requests or another runtime's WebSocket messages to this endpoint. |
+| Cluster-managed private HTTP service | [Kubernetes templates](../examples/openai_api/kubernetes/README.md) | Configure resources, persistent cache, probes, upload limits and gateway policy for the target cluster. |
-### Advanced Development Guide
-
-The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline_gpu.md)
+## File Transcription Service, Mandarin (GPU)
+Follow the [GPU development guide](./docs/SDK_advanced_guide_offline_gpu.md).
+The guide covers the native runtime stack; it is not an installation recipe for
+every model in the Model Zoo. Benchmark your exact image, weights and GPU.
## File Transcription Service, English (CPU)
-Currently, the FunASR runtime-SDK supports the deployment of file transcription service, English (CPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
-
-To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
-
-### Whats-new
-- 2024/09/26: Fix memory leak, docker image version funasr-runtime-sdk-en-cpu-0.1.7 (f6c5a7b59eb6).
-- 2024/05/15: Adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-en-cpu-0.1.6 (84d781d07997).
-- 2024/03/05: docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-en-cpu-0.1.5 (7cca2abc5901).
-- 2024/01/25: Optimized the VAD (Voice Activity Detection) data processing method,significantly reducing peak memory usage,memory leak optimization, docker image version funasr-runtime-sdk-en-cpu-0.1.3 (c00f9ce7a195).
-- 2024/01/03: Fixed known crash issues as well as memory leak problems, docker image version funasr-runtime-sdk-en-cpu-0.1.2 (0cdd9f4a4bb5).
-- 2023/11/08: Adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-en-cpu-0.1.1 (27017f70f72a).
-- 2023/10/16: English File Transcription Service 1.0 released, docker image version funasr-runtime-sdk-en-cpu-0.1.0 (e0de03eb0163), refer to the detailed documentation([here](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A))
-
-### Technical Principles
-
-The technical principles and documentation behind FunASR explain the underlying technology, recognition accuracy, computational efficiency, and core advantages of the framework, including convenience, high precision, high efficiency, and support for long audio chains. For detailed information, please refer to the documentation available by [docs](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A).
-
-### Deployment Tutorial
-
-The documentation mainly targets novice users who have no need for modifications or customization. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed tutorials, please refer to [docs](docs/SDK_tutorial_en.md).
-
-### Advanced Development Guide
+Use the [English tutorial](./docs/SDK_tutorial_en.md) and
+[advanced configuration](./docs/SDK_advanced_guide_offline_en.md).
+Select the English checkpoint rather than inferring language coverage from the
+container name alone.
-The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline_en.md)
-
-
-## The real-time transcription service, Mandarin (CPU)
-
-The FunASR real-time speech-to-text service software package not only performs real-time speech-to-text conversion, but also allows high-precision transcription text correction at the end of each sentence and outputs text with punctuation, supporting high-concurrency multiple requests.
-In order to meet the needs of different users for different scenarios, different tutorials are prepared:
-
-### Whats-new+
-- 2024/10/29: Real-time Transcription Service 1.12 released,The 2pass-offline mode supports the SensevoiceSmal model, docker image version funasr-runtime-sdk-online-cpu-0.1.12 (f5febc5cf13a)
-- 2024/09/26: Real-time Transcription Service 1.11 released,Fix memory leak, docker image version funasr-runtime-sdk-online-cpu-0.1.11 (e51a36c42771)
-- 2024/05/15: Real-time Transcription Service 1.10 released,adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-online-cpu-0.1.10 (1c2adfcff84d)
-- 2024/03/05: Real-time Transcription Service 1.9 released,docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-online-cpu-0.1.9 (4a875e08c7a2)
-- 2024/01/25: Real-time Transcription Service 1.7 released,optimization of the client-side, docker image version funasr-runtime-sdk-online-cpu-0.1.7 (2aa23805572e)
-- 2024/01/03: Real-time Transcription Service 1.6 released,The 2pass-offline mode supports Ngram language model decoding and WFST hotwords, while also addressing known crash issues and memory leak problems, docker image version funasr-runtime-sdk-online-cpu-0.1.6 (f99925110d27)
-- 2023/11/09: Real-time Transcription Service 1.5 released,fix bug: without online results, docker image version funasr-runtime-sdk-online-cpu-0.1.5 (b16584b6d38b)
-- 2023/11/08: Real-time Transcription Service 1.4 released, supporting server-side loading of hotwords (updated hotword communication protocol), adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-online-cpu-0.1.4(691974017c38).
-- 2023/09/19: Real-time Transcription Service 1.2 released, supporting hotwords, timestamps, and ITN model in 2pass mode, docker image version funasr-runtime-sdk-online-cpu-0.1.2 (7222c5319bcf).
-- 2023/08/11: Real-time Transcription Service 1.1 released, addressing some known bugs (including server crashes), docker image version funasr-runtime-sdk-online-cpu-0.1.1 (bdbdd0b27dee).
-- 2023/08/07: Real-time Transcription Service 1.0 released, docker image version funasr-runtime-sdk-online-cpu-0.1.0(bdbdd0b27dee), refer to the detailed documentation([here](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w))
-
-### Convenient Deployment Tutorial
-
-This is suitable for scenarios where there is no need to modify the service deployment SDK and the deployed model comes from ModelScope or is finetuned by the user. For detailed tutorials, please refer to [docs](./docs/SDK_tutorial_online.md)
-
-
-### Development Guide
-
-This is suitable for scenarios where there is a need to modify the service deployment SDK and the deployed model comes from ModelScope or is finetuned by the user. For detailed documentation, please refer to [docs](./docs/SDK_advanced_guide_online.md)
-
-### Technology Principles Revealed
-
-The document introduces the technology principles behind the service, recognition accuracy, computing efficiency, and core advantages: convenience, high precision, high efficiency, and long audio chain. For detailed documentation, please refer to [docs](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w).
+## Real-time Transcription Service, Mandarin (CPU)
+Use the [streaming tutorial](./docs/SDK_tutorial_online.md), then verify the
+[protocol](./docs/websocket_protocol.md) and
+[matching multi-client example](./python/websocket/README.md).
+Validate sample rate, chunking, finalization, reconnect behavior and session
+isolation with actual audio. C++ two-pass and Fun-ASR-Nano Python streaming are
+different implementations. The separate [Nano realtime benchmark](../docs/benchmark/realtime_ws_benchmark.md)
+uses Nano's `START`/`STOP` protocol and must not be used against the C++ endpoint.
## File Transcription Service, Mandarin (CPU)
-Currently, the FunASR runtime-SDK supports the deployment of file transcription service, Mandarin (CPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
-
-To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
-
-### Whats-new
-- 2024/09/26: File Transcription Service 4.6 released, Fix memory leak & Support the SensevoiceSmall onnx model, docker image version funasr-runtime-sdk-cpu-0.4.6 (8651c6b8a1ae)
-- 2024/05/15: File Transcription Service 4.5 released, adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-cpu-0.4.5 (058b9882ae67)
-- 2024/03/05: File Transcription Service 4.4 released, docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-cpu-0.4.4 (2dc87b86dc49)
-- 2024/01/25: File Transcription Service 4.2 released, optimized the VAD (Voice Activity Detection) data processing method, significantly reducing peak memory usage, memory leak optimization, docker image version funasr-runtime-sdk-cpu-0.4.2 (befdc7b179ed)
-- 2024/01/08: File Transcription Service 4.1 released, optimized format sentence-level timestamps, docker image version funasr-runtime-sdk-cpu-0.4.1 (0250f8ef981b)
-- 2024/01/03: File Transcription Service 4.0 released, Added support for 8k models, optimized timestamp mismatch issues and added sentence-level timestamps, improved the effectiveness of English word FST hotwords, supported automated configuration of thread parameters, and fixed known crash issues as well as memory leak problems, docker image version funasr-runtime-sdk-cpu-0.4.0 (c4483ee08f04)
-- 2023/11/08: File Transcription Service 3.0 released, supporting punctuation large model, Ngram model, fst hotwords (updated hotword communication protocol), server-side loading of hotwords, adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-cpu-0.3.0 (caa64bddbb43), refer to the detailed documentation ([here]())
-- 2023/09/19: File Transcription Service 2.2 released, supporting ITN model, docker image version funasr-runtime-sdk-cpu-0.2.2 (2c5286be13e9).
-- 2023/08/22: File Transcription Service 2.0 released, integrated ffmpeg to support various audio and video inputs, supporting hotword model and timestamp model, docker image version funasr-runtime-sdk-cpu-0.2.0 (1ad3d19e0707), refer to the detailed documentation ([here](https://mp.weixin.qq.com/s/oJHe0MKDqTeuIFH-F7GHMg))
-- 2023/07/03: File Transcription Service 1.0 released, docker image version funasr-runtime-sdk-cpu-0.1.0 (1ad3d19e0707), refer to the detailed documentation ([here](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww))
+Use the [offline tutorial](./docs/SDK_tutorial.md) and
+[advanced configuration](./docs/SDK_advanced_guide_offline.md).
+[Model selection](../docs/model_selection.md) explains when Paraformer,
+SenseVoice or a different recognizer fits the workload.
-### Technical Principles
+## Client and platform adapters
-The technical principles and documentation behind FunASR explain the underlying technology, recognition accuracy, computational efficiency, and core advantages of the framework, including convenience, high precision, high efficiency, and support for long audio chains. For detailed information, please refer to the documentation available by [docs](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww).
+- [Python WebSocket](./python/websocket/README.md), [Python HTTP](./python/http/README.md), [Java](./java/readme.md), [Go](./golang/websocket/readme.md).
+- [Browser client](./html5/readme.md), [gRPC](./grpc/Readme.md), [Triton](./triton_gpu/README.md).
+- [Android](./android/readme.md) and [iOS](./ios/Readme.md) are separate porting guides, not a guarantee that each desktop release supports those devices.
-### Deployment Tutorial
+Follow each adapter's protocol and dependency instructions. An SDK example is
+not automatically a supported production package for every target platform.
-The documentation mainly targets novice users who have no need for modifications or customization. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed tutorials, please refer to [docs](docs/SDK_tutorial.md).
+## Production checklist
-### Advanced Development Guide
+1. Record the exact commit/image digest, model revision, configuration and target hardware.
+2. Run a known-audio transcription and inspect the raw output, not only a health endpoint.
+3. Measure representative quality, latency, concurrency, memory and failure behavior.
+4. Add authentication, TLS, request limits and privacy controls using the
+ [security guide](../examples/openai_api/SECURITY.md).
+5. Preserve the previous model/artifact/configuration and exercise rollback.
+6. Report unresolved failures with the [troubleshooting checklist](../docs/troubleshooting.md);
+ published code is not proof that a reporter's hardware issue is resolved.
-The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline.md)
+## Historical releases
+The [full release history](./release-history.md) preserves earlier Docker tags,
+dates and benchmark references. For a new deployment, use a current
+[deployment manual](https://www.funasr.com/en/deploy/) and its explicit test boundary.
diff --git a/runtime/readme_cn.md b/runtime/readme_cn.md
index e6c4745b3..1afa80001 100644
--- a/runtime/readme_cn.md
+++ b/runtime/readme_cn.md
@@ -1,98 +1,70 @@
-# FunASR软件包路线图
+# FunASR 运行时部署指南
-English Version([docs](./readme.md))
+简体中文 | [English](./readme.md)
-原生 ONNX Runtime JSONL 转写与时间戳输出:[使用文档](./docs/onnxruntime_binary_output_zh.md)
+先确定模型和协议,再选择容器或二进制包。[部署矩阵](../docs/deployment_matrix_zh.md)
+给出固定版本命令、验证硬件和已知限制。旧发布说明保留在
+[历史记录](./release-history_zh.md),不能直接作为当前服务容量承诺。
-FunASR是由阿里巴巴通义实验室语音团队开源的一款语音识别基础框架,集成了语音端点检测、语音识别、标点断句等领域的工业级别模型,吸引了众多开发者参与体验和开发。为了解决工业落地的最后一公里,将模型集成到业务中去,我们开发了社区软件包。
-支持以下几种服务部署:
+## 选择服务路径
-<img src="docs/images/sdk_roadmap.jpg" width="900"/>
-
-- 中文离线文件转写服务(CPU版本),已完成
-- 中文流式语音识别服务(CPU版本),已完成
-- 英文离线文件转写服务(CPU版本),已完成
-- 中文离线文件转写服务(GPU版本),已完成
-- 更多支持中
+| 需求 | 入口 | 边界 |
+| --- | --- | --- |
+| Python HTTP 转写 | [OpenAI 兼容服务](../examples/openai_api/README_zh.md) | API 兼容、模型质量和实时能力是不同问题。 |
+| Fun-ASR-Nano 解码加速 | [vLLM 指南](../docs/vllm_guide_zh.md) | 原生 vLLM 与 FunASR split-engine 的权重布局和接口契约不同。 |
+| 本地便携 GGUF 推理 | [llama.cpp](./llama.cpp/README.md) | 使用匹配的平台/后端包和 GGUF 模型;构建成功不等于所有设备验证通过。 |
+| 原生 ONNX CPU 推理 | [ONNX Runtime](./onnxruntime/readme.md) | 输出字段见 [JSONL 与时间戳契约](./docs/onnxruntime_binary_output_zh.md)。 |
+| 统一离线转写与说话人分离 | [MOSS-Transcribe-Diarize](../docs/moss_transcribe_diarize_zh.md) | OpenMOSS 第三方模型,输出匿名说话人标签,不是实时或已知人物身份识别。 |
+| 长连接流式 / 双遍会话 | [C++ WebSocket 协议](./docs/websocket_protocol_zh.md) | 不能向该端点发送 OpenAI HTTP 请求或其他实现的 WebSocket 消息。 |
+| 集群内私有 HTTP 服务 | [Kubernetes 模板](../examples/openai_api/kubernetes/README_zh.md) | 按目标集群配置资源、持久缓存、探针、上传限制和网关策略。 |
## 中文离线文件转写服务(GPU版本)
-中文语音离线文件服务部署(GPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持多路请求同时进行转写。
-为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
-
-### 最新动态
-- 2024/09/26: 中文离线文件转写服务GPU 2.0 发布,修复显存泄漏,docker镜像版本funasr-runtime-sdk-gpu-0.2.0 (d280bf7e495b)
-- 2024/07/01: 中文离线文件转写服务GPU 1.1 发布,优化bladedisc模型兼容性问题,docker镜像版本funasr-runtime-sdk-gpu-0.1.1 (8875cbf9b99e)
-- 2024/06/27: 中文离线文件转写服务GPU 1.0 发布,支持动态batch,支持多路并发,在长音频测试集上单线RTF为0.0076,多线加速比为1200+(CPU为330+),详见([文档](./docs/benchmark_libtorch_cpp.md)),docker镜像版本funasr-runtime-sdk-gpu-0.1.0 (b86066f4d018)
-
-### 部署与开发文档
-
-部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_gpu_zh.md))
-
+按 [GPU 部署开发指南](./docs/SDK_advanced_guide_offline_gpu_zh.md)配置原生运行时。
+它不是 Model Zoo 中每个模型的通用安装方法;需要用实际镜像、权重和 GPU 复测。
## 英文离线文件转写服务(CPU版本)
-英文离线文件转写服务部署(CPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持上百路请求同时进行转写。
-为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
-
-### 最新动态
-- 2024/09/26: 英文离线文件转写服务 1.7 发布,修复内存泄漏,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.7 (f6c5a7b59eb6)
-- 2024/05/15: 英文离线文件转写服务 1.6 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.6 (84d781d07997)
-- 2024/03/05: 英文离线文件转写服务 1.5 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.5 (7cca2abc5901)
-- 2024/01/25: 英文离线文件转写服务 1.3 发布,优化vad数据处理方式,大幅降低峰值内存占用,内存泄漏优化,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.3 (c00f9ce7a195)
-- 2024/01/03: 英文离线文件转写服务 1.2 发布,修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.2 (0cdd9f4a4bb5)
-- 2023/11/08: 英文离线文件转写服务 1.1 发布,runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-en-cpu-0.1.1 (27017f70f72a)
-- 2023/10/16: 英文离线文件转写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.0 (e0de03eb0163),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A))
-
-
-### 部署与开发文档
-
-部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_en_zh.md))
-
+参见[英文服务教程](./docs/SDK_tutorial_en.md)和
+[高级配置](./docs/SDK_advanced_guide_offline_en.md)。
+显式选择英文权重,不要只凭容器名推断语言覆盖。
## 中文实时语音听写服务(CPU版本)
-FunASR实时语音听写服务软件包,既可以实时地进行语音转文字,而且能够在说话句尾用高精度的转写文字修正输出,输出文字带有标点,支持高并发多路请求。
-为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
-
-### 最新动态
-- 2024/10/29: 中文实时语音听写服务 1.12 发布,2pass-offline模式支持SensevoiceSmall模型,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.12 (f5febc5cf13a)
-- 2024/09/26: 中文实时语音听写服务 1.11 发布,修复内存泄漏,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.11 (e51a36c42771)
-- 2024/05/15: 中文实时语音听写服务 1.10 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.10 (1c2adfcff84d)
-- 2024/03/05: 中文实时语音听写服务 1.9 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.9 (4a875e08c7a2)
-- 2024/01/25: 中文实时语音听写服务 1.7 发布,客户端优化,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.7 (2aa23805572e)
-- 2024/01/03: 中文实时语音听写服务 1.6 发布,2pass-offline模式支持Ngram语言模型解码、wfst热词,同时修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.6 (f99925110d27)
-- 2023/11/09: 中文实时语音听写服务 1.5 发布,修复无实时结果的问题,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.5 (b16584b6d38b)
-- 2023/11/08: 中文实时语音听写服务 1.4 发布,支持服务端加载热词(更新热词通信协议)、runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-online-cpu-0.1.4 (691974017c38)
-- 2023/09/19: 中文实时语音听写服务 1.2 发布,2pass模式支持热词、时间戳、ITN模型,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.2 (7222c5319bcf)
-- 2023/08/11: 中文实时语音听写服务 1.1 发布,修复了部分已知的bug(包括server崩溃等),docker镜像版本funasr-runtime-sdk-online-cpu-0.1.1 (bdbdd0b27dee)
-- 2023/08/07: 中文实时语音听写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.0 (bdbdd0b27dee),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w))
-
-### 部署与开发文档
-
-部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_online_zh.md))
+先运行[流式教程](./docs/SDK_tutorial_online_zh.md),再按
+[协议](./docs/websocket_protocol_zh.md)与
+[对应的多客户端示例](./python/websocket/README.md)验证。
+重点检查采样率、音频分块、结束消息、重连和不同会话之间的状态隔离。
+C++ 双遍服务与 Fun-ASR-Nano Python 流式服务是不同实现。
+另一个 [Nano 实时压测工具](../docs/benchmark/realtime_ws_benchmark.md)使用
+Nano 的 `START`/`STOP` 协议,不能对 C++ 服务使用。
+## 中文离线文件转写服务(CPU版本)
+参见[离线教程](./docs/SDK_tutorial_zh.md)和
+[高级配置](./docs/SDK_advanced_guide_offline_zh.md)。
+Paraformer、SenseVoice 等模型的选择边界见[模型选择](../docs/model_selection_zh.md)。
-## 中文离线文件转写服务(CPU版本)
+## 客户端与平台适配
-中文语音离线文件服务部署(CPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持上百路请求同时进行转写。
-为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
+- [Python WebSocket](./python/websocket/README.md)、[Python HTTP](./python/http/README.md)、[Java](./java/readme.md)、[Go](./golang/websocket/readme.md)。
+- [浏览器客户端](./html5/readme_zh.md)、[gRPC](./grpc/Readme.md)、[Triton](./triton_gpu/README.md)。
+- [Android](./android/readme.md) 与 [iOS](./ios/Readme.md) 是独立移植指南,
+ 不代表每个桌面发布包都验证过这些设备。
-### 最新动态
-- 2024/09/26: 中文离线文件转写服务 4.6 发布,修复内存泄漏、支持SensevoiceSmall onnx模型,docker镜像版本funasr-runtime-sdk-cpu-0.4.6 (8651c6b8a1ae)
-- 2024/05/15: 中文离线文件转写服务 4.5 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-cpu-0.4.5 (058b9882ae67)
-- 2024/03/05: 中文离线文件转写服务 4.4 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-cpu-0.4.4 (2dc87b86dc49)
-- 2024/01/25: 中文离线文件转写服务 4.2 发布,优化vad数据处理方式,大幅降低峰值内存占用,内存泄漏优化,docker镜像版本funasr-runtime-sdk-cpu-0.4.2 (befdc7b179ed)
-- 2024/01/08: 中文离线文件转写服务 4.1 发布,优化句子级时间戳json格式,docker镜像版本funasr-runtime-sdk-cpu-0.4.1 (0250f8ef981b)
-- 2024/01/03: 中文离线文件转写服务 4.0 发布,新增支持8k模型、优化时间戳不匹配问题及增加句子级别时间戳、优化英文单词fst热词效果、支持自动化配置线程参数,同时修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-cpu-0.4.0 (c4483ee08f04)
-- 2023/11/08: 中文离线文件转写服务 3.0 发布,支持标点大模型、支持Ngram模型、支持fst热词(更新热词通信协议)、支持服务端加载热词、runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-cpu-0.3.0 (caa64bddbb43),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/jSbnKw_m31BUUbTukPSOIw))
-- 2023/09/19: 中文离线文件转写服务 2.2 发布,支持ITN模型,docker镜像版本funasr-runtime-sdk-cpu-0.2.2 (2c5286be13e9)
-- 2023/08/22: 中文离线文件转写服务 2.0 发布,集成ffmpeg支持多种音视频输入、支持热词模型、支持时间戳模型,docker镜像版本funasr-runtime-sdk-cpu-0.2.0 (1ad3d19e0707),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/oJHe0MKDqTeuIFH-F7GHMg))
-- 2023/07/03: 中文离线文件转写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-cpu-0.1.0 (1ad3d19e0707),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww))
+不同适配器的协议和依赖以各自文档为准,示例代码不自动等于所有目标平台的生产支持。
-### 部署与开发文档
+## 上线检查清单
-部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_zh.md))
+1. 固定代码 commit / 镜像 digest、模型 revision、配置与目标硬件。
+2. 用已知音频检查真实转写和原始返回值,不只检查 health 端点。
+3. 分别评测业务音频质量、延迟、并发、内存与失败行为。
+4. 依据[安全指南](../examples/openai_api/SECURITY_zh.md)配置认证、TLS、请求限制和隐私控制。
+5. 保留上一版模型、产物和配置,并实际演练回滚。
+6. 按[排障清单](../docs/troubleshooting_zh.md)提交未解决问题;
+ 代码发布不能证明用户报告的硬件问题已经解决。
+## 历史发布记录
+[完整历史记录](./release-history_zh.md)保留早期 Docker 标签、日期和性能评测引用。
+新部署以当前[部署手册](https://www.funasr.com/deploy/)和明确的验证边界为准。
diff --git a/runtime/release-history.md b/runtime/release-history.md
new file mode 100644
index 000000000..be4188164
--- /dev/null
+++ b/runtime/release-history.md
@@ -0,0 +1,125 @@
+# Historical Runtime Release Notes
+
+Archived from the former runtime landing page. Dates, image tags and performance
+figures below describe historical releases, not current deployment guarantees.
+For new deployments use the [runtime guide](./readme.md).
+
+# FunASR Runtime Roadmap
+中文文档([点击此处](./readme_cn.md))
+
+Native ONNX Runtime JSONL transcript and timestamp output: [usage guide](./docs/onnxruntime_binary_output.md)
+
+FunASR is a speech recognition framework developed by the Speech Lab of DAMO Academy, which integrates industrial-level models in the fields of speech endpoint detection, speech recognition, punctuation segmentation, and more.
+It has attracted many developers to participate in experiencing and developing. To solve the last mile of industrial landing and integrate models into business, we have developed the FunASR runtime-SDK. The SDK supports several service deployments, including:
+
+- File transcription service, Mandarin, CPU version, done
+- The real-time transcription service, Mandarin (CPU), done
+- File transcription service, English, CPU version, done
+- File transcription service, Mandarin, GPU version, done
+- and more.
+
+## File Transcription Service, Mandarin (GPU)
+
+Currently, the FunASR runtime-SDK supports the deployment of file transcription service, Mandarin (GPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
+
+To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
+
+### Whats-new
+- 2024/09/26: File Transcription Service 2.0 GPU released, Fix GPU memory leak, docker image version funasr-runtime-sdk-gpu-0.2.0 (d280bf7e495b)
+- 2024/07/01: File Transcription Service 1.1 GPU released, optimize BladeDISC model compatibility issues, docker image version funasr-runtime-sdk-gpu-0.1.1 (8875cbf9b99e)
+- 2024/06/27: File Transcription Service 1.0 GPU released, supporting dynamic batch processing and multi-threading concurrency. In the long audio test set, the single-thread RTF is 0.0076, and multi-threads' speedup is 1200+ (compared to 330+ on CPU), ref to([docs](./docs/benchmark_libtorch_cpp.md)) , docker image version funasr-runtime-sdk-gpu-0.1.0 (b86066f4d018)
+
+### Advanced Development Guide
+
+The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline_gpu.md)
+
+
+## File Transcription Service, English (CPU)
+
+Currently, the FunASR runtime-SDK supports the deployment of file transcription service, English (CPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
+
+To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
+
+### Whats-new
+- 2024/09/26: Fix memory leak, docker image version funasr-runtime-sdk-en-cpu-0.1.7 (f6c5a7b59eb6).
+- 2024/05/15: Adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-en-cpu-0.1.6 (84d781d07997).
+- 2024/03/05: docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-en-cpu-0.1.5 (7cca2abc5901).
+- 2024/01/25: Optimized the VAD (Voice Activity Detection) data processing method,significantly reducing peak memory usage,memory leak optimization, docker image version funasr-runtime-sdk-en-cpu-0.1.3 (c00f9ce7a195).
+- 2024/01/03: Fixed known crash issues as well as memory leak problems, docker image version funasr-runtime-sdk-en-cpu-0.1.2 (0cdd9f4a4bb5).
+- 2023/11/08: Adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-en-cpu-0.1.1 (27017f70f72a).
+- 2023/10/16: English File Transcription Service 1.0 released, docker image version funasr-runtime-sdk-en-cpu-0.1.0 (e0de03eb0163), refer to the detailed documentation([here](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A))
+
+### Technical Principles
+
+The technical principles and documentation behind FunASR explain the underlying technology, recognition accuracy, computational efficiency, and core advantages of the framework, including convenience, high precision, high efficiency, and support for long audio chains. For detailed information, please refer to the documentation available by [docs](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A).
+
+### Deployment Tutorial
+
+The documentation mainly targets novice users who have no need for modifications or customization. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed tutorials, please refer to [docs](docs/SDK_tutorial_en.md).
+
+### Advanced Development Guide
+
+The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline_en.md)
+
+
+## The real-time transcription service, Mandarin (CPU)
+
+The FunASR real-time speech-to-text service software package not only performs real-time speech-to-text conversion, but also allows high-precision transcription text correction at the end of each sentence and outputs text with punctuation, supporting high-concurrency multiple requests.
+In order to meet the needs of different users for different scenarios, different tutorials are prepared:
+
+### Whats-new+
+- 2024/10/29: Real-time Transcription Service 1.12 released,The 2pass-offline mode supports the SensevoiceSmal model, docker image version funasr-runtime-sdk-online-cpu-0.1.12 (f5febc5cf13a)
+- 2024/09/26: Real-time Transcription Service 1.11 released,Fix memory leak, docker image version funasr-runtime-sdk-online-cpu-0.1.11 (e51a36c42771)
+- 2024/05/15: Real-time Transcription Service 1.10 released,adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-online-cpu-0.1.10 (1c2adfcff84d)
+- 2024/03/05: Real-time Transcription Service 1.9 released,docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-online-cpu-0.1.9 (4a875e08c7a2)
+- 2024/01/25: Real-time Transcription Service 1.7 released,optimization of the client-side, docker image version funasr-runtime-sdk-online-cpu-0.1.7 (2aa23805572e)
+- 2024/01/03: Real-time Transcription Service 1.6 released,The 2pass-offline mode supports Ngram language model decoding and WFST hotwords, while also addressing known crash issues and memory leak problems, docker image version funasr-runtime-sdk-online-cpu-0.1.6 (f99925110d27)
+- 2023/11/09: Real-time Transcription Service 1.5 released,fix bug: without online results, docker image version funasr-runtime-sdk-online-cpu-0.1.5 (b16584b6d38b)
+- 2023/11/08: Real-time Transcription Service 1.4 released, supporting server-side loading of hotwords (updated hotword communication protocol), adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-online-cpu-0.1.4(691974017c38).
+- 2023/09/19: Real-time Transcription Service 1.2 released, supporting hotwords, timestamps, and ITN model in 2pass mode, docker image version funasr-runtime-sdk-online-cpu-0.1.2 (7222c5319bcf).
+- 2023/08/11: Real-time Transcription Service 1.1 released, addressing some known bugs (including server crashes), docker image version funasr-runtime-sdk-online-cpu-0.1.1 (bdbdd0b27dee).
+- 2023/08/07: Real-time Transcription Service 1.0 released, docker image version funasr-runtime-sdk-online-cpu-0.1.0(bdbdd0b27dee), refer to the detailed documentation([here](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w))
+
+### Convenient Deployment Tutorial
+
+This is suitable for scenarios where there is no need to modify the service deployment SDK and the deployed model comes from ModelScope or is finetuned by the user. For detailed tutorials, please refer to [docs](./docs/SDK_tutorial_online.md)
+
+
+### Development Guide
+
+This is suitable for scenarios where there is a need to modify the service deployment SDK and the deployed model comes from ModelScope or is finetuned by the user. For detailed documentation, please refer to [docs](./docs/SDK_advanced_guide_online.md)
+
+### Technology Principles Revealed
+
+The document introduces the technology principles behind the service, recognition accuracy, computing efficiency, and core advantages: convenience, high precision, high efficiency, and long audio chain. For detailed documentation, please refer to [docs](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w).
+
+
+## File Transcription Service, Mandarin (CPU)
+
+Currently, the FunASR runtime-SDK supports the deployment of file transcription service, Mandarin (CPU version), with a complete speech recognition chain that can transcribe tens of hours of audio into punctuated text, and supports recognition for more than a hundred concurrent streams.
+
+To meet the needs of different users, we have prepared different tutorials with text and images for both novice and advanced developers.
+
+### Whats-new
+- 2024/09/26: File Transcription Service 4.6 released, Fix memory leak & Support the SensevoiceSmall onnx model, docker image version funasr-runtime-sdk-cpu-0.4.6 (8651c6b8a1ae)
+- 2024/05/15: File Transcription Service 4.5 released, adapting to FunASR 1.0 model structure, docker image version funasr-runtime-sdk-cpu-0.4.5 (058b9882ae67)
+- 2024/03/05: File Transcription Service 4.4 released, docker image supports ARM64 platform, update modelscope, docker image version funasr-runtime-sdk-cpu-0.4.4 (2dc87b86dc49)
+- 2024/01/25: File Transcription Service 4.2 released, optimized the VAD (Voice Activity Detection) data processing method, significantly reducing peak memory usage, memory leak optimization, docker image version funasr-runtime-sdk-cpu-0.4.2 (befdc7b179ed)
+- 2024/01/08: File Transcription Service 4.1 released, optimized format sentence-level timestamps, docker image version funasr-runtime-sdk-cpu-0.4.1 (0250f8ef981b)
+- 2024/01/03: File Transcription Service 4.0 released, Added support for 8k models, optimized timestamp mismatch issues and added sentence-level timestamps, improved the effectiveness of English word FST hotwords, supported automated configuration of thread parameters, and fixed known crash issues as well as memory leak problems, docker image version funasr-runtime-sdk-cpu-0.4.0 (c4483ee08f04)
+- 2023/11/08: File Transcription Service 3.0 released, supporting punctuation large model, Ngram model, fst hotwords (updated hotword communication protocol), server-side loading of hotwords, adaptation to runtime structure changes (FunASR/funasr/runtime -> FunASR/runtime), docker image version funasr-runtime-sdk-cpu-0.3.0 (caa64bddbb43), refer to the detailed documentation ([here]())
+- 2023/09/19: File Transcription Service 2.2 released, supporting ITN model, docker image version funasr-runtime-sdk-cpu-0.2.2 (2c5286be13e9).
+- 2023/08/22: File Transcription Service 2.0 released, integrated ffmpeg to support various audio and video inputs, supporting hotword model and timestamp model, docker image version funasr-runtime-sdk-cpu-0.2.0 (1ad3d19e0707), refer to the detailed documentation ([here](https://mp.weixin.qq.com/s/oJHe0MKDqTeuIFH-F7GHMg))
+- 2023/07/03: File Transcription Service 1.0 released, docker image version funasr-runtime-sdk-cpu-0.1.0 (1ad3d19e0707), refer to the detailed documentation ([here](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww))
+
+### Technical Principles
+
+The technical principles and documentation behind FunASR explain the underlying technology, recognition accuracy, computational efficiency, and core advantages of the framework, including convenience, high precision, high efficiency, and support for long audio chains. For detailed information, please refer to the documentation available by [docs](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww).
+
+### Deployment Tutorial
+
+The documentation mainly targets novice users who have no need for modifications or customization. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed tutorials, please refer to [docs](docs/SDK_tutorial.md).
+
+### Advanced Development Guide
+
+The documentation mainly targets advanced developers who require modifications and customization of the service. It supports downloading model deployments from modelscope and also supports deploying models that users have fine-tuned. For detailed information, please refer to the documentation available by [docs](./docs/SDK_advanced_guide_offline.md)
diff --git a/runtime/release-history_zh.md b/runtime/release-history_zh.md
new file mode 100644
index 000000000..972be5905
--- /dev/null
+++ b/runtime/release-history_zh.md
@@ -0,0 +1,101 @@
+# 运行时历史发布记录
+
+从原运行时首页归档。以下日期、镜像标签和性能数字属于历史发布记录,
+不是当前部署保证。新部署请使用[运行时指南](./readme_cn.md)。
+
+# FunASR软件包路线图
+
+English Version([docs](./readme.md))
+
+原生 ONNX Runtime JSONL 转写与时间戳输出:[使用文档](./docs/onnxruntime_binary_output_zh.md)
+
+FunASR是由阿里巴巴通义实验室语音团队开源的一款语音识别基础框架,集成了语音端点检测、语音识别、标点断句等领域的工业级别模型,吸引了众多开发者参与体验和开发。为了解决工业落地的最后一公里,将模型集成到业务中去,我们开发了社区软件包。
+支持以下几种服务部署:
+
+<img src="docs/images/sdk_roadmap.jpg" width="900"/>
+
+- 中文离线文件转写服务(CPU版本),已完成
+- 中文流式语音识别服务(CPU版本),已完成
+- 英文离线文件转写服务(CPU版本),已完成
+- 中文离线文件转写服务(GPU版本),已完成
+- 更多支持中
+
+## 中文离线文件转写服务(GPU版本)
+
+中文语音离线文件服务部署(GPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持多路请求同时进行转写。
+为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
+
+### 最新动态
+- 2024/09/26: 中文离线文件转写服务GPU 2.0 发布,修复显存泄漏,docker镜像版本funasr-runtime-sdk-gpu-0.2.0 (d280bf7e495b)
+- 2024/07/01: 中文离线文件转写服务GPU 1.1 发布,优化bladedisc模型兼容性问题,docker镜像版本funasr-runtime-sdk-gpu-0.1.1 (8875cbf9b99e)
+- 2024/06/27: 中文离线文件转写服务GPU 1.0 发布,支持动态batch,支持多路并发,在长音频测试集上单线RTF为0.0076,多线加速比为1200+(CPU为330+),详见([文档](./docs/benchmark_libtorch_cpp.md)),docker镜像版本funasr-runtime-sdk-gpu-0.1.0 (b86066f4d018)
+
+### 部署与开发文档
+
+部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_gpu_zh.md))
+
+
+## 英文离线文件转写服务(CPU版本)
+
+英文离线文件转写服务部署(CPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持上百路请求同时进行转写。
+为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
+
+### 最新动态
+- 2024/09/26: 英文离线文件转写服务 1.7 发布,修复内存泄漏,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.7 (f6c5a7b59eb6)
+- 2024/05/15: 英文离线文件转写服务 1.6 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.6 (84d781d07997)
+- 2024/03/05: 英文离线文件转写服务 1.5 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.5 (7cca2abc5901)
+- 2024/01/25: 英文离线文件转写服务 1.3 发布,优化vad数据处理方式,大幅降低峰值内存占用,内存泄漏优化,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.3 (c00f9ce7a195)
+- 2024/01/03: 英文离线文件转写服务 1.2 发布,修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.2 (0cdd9f4a4bb5)
+- 2023/11/08: 英文离线文件转写服务 1.1 发布,runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-en-cpu-0.1.1 (27017f70f72a)
+- 2023/10/16: 英文离线文件转写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-en-cpu-0.1.0 (e0de03eb0163),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/DZZUTj-6xwFfi-96ml--4A))
+
+
+### 部署与开发文档
+
+部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_en_zh.md))
+
+
+## 中文实时语音听写服务(CPU版本)
+FunASR实时语音听写服务软件包,既可以实时地进行语音转文字,而且能够在说话句尾用高精度的转写文字修正输出,输出文字带有标点,支持高并发多路请求。
+为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
+
+### 最新动态
+- 2024/10/29: 中文实时语音听写服务 1.12 发布,2pass-offline模式支持SensevoiceSmall模型,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.12 (f5febc5cf13a)
+- 2024/09/26: 中文实时语音听写服务 1.11 发布,修复内存泄漏,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.11 (e51a36c42771)
+- 2024/05/15: 中文实时语音听写服务 1.10 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.10 (1c2adfcff84d)
+- 2024/03/05: 中文实时语音听写服务 1.9 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.9 (4a875e08c7a2)
+- 2024/01/25: 中文实时语音听写服务 1.7 发布,客户端优化,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.7 (2aa23805572e)
+- 2024/01/03: 中文实时语音听写服务 1.6 发布,2pass-offline模式支持Ngram语言模型解码、wfst热词,同时修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.6 (f99925110d27)
+- 2023/11/09: 中文实时语音听写服务 1.5 发布,修复无实时结果的问题,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.5 (b16584b6d38b)
+- 2023/11/08: 中文实时语音听写服务 1.4 发布,支持服务端加载热词(更新热词通信协议)、runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-online-cpu-0.1.4 (691974017c38)
+- 2023/09/19: 中文实时语音听写服务 1.2 发布,2pass模式支持热词、时间戳、ITN模型,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.2 (7222c5319bcf)
+- 2023/08/11: 中文实时语音听写服务 1.1 发布,修复了部分已知的bug(包括server崩溃等),docker镜像版本funasr-runtime-sdk-online-cpu-0.1.1 (bdbdd0b27dee)
+- 2023/08/07: 中文实时语音听写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-online-cpu-0.1.0 (bdbdd0b27dee),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/8He081-FM-9IEI4D-lxZ9w))
+
+
+### 部署与开发文档
+
+部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_online_zh.md))
+
+
+
+## 中文离线文件转写服务(CPU版本)
+
+中文语音离线文件服务部署(CPU版本),拥有完整的语音识别链路,可以将几十个小时的长音频与视频识别成带标点的文字,而且支持上百路请求同时进行转写。
+为了支持不同用户的需求,针对不同场景,准备了不同的图文教程:
+
+### 最新动态
+- 2024/09/26: 中文离线文件转写服务 4.6 发布,修复内存泄漏、支持SensevoiceSmall onnx模型,docker镜像版本funasr-runtime-sdk-cpu-0.4.6 (8651c6b8a1ae)
+- 2024/05/15: 中文离线文件转写服务 4.5 发布,适配FunASR 1.0模型结构,docker镜像版本funasr-runtime-sdk-cpu-0.4.5 (058b9882ae67)
+- 2024/03/05: 中文离线文件转写服务 4.4 发布,docker镜像支持arm64平台,升级modelscope版本,docker镜像版本funasr-runtime-sdk-cpu-0.4.4 (2dc87b86dc49)
+- 2024/01/25: 中文离线文件转写服务 4.2 发布,优化vad数据处理方式,大幅降低峰值内存占用,内存泄漏优化,docker镜像版本funasr-runtime-sdk-cpu-0.4.2 (befdc7b179ed)
+- 2024/01/08: 中文离线文件转写服务 4.1 发布,优化句子级时间戳json格式,docker镜像版本funasr-runtime-sdk-cpu-0.4.1 (0250f8ef981b)
+- 2024/01/03: 中文离线文件转写服务 4.0 发布,新增支持8k模型、优化时间戳不匹配问题及增加句子级别时间戳、优化英文单词fst热词效果、支持自动化配置线程参数,同时修复已知的crash问题及内存泄漏问题,docker镜像版本funasr-runtime-sdk-cpu-0.4.0 (c4483ee08f04)
+- 2023/11/08: 中文离线文件转写服务 3.0 发布,支持标点大模型、支持Ngram模型、支持fst热词(更新热词通信协议)、支持服务端加载热词、runtime结构变化适配(FunASR/funasr/runtime->FunASR/runtime),docker镜像版本funasr-runtime-sdk-cpu-0.3.0 (caa64bddbb43),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/jSbnKw_m31BUUbTukPSOIw))
+- 2023/09/19: 中文离线文件转写服务 2.2 发布,支持ITN模型,docker镜像版本funasr-runtime-sdk-cpu-0.2.2 (2c5286be13e9)
+- 2023/08/22: 中文离线文件转写服务 2.0 发布,集成ffmpeg支持多种音视频输入、支持热词模型、支持时间戳模型,docker镜像版本funasr-runtime-sdk-cpu-0.2.0 (1ad3d19e0707),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/oJHe0MKDqTeuIFH-F7GHMg))
+- 2023/07/03: 中文离线文件转写服务 1.0 发布,docker镜像版本funasr-runtime-sdk-cpu-0.1.0 (1ad3d19e0707),原理介绍文档([点击此处](https://mp.weixin.qq.com/s/DHQwbgdBWcda0w_L60iUww))
+
+### 部署与开发文档
+
+部署模型来自于ModelScope,或者用户finetune,支持用户定制服务,详细文档参考([点击此处](./docs/SDK_advanced_guide_offline_zh.md))
diff --git a/scripts/gen_api_docs.py b/scripts/gen_api_docs.py
index 1ed4c4bd0..c01abe971 100644
--- a/scripts/gen_api_docs.py
+++ b/scripts/gen_api_docs.py
@@ -6,6 +6,7 @@ Output: gh-pages-output/api.html for deployment to gh-pages.
This script is designed to be run by GitHub Actions on every push to main,
automatically regenerating the API docs.
"""
+import argparse
import ast
import glob
import html as htmlmod
@@ -17,7 +18,10 @@ from pathlib import Path
REPO_URL = "https://github.com/modelscope/FunASR"
BRANCH = "main"
REPO_ROOT = Path(__file__).resolve().parents[1]
-OUTPUT_DIR = REPO_ROOT / "gh-pages-output"
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument("--output-dir", type=Path, default=REPO_ROOT / "gh-pages-output")
+OUTPUT_DIR = parser.parse_args().output_dir.resolve()
+STYLESHEET = REPO_ROOT / "gh-pages-output" / "api-reference.css"
os.chdir(REPO_ROOT)
@@ -164,22 +168,27 @@ print(f"Extracted: {len(all_data)} modules, {total_entries} entries")
# Generate HTML
sidebar = ""
content = ""
+overview_links = ""
eid = 0
-for top_level in tree_structure:
+for group_index, top_level in enumerate(tree_structure):
sub_modules = tree_structure[top_level]
- sidebar += f'<div class="l1"><div class="l1-title" onclick="toggleL1(this)"><span>{esc(top_level)}</span><span class="cnt">{sum(1 for s in sub_modules if f"{top_level}.{s}" in all_data)}</span><span class="arr">▸</span></div><div class="l1-children">\n'
- for sub_name in sub_modules:
+ group_id = f"group-{group_index}"
+ sidebar += f'<div class="l1"><button type="button" class="l1-title" aria-expanded="true" aria-controls="{group_id}"><span>{esc(top_level)}</span><span class="cnt">{sum(1 for s in sub_modules if f"{top_level}.{s}" in all_data)}</span><span class="arr" aria-hidden="true">▸</span></button><div class="l1-children" id="{group_id}">\n'
+ for module_index, sub_name in enumerate(sub_modules):
key = f"{top_level}.{sub_name}"
if key not in all_data:
continue
- sidebar += f'<div class="l2"><div class="l2-title" onclick="toggleL2(this)"><span>{esc(sub_name)}</span><span class="arr">▸</span></div><div class="l2-children">\n'
+ module_id = f"{group_id}-module-{module_index}"
+ sidebar += f'<div class="l2"><button type="button" class="l2-title" aria-expanded="true" aria-controls="{module_id}"><span>{esc(sub_name)}</span><span class="arr" aria-hidden="true">▸</span></button><div class="l2-children" id="{module_id}">\n'
for entry in all_data[key]:
eid += 1
eid_str = f"e{eid}"
filepath = entry.get("filepath", "")
if entry["type"] == "class":
- sidebar += f'<a class="l3-item" data-target="{eid_str}" onclick="showEntry(\'{eid_str}\')"><span class="mb badge-c">C</span>{esc(entry["name"])}</a>\n'
+ if entry["name"] in {"AutoModel", "RegisterTables"}:
+ overview_links += f'<a href="#{eid_str}" class="entry-link">{esc(entry["name"])} <span aria-hidden="true">→</span></a> '
+ sidebar += f'<a class="l3-item" href="#{eid_str}" data-target="{eid_str}"><span class="mb badge-c" aria-hidden="true">C</span><span>{esc(entry["name"])}</span></a>\n'
gh_link = github_url(filepath, entry["lineno"])
content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-c">class</span><h2>{esc(entry["name"])}</h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'
content += f'<details class="src-block"><summary>📄 Source code</summary><pre><code>{esc(entry["source"])}</code></pre>'
@@ -200,7 +209,7 @@ for top_level in tree_structure:
for m in entry["methods"]:
eid += 1
mid = f"e{eid}"
- sidebar += f'<a class="l3-item l3m" data-target="{mid}" onclick="showEntry(\'{mid}\')"><span class="mb badge-m">M</span>.{esc(m["name"])}()</a>\n'
+ sidebar += f'<a class="l3-item l3m" href="#{mid}" data-target="{mid}"><span class="mb badge-m" aria-hidden="true">M</span><span>.{esc(m["name"])}()</span></a>\n'
sig = f'{entry["name"]}.{m["name"]}({", ".join(m["args"])})'
mgh = github_url(filepath, m["lineno"])
content += f'<div class="api-detail" id="{mid}"><span class="dtag badge-m">method</span><h2><code>{esc(sig)}</code></h2><div class="dmod">{key}.{entry["name"]} · <a href="{mgh}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(m["doc"])}</div>'
@@ -211,7 +220,7 @@ for top_level in tree_structure:
else:
args_str = ", ".join(entry.get("args", []))
gh_link = github_url(filepath, entry["lineno"])
- sidebar += f'<a class="l3-item" data-target="{eid_str}" onclick="showEntry(\'{eid_str}\')"><span class="mb badge-f">F</span>{esc(entry["name"])}</a>\n'
+ sidebar += f'<a class="l3-item" href="#{eid_str}" data-target="{eid_str}"><span class="mb badge-f" aria-hidden="true">F</span><span>{esc(entry["name"])}</span></a>\n'
content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-f">function</span><h2><code>{esc(entry["name"])}({esc(args_str)})</code></h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'
content += f'<details class="src-block"><summary>📄 Source code</summary><pre><code>{esc(entry["source"])}</code></pre>'
if entry["truncated"]:
@@ -220,53 +229,114 @@ for top_level in tree_structure:
sidebar += '</div></div>\n'
sidebar += '</div></div>\n'
-# Write the full page (keeping same CSS structure + source styles)
+# Preserve extracted content and entry numbering while adding focus targets.
+content = content.replace('class="api-detail"', 'class="api-detail" tabindex="-1"')
+content = content.replace('target="_blank"', 'target="_blank" rel="noopener noreferrer"')
+content = content.replace('<summary>📄 Source', '<summary>Source')
+
html_page = f'''<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0">
<title>FunASR API</title>
-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="api-reference.css">
</head><body class="api-page">
-<nav class="nav"><div class="container">
+<a class="skip-link" href="#api-content">Skip to content</a>
+<nav class="nav" aria-label="Main navigation"><div class="container">
<a href="index.html" class="nav-logo">FunASR</a>
<div class="nav-links">
<a href="index.html">Home</a>
<a href="tutorial.html">Tutorial</a>
<a href="training.html">Training</a>
<a href="model-registration.html">Develop</a>
- <a href="api.html" class="active">API</a>
+ <a href="api.html" class="active" aria-current="page">API</a>
</div>
<a href="https://github.com/modelscope/FunASR" class="nav-github">GitHub</a>
</div></nav>
+<header class="api-header"><h1>API Reference</h1><p>{len(all_data)} modules <span aria-hidden="true">/</span> {total_entries} classes and functions</p></header>
<div class="api-layout">
-<div class="api-sidebar">
-<input type="text" class="sb-search" placeholder="Search..." oninput="filterSidebar(this.value)">
+<aside class="api-sidebar" aria-label="API navigation">
+<label class="sr-only" for="api-search">Search API entries</label>
+<input id="api-search" type="search" class="sb-search" placeholder="Search API" autocomplete="off" spellcheck="false">
+<p id="search-empty" class="search-empty" role="status" hidden>No matching APIs</p>
+<nav aria-label="Modules and entries">
{sidebar}
-</div>
-<div class="api-content">
-<div class="api-welcome" id="api-welcome"><h2>API Reference</h2><p>{total_entries} entries · auto-generated from source<br>Click source code to expand. Links point to latest GitHub code.</p></div>
+</nav></aside>
+<main class="api-content" id="api-content" tabindex="-1">
+<div class="api-welcome" id="api-welcome"><h2>FunASR Python API</h2><p class="muted">Models, inference, training, and utilities.</p>{overview_links}</div>
{content}
-</div></div>
+</main></div>
<script>
-function toggleL1(el){{el.closest('.l1').classList.toggle('open')}}
-function toggleL2(el){{el.closest('.l2').classList.toggle('open')}}
-function showEntry(id){{
-document.querySelectorAll('.api-detail').forEach(e=>e.classList.remove('active'));
-document.querySelectorAll('.l3-item').forEach(e=>e.classList.remove('active'));
-document.getElementById('api-welcome').style.display='none';
-var t=document.getElementById(id);if(t)t.classList.add('active');
-var l=document.querySelector('[data-target="'+id+'"]');if(l)l.classList.add('active');
-document.querySelector('.api-content').scrollTop=0;
+const entries = Array.from(document.querySelectorAll('.api-detail'));
+const entryLinks = Array.from(document.querySelectorAll('.l3-item'));
+const controls = Array.from(document.querySelectorAll('.l1-title, .l2-title'));
+const welcome = document.getElementById('api-welcome');
+const search = document.getElementById('api-search');
+let expandedBeforeSearch = null;
+
+function setExpanded(button, expanded) {{
+ button.setAttribute('aria-expanded', String(expanded));
+ document.getElementById(button.getAttribute('aria-controls')).hidden = !expanded;
+}}
+function showEntry(id, focus = false) {{
+ // Resolve only known entries, never interpolate an untrusted hash in a selector.
+ const target = entries.find(entry => entry.id === id) || null;
+ entries.forEach(entry => {{ entry.hidden = entry !== target; }});
+ welcome.hidden = Boolean(target);
+ entryLinks.forEach(link => {{
+ if (target && link.dataset.target === target.id) {{
+ link.setAttribute('aria-current', 'true');
+ if (link.hidden) {{ search.value = ''; filterSidebar(''); }}
+ for (const level of ['.l1', '.l2']) {{
+ const group = link.closest(level);
+ if (group) setExpanded(group.querySelector('button'), true);
+ }}
+ }} else {{
+ link.removeAttribute('aria-current');
+ }}
+ }});
+ document.title = target ? target.querySelector('h2').textContent + ' | FunASR API' : 'FunASR API';
+ if (focus && target) {{
+ target.focus({{preventScroll: true}});
+ target.scrollIntoView({{block: 'start'}});
+ }}
}}
-function filterSidebar(q){{
-q=q.toLowerCase();
-document.querySelectorAll('.l3-item').forEach(e=>e.classList.toggle('hidden',q&&!e.textContent.toLowerCase().includes(q)));
-if(q)document.querySelectorAll('.l1,.l2').forEach(e=>e.classList.add('open'));
+function filterSidebar(query) {{
+ const q = query.trim().toLowerCase();
+ if (q && !expandedBeforeSearch) {{
+ expandedBeforeSearch = new Map(controls.map(button => [button, button.getAttribute('aria-expanded') === 'true']));
+ }}
+ entryLinks.forEach(link => {{ link.hidden = Boolean(q) && !link.textContent.toLowerCase().includes(q); }});
+ document.querySelectorAll('.l2, .l1').forEach(group => {{
+ group.hidden = Boolean(q) && !Array.from(group.querySelectorAll('.l3-item')).some(link => !link.hidden);
+ }});
+ if (q) controls.forEach(button => setExpanded(button, true));
+ else if (expandedBeforeSearch) {{
+ expandedBeforeSearch.forEach((expanded, button) => setExpanded(button, expanded));
+ expandedBeforeSearch = null;
+ }}
+ document.getElementById('search-empty').hidden = !q || entryLinks.some(link => !link.hidden);
}}
-if(window.location.hash)showEntry(window.location.hash.slice(1));
+controls.forEach(button => {{
+ setExpanded(button, false);
+ button.addEventListener('click', () => setExpanded(button, button.getAttribute('aria-expanded') !== 'true'));
+}});
+entryLinks.forEach(link => link.addEventListener('click', event => {{
+ if (!event.ctrlKey && !event.metaKey && !event.shiftKey && !event.altKey && event.button === 0) {{
+ showEntry(link.dataset.target, true);
+ }}
+}}));
+search.addEventListener('input', () => filterSidebar(search.value));
+document.querySelector('.skip-link').addEventListener('click', event => {{
+ if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || event.button !== 0) return;
+ event.preventDefault();
+ document.getElementById('api-content').focus();
+}});
+window.addEventListener('hashchange', () => showEntry(window.location.hash.slice(1)));
+showEntry(window.location.hash.slice(1));
</script></body></html>'''
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+if STYLESHEET.resolve() != (OUTPUT_DIR / STYLESHEET.name).resolve():
+ shutil.copy2(STYLESHEET, OUTPUT_DIR / STYLESHEET.name)
with (OUTPUT_DIR / "api.html").open("w", encoding="utf-8") as f:
f.write(html_page)
@@ -274,4 +344,4 @@ training_src = REPO_ROOT / "training.html"
if training_src.exists():
shutil.copy2(training_src, OUTPUT_DIR / "training.html")
-print("Generated gh-pages-output/api.html")
+print(f"Generated {OUTPUT_DIR / 'api.html'}")
diff --git a/tests/test_generated_api_docs.py b/tests/test_generated_api_docs.py
new file mode 100644
index 000000000..7ab9a70a4
--- /dev/null
+++ b/tests/test_generated_api_docs.py
@@ -0,0 +1,307 @@
+"""Exercise API generation without overwriting published page artifacts."""
+
+import ast
+from html.parser import HTMLParser
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+FIXTURE = '''class Example:
+ """Example documentation with <escaped> content."""
+
+ def generate(self, input, **kwargs):
+ """Return input unchanged."""
+ return input
+
+
+def helper(value):
+ """A helper function."""
+ return value
+'''.replace("A helper function.", "A helper function. " + "longword" * 100)
+
+
+class Page(HTMLParser):
+ def __init__(self, text):
+ super().__init__(convert_charrefs=True)
+ self.elements = []
+ self.sources = []
+ self.in_pre = False
+ self.feed(text)
+
+ def handle_starttag(self, tag, attrs):
+ self.elements.append((tag, dict(attrs)))
+ if tag == "pre":
+ self.in_pre = True
+ self.sources.append("")
+
+ def handle_endtag(self, tag):
+ if tag == "pre":
+ self.in_pre = False
+
+ def handle_data(self, data):
+ if self.in_pre:
+ self.sources[-1] += data
+
+ def with_class(self, name):
+ return [(tag, attrs) for tag, attrs in self.elements
+ if name in attrs.get("class", "").split()]
+
+
+class GeneratedApiDocsTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ cls.temp = tempfile.TemporaryDirectory(prefix="funasr-api-tests-")
+ cls.repo = Path(cls.temp.name)
+ (cls.repo / "scripts").mkdir()
+ (cls.repo / "funasr/auto").mkdir(parents=True)
+ (cls.repo / "funasr/auto/auto_model.py").write_text(FIXTURE)
+ shutil.copy2(ROOT / "scripts/gen_api_docs.py", cls.repo / "scripts")
+ css = ROOT / "gh-pages-output/api-reference.css"
+ if css.exists():
+ (cls.repo / "gh-pages-output").mkdir()
+ shutil.copy2(css, cls.repo / "gh-pages-output")
+ result = subprocess.run(
+ [sys.executable, str(cls.repo / "scripts/gen_api_docs.py")],
+ capture_output=True, text=True, timeout=30,
+ )
+ if result.returncode:
+ raise AssertionError(result.stdout + result.stderr)
+ cls.html = (cls.repo / "gh-pages-output/api.html").read_text()
+ cls.page = Page(cls.html)
+
+ @classmethod
+ def tearDownClass(cls):
+ cls.temp.cleanup()
+
+ def test_existing_numeric_anchors_and_source_are_preserved(self):
+ details = self.page.with_class("api-detail")
+ self.assertEqual([attrs["id"] for _, attrs in details], ["e1", "e2", "e3"])
+ tree = ast.parse(FIXTURE)
+ lines = FIXTURE.splitlines(keepends=True)
+ def preview(node):
+ return "".join(lines[node.lineno - 1:min(node.lineno + 29, node.end_lineno)])
+ cls, helper = tree.body
+ method = cls.body[1]
+ self.assertEqual(self.page.sources, [preview(cls), preview(method), preview(method), preview(helper)])
+ self.assertIn("Example documentation with &lt;escaped&gt; content.", self.html)
+ self.assertIn("funasr/auto/auto_model.py#L4", self.html)
+
+ def test_group_controls_are_accessible_buttons(self):
+ ids = {attrs["id"] for _, attrs in self.page.elements if "id" in attrs}
+ controls = self.page.with_class("l1-title") + self.page.with_class("l2-title")
+ self.assertTrue(controls)
+ for tag, attrs in controls:
+ self.assertEqual(tag, "button")
+ self.assertEqual(attrs.get("type"), "button")
+ self.assertIn(attrs.get("aria-expanded"), {"true", "false"})
+ self.assertIn(attrs.get("aria-controls"), ids)
+ self.assertNotIn("onclick", attrs)
+
+ def test_entry_links_search_and_landmarks(self):
+ for tag, attrs in self.page.with_class("l3-item"):
+ self.assertEqual(tag, "a")
+ self.assertEqual(attrs.get("href"), "#" + attrs["data-target"])
+ self.assertNotIn("onclick", attrs)
+ self.assertTrue(any(tag == "main" for tag, _ in self.page.elements))
+ search = self.page.with_class("sb-search")[0][1]
+ self.assertTrue(search.get("aria-label") or any(
+ tag == "label" and attrs.get("for") == search.get("id")
+ for tag, attrs in self.page.elements
+ ))
+ self.assertNotIn("Click source code to expand", self.html)
+
+ def test_independent_local_responsive_stylesheet(self):
+ styles = [attrs["href"] for tag, attrs in self.page.elements
+ if tag == "link" and attrs.get("rel") == "stylesheet"]
+ self.assertEqual(styles, ["api-reference.css"])
+ css = (self.repo / "gh-pages-output/api-reference.css").read_text()
+ for contract in (":focus-visible", "minmax(0, 1fr)", "min-width: 0", "overflow-wrap: anywhere", "@media", "[hidden]"):
+ self.assertIn(contract, css)
+
+ def test_script_syntax_and_hash_fallback(self):
+ script = re.search(r"<script>(.*?)</script>", self.html, re.S).group(1)
+ self.assertIn("hashchange", script)
+ self.assertIn("aria-current", script)
+ if not shutil.which("node"):
+ self.skipTest("Node.js is required for JavaScript execution")
+ # Execute the real routing function against a minimal DOM, including
+ # malformed hashes and IDs belonging to non-entry elements.
+ harness = r'''
+const assert = require('node:assert/strict');
+const listeners = {};
+function element(id) {
+ const attrs = {};
+ return {id, hidden: false, textContent: id, dataset: {target: id},
+ classList: {contains: name => name === 'api-detail'},
+ setAttribute: (key, value) => attrs[key] = value,
+ removeAttribute: key => delete attrs[key],
+ getAttribute: key => attrs[key],
+ addEventListener() {}, closest() {return null;},
+ querySelector() {return {textContent: id};},
+ focus() {}, scrollIntoView() {}};
+}
+const detail = element('e1'), link = element('e1');
+const welcomeNode = element('api-welcome');
+const searchNode = {...element('api-search'), value: ''};
+const empty = element('search-empty');
+global.document = {
+ title: '',
+ querySelector(selector) {return selector === '.skip-link' ? element('skip-link') : null;},
+ getElementById(id) {return {e1: detail, 'api-welcome': welcomeNode, 'api-search': searchNode, 'search-empty': empty}[id] || null;},
+ querySelectorAll(selector) {
+ if (selector === '.api-detail') return [detail];
+ if (selector === '.l3-item') return [link];
+ return [];
+ }
+};
+global.window = {location: {hash: '#invalid'}, addEventListener(name, fn) {listeners[name] = fn;}};
+'''
+ assertions = r'''
+assert.equal(welcome.hidden, false);
+assert.equal(detail.hidden, true);
+for (const id of ['e1', 'missing', 'api-welcome', '%ZZ', '"][data-target]']) {
+ showEntry(id);
+ assert.equal(detail.hidden, id !== 'e1');
+ assert.equal(welcome.hidden, id === 'e1');
+}
+window.location.hash = '#e1'; listeners.hashchange();
+assert.equal(detail.hidden, false);
+assert.equal(link.getAttribute('aria-current'), 'true');
+window.location.hash = ''; listeners.hashchange();
+assert.equal(welcome.hidden, false);
+assert.equal(link.getAttribute('aria-current'), undefined);
+console.log('hash routing passed');
+'''
+ result = subprocess.run(["node", "-"], input=harness + script + assertions,
+ capture_output=True, text=True, timeout=10)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+ def test_full_checkout_generation_to_isolated_output(self):
+ with tempfile.TemporaryDirectory(prefix="funasr-api-source-") as directory:
+ result = subprocess.run(
+ [sys.executable, str(ROOT / "scripts/gen_api_docs.py"), "--output-dir", directory],
+ capture_output=True, text=True, timeout=60,
+ )
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ output = Path(directory)
+ self.assertTrue((output / "api-reference.css").is_file())
+ page = Page((output / "api.html").read_text())
+ entries = page.with_class("api-detail")
+ self.assertGreater(len(entries), 100)
+ self.assertEqual([attrs["id"] for _, attrs in entries],
+ [f"e{i}" for i in range(1, len(entries) + 1)])
+
+ def test_skip_link_preserves_selection_playwright(self):
+ try:
+ from playwright.sync_api import expect, sync_playwright
+ except ImportError:
+ self.skipTest("Playwright is required for skip-link interaction regression")
+ cache = Path.home() / ".cache/ms-playwright"
+ browsers = sorted(cache.glob("chromium_headless_shell-*/chrome-linux*/headless_shell"), reverse=True)
+ with sync_playwright() as playwright:
+ browser = playwright.chromium.launch(
+ executable_path=str(browsers[0]) if browsers else None,
+ headless=True, args=["--no-sandbox"], timeout=15000,
+ )
+ try:
+ for width, activation in ((1440, "keyboard"), (390, "click")):
+ with self.subTest(width=width, activation=activation):
+ context = browser.new_context(viewport={"width": width, "height": 900})
+ try:
+ page = context.new_page()
+ page.goto((self.repo / "gh-pages-output/api.html").as_uri() + "#e3")
+ detail = page.locator("#e3")
+ expect(detail).to_be_visible()
+ detail.locator("summary").click()
+ title, url = page.title(), page.url
+ skip = page.get_by_role("link", name="Skip to content")
+ skip.focus()
+ if activation == "keyboard":
+ page.keyboard.press("Enter")
+ else:
+ skip.click()
+ expect(page.locator("#api-content")).to_be_focused()
+ expect(page).to_have_url(url, timeout=1000)
+ expect(detail).to_be_visible()
+ expect(page.locator("#api-welcome")).to_be_hidden()
+ expect(page.locator('[data-target="e3"]')).to_have_attribute("aria-current", "true")
+ self.assertEqual(page.title(), title)
+ self.assertTrue(detail.locator("details").evaluate("node => node.open"))
+ finally:
+ context.close()
+ finally:
+ browser.close()
+
+ def test_browser_navigation_and_responsive_overflow(self):
+ cache = Path.home() / ".cache/ms-playwright"
+ candidates = sorted(cache.glob("chromium_headless_shell-*/chrome-linux*/headless_shell"), reverse=True)
+ candidates += [shutil.which("chromium"), shutil.which("google-chrome")]
+ candidates += sorted(cache.glob("chromium-*/chrome-linux*/chrome"), reverse=True)
+ browser = next((str(path) for path in candidates if path), None)
+ if not browser:
+ self.skipTest("Chromium is required for browser layout verification")
+ check = r'''
+<script>
+window.addEventListener('load', () => {
+ const errors = [];
+ const check = (condition, label) => {if (!condition) errors.push(label);};
+ check(innerWidth === EXPECTED_WIDTH, 'requested viewport width');
+ const group = document.querySelector('.l1-title');
+ check(group.getAttribute('aria-expanded') === 'false', 'initial collapsed state');
+ group.click();
+ check(group.getAttribute('aria-expanded') === 'true', 'button expansion');
+ check(!document.getElementById(group.getAttribute('aria-controls')).hidden, 'expanded panel');
+ group.click();
+ const input = document.getElementById('api-search');
+ input.value = 'no-such-entry'; input.dispatchEvent(new Event('input'));
+ check(!document.getElementById('search-empty').hidden, 'empty search state');
+ input.value = ''; input.dispatchEvent(new Event('input'));
+ check(group.getAttribute('aria-expanded') === 'false', 'restore expansion');
+ document.querySelector('[href="#e3"]').click();
+ const detail = document.getElementById('e3');
+ check(!detail.hidden, 'selected entry');
+ check(document.activeElement === detail, 'entry keyboard focus');
+ check(group.getAttribute('aria-expanded') === 'true', 'reveal ancestors');
+ detail.querySelector('details').open = true;
+ const source = detail.querySelector('pre');
+ check(source.scrollWidth > source.clientWidth, 'long source scrolls internally');
+ check(document.documentElement.scrollWidth <= innerWidth, 'page horizontal overflow');
+ for (const selector of ['.api-sidebar', '.api-content']) {
+ const box = document.querySelector(selector).getBoundingClientRect();
+ check(box.left >= 0 && box.right <= innerWidth + 1, selector + ' viewport bounds');
+ }
+ showEntry('api-welcome');
+ check(!document.getElementById('api-welcome').hidden, 'invalid hash fallback');
+ showEntry('e3');
+ const result = document.createElement('output');
+ result.id = 'browser-verification'; result.textContent = errors.length ? errors.join('; ') : 'PASS';
+ document.body.append(result);
+});
+</script>
+'''
+ page = self.repo / "gh-pages-output/browser-check.html"
+ for width, height in ((1440, 1000), (390, 844), (320, 740)):
+ with self.subTest(width=width):
+ page.write_text(self.html.replace("</body>", check.replace("EXPECTED_WIDTH", str(width)) + "</body>"))
+ result = subprocess.run(
+ [browser, "--headless", "--no-sandbox", "--disable-gpu",
+ "--no-first-run", "--disable-background-networking",
+ f"--user-data-dir={self.repo / ('browser-' + str(width))}",
+ f"--window-size={width},{height}", "--force-device-scale-factor=1",
+ "--virtual-time-budget=1000", "--dump-dom", page.as_uri()],
+ capture_output=True, text=True, timeout=30,
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+ match = re.search(r'<output id="browser-verification">(.*?)</output>', result.stdout)
+ self.assertIsNotNone(match, result.stderr)
+ self.assertEqual(match.group(1), "PASS")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_learning_docs_contract.py b/tests/test_learning_docs_contract.py
new file mode 100644
index 000000000..34d8323ef
--- /dev/null
+++ b/tests/test_learning_docs_contract.py
@@ -0,0 +1,202 @@
+"""Static learning-guide contracts; never import models or download artifacts."""
+
+import ast
+from collections import Counter
+import importlib.util
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PAIRS = (
+ ("docs/installation/installation.md", "docs/installation/installation_zh.md"),
+ ("docs/installation/docker.md", "docs/installation/docker_zh.md"),
+ ("docs/tutorial/README.md", "docs/tutorial/README_zh.md"),
+)
+DOCS = tuple(path for pair in PAIRS for path in pair)
+
+
+def read(path):
+ return (ROOT / path).read_text(encoding="utf-8")
+
+
+def fences(text):
+ """Read the unindented fenced examples used by these six guides."""
+ language = None
+ lines = []
+ for line in text.splitlines():
+ if line.startswith("```"):
+ if language is None:
+ language = line[3:].strip()
+ lines = []
+ else:
+ yield language, "\n".join(lines) + "\n"
+ language = None
+ elif language is not None:
+ lines.append(line)
+ if language is not None:
+ raise AssertionError("Unclosed code fence")
+
+
+class LearningDocsContract(unittest.TestCase):
+ def test_rendered_tutorial_ids_are_unique_and_keep_legacy_anchors(self):
+ from bs4 import BeautifulSoup
+
+ spec = importlib.util.spec_from_file_location(
+ "learning_documentation", ROOT / "web-pages/product-site/documentation.py"
+ )
+ documentation = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(documentation)
+ catalogue = documentation.load_catalogue()
+ entry = next(page for page in catalogue["pages"] if page["slug"] == "quickstart")
+ legacy = {
+ "en": ("Inference", "Training", "Export", "new-model-registration-tutorial"),
+ "zh": ("模型推理", "模型训练与测试", "模型导出与测试", "新模型注册教程"),
+ }
+ for language, anchors in legacy.items():
+ with self.subTest(language=language):
+ rendered = documentation.render_source(entry, language, catalogue)
+ soup = BeautifulSoup(rendered["content_html"], "html.parser")
+ ids = Counter(node["id"] for node in soup.select("[id]"))
+ self.assertEqual({key: count for key, count in ids.items() if count > 1}, {})
+ for anchor in anchors:
+ self.assertEqual(ids[anchor], 1)
+
+ def test_python_examples_compile_without_running(self):
+ count = 0
+ for path in DOCS:
+ for language, code in fences(read(path)):
+ if language == "python":
+ with self.subTest(path=path, code=code[:70]):
+ compile(code, path, "exec")
+ count += 1
+ self.assertGreaterEqual(count, 16)
+
+ def test_shell_syntax_and_embedded_python_without_execution(self):
+ for path in DOCS:
+ for language, code in fences(read(path)):
+ if language not in {"sh", "shell", "bash"}:
+ continue
+ with self.subTest(path=path, code=code[:70]):
+ result = subprocess.run(
+ ["bash", "-n"], input=code, text=True,
+ capture_output=True, check=False,
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+ for line in code.splitlines():
+ if not line.startswith("python -c "):
+ continue
+ words = shlex.split(line)
+ if words[:2] == ["python", "-c"]:
+ compile(words[2], path, "exec")
+
+ def test_bilingual_examples_are_identical(self):
+ for english, chinese in PAIRS:
+ with self.subTest(pair=(english, chinese)):
+ self.assertEqual(list(fences(read(english))), list(fences(read(chinese))))
+
+ def test_relative_link_targets_exist(self):
+ for path in DOCS:
+ for target in re.findall(r"\[[^\]]*\]\(([^)]+)\)", read(path)):
+ if target.startswith(("https://", "http://", "#")):
+ continue
+ with self.subTest(path=path, target=target):
+ resolved = (ROOT / path).parent / target.split("#", 1)[0]
+ self.assertTrue(resolved.exists(), str(resolved))
+
+ def test_sdk_examples_have_source_evidence(self):
+ sources = (
+ "funasr/auto/auto_model.py",
+ "funasr/models/seaco_paraformer/model.py",
+ "funasr/models/fsmn_vad_streaming/model.py",
+ "funasr/download/download_model_from_hub.py",
+ "funasr/utils/postprocess_hotwords.py",
+ )
+ literals = {
+ node.value
+ for source in sources
+ for node in ast.walk(ast.parse(read(source)))
+ if isinstance(node, ast.Constant) and isinstance(node.value, str)
+ }
+ self.assertIn('"AutoModel": ("funasr.auto.auto_model", "AutoModel")', read("funasr/__init__.py"))
+ aliases = ast.parse(read("funasr/download/name_maps_from_hub.py"))
+ ms_map = next(
+ ast.literal_eval(node.value) for node in aliases.body
+ if isinstance(node, ast.Assign)
+ and any(isinstance(target, ast.Name) and target.id == "name_maps_ms" for target in node.targets)
+ )
+ for language, code in fences(read("docs/tutorial/README.md")):
+ if language != "python":
+ continue
+ for node in ast.walk(ast.parse(code)):
+ if isinstance(node, ast.ImportFrom) and node.module == "funasr":
+ self.assertEqual([alias.name for alias in node.names], ["AutoModel"])
+ if not isinstance(node, ast.Call):
+ continue
+ is_constructor = isinstance(node.func, ast.Name) and node.func.id == "AutoModel"
+ is_generate = isinstance(node.func, ast.Attribute) and node.func.attr == "generate"
+ if not (is_constructor or is_generate):
+ continue
+ for keyword in node.keywords:
+ if keyword.arg != "input":
+ self.assertIn(keyword.arg, literals)
+ if keyword.arg in {"model", "vad_model", "punc_model"}:
+ self.assertIn(ast.literal_eval(keyword.value), ms_map)
+ self.assertIn("speech_seaco_paraformer", ms_map["paraformer-zh"])
+ sample = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav"
+ self.assertIn(sample, read("examples/industrial_data_pretraining/paraformer/demo.py"))
+ self.assertIn(sample, read("docs/tutorial/README.md"))
+
+ def test_installation_distinguishes_metadata_and_offline_limits(self):
+ setup = read("setup.py")
+ self.assertIn('python_requires=">=3.7.0"', setup)
+ self.assertIn('"modelscope"', setup)
+ self.assertIn('"huggingface_hub"', setup)
+ self.assertIn("setuptools.build_meta", read("pyproject.toml"))
+ self.assertTrue(read("funasr/version.txt").strip())
+ loader = ast.parse(read("funasr/download/download_model_from_hub.py"))
+ helper = next(node for node in loader.body if isinstance(node, ast.FunctionDef) and node.name == "get_or_download_model_dir_hf")
+ download = next(node for node in ast.walk(helper) if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "snapshot_download")
+ self.assertFalse(download.keywords, "HF revision caveat needs review after helper changes")
+ for path in PAIRS[0]:
+ text = read(path)
+ for marker in ("PyPI", "python -m pip install -e .", "sys.executable", "funasr.__file__", "pip check", "disable_update=True", "trust_remote_code=False", "snapshot_download(model)", "model_revision", "MIT"):
+ self.assertIn(marker, text)
+
+ def test_runtime_tags_have_independent_repository_evidence(self):
+ evidence = "\n".join(read(path) for path in (
+ "runtime/docs/SDK_advanced_guide_offline.md",
+ "runtime/docs/SDK_advanced_guide_offline_gpu.md",
+ "runtime/docs/SDK_advanced_guide_online.md",
+ "runtime/dockerfile/Dockerfile.online.cpu",
+ ))
+ pattern = r"registry\.cn-hangzhou\.aliyuncs\.com/funasr_repo/funasr:[a-z0-9.-]+"
+ for path in PAIRS[1]:
+ images = re.findall(pattern, read(path))
+ self.assertGreaterEqual(len(set(images)), 3)
+ for image in images:
+ self.assertIn(image, evidence)
+ for language, code in fences(read(path)):
+ if language == "sh":
+ self.assertNotIn("--privileged", code)
+ self.assertNotIn("-v /root", code)
+ self.assertNotIn("curl ", code)
+ self.assertIn("-f runtime/dockerfile/Dockerfile.online.cpu", read(path))
+ self.assertIn("funasr-online-cpu:local", evidence)
+
+ def test_learning_flow_keeps_boundaries_and_advanced_entrypoints(self):
+ for path in PAIRS[2]:
+ text = read(path)
+ for marker in ("sentence_info", 'sentence.get("spk")', "batch_size_s", "batch_size_threshold_s", "max_single_segment_time", "hotword", "hotwords", "language", "9600", "OpenMOSS", "finetune.sh", "infer_from_local.sh", "export.py", "model_zoo/", "Tables"):
+ self.assertIn(marker, text)
+ self.assertNotIn("remote_code=\"./model.py\"", text)
+ for anchor in ("Inference", "Training", "Export", "new-model-registration-tutorial"):
+ self.assertIn('name="' + anchor + '"', read(PAIRS[2][0]))
+ self.assertIn('id="' + anchor + '"', read(PAIRS[2][0]))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_python_api_docs_contract.py b/tests/test_python_api_docs_contract.py
new file mode 100644
index 000000000..2f4d51025
--- /dev/null
+++ b/tests/test_python_api_docs_contract.py
@@ -0,0 +1,178 @@
+"""Lightweight documentation contracts; no SDK import, network, or model weights."""
+
+import ast
+from pathlib import Path
+import re
+import types
+import unittest
+from urllib.parse import unquote, urlsplit
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS = (ROOT / "docs/python_api.md", ROOT / "docs/python_api_zh.md")
+AUTO_MODEL = ROOT / "funasr/auto/auto_model.py"
+
+
+def python_blocks(path):
+ return re.findall(r"^```python\n(.*?)^```", path.read_text(encoding="utf-8"), re.M | re.S)
+
+
+def source_tree(relative_path):
+ return ast.parse((ROOT / relative_path).read_text(encoding="utf-8"))
+
+
+def literal_gets(tree):
+ values = set()
+ for node in ast.walk(tree):
+ if not (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)):
+ continue
+ if node.func.attr != "get" or not node.args:
+ continue
+ try:
+ key = ast.literal_eval(node.args[0])
+ default = ast.literal_eval(node.args[1]) if len(node.args) > 1 else None
+ values.add((key, repr(default)))
+ except (ValueError, TypeError):
+ pass
+ return values
+
+
+class PythonApiDocsContract(unittest.TestCase):
+ def test_examples_compile_and_use_source_backed_keywords(self):
+ tree = source_tree("funasr/auto/auto_model.py")
+ known_keys = {key for key, _ in literal_gets(tree)}
+ known_keys.update({"model", "input", "input_len", "progress_callback"})
+ known_keys.update(key for key, _ in literal_gets(source_tree(
+ "funasr/models/paraformer_streaming/model.py")))
+ for path in DOCS:
+ blocks = python_blocks(path)
+ self.assertEqual(len(blocks), 3, path.name)
+ for index, block in enumerate(blocks):
+ with self.subTest(doc=path.name, block=index):
+ compile(block, str(path), "exec")
+ for node in ast.walk(ast.parse(block)):
+ if not isinstance(node, ast.Call):
+ continue
+ is_constructor = isinstance(node.func, ast.Name) and node.func.id == "AutoModel"
+ is_generate = isinstance(node.func, ast.Attribute) and node.func.attr == "generate"
+ if is_constructor or is_generate:
+ for keyword in node.keywords:
+ if keyword.arg is not None:
+ self.assertIn(keyword.arg, known_keys)
+
+ def test_translations_keep_identical_executable_examples(self):
+ self.assertEqual(python_blocks(DOCS[0]), python_blocks(DOCS[1]))
+
+ def test_local_links_resolve_without_repository_scan(self):
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ links = re.findall(r"\[[^\]]+\]\(([^)]+)\)", text)
+ self.assertTrue(links)
+ for link in links:
+ parts = urlsplit(link)
+ if parts.scheme or not parts.path:
+ continue
+ target = (path.parent / unquote(parts.path)).resolve()
+ self.assertIn(ROOT.resolve(), target.parents)
+ self.assertNotIn(".mcp-tasks", target.parts)
+ self.assertTrue(target.exists(), f"{path.name}: {link}")
+
+ def test_assigned_files_have_no_whitespace_errors(self):
+ for path in (*DOCS, Path(__file__)):
+ text = path.read_text(encoding="utf-8")
+ self.assertTrue(text.endswith("\n"), path.name)
+ self.assertFalse(text.endswith("\n\n"), path.name)
+ for number, line in enumerate(text.splitlines(), 1):
+ self.assertEqual(line, line.rstrip(), f"{path.name}:{number}")
+
+ def test_documented_wrapper_defaults_match_source(self):
+ gets = literal_gets(source_tree("funasr/auto/auto_model.py"))
+ expected = {
+ "device": "cuda", "hub": "ms", "ngpu": 1, "ncpu": 4,
+ "disable_update": False, "disable_pbar": False,
+ "batch_size": 1, "batch_size_s": 300,
+ "batch_size_threshold_s": 60, "merge_vad": False,
+ "merge_length_s": 15, "spk_mode": "punc_segment",
+ "return_spk_res": True, "return_spk_center": False,
+ "preset_spk_num": None, "sentence_timestamp": False,
+ "return_raw_text": False,
+ }
+ for key, value in expected.items():
+ self.assertIn((key, repr(value)), gets, key)
+ for path in DOCS:
+ self.assertIn(f"`{key}`", path.read_text(encoding="utf-8"))
+
+ def test_model_specific_defaults_match_source(self):
+ expectations = {
+ "funasr/models/sense_voice/model.py": {
+ "language": "auto", "use_itn": False, "output_timestamp": False,
+ },
+ "funasr/models/fun_asr_nano/model.py": {
+ "hotwords": [], "language": None, "itn": True,
+ },
+ "funasr/models/qwen3_asr/model.py": {
+ "context": "", "return_time_stamps": False,
+ },
+ "funasr/models/paraformer_streaming/model.py": {
+ "chunk_size": [0, 10, 5], "encoder_chunk_look_back": 0,
+ "decoder_chunk_look_back": 0, "is_final": False,
+ },
+ }
+ for path, defaults in expectations.items():
+ gets = literal_gets(source_tree(path))
+ for key, value in defaults.items():
+ self.assertIn((key, repr(value)), gets, f"{path}: {key}")
+
+ def test_hf_revision_caveat_matches_download_helper(self):
+ tree = source_tree("funasr/download/download_model_from_hub.py")
+ helper = next(node for node in tree.body if isinstance(node, ast.FunctionDef)
+ and node.name == "get_or_download_model_dir_hf")
+ calls = [node for node in ast.walk(helper) if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name) and node.func.id == "snapshot_download"]
+ self.assertEqual(len(calls), 1)
+ self.assertEqual(calls[0].keywords, [])
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ for marker in ("snapshot_download(model)", "model_revision", "disable_update",
+ "check_latest", "trust_remote_code", "OpenMOSS", "MIT",
+ "funasr-server", "AutoModelVLLM", "llama.cpp", "CLIENTS.md"):
+ self.assertIn(marker, text)
+
+ def test_generate_dispatch_preserves_caller_cache(self):
+ # Execute only the real wrapper method with fake inference endpoints.
+ tree = ast.parse(AUTO_MODEL.read_text(encoding="utf-8"))
+ cls = next(node for node in tree.body if isinstance(node, ast.ClassDef)
+ and node.name == "AutoModel")
+ method = next(node for node in cls.body if isinstance(node, ast.FunctionDef)
+ and node.name == "generate")
+ namespace = {"apply_postprocess_hotwords_to_results": lambda results, cfg: results}
+ exec(compile(ast.Module(body=[method], type_ignores=[]), str(AUTO_MODEL), "exec"), namespace)
+ for use_vad in (False, True):
+ calls = []
+ resets = []
+ expected = [{"key": "test", "text": "stub"}]
+
+ def inference(input, **cfg):
+ calls.append(("direct", input, cfg))
+ return expected
+
+ def inference_with_vad(input, **cfg):
+ calls.append(("vad", input, cfg))
+ return expected
+
+ model = types.SimpleNamespace(
+ vad_model=object() if use_vad else None, punc_model=None,
+ _reset_runtime_configs=lambda: resets.append(True),
+ inference=inference, inference_with_vad=inference_with_vad,
+ )
+ cache = {}
+ result = namespace["generate"](model, "audio.wav", cache=cache, is_final=True)
+ self.assertIs(result, expected)
+ self.assertEqual(resets, [True])
+ self.assertEqual(calls[0][0], "vad" if use_vad else "direct")
+ self.assertIs(calls[0][2]["cache"], cache)
+ self.assertTrue(calls[0][2]["is_final"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_service_docs_contract.py b/tests/test_service_docs_contract.py
new file mode 100644
index 000000000..a91511cd6
--- /dev/null
+++ b/tests/test_service_docs_contract.py
@@ -0,0 +1,179 @@
+"""Source-backed service docs checks without loading models or starting servers."""
+
+import ast
+import json
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import unittest
+from urllib.parse import unquote, urlsplit
+
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLE = ROOT / "examples/openai_api"
+DOCS = [EXAMPLE / name for name in ("CLIENTS.md", "README.md", "README_zh.md")]
+PACKAGED = ROOT / "funasr/bin/_server_app.py"
+
+
+def blocks(text, language):
+ return re.findall(r"^```" + language + r"\n(.*?)^```", text, re.M | re.S)
+
+
+def tree(path):
+ return ast.parse(path.read_text(encoding="utf-8"))
+
+
+def function(path, name):
+ return next(node for node in ast.walk(tree(path))
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+ and node.name == name)
+
+
+def form_defaults(node):
+ defaults = {}
+ for arg, value in zip(node.args.args[-len(node.args.defaults):], node.args.defaults):
+ if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "Form":
+ defaults[arg.arg] = ast.literal_eval(next(
+ keyword.value for keyword in value.keywords if keyword.arg == "default"))
+ return defaults
+
+
+def headings(text):
+ text = re.sub(r"^```[^\n]*\n.*?^```[^\n]*$", "", text, flags=re.M | re.S)
+ result = set()
+ counts = {}
+ for heading in re.findall(r"^#{1,6}\s+(.+?)\s*#*\s*$", text, re.M):
+ slug = re.sub(r"[^\w\- ]", "", heading.lower()).replace(" ", "-")
+ count = counts.get(slug, 0)
+ counts[slug] = count + 1
+ result.add(f"{slug}-{count}" if count else slug)
+ return result
+
+
+class ServiceDocsContract(unittest.TestCase):
+ def test_relative_links_and_owned_page_anchors(self):
+ owned = {path.resolve() for path in DOCS}
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ self.assertIn("## API Contract", text)
+ self.assertIn("](#api-contract)", text)
+ for link in re.findall(r"\[[^\]]+\]\(([^)]+)\)", text):
+ parts = urlsplit(link)
+ if parts.scheme or parts.netloc:
+ continue
+ target = (path.parent / unquote(parts.path)).resolve() if parts.path else path.resolve()
+ self.assertIn(ROOT.resolve(), target.parents)
+ self.assertNotIn(".mcp-tasks", target.parts)
+ self.assertTrue(target.exists(), f"{path.name}: {link}")
+ if parts.fragment and target in owned:
+ self.assertIn(unquote(parts.fragment), headings(target.read_text(encoding="utf-8")), link)
+
+ def test_sdk_links_and_unsupported_claims(self):
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ for link in ("../../docs/python_api.md", "../../docs/python_api_zh.md"):
+ self.assertIn(f"]({link})", text)
+ for marker in ("spk=true", "segments=[]", "--model auto", "OpenAI API"):
+ self.assertIn(marker, text)
+ for stale in ("170x realtime", "120x realtime", "3.6x realtime",
+ "Server starts in ~20s", "Works with **any agent framework**",
+ "Fast default with language, emotion, and event tags",
+ "Returns: text, segments (with start/end/speaker), duration"):
+ self.assertNotIn(stale, text)
+
+ def test_python_and_shell_examples_are_syntactically_valid(self):
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ for index, code in enumerate(blocks(text, "python")):
+ compile(code, f"{path}:{index}", "exec")
+ for index, code in enumerate(blocks(text, "bash")):
+ result = subprocess.run(["bash", "-n"], input=code, text=True, capture_output=True)
+ self.assertEqual(result.returncode, 0, f"{path}:{index}: {result.stderr}")
+
+ def test_local_script_commands_and_options_match_source(self):
+ for path in DOCS:
+ text = path.read_text(encoding="utf-8")
+ if path.name.startswith("README"):
+ quick_start = blocks(text, "bash")[0]
+ self.assertIn("cd examples/openai_api", quick_start)
+ self.assertLess(quick_start.index("cd examples/openai_api"), quick_start.index("python server.py"))
+ for code in blocks(text, "bash"):
+ for line in code.replace("\\\n", " ").splitlines():
+ args = shlex.split(line, comments=True)
+ if len(args) < 2 or args[0] not in ("python", "bash"):
+ continue
+ script = EXAMPLE / args[1]
+ self.assertTrue(script.is_file(), str(script))
+ if args[0] != "python":
+ continue
+ options = {ast.literal_eval(arg) for node in ast.walk(tree(script))
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "add_argument"
+ for arg in node.args if isinstance(arg, ast.Constant) and isinstance(arg.value, str)}
+ for arg in args[2:]:
+ if arg.startswith("--"):
+ self.assertIn(arg.split("=", 1)[0], options, str(script))
+
+ def test_form_defaults_and_alias_boundaries_match_source(self):
+ example = form_defaults(function(EXAMPLE / "server.py", "transcribe"))
+ packaged = form_defaults(function(PACKAGED, "transcribe"))
+ self.assertEqual(example["model"], "sensevoice")
+ self.assertNotIn("spk", example)
+ self.assertEqual(packaged["model"], "fun-asr-nano")
+ self.assertIs(packaged["spk"], False)
+ for path, name, expected in ((EXAMPLE / "server.py", "MODEL_CONFIGS", True),
+ (PACKAGED, "FALLBACK_CONFIGS", False)):
+ assignment = next(node for node in ast.walk(tree(path))
+ if isinstance(node, ast.Assign) and any(
+ isinstance(target, ast.Name) and target.id == name for target in node.targets))
+ aliases = [ast.literal_eval(key) for key in assignment.value.keys]
+ self.assertEqual("paraformer-en" in aliases, expected)
+
+ def test_startup_defaults_match_source(self):
+ for path, expected in ((EXAMPLE / "server.py", "sensevoice"),
+ (ROOT / "funasr/bin/server.py", "auto")):
+ option = next(node for node in ast.walk(tree(path)) if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute) and node.func.attr == "add_argument"
+ and node.args and isinstance(node.args[0], ast.Constant)
+ and node.args[0].value == "--model")
+ self.assertEqual(next(ast.literal_eval(kw.value) for kw in option.keywords
+ if kw.arg == "default"), expected)
+ startup = function(PACKAGED, "create_app")
+ selection = next(node for node in ast.walk(startup) if isinstance(node, ast.IfExp)
+ and isinstance(node.body, ast.Constant) and node.body.value == "fun-asr-nano")
+ for device, expected in (("cuda:0", "fun-asr-nano"), ("cpu", "sensevoice"), ("mps", "sensevoice")):
+ self.assertEqual(eval(compile(ast.Expression(selection), str(PACKAGED), "eval"), {"device": device}), expected)
+
+ def test_packaged_verbose_example_matches_real_builder(self):
+ samples = [json.loads(code) for code in blocks(DOCS[0].read_text(encoding="utf-8"), "json")]
+ self.assertEqual(len(samples), 3)
+ namespace = {"resolve_transcription_language": lambda requested, result: requested or result["language"]}
+ builder = function(PACKAGED, "build_openai_verbose_json")
+ exec(compile(ast.Module(body=[builder], type_ignores=[]), str(PACKAGED), "exec"), namespace)
+ result = {"text": "recognized speech", "language": "en", "duration": 3.2,
+ "segments": [{"start": 0.0, "end": 3.2, "text": "recognized speech"}]}
+ self.assertEqual(namespace[builder.name](result), samples[1])
+ self.assertNotIn("speaker", samples[1]["segments"][0])
+ self.assertLessEqual(samples[1]["segments"][0]["end"], samples[1]["duration"])
+
+ def test_example_verbose_sample_and_duration_meaning(self):
+ samples = [json.loads(code) for code in blocks(DOCS[0].read_text(encoding="utf-8"), "json")]
+ handler = function(EXAMPLE / "server.py", "transcribe")
+ response = next(node for node in ast.walk(handler) if isinstance(node, ast.Dict)
+ and any(isinstance(key, ast.Constant) and key.value == "duration" for key in node.keys))
+ expected = eval(compile(ast.Expression(response), "example-response", "eval"),
+ {"text": "recognized speech", "segments": [], "language": None,
+ "elapsed": 0.42, "model": "sensevoice"})
+ self.assertEqual(expected, samples[2])
+ source = PACKAGED.read_text(encoding="utf-8")
+ self.assertIn("float(sf.info(audio_path).duration)", source)
+ self.assertIn('"duration": len(audio_data) / sr', source)
+ clients = DOCS[0].read_text(encoding="utf-8")
+ self.assertIn("not audio duration", clients)
+ self.assertIn("Audio duration in seconds", clients)
+ self.assertIn("does not enable diarization", clients)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_training_docs_contract.py b/tests/test_training_docs_contract.py
new file mode 100644
index 000000000..bf6c35f4d
--- /dev/null
+++ b/tests/test_training_docs_contract.py
@@ -0,0 +1,117 @@
+"""Source-backed docs checks, without model downloads or GPU training."""
+
+import ast
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from urllib.parse import unquote, urlsplit
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS = (
+ "training.md",
+ "training_zh.md",
+ "model_registration.md",
+ "model_registration_zh.md",
+)
+
+
+def blocks(name, language):
+ text = (ROOT / "docs" / name).read_text(encoding="utf-8")
+ return re.findall(rf"^```{language}\n(.*?)^```", text, re.M | re.S)
+
+
+class TrainingDocsContractTests(unittest.TestCase):
+ def test_relative_repository_links(self):
+ for name in DOCS:
+ document = ROOT / "docs" / name
+ text = document.read_text(encoding="utf-8")
+ links = re.findall(r"\[[^\]\n]+\]\(([^)]+)\)", text)
+ self.assertGreater(len(links), 5)
+ for target in links:
+ parsed = urlsplit(target)
+ if parsed.scheme or not parsed.path:
+ continue
+ resolved = (document.parent / unquote(parsed.path)).resolve()
+ with self.subTest(document=name, target=target):
+ self.assertTrue(resolved.is_relative_to(ROOT))
+ self.assertTrue(resolved.exists(), target)
+
+ def test_python_json_and_shell_syntax(self):
+ for name in DOCS:
+ for source in blocks(name, "python"):
+ ast.parse(source, filename=name)
+ for source in blocks(name, "json"):
+ self.assertIsInstance(json.loads(source), dict)
+ for source in blocks(name, "bash"):
+ result = subprocess.run(
+ ["bash", "-n"], input=source, text=True,
+ capture_output=True, timeout=10,
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+
+ def test_bilingual_executable_examples_match(self):
+ for english, chinese in (
+ ("training.md", "training_zh.md"),
+ ("model_registration.md", "model_registration_zh.md"),
+ ):
+ for language in ("python", "bash", "json"):
+ self.assertEqual(blocks(english, language), blocks(chinese, language))
+
+ def test_documented_commands_reference_real_scripts(self):
+ for relative in (
+ "funasr/bin/train_ds.py",
+ "funasr/datasets/audio_datasets/scp2jsonl.py",
+ "examples/industrial_data_pretraining/fun_asr_nano/tools/scp2jsonl.py",
+ ):
+ self.assertTrue((ROOT / relative).is_file(), relative)
+ for name in DOCS:
+ text = (ROOT / "docs" / name).read_text(encoding="utf-8")
+ self.assertNotRegex(text, r"/(?:Users|home)/[^\s]+")
+
+ def test_loader_and_registry_source_contract(self):
+ loader = ast.parse(
+ (ROOT / "funasr/download/download_model_from_hub.py").read_text()
+ )
+ functions = {
+ node.name: node for node in loader.body
+ if isinstance(node, ast.FunctionDef)
+ }
+ for name, imports_code in (("download_from_ms", True), ("download_from_hf", False)):
+ calls = {
+ node.func.id for node in ast.walk(functions[name])
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+ }
+ self.assertEqual("import_module_from_path" in calls, imports_code)
+ source = (ROOT / "funasr/register.py").read_text()
+ self.assertIn("registry[registry_key] = target_class", source)
+ auto = (ROOT / "funasr/auto/auto_model.py").read_text()
+ self.assertIn('if "model_conf" not in kwargs:', auto)
+ self.assertIn("res = model.inference(**batch, **kwargs)", auto)
+ self.assertIn("next(model.parameters()).device", auto)
+
+ def test_no_download_toy_against_checkout(self):
+ source = blocks("model_registration.md", "python")[0]
+ # A real file is necessary for the registry's inspect metadata.
+ with tempfile.TemporaryDirectory(prefix="funasr-docs-contract-") as temp:
+ path = Path(temp) / "custom_model_demo.py"
+ path.write_text(source, encoding="utf-8")
+ env = os.environ.copy()
+ env["PYTHONPATH"] = str(ROOT) + os.pathsep + env.get("PYTHONPATH", "")
+ env["HF_HUB_OFFLINE"] = "1"
+ env["TRANSFORMERS_OFFLINE"] = "1"
+ result = subprocess.run(
+ [sys.executable, str(path)], cwd=ROOT, env=env,
+ text=True, capture_output=True, timeout=90,
+ )
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("['hello', 'world']", result.stdout)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/web-pages/product-site/README.md b/web-pages/product-site/README.md
index 6152e48ab..8fbda9992 100644
--- a/web-pages/product-site/README.md
+++ b/web-pages/product-site/README.md
@@ -6,7 +6,8 @@ Python build; no browser framework or runtime application server is required.
## Content ownership
- `data/documentation.json`: task groups, bilingual titles and Markdown sources.
-- Repository `docs/*.md`: documentation body, shared with GitHub readers.
+- Repository `docs/`, `model_zoo/`, `runtime/` and `examples/openai_api/`
+ Markdown listed in the catalogue: documentation body, shared with GitHub readers.
- `data/deployments.json`: versions, hardware, evidence and operational limits.
- `templates/`: generated homepage, deployment manuals and documentation shell.
- `assets/css/experience.css`: shared product and legacy reading experience.
@@ -14,6 +15,11 @@ Python build; no browser framework or runtime application server is required.
replace this snapshot with a partial output tree.
- Repository `gh-pages-output/index.html` and `zh/index.html`: GitHub Pages entry
points. Their existing API/tutorial routes remain available.
+- `export_docs.py`: generates established GitHub Pages guide URLs from the same
+ rendered sources, with canonical navigation to www.funasr.com and a local copy
+ of the fingerprinted assets so publication does not depend on cross-host timing.
+- Repository `scripts/gen_api_docs.py`: extracts the separate API reference from
+ Python source; `gh-pages-output/api-reference.css` owns its responsive layout.
The build emits search indexes, maps source-relative document links, preserves
Unicode heading anchors and fingerprints all product assets. Historical
@@ -27,8 +33,19 @@ python -m pip install -r web-pages/product-site/requirements-site.txt
python -m pytest web-pages/product-site/tests -q
python web-pages/product-site/build.py --output /tmp/funasr-site
python web-pages/product-site/validate.py /tmp/funasr-site
+python scripts/gen_api_docs.py
+python web-pages/product-site/export_docs.py --site /tmp/funasr-site --output gh-pages-output
```
+Add a guide by listing both source paths, a unique slug and a known group in the
+catalogue. Use repository-relative Markdown links; the renderer maps registered
+guides to their local language routes. Keep explicit legacy anchors unique.
+Preserve protocol distinctions and mark historical evidence as historical.
+Do not hand-edit generated guide bodies in `gh-pages-output/`; the publication
+workflow renders them again after the API generator runs. Specialist recipes
+and historical notes remain linked from the curated guides rather than being
+presented as current, universally supported deployment paths.
+
Browser tests live in `tests/browser/`. Install their pinned npm dependencies
and Chromium, then run `npm test` from that directory. The suite owns its local
HTTP server and rejects reuse of an occupied port.
diff --git a/web-pages/product-site/assets/css/experience.css b/web-pages/product-site/assets/css/experience.css
index 03c968e28..2fee6c2c6 100644
--- a/web-pages/product-site/assets/css/experience.css
+++ b/web-pages/product-site/assets/css/experience.css
@@ -137,6 +137,8 @@ td, th { padding: 14px; }
.docs-home { font-weight: 700; color: var(--ink) !important; }
.docs-sidebar details { margin: 22px 0; }
.docs-sidebar summary { font-size: 12px; font-weight: 700; padding: 0 10px 6px; cursor: pointer; }
+.docs-sidebar .docs-navigation { margin: 0; }
+.docs-navigation > .docs-navigation-toggle { display: none; }
.docs-body { min-width: 0; }
.breadcrumbs { display: flex; flex-wrap: wrap; gap: 8px; color: var(--muted); font-size: 12px; margin-bottom: 32px; }
.breadcrumbs a { text-decoration: none; }
@@ -243,6 +245,8 @@ td, th { padding: 14px; }
.docs-sidebar details { display: inline-block; vertical-align: top; width: calc(50% - 8px); margin: 6px 4px 6px 0; }
.docs-sidebar details:not([open]) nav { display: none; }
.docs-sidebar details[open] { width: 100%; }
+ .docs-sidebar .docs-navigation { display: block; width: 100%; margin: 4px 0 0; }
+ .docs-navigation > .docs-navigation-toggle { display: list-item; margin-left: 10px; padding: 6px 0; }
.docs-title h1 { font-size: 29px; }
.breadcrumbs { margin-bottom: 20px; }
.docs-groups { gap: 24px; grid-template-columns: 1fr; }
diff --git a/web-pages/product-site/assets/js/experience.js b/web-pages/product-site/assets/js/experience.js
index e86b84075..8af8804e9 100644
--- a/web-pages/product-site/assets/js/experience.js
+++ b/web-pages/product-site/assets/js/experience.js
@@ -64,9 +64,14 @@
const query = new URLSearchParams(location.search).get('q');
if (query) { input.value = query; show(); }
});
- if (matchMedia('(max-width: 720px)').matches) {
+ const mobileDocs = matchMedia('(max-width: 720px)');
+ if (mobileDocs.matches) {
document.querySelectorAll('.docs-sidebar details').forEach((group) => { group.open = false; });
}
+ mobileDocs.addEventListener('change', ({ matches }) => {
+ const navigation = document.querySelector('.docs-navigation');
+ if (navigation) navigation.open = !matches;
+ });
document.querySelectorAll('.docs-article pre, .legacy-page article pre').forEach((pre) => {
if (pre.querySelector('button')) return;
const text = pre.textContent.trim();
diff --git a/web-pages/product-site/data/documentation.json b/web-pages/product-site/data/documentation.json
index a3f2f63cc..e9be41718 100644
--- a/web-pages/product-site/data/documentation.json
+++ b/web-pages/product-site/data/documentation.json
@@ -2,23 +2,41 @@
"groups": [
{"id": "start", "zh": "开始使用", "en": "Get started"},
{"id": "models", "zh": "模型与能力", "en": "Models & capabilities"},
+ {"id": "train", "zh": "训练与扩展", "en": "Train & extend"},
{"id": "deploy", "zh": "部署与接口", "en": "Deploy & integrate"},
{"id": "operate", "zh": "评测与运维", "en": "Evaluate & operate"},
- {"id": "ecosystem", "zh": "应用与生态", "en": "Applications & ecosystem"}
+ {"id": "ecosystem", "zh": "应用与生态", "en": "Applications & ecosystem"},
+ {"id": "reference", "zh": "协议与参考", "en": "Protocols & reference"}
],
"pages": [
+ {"slug": "installation", "group": "start", "zh": "安装与环境验证", "en": "Installation & environment checks", "source_zh": "docs/installation/installation_zh.md", "source_en": "docs/installation/installation.md"},
+ {"slug": "quickstart", "group": "start", "zh": "第一次转写", "en": "Your first transcription", "source_zh": "docs/tutorial/README_zh.md", "source_en": "docs/tutorial/README.md"},
+ {"slug": "python-api", "group": "start", "zh": "Python SDK: AutoModel", "en": "Python SDK: AutoModel", "source_zh": "docs/python_api_zh.md", "source_en": "docs/python_api.md"},
{"slug": "model-selection", "group": "start", "zh": "选择第一个模型", "en": "Choose your first model", "source_zh": "docs/model_selection_zh.md", "source_en": "docs/model_selection.md"},
{"slug": "command-line", "group": "start", "zh": "命令行转写", "en": "Command-line transcription", "source_zh": "docs/cli.md", "source_en": "docs/cli.md"},
{"slug": "migration", "group": "start", "zh": "从 Whisper 与云 API 迁移", "en": "Migrate from Whisper & cloud APIs", "source_zh": "docs/migration_from_whisper_zh.md", "source_en": "docs/migration_from_whisper.md"},
{"slug": "moss-transcribe-diarize", "group": "models", "zh": "MOSS 转写与说话人分离", "en": "MOSS transcription & diarization", "source_zh": "docs/moss_transcribe_diarize_zh.md", "source_en": "docs/moss_transcribe_diarize.md"},
+ {"slug": "model-zoo", "group": "models", "zh": "Model Zoo", "en": "Model Zoo", "source_zh": "model_zoo/readme_zh.md", "source_en": "model_zoo/readme.md"},
+ {"slug": "training", "group": "train", "zh": "微调与评测", "en": "Fine-tuning & evaluation", "source_zh": "docs/training_zh.md", "source_en": "docs/training.md"},
+ {"slug": "model-registration", "group": "train", "zh": "自定义模型注册", "en": "Custom model registration", "source_zh": "docs/model_registration_zh.md", "source_en": "docs/model_registration.md"},
+ {"slug": "docker", "group": "deploy", "zh": "容器环境与镜像选择", "en": "Containers & image selection", "source_zh": "docs/installation/docker_zh.md", "source_en": "docs/installation/docker.md"},
+ {"slug": "runtime-guide", "group": "deploy", "zh": "服务部署入口", "en": "Serving entry points", "source_zh": "runtime/readme_cn.md", "source_en": "runtime/readme.md"},
+ {"slug": "http-server", "group": "deploy", "zh": "Python HTTP 服务", "en": "Python HTTP service", "source_zh": "examples/openai_api/README_zh.md", "source_en": "examples/openai_api/README.md"},
+ {"slug": "kubernetes", "group": "deploy", "zh": "Kubernetes 部署", "en": "Kubernetes deployment", "source_zh": "examples/openai_api/kubernetes/README_zh.md", "source_en": "examples/openai_api/kubernetes/README.md"},
{"slug": "deployment-matrix", "group": "deploy", "zh": "运行时与部署矩阵", "en": "Runtime & deployment matrix", "source_zh": "docs/deployment_matrix_zh.md", "source_en": "docs/deployment_matrix.md"},
{"slug": "vllm", "group": "deploy", "zh": "vLLM split-engine 推理", "en": "vLLM split-engine inference", "source_zh": "docs/vllm_guide_zh.md", "source_en": "docs/vllm_guide.md"},
{"slug": "native-vllm", "group": "deploy", "zh": "原生 vLLM 验证记录", "en": "Native vLLM validation record", "source_zh": "docs/vllm_native_funasr_validation.md", "source_en": "docs/vllm_native_funasr_validation.md"},
{"slug": "troubleshooting", "group": "operate", "zh": "安装与推理故障排查", "en": "Troubleshooting", "source_zh": "docs/troubleshooting_zh.md", "source_en": "docs/troubleshooting.md"},
+ {"slug": "security", "group": "operate", "zh": "服务安全边界", "en": "Service security boundaries", "source_zh": "examples/openai_api/SECURITY_zh.md", "source_en": "examples/openai_api/SECURITY.md"},
{"slug": "benchmark-method", "group": "operate", "zh": "可复现性能评测", "en": "Reproducible performance tests", "source_zh": "docs/benchmark/rtf_reproducibility.md", "source_en": "docs/benchmark/rtf_reproducibility.md"},
{"slug": "realtime-benchmark", "group": "operate", "zh": "实时 WebSocket 压测", "en": "Realtime WebSocket benchmarking", "source_zh": "docs/benchmark/realtime_ws_benchmark.md", "source_en": "docs/benchmark/realtime_ws_benchmark.md"},
{"slug": "use-cases", "group": "ecosystem", "zh": "应用场景与示例", "en": "Use cases & examples", "source_zh": "docs/use_case_showcase_zh.md", "source_en": "docs/use_case_showcase.md"},
{"slug": "community", "group": "ecosystem", "zh": "社区集成", "en": "Community integrations", "source_zh": "docs/community_projects_zh.md", "source_en": "docs/community_projects.md"},
- {"slug": "repositories", "group": "ecosystem", "zh": "四仓职责与贡献入口", "en": "Repositories & contribution paths", "source_zh": "docs/repository_roles_zh.md", "source_en": "docs/repository_roles.md"}
+ {"slug": "repositories", "group": "ecosystem", "zh": "四仓职责与贡献入口", "en": "Repositories & contribution paths", "source_zh": "docs/repository_roles_zh.md", "source_en": "docs/repository_roles.md"},
+ {"slug": "javascript", "group": "ecosystem", "zh": "JavaScript 客户端", "en": "JavaScript clients", "source_zh": "examples/openai_api/JAVASCRIPT_zh.md", "source_en": "examples/openai_api/JAVASCRIPT.md"},
+ {"slug": "workflows", "group": "ecosystem", "zh": "工作流集成", "en": "Workflow integrations", "source_zh": "examples/openai_api/WORKFLOWS_zh.md", "source_en": "examples/openai_api/WORKFLOWS.md"},
+ {"slug": "service-api", "group": "reference", "zh": "HTTP API 契约", "en": "HTTP API contract", "source_zh": "examples/openai_api/OPENAPI_zh.md", "source_en": "examples/openai_api/OPENAPI.md"},
+ {"slug": "websocket-protocol", "group": "reference", "zh": "C++ WebSocket 协议", "en": "C++ WebSocket protocol", "source_zh": "runtime/docs/websocket_protocol_zh.md", "source_en": "runtime/docs/websocket_protocol.md"},
+ {"slug": "onnx-output", "group": "reference", "zh": "ONNX 二进制输出契约", "en": "ONNX binary output contract", "source_zh": "runtime/docs/onnxruntime_binary_output_zh.md", "source_en": "runtime/docs/onnxruntime_binary_output.md"}
]
}
diff --git a/web-pages/product-site/data/legacy_doc_anchors.json b/web-pages/product-site/data/legacy_doc_anchors.json
new file mode 100644
index 000000000..da22d3982
--- /dev/null
+++ b/web-pages/product-site/data/legacy_doc_anchors.json
@@ -0,0 +1,151 @@
+{
+ "source_ref": "origin/gh-pages",
+ "source_revision": "871ac766876c2f511550478d88c86aa3daab3172",
+ "notes": "Published fragments map to the nearest current topic heading. Consolidated quickstart topics use workflow sections; removed standalone runtime diagnostics use the deployment readiness checklist. Source articles and API reference pages are not rewritten by this compatibility layer.",
+ "pages": {
+ "tutorial.html": {
+ "quick": "1-produce-a-first-transcript",
+ "install": "1-produce-a-first-transcript",
+ "choose": "5-hotwords-and-language-boundaries",
+ "scenarios": "6-continue-with-a-specific-workflow",
+ "offline": "1-produce-a-first-transcript",
+ "streaming": "6-continue-with-a-specific-workflow",
+ "spk": "3-add-vad-punctuation-and-sentence-timestamps",
+ "emotion": "6-continue-with-a-specific-workflow",
+ "vad": "3-add-vad-punctuation-and-sentence-timestamps",
+ "punc": "3-add-vad-punctuation-and-sentence-timestamps",
+ "deploy-agent": "6-continue-with-a-specific-workflow",
+ "subtitle": "3-add-vad-punctuation-and-sentence-timestamps",
+ "export": "model-export-and-testing",
+ "faq": "6-continue-with-a-specific-workflow"
+ },
+ "zh/tutorial.html": {
+ "quick": "1-完成第一次转写",
+ "install": "1-完成第一次转写",
+ "choose": "5-热词与语言边界",
+ "scenarios": "6-进入具体工作流",
+ "offline": "1-完成第一次转写",
+ "streaming": "6-进入具体工作流",
+ "spk": "3-添加-vad标点与句级时间戳",
+ "emotion": "6-进入具体工作流",
+ "vad": "3-添加-vad标点与句级时间戳",
+ "punc": "3-添加-vad标点与句级时间戳",
+ "deploy-agent": "6-进入具体工作流",
+ "subtitle": "3-添加-vad标点与句级时间戳",
+ "export": "导出与运行时验证",
+ "faq": "6-进入具体工作流"
+ },
+ "training.html": {
+ "overview": "choose-the-work",
+ "data": "prepare-the-dataset",
+ "paraformer": "validate-small-then-launch",
+ "sensevoice": "sensevoice-preserve-rich-labels",
+ "nano": "funasrnano-chatml-jsonl",
+ "params": "validate-small-then-launch",
+ "multi-gpu": "validate-small-then-launch",
+ "deepspeed": "checkpoints-and-resume",
+ "monitor": "validate-small-then-launch",
+ "inference-after": "evaluate-and-export",
+ "tips": "validate-small-then-launch"
+ },
+ "zh/training.html": {
+ "overview": "先确定任务",
+ "data": "准备数据",
+ "paraformer": "先做小规模验证",
+ "sensevoice": "sensevoice保留富标签",
+ "nano": "funasrnanochatml-jsonl",
+ "params": "先做小规模验证",
+ "multi-gpu": "先做小规模验证",
+ "deepspeed": "checkpoint-与恢复",
+ "monitor": "先做小规模验证",
+ "inference-after": "评估与导出",
+ "tips": "先做小规模验证"
+ },
+ "model-registration.html": {
+ "architecture": "names-and-import-order",
+ "setup": "minimal-local-contract-example",
+ "understand": "inference-and-training-contracts",
+ "add-model": "minimal-local-contract-example",
+ "add-component": "names-and-import-order",
+ "standalone": "loading-reviewed-custom-code-and-weights",
+ "testing": "safety-and-verification",
+ "pitfalls": "safety-and-verification",
+ "contribute": "real-examples-and-boundaries"
+ },
+ "zh/model-registration.html": {
+ "architecture": "名称与导入顺序",
+ "setup": "最小本地接口示例",
+ "understand": "推理与训练接口",
+ "add-model": "最小本地接口示例",
+ "add-component": "名称与导入顺序",
+ "standalone": "加载已审查代码与权重",
+ "testing": "安全与验证",
+ "pitfalls": "安全与验证",
+ "contribute": "真实示例与边界"
+ },
+ "model-selection.html": {
+ "default": "fast-default-path",
+ "decision": "decision-table",
+ "aliases": "openai-compatible-api-aliases",
+ "runtime": "runtime-choice-by-workload",
+ "benchmark": "benchmark-before-committing"
+ },
+ "zh/model-selection.html": {
+ "default": "默认快速路径",
+ "decision": "决策表",
+ "aliases": "openai-兼容-api-别名",
+ "runtime": "按工作负载选择运行路径",
+ "benchmark": "上线前先-benchmark"
+ },
+ "moss-transcribe-diarize.html": {
+ "contract": "funasr-automodel-contract",
+ "server": "funasr-openai-compatible-service",
+ "runtimes": "choose-a-serving-path",
+ "evidence": "funasr-openai-compatible-service",
+ "boundaries": "production-validation"
+ },
+ "zh/moss-transcribe-diarize.html": {
+ "contract": "funasr-automodel-契约",
+ "server": "funasr-openai-兼容服务",
+ "runtimes": "选择服务后端",
+ "evidence": "funasr-openai-兼容服务",
+ "boundaries": "上线前验证"
+ },
+ "vllm.html": {
+ "overview": "2-vllm-engine-architecture",
+ "install": "1-installation--environment",
+ "offline": "3-offline-sdk-inference",
+ "streaming-sdk": "4-streaming-sdk-inference",
+ "websocket": "6-streaming-speech-recognition-service",
+ "dynamic-vad": "7-dynamic-vad",
+ "performance": "benchmark",
+ "api-reference": "8-api-reference",
+ "faq": "9-faq"
+ },
+ "zh/vllm.html": {
+ "overview": "2-vllm-推理引擎架构",
+ "install": "1-安装与环境",
+ "offline": "3-离线-sdk-推理",
+ "streaming-sdk": "4-流式-sdk-推理",
+ "websocket": "6-流式语音识别服务",
+ "dynamic-vad": "7-动态-vad",
+ "performance": "benchmark",
+ "api-reference": "8-api-参考",
+ "faq": "9-faq"
+ },
+ "deployment-matrix.html": {
+ "matrix": "quick-decision-table",
+ "choices": "common-choices",
+ "runtime-diagnostics": "readiness-checklist",
+ "checklist": "readiness-checklist",
+ "help": "when-to-open-an-issue"
+ },
+ "zh/deployment-matrix.html": {
+ "matrix": "快速决策表",
+ "choices": "常见选择",
+ "runtime-diagnostics": "上线检查清单",
+ "checklist": "上线检查清单",
+ "help": "什么时候开-issue"
+ }
+ }
+}
diff --git a/web-pages/product-site/documentation.py b/web-pages/product-site/documentation.py
index 4085ae670..1a34a89b0 100644
--- a/web-pages/product-site/documentation.py
+++ b/web-pages/product-site/documentation.py
@@ -24,7 +24,13 @@ def source_slug(value: str, separator: str) -> str:
def load_catalogue() -> dict:
catalogue = json.loads((SITE_ROOT / 'data/documentation.json').read_text())
+ groups = [group['id'] for group in catalogue['groups']]
+ slugs = [entry['slug'] for entry in catalogue['pages']]
+ if len(set(groups)) != len(groups) or len(set(slugs)) != len(slugs):
+ raise ValueError('Duplicate documentation group or slug')
for entry in catalogue['pages']:
+ if entry['group'] not in groups or not re.fullmatch(r'[a-z0-9]+(?:-[a-z0-9]+)*', entry['slug']):
+ raise ValueError(f'Invalid documentation entry: {entry["slug"]}')
for language in ('zh', 'en'):
path = (REPO_ROOT / entry[f'source_{language}']).resolve()
if not path.is_relative_to(REPO_ROOT) or not path.is_file():
@@ -41,10 +47,10 @@ def render_source(entry: dict, language: str, catalogue: dict) -> dict:
parser = Markdown(extensions=['extra', 'toc', 'sane_lists'],
extension_configs={'toc': {'slugify': source_slug}})
soup = BeautifulSoup(parser.convert((REPO_ROOT / relative).read_text()), 'html.parser')
- local_routes = {
- page[f'source_{language}']: doc_route(page['slug'], language)
- for page in catalogue['pages']
- }
+ local_routes = {}
+ for variant in (('en' if language == 'zh' else 'zh'), language):
+ for page in catalogue['pages']:
+ local_routes[page[f'source_{variant}']] = doc_route(page['slug'], variant)
for element, attr in [('a', 'href'), ('img', 'src')]:
for node in soup.select(f'{element}[{attr}]'):
value = str(node[attr])
diff --git a/web-pages/product-site/export_docs.py b/web-pages/product-site/export_docs.py
new file mode 100644
index 000000000..5ee7f42e3
--- /dev/null
+++ b/web-pages/product-site/export_docs.py
@@ -0,0 +1,71 @@
+"""Publish source-rendered guides at established GitHub Pages URLs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import shutil
+from bs4 import BeautifulSoup
+
+ORIGIN = 'https://www.funasr.com'
+ALIASES = {
+ 'quickstart': 'tutorial.html',
+ 'training': 'training.html',
+ 'model-registration': 'model-registration.html',
+ 'model-selection': 'model-selection.html',
+ 'moss-transcribe-diarize': 'moss-transcribe-diarize.html',
+ 'vllm': 'vllm.html',
+ 'deployment-matrix': 'deployment-matrix.html',
+}
+
+
+def insert_legacy_anchors(soup: BeautifulSoup, mapping: dict[str, str]) -> None:
+ """Place legacy fragments next to their current section without changing it."""
+ article = soup.select_one('.docs-article')
+ if article is None:
+ # Non-catalogue HTML has no source-article heading contract.
+ return
+ for old, target in mapping.items():
+ headings = article.find_all(id=target)
+ if len(headings) != 1 or headings[0].name not in ('h2', 'h3'):
+ raise ValueError(f'Legacy fragment {old!r} needs one h2/h3 target {target!r}')
+ existing = soup.find_all(id=old)
+ if len(existing) > 1:
+ raise ValueError(f'Duplicate legacy fragment {old!r}')
+ if existing:
+ continue
+ anchor = soup.new_tag('span', id=old)
+ anchor['data-legacy-doc-anchor'] = target
+ headings[0].insert_before(anchor)
+
+
+def export_documentation(built: Path, output: Path, aliases: dict | None = None) -> None:
+ """Keep API/hub pages intact and publish immutable assets with the guides."""
+ legacy = json.loads((Path(__file__).parent / 'data/legacy_doc_anchors.json').read_text(encoding='utf-8'))
+ if (built / 'assets').is_dir():
+ shutil.copytree(built / 'assets', output / 'assets', dirs_exist_ok=True)
+ for slug, filename in (ALIASES if aliases is None else aliases).items():
+ for source_prefix, target_prefix in (('en/', ''), ('', 'zh/')):
+ source = built / source_prefix / 'docs' / f'{slug}.html'
+ soup = BeautifulSoup(source.read_text(encoding='utf-8'), 'html.parser')
+ insert_legacy_anchors(soup, legacy['pages'].get(target_prefix + filename, {}))
+ for node in soup.find_all(True):
+ for attribute in ('href', 'src', 'action', 'data-copy-icon'):
+ value = node.get(attribute, '')
+ if isinstance(value, str) and value.startswith('/') and not value.startswith('//'):
+ if value.startswith('/assets/'):
+ node[attribute] = ('../' if target_prefix else '') + value.lstrip('/')
+ else:
+ node[attribute] = ORIGIN + value
+ target = output / target_prefix / filename
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(str(soup), encoding='utf-8')
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--site', type=Path, required=True)
+ parser.add_argument('--output', type=Path, required=True)
+ args = parser.parse_args()
+ export_documentation(args.site, args.output)
diff --git a/web-pages/product-site/templates/docs.html b/web-pages/product-site/templates/docs.html
index c07b20cb1..5893fb050 100644
--- a/web-pages/product-site/templates/docs.html
+++ b/web-pages/product-site/templates/docs.html
@@ -3,6 +3,8 @@
<div class="docs-layout">
<aside class="docs-sidebar">
<a class="docs-home" href="{{ '/docs/' if language == 'zh' else '/en/docs/' }}">{{ '文档中心' if language == 'zh' else 'Documentation' }}</a>
+ <details class="docs-navigation" open>
+ <summary class="docs-navigation-toggle">{{ '浏览目录' if language == 'zh' else 'Browse topics' }}</summary>
{% for group in catalogue.groups %}
<details open>
<summary>{{ group[language] }}</summary>
@@ -14,6 +16,7 @@
</details>
{% endfor %}
<a href="{{ '/deploy/' if language == 'zh' else '/en/deploy/' }}">{{ '部署手册' if language == 'zh' else 'Deployment guides' }} &rarr;</a>
+ </details>
</aside>
<div class="docs-body">
<nav class="breadcrumbs" aria-label="{{ '面包屑' if language == 'zh' else 'Breadcrumbs' }}"><a href="{{ '/' if language == 'zh' else '/en/' }}">FunASR</a><span>/</span><a href="{{ '/docs/' if language == 'zh' else '/en/docs/' }}">{{ '文档' if language == 'zh' else 'Docs' }}</a>{% if doc_entry %}<span>/</span><span>{{ doc_entry[language] }}</span>{% endif %}</nav>
diff --git a/web-pages/product-site/tests/browser/documentation.spec.ts b/web-pages/product-site/tests/browser/documentation.spec.ts
index 64cbb0d41..00a41df63 100644
--- a/web-pages/product-site/tests/browser/documentation.spec.ts
+++ b/web-pages/product-site/tests/browser/documentation.spec.ts
@@ -1,5 +1,44 @@
import { expect, test } from '@playwright/test';
+test('mobile topic navigation leaves the article in the first viewport', async ({ page }) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.goto('/docs/training.html');
+ const menu = page.locator('.docs-navigation');
+ await expect(menu).not.toHaveAttribute('open', '');
+ expect((await page.locator('.docs-title h1').boundingBox())!.y).toBeLessThan(300);
+ await menu.locator(':scope > summary').press('Enter');
+ await expect(menu).toHaveAttribute('open', '');
+ await menu.locator('details').filter({ hasText: '训练与扩展' }).locator('summary').click();
+ await page.locator('.docs-sidebar a[href="/docs/model-registration.html"]').click();
+ await expect(page).toHaveURL(/model-registration.html$/);
+ await page.setViewportSize({ width: 1440, height: 900 });
+ await expect(page.locator('.docs-navigation')).toHaveAttribute('open', '');
+ await expect(page.locator('.docs-sidebar summary').filter({ hasText: '训练与扩展' })).toBeVisible();
+});
+
+for (const width of [320, 768, 1440]) {
+ test(`expanded documentation journey fits ${width}px`, async ({ page }) => {
+ await page.setViewportSize({ width, height: 900 });
+ const errors: string[] = [];
+ page.on('pageerror', error => errors.push(error.message));
+ for (const slug of ['installation', 'quickstart', 'python-api', 'model-zoo', 'training', 'model-registration', 'runtime-guide', 'service-api', 'security', 'kubernetes']) {
+ await page.goto(`/docs/${slug}.html`, { waitUntil: 'domcontentloaded' });
+ await expect(page.locator('.docs-article')).toBeVisible();
+ expect(await page.evaluate(() => document.documentElement.scrollWidth - innerWidth), slug).toBeLessThanOrEqual(1);
+ await expect(page.locator('.docs-toc a').first()).toHaveAttribute('href', /^#/);
+ }
+ expect(errors).toEqual([]);
+ });
+}
+
+test('SDK, training and Model Zoo are discoverable through search', async ({ page }) => {
+ for (const [query, slug] of [['AutoModel', 'python-api'], ['Model Zoo', 'model-zoo'], ['fine-tuning', 'training']]) {
+ await page.goto('/en/docs/');
+ await page.locator('[data-doc-search] input').fill(query);
+ await expect(page.locator(`.search-results a[href="/en/docs/${slug}.html"]`)).toBeVisible();
+ }
+});
+
for (const width of [320, 390, 768, 1440, 1920]) {
test(`documentation and legacy layouts fit ${width}px`, async ({ page }) => {
await page.setViewportSize({ width, height: 900 });
diff --git a/web-pages/product-site/tests/test_documentation_coverage.py b/web-pages/product-site/tests/test_documentation_coverage.py
new file mode 100644
index 000000000..aaced6ae3
--- /dev/null
+++ b/web-pages/product-site/tests/test_documentation_coverage.py
@@ -0,0 +1,94 @@
+from pathlib import Path
+import ast
+import json
+import sys
+from urllib.parse import unquote, urlsplit
+
+from bs4 import BeautifulSoup
+from markdown import markdown
+
+SITE = Path(__file__).resolve().parents[1]
+ROOT = SITE.parents[1]
+sys.path.insert(0, str(SITE))
+
+
+def test_catalogue_covers_the_full_user_journey():
+ catalogue = json.loads((SITE / 'data/documentation.json').read_text())
+ slugs = {row['slug'] for row in catalogue['pages']}
+ assert {
+ 'installation', 'quickstart', 'python-api', 'model-zoo', 'training',
+ 'model-registration', 'docker', 'service-api', 'security',
+ 'javascript', 'kubernetes', 'websocket-protocol', 'runtime-guide',
+ } <= slugs
+ assert {'train', 'reference'} <= {group['id'] for group in catalogue['groups']}
+
+
+def test_model_zoo_covers_current_families_without_empty_links():
+ for name in ('readme.md', 'readme_zh.md'):
+ content = (ROOT / 'model_zoo' / name).read_text()
+ for marker in ('Fun-ASR-Nano', 'Fun-ASR-MLT-Nano', 'SenseVoice', 'Paraformer', 'MOSS-Transcribe-Diarize', 'OpenMOSS'):
+ assert marker in content
+ assert ']()' not in content
+ assert '../docs/python_api' in content
+
+
+def test_model_zoo_alias_links_match_the_hub_mapping():
+ tree = ast.parse((ROOT / 'funasr/download/name_maps_from_hub.py').read_text())
+ mapping = next(ast.literal_eval(node.value) for node in tree.body
+ if isinstance(node, ast.Assign) and any(
+ isinstance(target, ast.Name) and target.id == 'name_maps_ms' for target in node.targets))
+ for name in ('readme.md', 'readme_zh.md'):
+ soup = BeautifulSoup(markdown((ROOT / 'model_zoo' / name).read_text(), extensions=['extra']), 'html.parser')
+ for alias in ('paraformer-zh', 'paraformer-zh-streaming'):
+ row = next(row for row in soup.select('tr') if row.select_one('code') and row.select_one('code').get_text() == alias)
+ assert any(f'/models/{mapping[alias]}/' in link['href'] for link in row.select('a[href]'))
+
+
+def test_runtime_index_separates_historical_release_notes():
+ for name, history in (('readme.md', 'release-history.md'), ('readme_cn.md', 'release-history_zh.md')):
+ content = (ROOT / 'runtime' / name).read_text()
+ assert history in content
+ assert 'MOSS' in content and 'llama.cpp' in content and 'vLLM' in content
+ assert (ROOT / 'runtime' / history).is_file()
+ assert './python/websocket/README.md' in content
+ assert '`START`/`STOP`' in content
+
+
+def test_catalogued_repository_links_resolve():
+ from documentation import load_catalogue
+
+ sources = {page[f'source_{lang}'] for page in load_catalogue()['pages'] for lang in ('zh', 'en')}
+ for relative in sources:
+ source = ROOT / relative
+ soup = BeautifulSoup(markdown(source.read_text(), extensions=['extra']), 'html.parser')
+ for tag, attribute in (('a', 'href'), ('img', 'src')):
+ for node in soup.select(f'{tag}[{attribute}]'):
+ link = urlsplit(node[attribute])
+ if link.scheme or link.netloc or not link.path or link.path.startswith('/'):
+ continue
+ destination = (source.parent / unquote(link.path)).resolve()
+ assert destination.is_relative_to(ROOT) and destination.exists(), (relative, node[attribute])
+
+
+def test_compatibility_export_uses_canonical_docs_without_changing_api(tmp_path):
+ from export_docs import export_documentation
+
+ built = tmp_path / 'site'
+ (built / 'docs').mkdir(parents=True)
+ (built / 'en/docs').mkdir(parents=True)
+ (built / 'assets').mkdir()
+ (built / 'assets/example.css').write_text('body { color: black; }')
+ for prefix in ('', 'en/'):
+ (built / prefix / 'docs/quickstart.html').write_text('<html><head><link rel="canonical" href="https://www.funasr.com/docs/quickstart.html"><link rel="stylesheet" href="/assets/example.css"></head><body><a href="/docs/python-api.html">API</a><a href="#step">Step</a><h1 id="step">Guide</h1></body></html>')
+ output = tmp_path / 'pages'
+ output.mkdir()
+ (output / 'api.html').write_text('existing generated API')
+ export_documentation(built, output, aliases={'quickstart': 'tutorial.html'})
+ for relative in ('tutorial.html', 'zh/tutorial.html'):
+ soup = BeautifulSoup((output / relative).read_text(), 'html.parser')
+ assert soup.select_one('a[href="https://www.funasr.com/docs/python-api.html"]')
+ assert soup.select_one('a[href="#step"]')
+ asset = soup.select_one('link[rel="stylesheet"]')['href']
+ assert not asset.startswith(('/', 'http'))
+ assert ((output / relative).parent / asset).read_text() == 'body { color: black; }'
+ assert (output / 'api.html').read_text() == 'existing generated API'
diff --git a/web-pages/product-site/tests/test_legacy_doc_anchors.py b/web-pages/product-site/tests/test_legacy_doc_anchors.py
new file mode 100644
index 000000000..be83abb54
--- /dev/null
+++ b/web-pages/product-site/tests/test_legacy_doc_anchors.py
@@ -0,0 +1,147 @@
+"""Compatibility contracts for the published pre-catalogue guide URLs."""
+
+import json
+from pathlib import Path
+import sys
+
+from bs4 import BeautifulSoup
+import pytest
+
+SITE = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SITE))
+
+# IDs independently inventoried from gh-pages at 871ac766876c2f511550478d88c86aa3daab3172.
+OLD_IDS = {
+ 'tutorial.html': 'quick install choose scenarios offline streaming spk emotion vad punc deploy-agent subtitle export faq',
+ 'training.html': 'overview data paraformer sensevoice nano params multi-gpu deepspeed monitor inference-after tips',
+ 'model-registration.html': 'architecture setup understand add-model add-component standalone testing pitfalls contribute',
+ 'model-selection.html': 'default decision aliases runtime benchmark',
+ 'moss-transcribe-diarize.html': 'contract server runtimes evidence boundaries',
+ 'vllm.html': 'overview install offline streaming-sdk websocket dynamic-vad performance api-reference faq',
+ 'deployment-matrix.html': 'matrix choices runtime-diagnostics checklist help',
+}
+PAGES = [prefix + name for name in OLD_IDS for prefix in ('', 'zh/')]
+
+
[email protected](scope='module')
+def exported(tmp_path_factory):
+ from documentation import load_catalogue, render_source
+ from export_docs import ALIASES, export_documentation
+
+ root = tmp_path_factory.mktemp('legacy-docs')
+ built, output = root / 'built', root / 'pages'
+ catalogue = load_catalogue()
+ entries = {entry['slug']: entry for entry in catalogue['pages']}
+ originals = {}
+ for slug, filename in ALIASES.items():
+ for language, source_prefix, target_prefix in (('en', 'en/', ''), ('zh', '', 'zh/')):
+ content = render_source(entries[slug], language, catalogue)['content_html']
+ html = ('<html><head><link rel="stylesheet" href="/assets/site.123.css">'
+ '<script src="/assets/experience.456.js" defer></script></head><body>'
+ '<a href="/docs/python-api.html">API</a>'
+ f'<article class="docs-article">{content}</article></body></html>')
+ path = built / source_prefix / 'docs' / f'{slug}.html'
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(html, encoding='utf-8')
+ originals[target_prefix + filename] = (path, html)
+ (built / 'assets').mkdir()
+ (built / 'assets/site.123.css').write_text('body { color: black; }')
+ (built / 'assets/experience.456.js').write_text('"use strict";')
+ for name in ('api.html', 'zh/api.html', 'reference/AutoModel.html', 'index.html'):
+ path = output / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_bytes(b'existing reference\n')
+ export_documentation(built, output)
+ return built, output, originals
+
+
[email protected]('page', PAGES)
+def test_every_published_fragment_survives(exported, page):
+ _, output, _ = exported
+ soup = BeautifulSoup((output / page).read_text(), 'html.parser')
+ ids = [node['id'] for node in soup.select('[id]')]
+ expected = set(OLD_IDS[Path(page).name].split())
+ assert expected <= set(ids), (page, sorted(expected - set(ids)))
+ assert len(ids) == len(set(ids)), page
+
+
[email protected]('page', PAGES)
+def test_aliases_precede_their_semantic_headings(exported, page):
+ _, output, _ = exported
+ manifest = json.loads((SITE / 'data/legacy_doc_anchors.json').read_text())
+ mapping = manifest['pages'][page]
+ assert set(mapping) == set(OLD_IDS[Path(page).name].split())
+ soup = BeautifulSoup((output / page).read_text(), 'html.parser')
+ article = soup.select_one('.docs-article')
+ for old, target in mapping.items():
+ anchor = article.find(id=old)
+ heading = article.find(id=target)
+ assert anchor is not None and heading is not None, (page, old, target)
+ assert heading.name in ('h2', 'h3'), (page, target)
+ assert anchor.name == 'span' and not anchor.get_text(), (page, old)
+ sibling = anchor.find_next_sibling()
+ while sibling is not None and sibling.name == 'span' and sibling.get('data-legacy-doc-anchor') is not None:
+ sibling = sibling.find_next_sibling()
+ assert sibling is heading, (page, old, target)
+
+
+def test_export_preserves_source_content_api_and_local_assets(exported):
+ _, output, originals = exported
+ for page, (path, original) in originals.items():
+ assert path.read_text() == original
+ before = BeautifulSoup(original, 'html.parser')
+ after = BeautifulSoup((output / page).read_text(), 'html.parser')
+ assert after.select_one('.docs-article').get_text() == before.select_one('.docs-article').get_text()
+ assert [(n.name, n['id'], n.get_text()) for n in after.select('h2[id],h3[id]')] == [
+ (n.name, n['id'], n.get_text()) for n in before.select('h2[id],h3[id]')]
+ assert [n.get_text() for n in after.select('pre')] == [n.get_text() for n in before.select('pre')]
+ assert after.select_one('a[href="https://www.funasr.com/docs/python-api.html"]')
+ for node, attribute in ((after.select_one('link[rel=stylesheet]'), 'href'), (after.script, 'src')):
+ assert not node[attribute].startswith(('/', 'http'))
+ assert ((output / page).parent / node[attribute]).is_file()
+ for node in after.select('[data-legacy-doc-anchor]'):
+ node.decompose()
+ # Apart from the existing root-link rewrite, the article DOM is unchanged.
+ for node in before.select('[href], [src]'):
+ for attribute in ('href', 'src'):
+ value = node.get(attribute, '')
+ if value.startswith('/') and not value.startswith('//'):
+ node[attribute] = 'https://www.funasr.com' + value
+ assert str(after.select_one('.docs-article')) == str(before.select_one('.docs-article'))
+ for name in ('api.html', 'zh/api.html', 'reference/AutoModel.html', 'index.html'):
+ assert (output / name).read_bytes() == b'existing reference\n'
+
+
+def test_training_alias_and_moss_mappings_are_topic_specific():
+ pages = json.loads((SITE / 'data/legacy_doc_anchors.json').read_text())['pages']
+ for prefix, data, params, aliases, server in (
+ ('', 'prepare-the-dataset', 'validate-small-then-launch', 'openai-compatible-api-aliases', 'funasr-openai-compatible-service'),
+ ('zh/', '准备数据', '先做小规模验证', 'openai-兼容-api-别名', 'funasr-openai-兼容服务'),
+ ):
+ assert pages[prefix + 'training.html']['data'] == data
+ assert pages[prefix + 'training.html']['params'] == params
+ assert pages[prefix + 'model-selection.html']['aliases'] == aliases
+ assert pages[prefix + 'moss-transcribe-diarize.html']['server'] == server
+ assert pages[prefix + 'moss-transcribe-diarize.html']['evidence'] == server
+
+
+def test_insertion_is_idempotent_and_keeps_existing_anchors():
+ from export_docs import insert_legacy_anchors
+
+ soup = BeautifulSoup('<article class="docs-article"><a id="existing"></a><h2 id="topic">Topic</h2></article>', 'html.parser')
+ mapping = {'old': 'topic', 'existing': 'topic'}
+ insert_legacy_anchors(soup, mapping)
+ first = str(soup)
+ insert_legacy_anchors(soup, mapping)
+ assert str(soup) == first
+ assert len(soup.select('#existing')) == 1
+ assert soup.find(id='existing').name == 'a'
+
+
[email protected]('heading', ('<h2 id="different">Topic</h2>', '<p id="topic">Not a heading</p>'))
+def test_missing_or_nonheading_target_fails_explicitly(heading):
+ from export_docs import insert_legacy_anchors
+
+ soup = BeautifulSoup(f'<article class="docs-article">{heading}</article>', 'html.parser')
+ with pytest.raises(ValueError, match='topic'):
+ insert_legacy_anchors(soup, {'old': 'topic'})