ona

参考与帮助

CLI 指南

从终端运行 Sona 的离线批量转录，管理预置模型，生成 shell 补全脚本，并启动无界面本地服务。

向 AI 提问

当前部署尚未启用受保护的文档问答。

sona 通过桌面主程序提供离线转写命令。安装包不会把 sona 写入 shell PATH，因此需要直接运行已安装的应用二进制文件并附带 CLI 子命令。从源码构建时，也可以用 Cargo 运行同一组命令。

CLI 范围刻意保持精简：单文件和目录离线转写、预置模型列表/下载/删除、无头 HTTP API 服务启动。它不包含实时录音、LLM 润色或 LLM 翻译。

运行方式

  • Windows：在安装目录运行 Sona.exe transcribe ...
  • macOS：运行 /Applications/Sona.app/Contents/MacOS/Sona transcribe ...
  • Linux 安装包：从安装位置运行 Sona 主程序并附带 CLI 子命令
  • AppImage：运行挂载后的 AppImage 可执行文件并附带 CLI 子命令
  • 源码：cargo run --manifest-path src-tauri/Cargo.toml -- transcribe ./sample.mp4 --config ./sona-cli.toml

常用命令

转写文件

sona transcribe ./sample.mp4 \
  --config ./sona-cli.toml \
  --output ./sample.srt

不指定 --output 时，转写结果会以 JSON 写入 stdout。指定 --output 时，格式会从文件扩展名推断，除非同时传入 --format。已有输出文件默认受保护；只有明确传入 --force 时才会覆盖。

转写目录

sona transcribe \
  --input-dir ./media \
  --output-dir ./transcripts \
  --format srt \
  --recursive \
  --jobs 1 \
  --config ./sona-cli.toml

目录模式会为每个受支持媒体文件在 --output-dir 中写出一个转写文件。默认只扫描目录直属文件；加入 --recursive 后会包含子目录，并保留相对输出路径。转写正文写入文件，stdout 会输出 JSON 成功/失败汇总。

也可以传入多个输入文件或 glob 通配模式。它们会使用与目录模式相同的批量输出规划，并要求传入 --output-dir：

sona transcribe ./media/*.wav ./media/interview.mp4 --output-dir ./transcripts --format srt

列出、下载或删除模型

sona models list --mode offline --type whisper
sona models list --language zh --installed
sona models list --json
sona models download sherpa-onnx-whisper-turbo
sona models delete sherpa-onnx-whisper-turbo

models list 默认输出便于阅读的表格。脚本需要完整机器可读结构时使用 --json，其中仍包含 install_path。 当所选预置模型需要伴生模型时，models download 会自动下载所需模型，例如 silero-vad 或默认标点模型。 models delete 只会删除指定模型，不会自动删除伴生模型。

启动 API 服务

sona serve --host 127.0.0.1 --port 14200 --api-key your_secure_key

HTTP API 端点和请求示例见 HTTP API 指南。

配置文件

通过 --config 传入 TOML 文件。命令行参数会覆盖配置文件中的值。

最小 transcribe 示例：

models_dir = "C:/Users/you/AppData/Local/com.asoda.sona/models"
model_id = "sherpa-onnx-whisper-turbo"
vad_model_id = "silero-vad"
language = "auto"
threads = 4
enable_itn = false
vad_buffer_size = 5.0
gpu_acceleration = "auto"
hotwords = "Sona,offline ASR"
format = "srt"
quiet = false
jobs = 1

transcribe 配置键

参数 / 配置键必选性取值范围默认值说明
models_dir可选文件系统路径可推断时使用桌面应用模型目录CLI 找不到桌面模型目录时请显式传入。
model_id必选，除非传入 --model-id离线预置模型 ID无用 sona models list --mode offline 查看可用 ID。
vad_model_id可选预置模型 ID需要时为 silero-vad所选模型需要 VAD 时使用；可覆盖默认伴生模型。
punctuation_model_id可选预置模型 ID需要时为 sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8所选模型需要标点时使用；可覆盖默认伴生模型。
language可选auto 或模型语言代码，如 zh、en、jaauto覆盖自动语言检测。
threads可选大于 0 的整数4识别线程数。
enable_itn可选true 或 falsefalse启用逆文本归一化。
hotwords可选逗号分隔词组无自定义 ASR 热词；当前支持 Transducer 和 Qwen3 模型。
quiet可选true 或 falsefalse设为 true 时隐藏转写进度；CLI --quiet 也会启用。
jobs可选大于 0 的整数1目录、多输入或 glob 模式下最大并发文件任务数；CLI --jobs 会覆盖。
vad_buffer_size可选大于 0 的数字5.0VAD 缓冲秒数。
gpu_acceleration可选auto、cpu、cuda、coreml、directmlauto使用 cpu 可显式关闭 GPU 加速。
format可选json、txt、srt、vtt、md写入 stdout 或目录模式时为 json，否则从 --output 推断覆盖输出扩展名推断。

serve 配置键

参数 / 配置键必选性取值范围默认值说明
host可选监听地址0.0.0.0本机访问可用 127.0.0.1。
port可选TCP 端口 0 到 6553514200API 服务端口。
api_key可选字符串空为空时请求不需要 Bearer 认证。
models_dir可选文件系统路径可推断时使用桌面应用模型目录用于解析已安装模型。
ip_whitelist可选逗号分隔规则localhost支持 localhost、精确 IP、CIDR、*，以及 192.168.* 这类 IPv4 通配。
max_streaming可选非负整数2最大并发流式 WebSocket 连接数。
max_concurrent可选非负整数2最大并发批量任务数。
max_queue_size可选非负整数1000 表示队列基本不限。
max_upload_size_mb可选非负整数500 表示关闭上传大小限制。
job_ttl_minutes可选非负整数600 表示关闭完成/失败任务清理。
gpu_acceleration可选auto、cpu、cuda、coreml、directmlauto本地批量和流式任务的服务级默认值。
vad_model_id可选预置模型 IDsilero-vadAPI 服务任务的默认 VAD 伴生模型。
punctuation_model_id可选预置模型 IDsherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8API 服务任务的默认标点伴生模型。

参数

全局

sona
  -V, --version
  -v, --verbose
  -h, --help
  help

使用 -V 或 --version 打印 Sona 版本号。使用 -v 或 --verbose 放在子命令前启用详细诊断日志。使用 -h、--help 或 help 打印命令帮助：

sona --version
sona -V
sona -v models list
sona --verbose transcribe ./sample.mp4 --config ./sona-cli.toml
sona transcribe --help

详细诊断日志会写入 stderr。命令结果仍写入 stdout，包括 models list 的表格或 JSON 输出，以及 transcribe 未指定 --output 时的输出，因此仍可安全管道传给其他工具。

高级包装脚本和测试可以设置 SONA_FORCE_CLI=1，即使可执行文件启动时没有识别到 CLI 子命令，也强制进入 CLI 模式。

使用 sona completions <shell> 生成 shell 补全脚本。支持 bash、zsh、fish、powershell 和 elvish；脚本会写入 stdout。

transcribe

参数 / 配置键必选性取值范围默认值说明
<input>...必选，除非传入 --input-dir本地音频/视频文件路径或 glob 通配模式无单个输入保持单文件模式；多个输入或 glob 模式会进入批量模式并要求 --output-dir。
--input-dir <dir>目录模式必选目录路径无转写目录中的受支持媒体文件。
--config <path>可选TOML 文件路径无从配置文件加载默认值。
--output <path>可选文件系统路径stdout仅用于单文件模式。文件已存在时会报错，除非传入 --force。
--output-dir <dir>与 --input-dir、多个输入或 glob 同用时必选目录路径无为每个输入文件写出一个转写文件。计划输出已存在时会报错，除非传入 --force。
--recursive可选标志关闭扫描子目录并保留相对输出路径。
--jobs <n>可选大于 0 的整数jobs 配置或 1批量模式下最大并发文件任务数。
--format <format>可选json、txt、srt、vtt、md写入 stdout 或目录模式时为 json，否则从 --output 推断覆盖配置和输出扩展名推断。
--language <code>可选auto 或模型语言代码auto覆盖配置。
--model-id <id>必选，除非配置了 model_id离线预置模型 ID无主转写模型。
--models-dir <path>可选文件系统路径可推断时使用桌面应用模型目录覆盖配置。
--vad-model-id <id>可选预置模型 ID需要时为 silero-vad覆盖默认 VAD 伴生模型。
--punctuation-model-id <id>可选预置模型 ID需要时为 sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8覆盖默认标点伴生模型。
--threads <n>可选大于 0 的整数4覆盖配置。
--enable-itn可选标志false与 --disable-itn 互斥。
--disable-itn可选标志false覆盖 enable_itn = true；与 --enable-itn 互斥。
--hotwords <words>可选逗号分隔词组无覆盖 hotwords；当前支持 Transducer 和 Qwen3 模型。
--gpu-acceleration <provider>可选auto、cpu、cuda、coreml、directmlauto覆盖配置。
--vad-buffer <seconds>可选大于 0 的数字5.0vad_buffer_size 的 CLI 参数名。
--save-wav <path>可选文件系统路径无仅 CLI 参数；保存中间重采样 WAV。与 --input-dir 不兼容。
--quiet可选标志关闭隐藏转写进度，并覆盖 quiet = false。
--force可选标志关闭允许覆盖已有输出文件。批量模式中规划出的重复输出仍会失败。

models list

参数 / 配置键必选性取值范围默认值说明
--models-dir <path>可选文件系统路径可推断时使用桌面应用模型目录用于检测已安装预置模型。
--mode <mode>可选streaming、offline所有模式按支持模式过滤。
--type <type>可选预置模型类型，如 whisper、vad、punctuation所有类型按模型类型过滤。
--language <code>可选语言令牌，如 zh、en、ja、yue所有语言按支持语言令牌过滤。
--installed可选标志关闭只显示 models_dir 中已存在的模型。
--json可选标志关闭输出机器可读 JSON，而不是默认表格。
输出总是表格或 JSON表格写入 stdout。

models download

参数 / 配置键必选性取值范围默认值说明
<model_id>必选已知预置模型 ID无要下载的主模型。
--models-dir <path>可选文件系统路径可推断时使用桌面应用模型目录目标模型目录。
--quiet可选标志关闭隐藏单个下载进度。
伴生模型下载自动所需 VAD 和标点预置模型自动下载主模型时会同时下载必需伴生模型。

models delete

参数 / 配置键必选性取值范围默认值说明
<model_id>必选已知预置模型 ID无要删除的模型。
--models-dir <path>可选文件系统路径可推断时使用桌面应用模型目录目标模型目录。
--yes可选标志关闭跳过交互确认提示。
安装路径缺失否已知但未安装的预置模型成功 no-op向 stderr 输出提示并以状态码 0 退出。
伴生模型删除否所需 VAD 和标点预置模型不删除如果不再需要伴生模型，请显式删除对应模型。

serve

参数 / 配置键必选性取值范围默认值说明
--config <path>可选TOML 文件路径无从配置文件加载默认值。
--host <ip>可选监听地址0.0.0.0覆盖配置。
--port <port>可选TCP 端口 0 到 6553514200覆盖配置。
--api-key <key>可选字符串空为空时不启用 Bearer 认证。
--models-dir <path>可选文件系统路径可推断时使用桌面应用模型目录覆盖配置。
--ip-whitelist <rules>可选逗号分隔规则localhost支持 localhost、精确 IP、CIDR、*，以及 192.168.* 这类 IPv4 通配。
--max-streaming <n>可选非负整数2最大并发流式连接数。
--max-concurrent <n>可选非负整数2最大并发批量任务数。
--max-queue-size <n>可选非负整数1000 表示队列基本不限。
--max-upload-size-mb <n>可选非负整数500 表示关闭上传大小限制。
--job-ttl-minutes <n>可选非负整数600 表示关闭完成/失败任务清理。
--gpu-acceleration <provider>可选auto、cpu、cuda、coreml、directmlautoHTTP API 请求不支持按请求覆盖 GPU 配置。
--vad-model-id <id>可选预置模型 IDsilero-vadAPI 服务任务的默认 VAD 伴生模型。
--punctuation-model-id <id>可选预置模型 IDsherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8API 服务任务的默认标点伴生模型。

运行 sona <command> --help 可查看 clap 生成的完整帮助文本。

上一页

词汇与高级设置

下一页

HTTP API