SenseVoice-small开源镜像实操：离线环境安装依赖包完整离线包制作-Seo优化-合肥市网站建设公司

SenseVoice-small开源镜像实操：离线环境安装依赖包完整离线包制作

1. 引言：为什么需要离线部署？

想象一下这个场景：你正在为一个医疗项目开发一套本地语音病历录入系统，或者为一家金融机构搭建一个内部会议纪要工具。这些场景都有一个共同点——数据绝对不能离开本地网络。服务器可能没有外网，或者出于安全和合规要求，必须完全离线运行。

这时候，一个强大的离线语音识别工具就成了刚需。SenseVoice-small 的 ONNX 量化版 WebUI 镜像，正是为此而生。它把原本需要云端GPU算力的语音识别能力，压缩成了一个可以在普通CPU上、完全离线运行的轻量级服务。

但问题来了：官方镜像通常只包含核心模型和基础环境。当你真正要在内网服务器、嵌入式设备甚至工控机上部署时，你会发现缺少各种Python依赖包，而离线环境又没法用pip install。这篇文章，我就带你一步步解决这个痛点，手把手教你制作一个包含全部依赖的完整离线安装包，让你在任何“与世隔绝”的环境里，都能一键部署SenseVoice语音识别服务。

2. 环境准备：在能上网的机器上搭建“制造工厂”

制作离线包，首先得在一台能正常访问互联网的机器上操作。我们把这台机器称为“制造机”。这里我假设你使用 Ubuntu 22.04 系统，其他Linux发行版步骤类似。

2.1 第一步：获取原始镜像和创建基础环境

首先，你需要把 SenseVoice-small 的镜像跑起来，这是我们依赖包的“源头”。

# 假设你已经通过某种方式获取了镜像文件 sensevoice-small.tar # 加载镜像到本地Docker docker load -i sensevoice-small.tar # 查看镜像ID docker images # 运行一个临时容器，我们不需要它的服务，只需要它的环境 docker run -itd --name sensevoice-builder [你的镜像ID] /bin/bash

这个容器的内部，已经预置了Python环境、PyTorch等基础框架，但可能缺少一些运行WebUI所需的额外包。

2.2 第二步：进入容器，探查依赖情况

进入容器，看看里面到底预装了哪些包，还缺哪些。

# 进入容器 docker exec -it sensevoice-builder /bin/bash # 查看当前Python环境及已安装的包 pip list # 尝试启动WebUI服务，观察报错信息（这能告诉你缺什么） cd /root/sensevoice-small-语音识别-onnx python webui.py

通常，你可能会看到关于gradio、soundfile、pydub等库的ModuleNotFoundError。记下这些缺失的包名。

3. 依赖包收集：制作完整的离线包

现在我们知道缺什么了，接下来就是在“制造机”上，把这些依赖包连同它们的依赖，全部下载下来。

3.1 方法一：使用 pip download（推荐）

这是最规范的方法，能确保下载指定平台和Python版本的包。

# 1. 在宿主机（制造机）上创建一个工作目录 mkdir -p ~/sensevoice-offline-packages cd ~/sensevoice-offline-packages # 2. 生成requirements.txt文件 # 你可以根据上一步的报错，手动创建一个。一个典型的SenseVoice WebUI依赖列表可能如下： cat > requirements.txt << 'EOF' gradio>=4.0 soundfile pydub numpy onnxruntime librosa webrtcvad # 添加其他你在容器内pip list里看到但可能版本不对的包 # 例如，如果容器内是 torch 2.1.0，而你需要特定版本，可以指定 # torch==2.1.0 EOF # 3. 下载所有依赖包到当前目录 # 关键参数：--platform 指定系统（linux_x86_64）， --python-version 指定Python版本（如3.10）， --only-binary=:all: 只下载二进制包 pip download -r requirements.txt -d ./packages \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary=:all: \ --no-deps # 注意：这里先不加 --no-deps，让pip解析依赖树并下载所有相关包 # 如果上一步因为平台问题失败，可以尝试不指定平台，下载源码包或通用轮子 pip download -r requirements.txt -d ./packages

重要提示：--platform参数必须与目标离线机器的环境一致。你可以通过python -c "import platform; print(platform.platform())"在目标机（或模拟环境）上查看。

3.2 方法二：从运行中的容器直接导出pip缓存

如果容器在构建时已经联网下载过一些包，我们可以直接“偷”它的缓存。

# 1. 在容器内，找到pip的缓存目录。通常在这里： # /root/.cache/pip # 或者通过命令查找：pip cache dir # 2. 将缓存目录复制到宿主机 docker cp sensevoice-builder:/root/.cache/pip ./pip-cache-from-container # 3. 这个缓存目录里有很多 .whl 文件，但结构比较乱。 # 我们可以用 pip download 配合 --find-links 来利用这些缓存文件，生成一个干净的包目录。 cd ~/sensevoice-offline-packages mkdir -p ./local_wheels # 递归查找所有 .whl 文件并复制到统一目录 find ../pip-cache-from-container -name "*.whl" -exec cp {} ./local_wheels/ \; # 4. 使用本地wheel文件作为源进行下载（对于缺失的包，仍会从网络获取） pip download -r requirements.txt -d ./packages --find-links ./local_wheels

3.3 组织离线安装包

现在~/sensevoice-offline-packages/packages目录下应该有一大堆.whl或.tar.gz文件了。我们需要创建一个一键安装脚本。

cd ~/sensevoice-offline-packages # 创建安装脚本 install.sh cat > install.sh << 'EOF' #!/bin/bash set -e echo "开始安装 SenseVoice-small 离线依赖包..." # 检查Python环境 if ! command -v python3 &> /dev/null; then echo "错误：未找到 python3，请先安装Python 3.8或更高版本。" exit 1 fi PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') echo "检测到 Python 版本: $PYTHON_VERSION" # 检查pip if ! command -v pip3 &> /dev/null; then echo "正在尝试安装 pip..." apt-get update && apt-get install -y python3-pip # 适用于Debian/Ubuntu # 或 yum install -y python3-pip # 适用于RHEL/CentOS fi # 进入包目录 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" PACKAGE_DIR="$SCRIPT_DIR/packages" if [ ! -d "$PACKAGE_DIR" ]; then echo "错误：未找到 packages 目录。" exit 1 fi echo "正在从本地目录安装依赖包..." pip3 install --no-index --find-links=file://$PACKAGE_DIR -r $SCRIPT_DIR/requirements.txt if [ $? -eq 0 ]; then echo "依赖包安装成功！" else echo "安装过程中出现错误。" exit 1 fi EOF # 使脚本可执行 chmod +x install.sh # 确保 requirements.txt 也在目录根下 cp ~/sensevoice-offline-packages/requirements.txt ./ # 最终的目录结构应该是： # sensevoice-offline-packages/ # ├── install.sh # ├── requirements.txt # └── packages/ # ├── gradio-4.0.0-py3-none-any.whl # ├── soundfile-0.12.1-cp310-cp310-manylinux_2_17_x86_64.whl # └── ... 其他几十个包

4. 离线部署实战：在目标机器上安装

现在，将整个sensevoice-offline-packages文件夹（压缩成 tar.gz）拷贝到你的离线目标机器上。

4.1 场景一：纯净的Linux服务器

假设目标机是一台全新的Ubuntu服务器，没有外网。

# 1. 上传并解压离线包 scp sensevoice-offline-packages.tar.gz user@offline-server:/tmp/ ssh user@offline-server # 在离线服务器上操作 cd /tmp tar -zxvf sensevoice-offline-packages.tar.gz cd sensevoice-offline-packages # 2. 安装系统级依赖（部分Python包需要系统库） # 例如，soundfile 需要 libsndfile1， pydub 需要 ffmpeg sudo apt-get update sudo apt-get install -y libsndfile1 ffmpeg python3-pip # 3. 运行离线安装脚本 sudo ./install.sh # 如果使用系统Python，可能需要sudo。如果使用conda虚拟环境，则不需要。

4.2 场景二：Docker镜像构建

更优雅的方式是将离线包集成到新的Docker镜像中，方便分发。

# Dockerfile.offline FROM ubuntu:22.04 # 安装系统依赖 RUN apt-get update && apt-get install -y \ python3 \ python3-pip \ libsndfile1 \ ffmpeg \ && rm -rf /var/lib/apt/lists/* # 将离线包复制到镜像中 COPY sensevoice-offline-packages /opt/sensevoice-offline-packages # 安装Python依赖 RUN cd /opt/sensevoice-offline-packages && \ pip3 install --no-index --find-links=file:///opt/sensevoice-offline-packages/packages -r requirements.txt # 后续可以复制SenseVoice应用代码，设置启动命令等 # COPY sensevoice-app /app # WORKDIR /app # CMD ["python3", "webui.py"]

然后构建镜像：

docker build -f Dockerfile.offline -t sensevoice-offline:latest .

4.3 场景三：嵌入式设备（如Jetson Nano）

对于ARM架构的设备，pip download时需要指定对应的平台。

# 在制造机上，针对ARM架构下载包 # 首先在制造机上安装模拟器或使用同架构机器 # 或者，更简单的方法：在嵌入式设备本身上，通过临时联网下载所有包，然后归档。 # 1. 让设备暂时联网，安装所有包 pip3 install gradio soundfile pydub onnxruntime... # 2. 将 pip 缓存目录打包 cd ~/.cache/pip tar -zcf /tmp/pip-packages-arm64.tar.gz . # 3. 断网后，就可以用这个缓存包来安装了 pip3 install --no-index --find-links=file:///path/to/pip-packages-arm64 gradio soundfile ...

5. 验证与问题排查

安装完成后，必须验证环境是否完整。

5.1 基础验证脚本

在目标机器上创建一个简单的测试脚本test_env.py：

import sys import pkg_resources required_packages = [ 'gradio', 'soundfile', 'pydub', 'numpy', 'onnxruntime', 'librosa' ] print("Python 版本:", sys.version) print("\n检查核心依赖包...") all_ok = True for package in required_packages: try: dist = pkg_resources.get_distribution(package) print(f"✓ {dist.key}=={dist.version}") except pkg_resources.DistributionNotFound: print(f"✗ {package} 未安装") all_ok = False if all_ok: print("\n所有核心依赖包已就绪。") # 可以进一步测试音频读取等基本功能 try: import soundfile as sf print("soundfile 模块导入成功。") except Exception as e: print(f"soundfile 导入失败: {e}") else: print("\n存在未安装的包，请检查。") sys.exit(1)

运行它：python3 test_env.py

5.2 常见问题与解决

报错：libsndfile.so.1: cannot open shared object file
- 原因：系统缺少libsndfile1库。
- 解决：sudo apt-get install libsndfile1(Debian/Ubuntu) 或sudo yum install libsndfile(RHEL/CentOS)。
报错：No module named 'onnxruntime'
- 原因：ONNX Runtime包可能因为平台不匹配没安装上。
- 解决：在制造机上，为目标平台重新下载正确的onnxruntimewheel文件。访问 ONNX Runtime官网查找对应版本，手动放入packages目录。
报错：ERROR: Could not find a version that satisfies the requirement...
- 原因：requirements.txt中的某个包在packages目录中不存在。
- 解决：检查拼写错误，或在制造机上用pip download单独下载缺失的包。
性能问题：识别速度慢
- 原因：ONNX Runtime未使用合适的执行提供者（Execution Provider）。
- 解决：检查是否安装了onnxruntime的基础CPU版。对于Intel CPU，可以尝试下载onnxruntime-openvino或onnxruntime-directml（Windows）以获得加速。注意：这需要重新制作包含新版本ONNX Runtime的离线包。

6. 总结：打造属于你的离线语音识别利器

通过以上步骤，你已经掌握了从依赖分析、离线包制作到跨环境部署的完整流程。我们来回顾一下关键点：

规划先行：明确目标机器的操作系统、架构和Python版本，这是pip download成功的前提。
依赖闭环：利用pip download的--platform和--python-version参数，确保下载的包能在目标机运行。--only-binary=:all:能避免编译问题。
系统依赖别忘记：Python包只是半边天，像libsndfile1、ffmpeg这样的系统库必须提前准备好，尤其是在制作Docker镜像或系统安装脚本时。
验证是关键：部署完成后，用一个简单的脚本验证核心模块能否导入，能避免很多后续的运行时错误。

制作一个完整的离线依赖包，就像是为一艘潜艇准备一次漫长的深海航行。你需要把所有可能用到的“补给”都带齐，因为中途没有“港口”可以停靠。一旦准备妥当，SenseVoice-small 这款轻量、多语言的语音识别引擎，就能在你指定的任何离线环境中稳定服役，无论是保障数据隐私的医疗金融内网，还是算力有限的边缘设备，它都能提供可靠的语音转文字服务。