model_specs: correct declarations that disagree with the code - #372
Closed
CryptVenture wants to merge 1 commit into
Closed
model_specs: correct declarations that disagree with the code#372CryptVenture wants to merge 1 commit into
CryptVenture wants to merge 1 commit into
Conversation
Sixteen specs described a request surface the engine does not implement, or
failed to describe one it does. Each change below was checked against the C++
that reads the option.
Declarations that were wrong
- voxcpm1: num_inference_steps 50 -> 10, max_tokens 1024 -> 4096, min_tokens
0 -> 2, retry_badcase_max_times 2 -> 3, per voxcpm1/types.h:13-19.
- fish_audio, outetts: text_chunk_mode default "word_budget" -> "default".
The shared parser in framework/text/chunking.cpp throws on "word_budget",
so the documented default was un-passable. Both move from the
text_chunk_mode_full preset to explicit values, because "default" is not
currently in that preset; a separate change corrects the preset itself.
- midashenglm_gen: seed min -1 -> 0. parse_u32_option rejects any leading
minus, so a spec-legal -1 was a runtime error, and the "-1 selects a random
seed" claim went with it.
- dramabox: five descriptions claimed their default came from config.json.
dramabox/assets.cpp reads config.json for architecture only.
- irodori_tts: text_chunk_mode values widened to the four the shared parser
accepts.
Declarations for options nothing reads
- granite5asr: language. The session hard-codes "en" and never reads it.
- firered_audio: session option firered_audio.helper_graph_arena_mb. Only
the fireredtts3-prefixed key exists, and FireRedAudio validates session
options strictly, so this one actively lied.
Options the engine reads and no spec declared
- minimax_music3: the five options added with the performance pack --
flow_uncond_interval, flow_uncond_warmup, ensemble_takes,
ensemble_prefix_frames, flow_chunk_hop_frames -- plus the
minimax_music3.pipeline_overlap session option. ensemble_takes returns
several named outputs and had no way to be requested.
- minimax_h3: first_block_cache_start_percent and _end_percent, the primary
window whose _sigma override was already declared.
- sense_asr: "vad" added to the audio_chunk_mode enum; the session
implements it.
- parakeet_tdt: language. Every other strict ASR family declares it, and it
is a field of the OpenAI-compatible transcription contract, so a per-model
rejection of it is a protocol violation. Documented as accepted and
ignored, since Parakeet reads only keep_language_tags.
- qwen3_forced_aligner, miocodec: options.session filled in with the seven
and six prefixed session options their sessions actually read.
Required flags that lie
- heartmula: lyrics and tags marked required. heartmula/session.cpp:437-442
throws when either is empty, but the specs said optional, so a client had
no way to know before the engine did.
Deliberately not changed, with reasons recorded in the descriptions:
fish_audio and outetts require reference_text only when reference audio is
present, and the schema's `required` is a plain bool with no conditional form,
so marking them required would break plain TTS with a built-in voice.
mms_forced_aligner keeps return_timestamps: it is never read, but the family
validates strictly and the CLI's --words-out injects the key, so deleting it
would break forced alignment from the command line.
The WebUI bundle is regenerated because catalog.ts inlines model_specs at
frontend build time, so a spec edit does not reach users until it is rebuilt.
Validation:
python3 tools/check_loader_catalog_sync.py # ok, in sync
cd webui/native && npm run build
ctest -R model_spec_system_test # passes
Backend tested: Metal (Apple M4 Max).
Known limitations: the corrected declarations were verified by reading the
option-parsing code, not by running each of the sixteen families -- most have
no package installed here. No spec gained schema_version: the five that
declare options without it would need dependencies and load blocks they do not
have, and switching them to full v1 validation is not verifiable without
running every affected model.
This was referenced Aug 31, 2026
This was referenced Sep 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sixteen model specs described a request surface the engine does not implement, or failed to describe one it does. Every change here was checked against the C++ that reads the option.
Declarations that were wrong
num_inference_steps50 → 10,max_tokens1024 → 4096,min_tokens0 → 2,retry_badcase_max_times2 → 3, pervoxcpm1/types.h:13-19.text_chunk_modedefaultword_budget→default. The shared parser inframework/text/chunking.cppthrows onword_budget, so the documented default was un-passable. Both move from thetext_chunk_mode_fullpreset to explicit values becausedefaultis not currently in that preset; a separate PR corrects the preset itself.seedmin -1 → 0.parse_u32_optionrejects any leading minus, so a spec-legal -1 was a runtime error, and the "-1 selects a random seed" claim went with it.config.json.dramabox/assets.cppreadsconfig.jsonfor architecture only.text_chunk_modevalues widened to the four the shared parser accepts.Declarations for options nothing reads
language. The session hard-codes"en"and never reads it.firered_audio.helper_graph_arena_mb. Only thefireredtts3-prefixed key exists, and FireRedAudio validates session options strictly, so this declaration actively lied.Options the engine reads and no spec declared
flow_uncond_interval,flow_uncond_warmup,ensemble_takes,ensemble_prefix_frames,flow_chunk_hop_frames— plus theminimax_music3.pipeline_overlapsession option.ensemble_takesreturns several named outputs and had no way to be requested.first_block_cache_start_percentand_end_percent, the primary window whose_sigmaoverride was already declared.vadadded to theaudio_chunk_modeenum; the session implements it.language. Every other strict ASR family declares it, and it is a field of the OpenAI-compatible transcription contract, so a per-model rejection of it is a protocol violation. Documented as accepted and ignored, since Parakeet reads onlykeep_language_tags.options.sessionfilled in with the seven and six prefixed session options their sessions actually read.Required flags that lie
lyricsandtagsare now marked required.heartmula/session.cpp:437-442throws when either is empty, but the specs said optional, so a client had no way to know before the engine did.Deliberately not changed
Reasons are recorded in the spec descriptions.
fish_audioandoutettsrequirereference_textonly when reference audio is present, and the schema'srequiredis a plain bool with no conditional form, so marking it required would break plain TTS with a built-in voice.mms_forced_alignerkeepsreturn_timestamps: it is never read, but the family validates strictly and the CLI's--words-outinjects the key, so deleting it would break forced alignment from the command line.Scope
Declarations only — no engine code changes, so no output, performance or memory change. What does change is which requests are accepted: options the engine implements become requestable, and options nothing reads stop being advertised.
The WebUI bundle is regenerated in this PR because
catalog.tsinlinesmodel_specsat frontend build time, so a spec edit does not reach users until it is rebuilt.Validation
Full suite green (39/39). Backend tested: Metal, Apple M4 Max.
Known limitations
The corrected declarations were verified by reading the option-parsing code, not by running each of the sixteen families — most have no package installed on this machine. No spec gained
schema_version: the five that declare options without it would need dependencies and load blocks they do not have, and switching them to full v1 validation is not verifiable without running every affected model.