VOID-PQ5 — Setup & Fixes

Notes on getting generate_void.py working from a HuggingFace snapshot download
(as opposed to the git clone path the README assumes).

What setup.py actually does (the ~43 GB surprise)

The README advertises "13 GB download". That is the size of the compressed PQ5 codes.
Running setup.py dequantizes those codes back to full BF16, writing:

The compressed polarquant/ directory can be deleted after setup to reclaim 12 GB;
setup.py does not clean it up automatically.

Prevent setup.py from re-downloading an existing snapshot

If you downloaded the repo with hf download caiovicentino1/VOID-Netflix-HLWQ-Q5 --local-dir . rather than
git clone followed by setup.py may attempt to re-download the snapshot even though the files
are already present. The fix is to place the downloaded snapshot inside a subdirectory
named VOID-PQ5/ within your working directory before running setup.py:

your-working-dir/
└── VOID-PQ5/         <-- snapshot contents go here
    ├── polarquant/
    ├── void_code/
    ├── setup.py
    └── ...

With that layout setup.py recognises the existing files and skips the download.

The actual fixes

Fix 1 — generate_void.py: base model path not passed to inference

Problem: predict_v2v.py loads all pipeline components (VAE, tokenizer, text
encoder, scheduler) from config.video_model.model_name, which is hardcoded in
void_code/config/quadmask_cogvideox.py as "./CogVideoX-Fun-V1.5-5b-InP". That
path does not exist in a snapshot-based install. Without overriding it the script
attempts to download the full ~40 GB CogVideoX-Fun base model.

The VOID-PQ5/ directory already contains every required component after setup.py:
transformer/config.json, vae/, tokenizer/, text_encoder/, scheduler/,
model_index.json.

Fix: Add --config.video_model.model_name={model_dir} to the subprocess command
in both the --sample and the --video/--mask branches of generate_void.py.

File: generate_void.py, both cmd = [...] blocks. Added line:

f"--config.video_model.model_name={model_dir}",

Fix 2 — cogvideox_transformer3d.py: crash on empty transformer weights

Problem: The custom from_pretrained in
VOID-PQ5/void_code/videox_fun/models/cogvideox_transformer3d.py (line 790)
unconditionally indexes state_dict['patch_embed.proj.weight']. When
VOID-PQ5/transformer/ contains only config.json and no weight files, the
glob returns nothing and state_dict is {}, raising KeyError.

The transformer weights live in void_pass1.safetensors at the root of VOID-PQ5/
and are loaded separately in predict_v2v.py via transformer_path. The
from_pretrained call only needs to build the model architecture from config.json.

Fix: Guard line 790 so it is only evaluated when the base state dict is non-empty
and contains the expected key:

# Before
if model.state_dict()['patch_embed.proj.weight'].size() != state_dict['patch_embed.proj.weight'].size():

# After
if state_dict and 'patch_embed.proj.weight' in state_dict and model.state_dict()['patch_embed.proj.weight'].size() != state_dict['patch_embed.proj.weight'].size():

File: VOID-PQ5/void_code/videox_fun/models/cogvideox_transformer3d.py, line 790.

Fix 3 — Missing spiece.model in tokenizer directory

Problem: VOID-PQ5/tokenizer/ contains tokenizer_config.json,
added_tokens.json, and special_tokens_map.json, but is missing spiece.model
— the SentencePiece vocabulary file required by T5Tokenizer. The HuggingFace
snapshot for this repo does not include it. Loading the tokenizer raises:

TypeError: not a string

at sentencepiece.SentencePieceProcessor.LoadFromFile.

Fix: If you have previously downloaded any T5 model, the file will already be in
your HuggingFace cache and can be symlinked at zero extra disk cost:

ln -s ~/.cache/huggingface/hub/models--google--t5-v1_1-xxl/snapshots/<hash>/spiece.model \
      VOID-PQ5/tokenizer/spiece.model

Otherwise, download it directly from any T5 model:
bash python -c " from huggingface_hub import hf_hub_download hf_hub_download('google-t5/t5-large', 'spiece.model', local_dir='VOID-PQ5/tokenizer') "
or HF_TOKEN=xxx uvx hf download google-t5/t5-large spiece.model --local-dir VOID-PQ5/tokenizer

VRAM requirements

From the upstream README, minimum supported hardware is a 24 GB GPU (RTX 3090/4090).
The pipeline requires ~24 GB to dequantize and run inference; GPUs below that threshold
will OOM during the VAE mask encoding step. As tested on this uses just about ~21GB

Possible workarounds for constrained VRAM

1. VAE tiling — patch cogvideox_vae.py to process the video in temporal chunks
   through the encoder rather than the full sequence at once. The pipeline calls
   enable_vae_tiling() in some code paths; the custom VAE may need an equivalent.

2. Reduce resolution / frame count — shorter clips at lower resolution require
   less activation memory during VAE encode.

3. sequential_cpu_offload — change gpu_memory_mode in
   void_code/config/quadmask_cogvideox.py from "model_cpu_offload_and_qfloat8"
   to "sequential_cpu_offload". This offloads layer-by-layer and reduces peak VRAM
   for the transformer, though it does not reduce VAE activation memory.