如何使用 whisper.cpp：2026 完整指南

## 如何使用 whisper.cpp whisper.cpp 是 OpenAI Whisper 语音识别模型的 C/C++ 实现。它让你可以通过命令行转录音频，也可以将转录能力集成到应用程序中；完成安装后，通常无需将音频发送给托管式转录服务。本指南介绍如何构建程序、获取模型、转录文件、生成字幕、调整准确度与速度，以及排查常见问题。 这个项目是运行时与实现，并非一键式转录网站。你需要兼容的模型文件、受支持的构建环境，以及程序可读取的音频。不同版本中的命令和选项可能变化，因此应以已安装版本运行 `whisper-cli --help` 所显示的内容为准。 ## whisper.cpp 的功能 Whisper 是一个多语言语音识别模型系列。whisper.cpp 提供原生实现，旨在适配多种硬件，包括普通 CPU，以及在支持并正确启用时使用的加速后端。它可以转录音频、将语音翻译成英语、识别时间戳，并生成适用于字幕流程的输出格式。某些构建还会提供语音活动检测、服务端或流式处理示例等其他模式；具体功能取决于当前版本和构建配置。 典型工作流程分为四个部分： 1. 针对操作系统和硬件构建或安装 whisper.cpp。 2. 下载项目所需格式的兼容 Whisper 模型。 3. 提供音频文件并选择合适的转录选项。 4. 检查并导出结果，按需校正姓名、标点和专业术语。 该工具不保证生成完全正确的转录。识别质量取决于模型、语言、麦克风、录音环境、口音、多人重叠说话以及词汇内容。本地处理有助于让音频留在设备上，但隐私也取决于模型下载来源、应用程序如何处理文件，以及是否使用了联网服务或封装程序。 ### whisper.cpp 与托管式转录服务对比 | 考量因素 | 在本机运行 whisper.cpp | 托管式转录服务 | |---|---|---| | 音频处理 | 完成设置后可在本地处理文件 | 通常会将音频上传给服务提供方 | | 设置 | 需要模型和兼容的构建环境 | 通常可以从浏览器或 API 客户端开始 | | 控制能力 | 可使用命令行选项并集成到应用 | 取决于服务的界面与 API | | 成本模式 | 本地运行时没有按分钟收取的服务费，但硬件和设置仍有成本 | 可能提供免费、按用量或订阅套餐；当前条款请查看服务商官网 | | 维护 | 需要自行管理版本、模型、存储和更新 | 服务商负责大部分基础设施 | | 适用场景 | 离线工作、本地实验和定制应用 | 快速上手、托管工作流程或不想运维本地软件的团队 | 以上是总体差异，并不意味着某种方式始终更好。需要精致协作式编辑器的用户可能不适合命令行工具；而音频必须留在受控设备上的场景，也可能不适合托管服务。 ## 开始之前 ### 检查操作系统与硬件 whisper.cpp 面向常见桌面操作系统构建，但具体步骤有所不同。Linux 和 macOS 通常需要 C/C++ 编译器与 CMake。Windows 用户应使用受支持的编译器环境，并遵循项目当前的 Windows 指南。Git 便于获取源代码。某些加速路径还需要额外系统库、SDK 或兼容硬件。 从 CPU 构建开始通常比较合适。它比专用加速器构建更容易验证，也有助于确认模型和输入文件可以正常工作。较长录音可能会受益于性能合适的 GPU 或平台专用加速后端，但实际效果取决于硬件、构建选项、模型大小和音频内容。不要因为电脑装有 GPU 就假设程序正在使用它；请检查构建配置和运行日志。 ### 选择合适的模型 为 whisper.cpp 分发的模型文件使用项目要求的格式，项目文档通常将其称为 GGML 格式。仓库提供获取或转换模型的脚本和说明。请使用这些文档所列的来源与流程，不要只是把不相关的模型文件改名。 常见模型系列在体积、速度和识别能力之间有所取舍。较小模型通常占用较少内存、运行较快；较大模型在困难音频上可能更有能力，但需要更多资源。这是实用上的趋势，并不能保证适用于所有语言或录音。量化版本可以减少存储或内存需求，但也可能带来质量取舍。 | 模型选择 | 实用优势 | 取舍 | 适用情况 | |---|---|---|---| | Tiny 或 Base | 轻量；适合验证工作流程，或在资源有限的硬件上处理 | 在困难录音中更容易漏词 | 需要快速初测或资源限制严格时 | | Small | 在许多普通录音中提供折中选择 | 仍可能难以处理噪声、多人重叠和专业术语 | 想比较轻量模型与较大模型时 | | Medium | 比 Small 需要更多资源；可作为偏重质量的选择 | 速度较慢、内存占用较高 | 录音比较重要，值得使用更大模型时 | | Large | 常见尺寸中资源需求最高；可能有助于处理困难材料 | 并非每种语言或嘈杂录音都一定更好；需要更多算力 | 硬件合适并希望评估可用的较大模型时 | | 量化版本 | 相比对应的完整精度版本，存储或内存占用较小 | 识别表现可能不同；应使用自己的音频测试 | 标准模型无法轻松装入内存或运行过慢时 | 不要只看模型名称来选择。选取自己录音中有代表性的一小段，测试候选模型。样本应包含实际工作中会遇到的说话人、背景声音、术语和口音。比较需要改正的错误，而不仅仅是输出读起来是否通顺。 ### 准备音频 优先使用能获取到的最高质量原始录音。清晰语音、稳定音量和较少背景噪声都有帮助。如果文件使用不受支持的容器或编码，可用可信的音频工具转换成 WAV 等常见格式。避免反复进行有损转换：每次转换都可能丢失信息，却不一定改善语音。 检查文件确实含有声音、目标说话人清晰可闻，并确认声道布局合理。如果不同说话人分布在不同声道，立体声可能有用，但立体声并非总是更好。如果录音某个声道很小、发生削波或含有很长静音，应先检查或处理这些情况，再判断模型是否准确。根据构建方式，命令行工具可能接受多种格式；请查阅帮助信息和示例。 ## 安装和构建 whisper.cpp 以下命令展示常见的源代码构建流程。项目说明可能更新，使用前应对照当前仓库 README 核实。若需要 GPU 加速或平台专用后端，构建选项尤其重要。 ### 第 1 步：获取源代码 如果尚未安装 Git，请先安装，然后克隆官方 whisper.cpp 仓库并进入目录。仓库 README 会介绍当前支持的构建流程和平台专用前置条件。如果已经有代码副本，请有计划地更新，并记录正在测试的版本；升级版本可能会改变选项和输出行为。 ### 第 2 步：配置并编译 常见流程使用 CMake： ```sh cmake -B build cmake --build build --config Release ``` 有些系统会把可执行文件放在 build 子目录中，具体路径也可能不同。找到生成的命令行程序后，查看帮助信息： ```sh ./build/bin/whisper-cli --help ``` 可执行文件名称或位置可能随版本和平台变化。如果找不到该命令，请检查构建输出和仓库文档，不要直接认定编译失败。构建成功只说明程序完成编译，并不代表所有可选后端都已启用。 ### 第 3 步：基线运行正常后再添加加速 先用默认构建处理一个短文件。之后再考虑项目为你的平台记录的加速方式。根据版本与硬件，可能涉及 CUDA、Metal、Vulkan 或其他受支持路径。每种路径都有各自的依赖和 CMake 配置。请使用项目当前说明；不要未经核实就照搬旧教程中的参数，确认当前版本仍然识别该选项。 记录构建命令和运行输出。调查速度时，使用相同音频、模型和选项进行对比。对于很小的文件，加速构建可能没有帮助，因为启动开销可能占主导。若依赖或配置缺失，程序也可能没有使用预期的设备。 ## 下载并验证模型 使用项目的模型说明或脚本，获取与你构建版本兼容的模型。将其保存到容易找到的位置，例如 `models` 目录，并保留文件名。以下示例使用 `models/ggml-base.bin` 作为占位路径；请替换为实际下载的模型路径。 初次测试时，选择系统可以轻松加载的模型。如果程序报告无法打开模型，请检查路径、权限、文件是否下载完整，以及模型格式是否符合要求。仅凭扩展名无法确认兼容性。如果仓库提供转换脚本，请按照文档列出的输入和输出使用。 妥善管理模型文件。它们可能占用不少磁盘空间，多个版本很快就会累积。如果可重复性很重要，请记录模型名称、来源、量化方式和用于生成转录的版本。处理敏感工作时，应核实模型来源，并遵循组织针对软件和模型下载的规定。 ## 转录第一份音频 准备好模型和音频文件后，使用明确路径运行 CLI。常见命令如下： ```sh ./build/bin/whisper-cli \ -m models/ggml-base.bin \ -f audio.wav ``` 请用 `--help` 确认当前构建的准确参数。多数命令行示例会分别使用一个选项指定模型，另一个选项指定输入文件，但具体名称和支持情况应在本机确认。程序通常会输出识别文本，也可能显示时间信息或性能数据。 如果第一次运行失败，不要马上同时修改多个设置。先确认程序能启动、模型能加载、音频能打开，以及所选语言正确。然后每次只更改一个变量。这样更容易判断问题来自文件、模型、构建过程还是选项。 ### 选择语言 Whisper 可以识别多种语言。你通常可以让模型自动检测，也可以使用当前构建支持的选项明确指定语言。当录音很短、语音内容很少，或语言线索混杂导致检测不准时，明确指定语言可能有帮助。请使用已安装 CLI 文档中列出的语言代码和语法。 对于多语言录音，自动检测不一定能生成干净的逐说话人语言转录。语码转换、姓名和短语可能会被不一致地处理。请人工检查这些片段，并在大批量处理之前测试有代表性的样本。 ### 保留原语言转录，或翻译成英语 转录的目标是记录所说的语言。翻译模式则会将支持的非英语语音输出为英文文本。具体选项名称取决于版本，请使用 `--help` 核实。翻译不等同于忠实转录：它可能调整语序、省略口头停顿，并选择一种解释，而不是保留原文的每个表达。 如果需要可审计记录，请保留原语言转录，并单独生成译文。清晰标注不同输出，避免读者误以为译文就是英语原话。 ## 生成时间戳和字幕文件 时间戳有助于编辑、审阅和文本与音频的对齐。根据你所用版本的 CLI 选项，whisper.cpp 可以生成适用于字幕工作流程的输出格式。查看帮助信息，确认是否支持 SRT、VTT 或带时间戳的文本等格式。除了模型和输入路径，通常还需要指定输出格式或输出路径。 ```sh ./build/bin/whisper-cli \ -m models/ggml-base.bin \ -f interview.wav \ -osrt ``` 这只是示例，不能视为所有版本都支持的保证：选项名称和格式可能变化。生成后应检查文件，并用项目所用的编辑器或播放器打开。检查字幕时间、换行、标点和说话人变化。遇到停顿、多人重叠、音乐或快速对话时，自动时间戳可能偏移，句子切分也可能不自然。 ### 字幕审阅清单 - 确认第一条和最后一条字幕与可听见的语音对齐。 - 检查长停顿、打断和说话人切换附近的字幕。 - 按自然语义切行，不要在句意中间断开。 - 校正姓名、缩写、数字和专业词汇。 - 确认字幕在播放尺寸下容易阅读，且不会遮挡重要屏幕文字。 - 回放每个校正过的片段；文本即使语法通顺，也可能仍然错误。 ## 提高转录质量 ### 使用更好的源录音 后期处理不能替代良好的麦克风和干净录音。如果能够控制录音过程，应让麦克风靠近说话人，避免操作噪声，并防止削波。后期稍微调整音量或删除长段静音，有助于审阅；但过度降噪可能会扭曲辅音，降低识别效果。 不要把重采样当作提升音质的方法。它可能是满足工具输入要求所必需的，但不能还原录制时从未捕获的细节。遵循构建版本的输入说明，必要时使用标准音频转换工具。 ### 有意识地设置语言和上下文 如果已知录音语言且自动检测不可靠，应明确设置语言。某些版本提供提示词或初始上下文选项，可能有助于处理姓名和专业词汇。这些内容只是提示，并非词典或保证。请在已安装 CLI 中确认准确语法，也不要在提示中塞入冗长且无关的词表；过多或误导性的上下文可能让输出产生偏向。 对技术术语，可在转录后建立校正清单。为产品名称、缩写和人名确定统一拼写。统一应用校正，但应根据音频核对每一次出现，而不是仅凭外观相似就盲目替换。 ### 用可重复测试比较模型 选择一段有代表性的片段，使用相同的语言和解码设置运行两个或更多候选模型。比较实际错误：漏掉的短语、替换词、标点和时间戳。如果有可信参考稿，可用来评估差异，但也要记住参考稿本身可能有错。记录模型和构建设置，以便之后进行可比测试。 ### 了解自动清理的局限 语音识别无法可靠识别每位说话人，也无法总是根据上下文推断正确含义。转录可能漏掉音量很小的说话人、规范口头语、误读专有名词，或在嘈杂间隙生成看似合理的词句。文本流畅并不能证明片段准确。对于法律、医疗、金融、安全或就业决策中的重要引语和转录，应采用适当的人工审核流程。 ## 批量处理与可重复工作流程 处理多个文件时，可以用 shell 循环对每个输入运行相同命令。先在一个文件上测试，给含空格的路径加引号，并为每个结果指定不同输出名称。通用 shell 模式如下： ```sh for file in recordings/*.wav; do ./build/bin/whisper-cli -m models/ggml-base.bin -f "$file" done ``` 此示例会将输出打印到终端，并未定义可靠的转录文件命名方案。请使用当前版本支持的输出选项，或编写一个小型封装来生成安全的输出文件名。在目标系统上测试含空格和非英文字符的文件名。避免覆盖源文件或之前生成的转录。 生产环境的批处理应为失败做好准备，不要假设所有文件都有效。记录输入路径、模型、命令选项、退出状态和输出位置。为每个文件隔离结果，避免一个文件失败后悄悄覆盖另一个结果。并行运行时要考虑文件大小和可用内存；同时启动多个模型实例可能会显著增加内存使用量。 ### 实用批处理清单 1. 创建源音频的只读副本或备份。 2. 验证每个文件可读取且格式受支持。 3. 选择并记录模型与语言设置。 4. 运行小批样本并检查输出。 5. 扩大处理规模前加入日志和唯一输出路径。 6. 检查失败、空转录和异常短的输出。 7. 保留原始音频，并记录所有人工编辑。 ## 在应用程序中使用 whisper.cpp 仓库包含面向集成的代码和示例，但具体 API 和示例程序可能变化。在围绕特定接口开发应用之前，请查看当前项目文档。个人脚本通常用命令行调用就足够。服务端或嵌入式集成还需要考虑并发、取消操作、内存限制、文件验证、错误报告和临时音频清理。 如果通过 HTTP 接口提供转录服务，应将音频视为敏感输入。设置身份验证和授权，限制请求大小与处理时间，并避免将文件写入公开目录。明确数据保留和删除规则。本地托管的服务并不会自动保证隐私；日志、备份或访问控制处理不当仍会造成风险。 如果应用需要的是界面，而不是本地 CLI，请先明确用户的实际需求。屏幕录制器和语音转录引擎解决的是不同问题：[Loom](/zh/tools/loom) 专注于录制与分享屏幕或摄像头演示，而 whisper.cpp 是用于运行语音识别的软件组件。两者可以互补，但不能互相直接替代。 ## whisper.cpp 与其他 AI 工具：按任务选择 下表中的 AI 产品可能适用于媒体工作流程的相邻环节。它们的出现并不意味着它们使用 whisper.cpp、提供等效转录能力或保证某种导出功能。依赖它们之前，请核实当前功能和条款。 | 工具 | 更适合的工作 | 与 whisper.cpp 的关系 | 价格层级 | |---|---|---|---| | [Gemini](/zh/tools/gemini) | 通用 AI 辅助，以及处理受支持的内容 | 可以协助整理或总结你提供的文本；它不同于本地运行 whisper.cpp | Freemium；当前价格请查看官网 | | [Loom](/zh/tools/loom) | 录制和分享屏幕或摄像头更新 | 用于录制演示流程；whisper.cpp 可另行识别兼容音频 | Freemium；当前价格请查看官网 | | [Opus Clip](/zh/tools/opus-clip) | 将长视频改编为较短片段 | 视频编辑和片段选择不同于本地语音识别 | Freemium；当前价格请查看官网 | | [Canva](/zh/tools/canva) | 设计视觉内容和演示文稿 | 可在转录后将选定素材制作成视觉内容；不能替代本地模型 | Freemium；当前价格请查看官网 | | [Gamma](/zh/tools/gamma) | 创建演示文稿和结构化视觉文档 | 将经过审核的转录内容制作成演示文稿时可能有用 | Freemium；当前价格请查看官网 | | [Wix AI](/zh/tools/wix-ai) | 创建或管理网站内容 | 可协助发布经审核的转录或文章，但不负责本地转录步骤 | Freemium；当前价格请查看官网 | | [Magical](/zh/tools/magical) | 重复文本任务与浏览器工作流程辅助 | 可能适用于后续文本工作；不能替代音频识别 | Free；当前价格请查看官网 | | [Replicate](/zh/tools/replicate) | 访问托管机器学习模型与 API | 托管模型工作流程不同于在自有硬件运行 whisper.cpp；应比较隐私、运维和使用条款 | Freemium；当前价格请查看官网 | 根据任务选择工具。若要本地转录文件和进行实验，whisper.cpp 可以直接控制运行时与模型。若需要编辑、发布、制作演示文稿或使用托管 AI，相邻产品可能更方便。除非其他服务的数据处理方式符合需求，否则不要向其上传机密音频或转录文本。 ## 常见错误与排查方法 ### 无法打开模型文件 检查完整路径、文件名、权限以及下载是否完成。确认文件格式受到当前 whisper.cpp 版本支持。来自其他运行时的模型可能需要转换。请遵循仓库的模型说明；更改扩展名不等于转换格式。 ### 无法读取音频文件 尝试用一个确认可用的 WAV 文件测试，以区分输入格式问题和构建问题。用音频播放器检查文件，确认它不是空文件或损坏文件。必要时使用可信工具转换成项目建议的输入格式。如果文件是多声道或格式特殊，可以制作简单的单声道测试副本并比较结果。 ### 输出语言不正确 使用构建版本支持的语法明确设置语言。检查音乐、静音、语音过短或多语言等可能干扰自动检测的因素。如果录音不断切换语言，应分别检查各段，不要期待单一语言设置适用于整场对话。 ### 转录速度很慢 确认加载的是哪个模型，以及预期加速后端是否已启用。可先用较小模型建立基线，再比较受支持的加速构建。内存受限时关闭其他高负载任务。处理速度还会随音频时长、硬件、构建设置和模型变化；不要根据极短测试片段推算整体处理时间。 ### 输出重复或出现幻觉文本 当音频包含静音、噪声、音乐或难以辨识的语音时，可能出现这种情况。检查音频、语言设置，以及任何提示词或上下文选项。尝试其他模型或清晰片段。不要因为重复文本读起来通顺，就认定音频中确实说了这些话。重要材料应对照录音核实。 ### 构建成功，但无法使用加速后端 即使编译完成，可选加速器也可能没有启用。检查 CMake 配置、依赖检测结果和启动时的运行信息，并对照当前平台说明。CPU 回退仍可用于验证，但应确认实际使用的是哪种设备。 ### 字幕时间不准确 确认转录后音频没有被剪切或移动。如果有停顿、多人重叠说话或长段音乐，应重点检查这些位置。如果编辑过音频，应从最终音频重新生成字幕，或在字幕编辑器中重新对齐。不要认为修改源音轨时间线后原时间戳仍然有效。 ## 隐私、许可与负责任使用 本地推理可以减少上传音频的需要，但并不能解决所有隐私问题。模型下载、包管理器、周边工具中的遥测、shell 历史记录、日志、备份和应用集成都可能影响数据暴露。检查软件环境，并遵循录音适用的政策。临时文件不再需要时应删除，同时限制已存储转录的访问权限。 检查 whisper.cpp 软件、模型权重及部署所用依赖的许可和条款。软件和模型条款可能并不相同。若要重新分发或用于商业用途，应查阅当前适用许可，不要假设本地运行就免除了义务。 转录可能包含个人或机密信息。限制访问、制定保留期限，并在必要时取得适当同意。识别错误可能显著改变含义，因此不要将未经校对的自动转录作为高影响决策的唯一依据。 ## 推荐的端到端工作流程 要可靠地完成第一个项目，可以分阶段进行： 1. 阅读当前仓库的构建说明，并安装基础编译工具。 2. 构建 CPU 版本，确认 CLI 帮助信息可以正常显示。 3. 按项目文档获取一个兼容模型。 4. 使用标准格式的、有代表性的短录音进行测试。 5. 如果自动检测不可靠，就明确设置语言。 6. 先生成纯文本；需要时再生成带时间戳或字幕输出。 7. 对照音频检查姓名、数字、标点和困难片段。 8. 只有在基线显示出实际限制时，才比较其他模型或构建方式。 9. 批量使用时，加入日志、独立输出路径、输入验证和失败处理。 10. 记录模型和设置，并保护源录音与转录文件。 这种流程可以将设置问题与识别质量问题分开处理。升级源代码、模型或硬件配置后，也更容易重现结果。 ## 常见问题 ### whisper.cpp 可以免费使用吗？ whisper.cpp 项目是开源软件，但你应检查当前仓库许可，以及所用具体模型和依赖的条款。本地运行可以避免为该运行时支付托管转录费用，但硬件、存储和工程时间仍有成本。当前条款请查阅项目与模型的官方来源。 ### whisper.cpp 能否在没有网络连接时使用？ 获取软件和兼容模型后，可以离线推理。初始设置仍需获取源代码或二进制文件及模型文件。封装程序、更新检查器或周边应用可能会发起网络请求，因此应检查完整环境的行为，不要假设所有组件都离线运行。 ### whisper.cpp 能转录实时语音吗？ 仓库曾提供与流式处理或麦克风输入有关的示例和模式，但可用性与行为可能随版本和平台变化。请查看当前示例和构建说明。处理已录制文件通常比实时应用更容易验证；实时应用还需要处理缓冲、延迟和中断。 ### 应该使用哪个模型？ 先选择符合内存和处理资源限制的模型，再测试有代表性的样本。小模型通常更快、更轻；大模型需要更多资源，并可能改善某些困难场景。最佳选择取决于语言、录音质量、词汇和硬件，因此应比较实际输出，而不是只看模型大小。 ### 它能生成字幕吗？ 受支持的版本可以通过 CLI 生成带时间戳或面向字幕的输出。使用 `--help` 查看可用格式和选项。发布前应检查时间、换行、说话人变化和术语；自动输出是草稿，不保证已达到最终字幕质量。 ### 为什么姓名和专业词汇容易识别错误？ 如果音频证据不足，模型可能无法分辨陌生术语，相似发音的词也可能存在歧义。改善源录音、设置语言、在适当情况下使用文档所支持的上下文选项，并对照录音校正文本。可以为重复术语维护统一词表，但每次都要结合上下文核对。 ### 本地转录是否自动保证隐私？ 不能。本地处理可以避免把音频发送给转录服务商，但隐私还取决于文件存储、日志、备份、访问控制、模型来源和任何联网应用。应检查完整工作流程以及录音适用的规定。 ### whisper.cpp 与浏览器应用中的 Whisper 是同一个东西吗？ 不是。Whisper 指的是语音识别模型系列，而 whisper.cpp 是运行兼容模型的一种特定实现。浏览器或托管服务可能使用不同的软件、模型版本、处理设置和数据实践。应比较具体实现与条款，不要假设两者完全相同。