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

from faster_whisper import WhisperModel

# 加载本地模型（GPU 使用 float16，CPU 使用 int8）
model = WhisperModel(
    "C:/models/faster-whisper-large-v3",
    device="cuda",          # 无 GPU 时改为 "cpu"
    compute_type="float16",
)

segments, info = model.transcribe(
    "audio.mp3",            # 任意格式音频
    language="zh",          # 语种代码，传 None 表示自动检测
    beam_size=5,            # 束搜索宽度
    vad_filter=True,        # 过滤静音段，抑制幻觉
)

for seg in segments:
    print(f"[{seg.start:.1f} -> {seg.end:.1f}] {seg.text}")

# 创建并激活 conda 环境
conda create -n voice2text python=3.10 -y
conda activate voice2text

# 安装 lzma 运行库（conda 的 Python 可能缺少 _lzma 模块，避免后续报错）
conda install -c conda-forge liblzma -y

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

cd voice2text

# 安装服务依赖（含 faster-whisper、fastapi、uvicorn 等）
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# GPU 推理可选：安装 CUDA 运行库（cuBLAS 与 cuDNN，CPU 推理可跳过）
uv pip install nvidia-cublas-cu12 nvidia-cudnn-cu12 --index-url https://pypi.tuna.tsinghua.edu.cn/simple

voice2text/
├── config.py                  # 服务配置（端口、模型路径、设备、字幕分段时长）
├── main.py                    # FastAPI 后端，识别与字幕接口
├── asr_service.py             # ASR 识别服务（faster-whisper 封装）
├── subtitle.py                # 字幕格式化（SRT / VTT 生成）
├── requirements.txt           # 依赖管理
├── static/
│   └── index.html             # 前端页面（上传 + 录音 + 字幕下载）
└── README.md                  # 项目说明

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

# faster-whisper 模型目录（需包含 model.bin、tokenizer.json 等文件）
ASR_MODEL_DIR = "C:/models/faster-whisper-large-v3"

# 推理设备：cuda / cpu（cuda 初始化失败会自动回退 cpu）
ASR_DEVICE = "cuda"

# 识别语言：auto（自动检测）/ zh / en / yue / ja / ko 等
ASR_LANGUAGE = "zh"

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

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

# asr_service.py（核心片段，完整代码请查看 voice2text/asr_service.py）
def _get_model():
    """懒加载 faster-whisper 模型（首次调用时加载），GPU 失败自动回退 CPU"""
    global _model
    if _model is None:
        from faster_whisper import WhisperModel

        _add_nvidia_dll_dirs()               # 引入 pip 安装的 CUDA 运行库
        if ASR_DEVICE.startswith("cuda"):
            try:
                _model = WhisperModel(ASR_MODEL_DIR, device="cuda", compute_type="float16")
            except Exception as e:
                logger.warning("CUDA 初始化失败，回退 CPU：%s", e)
                _model = WhisperModel(ASR_MODEL_DIR, device="cpu", compute_type="int8")
        else:
            _model = WhisperModel(ASR_MODEL_DIR, device="cpu", compute_type="int8")
    return _model


def transcribe(audio_path, language=None):
    """将音频文件识别为整段文字"""
    items = _transcribe(audio_path, language, with_words=False)
    return "".join(item["text"] for item in items)


def transcribe_segments(audio_path, language=None):
    """将音频识别为带时间戳的字幕分段列表"""
    items = _transcribe(audio_path, language, with_words=True)
    segments = [{
        "start": int(item["start"] * 1000),  # 起始毫秒
        "end": int(item["end"] * 1000),      # 结束毫秒
        "text": item["text"],
    } for item in items]
    # 超过字幕时长上限的段落二次细分，切口不落入英文数字单元内部
    segments = split_segments(segments, SUBTITLE_MAX_LENGTH_S * 1000)
    # 字幕场景默认去除句读标点，与正文聚合识别结果区分
    if SUBTITLE_STRIP_PUNCTUATION:
        segments = strip_punctuation(segments)
    return segments


def _transcribe(audio_path, language, with_words):
    """执行一次转写，返回 [{"start": 秒, "end": 秒, "text": 文本}]"""
    model = _get_model()
    lang = language or ASR_LANGUAGE

    segments_iter, _info = model.transcribe(
        audio_path,
        language=None if lang in ("auto", "") else lang,
        beam_size=5,
        vad_filter=True,                    # 过滤静音段，抑制幻觉
        condition_on_previous_text=False,   # 降低长音频的重复幻觉风险
        word_timestamps=with_words,         # 字幕场景使用词级时间戳收紧边界
    )
    items = []
    with _recog_lock:                       # 生成器遍历时才真正推理，需持有全局锁
        for seg in segments_iter:
            text = seg.text.strip()
            if text:
                items.append({"start": seg.start, "end": seg.end, "text": text})
    return items

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

@app.post("/v1/audio/transcriptions")
async def transcriptions(
    file: UploadFile = File(...),
    model: str = Form("whisper-large-v3"),
    language: str = Form("auto"),
):
    """OpenAI 兼容的语音识别接口"""
    audio_path = _save_audio(file)
    try:
        text = asr_service.transcribe(audio_path, language=language or None)
    finally:
        os.unlink(audio_path)
    return {"text": text}                        # OpenAI 兼容返回格式

@app.post("/api/subtitle")
async def generate_subtitle(
    file: UploadFile = File(...),
    language: str = Form("auto"),
    fmt: str = Form("srt"),                      # srt / vtt
):
    """字幕识别接口：返回可下载的字幕文件"""
    audio_path = _save_audio(file)
    try:
        segments = asr_service.transcribe_segments(
            audio_path, language=language or None
        )
    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,420 --> 00:00:05,600
开放时间早上9点至下午5点

2
00:00:06,100 --> 00:00:11,300
自动字幕生成可以大幅提升视频制作效率

# 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 activate voice2text
cd voice2text

# 安装服务依赖（若第 3 章已安装可跳过）
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/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="whisper-large-v3",
        file=f,
        language="zh",
    )
print(result.text)