参考

1. 安装XCODE

macos自带的Command Line Tools没有coremlc库，需要安装完整的xcode，去App Store下载安装，然后执行以下命令。

# change xcode tool path
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
# agree xcode license
sudo xcodebuild -license

按回车查看协议所有内容，最后输入agree确认同意。

2. 编译whisper.cpp

避免污染电脑的运行环境，使用uv进行python版本和包管理。依次安装依赖库、拉取whisper.cpp代码、下载模型（这里我下载的是large-v2，可以查看所有模型，下载自己需要的）、模型转换（为了利用Apple M芯片的加速器）以及编译链接。

# install uv
brew install uv

# start project
uv init my_whisper_cpp
cd my_whisper_cpp

# install dependent libraries for core-ml
uv venv --python 3.11
uv add ane_transformers openai-whisper coremltools
xcode-select --install

# pull whisper.cpp as open-source submodule
git submodule add https://github.com/ggml-org/whisper.cpp.git whisper_cpp

# download models
sh ./whisper_cpp/models/download-ggml-model.sh large-v2
sh ./whisper_cpp/models/download-ggml-model.sh large-v3
sh ./whisper_cpp/models/download-ggml-model.sh large-v3-turbo
# transform coreml model
uv run ./whisper_cpp/models/generate-coreml-model.sh large-v2
uv run ./whisper_cpp/models/generate-coreml-model.sh large-v3
uv run ./whisper_cpp/models/generate-coreml-model.sh large-v3-turbo

# build whisper
brew install cmake
cmake -B build -DWHISPER_COREML=1
cmake --build build -j --config Release

3. 转录

编译完成后，生成可执行文件，我们就可以使用它进行转录了。

假设待转录的文件为./input/my_file.mp3
为了使转录字体为简体中文，并且带有标点符号，启动时增加prompt选项，使用带标点符号的简体中文句子作为prompt。（重要的是prompt的格式，而不是内容）

# see help
./whisper_cpp/build/bin/whisper-cli help

# transcribe
./whisper_cpp/build/bin/whisper-cli \
    --model ./whisper_cpp/models/ggml-large-v2.bin \
    --language zh \
    --prompt "- 你可以帮我吗？谢谢你的帮忙！议地点在哪里？我昨天看了一部电影。" \
    --file ./input/my_file.mp3 \
    --output-txt \
    -pc \
    -pp

4. （可选）使用VAD

VAD（Voice Activity Detection）可以探测有效语音数据，将语音分割为几段，加速转录，更重要的是可以避免因为无效声音或大段空白造成的幻觉。

# see all available VAD models
./whisper_cpp/models/download-vad-model.sh

# download VAD model
./whisper_cpp/models/download-vad-model.sh silero-v5.1.2

在转录时增加选项--vad和--vad-model ./whisper_cpp/models/ggml-silero-v5.1.2.bin，就可以额外使用VAD模型了。例如

./whisper_cpp/build/bin/whisper-cli \
    ... \
    --vad \
    --vad-model ./whisper_cpp/models/ggml-silero-v5.1.2.bin

使用VAD之后，音频中的空白时间可能会被丢弃（用户可调参），会使原本大段的文字将会被分割为一行行的句子。

5. （可选）使用hugging face的模型（TODO）

如果想要使用非whisper.cpp官方提供的模型，需要进行转换。这里我以BELLE-2/Belle-whisper-large-v3-zh-punct为例子。

到你的项目的根目录，拉取whisper仓库作为submodule，转换需要使用其中的python脚本。
调用脚本将hugging face等平台下载的pytorch模型转换为ggml格式。
- 假设待转换的pytorch模型所在目录为./models_to_convert
- 假设存放转换后模型的目录为./models_converted
- 假设本地的whisper仓库目录为./whisper
将转换后的模型移动到whisper.cpp仓库的models目录（./whisper_cpp/models），并改名。
- 我使用的这个模型是基于large-v3微调训练出来的，所以改名为ggml-large-v3.bin。（注意，这里使用的名称与whisper官方的large-v3模型相同，如果你下载了官方的这个模型，最好先删掉）
- 如果不改名，无法被后续coreml的转换脚本识别。（当然你也可以选择去修改脚本，我是为了避免修改开源代码而选择了改文件名）
继续转换为coreml模型（为Apple设备优化）。

# pull source code of whisper
git submodule add https://github.com/openai/whisper whisper

# convert to ggml
uv run whisper_cpp/models/convert-h5-to-ggml.py ./models_to_convert ./whisper ./models_converted
# rename and move to model directory of whisper_cpp
mv ./models_converted/ggml-model.bin whisper_cpp/models/ggml-large-v3.bin

# convert to coreml
uv run ./whisper_cpp/models/generate-coreml-model.sh -h5 large-v3 ./whisper_cpp/models

TODO：

BELLE-2/Belle-whisper-large-v3-zh-punct这个模型文件的大小是官方large-v3模型的两倍多，但是加载到内存（显存）后占用的空间却一样，我不太理解这个现象。两个模型的运行结果确实有较大区别，BELLE模型对中文音频的转录效果更好，但是耗时变得很长。
或许是我转换模型时使用了“偷梁换柱”的操作，whisper.cpp提供的转换脚本只考虑了官方模型，我未仔细看脚本代码，可能需要做一些适配，按理说模型文件变大之后，占用的内存（显存）应该也会显著变大。
将ggml模型转换为coreml模型的过程，或许可以使用Apple官方或其他开源的工具，whisper.cpp提供的脚本大概率有局限性。

macOS使用Whisper.cpp进行音频转文字

参考

1. 安装XCODE

2. 编译whisper.cpp

3. 转录

4. （可选）使用VAD

5. （可选）使用hugging face的模型（TODO）

Comments