Skip to content

model_specs: correct declarations that disagree with the code - #372

Closed
CryptVenture wants to merge 1 commit into
0xShug0:mainfrom
CryptVenture:pr/model-spec-corrections
Closed

model_specs: correct declarations that disagree with the code#372
CryptVenture wants to merge 1 commit into
0xShug0:mainfrom
CryptVenture:pr/model-spec-corrections

Conversation

@CryptVenture

Copy link
Copy Markdown
Contributor

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

  • 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_budgetdefault. 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 PR 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 declaration actively lied.

Options the engine reads and no spec declared

  • minimax_music3: the five options that arrived 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 are now 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

Reasons are recorded in the spec 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 it 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.

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.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 --test-dir build/macos-metal-tests --output-on-failure -R model_spec_system_test

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.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants