语音转文本（转录/翻译）支持¶
本文档将引导您完成为 vLLM 的转录和翻译 API 添加语音转文本（ASR）模型支持的步骤，方法是实现 SupportsTranscription。有关更多指导，请参阅 支持的模型。
更新基础 vLLM 模型¶
假设您已按照基本模型指南在 vLLM 中实现了模型。通过 SupportsTranscription 接口扩展您的模型，并实现以下类属性和方法。
supported_languages 和 supports_transcription_only¶
声明支持的语言和功能
supported_languages映射在初始化时进行验证。- 如果模型不应提供文本生成（例如 Whisper），请将
supports_transcription_only设置为True。
supported_languages 和 supports_transcription_only
from typing import ClassVar, Mapping, Literal
import numpy as np
import torch
from torch import nn
from vllm.config import ModelConfig, SpeechToTextConfig
from vllm.inputs.data import PromptType
from vllm.model_executor.models.interfaces import SupportsTranscription
class YourASRModel(nn.Module, SupportsTranscription):
# Map of ISO 639-1 language codes to language names
supported_languages: ClassVar[Mapping[str, str]] = {
"en": "English",
"it": "Italian",
# ... add more as needed
}
# If your model only supports audio-conditioned generation
# (no text-only generation), enable this flag.
supports_transcription_only: ClassVar[bool] = True
通过 get_speech_to_text_config 提供 ASR 配置。
这用于控制提供模型时的 API 的一般行为
get_speech_to_text_config()
class YourASRModel(nn.Module, SupportsTranscription):
...
@classmethod
def get_speech_to_text_config(
cls,
model_config: ModelConfig,
task_type: Literal["transcribe", "translate"],
) -> SpeechToTextConfig:
return SpeechToTextConfig(
sample_rate=16_000,
max_audio_clip_s=30,
# Set to None to disable server-side chunking if your
# model/processor handles it already
min_energy_split_window_size=None,
)
有关每个字段的控制内容，请参阅 音频预处理和分块。
通过 get_generation_prompt 实现提示构建。服务器会向您传递重采样后的波形和任务参数；您需要返回一个有效的 PromptType。有两种常见模式：
带音频嵌入的多模态 LLM（例如，Voxtral、Gemma3n）¶
返回一个包含 multi_modal_data（带音频）以及 prompt 字符串或 prompt_token_ids 的字典。
get_generation_prompt()
class YourASRModel(nn.Module, SupportsTranscription):
...
@classmethod
def get_generation_prompt(
cls,
audio: np.ndarray,
stt_config: SpeechToTextConfig,
model_config: ModelConfig,
language: str | None,
task_type: Literal["transcribe", "translate"],
request_prompt: str,
to_language: str | None,
) -> PromptType:
# Example with a free-form instruction prompt
task_word = "Transcribe" if task_type == "transcribe" else "Translate"
prompt = (
"<start_of_turn>user\n"
f"{task_word} this audio: <audio_soft_token>"
"<end_of_turn>\n<start_of_turn>model\n"
)
return {
"multi_modal_data": {"audio": (audio, stt_config.sample_rate)},
"prompt": prompt,
}
有关多模态输入的进一步说明，请参阅 多模态输入。
仅音频的编码器-解码器（例如，Whisper）¶
返回一个包含单独的 encoder_prompt 和 decoder_prompt 条目的字典。
get_generation_prompt()
class YourASRModel(nn.Module, SupportsTranscription):
...
@classmethod
def get_generation_prompt(
cls,
audio: np.ndarray,
stt_config: SpeechToTextConfig,
model_config: ModelConfig,
language: str | None,
task_type: Literal["transcribe", "translate"],
request_prompt: str,
to_language: str | None,
) -> PromptType:
if language is None:
raise ValueError("Language must be specified")
prompt = {
"encoder_prompt": {
"prompt": "",
"multi_modal_data": {
"audio": (audio, stt_config.sample_rate),
},
},
"decoder_prompt": (
(f"<|prev|>{request_prompt}" if request_prompt else "")
+ f"<|startoftranscript|><|{language}|>"
+ f"<|{task_type}|><|notimestamps|>"
),
}
return cast(PromptType, prompt)
validate_language（可选）¶
通过 validate_language 进行语言验证。
如果您的模型需要语言并且您想要一个默认值，请重写此方法（参见 Whisper）。
validate_language()
@classmethod
def validate_language(cls, language: str | None) -> str | None:
if language is None:
logger.warning(
"Defaulting to language='en'. If you wish to transcribe "
"audio in a different language, pass the `language` field "
"in the TranscriptionRequest."
)
language = "en"
return super().validate_language(language)
get_num_audio_tokens（可选）¶
通过 get_num_audio_tokens 进行流式传输的令牌计数。
提供快速的持续时间到令牌的估计，以改进流式传输使用统计信息。
get_num_audio_tokens()
class YourASRModel(nn.Module, SupportsTranscription):
...
@classmethod
def get_num_audio_tokens(
cls,
audio_duration_s: float,
stt_config: SpeechToTextConfig,
model_config: ModelConfig,
) -> int | None:
# Return None if unknown; otherwise return an estimate.
return int(audio_duration_s * stt_config.sample_rate // 320) # example
音频预处理和分块¶
API 服务器负责基本的音频 I/O 和可选的分块，然后再构建提示。
- 重采样：使用
librosa将输入音频重采样到SpeechToTextConfig.sample_rate。 - 分块：如果
SpeechToTextConfig.allow_audio_chunking为 True 且持续时间超过max_audio_clip_s，服务器会将音频分割成重叠的块，并为每个块生成一个提示。重叠由overlap_chunk_second控制。 - 能量感知分割：当设置
min_energy_split_window_size时，服务器会寻找低能量区域，以尽量减少在单词内部切割。
相关的服务器逻辑
_preprocess_speech_to_text()
# vllm/entrypoints/openai/speech_to_text.py
async def _preprocess_speech_to_text(...):
language = self.model_cls.validate_language(request.language)
...
y, sr = librosa.load(bytes_, sr=self.asr_config.sample_rate)
duration = librosa.get_duration(y=y, sr=sr)
do_split_audio = (self.asr_config.allow_audio_chunking
and duration > self.asr_config.max_audio_clip_s)
chunks = [y] if not do_split_audio else self._split_audio(y, int(sr))
prompts = []
for chunk in chunks:
prompt = self.model_cls.get_generation_prompt(
audio=chunk,
stt_config=self.asr_config,
model_config=self.model_config,
language=language,
task_type=self.task_type,
request_prompt=request.prompt,
to_language=to_language,
)
prompts.append(prompt)
return prompts, duration
自动暴露任务¶
如果您的模型实现了该接口，vLLM 将自动声明转录支持。
if supports_transcription(model):
if model.supports_transcription_only:
return ["transcription"]
supported_tasks.append("transcription")
启用后，服务器将初始化转录和翻译处理程序。
state.openai_serving_transcription = OpenAIServingTranscription(...) if "transcription" in supported_tasks else None
state.openai_serving_translation = OpenAIServingTranslation(...) if "transcription" in supported_tasks else None
除了通过模型注册表提供您的模型类并实现 SupportsTranscription 之外，无需额外的注册。
内置示例¶
- Whisper 编码器-解码器（仅音频）： vllm/model_executor/models/whisper.py
- Voxtral 仅解码器（音频嵌入 + LLM）： vllm/model_executor/models/voxtral.py。请确保已安装
mistral-common[audio]。 - Gemma3n 仅解码器，带有固定指令提示： vllm/model_executor/models/gemma3n_mm.py
通过 API 进行测试¶
一旦您的模型实现了 SupportsTranscription，您就可以测试端点（API 模拟 OpenAI）。
-
转录（ASR）
-
翻译（源 → 英语，除非另有支持）
或者查看 更多示例中的 online_serving。
注意
- 如果您的模型内部处理分块（例如，通过其处理器或编码器），请在返回的
SpeechToTextConfig中将min_energy_split_window_size设置为None以禁用服务器端分块。 - 实现
get_num_audio_tokens可以提高流式传输使用情况指标（prompt_tokens）的准确性，而无需额外的正向传递。 - 对于多语言行为，请使
supported_languages与实际模型功能保持一致。