LC Vision Loader 🔬:
LCVisionLoader loads a vision-capable GGUF language model together with its matching image projector, allowing LC Vision workflows to interpret images and generate text about them. It finds compatible local model pairs or downloads a listed curated pair on first use. ComfyUI can reuse the loaded model across queued runs when the node’s settings stay the same, avoiding repeated loading and making captioning and other image-understanding workflows more convenient.
LC Vision Loader 🔬 Input Parameters:
model_name
Selects the vision model to load. The menu lists GGUF models that have a sibling mmproj GGUF file in the same folder under a registered LLM model path; available Download: entries fetch their model and projector on first use. The model and projector must fit each other, so keeping each pair in its own folder helps prevent mismatches. Options depend on the models found on your system and the curated download list; there is no fixed numeric range or stated default.
device
Chooses where inference runs. Options are auto (default), cuda, and cpu. auto selects CUDA when PyTorch reports it is available and otherwise selects CPU; cpu forces CPU execution regardless of the GPU-layer setting. CUDA can accelerate a compatible installation, while CPU execution avoids using GPU memory for model layers.
n_gpu_layers
Controls how many model layers are offloaded to the GPU when CPU mode is not selected. The default and minimum are -1, which requests offloading every layer; 0 uses CPU-only layers, and positive values offload that many layers while leaving the rest in system RAM. The maximum is 999. Reducing this value can help when GPU memory is limited, though it may slow inference.
n_ctx
Sets the context window: the token space available for the image-related input, your instructions, and the model’s answer together. The default is 8192; the dropdown options come from N_CTX_CHOICES and are not fully listed in the provided source, although the node guidance describes 4096, 8192, 16384, and 32768. Smaller contexts use less reserved VRAM: the node estimates about 0.6 GB at 4096, 1.1 GB at 8192, 2.3 GB at 16384, and 4.5 GB at 32768. Saved workflows can also supply other numeric values, but the minimum accepted value is 512; no maximum is specified by validation.
n_batch
Sets the token capacity per decode call and also sets the underlying micro-batch capacity to the same value. The default is 2048, the minimum is 64, the maximum is 32768, and the step is 64. Raise it if a large input or multiple reference images exceed the batch capacity; lower it to reduce memory use. The node guidance notes that 1024 can save about 0.6 GB of VRAM on an 8 GB card and is suitable for captioning one or two images.
image_min_tokens
Sets the vision handler’s minimum image-token setting, affecting how much token capacity it requests for image interpretation. The default is 1024, the minimum is -1, and the maximum is 16384; -1 uses the model default. The node guidance recommends at least 1024 for reliable grounding with Qwen-VL models. For Gemma 4 models, loading caps this setting at 280.
image_max_tokens
Sets an upper limit on the vision handler’s image tokens. The default and minimum are -1, meaning no additional cap beyond n_batch; the maximum is 16384. A lower cap can constrain image-token use, while a higher one allows more room within the other configured limits. For Gemma 4 models, a value of -1 or any value above 280 is capped at 280 during loading.
batch_max_tokens
Sets the vision chat handler’s per-batch limit for image embedding, separately from n_batch. The default is 1024, the minimum is 64, and the maximum is 16384. If you use multiple large reference images, raise this alongside n_batch so the image-embedding stage has sufficient capacity.
verbose
Controls whether llama.cpp prints its internal loading and inference diagnostics to the console. Options are False (default) and True. Leave it off for cleaner logs, or turn it on when you need more detail to troubleshoot loading or performance.
keep_model_loaded
Controls whether the loaded model is intended to remain available between LC Vision operations. Options are True (default) and False. Keeping it loaded makes reruns faster but retains its memory allocation; turning it off allows LC Vision nodes to unload it after answering, freeing GPU memory for an image-generation model at the cost of reloading it later.
LC Vision Loader 🔬 Output Parameters:
vision_model
An LC_VISION_MODEL handle representing the loaded vision model and its image-processing chat handler. It also carries information such as the model name, detected architecture, context size, loading settings, and whether the model should remain loaded. Connect this handle to compatible LC Vision nodes so they can use the selected model; it is not a generated image or caption by itself.
LC Vision Loader 🔬 Usage Tips:
- Put each local model GGUF and its matching
mmprojGGUF in the same folder under a registeredLLMmodel path. Separate folders are especially helpful when you keep different model sizes. - Start with
deviceset toauto,n_gpu_layersat-1, andn_ctxat8192. If VRAM is tight, tryn_ctxat4096for a single-image caption, reducen_batchto1024, or setkeep_model_loadedtoFalsewhen another model needs the GPU. - For several reference images or longer answers, consider
n_ctxvalues of16384or32768. Raisen_batchandbatch_max_tokensif large image inputs exceed their respective capacities, while allowing for greater memory use. - Choose
cpuor setn_gpu_layersto0when you need CPU-only execution. SetverbosetoTruetemporarily if you need diagnostic messages. - A
Download:selection downloads the model and projector on first use. Allow time and disk space for both files before expecting the first run to finish.
LC Vision Loader 🔬 Common Errors and Solutions:
n_ctx `{value}` is too small (512 at least).
- Explanation: The context value is below the node’s accepted minimum.
- Solution: Choose a context of at least
512; the documented4096or8192settings are practical starting points.
n_ctx '`{value}`' is not a number.
- Explanation: A saved workflow supplied a context value the node cannot convert to a number.
- Solution: Select a numeric dropdown value or correct the saved value to a whole number.
LC Vision model '`{name}`' not found under models/LLM/GGUF.
- Explanation: The selected name is no longer an available local model or curated download entry.
- Solution: Refresh or reselect the model. For a local model, place its GGUF and matching
mmprojGGUF together under a registeredLLMmodel path.
[LC Vision] '`{name}`' not found under models/LLM/GGUF. Place the model .gguf and its mmproj .gguf in the same folder.
- Explanation: The selected local model pair could not be found when loading began.
- Solution: Check that neither file was moved or renamed, that both are in the same folder, and that the folder is within a registered
LLMpath; then select the model again.
[LC Vision] llama_cpp is not installed, or the installed copy cannot load or lacks vision support (...)
- Explanation: ComfyUI cannot import the required llama.cpp Python package in the Python environment it runs.
- Solution: Run this pack’s
install.pywith ComfyUI’s own Python, or follow the pack’s README. Check the Python executable printed in the error rather than installing into an unrelated system Python.
[LC Vision] llama_cpp is installed but cannot load. Missing '`{package}`'. Run: ...
- Explanation: A dependency needed by the installed
llama_cpppackage is missing. - Solution: Run the installation command shown in the error using ComfyUI’s Python, then restart ComfyUI.
[LC Vision] Installed llama_cpp has neither Qwen3VLChatHandler nor Qwen25VLChatHandler -- it doesn't have vision support compiled in.
- Explanation: The installed package does not provide the vision handler this loader requires.
- Solution: Run this pack’s
install.pywith ComfyUI’s Python and restart ComfyUI.
[LC Vision] Your llama_cpp (...) is the original llama-cpp-python build. It has an older Qwen-VL handler that cannot load Qwen3-VL models.
- Explanation: The installed build has an incompatible older vision handler.
- Solution: Update the pack through ComfyUI-Manager, or run its
install.pywith ComfyUI’s Python, then restart ComfyUI.
[LC Vision] This vision projector does not fit this model.
- Explanation: The model and selected
mmprojprojector report different model widths, so they cannot be used together. - Solution: Use the projector supplied for that exact model size. Keeping each downloaded pair in its own folder helps the loader select the right one.
[LC Vision] This llama_cpp has no Gemma 4 support. Update the pack (install.py) and restart ComfyUI.
- Explanation: A Gemma 4 model was selected, but the installed package lacks its chat handler.
- Solution: Update the pack, run its
install.pywith ComfyUI’s Python, and restart ComfyUI.
[LC Vision] Download of '`{filename}`' from `{repo_id}` did not produce the expected file.
- Explanation: A curated first-use download finished without creating the required model or projector file.
- Solution: Check your connection, available disk space, and write access to the
LLMmodel folder, then retry.
[LC Vision] '`{filename}`' from `{repo_id}` doesn't match its known checksum, so it was deleted. Try the download again.
- Explanation: The downloaded file failed its integrity check and was removed so it would not be loaded.
- Solution: Retry the download; if it happens repeatedly, check your connection and available disk space.
llama-cpp's CUDA plugin cannot load (...), so LC Vision runs on CPU.
- Explanation: On Linux, the installed llama.cpp CUDA plugin could not find or load the CUDA libraries it needs. This is printed as a diagnostic rather than raised as a loader error.
- Solution: If CPU speed is acceptable, you can continue. Otherwise, install the CUDA 12 runtime libraries or follow the source-build guidance printed in the diagnostic.
