🚀 体验 Speech Box 桌面应用 | 离线、多语言桌面转录：https://speechbox.gumroad.com/l/desktop-app

Whisper ASR Box

Whisper ASR Box 是一款通用的语音识别工具包。Whisper 模型基于大规模多样化音频数据集进行训练，同时它也是一款多任务模型，能够执行多语言语音识别、语音翻译以及语言识别等功能。

🎉 加入我们的 Discord 社区！ 与其他用户交流、获取帮助，并及时了解最新功能：https://discord.gg/4Q5YVrePzZ

功能特性

当前版本 (v1.9.1) 支持以下 Whisper 模型：

• openai/whisper@v20250625
• SYSTRAN/faster-whisper@v1.1.1
• whisperX@v3.4.2

快速使用

CPU

docker run -d -p 9000:9000 \
  -e ASR_MODEL=base \
  -e ASR_ENGINE=openai_whisper \
  onerahmet/openai-whisper-asr-webservice:latest

GPU

docker run -d --gpus all -p 9000:9000 \
  -e ASR_MODEL=base \
  -e ASR_ENGINE=openai_whisper \
  onerahmet/openai-whisper-asr-webservice:latest-gpu

缓存

为减少容器启动时间，避免重复下载，您可以持久化缓存目录：

docker run -d -p 9000:9000 \
  -v $PWD/cache:/root/.cache/ \
  onerahmet/openai-whisper-asr-webservice:latest

核心功能

• 多种 ASR 引擎支持（OpenAI Whisper、Faster Whisper、WhisperX）
• 多种输出格式（文本、JSON、VTT、SRT、TSV）
• 支持词级别时间戳
• 语音活动检测（VAD）过滤
• 发言人分离（配合 WhisperX 使用）
• 集成 FFmpeg，支持广泛的音视频格式
• GPU 加速支持
• 可配置的模型加载与卸载
• 带 Swagger 文档的 REST API

环境变量

关键配置选项：

• ASR_ENGINE：引擎选择（openai_whisper、faster_whisper、whisperx）
• ASR_MODEL：模型选择（tiny、base、small、medium、large-v3 等）
• ASR_MODEL_PATH：自定义存储/加载模型的路径
• ASR_DEVICE：设备选择（cuda、cpu）
• MODEL_IDLE_TIMEOUT：模型卸载超时时间

文档

完整文档请访问： https://ahmetoner.github.io/whisper-asr-webservice

开发

# 安装 poetry v2.X
pip3 install poetry

# 安装 CPU 依赖
poetry install --extras cpu

# 安装 CUDA 依赖
poetry install --extras cuda

# 运行服务
poetry run whisper-asr-webservice --host 0.0.0.0 --port 9000

启动服务后，您可以在浏览器中访问 http://localhost:9000 或 http://0.0.0.0:9000，以查看 Swagger UI 文档并试用 API 接口。

致谢

• 本软件使用了 FFmpeg 项目下的库，遵循 LGPLv2.1 许可协议。

Whisper ASR Webservice 快速上手指南

Whisper ASR Webservice 是一个通用的语音识别工具包，基于 OpenAI Whisper 模型，支持多语言语音识别、翻译及语言检测。它提供了 REST API 接口，支持多种引擎（OpenAI Whisper, Faster Whisper, WhisperX）和输出格式。

环境准备

系统要求

• 操作系统: Linux, macOS, Windows (需安装 Docker Desktop)
• 硬件:
  • CPU 模式: 任意现代 CPU，建议 4GB+ 内存。
  • GPU 模式: NVIDIA GPU，需安装 NVIDIA Container Toolkit 以支持 Docker GPU 透传。
• 软件依赖:
  • Docker & Docker Compose
  • (可选) NVIDIA Driver & CUDA Toolkit (仅 GPU 模式需要)

前置检查

确保 Docker 已正常运行：

docker --version

若使用 GPU，请验证 GPU 支持：

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

安装步骤

本项目推荐使用 Docker 部署，无需手动配置 Python 环境或下载模型文件。

1. CPU 模式部署

适用于无独立显卡或测试环境。

docker run -d -p 9000:9000 \
  -e ASR_MODEL=base \
  -e ASR_ENGINE=openai_whisper \
  onerahmet/openai-whisper-asr-webservice:latest

2. GPU 模式部署

适用于生产环境或大文件处理，显著提升推理速度。

docker run -d --gpus all -p 9000:9000 \
  -e ASR_MODEL=base \
  -e ASR_ENGINE=openai_whisper \
  onerahmet/openai-whisper-asr-webservice:latest-gpu

3. (推荐) 持久化缓存

为避免每次重启容器时重新下载模型，建议挂载本地缓存目录。

mkdir -p ./cache

docker run -d -p 9000:9000 \
  -v $PWD/cache:/root/.cache/ \
  -e ASR_MODEL=base \
  -e ASR_ENGINE=openai_whisper \
  onerahmet/openai-whisper-asr-webservice:latest

注意: 国内用户若下载模型缓慢，可在宿主机配置 Hugging Face 镜像加速，或在 docker run 中添加环境变量 HF_ENDPOINT=https://hf-mirror.com。

基本使用

服务启动后，默认监听 9000 端口。

1. 访问 API 文档

在浏览器中打开以下地址查看 Swagger UI 界面，可直接在线测试接口：

• http://localhost:9000
• http://0.0.0.0:9000

2. 命令行调用示例

使用 curl 上传音频文件进行转录（假设当前目录下有 audio.mp3）：

curl -X POST "http://localhost:9000/asr" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3" \
  -F "task=transcribe" \
  -F "language=zh" \
  -F "output_format=json"

3. 关键参数说明

• ASR_ENGINE: 选择引擎 (openai_whisper, faster_whisper, whisperx)
• ASR_MODEL: 选择模型大小 (tiny, base, small, medium, large-v3)
• task: 任务类型 (transcribe 转录, translate 翻译为英文)
• language: 源语言代码 (如 zh, en, ja，留空则自动检测)
• output_format: 输出格式 (text, json, srt, vtt, tsv)

更多高级功能（如说话人分离、词级时间戳）请参考 Swagger 文档中的详细参数定义。