publish-model

name	publish-model
description	学習済み Lightning checkpoint (.ckpt) を ONNX export → sanity check → RTF benchmark → HuggingFace upload まで連鎖実行する read-mostly skill。 export 仕様 (FP16 / EMA / emb_lang unify / opset 15) を `docs/spec/onnx-export-contract.toml` から取得し、 全 7 ランタイムでの load 可否を gate する。
argument-hint	<ckpt-path> [--output <onnx-path>] [--repo <hf-repo>] [--skip-benchmark]
disable-model-invocation	true
allowed-tools	Bash(uv run *) Bash(ls *) Bash(stat *) Bash(sha256sum *) Bash(file *) Bash(git diff *) Bash(git status *) Read Edit Grep

Model Publish Pipeline Skill

Lightning checkpoint から HuggingFace 公開までを 1 つの skill に集約。 現状 4 ステップ手動運用 (export → infer test → RTF bench → HF push) で、 工程間の引き継ぎミスが頻発する。

memory feedback_merge_caution.md に従い、 publish (HuggingFace への push) は確認後に明示実行。 デフォルトは export + sanity + bench までで停止。

引数

• $1 (必須): checkpoint パス、 例 /data/piper/output-tsukuyomi-finetune-6lang-v2/last.ckpt
• --output PATH: 出力 ONNX パス (デフォルト: checkpoint 隣に .onnx)
• --repo OWNER/REPO: HuggingFace repo 名 (デフォルト: ayousanz/<voice-key>)
• --skip-benchmark: フェーズ 4 を skip
• --apply: フェーズ 5 (HuggingFace upload) も実行

現在の状態

• ブランチ: !git rev-parse --abbrev-ref HEAD
• 引数: $ARGUMENTS

フェーズ 1: 事前検査

# Checkpoint 存在 / サイズ確認
ls -la "$1"
file "$1"  # PyTorch Lightning checkpoint であることを確認

# Contract gate (drift 検出して bump 前 fail)
uv run python scripts/check_onnx_export_contract.py 2>&1 | tail -3
uv run python scripts/check_phoneme_set_version.py 2>&1 | tail -3

フェーズ 2: ONNX export

CLAUDE.md の推奨設定 (FP16 + EMA + stochastic + emb_lang 自動統一) を使う:

CUDA_VISIBLE_DEVICES="" uv run python -m piper_train.export_onnx \
    "$CKPT_PATH" "$OUTPUT_ONNX"

出力後の verification:

# ONNX checker / shape inference
uv run python -c "import onnx; m=onnx.load('$OUTPUT_ONNX'); onnx.checker.check_model(m); onnx.shape_inference.infer_shapes(m)"

# Size 確認 (FP16 で ~50% 削減されているか)
ls -la "$OUTPUT_ONNX"

フェーズ 3: Inference sanity check

# JSONL 1 行入力で推論テスト
echo '{"phoneme_ids": [1, 2, 3, 4, 5], "speaker_id": 0}' | \
    CUDA_VISIBLE_DEVICES="" uv run python -m piper_train.infer_onnx \
        --model "$OUTPUT_ONNX" --output-dir /tmp/sanity

# 出力 wav の sanity 確認
ls -la /tmp/sanity/*.wav

無音 / クリップ / 形状不一致を catch。

フェーズ 4: RTF benchmark (optional)

uv run python tools/benchmark/run_benchmark.py \
    --model "$OUTPUT_ONNX" --warmup 5 --runs 30 \
    --output /tmp/rtf_$(basename "$OUTPUT_ONNX" .onnx).json

baseline (README.md の Benchmark 表、 Xeon E5-2650 v4 / 25 phoneme 英文 / 27ms) と比較し、 ±30% 以内なら OK、 大きい drift があれば warning。

フェーズ 5: HuggingFace upload (apply モードでのみ)

# config.json も同送 (model_resolution_vectors.json で alias を canonical 化)
uv run python scripts/upload_model_to_hf.py \
    --onnx "$OUTPUT_ONNX" \
    --config "$OUTPUT_ONNX.json" \
    --repo "$HF_REPO" \
    --license cc-by-nc-sa-4.0

upload 後、 docs/spec/model-sha256-manifest.toml に新 entry を追加するための diff 提案 (sha256sum 値含む)。

フェーズ 6: 7-runtime load 確認 (optional / 軽量検証)

各 runtime で「model を load できるか」 だけ確認 (full inference は時間がかかる):

# Python
uv run python -c "from piper import PiperVoice; v = PiperVoice.load('$OUTPUT_ONNX', '$OUTPUT_ONNX.json'); print('Python: OK')"

# Rust
(cd src/rust && cargo run --release --bin piper-plus -- --model $OUTPUT_ONNX --text 'test' --output-file /tmp/r.wav 2>&1 | tail -3)

# Go / C# / C++ / WASM はオプション

注意

• memory feedback_training_cost: 学習時間は見送り理由にならない。 benchmark で出る drift は publish 中止の理由にもならない (regression 報告)。
• memory feedback_data_asset_distribution: 新 voice 追加時は 7 manifest 同期が必要。 publish 後 check-new-runtime-asset skill を呼ぶ。
• memory feedback_merge_caution: HuggingFace push は --apply 指定時のみ。 default は dry-run。
• --skip-benchmark は CI 環境で RTF 測定が無意味な場合のみ使う (ローカル開発機推奨)。

使用例

# 通常のリリース前 publish
/publish-model /data/piper/output-tsukuyomi-finetune-6lang-v2/last.ckpt

# Benchmark をスキップして export + sanity だけ
/publish-model /data/piper/last.ckpt --skip-benchmark

# 確認後 HuggingFace へ実 publish
/publish-model /data/piper/last.ckpt --repo ayousanz/piper-plus-newvoice --apply

期待効果

• 学習完了 → 公開までの 4-step 手動運用を 1 skill 化
• ONNX export 仕様 drift (opset / FP16 / EMA / emb_lang) の commit-before-export catch
• RTF benchmark の regression early detection
• model SHA256 manifest 更新の markdown diff 自動生成
• 7-runtime load 可否の publish 前 sanity