voice_audio_multi/tests/mira_tts/LOCAL_HEAD_VALIDATION.md

MiraTTS-local sparse output head

Validated on Windows, 2026-09-06, using the RTX 3090 for CUDA and Vulkan (Vulkan device 1).

MiraTTS now creates its CPU sparse output-head view when loading its own weights. The view shares the embedding storage without copying or converting weights. Its metadata context lives with the model weights and outlives all prefill/decode graphs. MiraTTS rebases only the compact logits readback indices; prompt and generated token IDs still use the full embedding vocabulary.

The shared qwen_causal_decode_runtime.h and .cpp are restored to upstream origin/main at a8fccb4, with no sparse-head field, slicing, or index rebasing. At that revision, GPU backends retained their full output projection. The model-local CPU AUDIOCPP_MIRA_TTS_SPARSE_HEAD=0 diagnostic remains available.

This describes the September 6 validation. The subsequent CPU/Vulkan optimization extends the local head to Vulkan as well; CUDA remains unchanged. See CPU/Vulkan optimization validation.

Output preservation

All six WAV files are byte-for-byte identical to the corresponding samples generated before this refactor: CPU, Vulkan, and CUDA, each with Q8 and BF16. The comparison uses SHA-256 on the complete WAV files.

Text: Hello, this is a native Mira TTS test. Reference: ../models_v3_test/MiraTTS-comparison/00-reference-voice.wav. Seed: 1234. Maximum tokens: 1024. Other sampling parameters: CLI defaults.

Build each backend with:

cmake --build build/windows-cpu-release --target audiocpp_cli mira_tts_warm_bench -j 12
cmake --build build/windows-vulkan-release --target audiocpp_cli mira_tts_warm_bench -j 12
cmake --build build/windows-cuda-release --target audiocpp_cli mira_tts_warm_bench -j 12

Example (substitute backend and precision; Vulkan uses --device 1):

.\build\windows-cpu-release\bin\audiocpp_cli.exe --task clon --family mira_tts --model ..\models_v3_test\MiraTTS-GGUF\mira-tts-q8.gguf --backend cpu --text "Hello, this is a native Mira TTS test." --voice-ref ..\models_v3_test\MiraTTS-comparison\00-reference-voice.wav --seed 1234 --max-tokens 1024 --out ..\outputs\MiraTTS-q8-CPU-local-head.wav --metrics

Local samples are named ../outputs/MiraTTS-{q8,bf16}-{cpu,vulkan,cuda}-local-head.wav. The previously generated files without -local-head are the comparison baseline.

Repeated CPU requests

The existing five-request offline fixture exercises the new view through repeated requests, a changed prompt, a longer request, and graph release/rebuild. Both precisions use assets/resources/b.wav with eight CPU threads:

.\build\windows-cpu-release\bin\mira_tts_warm_bench.exe --model ..\models_v3_test\MiraTTS-GGUF\mira-tts-q8.gguf --model-spec-override model_specs/mira_tts.json --backend cpu --voice-ref assets/resources/b.wav --request-file tests/mira_tts/offline_requests.json --audio-out-dir ../outputs/mira-local-head-q8-offline --summary-file ../outputs/mira-local-head-q8-offline.json --log-file ../outputs/mira-local-head-q8-offline.log

Repeat with bf16 instead of q8 for the second precision. The fixture's token budgets cap outputs at 5.12 and 15.36 seconds; these requests test lifecycle and determinism rather than full-prompt coverage.

All five requests completed for each precision. The cold, immediate-repeat, and repeat-after-long-form audio hashes match within each precision: Q8 eac900c3f8b032d9, BF16 97ef7aca310a5692.