SenseVoice

环境要求

• Python 环境与 pip（用于安装 funasr / funasr-onnx）
• Docker（用于构建和运行 SenseVoice 容器镜像）
• GPU 运行需 NVIDIA 驱动并支持 docker run --gpus all；纯 CPU 也可运行
• 如需无 Python 环境运行，需使用 llama.cpp/GGUF 版 SenseVoice 预编译二进制

安装与启动步骤

1. 1安装 Python 依赖

   用 pip 安装 FunASR 与 funasr-onnx，供 Python 侧调用 SenseVoiceSmall 模型推理。

   pip3 install -U funasr funasr-onnx

   复制

2. 2构建 Docker 镜像

   在项目根目录执行构建，生成名为 sensevoice 的本地镜像；官方 ghcr 镜像当前为私有，需本地构建。

   docker build -t sensevoice .

   复制

3. 3GPU 方式启动容器

   默认 GPU 模式启动，映射 50000 端口并挂载模型缓存卷，模型文件会保存在 sensevoice-models 卷中。

   docker run --rm --gpus all -p 50000:50000 -v sensevoice-models:/models sensevoice

   复制

4. 4CPU 方式启动容器

   无 GPU 时通过环境变量切换到 CPU 推理，其余端口与模型卷参数与 GPU 模式一致。

   docker run --rm -e SENSEVOICE_DEVICE=cpu -p 50000:50000 -v sensevoice-models:/models sensevoice

   复制

5. 5使用 Docker Compose

   compose 会构建同样的镜像并复用模型缓存卷；默认不请求 GPU，因此直接在 CPU 主机上启动。

   docker compose up --build

   复制

6. 6FastAPI 方式部署

   非容器方式启动 FastAPI 服务，先用环境变量指定推理设备（如 cuda:0），再以 50000 端口运行。

   export SENSEVOICE_DEVICE=cuda:0
   fastapi run --port 50000

   复制

7. 7llama.cpp 无依赖运行

   无需 GPU 和 Python：先下载 GGUF 模型与内置 FSMN-VAD，再用单文件二进制对音频文件做识别。

   bash runtime/llama.cpp/download-funasr-model.sh sensevoice ./gguf
   llama-funasr-sensevoice -m ./gguf/sensevoice-small-f16.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav

   复制

关键配置

如何确认成功

容器或服务启动后访问 http://127.0.0.1:50000/docs，能看到 FastAPI 接口文档页面即部署成功。

常见问题

注意事项

• README 说明 ghcr 上的镜像包当前为私有，匿名拉取会 401，构建与运行请使用本地构建的镜像。
• Docker Compose 的默认配置不请求 GPU，GPU 场景请使用 docker run --gpus all 的命令。
• 容器监听端口为 50000，模型缓存在 sensevoice-models 卷中，删除卷会重新下载模型。
• llama.cpp 版为单文件二进制、内置 FSMN-VAD、运行时不依赖 Python，需从 Releases 获取预编译版本。