如何用 transformers serve 启动本地语音转写 API 服务？

如何用 transformers serve 启动本地语音转写 API 服务【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers如果你想在本地或自有服务器上暴露一个 OpenAI 兼容的语音转写接口而不是依赖第三方推理引擎可以用 transformers 的transformers serveCLI 完成。它启动一个默认监听 http://localhost:8000 的本地服务其中/v1/audio/transcriptions端点使用 speech-to-text 模型把音频文件转成文本。官方文档说明该方案定位为轻量级本地或自托管服务适合评估、实验和中等负载部署大规模生产场景文档建议改用 vLLM 或 SGLang参见 Inference backends 指南链接原文指向 serve CLI 文档 中的 TIP。整条路径是安装 serving 依赖 → 启动服务 → 准备并确认模型 → 发送转写请求 → 按响应验证结果。以下事实均来自 Serve CLI 文档。安装 serving 依赖并启动服务先安装 serving 依赖pip install transformers[serving]然后启动服务。默认服务地址是 http://localhost:8000transformers serve启动后服务提供以下 REST API其中与语音转写直接相关的是第一条/v1/audio/transcriptions音频转写/v1/chat/completions支持文本、图像、音频、视频请求/v1/completions传统自由文本补全/v1/responsesResponses API/v1/models列出第三方集成可发现的模型/load_model通过 SSE 流式返回模型加载进度准备模型并确认可用/v1/models端点会扫描本地 Hugging Face 缓存返回已下载的模型列表OpenAI 兼容格式。因此文档要求在运行transformers serve之前先下载模型命令模式如下model替换为你的模型 ID转写场景对应 speech-to-text 模型transformers download openai/whisper-large-v3模型下载完成后用下面的请求确认它出现在服务返回的模型列表中curl http://localhost:8000/v1/models端点返回包含可用模型的 JSON 对象模型 ID 出现在其中即说明本地缓存已被服务识别。如果希望在发送转写请求前先预热模型可以调用/load_model它通过 Server-Sent EventsSSE流式输出加载进度curl -N -X POST http://localhost:8000/load_model \ -H Content-Type: application/json \ -d {model: openai/whisper-large-v3}响应是Content-Type: text/event-stream的 SSE 流每行data:后是一个 JSON 对象。事件字段中status取值loading、ready或errorloading状态会带stage字段按processor、config、download、weights顺序推进本地已缓存文件时会跳过download。整个流以唯一一个终止事件结束ready表示成功error表示失败会带message错误描述。下面的帧是文档示例data: {status: loading, model: org/modelmain, stage: weights} data: {status: ready, model: org/modelmain, cached: false}发送转写请求并验证结果/v1/audio/transcriptions遵循 OpenAI 的 Audio transcription API 格式请求体是multipart/form-datafile字段传音频文件model字段传模型 ID。文档给出的示例命令如下其中/path/to/audio.wav需要替换为你机器上的真实音频文件路径curl -X POST http://localhost:8000/v1/audio/transcriptions \ -H Content-Type: multipart/form-data \ -F file/path/to/audio.wav \ -F modelopenai/whisper-large-v3命令返回 JSONtext字段即转写结果。下面是文档示例响应实际内容取决于你的音频{ text: Transcribed text from the audio file, }验证要点请求返回 200 且 JSON 中存在text字段且内容与音频实际语音相符即说明转写服务已跑通。可选分支通过 /v1/chat/completions 传入音频除专用转写端点外多模态模型文档示例为 Gemma 4 和 Qwen2.5-Omni也接受音频输入把音频 base64 编码后放进 OpenAIinput_audio内容类型并指定格式mp3或wav。用 Python 调用示例import base64 import httpx from huggingface_hub import InferenceClient audio_url https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3 audio_b64 base64.b64encode(httpx.get(audio_url, follow_redirectsTrue).content).decode() messages [ { role: user, content: [ {type: text, text: Transcribe this audio.}, {type: input_audio, input_audio: {data: audio_b64, format: mp3}}, ], } ] client InferenceClient(http://localhost:8000) result client.chat_completion(messages, modelgoogle/gemma-4-E2B-it, max_tokens256) print(result.choices[0].message.content)文档同时提供audio_url内容类型可以直接传音频 URL 而跳过 base64 编码。注意文档中的 WARNINGaudio_url不是 OpenAI 标准的一部分属于扩展能力未来版本可能变化。如果你的目标是稳定的转写服务优先使用/v1/audio/transcriptions这条 chat 路径适合复用同一个多模态服务时顺带做转写。模型驻留时间model-timeout 行为transformers serve按请求加载任意模型模型加载后驻留在 GPU 内存中闲置 300 秒后自动卸载以释放显存。如果转写服务预期请求间隔较长可以在启动时调整这个值单位秒或传-1关闭自动卸载transformers serve --model-timeout 400这样每次请求到来时不必重新加载权重避免首条转写请求承担完整的下载/加载耗时。限制与排查定位边界文档明确transformers serve是轻量级本地/自托管选项用于评估、实验和中等负载大规模生产部署应改用 vLLM 或 SGLang 并以 Transformer 模型作为后端。文件上传依赖从服务端实现transcription.py可见处理上传文件依赖python-multipart缺失时会报Missing python-multipart dependency for file uploads. Install with pip install python-multipart音频解码依赖librosa。若上传请求报相应错误按提示安装缺失包后重启服务。audio_url内容类型如前所述非 OpenAI 标准的扩展可能在未来版本改变生产集成建议以 base64 的input_audio或专用/v1/audio/transcriptions为准。验证顺序先用curl http://localhost:8000/v1/models确认模型在本地缓存中再用/load_model观察终止事件是否为ready出现error事件时读取其message字段定位原因最后发送转写请求确认text字段。完成以上步骤后你的本地服务就具备了与 OpenAI 客户端兼容的语音转写能力任何支持 OpenAI 格式的第三方工具都可以指向http://localhost:8000/v1发起转写。更多端点行为响应式 API、工具调用、推理模型支持等可继续在 serve-cli 文档 中查阅。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考