SenseVoice Docker Compose部署：一键启动完整语音服务集群

1. 痛点与解决方案

你是否还在为语音识别服务的复杂部署流程而困扰？从环境配置、依赖安装到服务编排，每一步都可能遇到兼容性问题。本文将带你通过Docker Compose实现SenseVoice语音服务集群的一键部署，无需繁琐配置，5分钟即可拥有企业级语音识别能力。

读完本文你将获得：

• 完整的Docker化部署方案
• 高可用的服务集群架构
• 多语言语音识别能力
• 可视化Web界面与API服务
• 性能优化与资源配置指南

2. 部署架构设计

2.1 系统架构图

flowchart TD
    Client[用户/应用] --> Nginx[负载均衡 Nginx]
    Nginx --> API1[SenseVoice API 节点1]
    Nginx --> API2[SenseVoice API 节点2]
    Nginx --> API3[SenseVoice API 节点3]
    API1 --> Model[语音识别模型]
    API2 --> Model
    API3 --> Model
    Model --> Data[音频数据]
    API1 --> WebUI[Web管理界面]

2.2 服务组件说明

组件	功能描述	技术栈	资源需求
sensevoice-api	语音识别核心服务	FastAPI, PyTorch	CPU: 4核, 内存: 8GB
nginx	负载均衡与反向代理	Nginx Alpine	CPU: 1核, 内存: 256MB
WebUI	可视化管理界面	Gradio	共享API资源
模型服务	语音识别模型推理	SenseVoice模型	建议GPU加速

3. 部署准备工作

3.1 环境要求

环境	最低配置	推荐配置
CPU	4核	8核及以上
内存	8GB	16GB及以上
存储	10GB空闲空间	SSD 20GB以上
Docker	20.10+	23.0+
Docker Compose	2.0+	2.10+
网络	可访问Git仓库	稳定网络连接

3.2 前期准备

# 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/se/SenseVoice
cd SenseVoice

# 创建必要目录
mkdir -p data webui logs nginx/conf.d

4. Docker Compose配置

4.1 docker-compose.yml

version: '3.8'

services:
  sensevoice-api:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      - SENSEVOICE_DEVICE=cpu  # GPU环境可改为cuda:0
      - MODEL_DIR=iic/SenseVoiceSmall
      - LOG_LEVEL=INFO
      - WORKERS=4
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:50000/"]
      interval: 30s
      timeout: 10s
      retries: 3

  sensevoice-api-2:
    extends: sensevoice-api
    depends_on:
      - sensevoice-api

  sensevoice-api-3:
    extends: sensevoice-api
    depends_on:
      - sensevoice-api

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./webui:/usr/share/nginx/html
      - ./nginx/logs:/var/log/nginx
    depends_on:
      - sensevoice-api
      - sensevoice-api-2
      - sensevoice-api-3
    restart: unless-stopped

  webui:
    build:
      context: .
      dockerfile: Dockerfile.webui
    ports:
      - "7860:7860"
    depends_on:
      - sensevoice-api
    environment:
      - API_URL=http://nginx/api/v1/asr
    restart: unless-stopped

4.2 Dockerfile

FROM python:3.9-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    libsndfile1 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 50000

# 启动命令
CMD ["python", "api.py"]

4.3 Nginx配置文件

创建nginx/conf.d/default.conf：

upstream sensevoice_api {
    server sensevoice-api:50000;
    server sensevoice-api-2:50000;
    server sensevoice-api-3:50000;
}

server {
    listen 80;
    server_name localhost;
    
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }

    location /api/ {
        proxy_pass http://sensevoice_api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws/ {
        proxy_pass http://sensevoice_api/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

5. 一键部署流程

5.1 启动服务集群

# 构建并启动服务
docker-compose up -d --build

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f sensevoice-api

5.2 服务验证

# 检查API服务是否正常运行
curl http://localhost/api/v1/asr -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "files=@test.wav" \
  -F "lang=zh"

5.3 访问Web界面

打开浏览器访问：http://localhost

6. 性能优化与扩展

6.1 资源配置优化

根据服务器配置调整docker-compose.yml中的资源限制：

deploy:
  resources:
    limits:
      cpus: '8'  # 增加CPU核心数
      memory: 16G  # 增加内存限制
    reservations:
      cpus: '4'
      memory: 8G

6.2 水平扩展

# 扩展API服务节点
docker-compose up -d --scale sensevoice-api=5

# 限制最大扩展数量
docker-compose up -d --scale sensevoice-api=3 sensevoice-api-2=0 sensevoice-api-3=0

6.3 GPU加速配置

services:
  sensevoice-api:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - SENSEVOICE_DEVICE=cuda:0

7. 日常维护与监控

7.1 日志管理

# 设置日志轮转
echo 'logs/*.log {
    daily
    missingok
    rotate 7
    compress
    delaycompress
    notifempty
}' | sudo tee /etc/logrotate.d/sensevoice

# 手动执行日志轮转
sudo logrotate -f /etc/logrotate.d/sensevoice

7.2 服务更新

# 拉取最新代码
git pull

# 重建并重启服务
docker-compose down
docker-compose up -d --build

7.3 监控指标

pie
    title 系统资源占用
    "CPU" : 35
    "内存" : 45
    "磁盘" : 10
    "网络" : 10

8. 常见问题解决

8.1 服务启动失败

# 检查容器日志
docker-compose logs sensevoice-api

# 常见问题：端口冲突
netstat -tulpn | grep 50000

# 解决方案：修改端口映射
sed -i 's/50000:50000/50001:50000/' docker-compose.yml

8.2 模型加载失败

# 检查模型文件
ls -l data/models

# 重新下载模型
docker-compose exec sensevoice-api python -c "from model import SenseVoiceSmall; SenseVoiceSmall.from_pretrained('iic/SenseVoiceSmall')"

8.3 性能瓶颈

timeline
    title 语音识别流程耗时分析
    音频预处理 : 0.2s
    特征提取 : 0.3s
    模型推理 : 1.5s
    结果后处理 : 0.1s

9. 总结与展望

通过Docker Compose部署SenseVoice语音服务集群，我们实现了：

• 环境隔离与一致性
• 服务高可用与负载均衡
• 一键部署与快速扩展
• 资源优化与性能监控

未来功能规划：

• 增加模型热更新机制
• 实现多模型版本共存
• 引入Kubernetes管理方案
• 增加监控告警系统

10. 附录：完整配置文件

10.1 docker-compose.yml

version: '3.8'

services:
  sensevoice-api:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      - SENSEVOICE_DEVICE=cpu
      - MODEL_DIR=iic/SenseVoiceSmall
      - LOG_LEVEL=INFO
      - WORKERS=4
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:50000/"]
      interval: 30s
      timeout: 10s
      retries: 3

  sensevoice-api-2:
    extends: sensevoice-api

  sensevoice-api-3:
    extends: sensevoice-api

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./webui:/usr/share/nginx/html
      - ./nginx/logs:/var/log/nginx
    depends_on:
      - sensevoice-api
      - sensevoice-api-2
      - sensevoice-api-3
    restart: unless-stopped

  webui:
    build:
      context: .
      dockerfile: Dockerfile.webui
    ports:
      - "7860:7860"
    depends_on:
      - sensevoice-api
    environment:
      - API_URL=http://nginx/api/v1/asr
    restart: unless-stopped

10.2 Dockerfile.webui

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

COPY webui.py .
COPY utils ./utils

EXPOSE 7860

CMD ["python", "webui.py"]

11. 收藏与关注

如果本文对你有帮助，请点赞、收藏、关注三连支持！下期我们将介绍如何基于SenseVoice构建实时语音转写系统，敬请期待。

感谢阅读，祝你的语音识别服务部署顺利！