选择参考图

Reference images are the quiet backbone of product photography: you want the new shot to feel like that other shot, even if the product is different. KSSelectReference does two jobs - it picks the best style reference from a folder by visual similarity, and it packages whatever reference you end up with into the KS_REFERENCE object that KSDesignStrategy and KSGeminiGenerate expect. If you're not using the whole pipeline, that second job alone is worth knowing about.

How it works

There's a mode dropdown with three personalities:

• ai_design - no reference at all. Returns an empty reference object with a match_score of 0. This is the "let the VLM art-direct it" path.
• background - takes the first image in reference_directory and uses it as a background reference. Score is fixed at 1.0.
• reference - the interesting one. It embeds your product image and every candidate image in the folder using an embedding model, then scores each candidate as 0.8 × visual similarity + 0.2 × tag overlap. The tags come from your product_profile JSON's style_tags and main_colors, crossed against tags stored in a reference_embeddings.json cache file it writes next to your images.

That cache is a genuinely nice touch. The first run embeds every image in the folder (slow, costs embedding calls); subsequent runs load the vectors from disk and only embed new files. Put your reference library somewhere stable and the matching gets cheap fast.

The reference mode defaults to provider openrouter, model nvidia/llama-nemotron-embed-vl-1b-v2 from the pack config - an embedding call per image, so it's metered like the rest of this pack's API nodes.

The inputs that matter

• product_image - what you're comparing against.
• product_profile - the JSON from KSAnalyzeProduct; reference mode reads its color and style tags.
• mode - the three-way switch above.
• reference_directory - the folder of reference images (png/jpg/jpeg/webp). reference and background modes read from here when nothing's wired in.
• reference_image (optional) - connect one directly and it wins; match_score is pinned to 1.0 and the reference name becomes "connected reference". This is the "I already know which one I want" path.

Outputs: reference (the KS_REFERENCE object - an image plus a path), reference_name, and match_score (the similarity score, handy if you want to gate on quality).

Installing and running it

It's part of the Kongshan Nodes pack - clone it, don't hunt for a standalone node:

cd ComfyUI/custom_nodes
git clone https://github.com/kongshan4219/ComfyUI-Kongshan-Nodes

restart ComfyUI, and set one of the API keys from .env.example (OPENROUTER_API_KEY is the one reference mode wants by default).

Gotchas

• "Reference directory not found" - the path is resolved with expanduser, so ~/refs works, but it must point at a real folder or the node raises before it does anything.
• Empty reference_directory + no reference_image + mode reference - there's nothing to match against, and the node has no fallback. You'll get an error; that's correct behavior, not a bug.
• The matching quality ceiling - a 1B embedding model is fast but not the sharpest knife. If your reference library is huge and visually similar, expect the occasional wrong pick. That's what match_score is for - you can look before you trust.

As with the rest of this pack, it's a young, opinionated piece of one author's e-commerce pipeline - 0 impressions everywhere as of now - but the embedding-cache trick and the KS_REFERENCE wrapper are solid engineering you can lift even if you never touch the rest.