跳转到内容
OpenASR

CLI 参考

openasr 可执行文件由开源仓库中的 openasr-cli crate 构建。你可以下载预编译版本，也可以按照 CLI 快速上手从源码编译。

在源码目录中调试时，可将下文的 openasr 替换为：

bash
cargo run -p openasr-cli -- <args>

命令一览

Section titled “命令一览”
命令用途
transcribe <inputs>...（别名 t）转写一个或多个文件，也可直接传入目录；--benchmark 只输出运行耗时，不输出转写结果
live从麦克风或系统音频实时采集，按语句输出最终字幕；声明支持流式输出的模型包也可返回中间结果
serve启动兼容 OpenAI 格式的本地 HTTP API；监听非本机地址时需要 TLS 和配对认证
search [query] / pull <ref>搜索模型目录 / 下载并安装模型包
list / show <id-or-pack> / rm <id>查看已安装模型 / 查看目录或模型包详情 / 删除模型
verify <pack.oasr>检查本地模型包的 ggml 完整性，不运行推理，也不下载文件
speaker enroll / speaker clear管理说话人分离所用的本地声纹匹配资料；仅保存嵌入向量，不用于身份认证
model-pack import <family>从源权重构建 .oasr 模型包，供维护者使用
config / doctor / bench-suite管理配置 / 输出环境诊断 / 运行性能测试套件
apikey create / apikey list / apikey revoke <id>管理 openasr serve 的本地 API key（Authorization: Bearer <key>）

不同版本的参数可能变化，请以 openasr --help 或 openasr <command> --help 的输出为准。

模型管理

Section titled “模型管理”
bash
openasr search                  # 浏览模型目录
openasr pull whisper-small      # 下载并安装模型包
openasr list                    # 查看已安装模型
openasr rm whisper-small        # 删除模型
openasr config list             # 查看当前配置
openasr doctor                  # 检查运行环境

模型的语言、体积和量化版本可在模型页面查看。

文件转写

Section titled “文件转写”
bash
openasr transcribe audio.wav --model whisper-small --format text

常用参数如下：

  • -m/--model：选择模型，也可通过 OPENASR_MODEL 环境变量设置
  • -f/--format：输出格式，可重复传入；支持 text、json、srt、vtt、verbose_json 和 markdown
  • -o/--output：指定输出文件或目录
  • -l/--language：使用 auto 自动识别，或传入 en 等语言提示
  • --task：转写任务类型，transcribe（保留源语言）或 translate（翻译为英语）；仅 Whisper 模型支持
  • --diarize：启用说话人分离；可配合 --speakers <n> 指定人数
  • --word-timestamps：输出逐词时间戳；不带值或 =approximate 使用模型自身解码时的 时间戳，=aligned 会用 Qwen3-ForcedAligner-0.6B 能力包做进一步对齐（仅 native 后端）
  • --no-punctuate：跳过标点恢复
  • --continue-on-error：批量处理时跳过失败文件，继续执行
  • --hotword <phrase> / --hotword-boost：提高指定词语的识别倾向
  • --adapter <path>：指定本地 .oadp adapter 包
  • --ffmpeg-bin <path>：指定已安装的 ffmpeg 可执行文件路径
  • -y/--yes：跳过模型下载确认
  • --offline：禁止下载；所需模型不存在时直接失败

--word-timestamps 可以带一个可选模式：不带值（或 =approximate，默认值） 使用模型自身解码过程产出的逐词时间戳，不需要额外开销。--word-timestamps=aligned 目前还不可用——它依赖的强制对齐能力包（Qwen3-ForcedAligner-0.6B）代码路径已经 存在，但尚未进入公开模型目录，拉取会失败。在该能力包发布之前，请使用默认的 approximate 模式。

使用本地 .oasr 模型包

Section titled “使用本地 .oasr 模型包”

transcribe、live 和 serve 默认都使用 native 后端。一般情况下只需用模型 ID 选择已安装模型；如需固定到某个本地文件，可使用 --model-pack：

bash
openasr transcribe audio.wav --model-pack /path/to/model.oasr --format text

如果模型包不支持请求的输入或能力，原生后端会明确失败，不会生成不完整的时间戳、说话人分离或置信度结果。

批量处理与性能测试

Section titled “批量处理与性能测试”

transcribe 可以接收多个文件或一个目录。配合 --output 时，每个输入文件会生成对应的转写结果：

bash
openasr transcribe /path/to/audio-dir --output /path/to/transcripts
openasr transcribe audio.wav --benchmark --model whisper-small

实时转写与本地服务

Section titled “实时转写与本地服务”
bash
openasr live --source mic --max-seconds 5 --format jsonl
openasr serve

服务端接口、监听地址和远程访问要求见本地 API。