Download nodes/ComfyUI-H3-Multishot/h3_remote_encode.py from Russ1on/MiniMax-H3-Multishot-Workflow: direct link, hf CLI and curl.
- Browser
- Download file 17.2 kB
-
https://huggingface.co/Russ1on/MiniMax-H3-Multishot-Workflow/resolve/main/nodes/ComfyUI-H3-Multishot/h3_remote_encode.py
- Command line
-
hf download hf://Russ1on/MiniMax-H3-Multishot-Workflow/nodes/ComfyUI-H3-Multishot/h3_remote_encode.py
-
curl -L -o h3_remote_encode.py https://huggingface.co/Russ1on/MiniMax-H3-Multishot-Workflow/resolve/main/nodes/ComfyUI-H3-Multishot/h3_remote_encode.py
17.2 kB
| """Remote text encode for MiniMax-H3: keep the 18 GB Qwen3-VL off the render card. | |
| The TE is needed for seconds per shot and is dead weight the rest of the run - | |
| and on 16-24 GB cards it cannot sit beside the DiT at all. This moves the encode | |
| to another box (any ComfyUI instance with this pack loaded) over HTTP. Any | |
| spare PC with a mid-size GPU works; avoid hosting it on a machine whose card | |
| is already busy rendering - the encoder wants to stay resident. | |
| WHY A CLIP PROXY AND NOT AN ENCODE NODE: the multishot samplers encode | |
| internally - clip.tokenize(prompt, minimax_ref_items=...) then | |
| clip.encode_from_tokens_scheduled(tokens) - per shot, including the vision path | |
| for reference images. A node that returned CONDITIONING could not feed that. | |
| So H3RemoteClip returns an object that answers exactly those calls by POSTing | |
| the raw inputs (text + image tensors) to the server, which tokenizes and | |
| encodes with a real, resident CLIP and ships the conds back. | |
| THE SWITCH: this is opt-in twice over. Nothing imports or calls any of this | |
| unless the H3RemoteClip node is in the graph, and the shipped workflow wires it | |
| through H3AnySwitch (lazy A/B) with the boolean OFF - lazy means the remote | |
| branch does not execute when off AND the local loader does not execute when on. | |
| Flip one boolean to move the TE off the card. | |
| SERVER: importing this module registers POST /h3multishot/encode on whatever | |
| ComfyUI instance loads the pack. Loading a clip happens only when a request | |
| names one, and the loaded clip stays resident keyed by name - residency is the | |
| entire point. The route reuses the pack's own H3ClipLoaderAny so GGUF+mmproj | |
| pairing behaves identically to a local load. | |
| HONESTY: fails loud. No silent local fallback - a fallback would quietly load | |
| the 18 GB the whole feature exists to avoid. If the remote is down, the error | |
| says so and says where the switch is. | |
| """ | |
| import hashlib | |
| import io | |
| import json | |
| import os | |
| import urllib.error | |
| import urllib.request | |
| _PACK_VER = "2.7.2" | |
| _ROUTE = "/h3multishot/encode" | |
| # --------------------------------------------------------------------------- | |
| # Codec: arbitrary python structure <-> (JSON skeleton, safetensors blob). | |
| # Generic on purpose - tokenize() output and ref-item schemas can change | |
| # upstream without breaking this, because the codec never assumes a schema. | |
| # --------------------------------------------------------------------------- | |
| def _pack_obj(obj): | |
| import torch | |
| tensors = {} | |
| def walk(o): | |
| if torch.is_tensor(o): | |
| k = "t%d" % len(tensors) | |
| tensors[k] = o.detach().to("cpu").contiguous() | |
| return {"__t__": k} | |
| if isinstance(o, dict): | |
| return {"__d__": [[walk(k), walk(v)] for k, v in o.items()]} | |
| if isinstance(o, list): | |
| return {"__l__": [walk(x) for x in o]} | |
| if isinstance(o, tuple): | |
| return {"__u__": [walk(x) for x in o]} | |
| if isinstance(o, (str, int, float, bool)) or o is None: | |
| return {"__v__": o} | |
| raise TypeError("h3 remote encode cannot serialise %r" % type(o)) | |
| return walk(obj), tensors | |
| def _unpack_obj(skel, tensors): | |
| def walk(s): | |
| if "__t__" in s: | |
| return tensors[s["__t__"]] | |
| if "__d__" in s: | |
| return {walk(k): walk(v) for k, v in s["__d__"]} | |
| if "__l__" in s: | |
| return [walk(x) for x in s["__l__"]] | |
| if "__u__" in s: | |
| return tuple(walk(x) for x in s["__u__"]) | |
| return s["__v__"] | |
| return walk(skel) | |
| def _to_bytes(skel, tensors): | |
| from safetensors.torch import save | |
| meta = {"skeleton": json.dumps(skel), "pack": _PACK_VER} | |
| if not tensors: # safetensors refuses an empty dict | |
| import torch | |
| tensors = {"__empty__": torch.zeros(1)} | |
| return save(tensors, metadata=meta) | |
| def _from_bytes(blob): | |
| from safetensors.torch import load | |
| tensors = load(blob) | |
| # safe_open only takes paths; the header is length-prefixed JSON, so read | |
| # the metadata straight out of the bytes instead of a temp file. | |
| hlen = int.from_bytes(blob[:8], "little") | |
| header = json.loads(blob[8:8 + hlen]) | |
| meta = header.get("__metadata__") or {} | |
| skel = json.loads(meta["skeleton"]) | |
| return _unpack_obj(skel, tensors) | |
| # --------------------------------------------------------------------------- | |
| # Server side: registers on import, does nothing until called. | |
| # --------------------------------------------------------------------------- | |
| _SERVER_CLIPS = {} # (clip_name, clip_type) -> loaded CLIP, resident | |
| def _server_load_clip(clip_name, clip_type): | |
| key = (clip_name, clip_type) | |
| if key in _SERVER_CLIPS: | |
| return _SERVER_CLIPS[key] | |
| from .h3_multishot_utils import H3ClipLoaderAny | |
| print("[H3RemoteEncode] loading %r type=%r (stays resident for future " | |
| "requests)" % (clip_name, clip_type), flush=True) | |
| clip = H3ClipLoaderAny().load(clip_name, clip_type)[0] | |
| _SERVER_CLIPS[key] = clip | |
| return clip | |
| def _register_route(): | |
| try: | |
| from server import PromptServer | |
| from aiohttp import web | |
| except Exception: | |
| return # CLI / headless import - no server to register on | |
| ps = getattr(PromptServer, "instance", None) | |
| if ps is None: | |
| return | |
| async def h3_remote_encode(request): # noqa: ANN001 | |
| import asyncio | |
| body = await request.read() | |
| try: | |
| req = _from_bytes(body) | |
| clip_name = req["clip_name"] | |
| clip_type = req.get("clip_type", "minimax") | |
| calls = req["calls"] # list of tokenize-kwarg dicts | |
| def run(): | |
| clip = _server_load_clip(clip_name, clip_type) | |
| out = [] | |
| for kw in calls: | |
| prompt = kw.pop("__prompt__") | |
| tokens = clip.tokenize(prompt, **kw) | |
| out.append(clip.encode_from_tokens_scheduled(tokens)) | |
| return out | |
| # comfy is not re-entrant under its execution lock; encode requests | |
| # run in a worker thread so a render on THIS box is not blocked. | |
| conds = await asyncio.get_event_loop().run_in_executor(None, run) | |
| skel, tensors = _pack_obj({"conds": conds, "pack": _PACK_VER}) | |
| return web.Response(body=_to_bytes(skel, tensors), | |
| content_type="application/octet-stream") | |
| except Exception as e: # noqa: BLE001 | |
| import traceback | |
| traceback.print_exc() | |
| return web.Response(status=500, text="%s: %s" % (type(e).__name__, e)) | |
| print("[H3RemoteEncode] serving POST %s (clips load on first request)" | |
| % _ROUTE, flush=True) | |
| _register_route() | |
| # --------------------------------------------------------------------------- | |
| # Client side: the CLIP proxy. | |
| # --------------------------------------------------------------------------- | |
| class _NoOpTEModel: | |
| def to(self, *a, **k): | |
| return self | |
| class _RemoteTEPatcher: | |
| """Just enough .patcher for the samplers' TE-offload housekeeping. | |
| The samplers probe clip.patcher.load_device to decide whether the text | |
| encoder shares the DiT's card and must be offloaded between shots. A | |
| remote encoder occupies no local memory at all, which is exactly the | |
| "separate device, nothing to reclaim" branch - load_device "remote" | |
| routes it there, and the no-op model absorbs any offload .to() calls. | |
| """ | |
| load_device = "remote" | |
| offload_device = "remote" | |
| model = _NoOpTEModel() | |
| class _RemoteClipProxy: | |
| """Answers the two calls the H3 samplers make, remotely. | |
| tokenize() only CAPTURES its arguments - tokenisation needs the model's own | |
| tokenizer, which lives on the server. encode_from_tokens_scheduled() ships | |
| the captured call and returns real conds. Anything else the caller tries to | |
| use fails loudly with the method name, because a proxy that half-works is | |
| worse than one that says what it cannot do. | |
| """ | |
| def __init__(self, endpoint, clip_name, clip_type, timeout, cache_dir): | |
| self._endpoint = endpoint.rstrip("/") | |
| self._clip_name = clip_name | |
| self._clip_type = clip_type | |
| self._timeout = timeout | |
| self._cache_dir = cache_dir | |
| self.patcher = _RemoteTEPatcher() | |
| # -- the supported surface ------------------------------------------------ | |
| def tokenize(self, prompt, **kwargs): | |
| call = dict(kwargs) | |
| call["__prompt__"] = prompt | |
| return {"__h3_remote_call__": call} | |
| def encode_from_tokens_scheduled(self, tokens): | |
| call = tokens.get("__h3_remote_call__") if isinstance(tokens, dict) \ | |
| else None | |
| if call is None: | |
| raise RuntimeError( | |
| "H3RemoteClip received tokens it did not produce. The remote " | |
| "proxy only works with nodes that call clip.tokenize() and " | |
| "clip.encode_from_tokens_scheduled() as a pair - the H3 " | |
| "multishot samplers do. For anything else, switch back to the " | |
| "local CLIP loader.") | |
| return self._post([call])[0] | |
| # -- transport ------------------------------------------------------------ | |
| def _post(self, calls): | |
| skel, tensors = _pack_obj({"clip_name": self._clip_name, | |
| "clip_type": self._clip_type, | |
| "calls": calls}) | |
| body = _to_bytes(skel, tensors) | |
| # Key on CANONICAL content, never on the serialized blob: safetensors' | |
| # header is rust-HashMap-ordered, so the same request serializes to | |
| # different bytes call-to-call and blob-hashing misses every time | |
| # (measured: two cache files for one identical prompt). | |
| h = hashlib.sha256() | |
| h.update((self._endpoint + "|" + self._clip_name + "|" | |
| + self._clip_type).encode()) | |
| h.update(json.dumps(skel, sort_keys=True).encode()) | |
| for name in sorted(tensors): | |
| h.update(name.encode()) | |
| h.update(tensors[name].numpy().tobytes()) | |
| key = h.hexdigest()[:16] | |
| cpath = os.path.join(self._cache_dir, "remote_%s.bin" % key) | |
| if os.path.isfile(cpath): | |
| with open(cpath, "rb") as f: | |
| print("[H3RemoteClip] cond cache HIT (%s) - no network, " | |
| "no encode." % os.path.basename(cpath), flush=True) | |
| return _from_bytes(f.read())["conds"] | |
| url = self._endpoint + _ROUTE | |
| req = urllib.request.Request( | |
| url, data=body, method="POST", | |
| headers={"Content-Type": "application/octet-stream"}) | |
| try: | |
| with urllib.request.urlopen(req, timeout=self._timeout) as r: | |
| blob = r.read() | |
| except urllib.error.HTTPError as e: | |
| detail = "" | |
| try: | |
| detail = e.read().decode("utf-8", "ignore")[:400] | |
| except Exception: # noqa: BLE001 | |
| pass | |
| raise RuntimeError( | |
| "Remote encode failed on %s (HTTP %s). Server said: %s\n" | |
| "Check the remote box loaded this pack version and has " | |
| "%r in models/text_encoders." % (url, e.code, detail, | |
| self._clip_name)) from e | |
| except Exception as e: # noqa: BLE001 | |
| raise RuntimeError( | |
| "Could not reach the remote encoder at %s (%s). Either start " | |
| "ComfyUI with this pack on that box, or flip the encode " | |
| "switch back to the local CLIP loader." % (url, e)) from e | |
| os.makedirs(self._cache_dir, exist_ok=True) | |
| with open(cpath, "wb") as f: | |
| f.write(blob) | |
| return _from_bytes(blob)["conds"] | |
| # -- everything else fails loudly ------------------------------------------ | |
| def __getattr__(self, name): | |
| raise AttributeError( | |
| "H3RemoteClip does not implement CLIP.%s(). The remote proxy " | |
| "covers tokenize/encode_from_tokens_scheduled (what the H3 " | |
| "multishot samplers use). Use the local CLIP loader for nodes " | |
| "that need more." % name) | |
| class H3RemoteTextEncoderClip: | |
| def INPUT_TYPES(cls): | |
| return { | |
| "required": { | |
| "endpoint": ("STRING", { | |
| "default": "http://OTHER-PC:8188", | |
| "tooltip": "The ComfyUI instance that will hold the text " | |
| "encoder resident and serve encodes. It must " | |
| "have this node pack installed (the route " | |
| "registers on load) and the encoder file in " | |
| "its models/text_encoders.", | |
| }), | |
| "clip_name": ("STRING", { | |
| "default": "qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors", | |
| "tooltip": "Encoder filename ON THE REMOTE BOX. GGUF " | |
| "encoders auto-pair their -mmproj exactly as a " | |
| "local load would.", | |
| }), | |
| "timeout_seconds": ("INT", { | |
| "default": 600, "min": 30, "max": 86400, | |
| "tooltip": "First request may include the remote box " | |
| "loading an 18 GB encoder from disk.", | |
| }), | |
| "clip_type": ("STRING", { | |
| "default": "minimax", | |
| "tooltip": "CLIP type as core's CLIPLoader names it. " | |
| "'minimax' for H3. A STRING rather than a " | |
| "dropdown because the valid list lives on the " | |
| "remote box.", | |
| }), | |
| }, | |
| } | |
| RETURN_TYPES = ("CLIP",) | |
| RETURN_NAMES = ("clip",) | |
| FUNCTION = "make" | |
| CATEGORY = "loaders/minimax" | |
| DESCRIPTION = ("A CLIP whose encode runs on another machine, so the 18 GB " | |
| "text encoder never loads on this card. Wire through " | |
| "H3 Any Switch against the local loader; identical " | |
| "requests are served from a local disk cache without " | |
| "touching the network.") | |
| def make(self, endpoint, clip_name, timeout_seconds, clip_type="minimax"): | |
| cache = os.path.join(os.path.dirname(os.path.abspath(__file__)), | |
| "cond_cache") | |
| self._preflight(endpoint) | |
| return (_RemoteClipProxy(endpoint, clip_name, clip_type, | |
| int(timeout_seconds), cache),) | |
| def _preflight(endpoint): | |
| """Fail here, not at the first encode. | |
| Without this the run reaches the sampler before anyone finds out the | |
| box is unreachable - and on a writer-driven graph that is after the | |
| LLM has spent minutes producing a script that is then thrown away | |
| (reported 2026-08-21: three attempts, ~7 minutes of writer time, the | |
| placeholder endpoint never edited). Two seconds of connect timeout | |
| here turns that into an instant, obvious failure. | |
| """ | |
| url = (endpoint or "").rstrip("/") | |
| if not url: | |
| raise RuntimeError( | |
| "H3 Remote Text Encoder: the endpoint is empty. Put in the " | |
| "address of the ComfyUI PC that will serve encodes, e.g. " | |
| "http://your-other-pc:8188 . It needs this pack installed and " | |
| "the encoder file in its models/text_encoders. (Or turn " | |
| "remote_encoder off on the H3 Studio Switches panel to " | |
| "encode on this machine.)") | |
| if "OTHER-PC" in url.upper(): | |
| raise RuntimeError( | |
| "H3 Remote Text Encoder is still set to the placeholder " | |
| "address %s. Replace it with the address of the ComfyUI PC " | |
| "that will serve encodes - it needs this pack installed (the " | |
| "route registers on load) and the encoder file in its " | |
| "models/text_encoders. (Or turn remote_encoder off on the H3 " | |
| "Studio Switches panel to encode on this machine.)" % url) | |
| try: | |
| req = urllib.request.Request(url + "/system_stats", | |
| headers={"Accept": "application/json"}) | |
| urllib.request.urlopen(req, timeout=5).read(1) | |
| except Exception as e: | |
| raise RuntimeError( | |
| "H3 Remote Text Encoder cannot reach %s (%s). Check that " | |
| "ComfyUI is running on that box with this pack installed, and " | |
| "that the address and port are right - a hostname that does " | |
| "not resolve gives exactly this error, so try the IP. (Or " | |
| "turn remote_encoder off on the H3 Studio Switches panel to " | |
| "encode on this machine.)" % (url, e)) from e | |
| NODE_CLASS_MAPPINGS = {"H3RemoteTextEncoderClip": H3RemoteTextEncoderClip} | |
| NODE_DISPLAY_NAME_MAPPINGS = { | |
| "H3RemoteTextEncoderClip": "H3 Remote Text Encoder (CLIP over LAN)"} | |