SenseVoice-Small ONNX模型部署：Ubuntu 20.04服务器环境保姆级教程

SenseVoice-Small ONNX模型部署：Ubuntu 20.04服务器环境保姆级教程

最近在折腾语音相关的AI应用，发现了一个挺有意思的模型叫SenseVoice-Small。它是个轻量级的语音识别模型，支持多种语言，而且推理速度挺快。最关键的是，它提供了ONNX格式的量化版本，部署起来相对友好，对硬件要求也没那么高。

如果你手头正好有一台Ubuntu 20.04的服务器，不管是云服务器还是本地的工作站，想快速把它跑起来，那这篇教程就是为你准备的。我会带你从零开始，一步步搞定环境、拉取镜像、启动服务，最后验证效果。整个过程不需要你事先精通Docker或者CUDA，跟着做就行。

1. 开始前的准备工作

在动手之前，我们先看看需要准备些什么。这就像做饭前得先备好菜和锅一样。

首先，你需要一台安装了Ubuntu 20.04操作系统的服务器。这个版本比较稳定，社区支持也好。服务器的配置方面，建议至少有以下硬件：

• CPU：4核或以上。
• 内存：8GB或以上。模型本身不大，但运行时的缓存和预处理会占用一些内存。
• GPU：虽然不是必须的，但如果有NVIDIA GPU，推理速度会快很多。显存建议4GB起步。
• 存储：至少20GB的可用磁盘空间，用来存放系统、Docker镜像和模型文件。

软件方面，我们需要确保服务器能访问网络，因为要下载不少东西。另外，你需要拥有服务器的管理员权限（也就是能使用sudo命令）。

最后，明确一下我们这篇教程的目标：在Ubuntu 20.04上，通过Docker的方式，一键部署好SenseVoice-Small ONNX量化模型的服务，并确保它能稳定运行，可以通过网络接口进行调用。

2. 服务器基础环境搭建

万事开头难，但第一步往往是最关键的。我们先来把服务器的“地基”打好。

2.1 系统更新与基础工具安装

首先，我们通过SSH连接到你的Ubuntu 20.04服务器。连接成功后，第一件事就是更新系统的软件包列表，并升级已有的软件到最新版本。这能确保我们后续安装的依赖都是兼容的。

打开终端，输入以下命令：

sudo apt update && sudo apt upgrade -y

这个命令可能会运行几分钟，取决于你的网络速度和需要更新的软件包数量。完成后，我们安装一些后续步骤可能会用到的基础工具，比如curl（用于网络请求）和wget（另一个下载工具）。

sudo apt install -y curl wget

2.2 NVIDIA驱动与CUDA Toolkit安装（GPU用户）

如果你的服务器有NVIDIA GPU，并且希望使用GPU来加速推理，那么这一步是必须的。如果只用CPU，可以跳过这一小节。

1. 安装NVIDIA驱动：Ubuntu 20.04的默认软件源里包含了NVIDIA的驱动，我们可以用apt来安装。首先，查看一下可用的驱动版本。

ubuntu-drivers devices

这个命令会列出所有推荐的驱动。通常我们选择标记为“recommended”的那个版本进行安装。例如，如果推荐的是nvidia-driver-535，则安装它：

sudo apt install -y nvidia-driver-535

安装完成后，必须重启服务器才能使驱动生效。

sudo reboot

重启后重新登录，运行nvidia-smi命令。如果能看到GPU的信息表格，就说明驱动安装成功了。

2. 安装CUDA Toolkit：CUDA是NVIDIA的并行计算平台。很多AI框架和模型推理引擎（比如ONNX Runtime）都需要它。我们安装一个与驱动兼容的版本。这里以CUDA 11.8为例，它是一个比较通用且稳定的版本。

访问NVIDIA官网找到CUDA 11.8的安装指令，或者直接使用以下命令：

wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run

在安装界面中，你只需要选择安装CUDA Toolkit，其他的如驱动（我们已经安装了）可以取消勾选。安装完成后，需要将CUDA路径添加到环境变量中。编辑你的~/.bashrc文件：

echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

现在，运行nvcc --version应该可以显示CUDA编译器的版本信息。

2.3 Docker环境安装与配置

Docker是我们这次部署的核心工具，它能把模型运行所需的所有环境打包成一个“容器”，避免了直接在宿主机上配置各种依赖的麻烦。

1. 安装Docker：使用Docker官方提供的便捷安装脚本是最快的方法。

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh

安装完成后，将当前用户添加到docker用户组，这样以后运行Docker命令就不需要每次都加sudo了。

sudo usermod -aG docker $USER

重要：执行完上面的命令后，你需要退出当前的SSH会话，并重新登录，这个组权限变更才会生效。

重新登录后，运行docker --version和docker run hello-world来测试Docker是否安装成功。如果能看到“Hello from Docker!”的提示信息，就说明一切正常。

2. 安装NVIDIA Container Toolkit（GPU用户）：为了让Docker容器能够使用宿主机的GPU，我们需要安装这个工具。

distribution=$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt update && sudo apt install -y nvidia-container-toolkit sudo systemctl restart docker

安装完成后，可以运行一个测试命令来验证GPU在Docker中是否可用：

docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu20.04 nvidia-smi

如果这个命令能成功输出和直接在宿主机上运行nvidia-smi一样的信息，那就恭喜你，Docker的GPU支持也配置好了。

3. 拉取与运行SenseVoice-Small镜像

基础环境全部就绪，现在进入正题，把SenseVoice-Small的服务跑起来。

3.1 从镜像仓库拉取镜像

SenseVoice-Small的ONNX版本通常已经被热心的开发者或平台打包成了Docker镜像。我们假设这个镜像存放在一个公开的仓库里，例如registry.example.com/ai-mirrors/sensevoice-small-onnx:latest（请注意，这是一个示例路径，实际操作时请替换为正确的镜像地址）。

拉取镜像的命令很简单：

docker pull registry.example.com/ai-mirrors/sensevoice-small-onnx:latest

这个过程会下载镜像文件，时间长短取决于你的网络速度和镜像大小。下载完成后，可以用docker images命令查看本地已有的镜像列表，确认它已经存在。

3.2 启动Docker容器

镜像拉取到本地后，它还是一个静态的文件。我们需要通过docker run命令把它“运行”起来，变成一个活的容器。

这里有一个比较完整的启动命令示例，我们拆开看看每个参数的作用：

docker run -d \ --name sensevoice-service \ --restart unless-stopped \ -p 8000:8000 \ -v /host/path/to/models:/app/models \ -v /host/path/to/audios:/app/audio_input \ --gpus all \ registry.example.com/ai-mirrors/sensevoice-small-onnx:latest

• -d：让容器在后台运行（守护进程模式）。
• --name sensevoice-service：给容器起个名字，方便后续管理。
• --restart unless-stopped：设置重启策略。除非我们手动停止，否则如果容器异常退出，Docker会自动重启它，这对于生产环境很实用。
• -p 8000:8000：端口映射。将容器内部的8000端口映射到宿主机的8000端口。这样我们通过访问服务器的IP:8000就能连接到容器内的服务。
• -v /host/path/to/models:/app/models：数据卷挂载。把宿主机上的一个目录（比如/home/user/sensevoice_models）挂载到容器内的/app/models路径。这样你可以把模型文件放在宿主机上，方便管理和更新，而不需要重新构建镜像。
• -v /host/path/to/audios:/app/audio_input：同上，可以挂载一个目录用于存放待识别的音频文件。
• --gpus all：将宿主机的所有GPU资源分配给这个容器。如果只用CPU，去掉这个参数即可。
• 最后一行就是我们要运行的镜像名称和标签。

请务必将/host/path/to/models和/host/path/to/audios替换成你服务器上真实的、存在的目录路径。

执行这个命令后，容器就在后台启动了。你可以用docker ps命令查看正在运行的容器，应该能看到名为sensevoice-service的容器状态是“Up”。

4. 服务验证与基本使用

容器跑起来了，但我们怎么知道里面的服务是不是真的正常工作了呢？我们来检查一下。

4.1 服务健康检查

首先，我们可以查看容器的日志，看看启动过程中有没有报错。

docker logs sensevoice-service

如果日志最后显示服务已经在某个端口（比如8000）监听，通常就表示启动成功了。

更直接的方法是进行健康检查。很多Web服务会提供一个/health或/status这样的接口。我们可以用curl命令来测试：

curl http://localhost:8000/health

或者，如果服务不在本机，用服务器的IP地址：

curl http://你的服务器IP地址:8000/health

如果返回类似{"status": "ok"}的JSON信息，那就说明服务状态健康。

4.2 调用语音识别接口

现在我们来真正试用一下语音转文字的功能。假设这个镜像提供的API接口是接收一个音频文件路径（通过之前挂载的卷）并进行识别。

我们可以准备一个测试用的WAV格式音频文件（例如test.wav），把它放到之前挂载的宿主机目录/host/path/to/audios下。

然后，向服务的识别接口发送一个POST请求。这里用curl命令示例：

curl -X POST http://localhost:8000/recognize \ -H "Content-Type: application/json" \ -d '{"audio_path": "/app/audio_input/test.wav", "language": "zh"}'

这个命令的意思是，告诉服务去处理容器内路径/app/audio_input/test.wav的音频文件（对应宿主机上的/host/path/to/audios/test.wav），并指定语言为中文。

如果一切顺利，服务会返回一个JSON响应，里面包含识别出的文本内容。恭喜你，SenseVoice-Small模型已经成功部署并运行起来了！

4.3 常见问题与排查

第一次部署难免会遇到点小问题，这里列举几个常见的：

• 端口冲突：如果宿主机8000端口已被占用，docker run时会报错。可以修改-p参数，比如改成-p 8001:8000，这样就用宿主机的8001端口来访问。
• 权限问题：如果你挂载了宿主机目录，但容器内服务没有权限读写，可能会出错。确保宿主机目录的权限设置正确（例如chmod 755 /host/path/to/models）。
• GPU不可用：如果加了--gpus all但容器内还是看不到GPU，请检查NVIDIA Container Toolkit是否安装正确，并确认nvidia-smi在宿主机上能正常运行。
• 容器启动后立即退出：用docker logs sensevoice-service查看退出前的日志，通常是启动脚本出错或依赖缺失，根据日志信息进行排查。

5. 总结与后续建议

跟着上面这些步骤走一遍，你应该已经在Ubuntu 20.04上把SenseVoice-Small ONNX模型的服务部署起来了。整个过程其实可以归纳为三步：准备一个干净的Ubuntu系统、安装好Docker和GPU驱动（如果需要）、然后拉取镜像一键运行。

用Docker来部署这种AI模型服务，最大的好处就是环境隔离和一致性。你不用担心复杂的Python包版本冲突，也不用在服务器上安装一堆可能只用一次的依赖。这个容器可以在任何安装了Docker的机器上以同样的方式运行，非常方便。

部署完成后，你可以根据实际需求来使用它。比如，可以写一个简单的Python脚本，定期扫描某个文件夹里的新录音文件，然后调用这个服务的API进行识别，把结果保存下来。或者，把它集成到你现有的业务系统里，作为一个微服务来提供语音转写能力。

如果后续想更新模型版本，通常只需要拉取新的镜像，然后停止旧容器，用新镜像重新运行一个即可。数据通过挂载的卷保存在宿主机上，所以不会丢失。

最后，记得关注服务器的资源使用情况，比如CPU、内存和GPU的占用。如果并发请求多了，可能需要调整容器的资源限制，或者考虑部署多个容器实例 behind a load balancer。不过，对于刚开始试用和轻量级应用，目前这个单容器部署已经足够稳定和实用了。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。