# ComfyUI-MiniMax-H3-FastPath

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow.svg)](https://buymeacoffee.com/capitan01r)

Euler-only middle-block caching for native MiniMax H3 models in ComfyUI.

This custom node keeps the beginning and end of the MiniMax H3 transformer exact. Between them, it can reuse a previously measured middle-block residual when the current prefix features remain close enough to the cached call.

The cache is an approximation. Calls that do not pass its sampler, identity, topology, schedule, reuse-limit, and feature-change checks run the full transformer path.

<a href="images/node.png">
  <img src="images/node.png" alt="Loader1" width="960" height="720">
</a>

## Installation

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/capitan01R/ComfyUI-MiniMax-H3-FastPath.git
```

Restart ComfyUI after installing or updating.

No extra Python packages are required beyond a working ComfyUI installation with native MiniMax H3 support.

## Included Node

| Node | Output | Purpose |
|---|---|---|
| **MiniMax H3 FastPath Euler Middle Cache** | `MODEL` | Runs an exact transformer prefix and suffix, with guarded residual reuse across a configurable middle block range. |

## Usage

Place **MiniMax H3 FastPath Euler Middle Cache** between the native MiniMax H3 diffusion model loader and a stock Euler sampler:

```text
Load Diffusion Model -> MiniMax H3 FastPath Euler Middle Cache -> KSampler
```

Use your normal MiniMax H3 conditioning, latent, scheduler, guider, and VAE decode path.

For a standalone model or a model whose weights remain static during sampling, set `require_fastpath_schedule` to `false`. When it is `true`, approximation is allowed only when the model call contains the expected per-call FastPath LoRA-strength signature. If that signature is absent, the node safely runs the exact path.

The defaults are a practical starting point: `8` exact prefix blocks, `8` exact suffix blocks, a `0.12` reuse threshold, one consecutive reuse, and GPU cache storage.

## Controls

| Parameter | Default | Meaning |
|---|---:|---|
| `model` | — | Native MiniMax H3 diffusion model to clone and patch. |
| `enabled` | `true` | Enables the middle-block cache. When disabled, the cloned model is returned without the cache patch. |
| `prefix_blocks` | `8` | Number of exact transformer blocks executed before the cached middle range on every model call. |
| `suffix_blocks` | `8` | Number of exact transformer blocks executed after the cached middle range on every model call. |
| `reuse_threshold` | `0.12` | Maximum relative change in the sampled prefix feature for cached residual reuse. Lower values reject more candidates; higher values allow more approximation. |
| `max_consecutive_reuses` | `1` | Maximum accepted reuses before a full middle-block refresh is forced. A value of `1` alternates an accepted reuse with a full refresh while the signature remains stable. |
| `cache_device` | `gpu` | Stores the residual on GPU for speed or on CPU to reduce VRAM use. CPU reuse transfers the full residual back to the model device. |
| `require_fastpath_schedule` | `true` | Requires the matching per-call LoRA-strength signature before approximation is allowed. Set to `false` for standalone static-model use. |
| `strict_branch_identity` | `true` | Uses the exact path when ComfyUI does not provide enough information to separate conditioning branches safely. |
| `suppress_candidate_prefetch` | `true` | Prevents dynamic middle-block weight prefetch on likely reuse calls so skipped weights are not loaded unnecessarily. |
| `verbose` | `false` | Logs the sampler decision, cached range, and end-of-run cache statistics. |

## How It Works

On a full eligible call, the node:

1. Runs the configured prefix blocks exactly.
2. Samples a small probe from the prefix output and saves the middle-range input.
3. Runs every middle block exactly.
4. Stores the middle residual: `middle output - middle input`.
5. Runs the configured suffix blocks exactly.

On the next eligible call for the same branch and model-strength signature, the prefix still runs exactly. The node compares the new prefix probe with the saved probe. If the relative change is within `reuse_threshold`, it adds the cached residual to the current hidden state, skips the middle blocks, and continues through the exact suffix.

A full middle pass refreshes the residual when the feature gate rejects reuse, the consecutive-reuse limit is reached, the model-strength signature changes, or the cached tensor topology no longer matches. Topology checks include shape, dtype, device, token segmentation, time-embedding shape, and rotary-embedding shape.

Cache state is separated by conditioning-branch identity and cleared at the beginning and end of each sampling run. Cloned models receive independent runtime state.

## Behavior and Limits

- Residual reuse is enabled only for the stock Euler sampler. Other samplers use the full exact block path.
- Multi-GPU model calls use the full exact path.
- If strict branch identity is enabled and branch labels are unavailable, the full exact path is used.
- If cache allocation runs out of memory, caching is disabled for the rest of that sampling run and execution continues through the full block path.
- Existing per-block replacements are preserved on full middle-block calls. The node refuses installation when a whole block-loop replacement is already active.
- GPU cache storage is fastest. One residual uses approximately `sequence length × 5376 × bytes per element` for each active branch/call identity.
- Cached middle-block reuse is approximate. Disable the node when exact numerical equivalence is required.