ghcr.io/trunk-reporter/qwen3-asr-server:latest

qwen3-asr-server

基于Qwen3-ASR构建的OpenAI兼容转录API服务器，针对P25公共安全调度音频进行了微调。通过Qwen3-ForcedAligner支持词级时间戳。

whisper-server的即插即用替代品——任何与OpenAI /v1/audio/transcriptions 端点通信的客户端都可直接使用。

/v1/audio/transcriptions

要求

Docker：仅需Docker（GPU版本需nvidia-container-toolkit）。无需其他依赖。

nvidia-container-toolkit

本地安装：

• Python 3.10+
• GPU：NVIDIA CUDA或Apple Silicon MPS（bfloat16精度下两个模型共需约4GB显存）。若两者均不可用，则回退至CPU。
• ffmpeg（用于非wav音频格式转换）

ffmpeg

使用Docker快速启动

最快的启动方式。首次启动时会自动下载模型。

GPU（NVIDIA — 词级时间戳，最快推理速度）

docker run --gpus all -p 8765:8765 \
-v asr-model:/model -v asr-aligner:/aligner \
ghcr.io/trunk-reporter/qwen3-asr-server:gpu

CPU（无需GPU — 使用C推理后端）

docker run -p 8765:8765 -v asr-model:/model \
ghcr.io/trunk-reporter/qwen3-asr-server:cpu

或使用docker compose：

# GPU
docker compose -f docker-compose.gpu.yml up -d

# CPU
docker compose -f docker-compose.cpu.yml up -d

平台支持

./start.sh

GPU镜像要求主机安装NVIDIA + nvidia-container-toolkit。需要GPU加速的macOS用户应使用本地安装——Docker容器内不支持MPS。

nvidia-container-toolkit

Docker配置

通过 -e 传递环境变量来自定义行为：

docker run --gpus all -p 8765:8765 \
-e SPEECH_RMS_THRESHOLD=0.02 \
-e INFERENCE_TIMEOUT=60 \
-v asr-model:/model -v asr-aligner:/aligner \
ghcr.io/trunk-reporter/qwen3-asr-server:gpu

所有可用变量详见配置部分。

本地构建镜像

# CPU
docker build -t qwen3-asr-server:cpu .

# GPU
docker build -f Dockerfile.gpu -t qwen3-asr-server:gpu .

预下载模型

如果已在本地拥有模型权重，可直接挂载而非使用Docker卷：

# GPU
docker run --gpus all -p 8765:8765 \
-v ./qwen3-asr-p25-0.6B:/model \
-v ./Qwen3-ForcedAligner-0.6B:/aligner \
ghcr.io/trunk-reporter/qwen3-asr-server:gpu

# CPU
docker run -p 8765:8765 \
-v ./qwen3-asr-p25-0.6B:/model \
ghcr.io/trunk-reporter/qwen3-asr-server:cpu

更新

Docker

拉取最新镜像并重启：

# GPU
docker pull ghcr.io/trunk-reporter/qwen3-asr-server:gpu
docker compose -f docker-compose.gpu.yml up -d

# CPU
docker pull ghcr.io/trunk-reporter/qwen3-asr-server:cpu
docker compose -f docker-compose.cpu.yml up -d

如果使用 docker run 启动，只需停止容器并重新运行相同命令——将使用新镜像。

docker run

模型权重保存在Docker卷中，因此不会重新下载。

响应格式：

json（默认）：

{"text": "All units respond to 5th and Main."}

verbose_json：

{
"task": "transcribe",
"language": "English",
"text": "All units respond to 5th and Main.",
"processing_time": 0.832,
"model": "qwen3-asr-p25-0.6B",
"words": [
{"word": "All", "start": 0.24, "end": 0.48},
{"word": "units", "start": 0.52, "end": 0.88}
]
}

text：

All units respond to 5th and Main.

GET /v1/models

GET /v1/models
列出已加载的模型。与OpenAI模型列表兼容。

GET /health

GET /health
返回服务器状态、模型信息、当前配置以及每个工作进程的请求计数器。

提示/上下文

prompt参数允许您向模型传递上下文以影响转录结果。它会被注入模型的系统提示中，以将 token 概率推向特定术语。适用于两种后端——对应 Python 后端的context和 C 后端的--prompt。

使用场景：

• 拼写和专有名词——引导模型识别其原本可能无法正确识别的特定领域名称
• 格式风格——提示首选的输出约定
• 领域词汇——提供音频源中常见的行话或缩写

示例：

# 辅助识别本地街道名称和单位编号
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="Rensselaer County, Engine 45, Pawling Avenue, Taconic Parkway"

# 缩写和格式提示
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="Use standard abbreviations: EMS, CPR, MVA, DOA"

# 使用 Python OpenAI 客户端
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="St. Clair Shores PD, Lake Shore Drive, Jefferson Avenue"

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8765/v1", api_key="not-needed")

transcript = client.audio.transcriptions.create(
model="qwen3-asr-p25",
file=open("dispatch.wav", "rb"),
prompt="Engine 12, Ladder 7, Battalion 3, Elmhurst Avenue",
)
print(transcript.text)

注意事项：提示偏向性“非常弱”——模型可能会也可能不会遵循您的指示。拼写提示通常效果最好。强烈或冗长的提示可能会严重偏向模型，导致其复述提示而非反映实际音频内容。长提示还会增加序列长度以及每个请求的内存/计算量。建议从简短、事实性的上下文（专有名词、缩写）开始，而非完整句子。如果结果变差，请尝试缩短提示或完全移除提示。

推理后端

服务器支持两种推理后端：

Python（INFERENCE_BACKEND=python，默认）——使用 PyTorch + transformers，支持 GPU 加速（CUDA 或 MPS）。通过 ForcedAligner 支持单词级时间戳。这是用于 GPU 生产环境的全功能后端。

C（INFERENCE_BACKEND=c）——使用 antirez/qwen-asr C 二进制文件。无需 GPU、PyTorch 或 CUDA。模型权重通过内存映射加载，推理通过 OpenBLAS 在 CPU 上运行。Docker CPU 镜像约 800MB ，而 GPU 镜像为多 GB。权衡：不支持单词级时间戳。

[!NOTE] 默认阈值：0.01
如果处理不同的音频源，请调整 SPEECH_RMS_THRESHOLD。

幻觉检测

已知的幻觉短语（例如“thank you for watching”、“hello how are you doing today...”）会与标准化转录输出进行匹配，匹配到则返回空字符串拒绝。

重复循环检测

检测模型何时进入解码循环（例如“Engine 5 Engine 5 Engine 5 Engine 5”）。检查 1-4 元语法（n-grams），如果任何模式重复 REPETITION_THRESHOLD（默认 4）次或更多，则拒绝。仅检查包含 8 个以上单词的文本，以避免对简短、合法的调度音频产生误判。阈值 4 可避免误判——调度员通常会重复单位名称 2-3 次。

推理超时

每个请求都有 INFERENCE_TIMEOUT（默认 120 秒）安全机制。GPU 推理在典型音频上可在数秒内完成；CPU 推理可能需要更长时间。使用 DEVICE 设置控制硬件加速：auto（默认，尝试 CUDA

MPS CPU）；或指定 cuda:0、mps、cpu。

API

POST /v1/audio/transcriptions

OpenAI 兼容的转录端点。

# 基础转录
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@audio.wav \
-F model=qwen3-asr-p25

# 带单词级时间戳
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@audio.wav \
-F model=qwen3-asr-p25 \
-F response_format=verbose_json \
-F "timestamp_granularities[]=word"

# 带上下文提示以辅助拼写
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@audio.wav \
-F model=qwen3-asr-p25 \
-F prompt="Engine 12, Ladder 7, Elmhurst Avenue"

# 纯文本响应
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@audio.wav \
-F response_format=text

参数：

响应格式：

json（默认）：

{"text": "All units respond to 5th and Main."}

verbose_json：

{
"task": "transcribe",
"language": "English",
"text": "All units respond to 5th and Main.",
"processing_time": 0.832,
"model": "qwen3-asr-p25-0.6B",
"words": [
{"word": "All", "start": 0.24, "end": 0.48},
{"word": "units", "start": 0.52, "end": 0.88}
]
}

text：

All units respond to 5th and Main.

GET /v1/models

列出已加载的模型。与OpenAI模型列表兼容。

GET /health

返回服务器状态、模型信息、当前配置以及每个工作进程的请求计数器。

提示/上下文

prompt参数允许您向模型传递上下文以影响转录结果。它会被注入模型的系统提示中，引导 token 概率向特定术语倾斜。两个后端均支持此参数——在Python后端中映射为context，在C后端中映射为--prompt。

使用场景：

• 拼写和专有名词——引导模型识别其原本可能无法正确识别的特定领域名称
• 格式风格——提示首选的输出约定
• 领域词汇——提供音频源中常见的行话或缩写

示例：

# 帮助识别本地街道名称和单位编号
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="Rensselaer County, Engine 45, Pawling Avenue, Taconic Parkway"

# 缩写和格式提示
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="Use standard abbreviations: EMS, CPR, MVA, DOA"

# 使用Python OpenAI客户端
curl -X POST http://localhost:8765/v1/audio/transcriptions \
-F file=@dispatch.wav \
-F model=qwen3-asr-p25 \
-F prompt="St. Clair Shores PD, Lake Shore Drive, Jefferson Avenue"

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8765/v1", api_key="not-needed")

transcript = client.audio.transcriptions.create(
model="qwen3-asr-p25",
file=open("dispatch.wav", "rb"),
prompt="Engine 12, Ladder 7, Battalion 3, Elmhurst Avenue",
)
print(transcript.text)

注意事项： 提示偏向性“非常弱”——模型可能会也可能不会遵循您的指示。拼写提示通常效果最佳。强烈或冗长的提示可能会严重影响模型，导致其复述提示而非反映实际音频内容。长提示还会增加序列长度以及每个请求的内存/计算量。建议从简短、事实性的上下文（专有名词、缩写）开始，而非完整句子。如果结果变差，请尝试缩短提示或完全移除提示。

推理后端

服务器支持两种推理后端：

Python（INFERENCE_BACKEND=python，默认）——使用PyTorch + transformers，支持GPU加速（CUDA或MPS）。通过ForcedAligner支持词级时间戳。这是用于GPU生产环境的全功能后端。

C（INFERENCE_BACKEND=c）——使用https://github.com/antirez/qwen-asr C二进制文件。无需GPU、PyTorch或CUDA。模型权重通过内存映射加载，推理通过OpenBLAS在CPU上运行。Docker CPU镜像约800MB，而GPU镜像为多GB。权衡：不支持词级时间戳。

音频预处理

RMS音量门控

音频首先通过RMS（均方根）音量门控过滤：

• 计算整个音频的RMS音量
• 如果RMS < SPEECH_RMS_THRESHOLD，返回空转录结果
• 默认阈值：0.01

如果处理不同的音频源，请调整SPEECH_RMS_THRESHOLD。

幻觉检测

已知的幻觉短语（例如“thank you for watching”、“hello how are you doing today...”）会与标准化转录输出进行匹配，匹配时将返回空字符串拒绝转录。

重复循环检测

检测模型是否进入解码循环（例如“Engine 5 Engine 5 Engine 5 Engine 5”）。检查1-4元语法，如果任何模式重复REPETITION_THRESHOLD（默认4）次或更多，则拒绝转录。仅检查包含8个以上单词的文本，以避免对短而合法的调度音频产生误判。阈值4可避免误判——调度员通常会重复单位名称2-3次。

推理超时

每个请求有INFERENCE_TIMEOUT（默认120秒）安全机制。GPU推理通常在<2秒内完成；CPU推理对于较长音频文件可能需要30-60秒。120秒的默认值对CPU部署是安全的，同时仍能捕获真正的异常解码循环。超时后，返回空转录结果并记录事件。

日志

所有事件使用Python的logging模块以结构化格式记录：

2026-03-02 14:30:01,234 [12345] INFO OK file=call_123.wav words=15 time=0.832s
2026-03-02 14:30:02,567 [12345] WARNING REJECT rms_gate file=call_456.wav rms=0.0021 threshold=0.01 time=0.012s

拒绝事件（REJECT rms_gate、REJECT hallucination、REJECT repetition_loop、REJECT timeout）以WARNING级别记录。成功转录（OK）以INFO级别记录。

/health端点包含跟踪每个结果的每个工作进程计数器。

优雅关闭

服务器使用uvicorn内置的timeout_graceful_shutdown在退出前处理完进行中的请求。默认值为15秒。systemd服务设置TimeoutStopSec=30，以便在systemd发送SIGKILL前给uvicorn足够时间完成请求处理。

作为服务运行

包含示例systemd单元文件。编辑systemd/qwen3-asr.service中的路径和用户，然后执行：

sudo cp systemd/qwen3-asr.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now qwen3-asr

支持的语言

英语、中文、粤语、日语、韩语、法语、德语、西班牙语、葡萄牙语、意大利语、俄语、阿拉伯语、印尼语——以及更多（完整列表见模型配置）。可传递ISO 639-1代码（en、zh、fr）或全名（English、Chinese、French）。