Qwen3 VL Batch Caption

Qwen3 VL Batch Caption is the sibling of the single-image Qwen3Caption, and it exists for one very boring, very common job: labeling a folder of images for a LoRA or fine-tune dataset. If you've ever tried to caption 500 images through a single-image node one at a time, you know exactly why this one's worth having. You point it at a directory, it captions every image in it, and it writes a matching .txt next to each file. Nothing else in your workflow needs to be involved.

It's part of the same WingeD123/ComfyUI_QwenVL_PromptCaption pack as the flagship Qwen3Caption, and shares its DNA: Qwen3-VL running locally via transformers, no API, no key. The batch node just trades the image input for a folder path.

How it works

You give it image_path (a folder). It scans for common image extensions - .jpg, .jpeg, .png, .bmp, .gif, .webp - loads each one, resizes it down to max_side, and runs Qwen3-VL with the same prompt-engineering instruction the single node uses. For each image it writes a text file with the same basename (image.png → image.txt), which is exactly the filename convention the LoRA training tools expect. It keeps a result cache keyed on image content hash, so re-running a partially-done folder skips images it already processed instead of re-billing you the GPU time.

There's one detail that makes this node genuinely pleasant: it unloads all other ComfyUI models before it starts, so it won't fight your checkpoint for VRAM mid-run. And unlike the single-image node, the batch path runs with keep_model_loaded semantics handled automatically - the README notes that leaving it False doesn't hurt batch speed because the model is kept alive until the whole folder is done, then cleaned up.

The inputs that matter

• image_path - the folder to caption. Required, and if it's not a real directory you get back 0 image captioned instead of an error.
• save_path - optional. If you leave it empty, captions go next to the source images. Point it elsewhere if you want captions separated from originals (nice for keeping a clean training set).
• instruction - the most important input for dataset work. The default prompts are tuned to produce text-to-image prompts; for LoRA training you want something like "describe this image with a trigger word, comma-separated tags." The pack's example workflow literally uses it to tag with a fixed character trigger word.
• lang - 中文 or English (no bbox mode here - that's the single node's party trick).
• dtype / keep_model_loaded / max_side - same as the single node; 4bit is the default and the right call for most cards.

Output is a single summary STRING - a stats line like 42 images captioned - that's really just a progress readout. The actual captions live in the .txt files.

Install and model setup

Same as the rest of the pack: ComfyUI Manager (search "ComfyUI_QwenVL_PromptCaption") or:

cd ComfyUI/custom_nodes
git clone https://github.com/WingeD123/ComfyUI_QwenVL_PromptCaption

then restart. Dependencies are transformers>=5.2.0, accelerate, peft, bitsandbytes. The model must be placed in ComfyUI/models/text_encoders by hand - the pack never downloads one. Grab Qwen3-VL-4B-Instruct or 8B from Hugging Face, or reuse ComfyUI's own Qwen Image/Edit model file via the README's rename-to-model.safetensors trick.

Troubleshooting

The failure modes are honest and legible. Empty model_path dropdown means no model in text_encoders. A 0 image captioned result means image_path was wrong or the folder has no supported images. If the summary says images were captioned but the captions look off for training, that's the instruction, not the node - the default prompt is built for prompt inversion, and dataset captioning wants its own phrasing. And on 6-8GB cards, stick with 4bit; an 8B model in bf16 will OOM mid-folder and leave you with half a dataset and a crashed run.