企业官网建设流程全解析

FunASR HTML5 客户端接入指南：wss 语音识别服务与网页端实时/离线转写实战

【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

本文围绕 FunASR 的 HTML5 客户端访问界面展开，介绍如何通过 WebSocket（wss）协议部署 Python/C++ 语音识别服务，并使用 FunASR 内置的网页客户端完成麦克风实时识别与离线文件转写。读完本篇后，你将能够独立启动 FunASR wss 服务端与 HTML5 静态服务（h5Server.py），在浏览器（含手机端）中完成 2pass、online、offline 三种识别模式的接入测试，并理解客户端音频采集、分块发送与服务端协议交互的完整链路。

两种客户端接入方式概述

FunASR 的服务端部署采用 WebSocket 协议，客户端支持 HTML5 网页访问，可同时支持麦克风输入与文件输入。接入服务共有两种方式：

• 方式一：html 客户端直连。手动下载 FunASR 仓库中的客户端静态目录 runtime/html5/static 至本地，直接打开其中的index.html网页，在页面上输入 wss 服务地址与端口号即可使用。
• 方式二：html5 服务端托管。启动h5Server.pyHTML5 服务，由它自动将客户端静态页面分发到本地/远端，支持手机等设备通过局域网或公网地址访问。

两种方式最终连接的都是同一个 FunASR wss ASR 服务，区别仅在于静态页面（index.html及配套 JS）的分发方式。

语音识别服务启动

FunASR 支持 Python 版本与 C++ 版本两种服务部署，二者定位不同：

• Python 版本：直接部署 Python pipeline，支持流式实时语音识别模型、离线语音识别模型、流式离线一体化纠错（2pass）模型，并可输出带标点的文字。单个 server，支持单个 client 连接，适合功能验证与快速调试。
• C++ 版本：基于 funasr-runtime-sdk，支持一键部署（当前 0.1.0 版本），支持离线文件转写。单个 server，可支撑上百路 client 并发请求，适合生产环境服务化。

Python 版本服务启动

安装依赖环境

pip3 install -U modelscope funasr flask # 中国大陆用户，如果遇到网络问题，可以通过下面指令安装： # pip3 install -U modelscope funasr -i https://mirror.sjtu.edu.cn/pypi/web/simple git clone https://gitcode.com/GitHub_Trending/fun/FunASR.git && cd FunASR

启动 ASR 服务（wss 方式）

cd funasr/runtime/python/websocket python funasr_wss_server.py --port 10095

该服务的完整实现在 funasr_wss_server.py，更多参数配置与客户端示例可参考 runtime/python/websocket 目录下的 README 与funasr_wss_client.py。

从源码的参数定义（funasr_wss_server.py）可以看到，服务默认加载一套覆盖 VAD + 流式 ASR + 离线 ASR + 标点的完整模型组合：

其中并发控制参数表明该服务内部通过ThreadPoolExecutor与分模块并发上限来避免阻塞事件循环，虽然文档定位是“单 server 单 client”，但底层实现已具备一定的多连接调度能力。

关于 SSL 证书：wss 协议要求服务端提供证书，仓库内置了 runtime/html5/ssl_key 下的server.crt/server.key。若需自行生成证书，可参考 ssl_key/readme.md 中的 openssl 命令：

### 1) Generate a private key openssl genrsa -des3 -out server.key 2048 ### 2) Generate a csr file openssl req -new -key server.key -out server.csr ### 3) Remove pass cp server.key server.key.org openssl rsa -in server.key.org -out server.key ### 4) Generated a crt file, valid for 1 year openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

该文档同时提醒：自行生成的自签证书可能因浏览器安全策略不被所有浏览器接受，生产环境建议使用正规机构签发的证书。

启动 HTML5 服务（可选）

如果需要使用前文“方式二”访问，可以启动 HTML5 静态服务：

h5Server.py [-h] [--host HOST] [--port PORT] [--certfile CERTFILE] [--keyfile KEYFILE]

示例如下。注意 IP 地址的设置：如果从其他设备（例如手机端）访问，需要将 IP 地址设为真实公网/局域网可达 IP：

cd funasr/runtime/html5 python h5Server.py --host 0.0.0.0 --port 1337

启动后，在浏览器中访问https://127.0.0.1:1337/static/index.html即可进入客户端页面。

从源码 h5Server.py 看，该服务实现非常轻量：

• 基于 Flask 构建，static_folder="static"、static_url_path="/static"，即把 runtime/html5/static 目录整体作为静态资源根目录对外分发（h5Server.py）；
• 访问根路径/时 302 重定向到/static/index.html；
• 四个命令行参数均有默认值：--host默认0.0.0.0，--port默认1337，--certfile默认./ssl_key/server.crt，--keyfile默认./ssl_key/server.key（h5Server.py）；
• 最终以ssl_context=(certfile, keyfile)启动，因此该服务本身就是一个 HTTPS 服务（h5Server.py）。这一点很关键：只有页面本身通过 https 加载时，浏览器才允许调用麦克风和发起 wss 连接。

C++ 版本服务启动

由于 C++ 依赖环境较多，官方建议采用 Docker 部署，支持一键启动服务：

curl -O https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/shell/funasr-runtime-deploy-offline-cpu-zh.sh; sudo bash funasr-runtime-deploy-offline-cpu-zh.sh install --workspace /root/funasr-runtime-resources

该脚本在仓库中的对应版本为 funasr-runtime-deploy-offline-cpu-zh.sh。详细参数配置与解析请参考 C++ SDK 教程 runtime/docs/SDK_tutorial_zh.md 以及 runtime/docs 目录下的其他 SDK 文档。

客户端测试

方式一：静态客户端直连

手动下载 runtime/html5/static 目录到本地计算机，打开index.html网页，输入 wss 地址与端口号（例如wss://127.0.0.1:10095/）即可使用。

方式二：通过 HTML5 服务端访问

启动h5Server.py后，通过https://127.0.0.1:1337/static/index.html访问。IP 地址需要与 html5 server 保持一致，如果是本地机器可以用127.0.0.1；手机等设备则填写服务器的局域网/公网 IP。进入页面后同样输入 wss 地址与端口号即可。

页面加载后，客户端会做一些便捷处理：从 main.js 可见，页面会自动把当前访问的https://前缀转换为wss://，并把端口替换为默认的10095填入输入框，方便“本机部署、本机访问”的常见场景。

客户端功能与协议交互细节

结合 runtime/html5/static 下的前端源码，可以完整理解这个网页客户端的能力边界与协议细节：

页面能力（index.html）：

• ASR 服务器地址输入框（必填），下方提供“点此处手工授权”链接，用于 iOS 等场景下先手工访问一次 wss 地址完成证书授权；
• 录音模式：麦克风（默认）或文件；
• ASR 模型模式（麦克风模式下可选）：2pass（默认，流式 + 离线一体化纠错）、online（纯流式）、offline（离线）；
• ITN 开关：逆文本标准化，默认关闭；
• 热词设置：一行一个关键字，空格隔开权重，如阿里巴巴 20；
• 识别结果显示区与录音回放播放器。

音频采集与分块发送（main.js）：

• 麦克风模式使用Recorder({type:"pcm", bitRate:16, sampleRate:16000})采集 16kHz 16bit PCM 数据；recProcess回调中会将录音缓冲区按chunk_size=960采样（即 60ms @16k）切块，通过 WebSocket 逐块发送；
• 文件模式下，客户端读取文件字节流（wav 文件还会解析文件头获取采样率，main.js），同样以 960 字节为块发送；收到is_final=true的响应后自动停止连接并播放原音频以便人工核对。

WebSocket 控制消息协议（wsconnecter.js）：连接建立成功（onOpen）后，客户端会先发送一条 JSON 配置消息，关键字段包括：

var request = { "chunk_size": [5, 10, 5], // 流式模型 chunk 配置 "wav_name": "h5", "is_speaking": true, // 会话开始 "chunk_interval": 10, "itn": getUseITN(), // ITN 开关 "mode": getAsrMode() // "2pass" / "online" / "offline"，文件模式强制 "offline" }; // 文件模式附加字段 request.wav_format = file_ext; // 如 "PCM"（wav 文件） request.audio_fs = file_sample_rate; // wav 文件采样率 // 热词附加字段 request.hotwords = JSON.stringify({"阿里巴巴": 20, "hello world": 40});

停止识别时，客户端发送is_speaking: false的 JSON 消息通知服务端结束会话（main.js）。服务端返回的消息为 JSON 格式，包含text（识别文本）、mode、is_final、timestamp字段；客户端会区分2pass-offline/offline结果（累计到 offline_text 并按时间戳展示）与流式增量结果（main.js）。

连接地址格式：wsconnecter.js要求输入以wss://或ws://开头，否则弹出“请检查wss地址正确性”的提示（wsconnecter.js）。由于 wss 依赖 TLS，本地自签证书场景下部分浏览器（尤其是 iOS Safari）需要先用页面上“点此处手工授权”链接访问一次 wss 地址、手动信任证书后再连接。

总结与适用边界

• Python wss 服务（funasr_wss_server.py）功能完整，支持 2pass/online/offline 三种模式、标点、ITN、热词，适合开发验证与单机体验；其官方定位是单 client 服务。
• HTML5 客户端是纯前端实现（index.html+ 5 个 JS 文件，基于录音库 pcm 编码），无构建依赖，直连或经 h5Server.py 托管均可使用，且支持手机端浏览器访问。
• C++ 版 funasr-runtime-sdk 面向生产部署，通过 Docker 一键安装，可承载上百路并发请求，是网页端体验与规模化服务之间的选择。
• 常见问题：连不上 wss 时，优先检查证书是否被浏览器信任、端口是否放行、--host是否设为0.0.0.0、手机访问时 IP 是否为可达的局域网/公网地址。

致谢

本项目由 FunASR 社区维护，HTML5 demo 由 AiHealthx 贡献。

【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR