ASR模型本地部署与服务调用教程

[0.48][S01]大家好，欢迎来到本期教程[4.10][12.26][S02]今天我们聊一聊语音识别模型的本地部署[15.80][16.02][S01]好的，我们正式开始[18.76]

import re

pattern = re.compile(r"\[(\d+(?:\.\d+)?)\]\[S(\d+)\](.*?)\[(\d+(?:\.\d+)?)\]", re.S)

# 创建并激活 conda 环境（vLLM 官方推荐 Python 3.12）
conda create -n vllm python=3.12 -y
conda activate vllm

# 安装 uv（Python 包管理工具）
pip install uv

# 安装 vLLM（0.26.0 起原生包含 MOSS-Transcribe-Diarize 模型注册，自动匹配 CUDA 版本的 PyTorch）
uv pip install -U vllm --torch-backend=auto

# 安装音频解码依赖
uv pip install soundfile

# 编辑 ~/models/MOSS-Transcribe-Diarize/generation_config.json
# 将 max_new_tokens 修改为 16384，防止长音频转写被截断
{
  "max_new_tokens": 16384
}

conda activate vllm

# WSL2 环境必需的三个环境变量
export VLLM_WSL2_ENABLE_PIN_MEMORY=1
export VLLM_MAX_AUDIO_DECODE_DURATION_S=5400
export VLLM_MAX_AUDIO_CLIP_FILESIZE_MB=200

# 启动服务（前台运行，关闭终端服务即停）
vllm serve ~/models/MOSS-Transcribe-Diarize \
  --trust-remote-code \
  --port 8001 \
  --gpu-memory-utilization 0.55 \
  --max-model-len 32768 \
  --max-num-batched-tokens 16384 \
  --served-model-name moss-asr

curl http://localhost:8001/v1/models

{"object": "list", "data": [{"id": "moss-asr", "object": "model"}]}

# 抽取音轨为 16kHz 单声道 wav
ffmpeg -y -i test.mp3 -vn -ac 1 -ar 16000 test.wav

# 调用 vLLM 转写接口
curl -sS http://localhost:8001/v1/audio/transcriptions \
  -F "model=moss-asr" \
  -F "response_format=json" \
  -F "temperature=0" \
  -F "file=@test.wav"

{"text": "[0.48][S01]大家好，欢迎来到本期教程[4.10][12.26][S02]今天我们聊一聊语音识别模型的本地部署[15.80]"}

voice2text/
├── config.py                  # 服务配置（端口、vLLM 服务地址、热词、字幕分段时长）
├── main.py                    # FastAPI 后端，识别与字幕接口
├── asr_service.py             # ASR 识别服务（vLLM 客户端与段式文本解析）
├── subtitle.py                # 字幕格式化（SRT / VTT 生成）
├── requirements.txt           # 依赖管理
├── static/
│   └── index.html             # 前端页面（上传 + 录音 + 字幕下载）
└── README.md                  # 项目说明

# config.py（核心片段，完整代码请查看 voice2text/config.py）
PORT = 8000

# WSL2 内 vLLM 转写服务地址（承载 MOSS-Transcribe-Diarize 模型）
ASR_SERVICE_URL = "http://localhost:8001"

# vLLM 服务的模型名称（对应启动服务时的 --served-model-name）
ASR_MODEL_NAME = "moss-asr"

# 采样温度，转写任务固定为 0 保证同一音频的结果稳定
ASR_TEMPERATURE = 0

# 常驻热词（逗号分隔），产品名、人名、术语等，可显著减少专名错别字
ASR_HOTWORDS = ""

# 逐字转写：保留语气词（嗯、呃、啊）与口误，剪辑对轴场景建议开启
ASR_VERBATIM = False

# 转写请求超时（秒），长音频转写耗时数分钟，放宽到 1 小时
REQUEST_TIMEOUT_SEC = 3600

# 字幕单条最大时长（秒），值越小每条字幕越短、时间轴越细
SUBTITLE_MAX_LENGTH_S = 5

# 字幕是否去除句读标点（句号、逗号等），仅影响字幕下载，正文聚合识别不受影响
SUBTITLE_STRIP_PUNCTUATION = True

# asr_service.py（核心片段，完整代码请查看 voice2text/asr_service.py）
# 默认提示词：让模型输出带时间戳与说话人编号的段式文本（与官方推荐一致）
DEFAULT_PROMPT = (
    "请将音频转写为文本，每一段需以起始时间戳和说话人编号"
    "（[S01]、[S02]、[S03]…）开头，正文为对应的语音内容，"
    "并在段末标注结束时间戳，以清晰标明该段语音范围。"
)

# 逐字转写后缀：保留语气词与口误，适合剪辑对轴场景
VERBATIM_SUFFIX = "请逐字转写，保留语气词（嗯、呃、啊）和口误，不要润色或省略。"

# 整洁文稿后缀：与逐字转写二选一，实测追加指令后缀可稳定模型的段式输出格式
CONCISE_SUFFIX = "请省略语气词与口误，输出整洁文稿。"

# 段式文本解析：[起始秒][S01]正文[结束秒]，相邻段落共用中间的时间戳
_SEGMENT_PATTERN = re.compile(
    r"\[(\d+(?:\.\d+)?)\]\[S(\d+)\](.*?)\[(\d+(?:\.\d+)?)\]", re.S
)


def build_prompt(hotwords, verbatim):
    """组装提示词：热词前置 + 基础指令 + 逐字/整洁后缀（二选一）"""
    prompt = ""
    if hotwords:
        prompt += f"热词提示：{hotwords}。"
    prompt += DEFAULT_PROMPT
    prompt += VERBATIM_SUFFIX if verbatim else CONCISE_SUFFIX
    return prompt


def _extract_wav(audio_path):
    """用 ffmpeg 把任意格式音频统一为 16kHz 单声道 wav（模型要求的输入格式）"""
    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".wav")
    tmp.close()
    subprocess.run(
        ["ffmpeg", "-y", "-v", "error", "-i", audio_path,
         "-vn", "-ac", "1", "-ar", "16000", tmp.name],
        check=True,
    )
    return tmp.name


def _call_service(wav_path, prompt):
    """上传 wav 到 vLLM 服务，返回模型输出的段式文本"""
    with open(wav_path, "rb") as f:
        resp = requests.post(
            f"{ASR_SERVICE_URL}/v1/audio/transcriptions",
            files={"file": ("audio.wav", f, "audio/wav")},
            data={
                "model": ASR_MODEL_NAME,
                "response_format": "json",
                "temperature": ASR_TEMPERATURE,
                "prompt": prompt,
            },
            timeout=REQUEST_TIMEOUT_SEC,
        )
    resp.raise_for_status()
    return resp.json().get("text", "")


def parse_segments(text):
    """解析 [起始][S01]正文[结束] 段式文本，返回带说话人的分段列表"""
    segments = []
    for m in _SEGMENT_PATTERN.finditer(text):
        segments.append({
            "start": int(float(m.group(1)) * 1000),
            "end": int(float(m.group(4)) * 1000),
            "speaker": f"S{m.group(2)}",
            "text": m.group(3).strip(),
        })
    return segments


def transcribe(audio_path, hotwords=None, verbatim=None):
    """整段转写：返回拼接后的纯文本（保留标点，去除时间戳与说话人标签）"""
    hot = ASR_HOTWORDS if hotwords is None else hotwords
    verb = ASR_VERBATIM if verbatim is None else verbatim
    segments = _transcribe(audio_path, hot, verb)
    return "".join(seg["text"] for seg in segments)


def transcribe_segments(audio_path, hotwords=None, verbatim=None):
    """字幕转写：返回 [{"start": 毫秒, "end": 毫秒, "text": 文本}]"""
    hot = ASR_HOTWORDS if hotwords is None else hotwords
    verb = ASR_VERBATIM if verbatim is None else verbatim
    segments = _transcribe(audio_path, hot, verb)
    # 超过字幕时长上限的段落二次细分，切口不落入英文数字单元内部
    segments = split_segments(segments, SUBTITLE_MAX_LENGTH_S * 1000)
    # 字幕场景默认去除句读标点，与正文聚合识别结果区分
    if SUBTITLE_STRIP_PUNCTUATION:
        segments = strip_punctuation(segments)
    return segments

# main.py（核心片段，完整代码请查看 voice2text/main.py）
@app.post("/api/transcribe")
def transcribe(
    file: UploadFile = File(...),
    hotwords: str = Form(""),
    verbatim: bool = Form(False),
):
    """自定义识别接口：上传音频文件，返回识别文字"""
    audio_path = _save_audio(file)               # 保存为临时文件
    try:
        text = asr_service.transcribe(audio_path, hotwords=hotwords or None,
                                      verbatim=verbatim)
    finally:
        os.unlink(audio_path)                    # 识别后清理临时文件
    return {"text": text}

@app.post("/v1/audio/transcriptions")
def transcriptions(
    file: UploadFile = File(...),
    model: str = Form("moss-asr"),
):
    """OpenAI 兼容的语音识别接口（model 参数仅做兼容）"""
    audio_path = _save_audio(file)
    try:
        text = asr_service.transcribe(audio_path)
    finally:
        os.unlink(audio_path)
    return {"text": text}                        # OpenAI 兼容返回格式

@app.post("/api/subtitle")
def generate_subtitle(
    file: UploadFile = File(...),
    hotwords: str = Form(""),
    verbatim: bool = Form(False),
    fmt: str = Form("srt"),                      # srt / vtt
):
    """字幕识别接口：返回可下载的字幕文件"""
    audio_path = _save_audio(file)
    try:
        segments = asr_service.transcribe_segments(audio_path, hotwords=hotwords or None,
                                                   verbatim=verbatim)
    finally:
        os.unlink(audio_path)
    content = subtitle.to_vtt(segments) if fmt == "vtt" else subtitle.to_srt(segments)
    return Response(
        content=content,
        media_type="text/vtt; charset=utf-8" if fmt == "vtt"
                   else "application/x-subrip; charset=utf-8",
        headers={"Content-Disposition": f"attachment; filename*=UTF-8''{quote(filename)}"},
    )

# subtitle.py（核心片段，完整代码请查看 voice2text/subtitle.py）
def _format_timestamp(ms, decimal_sep):
    """毫秒转 HH:MM:SS,mmm（SRT 用逗号）或 HH:MM:SS.mmm（VTT 用点）"""
    hours, rem = divmod(max(0, int(ms)), 3600_000)
    minutes, rem = divmod(rem, 60_000)
    seconds, millis = divmod(rem, 1000)
    return f"{hours:02d}:{minutes:02d}:{seconds:02d}{decimal_sep}{millis:03d}"

def to_srt(segments):
    """生成 SRT 格式字幕内容"""
    cues = []
    for i, seg in enumerate(segments, start=1):
        start = _format_timestamp(seg["start"], ",")
        end = _format_timestamp(seg["end"], ",")
        cues.append(f"{i}\n{start} --> {end}\n{seg['text']}")
    return "\n\n".join(cues) + "\n"

1
00:00:00,480 --> 00:00:04,100
大家好欢迎来到本期教程

2
00:00:12,260 --> 00:00:15,800
今天我们聊一聊语音识别模型的本地部署

# fmt 可选 srt / vtt，-o 指定保存路径
curl.exe -X POST http://localhost:8000/api/subtitle -F "file=@C:/path/to/audio.mp3" -F "fmt=srt" -o audio.srt

conda create -n voice2text python=3.10 -y
conda activate voice2text
pip install uv

cd voice2text

# 安装服务依赖（无需 PyTorch，安装很轻量）
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple

python main.py

curl.exe -X POST http://localhost:8000/api/transcribe -F "file=@C:/path/to/audio.wav"

# 带热词转写（修正专名错别字）
curl.exe -X POST http://localhost:8000/api/transcribe -F "file=@C:/path/to/audio.wav" -F "hotwords=FastAPI,vLLM"

# 验证字幕接口
curl.exe -X POST http://localhost:8000/api/subtitle -F "file=@C:/path/to/audio.mp3" -F "fmt=srt" -o audio.srt

# 使用 openai SDK 调用本地 voice2text 服务
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",  # 本地服务地址
    api_key="not-needed",                 # 本地服务不校验 Key
)

with open("audio.wav", "rb") as f:
    result = client.audio.transcriptions.create(
        model="moss-asr",
        file=f,
    )
print(result.text)