Skip to content

Model downloads

A model that is not on disk is fetched before it loads, as a step of its own, so the Web UI can show bytes, speed and time left and offer Stop. The pieces are plain functions and small value objects in downloads/, composed by ensure_downloaded.

The pipeline

  1. Plan. A planner returns DownloadTarget values (repo, revision, allow and ignore patterns, optional local_dir) for the files the load will read. downloads/plans.py composes the platform planners (backends/mac/download_plan.py, backends/cuda/download_plan.py) with the sources of models built on first use and the SeedVR2 tier files. A plan is () when nothing is to be fetched (a local folder, a built folder) and None when it cannot be made now (offline with no cached file index); callers skip the ensure step for None. Planners are light: they import neither torch, diffusers nor mflux, because a plan must exist without loading a backend. They mirror the patterns of the code that will load the model (mflux's weight definitions, mlx-lm's DEFAULT_ALLOW_PATTERNS, diffusers' pipeline files), so the downloaded files are exactly the loader's.
  2. Presence. target_present_offline decides without the network whether a target is fully on disk. A present part is skipped.
  3. Dry run. check_target calls snapshot_download(..., dry_run=True) and returns the files and bytes still missing. It returns None when the Hub cannot be reached, and raises RuntimeError when the Hub refuses (gated or missing repo, server error). A refusal is one line from downloads/hub_access.py, shared by the worker, the CUDA planner, job failures and both CLIs. Offline, the part is unchecked and the load proceeds with the loader's own download.
  4. Child process. run_in_child runs python -m zvisiongenerator.downloads.worker in its own session, so a terminal Ctrl+C does not reach it, and reads its ZIV-DOWNLOAD {json} progress lines on a thread. The two aggregate byte bars ("Downloading bytes" as wire, "Reconstructing" as written) overlap and are never summed. The child exits when its stdin closes, so a hard server kill leaves no orphan.
  5. Flights. DownloadFlights keeps one flight per destination (DownloadTarget.key). The first caller owns the download; others wait and mirror its progress with shared: true. When a flight ends stopped or unchecked, a waiter re-checks and claims it, so a stale result is never read, and finished files stay.
  6. Ensure. ensure_downloaded(targets, flights=, report=, cancelled=) walks the parts in order and returns READY, UNCHECKED (a part could not be checked; the load proceeds as before), STOPPED or DETACHED (this caller stopped waiting for someone else's download). A refused dry run or a failed download raises RuntimeError naming the repo. Every collaborator (present, check, run, clock) is a parameter, which is how the tests run without a network.

Import the planners from zvisiongenerator.downloads.plans; downloads/__init__.py re-exports downloads/declaration.py but not plans.py, because plans.py imports readers that import the declaration.

Declared pins

A built-in model's pins and file lists are declared in its entry of utils/model_metadata.yaml, and downloads/declaration.py reads them. model_targets(model_id, platform_key) returns the model's (role, target) pairs: its own downloads for the platform, in file order, then, for a video model, the companions of its family overlaid by its version. That order is load-bearing: planners and job parts rely on it. A target without a role is the model itself; the other roles name what a loader asks for (transformer, text_encoder, latent_upsampler, lora, voice, design, ...), and role_targets picks them. A target marked files_from: loader declares no file list: the loader's own planner lists the files. The declaration says what exists; the planners decide which targets a run needs.

Job parts and plans

web/job_downloads.py plans what one Web UI job downloads as JobDownloadPart values (label, model_id, role, targets): the generation or upscale model, the prompt enhancer, the background removal models and a SeedVR2 tier. The Models page builds its rows with the same builders, so a row and a job size a download the same way.

POST /api/generate/plan and POST /api/upscale/plan tell the Web UI what a job would download before it is queued. They run the submit route's parse half, so the plan and the job cannot disagree, and a plan is made from the fields alone: uploads are stand-ins that are neither read nor saved (see Plan without files). The summary drops every part whose missing files are already on their way, so the user is not asked twice about one download. A submit plans the job once and hands the model's part to the runner, so the worker does not plan it again.

Special plans

  • Audio. audio_plan(preset) builds targets from the metadata alone, so it never returns None. Targets with role voice come last and only a take that follows a recording or a saved voice needs them; targets with role design are left out, and audio_design_plan returns them for the one job that designs a voice. The backends only read the cache, so both download steps call downloads.require_checked after ensure_downloaded: a file still missing because the Hub could not be reached ends the job with a message about the connection, and any other missing file raises before the model loads.
  • Background removal. matte_plan() returns the two targets of the matte entry (birefnet first). A transparent job downloads them before its model loads; the Models page shows one row for both.
  • MiniMax H3. backends/__init__.h3_download_plan dispatches by platform. CUDA lists the main repository with allow and ignore patterns, the first shards of the NF4 text encoder, the turbo LoRA and, with upscale, the latent upscaler. macOS lists every file literally, so the presence check cannot pass on an empty or partial folder. Each platform then builds a stored copy on first use (<name>@q4, h3@mlx-te4); deleting the model removes its copy.
  • Local H3 folders on macOS. h3_video.local_int8_transformer decides what a local -m folder contributes, and the plan and the loader both follow it, so they agree. A folder in the port's INT8 layout is loaded as is; one with no transformer weights falls back to the pinned INT8 transformer; one with any other transformer raises ValueError, because the stock transformer must not stand in for it. ziv-model model --model-type h3 turns such a checkpoint into a converted folder.
  • Stored copies. utils.stored_quant.file_identities records each source file's identity in a copy's manifest (ziv-quant.json), and a copy whose manifest differs from the current sources is rebuilt. A Hugging Face cache blob is named by its content hash, so name and size are enough; any other file also records mtime_ns and inode, because a replaced file can keep its name and size and hashing tens of gigabytes was rejected.

Stop, detach and memory

Stopping an owning job or lane item terminates the child (killing it after grace_secs) and deletes its *.incomplete files. Finished files are kept and resume is per file. A job that only waits on another download is detached instead: the job ends and the download continues. Stop has to end the process: raising from the progress sink does not stop hf_xet's transfer, and an xet download does not grow its *.incomplete file as it goes, so progress comes only from the sink.

The child's memory is bounded by hf_xet's download buffer, which it sizes from host RAM, not by file size. child_env() sets HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE=512mb unless the parent sets it, which about halves the peak at the same speed, so a download can run beside a generation.

Events

Web jobs publish model_downloading (mode, role, model, repo, part, parts, bytes_done, bytes_total, bytes_per_sec, download_eta_secs, shared) at most once a second per job, plus each owned part's final report. It replaces the previous model_downloading in record.history, so a client that connects later replays only the latest. A job stopped during a download ends with job_cancelled carrying download: "stopped" or "detached". The job card turns the event into a row inside its load step and ends it at model_loading.

The Models page and the lane

web/model_download_plan.py plans a Models-page row (row_plan) and judges offline whether it needs a download (row_download_needed, which also drives the Download button). DownloadLane (web/download_lane.py) queues items and runs them one at a time with the same ensure_downloaded and the server's shared DownloadFlights. The lane never touches the job executor, so generation jobs are admitted while it downloads. The routes are listed by the running server's /docs; an unknown row is a 404, a Hub refusal a 424 and an unreachable Hub a 503.

Delete and used repos. web/model_delete.freed_repo_ids is the one answer to what deleting a built-in model frees: the repos it declares, minus its own model repo, minus every repo another built-in model declares while that model is on disk. Deleting moss while moss-sft is built frees only the Turbo LoRA repo. The Models page sizes the row from the same set, so the size shown is what a delete frees. used_repo_ids is the union of the declared repos of every model on the platform plus the custom enhancer repo; the cache view marks only those as used. A delete is refused with a 409 while a download touches its repo.

LoRA downloads

The lane also runs items of kind lora: the Discover LoRAs Download button and the Models page's Import a LoRA from Hugging Face. They start from their own routes, appear in the lane's list and are stopped like any item. web/lora_download.py builds an item:

  • Staged in a folder of its own. The target downloads into <loras>/.download-<name>, so the file never touches the Hugging Face cache and two files of one repo never share a flight. The folder sits beside the LoRA files so the final move is a rename on one drive. web/lora_staging.py holds a lock inside it until cleanup, and LoraInstaller.sweep_staging removes only the folders it can lock, so a killed server's leftovers go while another UI's running download stays.
  • Anonymous unless typed by the user. A curated entry or a Discover file sets DownloadTarget.anonymous: the user's token is never sent, so a stale token cannot make a public file fail. Import a LoRA keeps the token, so a private repository the user can open still imports.
  • Finalize, then cleanup. DownloadLane.submit(..., finalize=, cleanup=) runs finalize once every target is on disk and cleanup whatever the outcome. finalize checks the file's size and SHA-256 (utils/lora_install.install_staged), renames it into place with one os.replace that refuses an existing file, and records its source (see LoRA sources). A failed check, a stop or an error leaves nothing in the LoRA folder.
  • One decision at a time. LoraInstaller.start decides the name and submits under one lock. The same entry or file pressed twice returns the running item; a file already there counts as installed; a different file under a curated name is refused with a 409 before any bytes move; an open file whose name is taken gets -2, -3.
  • Queue order. The lane runs one item at a time, so a LoRA waits behind a running model download.

Version bumps

The planners depend on how the loaders choose files. After changing a pinned MLX LTX pack or LTX_COMMIT, re-list the pack's files in utils/model_metadata.yaml as described under LTX on macOS. Changing a pin rebuilds what is made from it (MOSS-Image, Ideogram 4 Instant, stored copies).

After changing mflux, mlx-lm, diffusers, huggingface_hub or hf-xet, run the pattern pins: uv run pytest tests/downloads/test_mac_download_plan.py on macOS (compares the planners with mflux's get_download_patterns() and mlx-lm's DEFAULT_ALLOW_PATTERNS) and tests/downloads/test_cuda_download_plan.py on Linux (pins the diffusers and CUDA video patterns against recorded file lists). Then repeat the hand test with a small public repo: start a download from the Models page and check that progress moves, cancel mid-file and check that no *.incomplete remains and finished files stay, then start a job on the same model while the lane downloads it and check that Stop on the job leaves the download running. A renamed progress bar shows as progress stuck at 0 until each part completes, never as a failed download; a pattern that drifts costs only the progress display, because the backend downloads the missing files during the load.