Skip to content

model_manager.md

Latest commit

 

History

History
130 lines (93 loc) · 4.67 KB

model_manager.md

File metadata and controls

130 lines (93 loc) · 4.67 KB
Raw

Model Manager

tools/model_manager_v2.py downloads supported model packages into the framework's expected models/ layout. It reads package metadata from model_specs/*.json, which is the current source of truth for default download links.

When a family has a ready-to-use GGUF package, the default install should be that GGUF package. The old safetensors/converter catalog is still available as tools/model_manager_deprecated.py, but it is a legacy path for models that have not migrated to spec-backed packages.

GGUF Downloads

Ready-to-use GGUF packages are published here:

For support status and tested precision coverage, see the GGUF guide. For measured 16-bit vs Q8 speed and peak-VRAM results, see the Q8 performance report.

Dependencies

  • Python 3
  • Network access to the upstream model source

Legacy converter installs through tools/model_manager_deprecated.py may also need torch, safetensors, PyYAML, or model-specific conversion inputs.

Commands

  • list shows the available package ids
  • list --json prints a machine-readable package catalog
  • info shows the target layout, required files, and install source for one package
  • info <package> --json prints machine-readable package details
  • install downloads or converts one package into a models root
  • installed --json reports package-file presence without network access
  • sizes --json reports remote sizes plus local/remote revision status
  • uninstall removes only files declared by one package precision
  • clean-partial removes abandoned staging directories left by an interrupted process

The runtime loader catalog is also available from:

audiocpp_cli --list-loaders --json

Quick Start

List installable packages:

python3 tools/model_manager_v2.py list

Inspect one package:

python3 tools/model_manager_v2.py info qwen3_tts

Install into the default models/ directory:

python3 tools/model_manager_v2.py install qwen3_tts

Install into a custom models root:

python3 tools/model_manager_v2.py install vevo2 --models-root /path/to/models

Overwrite an existing install:

python3 tools/model_manager_v2.py install pocket_tts --overwrite

Successful installs write a small .audiocpp-package-<id>.json manifest beside the package files. It records the resolved Hugging Face commit and enables the native WebUI to report whether the local package is current. Packages installed before this metadata existed remain usable and show Version unknown until they are reinstalled once.

Clean staging directories left by a process or machine interruption:

python3 tools/model_manager_v2.py clean-partial pocket_tts --models-root models

The native WebUI can stop an active download cooperatively. Its worker checks a cancellation marker between download chunks and deletes its staging directory before reporting the job as cancelled.

Package variants may declare an identical sidecar at the same destination. The manager downloads that file once, reuses it when installing a sibling precision, and keeps it until the last package that declares it is removed. PocketTTS uses this for the public alba preset shared by its English Q8 and BF16 packages.

Install a converter-style package that needs a source file:

python3 tools/model_manager_deprecated.py info voxcpm2_audiovae
python3 tools/model_manager_deprecated.py install voxcpm2_audiovae --source-file models/VoxCPM2/audiovae.pth --models-root models --overwrite

Kroko Community defaults to the ready-to-use GGUF package:

python3 tools/model_manager_v2.py install kroko_asr_community_q8_0 --models-root models --overwrite

The original Kroko .data conversion workflow remains documented in the community model guide for users who want to build from the upstream source package themselves.

Package Notes

For shared audio.cpp GGUF packages, the v2 model manager installs the default GGUF. That is usually q8_0; FP32-only packages such as Inflect Micro v2 use original dtype instead. Other precision variants can be downloaded directly from audio-cpp/audio.cpp-gguf.

Use python3 tools/model_manager_v2.py list --json for the current package ids and defaults. The legacy loader/catalog sync notes are maintained only for the deprecated catalog path.