# whisper-server **Repository Path**: openminds/whisper-server ## Basic Information - **Project Name**: whisper-server - **Description**: 基于 OpenAI Whisper 的语音转文字服务，提供与 OpenAI API 兼容的接口。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-14 - **Last Updated**: 2026-07-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: whisper, FastAPI ## README # Whisper Speech-to-Text Server 基于 OpenAI Whisper 的语音转文字服务，提供与 OpenAI API 兼容的接口。 ## 特性 - ✅ 支持多种语音格式（通过 FFmpeg 转换） - ✅ 支持多种输出格式（JSON、文本、SRT、VTT） - ✅ 支持语音翻译（其他语言 → 英语） - ✅ OpenAI API 兼容接口 - ✅ 支持多种 Whisper 模型（tiny / base / small / medium / large） - ✅ 健康检查端点 - ✅ 模型预加载机制 ## 系统架构 ```mermaid flowchart TB subgraph Client["客户端"] A[HTTP 请求] end subgraph FastAPI["FastAPI Server (Port 9000)"] B1["/health
健康检查"] B2["/v1/models
列出可用模型"] B3["/v1/audio/transcriptions
语音转文字"] B4["/v1/audio/translations
语音翻译"] end subgraph Processing["处理层"] C1["FFmpeg
音频格式转换"] C2["音频预处理
采样率 16kHz"] end subgraph Model["Whisper 模型"] D[("tiny / base / small / medium / large")] end subgraph Output["输出格式"] E1["JSON"] E2["Text"] E3["SRT"] E4["VTT"] E5["Verbose JSON"] end A --> B1 A --> B2 A --> B3 A --> B4 B3 --> C1 B4 --> C1 C1 --> C2 C2 --> D D --> E1 D --> E2 D --> E3 D --> E4 D --> E5 ``` ## 安装 ### 前置依赖 - Python >= 3.10 - [uv](https://github.com/astral-sh/uv) - Python 包管理器 - [FFmpeg](https://ffmpeg.org/) - 用于音频格式转换 ### 使用 uv 安装 ```bash # 克隆项目 git clone cd my-whisper # 创建虚拟环境并安装依赖（自动启用脚本命令） uv sync ``` ## 运行 ### 启动服务 ```bash # 方式一：使用脚本命令（推荐） uv run whisper-server # 方式二：直接运行 Python 文件 uv run python whisper_server.py # 方式三：使用 uvicorn uv run uvicorn whisper_server:app --host 0.0.0.0 --port 9000 ``` 服务启动后访问: http://localhost:9000 **注意**：服务启动时会自动预加载默认模型（`small`），首次加载可能需要几秒钟。 ### 模型选择 默认使用 `small` 模型。可以通过以下方式选择模型： **方式一：修改代码默认模型** 编辑 `whisper_server.py` 中的 `_model_name` 变量： ```python _model_name = "medium" # tiny, base, small, medium, large ``` **方式二：请求时指定模型** 调用 API 时通过 `model` 参数动态指定模型： ```bash curl -X POST http://localhost:9000/v1/audio/transcriptions \ -F "file=@test.wav" \ -F "model=medium" ``` > **说明**：当 `model` 参数为 `whisper-1`（默认值）时，使用服务器当前加载的模型；其他值会直接传递给 Whisper 加载对应的模型。 ## API 接口 | 端点 | 方法 | 描述 | |------|------|------| | `/health` | GET | 健康检查 | | `/v1/models` | GET | 列出可用模型 | | `/v1/audio/transcriptions` | POST | 语音转文字 | | `/v1/audio/translations` | POST | 语音翻译（→ 英语） | ### 健康检查 ```bash curl http://localhost:9000/health ``` **响应状态**： | 状态码 | 响应 | 说明 | |--------|------|------| | 200 | `{"status": "ok"}` | 服务正常 | | 503 | `{"status": "loading model"}` | 模型加载中 | | 503 | `{"status": "not ready"}` | 服务未就绪 | ### 列出模型 ```bash curl http://localhost:9000/v1/models ``` 响应示例： ```json { "data": [ {"id": "tiny", "object": "model", "owned_by": "openai", "permission": []}, {"id": "base", "object": "model", "owned_by": "openai", "permission": []}, {"id": "small", "object": "model", "owned_by": "openai", "permission": []}, {"id": "medium", "object": "model", "owned_by": "openai", "permission": []}, {"id": "large", "object": "model", "owned_by": "openai", "permission": []} ], "object": "list" } ``` ### 语音转文字 ```bash curl -X POST http://localhost:9000/v1/audio/transcriptions \ -F "file=@test.wav" \ -F "model=whisper-1" \ -F "language=zh" \ -F "response_format=json" ``` **参数说明**： | 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `file` | File | 必填 | 音频文件 | | `model` | String | whisper-1 | 模型名称（`whisper-1` 使用默认模型，其他值直接传递给 Whisper） | | `language` | String | None | 语言代码（如 zh, en, ja），自动检测时设为 None | | `prompt` | String | None | 提示文本，用于引导模型识别 | | `response_format` | String | json | 输出格式（json, text, srt, vtt, verbose_json） | | `temperature` | Float | 0.0 | 温度参数，控制输出随机性 | | `translate` | Boolean | false | 是否翻译为英语 | **响应示例（JSON）**： ```json {"text": "你好，这是一段测试语音。"} ``` **响应示例（SRT）**： ``` 1 00:00:00,000 --> 00:00:02,500 你好，这是一段测试语音。 ``` **响应示例（Verbose JSON）**： ```json { "text": "你好，这是一段测试语音。", "segments": [ { "id": 0, "start": 0.0, "end": 2.5, "text": "你好，这是一段测试语音。", "tokens": [50364, 2527, 2500, 42, 1746, 2523, 372, 445, 6965, 2500], "temperature": 0.0, "avg_logprob": -0.3, "compression_ratio": 1.2, "no_speech_prob": 0.01 } ], "language": "zh" } ``` ### 语音翻译 将其他语言翻译成英语。 ```bash curl -X POST http://localhost:9000/v1/audio/translations \ -F "file=@test.wav" \ -F "model=whisper-1" ``` **参数说明**： | 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `file` | File | 必填 | 音频文件 | | `model` | String | whisper-1 | 模型名称 | | `prompt` | String | None | 提示文本 | | `response_format` | String | json | 输出格式 | | `temperature` | Float | 0.0 | 温度参数 | > **注意**：翻译接口不支持 `language` 参数，语言会自动检测。 ## 支持的语言 | 语言代码 | 语言 | |----------|------| | zh | 中文 | | en | 英语 | | ja | 日语 | | ko | 韩语 | | fr | 法语 | | de | 德语 | | es | 西班牙语 | | ru | 俄语 | 更多语言请参考 [Whisper 官方文档](https://github.com/openai/whisper)。 ## 支持的输出格式 | 格式 | 描述 | |------|------| | json | 返回包含文本的 JSON 对象 | | text | 返回纯文本 | | srt | 返回 SRT 字幕格式 | | vtt | 返回 WebVTT 字幕格式 | | verbose_json | 返回包含详细信息的 JSON（文本、分段、语言） | ## 测试 项目包含 `test.wav` 测试文件，可用于验证服务： ```bash curl -X POST http://localhost:9000/v1/audio/transcriptions \ -F "file=@test.wav" \ -F "response_format=text" ``` ## 项目结构 ``` my-whisper/ ├── whisper_server.py # 主服务文件 ├── pyproject.toml # 项目配置（含构建系统与脚本定义） ├── uv.lock # 依赖锁文件 ├── test.wav # 测试音频 └── .venv/ # 虚拟环境 ``` ## 项目配置 `pyproject.toml` 关键配置说明： ```toml [project] name = "whisper-server" version = "1.0.0" dependencies = [ "fastapi>=0.110.0", "uvicorn>=0.24.0", "openai-whisper>=20231117", "torch>=2.1.0", "python-multipart>=0.0.32", ] [[tool.uv.index]] url = "https://uv.agentsmirror.com/pypi/simple" default = true [tool.uv] package = true # 启用包模式以支持 entry points [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project.scripts] whisper-server = "whisper_server:main" # 命令行入口 ``` ## 与 hwdsl2/whisper-server 的兼容性 本服务提供与 `hwdsl2/whisper-server:latest` Docker 镜像兼容的 API 接口，支持相同的端点和参数格式。 ## 许可证 MIT License