SOUND / Zipformer

Zipformer

reComputer RK3588

在 reComputer RK3576 和 RK3588 上通过 RKNN 加速的中英双语流式语音识别模型。

18 次下载

精度

RKNN

选择你正在使用的设备，设置指南和文档将相应更新。

平台

推理引擎

快速开始

Armbian 26.8.7 Gnome 及更新版本（启用 OTA overlayroot）： 运行容器前请配置 Docker 存储以避免 overlay 挂载错误。

部署

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-zipformer:latest

REST API

使用 REST API 进行推理。复制以下命令。

Curl

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "zipformer-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "zipformer-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

模型详情

Armbian 26.8.7 Gnome 及更新版本（启用 OTA overlayroot）： 运行容器前请配置 Docker 存储以避免 overlay 挂载错误。

快速开始

1. 安装 Docker

在开发板上运行以下命令安装 Docker：

bash

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. 运行项目（一条命令，双模式预览）

本项目提供中英双语语音识别。Web 界面支持上传文件的完整转录，以及带有中间结果的浏览器麦克风流式转录。

步骤 A：拉取镜像

bash

sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-zipformer:latest
sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-zipformer:latest

步骤 B：一键运行

适用于 RK3588:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-zipformer:latest

访问地址： http://<Board_IP>:8000

适用于 RK3576:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-zipformer:latest

访问地址： http://<Board_IP>:8000

浏览器通过 WebSocket 发送麦克风 PCM，因此无需映射主机 /dev/snd。

3. 命令行推理

bash

python inference.py --platform rk3576 --model_dir model \
    --file samples/test.wav

在 RK3588 源目录中运行时，请使用 --platform rk3588。

🔌 API 文档

服务提供用于完整文件转录的 REST 接口和用于流式 PCM 的 WebSocket 接口。OpenAPI 在 http://<Board_IP>:8000/docs 描述 REST 路由。

1. 文件转录接口

端点： POST /api/models/zipformer/predict

请求参数（Multipart/Form-Data）：

file：必填音频文件。服务在推理前解码文件并重采样至 16 kHz，上传大小上限为 64 MB。

使用示例：

bash

curl -X POST "http://127.0.0.1:8000/api/models/zipformer/predict" \
    -F 'file=@samples/test.wav'

响应格式（JSON）：

json

{
  "success": true,
  "model": "zipformer",
  "platform": "rk3576",
  "inference_time_ms": 164.3,
  "result": {
    "text": "example transcript",
    "tokens": [12, 34],
    "timestamps": [3, 8],
    "audio_duration_seconds": 2.4,
    "processed": true
  }
}

2. 流式转录接口

端点： WS /api/models/zipformer/stream

将单声道 16 kHz、有符号 16 位小端 PCM 作为二进制 WebSocket 消息发送。采集完成后，发送：

json

{"action":"stop"}

发送 {"action":"reset"} 可丢弃当前流式会话并重新开始。服务端消息使用以下类型：

ready：会话就绪，并报告 sample_rate: 16000 和 format: pcm_s16le。
partial：在处理足够的音频后，包含更新的结果。
final：包含执行 stop 操作后的完整结果。
error：报告无效的 PCM 帧结构或运行时故障。

3. 系统状态与配置

健康端点： GET /api/health
配置端点： GET /api/config
当前配置响应： {}，因为 Zipformer 没有可热更新的运行时设置。

向 POST /api/config 发送非空数据会被拒绝。服务启动时会一并加载编码器、解码器、joiner 和词表。

🛠️ 开发者指南（生产环境建议）

代码说明

web_service.py：
- REST API：解码上传音频并返回完整转录文本。
- WebSocket API：维护流式会话，并发出 ready、partial、final 和 error 消息。
task_runtime.py：
- 音频处理：为单声道 16 kHz 音频生成兼容 Kaldi 的滤波器组特征。
- 流式状态：在各数据块之间保留编码器缓存、词元历史和时间戳。
- RKNN 推理：运行编码器、解码器和 joiner 流水线。
inference.py：提供单次命令行文件转录。

模型文件

组件	文件
编码器	`model/encoder.rknn`
解码器	`model/decoder.rknn`
Joiner	`model/joiner.rknn`
双语词表	`model/vocab.txt`

修改模型

使用上述文件名，将转换后的编码器、解码器和 joiner 模型放入 model/。
三个 RKNN 文件应与同一词表和流式缓存约定保持配套。
验证完整文件推理和二进制 PCM WebSocket 流式传输。

这些文件是同一 Zipformer 流水线的各个阶段，不是不同的模型尺寸。上游项目目前为每个平台提供一套模型，没有独立的量化规格选择器。

构建本地镜像

在 reComputer-RK-CV 根目录运行：

bash

docker build -f docker/rk3576/zipformer.dockerfile \
    -t rk3576-zipformer:local src/rk3576_zipformer

docker build -f docker/rk3588/zipformer.dockerfile \
    -t rk3588-zipformer:local src/rk3588_zipformer

输入与输出

输入：音频文件或单声道 16 kHz 有符号 16 位小端 PCM。输出：中英文文本、词元 ID、时间戳和处理时长。