Summarize 接入 NVIDIA Parakeet/Canary ONNX 本地转写：外部 CLI 集成、自动下载与回退链路全解析
【免费下载链接】summarizePoint at any URL/YouTube/Podcast or file. Get the gist. CLI and Chrome Extension.项目地址: https://gitcode.com/GitHub_Trending/summarize/summarize
本文以 summarize 项目的 ONNX 本地转写功能为切入点，讲解如何通过外部 CLI（如 sherpa-onnx）在本机运行 NVIDIA Parakeet-TDT 0.6B-v3 / Canary 1B-v2 的 ONNX 导出模型完成语音转写。读完本文，你将掌握命令模板（JSON 数组与 Shell 字符串两种形式）的配置方法、四个占位符的语义、模型文件的自动缓存与镜像下载机制，以及 ONNX 在自动转写选择链中的位置与失败回退行为，并能使用summarize transcriber setup一键诊断本地环境。
功能概述：把 ONNX 转写"外包"给用户自备的 CLI
summarize 本身不捆绑任何 ONNX 推理引擎，而是采用"shell out（外部进程调用）"的设计：项目负责音频准备、模型文件下载缓存、命令模板展开与输出解析，真正执行推理的是用户提供的 CLI 二进制（官方推荐sherpa-onnx，也支持自定义包装脚本）。依据 onnx-cli.ts 的实现，这个外部程序只需满足两个契约：
- 接受一个 WAV 输入路径作为音频入口；
- 将转写文本输出到 stdout。
在自动转写链中，ONNX 的优先级由 help.ts 明确列出：
Groq -> ONNX (selected/configured parakeet or canary) -> whisper.cpp -> AssemblyAI -> Gemini -> OpenAI -> FAL -> Deepgram也就是说：当 Groq 已配置时优先走 Groq；之后在本地转写阶段，ONNX 优先于whisper.cpp；再往后才轮到各云端转写提供商。用户也可以显式指定whisper.cpp或某个具体的 ONNX 模型来限定本地阶段。
启用步骤
1. 安装能运行 ONNX 模型的 CLI
由于 Homebrew 可能没有现成的 formula，官方文档建议从上游二进制发布或源码编译安装sherpa-onnx（或自写包装脚本）。可以从summarize transcriber setup的提示文本看到同样的建议："Install sherpa-onnx from upstream binaries or build; Homebrew may not have a formula."（见 transcriber-cli.ts）。
2. 设置命令模板（两种形式任选其一）
为 Parakeet 与 Canary 各设置一条命令模板环境变量：
| 环境变量 | 对应模型 |
|---|---|
SUMMARIZE_ONNX_PARAKEET_CMD | Parakeet-TDT 0.6B-v3 ONNX |
SUMMARIZE_ONNX_CANARY_CMD | Canary 1B-v2 ONNX |
推荐形式——JSON 数组（不经 Shell，直接 spawn）：
export SUMMARIZE_ONNX_PARAKEET_CMD='["sherpa-onnx", "...", "--tokens", "{vocab}", "--offline-ctc-model", "{model}", "--input-wav", "{input}"]' export SUMMARIZE_ONNX_CANARY_CMD='["my-canary-wrapper", "{model_dir}", "{input}"]'JSON 数组中的每个元素必须是非空字符串（源码 parseCommandTemplate 会逐一校验），随后通过spawn(command, args)直接执行，不经过 Shell，天然规避了引号与注入问题。
高级形式——Shell 字符串：
export SUMMARIZE_ONNX_PARAKEET_CMD="sherpa-onnx ... --tokens {vocab} --offline-ctc-model {model} --input-wav {input}"此时命令会交给spawn(..., { shell: true })执行（见 onnx-cli.ts）。注意：使用 Shell 字符串形式时，不要给占位符加引号——summarize 会对替换进命令的路径执行 Shell 转义（POSIX 单引号转义、Windows 下cmd.exe风格双引号转义，见 shellEscape），因此包含空格的特殊路径也能安全工作，同时降低了注入风险。
3. 占位符语义
| 占位符 | 含义 | 说明 |
|---|---|---|
{input} | 音频路径 | 若命令模板中未出现，会被自动追加到命令末尾 |
{model} | 已下载的model.onnx路径 | 首次使用时由项目自动下载到缓存 |
{vocab} | 已下载的vocab.txt路径 | 与模型同目录 |
{model_dir} | 包含已下载文件的父目录 | 适合需要"模型目录"型参数的 CLI |
占位符替换在 buildArgvCommand / buildShellCommand 中实现：遍历模板逐个replaceAll替换，且只有在模板中没有{input}时才把输入路径追加到末尾。
4. 选择 ONNX 模型（auto / CLI / 环境变量三选一）
- 自动（默认）：不设置
SUMMARIZE_TRANSCRIBER，或显式设置SUMMARIZE_TRANSCRIBER=auto。此时按 resolvePreferredOnnxModel 的逻辑：优先选已配置命令的parakeet，否则选已配置命令的canary，两者都没配置则返回null（自动链跳过 ONNX 阶段）。 - CLI 参数：
--transcriber parakeet或--transcriber canary。 - 环境变量：
SUMMARIZE_TRANSCRIBER=parakeet（或canary）。
--transcriber的合法取值是auto | whisper | parakeet | canary（见 help.ts 与 runner-flags.ts）。
Chrome 扩展场景：在Settings → Model → Advanced Overrides → Transcriber中可以设置随每次请求下发的默认转写器。但请注意，ONNX 命令模板来自 daemon 进程的环境变量，因此扩展端配置要生效，需保证 daemon 环境里仍配置了SUMMARIZE_ONNX_PARAKEET_CMD/SUMMARIZE_ONNX_CANARY_CMD；更稳妥的做法是在运行summarize daemon install --token <TOKEN>之前先 export 这些环境变量，让 daemon 直接继承你的命令模板与默认转写器。daemon 的环境快照机制会在 env-snapshot.ts 中固化这三项（SUMMARIZE_TRANSCRIBER、两个 ONNX 命令变量），保证代理请求上下文一致。
缓存与模型下载细节
模型文件的管理遵循"首次使用自动下载、之后复用缓存"的策略：
- 缓存目录：
${SUMMARIZE_ONNX_CACHE_DIR || $XDG_CACHE_HOME || ~/.cache}/summarize/onnx/<model>/（<model>为parakeet或canary）。解析逻辑见 resolveCacheDir，transcriber setup输出中也会打印当前解析到的缓存目录。 - 下载源：默认从 Hugging Face 仓库拉取——Parakeet 对应
istupakov/parakeet-tdt-0.6b-v3-onnx，Canary 对应istupakov/canary-1b-v2-onnx（见 MODEL_SOURCES）。设置SUMMARIZE_ONNX_MODEL_BASE_URL可指向任意镜像（末尾斜杠会被自动去除），URL 拼接规则为{baseUrl}/{file.path}。 - 文件清单：每个模型下载
model.onnx与vocab.txt两个文件。 - 原子写入：下载先落到
{目标}.{uuid}.tmp临时文件，整个响应流完整写完后才rename提交到缓存；任何失败都会在finally中清理临时文件（见 downloadFile）。因此失败的下载不会留下半截模型，下一次运行会自动重试。若旧版本曾留下损坏的缓存产物，手动删除对应缓存目录/文件一次即可触发重新下载。
对应的行为测试在 transcription.onnx-cli.test.ts 中：既验证了首次运行下载两个文件到cache/<model>/，也验证了下载失败时缓存目录为空、以及重试后会补齐model.onnx与vocab.txt。
运行时行为与失败回退
- 音频预处理：当可用
ffmpeg时，输入音频会被转码为16kHz 单声道 WAV再交给 CLI；ffmpeg不可用时直接透传原始文件（源码 ensureWavInput，媒体类型本身是 WAV 时跳过转码）。转码产物是临时文件，进程退出后无论成败都会被清理。 - 失败回退：三类 ONNX 错误——命令未配置（
command not configured）、非零退出码（含 stderr 摘要）、stdout 为空——都会在转录元数据中记录备注，随后回退到既有的 Whisper 流程继续处理，不会中断整体任务。错误对象构造与备注收集见 transcribeWithOnnxCliFile。 - 进度展示：外部转写器运行时，进度 UI 显示"ONNX (Parakeet/Canary)"，对应 transcript-state.ts 中
hint === "onnx"的映射；provider 标识为onnx-parakeet/onnx-canary（见 resolveOnnxProviderId）。 - 内存音频暂存：以内存字节形式传入的音频会先写为临时文件，外部转写器退出后立即删除（无论成功失败，见 transcribeWithOnnxCli 的
finally清理）。
源码级的实现细节：命令模板解析与执行
理解onnx-cli.ts的调用链有助于排查配置问题：
- 模板判定：以
[开头的值尝试按 JSON 解析为 argv 数组（逐元素校验非空字符串），解析失败或非数组则降级为 Shell 字符串模式（parseCommandTemplate）。 - 执行方式差异：argv 模式用
spawnTracked(command, args)直接派生进程；shell 模式用spawnTracked(command, [], { shell: true })。两者都通过管道捕获 stdout/stderr，stdout 上限 256 KB、stderr 上限 16 KB，超出即停止累积，防止内存失控。 - 结果判定：
close事件中先检查退出码，非零则报错；再trim()stdout，为空视为失败；否则把整段文本作为转写结果返回。 - 模型选择优先级：
SUMMARIZE_TRANSCRIBER显式指定parakeet/canary时直接用；auto或未设置时按"parakeet 已配置优先、canary 次之"自动决定（resolvePreferredOnnxModel）。
在媒体资产流程中，ONNX 被列为本地转写的首选候选（见 media.ts 的提示文案：1. Local ONNX (Parakeet or Canary)，并引导执行summarize transcriber setup）。测试 transcription-start.test.ts 验证了在SUMMARIZE_TRANSCRIBER=parakeet且命令配置就绪时，可用性探测返回onnxReady=true、providerHint="onnx"、modelId="onnx/parakeet"，印证了从 CLI 参数到转写启动的完整链路。
环境诊断：summarize transcriber setup
项目内置了专门的本机转写环境诊断命令（实现在 transcriber-cli.ts）：
summarize transcriber setup # 默认检查 parakeet summarize transcriber setup --model canary # 检查 canary summarize transcriber setup --theme <name> # 自定义主题输出该命令会一次性输出：
- 当前转写模式（
SUMMARIZE_TRANSCRIBER或auto）与自动选择顺序（Groq → ONNX → whisper.cpp → 云端回退）； - 两个 ONNX 命令是否已配置（分别对应
SUMMARIZE_ONNX_PARAKEET_CMD/SUMMARIZE_ONNX_CANARY_CMD）； - ONNX 缓存目录解析结果，以及所选模型
model.onnx/vocab.txt是否已就绪； - whisper.cpp 二进制与模型路径状态（
SUMMARIZE_WHISPER_CPP_BINARY与默认~/.summarize/cache/whisper-cpp/models/ggml-base.bin）； - 若 ONNX 未配置，会打印推荐的环境变量 export 示例与占位符说明。
这是排查"为什么没走 ONNX"的首选入口——先确认命令模板被正确读取、缓存文件已下载，再检查自动链是否被更优先的 provider 抢占。
注意事项与适用前提
- 推理二进制不随项目分发：ONNX 推理 CLI（如
sherpa-onnx）需要用户自行安装或提供，summarize 只负责调用与集成。 - CPU-only：当前 ONNX 转写流程仅支持 CPU 运行，不涉及 GPU 加速，同时与既有 transcript provider 体系保持兼容（结果以统一的
WhisperTranscriptionResult结构返回）。 - daemon 环境继承：使用 Chrome 扩展 + daemon 时，务必在
summarize daemon install --token <TOKEN>前配置好 ONNX 环境变量，或确认 daemon 快照（env-snapshot.ts）中已包含它们，否则扩展端的 transcriber 覆盖无法命中 ONNX 命令。 - 损坏缓存处理：若历史版本遗留了不完整的缓存文件，删除对应
<model>目录后重跑即可重新下载。
综上，ONNX 转写模块以"外部 CLI + 自动下载 + 安全模板替换 + 原子缓存 + 静默回退"五个机制，为 summarize 提供了一条完全本地、CPU-only 的转写路径；结合summarize transcriber setup诊断命令，可以在几分钟内完成从安装 sherpa-onnx 到本地转写生效的完整配置。
【免费下载链接】summarizePoint at any URL/YouTube/Podcast or file. Get the gist. CLI and Chrome Extension.项目地址: https://gitcode.com/GitHub_Trending/summarize/summarize
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
