Technical Documentation

This document provides technical details about the implementation of ComfyUI-QwenImageLoraLoader, focusing on architectural decisions and design patterns.

Guidance Resolution Strategy

Problem Statement

The QwenImageTransformer2DModel.forward method has the following signature:

def forward(
    self,
    x,
    timestep,
    context,
    attention_mask=None,
    guidance=None,
    ref_latents=None,
    transformer_options={},
    **kwargs
)

Note that guidance is defined as a positional argument (not **kwargs).

The Issue

When calling the model from the wrapper layer (ComfyQwenImageWrapper), if guidance is passed as a keyword argument while ComfyUI's internal mechanisms also pass it positionally, Python raises:

TypeError: NunchakuQwenImageTransformer2DModel._forward() got multiple values for argument 'guidance'

This occurs because:

ComfyUI's WrapperExecutor may pass guidance positionally through the forward chain
The wrapper was passing guidance as a keyword argument
Python detects the conflict and raises an error

Solution

We intentionally pass guidance as a positional argument to match the exact signature of QwenImageTransformer2DModel.forward:

return self.model(
    x,
    timestep,
    context,
    None,                  # attention_mask
    guidance_value,        # guidance (positional)
    None,                  # ref_latents
    transformer_options_cleaned,
    **final_kwargs,
)

This ensures:

✅ guidance is always passed in exactly one way (positional)
✅ No conflicts with ComfyUI's dynamic argument merging
✅ Compatibility with WrapperExecutor and patcher_extension
✅ Python's calling convention is strictly followed

Positional vs Keyword Argument Policy

Rule: When wrapping ComfyUI model methods, always match the original method's signature exactly, using positional arguments for parameters that are defined positionally (not in **kwargs).

Rationale:

ComfyUI's patching system (WrapperExecutor, patcher_extension) may inject arguments in specific positions
Mixing positional and keyword arguments for the same parameter causes Python-level errors
Following the original signature ensures compatibility with all ComfyUI internal mechanisms

Current Implementation Details

attention_mask and ref_latents:

Currently passed as None because they are not used by the current Qwen Image pipelines in ComfyUI
attention_mask is not utilized in the current implementation
ref_latents is only used in image-to-image / ControlNet scenarios, which are handled through other mechanisms

Future Compatibility:

If upstream ComfyUI changes to pass attention_mask via transformer_options, our implementation will need to be updated
If ref_latents becomes a standard parameter for LoRA / Control implementations, we should extract it from transformer_options or **kwargs and pass it positionally

Execution Flow

ComfyUI Sampler
    ↓
ComfyQwenImageWrapper.forward()
    ↓
ComfyQwenImageWrapper._execute_model()
    ↓
NunchakuQwenImageTransformer2DModel.forward()  [positional: guidance]
    ↓
WrapperExecutor.execute()
    ↓
NunchakuQwenImageTransformer2DModel._forward()  [positional: guidance]

Key Points:

guidance normalization happens at the wrapper layer (_execute_model)
All downstream calls use positional arguments
No keyword argument conflicts can occur

Issue #32: TypeError: NunchakuQwenImageTransformer2DModel._forward() got multiple values for argument 'guidance'
- Status: Fixed in v2.0.5
- Root Cause: Keyword argument conflict with positional argument
- Solution: Changed to positional argument passing

3.7 KiB Raw Permalink Blame History