VOSR 2.0 Model Loader:
VOSR2ModelLoader, displayed in ComfyUI as “VOSR 2.0 Model Loader,” prepares the complete VOSR 2.0 model bundle for image-upscaling workflows. VOSR 2.0 uses a one-step, 1.4-billion-parameter LightningDiT model together with a matched Qwen-Image 2D VAE and DINOv2-L vision encoder. In practical terms, these components provide the main image-processing model, the system that converts images into and out of its working representation, and the system that extracts visual features. They are designed to work together and cannot be independently replaced with other VAEs or vision encoders. The node handles loading this matched set and integrates it with ComfyUI’s model-loading and offloading system. For the confirmed VOSR2 bundle, missing files are downloaded from the CSWRY/VOSR Hugging Face repository on first use; once all required files are present, the loader does not need to access the network. This node prepares the models rather than performing image upscaling itself.
VOSR 2.0 Model Loader Input Parameters:
model
Selects the VOSR 2.0 bundle to load from a subfolder of ComfyUI/models/vosr2/. This is a required COMBO selection, with VOSR2 as the default and the one confirmed bundle identified in the supplied code. The available options are generated by the loader rather than defined as a fixed list in the node schema; the provided context does not show the complete option-discovery logic. Your selection determines which matched LightningDiT, Qwen-Image 2D VAE, DINOv2-L encoder, and model configuration are loaded together. This is a bundle selection, not an arbitrary file-path field or a choice of separate model components. Missing files for the confirmed bundle can be downloaded automatically from CSWRY/VOSR. There is no numerical minimum or maximum.
dtype
Controls the computation precision used by the LightningDiT model and DINOv2-L vision encoder. This is a required COMBO selection with exactly three options: default, fp16, and bf16; the default is default. The default option lets the loader resolve the computation type for the active device, although the exact selection rules are not included in the supplied code. The fp16 option requests 16-bit floating-point computation, while bf16 requests the alternative bfloat16 format, which has a wider numerical range than fp16 but depends on suitable hardware and software support. Precision choices can affect memory use, performance, and numerical behavior, so neither explicit option should be assumed to be faster or better on every system. Regardless of this setting, the Qwen-Image 2D VAE always runs in fp32. There is no numerical minimum or maximum.
VOSR 2.0 Model Loader Output Parameters:
model
Returns a custom VOSR2_MODEL object containing the loaded, matched VOSR 2.0 bundle. This object packages the LightningDiT model, Qwen-Image 2D VAE, and DINOv2-L vision encoder through ComfyUI model patchers, together with the bundle’s configuration. The patchers integrate the components with ComfyUI’s loading and offloading mechanisms. You can connect this output to a compatible VOSR 2.0 processing node, such as the extension’s VOSR2Upscale node, to make the bundle available for image processing. The output is not an image, a standalone VAE, or a standard ComfyUI diffusion-model connection; it represents the complete VOSR-specific model set.
VOSR 2.0 Model Loader Usage Tips:
- Start with
modelset toVOSR2anddtypeset todefault. These are the node’s declared defaults and provide a sensible starting point before testing explicit precision settings. - Allow extra time and provide internet access on the first run. Missing files for the confirmed bundle are fetched from
CSWRY/VOSR; subsequent loads do not access the network once all required files are in place. - Keep the bundle together under
ComfyUI/models/vosr2/VOSR2/. Its expected contents includeargs.json,checkpoints/ema_model.safetensors,Qwen-Image-vae-2d/config.json,Qwen-Image-vae-2d/diffusion_pytorch_model.safetensors, anddinov2_vitl14.safetensors. The loader also supports DiT weights in the alternative locations described in its source, but the checkpoint layout is the documented standard. - Do not substitute a VAE from your shared
models/vae/folder or a vision encoder frommodels/clip_vision/. VOSR 2.0 depends on its specific matched components, including the VAE’s latent representation and the DINOv2-L encoder’s features. - Test
bf16only when your device and software support it, or testfp16when that format is appropriate for your system. Compare compatibility, memory use, processing time, and resulting images in the downstream upscale workflow rather than assuming one format is universally preferable. - Remember that changing
dtypedoes not reduce the VAE’s precision: it remains infp32. If you encounter memory limits, closing other GPU-heavy applications may help, but this loader exposes no controls for image size, tiling, or batch size. - Connect the
modeloutput to a compatible VOSR 2.0 node. Loading the bundle alone does not upscale an image or produce a preview.
VOSR 2.0 Model Loader Common Errors and Solutions:
VOSR2 model bundle not found: '…'
- Explanation: This message is explicitly raised when the selected bundle directory does not exist after the loader has attempted to ensure the necessary files are available.
- Solution: Check that the selected bundle is located directly under
ComfyUI/models/vosr2/. For the confirmed bundle, selectVOSR2and verify that the first-run download can complete. A folder elsewhere on your computer is not accepted as an arbitrary model path.
VOSR2 bundle … is missing its Qwen-Image 2D VAE (…/config.json). The VAE's latent space is tied to this DiT and cannot be substituted.
- Explanation: This message is explicitly raised when the bundle lacks
Qwen-Image-vae-2d/config.json. The VAE is a required part of the matched bundle, not an optional accessory. - Solution: Restore the bundle’s matching
Qwen-Image-vae-2ddirectory, including bothconfig.jsonanddiffusion_pytorch_model.safetensors. For the confirmed bundle, check network access and rerun the loader so it can fetch missing files. Do not replace this VAE with a different model.
VOSR2 bundle … is missing its DINOv2-L encoder (…).
- Explanation: This message is explicitly raised when the expected
dinov2_vitl14.safetensorsfile is absent from the bundle directory. - Solution: Verify that
dinov2_vitl14.safetensorsis inside the selected bundle, alongsideargs.json, rather than in a shared vision-model directory. For the confirmed bundle, allow the loader to complete its missing-file download and preparation process.
Download failure or connection error during first-time loading
- Explanation: The exact download error text is not shown in the supplied source. Network, repository-access, or local storage problems can prevent the loader from obtaining missing bundle files.
- Solution: Confirm that you can access
CSWRY/VOSRon Hugging Face, check your connection and available disk space, and make sure ComfyUI can write tomodels/vosr2/. Retry once the underlying issue is resolved. A complete local bundle does not require a network connection for loading.
Missing or unreadable args.json or DiT weights
- Explanation: The loader reads
args.jsonand resolves the LightningDiT checkpoint before building the complete model. Missing, incomplete, or damaged files can stop loading, although the exact exception messages for these cases are not included in the provided context. - Solution: Check that the selected bundle contains a valid
args.jsonand the expected DiT weights, normallycheckpoints/ema_model.safetensors. If a download was interrupted, restore the affected files from the confirmed repository. Keep the configuration and weights from the same bundle together.
CUDA out of memory or another device-memory allocation error
- Explanation: This is a possible runtime error rather than a message explicitly defined in the supplied loader excerpt. The complete bundle contains several models, and loading or using them can exceed your device’s available memory.
- Solution: Close other GPU-intensive applications and release unused models or workflows before retrying. Start with
dtypeset todefault; consider an explicit 16-bit option only if your device supports it. Remember that the VAE remains infp32and that the loader itself has no image-size or tiling controls.
Unsupported dtype or an operation not supported for the selected precision
- Explanation: The exact wording depends on your device and PyTorch environment. Explicitly selecting
fp16orbf16can encounter compatibility limitations on some hardware or operations. - Solution: Switch
dtypeback todefaultand retry. If you need an explicit precision, confirm support for that format on your device and in your installed PyTorch version before selecting it.
Incompatible connection type: VOSR2_MODEL
- Explanation: This describes a possible workflow connection problem, not a literal error string shown in the source. The output uses the custom
VOSR2_MODELtype, so it cannot replace a standard model, image, VAE, or vision-encoder connection. - Solution: Connect the output to a node that explicitly accepts
VOSR2_MODEL, such as the extension’s VOSR2Upscale node. Keep the bundle intact rather than trying to route its internal components into unrelated nodes.
