MiniCPM-V-4 GGUF Loader

You want a vision-language model inside ComfyUI - something that actually looks at an image and tells you what's in it, not the CLIP-style flavor text you feed a checkpoint. This is the node that gets you there. It loads MiniCPM-V-4, a compact open VLM from OpenBMB, as a GGUF quant, and it does most of the annoying work for you: picks a quant, downloads the weights from Hugging Face, and hands you a ready-to-use handle for the Vision Infer node. No API keys, no Python scripting, no separate text-generation server to babysit.

The catch is in the name: it's a GGUF loader, which means the whole thing runs through llama-cpp-python - llama.cpp's Python binding. That's the same runtime behind local LLM apps, and it's where your install will either sail through or dump you in dependency hell.

What it actually does

Under the hood it's simple. The node ships with a dropdown of official quants from the openbmb/MiniCPM-V-4-gguf repo, sized 2.08 GB (Q4_0) up to 3.83 GB (Q8_0). On first load it calls Hugging Face to download two files: the quant you picked plus mmproj-model-f16.gguf, the vision projector that actually lets the model see images - without it you'd get a text-only chatbot. Then it spins up a Llama instance with a LLaVA-style chat handler and caches it, keyed by quant + processing mode, so switching quants mid-session reloads the model.

One thing the README gets wrong, so you don't hunt for files: it claims models land in ComfyUI/models/llama. They actually go to ComfyUI/models/LLM/GGUF. Same place city96-style GGUF packs drop stuff, honestly - no harm done, just don't go looking in the wrong folder.

The inputs that matter

There are exactly two, and one of them you can basically ignore:

• model - the quant dropdown. For a model this small the whole quality-ladder debate is overthinking it. Q4_K_M is the README's default, but we're talking about a 2 GB file; if you have 8 GB VRAM, take Q5_K_M or even Q8_0 and enjoy it. Q8 is essentially fp16 at half the size, and at this size it still fits comfortably.
• processing_mode - Auto, GPU, or CPU. Auto picks GPU if it finds CUDA. GPU offloads all layers; CPU runs on RAM. Pick GPU if you have the VRAM and want it fast.

Everything else - context length (pinned to 8192), GPU layers, thread count - is hardcoded in the node. The README advertises knobs for n_ctx, n_gpu_layers, threads, and a seed. They don't exist in the shipped code. Don't go looking for them.

The output is a single MINICPM_HANDLE, which wires straight into MiniCPM-V-4 Vision Infer. That's the only thing this handle plugs into.

Installing it

From ComfyUI Manager, search for "MiniCPM" and install the pack. Or the old-fashioned way:

cd ComfyUI/custom_nodes
git clone https://github.com/mamorett/ComfyUI_minicpmv4

Then restart ComfyUI. The pack's requirements.txt pulls llama-cpp-python, huggingface-hub, numpy, and pillow, and it points pip at abetlen's prebuilt CUDA 12.1 wheel index with --only-binary :all: - so no source compilation on Windows/Linux if you're on CUDA 12.1. If your CUDA differs, or you're on a Mac (Metal works with default wheels), you may need to build it yourself, which means a CUDA toolchain. This is the single most common failure point for the whole pack.

When it breaks

Two failure modes to know about.

First, if llama-cpp-python fails to import, the loader degrades: instead of the quant dropdown you get a node with one text input full of an error like libcuda.so.1: cannot open shared object file. That's by design - the node detects the missing dependency and shows you the reason. Fix the Python install and restart; the real UI comes back.

Second, "it loads but my GPU isn't doing anything." That's almost always a CPU-only wheel from pip install llama-cpp-python without the CUDA extras. Reinstall via the pack's wheel index (or build with the CUDA toolchain), and watch the console - the loader prints which mode it chose.