update SDK_advanced_guide_offline_zh.md

funasr/runtime/docs/SDK_advanced_guide_offline_zh.md

@@ -2,11 +2,47 @@
 
 FunASR提供可一键本地或者云端服务器部署的中文离线文件转写服务，内核为FunASR已开源runtime-SDK。FunASR-runtime结合了达摩院语音实验室在Modelscope社区开源的语音端点检测(VAD)、Paraformer-large语音识别(ASR)、标点检测(PUNC) 等相关能力，可以准确、高效的对音频进行高并发转写。
 
-本文档为FunASR离线文件转写服务开发指南。如果您想快速体验离线文件转写服务，请参考FunASR离线文件转写服务一键部署示例（[点击此处](./SDK_tutorial_cn.md)）。
+本文档为FunASR离线文件转写服务开发指南。如果您想快速体验离线文件转写服务，可参考[快速上手](#快速上手)。
 
+## 快速上手
+### 镜像启动
+
+通过下述命令拉取并启动FunASR runtime-SDK的docker镜像：
+
+```shell
+sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0
+
+sudo docker run -p 10095:10095 -it --privileged=true -v /root:/workspace/models registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0
+```
+如果您没有安装docker，可参考[Docker安装](#Docker安装)
+
+### 服务端启动
+
+docker启动之后，启动 funasr-wss-server服务程序：
+```shell
+cd FunASR/funasr/runtime
+./run_server.sh \
+  --download-model-dir /workspace/models \
+  --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
+  --model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx  \
+  --punc-dir damo/punc_ct-transformer_zh-cn-common-vocab272727-onnx
+```
+服务端详细参数介绍可参考[服务端参数介绍](#服务端参数介绍)
+### 客户端测试与使用
+
+下载客户端测试工具目录samples
+```shell
+wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gz
+```
+我们以Python语言客户端为例，进行说明，支持多种音频格式输入（.wav, .pcm, .mp3等），也支持视频输入(.mp4等)，以及多文件列表wav.scp输入，其他版本客户端请参考文档（[点击此处](#客户端用法详解)）,定制服务部署请参考[如何定制服务部署](#如何定制服务部署)
+```shell
+python3 wss_client_asr.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "../audio/asr_example.wav" --output_dir "./results"
+```
+
+------------------
 ## Docker安装
 
-下述步骤为手动安装docker及docker镜像的步骤，如您docker镜像已启动，可以忽略本步骤：
+下述步骤为手动安装docker环境的步骤：
 
 ### docker环境安装
 ```shell
@@ -30,36 +66,63 @@ brew install --cask --appdir=/Applications docker
 sudo systemctl start docker
 ```
 
-### 镜像拉取及启动
 
-通过下述命令拉取并启动FunASR runtime-SDK的docker镜像：
+## 客户端用法详解
+
+在服务器上完成FunASR服务部署以后，可以通过如下的步骤来测试和使用离线文件转写服务。
+目前分别支持以下几种编程语言客户端
+
+- [Python](#python-client)
+- [CPP](#cpp-client)
+- [html网页版本](#Html网页版)
+- [Java](#Java-client)
+
+### python-client
+若想直接运行client进行测试，可参考如下简易说明，以python版本为例：
 
 ```shell
-sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0
+python3 wss_client_asr.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "../audio/asr_example.wav" --output_dir "./results"
+```
 
-sudo docker run -p 10095:10095 -it --privileged=true -v /root:/workspace/models registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.1.0
+命令参数说明：
+```text
+--host 为FunASR runtime-SDK服务部署机器ip，默认为本机ip（127.0.0.1），如果client与服务不在同一台服务器，需要改为部署机器ip
+--port 10095 部署端口号
+--mode offline表示离线文件转写
+--audio_in 需要进行转写的音频文件，支持文件路径，文件列表wav.scp
+--output_dir 识别结果保存路径
 ```
 
-命令参数介绍：
+### cpp-client
+进入samples/cpp目录后，可以用cpp进行测试，指令如下：
+```shell
+./funasr-wss-client --server-ip 127.0.0.1 --port 10095 --wav-path ../audio/asr_example.wav
+```
+
+命令参数说明：
+
 ```text
--p <宿主机端口>:<映射到docker端口>
-如示例，宿主机(ecs)端口10095映射到docker端口10095上。前提是确保ecs安全规则打开了10095端口。
--v <宿主机路径>:<挂载至docker路径>
-如示例，宿主机路径/root挂载至docker路径/workspace/models
+--server-ip 为FunASR runtime-SDK服务部署机器ip，默认为本机ip（127.0.0.1），如果client与服务不在同一台服务器，需要改为部署机器ip
+--port 10095 部署端口号
+--wav-path 需要进行转写的音频文件，支持文件路径
 ```
 
+### Html网页版
 
-## 服务端启动
+在浏览器中打开 html/static/index.html，即可出现如下页面，支持麦克风输入与文件上传，直接进行体验
+
+<img src="images/html.png"  width="900"/>
+
+### Java-client
 
-docker启动之后，启动 funasr-wss-server服务程序：
 ```shell
-cd FunASR/funasr/runtime
-./run_server.sh --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
-  --model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx  \
-  --punc-dir damo/punc_ct-transformer_zh-cn-common-vocab272727-onnx
+FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline
 ```
+详细可以参考文档（[点击此处](../java/readme.md)）
 
-详细命令参数介绍：
+
+
+## 服务端参数介绍：
 
 funasr-wss-server支持从Modelscope下载模型，设置模型下载地址（--download-model-dir，默认为/workspace/models）及model ID（--model-dir、--vad-dir、--punc-dir）,示例如下：
 ```shell
@@ -91,7 +154,7 @@ cd /workspace/FunASR/funasr/runtime/websocket/build/bin
 --keyfile <string> # ssl的密钥文件，默认为：../../../ssl_key/server.key
 ```
 
-funasr-wss-server同时也支持从本地路径加载模型（本地模型资源准备详见[模型资源准备](#anchor-1)）示例如下：
+funasr-wss-server同时也支持从本地路径加载模型（本地模型资源准备详见[模型资源准备](#模型资源准备)）示例如下：
 ```shell
 cd /workspace/FunASR/funasr/runtime/websocket/build/bin
 ./funasr-wss-server  \
@@ -119,19 +182,19 @@ cd /workspace/FunASR/funasr/runtime/websocket/build/bin
 --keyfile <string> # ssl的密钥文件，默认为：../../../ssl_key/server.key
 ```
 
-## <a id="anchor-1">模型资源准备</a>
+##模型资源准备
 
 如果您选择通过funasr-wss-server从Modelscope下载模型，可以跳过本步骤。
 
 FunASR离线文件转写服务中的vad、asr和punc模型资源均来自Modelscope，模型地址详见下表：
 
-| 模型 | Modelscope链接                                                                                                     |
-|------|------------------------------------------------------------------------------------------------------------------|
-| VAD  | https://www.modelscope.cn/models/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary |
-| ASR  | https://www.modelscope.cn/models/damo/speech_fsmn_vad_zh-cn-16k-common-pytorch/summary                           |
-| PUNC | https://www.modelscope.cn/models/damo/punc_ct-transformer_zh-cn-common-vocab272727-pytorch/summary               |
+| 模型 | Modelscope链接                                                                                                  |
+|------|---------------------------------------------------------------------------------------------------------------|
+| VAD  | https://www.modelscope.cn/models/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx/summary |
+| ASR  | https://www.modelscope.cn/models/damo/speech_fsmn_vad_zh-cn-16k-common-onnx/summary                           |
+| PUNC | https://www.modelscope.cn/models/damo/punc_ct-transformer_zh-cn-common-vocab272727-onnx/summary               |
 
-离线文件转写服务中部署的是量化后的ONNX模型，下面介绍下如何导出ONNX模型及其量化：您可以选择从Modelscope导出ONNX模型、从本地文件导出ONNX模型或者从finetune后的资源导出模型：
+离线文件转写服务中部署的是量化后的ONNX模型，下面介绍下如何导出ONNX模型及其量化：您可以选择从Modelscope导出ONNX模型、从finetune后的资源导出模型：
 
 ### 从Modelscope导出ONNX模型
 
@@ -154,22 +217,6 @@ python -m funasr.export.export_model \
 --type 模型类型，目前支持 ONNX、torch
 --quantize  int8模型量化
 ```
-
-### 从本地文件导出ONNX模型
-
-设置model name为模型本地路径，导出量化后的ONNX模型：
-
-```shell
-python -m funasr.export.export_model --model-name /workspace/models/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch --export-dir ./export --type onnx --quantize True
-```
-命令参数介绍：
-```text
---model-name  模型本地路径，例如/workspace/models/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch
---export-dir  ONNX模型导出地址
---type 模型类型，目前支持 ONNX、torch
---quantize  int8模型量化
-```
-
 ### 从finetune后的资源导出模型
 
 假如您想部署finetune后的模型，可以参考如下步骤：
@@ -180,36 +227,18 @@ python -m funasr.export.export_model --model-name /workspace/models/speech_paraf
 python -m funasr.export.export_model --model-name /path/to/finetune/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch --export-dir ./export --type onnx --quantize True
 ```
 
-## 客户端启动
 
-在服务器上完成FunASR离线文件转写服务部署以后，可以通过如下的步骤来测试和使用离线文件转写服务。目前FunASR-bin支持多种方式启动客户端，如下是基于python-client、c++-client的命令行实例及自定义客户端Websocket通信协议：
 
-### python-client
-```shell
-python wss_client_asr.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "./data/wav.scp" --send_without_sleep --output_dir "./results"
-```
-命令参数介绍：
-```text
---host # 服务端ip地址，本机测试可设置为 127.0.0.1
---port # 服务端监听端口号
---audio_in # 音频输入，输入可以是：wav路径 或者 wav.scp路径（kaldi格式的wav list，wav_id \t wav_path）
---output_dir # 识别结果输出路径
---ssl # 是否使用SSL加密，默认使用
---mode # offline模式
-```
+## 如何定制服务部署
 
-### c++-client：
-```shell
-. /funasr-wss-client --server-ip 127.0.0.1 --port 10095 --wav-path test.wav --thread-num 1 --is-ssl 1
-```
-命令参数介绍：
-```text
---server-ip # 服务端ip地址，本机测试可设置为 127.0.0.1
---port # 服务端监听端口号
---wav-path # 音频输入，输入可以是：wav路径 或者 wav.scp路径（kaldi格式的wav list，wav_id \t wav_path）
---thread-num # 客户端线程数
---is-ssl # 是否使用SSL加密，默认使用
-```
+FunASR-runtime的代码已开源，如果服务端和客户端不能很好的满足您的需求，您可以根据自己的需求进行进一步的开发：
+### c++ 客户端：
+
+https://github.com/alibaba-damo-academy/FunASR/tree/main/funasr/runtime/websocket
+
+### python 客户端：
+
+https://github.com/alibaba-damo-academy/FunASR/tree/main/funasr/runtime/python/websocket
 
 ### 自定义客户端：
 
@@ -224,16 +253,6 @@ bytes数据
 {"is_speaking": False}
 ```
 
-## 如何定制服务部署
-
-FunASR-runtime的代码已开源，如果服务端和客户端不能很好的满足您的需求，您可以根据自己的需求进行进一步的开发：
-### c++ 客户端：
-
-https://github.com/alibaba-damo-academy/FunASR/tree/main/funasr/runtime/websocket
-
-### python 客户端：
-
-https://github.com/alibaba-damo-academy/FunASR/tree/main/funasr/runtime/python/websocket
 ### c++ 服务端：
 
 #### VAD