Whisper语音识别服务API文档：Swagger集成与测试

1. 引言

1.1 业务场景描述

在多语言内容处理、智能客服、会议记录和教育科技等实际应用中，语音识别技术已成为关键基础设施。基于 OpenAI 的 Whisper 模型构建的语音识别 Web 服务，能够实现高精度、低延迟的自动语音转录，尤其适用于需要支持多种语言的全球化应用场景。

本项目由by113小贝二次开发，封装了Whisper large-v3模型为可部署的 Web 服务，并集成了 Gradio 可视化界面与 RESTful API 接口。为进一步提升接口的可用性与调试效率，本文重点介绍如何将 Swagger（通过 FastAPI 自动生成）集成到服务中，实现 API 文档的可视化展示与在线测试功能。

1.2 痛点分析

原始 Whisper 模型虽具备强大识别能力，但缺乏标准化的服务暴露机制：

• 缺少结构化 API 接口定义
• 调试依赖代码调用，无法直观测试
• 第三方系统集成成本高
• 无统一文档入口，不利于团队协作

这些问题限制了模型在生产环境中的快速落地。

1.3 方案预告

本文将详细介绍：

• 如何基于 FastAPI 封装 Whisper 服务接口
• 集成 Swagger UI 实现 API 可视化文档
• 提供完整的请求/响应示例
• 支持音频文件上传与实时转录测试
• 给出部署建议与安全配置提示

最终目标是打造一个“开箱即用”的语音识别 API 服务，支持开发者一键查看文档并完成接口调用验证。

2. 技术方案选型

2.1 为什么选择 FastAPI + Swagger？

因此，FastAPI 是当前最适合构建高性能 AI 服务 API 的框架之一。

2.2 与 Gradio 的协同架构

Gradio 提供用户友好的交互式界面，适合演示和内部测试；而 FastAPI 提供标准 HTTP 接口，便于系统集成。两者可以共存于同一服务中：

+---------------------+ | Client (UI) | ←→ Gradio (http://:7860) +---------------------+ | Third-party App | ←→ FastAPI (http://:8000/docs) +---------------------+ ↓ Whisper Model (GPU)

我们将 Gradio 保留在 7860 端口用于交互体验，同时新增 FastAPI 服务运行在 8000 端口提供 API 访问。

3. 实现步骤详解

3.1 修改目录结构以支持 API 服务

更新后的项目结构如下：

/root/Whisper-large-v3/ ├── app.py # Gradio 主程序（保留） ├── api_server.py # 新增：FastAPI 服务入口 ├── whisper_service.py # 新增：模型加载与推理逻辑复用模块 ├── requirements.txt ├── configuration.json ├── config.yaml └── example/

3.2 抽取核心推理逻辑（whisper_service.py）

# whisper_service.py import whisper import torch _model = None def load_whisper_model(): """懒加载 Whisper large-v3 模型""" global _model if _model is None: print("Loading Whisper large-v3 model...") _model = whisper.load_model("large-v3", device="cuda" if torch.cuda.is_available() else "cpu") return _model def transcribe_audio(file_path, language=None, task="transcribe"): """ 执行语音识别或翻译 :param file_path: 音频文件路径 :param language: 指定语言（如 'zh'），None 表示自动检测 :param task: 'transcribe' 或 'translate' :return: 转录结果 dict """ model = load_whisper_model() result = model.transcribe(file_path, language=language, task=task) return {"text": result["text"], "language": result["language"], "segments": result.get("segments", [])}

3.3 构建 FastAPI 服务（api_server.py）

# api_server.py from fastapi import FastAPI, File, UploadFile, Form, HTTPException from fastapi.responses import JSONResponse from fastapi.middleware.cors import CORSMiddleware import tempfile import os import logging from whisper_service import transcribe_audio app = FastAPI( title="Whisper Large v3 - Speech-to-Text API", description="基于 OpenAI Whisper large-v3 的多语言语音识别 API，支持 99 种语言自动检测与转录。", version="1.0.0", docs_url="/docs", # 启用 Swagger UI redoc_url="/redoc" # 启用 ReDoc ) # 允许跨域（适用于前端调用） app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) @app.post("/v1/transcribe", summary="语音转录接口") async def api_transcribe( audio: UploadFile = File(..., description="上传的音频文件，支持 WAV/MP3/M4A/FLAC/OGG"), language: str = Form(None, description="指定语言代码（如 zh, en），留空则自动检测"), task: str = Form("transcribe", description="任务类型：transcribe 或 translate") ): """ 接收音频文件并返回转录文本。 支持自动语言检测（99种语言）和英译功能。 """ if not audio.filename.lower().endswith(('.wav', '.mp3', '.m4a', '.flac', '.ogg')): raise HTTPException(status_code=400, detail="不支持的音频格式") # 创建临时文件保存上传内容 with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(audio.filename)[1]) as tmp: content = await audio.read() tmp.write(content) temp_path = tmp.name try: result = transcribe_audio(temp_path, language=language, task=task) return JSONResponse(content={"success": True, "data": result}) except Exception as e: logging.error(f"Transcription failed: {str(e)}") raise HTTPException(status_code=500, detail=f"转录失败: {str(e)}") finally: # 清理临时文件 if os.path.exists(temp_path): os.unlink(temp_path) @app.get("/v1/health", summary="健康检查") def health_check(): """用于负载均衡和服务探活""" return {"status": "healthy", "model": "whisper-large-v3", "gpu": torch.cuda.is_available()}

3.4 更新 requirements.txt

确保包含以下依赖：

fastapi>=0.110.0 uvicorn[standard]>=0.29.0 pydantic>=2.0 gradio>=4.0 torch>=2.0.0 whisper==1.1.10 ffmpeg-python>=0.2.0

3.5 启动双服务脚本

创建start_services.sh：

#!/bin/bash # 同时启动 Gradio 和 FastAPI 服务 echo "Starting Whisper services..." # 终端1：启动 Gradio UI python3 app.py --server_port 7860 & # 终端2：启动 FastAPI + Swagger uvicorn api_server:app --host 0.0.0.0 --port 8000 --reload & echo "Services running:" echo " - Gradio UI: http://localhost:7860" echo " - API Docs: http://localhost:8000/docs" echo " - API Redoc: http://localhost:8000/redoc" wait

赋予执行权限：

chmod +x start_services.sh ./start_services.sh

4. Swagger API 文档使用指南

4.1 访问 Swagger UI

启动服务后，访问：

http://localhost:8000/docs

你将看到自动生成的交互式 API 文档页面，包含：

• /v1/transcribe：语音转录接口
• /v1/health：健康检查接口

4.2 在线测试语音识别接口

步骤说明：

1. 展开POST /v1/transcribe接口
2. 点击「Try it out」按钮
3. 填写表单参数：
   • audio: 选择本地音频文件（≤25MB）
   • language: 可选，如zh（中文）、en（英文）
   • task:transcribe（原文转录）或translate（翻译成英文）
4. 点击「Execute」发起请求

示例响应：

{ "success": true, "data": { "text": "你好，这是一个测试音频。", "language": "zh", "segments": [ { "id": 0, "start": 0.0, "end": 3.2, "text": "你好，这是一个测试音频。" } ] } }

4.3 使用 cURL 调用示例

curl -X POST "http://localhost:8000/v1/transcribe" \ -H "accept: application/json" \ -F "audio=@test.wav;type=audio/wav" \ -F "language=zh" \ -F "task=transcribe"

5. 实践问题与优化

5.1 常见问题及解决方案

5.2 性能优化建议

• 启用 FP16 推理：在transcribe_audio()中添加fp16=True参数，减少显存占用约 40%
• 缓存模型实例：避免重复加载，已在whisper_service.py中实现单例模式
• 异步处理长音频：对于 >30s 音频，建议拆分为片段并行处理
• 使用 ONNX Runtime 加速：可进一步提升 CPU/GPU 推理速度（需转换模型）

6. 安全与生产建议

6.1 生产环境加固建议

• 禁用调试模式：移除--reload参数
• 限制上传大小：在 Nginx 或 Uvicorn 层设置最大请求体大小（如 25MB）
• 增加身份认证：使用 JWT 或 API Key 验证调用方权限
• 日志审计：记录所有 API 请求用于追踪与分析
• 反向代理保护：使用 Nginx 做 SSL 终止与流量控制

6.2 Docker 化部署建议（可选）

创建Dockerfile：

FROM nvidia/cuda:12.4-runtime-ubuntu24.04 RUN apt-get update && apt-get install -y ffmpeg python3-pip COPY . /app WORKDIR /app RUN pip install -r requirements.txt EXPOSE 7860 8000 CMD ["bash", "start_services.sh"]

构建镜像：

docker build -t whisper-api . docker run --gpus all -p 7860:7860 -p 8000:8000 whisper-api

7. 总结

7.1 实践经验总结

通过本次集成，我们成功将 Whisper large-v3 模型封装为具备完整 API 文档能力的 Web 服务。关键收获包括：

• Swagger 极大提升了接口可用性：非技术人员也能轻松理解并测试 API
• FastAPI + Pydantic 提升稳定性：自动数据校验减少了无效请求带来的异常
• 双服务并行设计兼顾体验与集成：Gradio 用于演示，FastAPI 用于对接系统
• 工程化思维贯穿始终：从模块解耦到异常处理，保障服务健壮性

避坑指南：

• 切勿在每次请求时重新加载模型
• 注意临时文件清理，防止磁盘占满
• 生产环境务必关闭 reload 模式

7.2 最佳实践建议

1. 优先使用 Swagger 进行接口联调，避免手写请求出错
2. 对高频调用场景启用缓存机制，例如相同音频不做重复识别
3. 定期监控 GPU 显存与温度，防止长时间运行导致过热降频

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。