跳转到内容
OpenASR

Docker

每个 OpenASR 核心版本发布时，都会同步推送运行镜像到 Docker Hub。镜像里只有 CLI 二进制和已签名的 model-registry 元数据——不包含模型权重。请在运行时把模型 安装到挂载在 /data 的卷上（即容器内的 OPENASR_HOME）。

镜像直接组装自 GitHub Release 里的预编译包（不会在 Docker 里再编一遍），因此 容器内的二进制与对应 release 标签逐字节一致。

镜像与标签

Section titled “镜像与标签”
标签形式内容平台
latest、<version>、sha-<short>CPU 二进制（linux-x86_64 / linux-arm64）linux/amd64、linux/arm64
cuda-latest、cuda-<version>、cuda-sha-<short>CUDA 二进制（linux-x86_64-cuda）仅 linux/amd64

把 <version> 换成已发布的核心版本（见 GitHub Releases）。生产环境 建议钉死版本标签；只有在你明确要跟随最新核心版时，才使用 latest / cuda-latest。

目前没有做成镜像的变体（请直接在宿主机使用 GitHub Release 压缩包）： Vulkan、ROCm、musl。它们对宿主机驱动或 C 库的要求，与这里使用的精简 Debian / CUDA runtime 基座不一致。

快速开始（CPU）

Section titled “快速开始（CPU）”
bash
docker pull quintinshaw/openasr:latest


docker run --rm -d --name openasr \
  -p 8080:8080 \
  -v openasr-data:/data \
  quintinshaw/openasr:latest

默认命令是 serve --addr 0.0.0.0:8080。健康检查：

bash
curl -s http://127.0.0.1:8080/health

NVIDIA GPU（CUDA）

Section titled “NVIDIA GPU（CUDA）”

宿主机需要安装 NVIDIA Container Toolkit， 驱动需兼容 CUDA 13.2，GPU 计算能力需 sm_75（Turing）及以上。

bash
docker pull quintinshaw/openasr:cuda-latest


docker run --rm -d --name openasr-cuda \
  --gpus all \
  -p 8080:8080 \
  -v openasr-data:/data \
  quintinshaw/openasr:cuda-latest

CUDA 镜像在 GPU 可见性上是失败即停的：如果容器内看不到 GPU 设备 （openasr doctor 没有报告 (gpu, …)），入口脚本会直接退出，而不会悄悄改走 CPU。常见原因是没加 --gpus、没装 Container Toolkit，或宿主机驱动不匹配。

安装模型（转写前必须做）

Section titled “安装模型（转写前必须做）”

HTTP 服务不会为了满足一次请求去下载模型——这与直接在机器上跑 openasr serve 的约定相同。请显式把模型拉进数据卷：

bash
# 已有名为 openasr 的容器
docker exec -it openasr openasr pull whisper-small --yes


# 或对同一命名卷做一次性拉取
docker run --rm -v openasr-data:/data quintinshaw/openasr:latest \
  pull whisper-small --yes

在非交互环境（没有 TTY）里必须加 --yes。查看已安装模型：

bash
docker exec openasr openasr list

然后调用兼容 OpenAI 的转写接口：

bash
curl -s http://127.0.0.1:8080/v1/audio/transcriptions \
  -F [email protected] \
  -F model=whisper-small \
  -F response_format=json

完整路由表、鉴权模式与 TLS 说明见本地服务 API 参考。

持久化数据

Section titled “持久化数据”
容器内路径作用
/data（OPENASR_HOME）已安装的 .oasr 包、配置、历史记录、声纹注册等

请始终给 /data 挂卷（或 bind mount）。不挂的话，每次新容器都是空的，模型 要重新下载。

在镜像里直接跑 CLI

Section titled “在镜像里直接跑 CLI”

入口就是 openasr 二进制，因此任意子命令都可以用：

bash
docker run --rm -v openasr-data:/data -v "$PWD:/work" -w /work \
  quintinshaw/openasr:latest \
  transcribe audio.wav --model whisper-small --offline

若模型尚未安装，--offline 会直接失败——请先按上文拉取。麦克风 / 系统音频 采集依赖宿主机环境；容器场景主要面向文件转写和本地 HTTP API。

环境变量与网络

Section titled “环境变量与网络”
变量 / 设置镜像默认值说明
OPENASR_HOME/data数据卷挂这里
OPENASR_ALLOW_INSECURE_NON_LOOPBACK1允许容器内 serve 监听 0.0.0.0。对外是否暴露仍由你的 -p、编排和防火墙决定。在不可信网络前请加 TLS（或由代理终止 TLS）。
暴露端口8080用 -p 8080:8080 映射

远程访问（配对鉴权、自签 TLS 等）可通过 docker run … <flags> 传入 openasr serve 参数，详见本地服务 API 参考。除上述回环 监听放宽外，镜像不会放宽其他失败即停默认行为。

Compose（本地源码构建）

Section titled “Compose（本地源码构建）”

仓库里的 compose.yaml 用于开发时的源码构建（Dockerfile / Dockerfile.cuda）。正式发布走 Docker Hub 镜像；compose 仍适合本地改代码和冒烟：

bash
git clone --recurse-submodules https://github.com/QuintinShaw/openasr.git
cd openasr
docker compose up openasr                 # CPU，源码构建
docker compose --profile gpu up openasr-cuda

自动发布

Section titled “自动发布”

每次核心版 GitHub Release 完成后，在配置了 DOCKER_PAT 密钥的前提下，CI 会 自动组装并推送上表中的 CPU 多架构与 CUDA 标签到 quintinshaw/openasr。Docker 任务失败不会回滚 GitHub Release 资产。需要手动重推时：

bash
gh workflow run docker-release.yml \
  -R QuintinShaw/openasr \
  -f version=<version> -f push=true -f mark_latest=true -f variants=all

相关文档

Section titled “相关文档”