Apply Bokeh Adapter

If you've stared at AI images long enough, you know the tell: the background blur never looks like it came out of a lens. Real bokeh has characteristic falloff, circles and cat-eyes and swirls; model-generated blur is often too uniform, too perfect. The photorealism essay in most local model docs calls this out as one of the classic tells that AI isn't photography. Apply Bokeh Adapter is the pack's attempt to fix that by giving FLUX actual defocus control, and this node is where the magic - and the downloading, and most of the errors - happens.

In the workflow Load Bokeh Adapter → Apply Bokeh Adapter → Bokeh KSampler, this is the middleman. It takes your plain FLUX model, bolts the Bokeh Diffusion adapter onto it, and hands you back a model that understands "how blurry should this be" as a parameter.

What it does to your model

The mechanism is honest attention surgery. The node digs into ComfyUI's model wrapper and hunts for the underlying FluxTransformer2DModel, then checks that it has attn_processors and a set_attn_processor method - the standard diffusers hooks. If it finds them, it loads the BokehFluxControlAdapter from HuggingFace (default atfortes/BokehDiffusion), moves it to the same device and dtype as your transformer, applies the bokeh_scale and lora_scale you set on the loader, and stashes the whole thing on the model object. From then on, when the sampler runs, custom attention processors read the bokeh level and add defocus-specific key/value projections to the attention math. It's a focused LoRA-plus-embedding injection, not a full model fork.

Two things worth knowing before you hit run:

1. This is where the download happens. The loader is just a config node; Apply Bokeh Adapter is the one that actually fetches weights from HuggingFace. Your first run needs internet and HF access, and it'll take a moment. After that the adapter is cached in memory and reused.
2. It is loud. The node sets logging to DEBUG and prints giant ========== separator blocks describing every step. Expect your console to look like a ransom note. That's by design - it's also your best troubleshooting tool, since this pack has essentially no community to ask.

Inputs and output

Only two inputs: model (your FLUX MODEL from a standard loader) and adapter (the BOKEH_ADAPTER from Load Bokeh Adapter). One output: model, the same model object with the adapter attached. Wire that straight into Bokeh KSampler - not the normal KSampler, which won't know what to do with it.

Installing the pack

ComfyUI Manager, search BokehDiffusionComfyUI, or:

cd ComfyUI/custom_nodes
git clone https://github.com/jrabek/BokehDiffusionComfyUI

Restart, then make sure the heavy dependencies are present - diffusers>=0.32.2, transformers>=4.53.0, huggingface_hub, opencv-python, torch 2.0+:

pip install diffusers transformers huggingface_hub opencv-python

Common issues

• "Could not find FLUX transformer in model" - the number one failure, and it's blunt. The search looks specifically for a FluxTransformer2DModel instance. That means: it's not a FLUX.1 model (this won't touch Flux 2 Klein), or your checkpoint format doesn't expose the diffusers class it's scanning for. Stick to the standard FLUX.1-dev checkpoint for this pack.
• "Model transformer does not have attn_processors" - same family of error; the model you loaded isn't the plain FLUX architecture this adapter expects.
• First run hangs on "Loading adapter from..." - that's the HF download. Check your internet and that atfortes/BokehDiffusion is reachable.
• Device/dtype warnings - the code tries to match your transformer and logs a warning if it can't. Usually non-fatal; generation will just be slower or slightly off.

It's fiddly, it's research-ware, and you'll be reading debug logs more than forum posts - but when it works, you get a genuine defocus dial on FLUX that vanilla sampling can't give you.