API 参考

相关源文件

• whisper/__init__.py
• whisper/decoding.py
• whisper/transcribe.py

本文档为 Whisper 自动语音识别 (ASR) 系统的主要编程接口提供了全面的参考。它涵盖了用于模型加载、音频转录和自定义解码过程的核心函数和类。有关基本用法示例，请参阅基本用法；有关实现细节，请参阅转录流程。

核心功能

Whisper API 提供了几个高级函数，构成了用户的主要接口。

来源: whisper/__init__.py103-160 whisper/transcribe.py38-514 whisper/decoding.py793-826 whisper/decoding.py19-77

load_model()

加载 Whisper ASR 模型进行推理。

参数

• name: 模型名称或模型检查点路径。可用模型名称包括：
  • 小型模型: "tiny", "tiny.en", "base", "base.en", "small", "small.en"
  • 大型模型: "medium", "medium.en", "large", "large-v1", "large-v2", "large-v3", "turbo" (别名 "large-v3-turbo")
• device: PyTorch 设备 ("cuda", "cpu", 等)。如果 CUDA 可用，则默认为 CUDA，否则为 CPU。
• download_root: 下载模型的存储目录。默认为 ~/.cache/whisper。
• in_memory: 是否将模型权重预加载到内存中，而不是按需加载。

返回值

• 一个可用于推理的 Whisper 模型实例。

示例

来源: whisper/__init__.py103-160

transcribe()

使用 Whisper 模型转录音频，处理音频预处理、语言检测和带错误恢复的解码。

参数

• model: Whisper 模型实例。
• audio: 音频文件路径、包含音频波形的 NumPy 数组或 PyTorch 张量。
• verbose: 控制输出详细程度（True 为详细，False 为最小，None 为静默）。
• temperature: 采样温度。可以是浮点数或浮点数元组，用于回退。
• compression_ratio_threshold: 如果压缩率超过此值，则认为解码失败。
• logprob_threshold: 如果平均对数概率低于此值，则认为解码失败。
• no_speech_threshold: 将音频分类为静音的阈值。
• condition_on_previous_text: 是否根据先前的输出对每个窗口进行条件化。
• initial_prompt: 可选文本，用于为转录提供上下文。
• word_timestamps: 是否提取词级别的时间戳。
• clip_timestamps: 逗号分隔的开始、结束、开始、结束时间戳列表，用于处理。
• Additional parameters: 传递给 DecodingOptions。

返回值

• 包含以下内容的字典：
  • text: 转录文本。
  • segments: 包含时间戳及其他元数据的片段字典列表。
  • language: 检测到或指定的语言。

来源: whisper/transcribe.py38-514

decode()

执行梅尔频谱图到文本的低级解码。

参数

• model: Whisper 模型实例。
• mel: 梅尔频谱图，形状为 (80, 3000) 或批处理。
• options: DecodingOptions 实例。
• kwargs: 用于覆盖选项的附加关键字参数。

返回值

• DecodingResult 或包含转录文本及元数据的结果列表。

来源: whisper/decoding.py793-826

detect_language()

检测音频中所说的语言。

参数

• model: Whisper 模型实例。
• mel: 梅尔频谱图。
• tokenizer: 可选的 tokenizer 实例。

返回值

• 语言token和语言概率分布的元组。

来源: whisper/decoding.py19-77

关键类

来源: whisper/decoding.py80-128 whisper/decoding.py508-789

DecodingOptions

用于控制解码过程的配置类。

关键参数

• task: 用于 X→X 转录的 "transcribe" 或用于 X→英语翻译的 "translate"。
• language: 音频语言（如果为 None 则自动检测）。
• temperature: 控制采样的随机性（0 = 贪婪，值越高随机性越大）。
• beam_size: 束搜索的束大小（当 temperature = 0 时）。
• best_of: 当 temperature > 0 时独立样本的数量。
• prompt: 用于条件化的先前上下文。
• prefix: 用于为当前上下文添加前缀的文本。
• suppress_tokens: 生成过程中要抑制的token。
• without_timestamps: 使用 <|notimestamps|> 生成不带时间戳的文本。

来源: whisper/decoding.py80-115

DecodingResult

解码结果的容器。

关键属性

• audio_features: 编码器输出特征。
• language: 检测到或指定的语言。
• tokens: 来自解码器的token ID列表。
• text: 解码文本。
• avg_logprob: 平均对数概率（置信度度量）。
• no_speech_prob: 该片段不包含语音的概率。
• compression_ratio: 文本压缩率（用于检测重复）。

来源: whisper/decoding.py117-128

解码系统

解码系统通过各种策略将模型输出转换为文本。

来源: whisper/decoding.py130-506

DecodingTask

解码过程的中心协调器。

DecodingTask 类负责协调：

• 使用 PyTorchInference 进行模型推理
• 使用 GreedyDecoder 或 BeamSearchDecoder 生成token
• 通过 MaximumLikelihoodRanker 进行序列排序
• 通过各种 LogitFilter 实现进行 Logit 过滤

来源: whisper/decoding.py508-789

推理和token解码器

推理处理模型的正向传递，而token解码器实现生成策略。

类	目的
PyTorchInference	通过 KV 缓存对模型进行正向传递
GreedyDecoder	在每一步选择概率最高的token（当 temperature=0 时）
BeamSearchDecoder	维护多个候选序列，选择最佳整体路径

来源: whisper/decoding.py130-404

音频处理

该 API 包含将音频文件处理为模型输入的函数。

关键音频常量

• SAMPLE_RATE: 16000 赫兹
• N_FFT: 400
• HOP_LENGTH: 160
• CHUNK_LENGTH: 30 秒
• N_FRAMES: 每块 3000 帧

来源: whisper/__init__.py11 whisper/transcribe.py11-19

命令行界面

该库提供了一个用于转录的命令行界面。

whisper audio.mp3 --model base --language en

常用 CLI 参数

参数	描述
--model	模型名称（"tiny", "base", "small", "medium", "large", "turbo"）
--language	语言代码或“auto”用于自动检测
--task	“transcribe”或“translate”
--output_dir	输出保存目录
--output_format	保存格式（txt, vtt, srt, tsv, json）
--verbose	显示进度和中间结果
--word_timestamps	生成词级别时间戳

来源: whisper/transcribe.py517-623

数据流示例

来源: whisper/transcribe.py38-514 whisper/decoding.py793-826

使用示例

基本转录

自定义解码选项

语言检测

来源: whisper/__init__.py103-160 whisper/transcribe.py38-514 whisper/decoding.py19-77