完整指令
supported audio formats: flac, mp3, ogg, wav options: -h, --help [default] show this help message and exit -t N, --threads N [4 ] number of threads to use during computation -p N, --processors N [1 ] number of processors to use during computation -ot N, --offset-t N [0 ] time offset in milliseconds -on N, --offset-n N [0 ] segment index offset -d N, --duration N [0 ] duration of audio to process in milliseconds -mc N, --max-context N [-1 ] maximum number of text context tokens to store -ml N, --max-len N [0 ] maximum segment length in characters -sow, --split-on-word [false ] split on word rather than on token -bo N, --best-of N [5 ] number of best candidates to keep -bs N, --beam-size N [5 ] beam size for beam search -ac N, --audio-ctx N [0 ] audio context size (0 - all) -wt N, --word-thold N [0.01 ] word timestamp probability threshold -et N, --entropy-thold N [2.40 ] entropy threshold for decoder fail -lpt N, --logprob-thold N [-1.00 ] log probability threshold for decoder fail -nth N, --no-speech-thold N [0.60 ] no speech threshold -tp, --temperature N [0.00 ] The sampling temperature, between 0 and 1 -tpi, --temperature-inc N [0.20 ] The increment of temperature, between 0 and 1 -debug, --debug-mode [false ] enable debug mode (eg. dump log_mel) -tr, --translate [false ] translate from source language to english -di, --diarize [false ] stereo audio diarization -tdrz, --tinydiarize [false ] enable tinydiarize (requires a tdrz model) -nf, --no-fallback [false ] do not use temperature fallback while decoding -otxt, --output-txt [false ] output result in a text file -ovtt, --output-vtt [false ] output result in a vtt file -osrt, --output-srt [false ] output result in a srt file -olrc, --output-lrc [false ] output result in a lrc file -owts, --output-words [false ] output script for generating karaoke video -fp, --font-path [/System/Library/Fonts/Supplemental/Courier New Bold.ttf] path to a monospace font for karaoke video -ocsv, --output-csv [false ] output result in a CSV file -oj, --output-json [false ] output result in a JSON file -ojf, --output-json-full [false ] include more information in the JSON file -of FNAME, --output-file FNAME [ ] output file path (without file extension) -np, --no-prints [false ] do not print anything other than the results -ps, --print-special [false ] print special tokens -pc, --print-colors [false ] print colors --print-confidence [false ] print confidence -pp, --print-progress [false ] print progress -nt, --no-timestamps [false ] do not print timestamps -l LANG, --language LANG [en ] spoken language ('auto' for auto-detect) -dl, --detect-language [false ] exit after automatically detecting language --prompt PROMPT [ ] initial prompt (max n_text_ctx/2 tokens) --carry-initial-prompt [false ] always prepend initial prompt -m FNAME, --model FNAME [models/ggml-base.en.bin] model path -f FNAME, --file FNAME [ ] input audio file path -oved D, --ov-e-device DNAME [CPU ] the OpenVINO device used for encode inference -dtw MODEL --dtw MODEL [ ] compute token-level timestamps -ls, --log-score [false ] log best decoder scores of tokens -ng, --no-gpu [false ] disable GPU -fa, --flash-attn [true ] enable flash attention -nfa, --no-flash-attn [false ] disable flash attention -sns, --suppress-nst [false ] suppress non-speech tokens --suppress-regex REGEX [ ] regular expression matching tokens to suppress --grammar GRAMMAR [ ] GBNF grammar to guide decoding --grammar-rule RULE [ ] top-level GBNF grammar rule name --grammar-penalty N [100.0 ] scales down logits of nongrammar tokens Voice Activity Detection (VAD) options: --vad [false ] enable Voice Activity Detection (VAD) -vm FNAME, --vad-model FNAME [ ] VAD model path -vt N, --vad-threshold N [0.50 ] VAD threshold for speech recognition -vspd N, --vad-min-speech-duration-ms N [250 ] VAD min speech duration (0.0-1.0) -vsd N, --vad-min-silence-duration-ms N [100 ] VAD min silence duration (to split segments) -vmsd N, --vad-max-speech-duration-s N [FLT_MAX] VAD max speech duration (auto-split longer) -vp N, --vad-speech-pad-ms N [30 ] VAD speech padding (extend segments) -vo N, --vad-samples-overlap N [0.10 ] VAD samples overlap (seconds between segments)
Whisper-CLI 是基于 OpenAI Whisper 模型的命令行工具，由 whisper.cpp 项目封装实现，能在本地快速完成语音转文字、精准识别特定指令的任务。对于初学者而言，无需复杂的代码开发，仅靠几条命令就能解锁语音识别能力。
我们可以用架构比喻来理解 Whisper-CLI 的核心逻辑：
- 核心项目 =
whisper.cpp项目本体：提供所有工具和能力的基础； - 执行入口 =
whisper-cli.exe：负责执行指令、调度资源的核心工具； - 预训练模型（如
ggml-tiny.bin）：模型大小决定性能强弱，小模型轻便快速，大模型精准全面； - 约束规则 = GBNF 语法文件：约束识别范围，只允许提取符合规则的内容；
- 音频输入：需要被识别的语音文件；
- 输出结果 = 语音转文字 / 热词提取：最终生成的识别文本。
一、核心概念与组件介绍
1. 核心组件
| 组件 | 作用 |
|---|---|
whisper-cli.exe | 命令行执行入口，接收参数、调度模型、输出结果 |
| 预训练模型（.bin） | 决定识别能力，从 tiny（轻量）到 large（高精度）分为多个等级 |
| GBNF 语法文件 | 约束识别范围，只提取符合规则的内容（如酒店指令、设备控制指令） |
| 音频文件（wav/mp3） | 待识别的语音输入，推荐 16kHz 单声道 WAV 格式 |
2. 关键参数
| 参数 | 功能 | 示例 |
|---|---|---|
-m | 指定模型路径 | -m D:/ai/asr/models/ggml-tiny.bin |
--language | 指定识别语言（如中文） | --language zh |
--grammar | 启用 GBNF 语法约束 | --grammar D:/ai/asr/rule.wbnf |
--output-txt | 将结果保存为文本文件 | --output-txt |
--no-timestamps | 只输出纯文字，去除时间戳 | --no-timestamps |
| 音频文件路径 | 指定待识别音频 | D:/ai/asr/audio/test.wav |
二、初学者入门步骤
步骤 1：环境与文件准备
- 下载项目：从
whisper.cpp官方仓库下载项目压缩包，解压到本地（如D:/ai/asr/whisper.cpp），找到whisper-cli.exe； - 下载模型：下载预训练模型，初学者优先选
ggml-tiny.bin（体积小、运行快），放到models文件夹； - 准备音频：准备待识别的音频文件，用工具（如 Audacity）转换为 16kHz 单声道 WAV 格式；
- 编写规则（可选）：新建 GBNF 文件，写入简单规则（如
root ::= "查询酒店" | "打开房间"），放到rule文件夹。
步骤 2：基础语音转文字
- 打开终端：启动 Windows 命令提示符（CMD）或 PowerShell；
- 切换目录：切换到
whisper-cli.exe所在目录。
cd D:/ai/asr/whisper.cpp
- 运行命令：输入基础识别命令。
whisper-cli.exe -m D:/ai/asr/models/ggml-tiny.bin --language zh D:/ai/asr/audio/test.wav
命令执行完成后，控制台会输出音频对应的文字内容。
步骤 3：启用 GBNF 约束
如果想让工具只识别特定指令（如酒店开房、设备控制），就需要启用 GBNF 语法文件：
- 添加参数：在命令中加入
--grammar参数。
whisper-cli.exe -m D:/ai/asr/models/ggml-tiny.bin --language zh --grammar D:/ai/asr/rule/hotel_rule.gbnf D:/ai/asr/audio/test.wav
- 编写规则：新建
hotel_rule.gbnf文件，写入极简规则。
root ::= "帮我打开酒店房间 3105" | "客人李四的手机号 1348883468" | "送一瓶可乐"
此时工具只会输出符合 GBNF 规则的内容，无关的口语化表述会被自动过滤。
步骤 4：保存识别结果
添加 --output-txt 参数，将识别结果保存为文本文件。
whisper-cli.exe -m D:/ai/asr/models/ggml-tiny.bin --language zh --grammar D:/ai/asr/rule/hotel_rule.gbnf --output-txt --no-timestamps D:/ai/asr/audio/test.wav
执行后，会在音频文件同目录生成 test.txt，里面是纯净的识别文字。
三、常见应用场景
1. 日常语音转写
适用于会议录音转文字、采访音频整理等场景。无需 GBNF 约束，直接用基础命令就能将语音转为文字。
- 核心优势：本地运行，无需联网，保护隐私；
- 入门命令：
whisper-cli.exe -m 模型路径 --language zh 音频路径 --output-txt。
2. 特定指令识别
适用于智能设备控制、业务指令提取等场景，通过 GBNF 语法约束，只识别预设指令。
- 场景示例：酒店前台语音指令识别、智能家居控制；
- 核心优势：过滤无关内容，精准提取关键指令；
- 关键配置：编写针对性的 GBNF 语法文件。
3. 热词精准提取
适用于需要从语音中提取特定信息的场景，如从酒店通话中提取房间号、手机号、配送物品等。
- 实现思路：先用极简 GBNF 约束识别范围，再用正则表达式提取热词；
- 核心优势：比通用语音转写更聚焦，适合垂直业务场景。
四、避坑指南
- 模型选择：入门选
tiny/base模型，大模型（如large）虽然精准，但对电脑性能要求高； - 音频格式：必须转为 16kHz 单声道 WAV 格式，否则可能出现识别乱码或失败；
- GBNF 语法：初学者不要写复杂嵌套规则，先从
root ::= "指令 1" | "指令 2"开始； - 路径规范：模型、音频、语法文件的路径不要包含中文和空格，否则会提示'文件找不到'。
五、进阶方向
- 尝试更大模型：从
tiny升级到base/small，提升识别准确率； - 编写复杂 GBNF 规则：针对业务场景定制语法，实现更精准的指令约束；
- 结合脚本自动化：用 Python 脚本批量处理音频文件，自动提取热词并生成报告；
- 部署到嵌入式设备：
whisper.cpp支持树莓派等设备，可实现本地化的语音助手。