Parakeet MLX

基于 MLX 的 Parakeet 模型实现——NVIDIA 的自动语音识别（ASR）模型，专为 Apple Silicon 设计。

安装

[!NOTE]
请确保您的系统已安装 ffmpeg，否则 CLI 将无法正常工作。

使用 uv（推荐方式）：

uv add parakeet-mlx -U

或者，对于 CLI：

uv tool install parakeet-mlx -U

使用 pip：

pip install parakeet-mlx -U

CLI 快速入门

parakeet-mlx <audio_files> [OPTIONS]

参数

• audio_files: 要转录的一个或多个音频文件（WAV、MP3 等）

选项

• --model（默认值：mlx-community/parakeet-tdt-0.6b-v3，环境变量：PARAKEET_MODEL）
  使用的模型的 Hugging Face 仓库
  https://huggingface.co/collections/mlx-community/parakeet

• --output-dir（默认值：当前目录）
  保存转录结果的目录

• --output-format（默认值：srt，环境变量：PARAKEET_OUTPUT_FORMAT）
  输出格式（txt/srt/vtt/json/all）

• --output-template（默认值：{filename}，环境变量：PARAKEET_OUTPUT_TEMPLATE）
  输出文件名模板，支持 {parent}、{filename}、{index}、{date}。

• --highlight-words（默认值：False）
  在 SRT/VTT 输出中启用词级时间戳

• --verbose / -v（默认值：False）
  打印详细的进度信息

• --decoding（默认值：greedy，环境变量：PARAKEET_DECODING）
  解码方法（greedy 或 beam）
  目前仅 TDT 模型支持 beam 解码

• --chunk-duration（默认值：120 秒，环境变量：PARAKEET_CHUNK_DURATION）
  长音频分块处理时的每块时长，设置为 0 可禁用分块

• --overlap-duration（默认值：15 秒，环境变量：PARAKEET_OVERLAP_DURATION）
  使用分块时的重叠时长

• --beam-size（默认值：5，环境变量：PARAKEET_BEAM_SIZE）
  束搜索的宽度（仅在束搜索解码时使用）

• --length-penalty（默认值：0.013，环境变量：PARAKEET_LENGTH_PENALTY）
  束搜索中的长度惩罚。设置为 0.0 可禁用（仅在束搜索解码时使用）

• --patience（默认值：3.5，环境变量：PARAKEET_PATIENCE）
  束搜索中的耐心参数。设置为 1.0 可禁用（仅在束搜索解码时使用）

• --duration-reward（默认值：0.67，环境变量：PARAKEET_DURATION_REWARD）
  值范围为 0.0 到 1.0，小于 0.5 时更倾向于 token 对数似然，大于 0.5 时更倾向于持续时间对数似然。（仅在 TDT 的束搜索解码时使用）

• --max-words（默认值：无，环境变量：PARAKEET_MAX_WORDS）
  每个句子的最大词数

• --silence-gap（默认值：无，环境变量：PARAKEET_SILENCE_GAP）
  如果句子超过指定的静音间隔（秒），则将其拆分

• --max-duration（默认值：无，环境变量：PARAKEET_MAX_DURATION）
  每个句子的最大时长（秒）

• --fp32 / --bf16（默认值：bf16，环境变量：PARAKEET_FP32 - 布尔值）
  决定使用的精度

• --full-attention / --local-attention（默认值：full-attention，环境变量：PARAKEET_LOCAL_ATTENTION - 布尔值）
  使用全局注意力还是局部注意力（局部注意力可减少中间内存占用）
  适用于不进行分块的长音频转录场景

• --local-attention-context-size（默认值：256，环境变量：PARAKEET_LOCAL_ATTENTION_CTX）
  Parakeet 模型中局部注意力的上下文窗口大小（以帧为单位）

• --cache-dir（默认值：无，环境变量：PARAKEET_CACHE_DIR）
  Hugging Face 模型缓存目录。若未指定，则使用 HF 的默认缓存位置 (~/.cache/huggingface 或您在 HF_HOME 或 HF_HUB_CACHE 中设置的路径，即 $HF_HOME/hub)

示例

# 基本转录
parakeet-mlx audio.mp3

# 多个文件，并生成带有词级时间戳的 VTT 字幕
parakeet-mlx *.mp3 --output-format vtt --highlight-words

# 生成所有输出格式
parakeet-mlx audio.mp3 --output-format all

Python API 快速入门

转录一个文件：

from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav")

print(result.text)

查看时间戳：

from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav")

print(result.sentences)
# [AlignedSentence(text="Hello World.", start=1.01, end=2.04, duration=1.03, tokens=[...])]

进行分块处理：

from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav", chunk_duration=60 * 2.0, overlap_duration=15.0)

print(result.sentences)

使用束搜索解码：

from parakeet_mlx import from_pretrained, DecodingConfig, Beam

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    decoding = decoding(
        beam_size=5, length_penalty=0.013, patience=3.5, duration_reward=0.67
        # 参考 CLI 选项了解各参数的作用
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)

使用局部注意力：

from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

model.encoder.set_attention_model(
    "rel_pos_local_attn", # 遵循 NeMo 的命名规范
    (256, 256),
)

result = model.transcribe("audio_file.wav")

print(result.sentences)

指定句子拆分选项：

from parakeet_mlx import from_pretrained, DecodingConfig, SentenceConfig

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    sentence = SentenceConfig(
        # 参照 CLI 选项了解各项参数的作用
        max_words=30, silence_gap=5.0, max_duration=40.0
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)

from_pretrained

使用 from_pretrained 会从 Hugging Face 下载模型，并将下载的模型存储在 HF 的 缓存文件夹 中。您可以通过传递 cache_dir 参数来指定缓存目录。它会返回 Parakeet 的不同变体，例如：ParakeetTDT、ParakeetRNNT、ParakeetCTC 或 ParakeetTDTCTC。对于一般用途，通常使用 BaseParakeet 抽象即可。然而，如果您需要调用特定变体的方法（如 .decode()），并希望避免 linter 报错，可以使用 typing.cast。

时间戳结果

• AlignedResult: 顶级结果，包含完整文本和句子
  • text: 完整转录文本
  • sentences: AlignedSentence 列表
• AlignedSentence: 句子级别的对齐信息，包含开始和结束时间
  • text: 句子文本
  • start: 开始时间（秒）
  • end: 结束时间（秒）
  • duration: 从 start 到 end 的持续时间。
  • tokens: AlignedToken 列表
• AlignedToken: 词/标记级别的对齐信息，包含精确的时间戳
  • text: 标记文本
  • start: 开始时间（秒）
  • end: 结束时间（秒）
  • duration: 从 start 到 end 的持续时间。

流式转录

对于实时转录，可以使用 transcribe_stream 方法创建流式上下文：

from parakeet_mlx import from_pretrained
from parakeet_mlx.audio import load_audio
import numpy as np

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# 创建流式上下文
with model.transcribe_stream(
    context_size=(256, 256),  # (左文上下文, 右文上下文) 帧数
) as transcriber:
    # 模拟实时音频片段
    audio_data = load_audio("audio_file.wav", model.preprocessor_config.sample_rate)
    chunk_size = model.preprocessor_config.sample_rate  # 每1秒一个片段

    for i in range(0, len(audio_data), chunk_size):
        chunk = audio_data[i:i+chunk_size]
        transcriber.add_audio(chunk)

        # 获取当前转录结果
        result = transcriber.result
        print(f"当前文本: {result.text}")

        # 访问已完成和草稿标记
        # transcriber.finalized_tokens
        # transcriber.draft_tokens

流式参数

• context_size: 元组形式的 (左文上下文, 右文上下文)，用于注意力窗口

  • 控制模型在当前位置前后查看多少帧
  • 默认值：(256, 256)

• depth: 在分块之间保持精确计算的编码器层数

  • 控制有多少层能够与非流式前向传播保持完全等价
  • depth=1: 只有第一层编码器与非流式计算完全一致
  • depth=2: 前两层完全一致，依此类推
  • depth=N (总层数): 与非流式前向传播完全等价
  • 层次越高，与非流式模式的计算一致性越强
  • 默认值：1

• keep_original_attention: 是否保留原始注意力机制

  • False: 转为局部注意力以适应流式处理（推荐）
  • True: 保留原始注意力（不太适合流式处理）
  • 默认值：False

低级 API

若要直接转录音频的对数梅尔谱，可以按以下步骤操作：

import mlx.core as mx
from parakeet_mlx.audio import get_logmel, load_audio
from parakeet_mlx import DecodingConfig

# 手动加载并预处理音频
audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
mel = get_logmel(audio, model.preprocessor_config)

# 生成带对齐信息的转录
# 接受 [batch, sequence, feat] 和 [sequence, feat] 形式的输入
# `alignments` 是 AlignedResult 列表。（无论是否输入批次维度都适用！）
alignments = model.generate(mel, decoding_config=DecodingConfig())

待办事项

• 添加 CLI 以提高易用性
• 增加对其他 Parakeet 变体的支持
• 实现流式输入（通过 transcribe_stream 进行实时转录）
• 提供增强选定词语准确性的选项
• 支持带有连续上下文的分块处理（部分已通过流式处理实现）

致谢

• 感谢 Nvidia 训练这些优秀的模型、撰写精彩的论文，并提供了出色的实现。
• 感谢 MLX 项目，正是它提供的框架使得本次实现成为可能。
• 感谢 audiofile 和 audresample、numpy、librosa 等在音频处理方面的贡献。
• 感谢 dacite 在配置管理方面的支持。

许可证

Apache 2.0

Parakeet MLX 快速上手指南

Parakeet MLX 是 NVIDIA Parakeet 自动语音识别（ASR）模型在 Apple Silicon 芯片上的 MLX 实现，专为 macOS 用户打造高效的本地语音转文字体验。

环境准备

• 操作系统：macOS (需配备 Apple Silicon 芯片，如 M1/M2/M3 系列)
• 前置依赖：
  • 必须安装 ffmpeg，否则命令行工具无法正常工作。
  • 推荐使用 uv 进行包管理（也可使用 pip）。

安装 ffmpeg (使用 Homebrew):

brew install ffmpeg

安装步骤

方式一：使用 uv（推荐）

安装库：

uv add parakeet-mlx -U

安装命令行工具：

uv tool install parakeet-mlx -U

方式二：使用 pip

pip install parakeet-mlx -U

提示：国内开发者若遇到下载慢的问题，可配置 pip/uv 使用国内镜像源（如清华源、阿里源）。

基本使用

1. 命令行 (CLI) 快速转录

最简单的用法是直接传入音频文件（支持 WAV, MP3 等格式）：

parakeet-mlx audio.mp3

常用示例：

• 转录多个文件并生成带时间戳的 VTT 字幕：

  parakeet-mlx *.mp3 --output-format vtt --highlight-words
  

• 生成所有可用格式的输出：

  parakeet-mlx audio.mp3 --output-format all
  

2. Python API 快速调用

在 Python 脚本中加载模型并转录文件：

from parakeet_mlx import from_pretrained

# 加载模型
model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# 执行转录
result = model.transcribe("audio_file.wav")

# 输出文本
print(result.text)

获取带时间戳的句子信息：

print(result.sentences)
# 输出示例：[AlignedSentence(text="Hello World.", start=1.01, end=2.04, ...)]