デスクトップ CLI チュートリアル

English | 日本語

vokra-cli は umbrella コマンドラインツール（FR-TL-01, FR-TL-02）。同じ native runtime 上の 5 つの subcommand — run / convert / bench / f0 / 実験的な npu-bakeoff — を、手書きの引数パーサ・外部依存ゼロ（NFR-DS-02）で提供する。本ページは deep dive。5 分コースは getting-started.md を参照。

1. ビルド

cargo build --release

target/release/vokra-cli が生成される。各 subcommand のフルオプションは vokra-cli <subcommand> --help で確認する。

2. `run` — task 自動選択の推論

run は GGUF をロードし、モデルの vokra.model.arch metadata から task を選ぶ（Whisper → ASR、Silero VAD → VAD、piper-plus → TTS）。task を自分で指定する必要はない:

# ASR — 音声入力、テキスト出力
./target/release/vokra-cli run --model whisper-base.gguf --input speech.wav

# TTS — テキスト入力、WAV 出力
./target/release/vokra-cli run --model voice.gguf \
  --text "Hello from Vokra." --output hello.wav

ASR には decode 制御がある: --beam-size / --word-timestamps / --length-penalty / --no-repeat-ngram / --language。TTS には --voice / --style / --length-scale:

./target/release/vokra-cli run --model whisper-base.gguf --input speech.wav \
  --beam-size 5 --word-timestamps

MeloTTSの事前計算feature入力

公開中のMeloTTS 5 GGUFには音響モデル全体が入っているが、言語別の G2P/tokenizer/BERT frontendは含まれない。そのためraw --textではなく、 versioned VKRMELO1 v1 feature bundleを入力する:

./target/release/vokra-cli run --model melotts-japanese.gguf \
  --input hello.vmf --backend metal --output hello.wav

固定64-byte little-endian headerは言語variant、speaker ID、sequence長、必須BERT 幅を保持する。payloadは同じ長さのphoneme/tone/language u32列、その後に position-major [sequence, 1024] BERTと[sequence, 768] JA-BERT f32 matrixを格納する。言語不一致、不正shape、余分・不足byte、非finite feature、未登録 speaker IDはすべて明示エラーになる。raw textも明示エラーであり、推測した frontendや暗黙CPU fallbackには渡さない。

upstream frontendが出力したlittle-endian arrayは、runtime依存を追加せずbundle 化できる:

uv run --project tools/parity python tools/parity/melotts_pack_features.py \
  --variant japanese --speaker-id 0 \
  --phoneme-ids phoneme_ids.u32 --tones tones.u32 \
  --language-ids language_ids.u32 \
  --bert bert_position_major.f32 \
  --ja-bert ja_bert_position_major.f32 --output hello.vmf

CT-Punc のtoken/idペア入力

CT-Puncはtokenizeを推測しない。token文字列とモデルに渡す正確なvocabulary IDを、1つのversioned UTF-8 TSVに対で記述する:

vokra-ct-punc-tsv-v1
101	we
202	build
303	世界

各recordは<u32 id><TAB><escaped token>。tokenにはliteral Unicode、または \\ / \t / \n / \r / \u{HEX} escapeを使用できる。空record、余分な TSV列、不正escape、vocabulary範囲外IDはエラーになる。単一record streamにすることでtoken列とID列の長さ不一致を構造的に排除する。

./target/release/vokra-cli run --model ct-punc.gguf \
  --tokens tokens.tsv --output restored.txt

--outputなしではct_punc: <text>として表示する。指定時のfile内容は診断 prefixや暗黙newlineを含まない、復元後の正確なUTF-8 textになる。

Mimi encode/decodeとportable code container

Mimiは方向を明示する。Rustのnested arrayのdebug表示を交換形式にはしない:

./target/release/vokra-cli run --model mimi.gguf --codec-mode encode \
  --input speech-24k.wav --output speech.vmc
./target/release/vokra-cli run --model mimi.gguf --codec-mode decode \
  --input speech.vmc --output reconstructed.wav

speech.vmcはVKRMCODE version 1。固定little-endian headerにmono channel、 sample rate、milli-Hz単位のframe rate、frame数、元PCM sample数、codebook数・ size、feature幅、GGUF effective codebook tableのSHA-256を保持する。payloadは time-major [frame, codebook] 順のunsigned 32-bit code。decodeは異なるmodel hash/topology、余分・不足byte、範囲外code、frames * model_hopと一致しない PCM長を拒否する。encodeも正のframe-hop整数倍だけを受け付け、暗黙のresample・ padding・trimは行わない。

3. `convert` — checkpoint → GGUF（オフライン）

runtime は GGUF のみをロードする。ONNX / safetensors はここでオフライン処理する。--model はソース種別を指定し、--quantize は出力時に K-quant する:

./target/release/vokra-cli convert --model whisper \
  --input whisper-base/model.safetensors --output whisper-base.gguf

# K-quant で小型化
./target/release/vokra-cli convert --model whisper \
  --input whisper-base/model.safetensors --output whisper-base.q4_k.gguf \
  --quantize q4_k

piper-plus voice には config.json も要る。モデルによっては --tokenizer や --adapter-config の side-car を取る:

./target/release/vokra-cli convert --model piper-plus \
  --input voice.onnx --config voice.config.json --output voice.gguf

4. `bench` — RTF / TTFA / jitter と regression gate

bench は real-time factor・time-to-first-audio・jitter・p50/p95/p99 レイテンシを報告する。--baseline を付けると regression gate になり、記録した baseline に対し 5% を超える相対劣化で非ゼロ終了する（NFR-PF-13）。

# 計測
./target/release/vokra-cli bench --model whisper-base.gguf --input speech.wav \
  --iters 20 --warmup 3 --format json

# 記録済み baseline に対して gate
./target/release/vokra-cli bench --model whisper-base.gguf --input speech.wav \
  --baseline baseline.json

5. `f0` — checkpoint 不要のピッチ抽出

f0 は WAV に対して YIN または PyIN を実行する。run --task ではなく独立 subcommand なのは、run が --model GGUF を必須とする一方、この 2 つの extractor は重みを一切持たないため — checkpoint も license class も docs/license-audit.md §3.1 の行も無い。呼び出し側が渡せる --model が存在しない。

# YIN（デフォルト）
./target/release/vokra-cli f0 --input speech.wav

# PyIN、話声域に限定
./target/release/vokra-cli f0 --input speech.wav --algo pyin \
  --fmin 65 --fmax 400

出力行は tab 区切りで、neural F0 モデルに対して run が出す形と同一。 extractor を切り替えてもパース側は変更不要:

time_sec<TAB>hz<TAB>voiced<TAB>confidence

無声フレームは hz=0.000, voiced=false。PyIN は実際のフレーム単位の voiced probability を confidence に報告する。YIN は確率出力を持たないため、 confidence は voiced と同じ明示的な 1.0 / 0.0 のままとなる。

サンプルレートは固定ではない: 両 op とも WAV が持つレートから lag 探索範囲を導出するので、暗黙のリサンプルは発生しない。同じ family の neural メンバ — RMVPE / FCPE / CREPE — は checkpoint を要するため run 側に残る。

6. `npu-bakeoff` — 同一セッションの delegate gate（実験的）

実験的な npu-bakeoff は、Whisper encoder の CPU 経路と Core ML または QNN delegate を同一セッションで比較する。model load、delegate compilation、 log-mel 抽出はレイテンシ計測から除外し、数値 parity または指定 speedup 閾値に失敗した場合はエラーになる。CPU への fallback は行わない。QNN の encoder 全体実行は現在明示的に未対応なので、delegate artifact と platform を確認してから実行する。--model には Vokra Whisper GGUF を指定し、その隣に CoreML sidecar を事前生成する。sidecar manifest が GGUF の正確な bytes を認証する:

# 出力ディレクトリは存在し、空である必要がある。macOS の offline tool。
mkdir -p whisper-base.gguf.coreml
bash tools/coreml/build_whisper_encoder.sh \
  whisper-base.gguf whisper-base.gguf.coreml

現在の runtime contract は whisper-base.gguf.coreml/manifest.txt と、コンパイル済みの whisper-encoder.mlmodelc/ tree であり、単独の <GGUF>.coreml.json ファイルではない。manifest は元 GGUF と compiled tree の SHA-256、Whisper の feature 名/shape、macOS14 deployment target、CoreML Tools version、算術精度を結び付ける。不足・古い binding は CoreML load 前に失敗し、CPU へ置き換えない。入力 WAV は 16 kHz mono PCM（int16 または float32）とし、リサンプルは行わない。

cargo build --release -p vokra-cli --features coreml   # macOS
./target/release/vokra-cli npu-bakeoff \
  --model whisper-base.gguf --input speech.wav \
  --delegate coreml --warmup 2 --iters 10 --atol 0.01 --min-speedup 2.0

delegate 経路は feature gate 下にあり、--features coreml なしでビルドした binary は明示エラーになり CPU へ fallback しない。qnn も同じ command surface で parse されるが、encoder 全体の QNN 実行は現在明示的な unsupported error になる。これは認証済みの一つの Whisper artifact に対する、Vokra の first-party CPU-vs-delegate 測定 gate であり、一般的な end-to-end ASR benchmark、独立した upstream/PyTorch parity 結果、全モデルの Apple Neural Engine qualification ではない。現在のオプションは vokra-cli npu-bakeoff --help で確認する。

7. バックエンド選択は明示的（`FR-EX-08`）

--backend で計算バックエンドを選ぶ。Vokra は silent fallback をしない: GPU バックエンドが cover しない op、不在の device は明示エラーであり、CPU への無言の切り替えはしない。

cargo build --release -p vokra-cli --features metal   # macOS
./target/release/vokra-cli bench --model whisper-large-v3.gguf \
  --input speech30s.wav --backend metal

CPU を意図的に選ぶには --backend cpu を使う — それはあなたが下す決定であり、Vokra が裏で下す決定ではない。

8. トラブルシューティング

症状	原因 / 対処
`error: model file has no vokra.model.arch metadata`	GGUF が非 Vokra ツール（例 `llama.cpp`）製。`vokra-cli convert` で再生成する。
`error: backend does not implement op X`	GPU バックエンドがその op を cover していない（`FR-EX-08`）。`--backend cpu` で再試行するか model/op を報告する。
`bench` が regression メッセージで非ゼロ終了	`--baseline` gate が発火（5% 超の劣化）。変更を調査するか、意図的に baseline を更新する。
`error: research flag required for CC-BY-NC weight`	非商用 weight が compliance gate で拒否された。research 用途は明示 opt-in が必要。

Next steps

Server（4 互換 API） — CLI ではなく HTTP エンドポイントが欲しい場合の別バイナリ vokra-server
バックエンドの追加
Migration Guide（ONNX Runtime / whisper.cpp / sherpa-onnx から）

Keeping this page current

最終確認日: 2026-10-08 — crates/vokra-cli/src/ の run / convert / bench / f0 / npu-bakeoff 引数パーサに対して確認。

更新責任: CLI フラグを追加・改名した PR が、同一 PR で本ページと英語版を更新する。本ページの全 vokra-cli 呼び出しは doc-examples CI job が実パーサに対して照合するため、古いフラグは CI を落とす。
review cadence: 四半期 Go/No-go review（NFR-MT-05）。
フラグ surface の再取得:

grep -oE '"--[a-z0-9-]+"' crates/vokra-cli/src/run.rs crates/vokra-cli/src/convert.rs crates/vokra-cli/src/bench.rs crates/vokra-cli/src/f0.rs crates/vokra-cli/src/npu_bakeoff.rs

Navigation Menu

Repository navigation

cli.ja.md

cli.ja.md

デスクトップ CLI チュートリアル

1. ビルド

2. `run` — task 自動選択の推論

MeloTTSの事前計算feature入力

CT-Punc のtoken/idペア入力

Mimi encode/decodeとportable code container

3. `convert` — checkpoint → GGUF（オフライン）

4. `bench` — RTF / TTFA / jitter と regression gate

5. `f0` — checkpoint 不要のピッチ抽出

6. `npu-bakeoff` — 同一セッションの delegate gate（実験的）

7. バックエンド選択は明示的（`FR-EX-08`）

8. トラブルシューティング

Next steps

Keeping this page current

FilesExpand file tree

cli.ja.md

Latest commit

History

cli.ja.md

File metadata and controls

デスクトップ CLI チュートリアル

1. ビルド

2. run — task 自動選択の推論

MeloTTSの事前計算feature入力

CT-Punc のtoken/idペア入力

Mimi encode/decodeとportable code container

3. convert — checkpoint → GGUF（オフライン）

4. bench — RTF / TTFA / jitter と regression gate

5. f0 — checkpoint 不要のピッチ抽出

6. npu-bakeoff — 同一セッションの delegate gate（実験的）

7. バックエンド選択は明示的（FR-EX-08）

8. トラブルシューティング

Next steps

Keeping this page current

2. `run` — task 自動選択の推論

3. `convert` — checkpoint → GGUF（オフライン）

4. `bench` — RTF / TTFA / jitter と regression gate

5. `f0` — checkpoint 不要のピッチ抽出

6. `npu-bakeoff` — 同一セッションの delegate gate（実験的）

7. バックエンド選択は明示的（`FR-EX-08`）