Upload folder using huggingface_hub

adapter_stage2_best.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6559e73b3f1b8dd3d3b8702ba4f6221c2bf68427f39741db3cafef53dfe4af5c
+size 2288170738

custom_nodes/ComfyUI-MiniMaxH3-Adapter/__init__.py

@@ -0,0 +1,26 @@
+import os
+
+import folder_paths
+
+# models/minimax_h3_adapter/  -> adapter_stage2.safetensors
+folder_paths.add_model_folder_path("minimax_h3_adapter",
+                                   os.path.join(folder_paths.models_dir, "minimax_h3_adapter"))
+# models/text_encoders/       -> Qwen3.5-4B 文件夹（与 minimax CLIP 同目录）
+folder_paths.add_model_folder_path("minimax_h3_student",
+                                   os.path.join(folder_paths.models_dir, "text_encoders"))
+
+from .nodes import MiniMaxH3AdapterLoader, MiniMaxH3AdapterFromCLIPLoader  # noqa: E402
+from .export_cond import MiniMaxH3ExportCond  # noqa: E402
+
+NODE_CLASS_MAPPINGS = {
+    "MiniMaxH3AdapterLoader": MiniMaxH3AdapterLoader,
+    "MiniMaxH3AdapterFromCLIPLoader": MiniMaxH3AdapterFromCLIPLoader,
+    "MiniMaxH3ExportCond": MiniMaxH3ExportCond,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "MiniMaxH3AdapterLoader": "MiniMax H3 Adapter Loader",
+    "MiniMaxH3AdapterFromCLIPLoader": "MiniMax H3 Adapter (From CLIP)",
+    "MiniMaxH3ExportCond": "MiniMax H3 Export Cond (Debug)",
+}
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

custom_nodes/ComfyUI-MiniMaxH3-Adapter/adapter/__init__.py

@@ -0,0 +1,3 @@
+from .model import H3Adapter, H3_HIDDEN, STUDENT_HIDDEN
+
+__all__ = ["H3Adapter", "H3_HIDDEN", "STUDENT_HIDDEN"]

custom_nodes/ComfyUI-MiniMaxH3-Adapter/adapter/model.py

@@ -0,0 +1,230 @@
+"""H3 文本编码器替换适配器（接口蒸馏）：source_projection + CrossAttention Resampler + TokenRefiner。
+
+前向:
+    h3_ids [B, S_T] --QueryEmbedding--> Q [B, S_T, 5376]
+    student_hidden [B, S_S, 2560] --source_projection--> KV [B, S_S, 5376]
+    CrossAttentionBlock(Q, KV) -> [B, S_T, 5376]
+    TokenRefiner(2 层, 原权重初始化) -> [B, S_T, 5376]   # 与教师 target 同坐标系
+
+TokenRefiner 结构严格复刻原始 checkpoint（已源码核实）:
+    - fused qkv (chunk(3)) + per-head qk_norm + 双向注意力 + out_proj，全部 bias=False
+    - SwiGLU MLP: fc1 为 fused [gate; value]（gate 在前），fc2(silu(gate)*value)
+    - 2 个 pre-norm block + final RMSNorm，eps 全部 1e-5
+"""
+from __future__ import annotations
+
+import math
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+H3_VOCAB = 151936
+H3_HIDDEN = 5376
+REFINER_HEADS = 56
+REFINER_HEAD_DIM = 128
+REFINER_FFN = 14336
+STUDENT_HIDDEN = 2560
+
+
+class RMSNorm(nn.Module):
+    def __init__(self, dim: int, eps: float = 1e-5):
+        super().__init__()
+        self.weight = nn.Parameter(torch.ones(dim))
+        self.eps = eps
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + self.eps) * self.weight
+
+
+class SwiGLUFFN(nn.Module):
+    def __init__(self, hidden: int, ffn: int):
+        super().__init__()
+        self.fc1 = nn.Linear(hidden, 2 * ffn, bias=False)
+        self.fc2 = nn.Linear(ffn, hidden, bias=False)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        gate, value = self.fc1(x).chunk(2, dim=-1)
+        return self.fc2(F.silu(gate) * value)
+
+
+class TokenRefinerAttention(nn.Module):
+    def __init__(self, hidden: int, heads: int, dim_head: int):
+        super().__init__()
+        self.heads = heads
+        self.head_dim = dim_head
+        self.inner_dim = heads * dim_head
+        self.qkv_proj = nn.Linear(hidden, 3 * self.inner_dim, bias=False)
+        self.q_norm = RMSNorm(dim_head)
+        self.k_norm = RMSNorm(dim_head)
+        self.out_proj = nn.Linear(self.inner_dim, hidden, bias=False)
+        self.use_sdpa = True  # SDPA flash: 注意力内存 O(S²)->O(S)，数值与手写注意力差 ~1e-3（蒸馏噪声级）
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        q, k, v = self.qkv_proj(x).chunk(3, dim=-1)
+        q = self.q_norm(q.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2))
+        k = self.k_norm(k.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2))
+        v = v.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        if self.use_sdpa:
+            out = F.scaled_dot_product_attention(q, k, v, scale=self.head_dim ** -0.5)
+        else:
+            attn = torch.softmax((q @ k.transpose(-2, -1)) * (self.head_dim ** -0.5), dim=-1)
+            out = attn @ v
+        return self.out_proj(out.transpose(1, 2).flatten(2))
+
+
+class TokenRefinerBlock(nn.Module):
+    def __init__(self, hidden: int, heads: int, dim_head: int, ffn: int):
+        super().__init__()
+        self.norm1 = RMSNorm(hidden)
+        self.attn = TokenRefinerAttention(hidden, heads, dim_head)
+        self.norm2 = RMSNorm(hidden)
+        self.mlp = SwiGLUFFN(hidden, ffn)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = x + self.attn(self.norm1(x))
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class TokenRefiner(nn.Module):
+    def __init__(self, num_layers: int = 2, hidden: int = H3_HIDDEN,
+                 heads: int = REFINER_HEADS, dim_head: int = REFINER_HEAD_DIM, ffn: int = REFINER_FFN):
+        super().__init__()
+        self.blocks = nn.ModuleList([TokenRefinerBlock(hidden, heads, dim_head, ffn) for _ in range(num_layers)])
+        self.final_norm = RMSNorm(hidden)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        for block in self.blocks:
+            x = block(x)
+        return self.final_norm(x)
+
+
+class CrossAttentionBlock(nn.Module):
+    """跨空间交叉注意（学生 2560 投影空间 <-> 教师 5376 表示空间）。
+
+    训练稳定性升级（兼容旧权重加载）:
+      - QK-norm: to_q/to_k 投影后对每头做 RMSNorm（Llama 3.2 vision 交叉注意惯例，
+        稳定跨空间注意力的 q/k 尺度失配）
+      - gated tanh: out_proj 输出经 tanh(gate) 门控（Flamingo 惯例），gate 初始 0 => 恒等
+      - attn dropout: 交叉注意 dropout 0.1（Emu3 防后期 collapse）
+    """
+
+    def __init__(self, hidden: int = H3_HIDDEN, heads: int = 32, dim_head: int = 128, ffn: int = REFINER_FFN,
+                 attn_dropout: float = 0.1, use_qk_norm: bool = True, use_gate: bool = True):
+        super().__init__()
+        self.heads = heads
+        self.head_dim = dim_head
+        self.inner_dim = heads * dim_head
+        self.norm_q = RMSNorm(hidden)
+        self.norm_kv = RMSNorm(hidden)
+        self.to_q = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.to_k = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.to_v = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.out_proj = nn.Linear(self.inner_dim, hidden, bias=False)
+        self.norm2 = RMSNorm(hidden)
+        self.mlp = SwiGLUFFN(hidden, ffn)
+        self.use_sdpa = True
+        self.attn_dropout = attn_dropout
+        self.use_qk_norm = use_qk_norm
+        if use_qk_norm:
+            self.qk_norm = RMSNorm(dim_head)
+        self.use_gate = use_gate
+        if use_gate:
+            self.gate = nn.Parameter(torch.zeros(1))  # tanh(0)=0 -> 恒等，兼容旧权重
+
+    def forward(self, q: torch.Tensor, kv: torch.Tensor) -> torch.Tensor:
+        qn = self.norm_q(q)
+        kvn = self.norm_kv(kv)
+        qh = self.to_q(qn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        kh = self.to_k(kvn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        vh = self.to_v(kvn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        if self.use_qk_norm:
+            qh = self.qk_norm(qh)
+            kh = self.qk_norm(kh)
+        if self.use_sdpa:
+            out = F.scaled_dot_product_attention(qh, kh, vh, scale=self.head_dim ** -0.5,
+                                                 dropout_p=self.attn_dropout if self.training else 0.0)
+        else:
+            attn = torch.softmax((qh @ kh.transpose(-2, -1)) * (self.head_dim ** -0.5), dim=-1)
+            out = attn @ vh
+        proj = self.out_proj(out.transpose(1, 2).flatten(2))
+        x = q + (torch.tanh(self.gate) * proj if self.use_gate else proj)
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class QueryEmbedding(nn.Module):
+    def __init__(self, vocab: int = H3_VOCAB, dim: int = 256, out: int = H3_HIDDEN):
+        super().__init__()
+        self.embed = nn.Embedding(vocab, dim)
+        self.proj = nn.Linear(dim, out, bias=True)
+
+    def forward(self, ids: torch.Tensor) -> torch.Tensor:
+        return self.proj(self.embed(ids))
+
+
+class H3Adapter(nn.Module):
+    """完整适配器。param 约 1.14B（source_proj 13.8M + query_embed 40.3M + crossattn 319M + refiner 751M）。"""
+
+    def __init__(self):
+        super().__init__()
+        self.source_projection = nn.Linear(STUDENT_HIDDEN, H3_HIDDEN, bias=True)
+        self.query_embedding = QueryEmbedding()
+        self.cross_attention = CrossAttentionBlock()
+        self.token_refiner = TokenRefiner()
+
+    def forward(self, h3_ids: torch.Tensor, student_hidden: torch.Tensor) -> torch.Tensor:
+        kv = self.source_projection(student_hidden)
+        q = self.query_embedding(h3_ids)
+        x = self.cross_attention(q, kv)
+        x = self.token_refiner(x)
+        return x
+
+    def load_token_refiner(self, state_dict: dict[str, torch.Tensor], strict: bool = True) -> None:
+        refiner_state = {
+            k[len("token_refiner."):]: v
+            for k, v in state_dict.items()
+            if k.startswith("token_refiner.")
+        }
+        missing, unexpected = self.token_refiner.load_state_dict(refiner_state, strict=strict)
+        assert not missing and not unexpected, f"refiner load: missing={missing} unexpected={unexpected}"
+
+    def trainable_modules(self, stage: int) -> list[nn.Parameter]:
+        if stage == 1:
+            return (
+                list(self.source_projection.parameters())
+                + list(self.query_embedding.parameters())
+                + list(self.cross_attention.parameters())
+            )
+        return list(self.parameters())
+
+
+class TeacherHead(nn.Module):
+    """教师 target 计算: h50 -> condition_proj(5120->5376) -> token_refiner -> [B, S_T, 5376]。"""
+
+    def __init__(self):
+        super().__init__()
+        self.condition_proj = nn.Linear(5120, H3_HIDDEN, bias=True)
+        self.token_refiner = TokenRefiner()
+
+    def forward(self, h50: torch.Tensor) -> torch.Tensor:
+        return self.token_refiner(self.condition_proj(h50))
+
+
+def compute_query_embed_init(embed_tokens: torch.Tensor, dim: int = 256, seed: int = 0) -> torch.Tensor:
+    """query embedding 初始化: embed.weight = E @ P，P 为 5120->dim 的随机投影。
+
+    仅用于一次性初始化，后续可训练。embed_tokens 为 [151936, 5120]（BF16 或 FP32）。
+    """
+    assert embed_tokens.dim() == 2 and embed_tokens.shape[1] == 5120, embed_tokens.shape
+    rng = torch.Generator().manual_seed(seed)
+    p = torch.randn(5120, dim, generator=rng) * (1.0 / math.sqrt(5120))
+    embed_tokens = embed_tokens.to(torch.float32)
+    chunks = 8
+    out = torch.empty(embed_tokens.shape[0], dim, dtype=torch.float32)
+    for i in range(chunks):
+        lo = i * embed_tokens.shape[0] // chunks
+        hi = (i + 1) * embed_tokens.shape[0] // chunks
+        out[lo:hi] = embed_tokens[lo:hi] @ p
+    return out.to(torch.bfloat16)

custom_nodes/ComfyUI-MiniMaxH3-Adapter/adapter/model.py.bak_old

@@ -0,0 +1,160 @@
+"""H3 文本编码器替换适配器（接口蒸馏）——ComfyUI 节点用自包含版。
+
+前向:
+    h3_ids [B, S_T] --QueryEmbedding--> Q [B, S_T, 5376]
+    student_hidden [B, S_S, 2560] --source_projection--> KV [B, S_S, 5376]
+    CrossAttentionBlock(Q, KV) -> [B, S_T, 5376]
+    TokenRefiner(2 层, 原权重初始化) -> [B, S_T, 5376]   # 与教师 target 同坐标系
+
+TokenRefiner 结构严格复刻原始 checkpoint:
+    - fused qkv (chunk(3)) + per-head qk_norm + 双向注意力 + out_proj，全部 bias=False
+    - SwiGLU MLP: fc1 为 fused [gate; value]（gate 在前），fc2(silu(gate)*value)
+    - 2 个 pre-norm block + final RMSNorm，eps 全部 1e-5
+
+注意力 use_sdpa=True（默认）: SDPA flash 省显存；手写注意力保留为回退。
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+H3_VOCAB = 151936
+H3_HIDDEN = 5376
+REFINER_HEADS = 56
+REFINER_HEAD_DIM = 128
+REFINER_FFN = 14336
+STUDENT_HIDDEN = 2560
+
+
+class RMSNorm(nn.Module):
+    def __init__(self, hidden: int, eps: float = 1e-5):
+        super().__init__()
+        self.weight = nn.Parameter(torch.ones(hidden))
+        self.eps = eps
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + self.eps) * self.weight
+
+
+class SwiGLUFFN(nn.Module):
+    def __init__(self, hidden: int, ffn: int):
+        super().__init__()
+        self.fc1 = nn.Linear(hidden, 2 * ffn, bias=False)
+        self.fc2 = nn.Linear(ffn, hidden, bias=False)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        gate, value = self.fc1(x).chunk(2, dim=-1)
+        return self.fc2(F.silu(gate) * value)
+
+
+class TokenRefinerAttention(nn.Module):
+    def __init__(self, hidden: int, heads: int, dim_head: int):
+        super().__init__()
+        self.heads = heads
+        self.head_dim = dim_head
+        self.inner_dim = heads * dim_head
+        self.qkv_proj = nn.Linear(hidden, 3 * self.inner_dim, bias=False)
+        self.q_norm = RMSNorm(dim_head)
+        self.k_norm = RMSNorm(dim_head)
+        self.out_proj = nn.Linear(self.inner_dim, hidden, bias=False)
+        self.use_sdpa = True  # SDPA flash: 注意力内存 O(S²)->O(S)，数值与手写注意力差 ~1e-3（蒸馏噪声级）
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        q, k, v = self.qkv_proj(x).chunk(3, dim=-1)
+        q = self.q_norm(q.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2))
+        k = self.k_norm(k.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2))
+        v = v.unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        if self.use_sdpa:
+            out = F.scaled_dot_product_attention(q, k, v, scale=self.head_dim ** -0.5)
+        else:
+            attn = torch.softmax((q @ k.transpose(-2, -1)) * (self.head_dim ** -0.5), dim=-1)
+            out = attn @ v
+        return self.out_proj(out.transpose(1, 2).flatten(2))
+
+
+class TokenRefinerBlock(nn.Module):
+    def __init__(self, hidden: int, heads: int, dim_head: int, ffn: int):
+        super().__init__()
+        self.norm1 = RMSNorm(hidden)
+        self.attn = TokenRefinerAttention(hidden, heads, dim_head)
+        self.norm2 = RMSNorm(hidden)
+        self.mlp = SwiGLUFFN(hidden, ffn)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = x + self.attn(self.norm1(x))
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class TokenRefiner(nn.Module):
+    def __init__(self, num_layers: int = 2, hidden: int = H3_HIDDEN,
+                 heads: int = REFINER_HEADS, dim_head: int = REFINER_HEAD_DIM, ffn: int = REFINER_FFN):
+        super().__init__()
+        self.blocks = nn.ModuleList([TokenRefinerBlock(hidden, heads, dim_head, ffn) for _ in range(num_layers)])
+        self.final_norm = RMSNorm(hidden)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        for block in self.blocks:
+            x = block(x)
+        return self.final_norm(x)
+
+
+class CrossAttentionBlock(nn.Module):
+    def __init__(self, hidden: int = H3_HIDDEN, heads: int = 32, dim_head: int = 128, ffn: int = REFINER_FFN):
+        super().__init__()
+        self.heads = heads
+        self.head_dim = dim_head
+        self.inner_dim = heads * dim_head
+        self.norm_q = RMSNorm(hidden)
+        self.norm_kv = RMSNorm(hidden)
+        self.to_q = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.to_k = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.to_v = nn.Linear(hidden, self.inner_dim, bias=False)
+        self.out_proj = nn.Linear(self.inner_dim, hidden, bias=False)
+        self.norm2 = RMSNorm(hidden)
+        self.mlp = SwiGLUFFN(hidden, ffn)
+        self.use_sdpa = True
+
+    def forward(self, q: torch.Tensor, kv: torch.Tensor) -> torch.Tensor:
+        qn = self.norm_q(q)
+        kvn = self.norm_kv(kv)
+        qh = self.to_q(qn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        kh = self.to_k(kvn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        vh = self.to_v(kvn).unflatten(-1, (self.heads, self.head_dim)).transpose(1, 2)
+        if self.use_sdpa:
+            out = F.scaled_dot_product_attention(qh, kh, vh, scale=self.head_dim ** -0.5)
+        else:
+            attn = torch.softmax((qh @ kh.transpose(-2, -1)) * (self.head_dim ** -0.5), dim=-1)
+            out = attn @ vh
+        x = q + self.out_proj(out.transpose(1, 2).flatten(2))
+        x = x + self.mlp(self.norm2(x))
+        return x
+
+
+class QueryEmbedding(nn.Module):
+    def __init__(self, vocab: int = H3_VOCAB, dim: int = 256, out: int = H3_HIDDEN):
+        super().__init__()
+        self.embed = nn.Embedding(vocab, dim)
+        self.proj = nn.Linear(dim, out, bias=True)
+
+    def forward(self, ids: torch.Tensor) -> torch.Tensor:
+        return self.proj(self.embed(ids))
+
+
+class H3Adapter(nn.Module):
+    """完整适配器。param 约 1.14B（source_proj 13.8M + query_embed 40.3M + crossattn 319M + refiner 751M）。"""
+
+    def __init__(self):
+        super().__init__()
+        self.source_projection = nn.Linear(STUDENT_HIDDEN, H3_HIDDEN, bias=True)
+        self.query_embedding = QueryEmbedding()
+        self.cross_attention = CrossAttentionBlock()
+        self.token_refiner = TokenRefiner()
+
+    def forward(self, h3_ids: torch.Tensor, student_hidden: torch.Tensor) -> torch.Tensor:
+        kv = self.source_projection(student_hidden)
+        q = self.query_embedding(h3_ids)
+        x = self.cross_attention(q, kv)
+        x = self.token_refiner(x)
+        return x

custom_nodes/ComfyUI-MiniMaxH3-Adapter/adapter_clip.py

@@ -0,0 +1,132 @@
+"""MiniMaxH3AdapterCLIP: 鸭子类型 CLIP，纯 torch（无 ComfyUI 依赖，可独立测试）。
+
+contract（与官方 minimax CLIP 对齐）:
+    tokenize(prompt, images=...) -> 捕获官方节点的 prompt
+    encode_from_tokens_scheduled(tokens) -> [[embeds_fp16 [1, S_T, 5376],
+                                             {"minimax_token_tags": tags_long [S_T]}]]
+纯文本 prompt 的 tag 全为 1（DiT packed 布局的 text 段）。
+
+原理: ComfyUI MiniMaxH3 DiT 的 preprocess_text_embeds / _forward 在
+text_states.shape[-1] == 5376 (hidden_size) 时跳过 condition_proj + token_refiner，
+适配器输出已是 post-refiner 表示，直接注入。
+"""
+from __future__ import annotations
+
+import torch
+
+try:
+    import node_helpers
+except ImportError:  # 独立测试环境
+    def _conditioning_set_values(cond, new_values):
+        if len(cond) == 1 and len(cond[0][1]) == 0:
+            return [[cond[0][0], new_values]]
+        return [[c[0], {**c[1], **new_values}] for c in cond]
+    node_helpers = type("NH", (), {"conditioning_set_values": staticmethod(_conditioning_set_values)})()
+
+H3_HIDDEN = 5376
+TEXT_TAG = 1
+
+
+class MiniMaxH3AdapterCLIP:
+    def __init__(self, adapter: torch.nn.Module, student, h3_tokenizer,
+                 device: torch.device, output_dtype: torch.dtype = torch.float16,
+                 lowvram: bool = True):
+        self._adapter = adapter
+        self._student = student          # callable: prompt -> [S_S, 2560] (device)
+        self._tok = h3_tokenizer
+        self._device = device
+        self._dtype = output_dtype
+        self._lowvram = lowvram
+        self._adapter_offloaded = False
+        self._prompt = ""
+
+    def tokenize(self, text: str, return_word_ids: bool = False, images=None, **kwargs):
+        self._prompt = text
+        return {}
+
+    @torch.no_grad()
+    def encode_from_tokens_scheduled(self, tokens, unprojected: bool = False,
+                                     add_dict: dict = {}, show_pbar: bool = True):
+        prompt = self._prompt
+        dev = self._device
+        if self._adapter_offloaded:
+            self._adapter.to(dev)
+            self._adapter_offloaded = False
+        ids = self._tok(prompt, add_special_tokens=False)["input_ids"]
+        h_s = self._student(prompt).unsqueeze(0).to(dev)              # [1, S_S, 2560]
+        h3_ids = torch.tensor([ids], dtype=torch.long, device=dev)
+        embeds = self._adapter(h3_ids, h_s)                           # [1, S_T, 5376] bf16
+        s_t = embeds.shape[1]
+        assert s_t == len(ids), f"h3 ids {len(ids)} != adapter out {s_t}"
+        assert embeds.shape[-1] == H3_HIDDEN, embeds.shape
+        assert torch.isfinite(embeds).all(), "adapter 输出含 NaN"
+
+        cond_embeds = embeds.to(self._dtype)                          # fp16 对齐官方 minimax CLIP
+        tags = torch.ones(s_t, dtype=torch.long, device=dev)
+        cond = [[cond_embeds, {"minimax_token_tags": tags}]]
+        if self._lowvram:
+            # 适配器 1.14B(≈2.3GB) 不卸载会挤占 DiT 显存 → lowvram offload，下次 encode 再载入
+            self._adapter.to("cpu")
+            self._adapter_offloaded = True
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+        if add_dict:
+            cond = node_helpers.conditioning_set_values(cond, add_dict)
+        return cond
+
+
+class MiniMaxH3AdapterFromCLIP:
+    """CLIP→CLIP 包装: 学生 CLIP（CLIPLoader GGUF 等 ComfyUI 原生加载）的 encode 输出当 student_hidden。
+
+    消费内层 CLIP 契约（comfy.sd.CLIP 或等价鸭子类型）:
+        tokenize(prompt) -> tokens
+        encode_from_tokens(tokens) -> [[tensor [1, S_S, 2560], extras]]
+    内层 encode 的 layer="last" 输出 = 学生主干 post-final-norm hidden（与训练 HF 语义一致）。
+    """
+
+    def __init__(self, inner_clip, adapter: torch.nn.Module, h3_tokenizer,
+                 device: torch.device, output_dtype: torch.dtype = torch.float16,
+                 lowvram: bool = True):
+        self._inner = inner_clip
+        self._adapter = adapter
+        self._tok = h3_tokenizer
+        self._device = device
+        self._dtype = output_dtype
+        self._lowvram = lowvram
+        self._adapter_offloaded = False
+        self._prompt = ""
+
+    def tokenize(self, text: str, return_word_ids: bool = False, images=None, **kwargs):
+        self._prompt = text
+        return {}
+
+    @torch.no_grad()
+    def encode_from_tokens_scheduled(self, tokens, unprojected: bool = False,
+                                     add_dict: dict = {}, show_pbar: bool = True):
+        prompt = self._prompt
+        if self._adapter_offloaded:
+            self._adapter.to(self._device)
+            self._adapter_offloaded = False
+        inner_tokens = self._inner.tokenize(prompt)
+        inner_cond = self._inner.encode_from_tokens(inner_tokens)
+        dev = next(self._adapter.parameters()).device  # 内层 CLIP 可能在 CPU/低显存模式，以适配器设备为准
+        h_s = inner_cond[0][0][0].to(torch.bfloat16).to(dev)            # [S_S, 2560] post-norm
+        ids = self._tok(prompt, add_special_tokens=False)["input_ids"]
+        h3_ids = torch.tensor([ids], dtype=torch.long, device=dev)
+        embeds = self._adapter(h3_ids, h_s.unsqueeze(0))               # [1, S_T, 5376] bf16
+        s_t = embeds.shape[1]
+        assert s_t == len(ids), f"h3 ids {len(ids)} != adapter out {s_t}"
+        assert embeds.shape[-1] == H3_HIDDEN, embeds.shape
+        assert torch.isfinite(embeds).all(), "adapter 输出含 NaN"
+
+        cond_embeds = embeds.to(self._dtype)
+        tags = torch.ones(s_t, dtype=torch.long, device=dev)
+        cond = [[cond_embeds, {"minimax_token_tags": tags}]]
+        if self._lowvram:
+            self._adapter.to("cpu")
+            self._adapter_offloaded = True
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+        if add_dict:
+            cond = node_helpers.conditioning_set_values(cond, add_dict)
+        return cond

custom_nodes/ComfyUI-MiniMaxH3-Adapter/check_alignment.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""候选学生（GGUF 量化 / uncensored 微调 / 任意 HF 目录）vs bf16 原版 的特征对齐测试。
+
+这是"换学生"的照妖镜——适配器训练时的输入是 bf16 原版的 hidden_states[-1]，
+候选版隐藏态的任何漂移都会直接传导到生成的 conditioning。
+
+用法:
+    python check_alignment.py <bf16 原版目录> <候选: *.gguf 文件 或 HF 目录>
+    [--prompts 3] [--device cuda]
+
+判定:
+    cos > 0.99   合格（量化级噪声，直接用）
+    0.95-0.99    有可见漂移，评估后可用（建议先跑一次端到端生成对比）
+    < 0.95       漂移显著，需用候选学生重提特征 + 重训/微调适配器
+
+说明:
+    GGUF 走 transformers 内置加载器（>=4.45，AutoModel.from_pretrained(".gguf")），
+    隐藏态语义与 bf16 原版完全一致（都是 transformers 路径），测的是量化+微调漂移本身。
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import torch
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+from student import StudentTextEncoder, load_student, find_language_model  # noqa: E402
+from adapter_clip import H3_HIDDEN  # noqa: E402
+
+
+def load_candidate(path: str, device: torch.device, baseline_mem: float = 0.0):
+    from transformers import AutoConfig, AutoModel
+
+    if path.endswith(".gguf"):
+        from gguf_qwen35 import load_gguf_model_quantized
+        model, info = load_gguf_model_quantized(path)
+        print(f"    [candidate] 自定义 GGUF 加载器(量化驻留): {info}", flush=True)
+        model = model.to(torch.bfloat16).to(device)  # GGMLTensor 的 to 忽略 dtype, 只移设备
+        if device.type == "cuda":
+            used = torch.cuda.memory_allocated() / 2**30 - baseline_mem
+            print(f"    [candidate] 净显存: {used:.2f} GiB", flush=True)
+        return model
+    # HF 目录
+    cfg = AutoConfig.from_pretrained(path)
+    model = AutoModel.from_config(cfg)
+    try:
+        sd = {k[len("model."):] if k.startswith("model.") else k: v
+              for k, v in torch.load(os.path.join(path, "pytorch_model.bin"), map_location="cpu").items()}
+        missing, _ = model.load_state_dict(sd, strict=False)
+        assert not missing, f"missing: {missing[:5]}"
+    except FileNotFoundError:
+        model = AutoModel.from_pretrained(path, torch_dtype=torch.bfloat16)
+    return model.to(device)
+
+
+@torch.no_grad()
+def hidden_fn(lm, tok, prompt: str, device: torch.device) -> torch.Tensor:
+    ids = tok(prompt, add_special_tokens=False)["input_ids"]
+    out = lm(input_ids=torch.tensor([ids], device=device), output_hidden_states=True)
+    return out.hidden_states[-1][0].float()  # [S, D] 与训练同路径
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("reference", help="bf16 原版 Qwen3.5-4B HF 目录")
+    ap.add_argument("candidate", help="候选: .gguf 或 HF 目录")
+    ap.add_argument("--prompts", type=int, default=3)
+    ap.add_argument("--device", default="")
+    args = ap.parse_args()
+
+    from transformers import AutoTokenizer
+    dev = torch.device(args.device) if args.device else torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"device: {dev}")
+
+    print("[1/2] loading reference (bf16)...", flush=True)
+    ref_model = load_student(args.reference).to(torch.bfloat16).to(dev)
+    ref_lm = find_language_model(ref_model)
+    ref_tok = AutoTokenizer.from_pretrained(args.reference)
+
+    print("[2/2] loading candidate...", flush=True)
+    baseline = torch.cuda.memory_allocated() / 2**30 if dev.type == "cuda" else 0.0
+    cand_model = load_candidate(args.candidate, dev, baseline)
+    cand_lm = find_language_model(cand_model)
+    # .gguf 候选无自带 tokenizer: 复用参考模型的（同一 Qwen3.5-4B 词表）
+    cand_tok = ref_tok if args.candidate.endswith(".gguf") else AutoTokenizer.from_pretrained(args.candidate)
+
+    demo = [
+        "A cinematic shot of a tiny robot repairing a broken music box in a giant's attic",
+        "A surfer riding a massive neon wave at sunset, spray frozen in the air, dramatic backlight",
+        "Paper collage birds flocking over a misty city skyline, soft morning light",
+    ]
+    print(f"\ncosine 对比 {args.prompts} 条 prompt（hidden_states[-1], [S, 2560]）:")
+    worst = 1.0
+    for i, p in enumerate(demo[: args.prompts]):
+        h_ref = hidden_fn(ref_lm, ref_tok, p, dev)
+        h_can = hidden_fn(cand_lm, cand_tok, p, dev)
+        n = min(h_ref.shape[0], h_can.shape[0])
+        if h_ref.shape[0] != h_can.shape[0]:
+            print(f"  [注意] prompt {i}: 长度不同 ref={h_ref.shape[0]} cand={h_can.shape[0]}（截断到 {n} 比较）")
+        a, b = h_ref[:n].flatten(), h_can[:n].flatten()
+        cos = (a * b).sum() / (a.norm() * b.norm())
+        worst = min(worst, cos.item())
+        print(f"  prompt {i}: cos={cos.item():.4f}")
+
+    print(f"\n最差 cos = {worst:.4f} -> ", end="")
+    if worst > 0.99:
+        print("合格（量化级噪声，直接用）✅")
+    elif worst >= 0.95:
+        print("有可见漂移，评估后可用（建议先端到端生成对比）⚠️")
+    else:
+        print("漂移显著，需用候选学生重提特征 + 重训/微调适配器 ❌")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-MiniMaxH3-Adapter/export_adapter.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""导出 train.py checkpoint -> ComfyUI 适配器 .safetensors（纯 state_dict）。
+
+用法:
+    python export_adapter.py <adapter_stage2_step2000.pt> [--out adapter_stage2.safetensors]
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import torch
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+from adapter.model import H3Adapter  # noqa: E402
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("ckpt", help="train.py checkpoint (.pt)")
+    ap.add_argument("--out", default="adapter_stage2.safetensors")
+    args = ap.parse_args()
+
+    ckpt = torch.load(args.ckpt, map_location="cpu", weights_only=False)
+    state = ckpt.get("model", ckpt)  # 兼容 {"model":..., "config":...} 与纯 state_dict
+    if any(k.startswith("model.") for k in state):
+        state = {k[len("model."):]: v for k, v in state.items()}
+
+    model = H3Adapter()
+    missing, unexpected = model.load_state_dict(state, strict=False)
+    assert not missing, f"missing: {missing[:10]}"
+    print(f"adapter keys: {len(state)} | missing={len(missing)} unexpected={len(unexpected)}")
+
+    from safetensors.torch import save_file
+    save_file({k: v.contiguous().to(torch.bfloat16) for k, v in state.items()}, args.out)
+    print(f"saved -> {args.out}")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-MiniMaxH3-Adapter/export_cond.py

@@ -0,0 +1,42 @@
+"""临时调试节点: 导出 CLIP 的 cond embeds 到 models/minimax_h3_adapter/cond_official_ref.npy。
+
+用法（黑屏诊断，插进官方工作流）:
+    CLIPLoader(官方 qwen3vl-32B GGUF) -> MiniMaxH3ExportCond -> MiniMaxH3ImageToVideo
+    节点透传 clip 对象（不改变工作流行为），执行时导出 cond npy 并打印路径。
+    ComfyUI 惰性执行会剪枝无输出节点，故必须输出透传 clip 才能被触发。
+"""
+import os
+
+import numpy as np
+
+import folder_paths
+
+
+class MiniMaxH3ExportCond:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {"required": {
+            "clip": ("CLIP",),
+            "prompt": ("STRING", {"default": "a red apple rotating on a wooden table, studio lighting, 3d render",
+                                  "multiline": True}),
+        }}
+
+    RETURN_TYPES = ("CLIP",)
+    RETURN_NAMES = ("clip",)
+    FUNCTION = "run"
+    CATEGORY = "model/conditioning/minimax"
+
+    def run(self, clip, prompt):
+        tokens = clip.tokenize(prompt)
+        cond = clip.encode_from_tokens_scheduled(tokens)
+        embeds = cond[0][0].float().cpu().numpy()
+        out_dir = folder_paths.get_folder_paths("minimax_h3_adapter")[0]
+        os.makedirs(out_dir, exist_ok=True)
+        path = os.path.join(out_dir, "cond_official_ref.npy")
+        np.save(path, embeds)
+        extra = ""
+        if len(cond[0]) > 1 and isinstance(cond[0][1], dict) and "minimax_token_tags" in cond[0][1]:
+            tags = cond[0][1]["minimax_token_tags"].cpu().numpy()
+            extra = f" tags_unique={sorted(set(tags.tolist()))}"
+        print(f"[export_cond] saved {path} shape={embeds.shape} dtype={embeds.dtype}{extra}", flush=True)
+        return (clip,)

custom_nodes/ComfyUI-MiniMaxH3-Adapter/gguf_dequant.py

@@ -0,0 +1,309 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import gguf
+import torch
+
+try:
+    from tqdm import tqdm
+except ImportError:
+    class _Tqdm:
+        @staticmethod
+        def write(msg):
+            print(msg)
+    tqdm = _Tqdm
+
+
+TORCH_COMPATIBLE_QTYPES = (None, gguf.GGMLQuantizationType.F32, gguf.GGMLQuantizationType.F16)
+
+def is_torch_compatible(tensor):
+    return tensor is None or getattr(tensor, "tensor_type", None) in TORCH_COMPATIBLE_QTYPES
+
+def is_quantized(tensor):
+    return not is_torch_compatible(tensor)
+
+def dequantize_tensor(tensor, dtype=None, dequant_dtype=None):
+    qtype = getattr(tensor, "tensor_type", None)
+    oshape = getattr(tensor, "tensor_shape", tensor.shape)
+
+    if qtype in TORCH_COMPATIBLE_QTYPES:
+        return tensor.to(dtype)
+    elif qtype in dequantize_functions:
+        dequant_dtype = dtype if dequant_dtype == "target" else dequant_dtype
+        return dequantize(tensor.data, qtype, oshape, dtype=dequant_dtype).to(dtype)
+    else:
+        # this is incredibly slow
+        tqdm.write(f"Falling back to numpy dequant for qtype: {getattr(qtype, 'name', repr(qtype))}")
+        new = gguf.quants.dequantize(tensor.cpu().numpy(), qtype)
+        return torch.from_numpy(new).to(tensor.device, dtype=dtype)
+
+def dequantize(data, qtype, oshape, dtype=None):
+    """
+    Dequantize tensor back to usable shape/dtype
+    """
+    block_size, type_size = gguf.GGML_QUANT_SIZES[qtype]
+    dequantize_blocks = dequantize_functions[qtype]
+
+    rows = data.reshape(
+        (-1, data.shape[-1])
+    ).view(torch.uint8)
+
+    n_blocks = rows.numel() // type_size
+    blocks = rows.reshape((n_blocks, type_size))
+    blocks = dequantize_blocks(blocks, block_size, type_size, dtype)
+    return blocks.reshape(oshape)
+
+def to_uint32(x):
+    # no uint32 :(
+    x = x.view(torch.uint8).to(torch.int32)
+    return (x[:, 0] | x[:, 1] << 8 | x[:, 2] << 16 | x[:, 3] << 24).unsqueeze(1)
+
+def to_uint16(x):
+    x = x.view(torch.uint8).to(torch.int32)
+    return (x[:, 0] | x[:, 1] << 8).unsqueeze(1)
+
+def split_block_dims(blocks, *args):
+    n_max = blocks.shape[1]
+    dims = list(args) + [n_max - sum(args)]
+    return torch.split(blocks, dims, dim=1)
+
+# Full weights #
+def dequantize_blocks_BF16(blocks, block_size, type_size, dtype=None):
+    return (blocks.view(torch.int16).to(torch.int32) << 16).view(torch.float32)
+
+# Legacy Quants #
+def dequantize_blocks_Q8_0(blocks, block_size, type_size, dtype=None):
+    d, x = split_block_dims(blocks, 2)
+    d = d.view(torch.float16).to(dtype)
+    x = x.view(torch.int8)
+    return (d * x)
+
+def dequantize_blocks_Q5_1(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, m, qh, qs = split_block_dims(blocks, 2, 2, 4)
+    d = d.view(torch.float16).to(dtype)
+    m = m.view(torch.float16).to(dtype)
+    qh = to_uint32(qh)
+
+    qh = qh.reshape((n_blocks, 1)) >> torch.arange(32, device=d.device, dtype=torch.int32).reshape(1, 32)
+    ql = qs.reshape((n_blocks, -1, 1, block_size // 2)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape(1, 1, 2, 1)
+    qh = (qh & 1).to(torch.uint8)
+    ql = (ql & 0x0F).reshape((n_blocks, -1))
+
+    qs = (ql | (qh << 4))
+    return (d * qs) + m
+
+def dequantize_blocks_Q5_0(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, qh, qs = split_block_dims(blocks, 2, 4)
+    d  = d.view(torch.float16).to(dtype)
+    qh = to_uint32(qh)
+
+    qh = qh.reshape(n_blocks, 1) >> torch.arange(32, device=d.device, dtype=torch.int32).reshape(1, 32)
+    ql = qs.reshape(n_blocks, -1, 1, block_size // 2) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape(1, 1, 2, 1)
+
+    qh = (qh & 1).to(torch.uint8)
+    ql = (ql & 0x0F).reshape(n_blocks, -1)
+
+    qs = (ql | (qh << 4)).to(torch.int8) - 16
+    return (d * qs)
+
+def dequantize_blocks_Q4_1(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, m, qs = split_block_dims(blocks, 2, 2)
+    d = d.view(torch.float16).to(dtype)
+    m = m.view(torch.float16).to(dtype)
+
+    qs = qs.reshape((n_blocks, -1, 1, block_size // 2)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape(1, 1, 2, 1)
+    qs = (qs & 0x0F).reshape(n_blocks, -1)
+
+    return (d * qs) + m
+
+def dequantize_blocks_Q4_0(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, qs = split_block_dims(blocks, 2)
+    d  = d.view(torch.float16).to(dtype)
+
+    qs = qs.reshape((n_blocks, -1, 1, block_size // 2)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2, 1))
+    qs = (qs & 0x0F).reshape((n_blocks, -1)).to(torch.int8) - 8
+    return (d * qs)
+
+# K Quants #
+QK_K = 256
+K_SCALE_SIZE = 12
+
+def get_scale_min(scales):
+    n_blocks = scales.shape[0]
+    scales = scales.view(torch.uint8)
+    scales = scales.reshape((n_blocks, 3, 4))
+
+    d, m, m_d = torch.split(scales, scales.shape[-2] // 3, dim=-2)
+
+    sc = torch.cat([d & 0x3F, (m_d & 0x0F) | ((d >> 2) & 0x30)], dim=-1)
+    min = torch.cat([m & 0x3F, (m_d >> 4) | ((m >> 2) & 0x30)], dim=-1)
+
+    return (sc.reshape((n_blocks, 8)), min.reshape((n_blocks, 8)))
+
+def dequantize_blocks_Q6_K(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    ql, qh, scales, d, = split_block_dims(blocks, QK_K // 2, QK_K // 4, QK_K // 16)
+
+    scales = scales.view(torch.int8).to(dtype)
+    d = d.view(torch.float16).to(dtype)
+    d = (d * scales).reshape((n_blocks, QK_K // 16, 1))
+
+    ql = ql.reshape((n_blocks, -1, 1, 64)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2, 1))
+    ql = (ql & 0x0F).reshape((n_blocks, -1, 32))
+    qh = qh.reshape((n_blocks, -1, 1, 32)) >> torch.tensor([0, 2, 4, 6], device=d.device, dtype=torch.uint8).reshape((1, 1, 4, 1))
+    qh = (qh & 0x03).reshape((n_blocks, -1, 32))
+    q = (ql | (qh << 4)).to(torch.int8) - 32
+    q = q.reshape((n_blocks, QK_K // 16, -1))
+
+    return (d * q).reshape((n_blocks, QK_K))
+
+def dequantize_blocks_Q5_K(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, dmin, scales, qh, qs = split_block_dims(blocks, 2, 2, K_SCALE_SIZE, QK_K // 8)
+
+    d = d.view(torch.float16).to(dtype)
+    dmin = dmin.view(torch.float16).to(dtype)
+
+    sc, m = get_scale_min(scales)
+
+    d = (d * sc).reshape((n_blocks, -1, 1))
+    dm = (dmin * m).reshape((n_blocks, -1, 1))
+
+    ql = qs.reshape((n_blocks, -1, 1, 32)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2, 1))
+    qh = qh.reshape((n_blocks, -1, 1, 32)) >> torch.tensor([i for i in range(8)], device=d.device, dtype=torch.uint8).reshape((1, 1, 8, 1))
+    ql = (ql & 0x0F).reshape((n_blocks, -1, 32))
+    qh = (qh & 0x01).reshape((n_blocks, -1, 32))
+    q = (ql | (qh << 4))
+
+    return (d * q - dm).reshape((n_blocks, QK_K))
+
+def dequantize_blocks_Q4_K(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, dmin, scales, qs = split_block_dims(blocks, 2, 2, K_SCALE_SIZE)
+    d = d.view(torch.float16).to(dtype)
+    dmin = dmin.view(torch.float16).to(dtype)
+
+    sc, m = get_scale_min(scales)
+
+    d = (d * sc).reshape((n_blocks, -1, 1))
+    dm = (dmin * m).reshape((n_blocks, -1, 1))
+
+    qs = qs.reshape((n_blocks, -1, 1, 32)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2, 1))
+    qs = (qs & 0x0F).reshape((n_blocks, -1, 32))
+
+    return (d * qs - dm).reshape((n_blocks, QK_K))
+
+def dequantize_blocks_Q3_K(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    hmask, qs, scales, d = split_block_dims(blocks, QK_K // 8, QK_K // 4, 12)
+    d = d.view(torch.float16).to(dtype)
+
+    lscales, hscales = scales[:, :8], scales[:, 8:]
+    lscales = lscales.reshape((n_blocks, 1, 8)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 2, 1))
+    lscales = lscales.reshape((n_blocks, 16))
+    hscales = hscales.reshape((n_blocks, 1, 4)) >> torch.tensor([0, 2, 4, 6], device=d.device, dtype=torch.uint8).reshape((1, 4, 1))
+    hscales = hscales.reshape((n_blocks, 16))
+    scales = (lscales & 0x0F) | ((hscales & 0x03) << 4)
+    scales = (scales.to(torch.int8) - 32)
+
+    dl = (d * scales).reshape((n_blocks, 16, 1))
+
+    ql = qs.reshape((n_blocks, -1, 1, 32)) >> torch.tensor([0, 2, 4, 6], device=d.device, dtype=torch.uint8).reshape((1, 1, 4, 1))
+    qh = hmask.reshape(n_blocks, -1, 1, 32) >> torch.tensor([i for i in range(8)], device=d.device, dtype=torch.uint8).reshape((1, 1, 8, 1))
+    ql = ql.reshape((n_blocks, 16, QK_K // 16)) & 3
+    qh = (qh.reshape((n_blocks, 16, QK_K // 16)) & 1) ^ 1
+    q = (ql.to(torch.int8) - (qh << 2).to(torch.int8))
+
+    return (dl * q).reshape((n_blocks, QK_K))
+
+def dequantize_blocks_Q2_K(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    scales, qs, d, dmin = split_block_dims(blocks, QK_K // 16, QK_K // 4, 2)
+    d = d.view(torch.float16).to(dtype)
+    dmin = dmin.view(torch.float16).to(dtype)
+
+    # (n_blocks, 16, 1)
+    dl = (d * (scales & 0xF)).reshape((n_blocks, QK_K // 16, 1))
+    ml = (dmin * (scales >> 4)).reshape((n_blocks, QK_K // 16, 1))
+
+    shift = torch.tensor([0, 2, 4, 6], device=d.device, dtype=torch.uint8).reshape((1, 1, 4, 1))
+
+    qs = (qs.reshape((n_blocks, -1, 1, 32)) >> shift) & 3
+    qs = qs.reshape((n_blocks, QK_K // 16, 16))
+    qs = dl * qs - ml
+
+    return qs.reshape((n_blocks, -1))
+
+# IQ quants
+KVALUES = torch.tensor([-127, -104, -83, -65, -49, -35, -22, -10, 1, 13, 25, 38, 53, 69, 89, 113], dtype=torch.int8)
+
+def dequantize_blocks_IQ4_NL(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+
+    d, qs = split_block_dims(blocks, 2)
+    d = d.view(torch.float16).to(dtype)
+
+    qs = qs.reshape((n_blocks, -1, 1, block_size//2)) >> torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2, 1))
+    qs = (qs & 0x0F).reshape((n_blocks, -1, 1)).to(torch.int64)
+
+    kvalues = KVALUES.to(qs.device).expand(*qs.shape[:-1], 16)
+    qs = torch.gather(kvalues, dim=-1, index=qs).reshape((n_blocks, -1))
+    del kvalues # should still be view, but just to be safe
+
+    return (d * qs)
+
+def dequantize_blocks_IQ4_XS(blocks, block_size, type_size, dtype=None):
+    n_blocks = blocks.shape[0]
+    d, scales_h, scales_l, qs = split_block_dims(blocks, 2, 2, QK_K // 64)
+    d = d.view(torch.float16).to(dtype)
+    scales_h = to_uint16(scales_h)
+
+    shift_a = torch.tensor([0, 4], device=d.device, dtype=torch.uint8).reshape((1, 1, 2))
+    shift_b = torch.tensor([2 * i for i in range(QK_K // 32)], device=d.device, dtype=torch.uint8).reshape((1, -1, 1))
+
+    scales_l = scales_l.reshape((n_blocks, -1, 1)) >> shift_a.reshape((1, 1, 2))
+    scales_h = scales_h.reshape((n_blocks, -1, 1)) >> shift_b.reshape((1, -1, 1))
+
+    scales_l = scales_l.reshape((n_blocks, -1)) & 0x0F
+    scales_h = scales_h.reshape((n_blocks, -1)).to(torch.uint8) & 0x03
+
+    scales = (scales_l | (scales_h << 4)).to(torch.int8) - 32
+    dl = (d * scales.to(dtype)).reshape((n_blocks, -1, 1))
+
+    qs = qs.reshape((n_blocks, -1, 1, 16)) >> shift_a.reshape((1, 1, 2, 1))
+    qs = qs.reshape((n_blocks, -1, 32, 1)) & 0x0F
+
+    kvalues = KVALUES.to(qs.device).expand(*qs.shape[:-1], 16)
+    qs = torch.gather(kvalues, dim=-1, index=qs.to(torch.int64)).reshape((n_blocks, -1, 32))
+    del kvalues # see IQ4_NL
+    del shift_a
+    del shift_b
+
+    return (dl * qs).reshape((n_blocks, -1))
+
+dequantize_functions = {
+    gguf.GGMLQuantizationType.BF16: dequantize_blocks_BF16,
+    gguf.GGMLQuantizationType.Q8_0: dequantize_blocks_Q8_0,
+    gguf.GGMLQuantizationType.Q5_1: dequantize_blocks_Q5_1,
+    gguf.GGMLQuantizationType.Q5_0: dequantize_blocks_Q5_0,
+    gguf.GGMLQuantizationType.Q4_1: dequantize_blocks_Q4_1,
+    gguf.GGMLQuantizationType.Q4_0: dequantize_blocks_Q4_0,
+    gguf.GGMLQuantizationType.Q6_K: dequantize_blocks_Q6_K,
+    gguf.GGMLQuantizationType.Q5_K: dequantize_blocks_Q5_K,
+    gguf.GGMLQuantizationType.Q4_K: dequantize_blocks_Q4_K,
+    gguf.GGMLQuantizationType.Q3_K: dequantize_blocks_Q3_K,
+    gguf.GGMLQuantizationType.Q2_K: dequantize_blocks_Q2_K,
+    gguf.GGMLQuantizationType.IQ4_NL: dequantize_blocks_IQ4_NL,
+    gguf.GGMLQuantizationType.IQ4_XS: dequantize_blocks_IQ4_XS,
+}

custom_nodes/ComfyUI-MiniMaxH3-Adapter/gguf_qwen35.py

@@ -0,0 +1,445 @@
+"""自定义 Qwen3.5-4B GGUF 加载器（llama.cpp qwen35 arch -> HF state dict）。
+
+动机: city96/ComfyUI-GGUF 与旧版 transformers 均不支持 qwen35 arch 的 GGUF，
+本项目自研读取 + 反量化 + 张量名映射，产出与训练 checkpoint 同格式的
+state dict（language_model.*，与 load_student 剥离前缀后一致）。
+
+本加载器的全部布局假设均经"逐张量 cos 对比真实 HauhauCS GGUF vs bf16 参考"实证
+（426/426 张量 cos>=0.99，见 diag 记录）:
+
+1. 2D 张量数据即 HF [out, in] 行序（元数据 shape 声称 [in, out]，二者相反）。
+   反量化 flat 序已是 [out, in]，reshape 成 (shape[1], shape[0]) 即可，禁止转置。
+2. 范数权重（input/post_attention/q_norm/k_norm/output_norm）GGUF 存真值 w，
+   而 HF checkpoint 存增量 (w-1)（Qwen3_5RMSNorm 前向做 * (1 + weight)），
+   加载时统一减 1.0。ssm_norm（Qwen3_5RMSNormGated）无增量约定，不减。
+3. linear_attn 的 32 个 v-head 参数（A_log/dt_bias/in_proj_a/b 行、
+   in_proj_z 及 qkv/conv1d 的 value 段）GGUF 按 value-major 枚举
+   （head = v*16 + k），HF 按 key-major（head = k*2 + v），需逆置换。
+4. ssm_a 存 -A（负衰减），HF 需 A_log = log(A)，即 log(-x) 再置换。
+
+head 配置 (qwen35_4b): 全注意力 head_dim=256; 线性层 key=16x128 value=32x128; vocab=248320
+"""
+from __future__ import annotations
+
+import os
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+try:  # ComfyUI 包内加载（节点目录不在 sys.path，必须相对导入）
+    from .gguf_dequant import dequantize_tensor
+except ImportError:  # 独立脚本/顶层加载
+    from gguf_dequant import dequantize_tensor
+
+FULL_ATTN_LAYERS = {i for i in range(32) if (i + 1) % 4 == 0}  # 3,7,11,...,31
+V_HEADS, V_PER_KEY = 32, 2  # value head 数 = 32, 每个 key head 配 2 个 value head
+
+
+class GGMLTensor(torch.Tensor):
+    """量化块驻留张量（ComfyUI-GGUF 同款）: 底层 uint8 量化字节 + 逻辑形状元数据。
+
+    前向时由 dequantize_tensor 逐层反量化，避免整模型展开的显存开销。
+    属性必须在 __new__ 设置（torch 子类实例化常跳过 __init__）。
+    """
+
+    def __new__(cls, data=None, tensor_type=None, tensor_shape=None):
+        obj = super().__new__(cls, data) if data is not None else super().__new__(cls)
+        if tensor_type is not None:
+            obj.tensor_type = tensor_type
+            obj.tensor_shape = tensor_shape
+        return obj
+
+    def to(self, *args, **kwargs):
+        kwargs.pop("dtype", None)  # 底层是量化字节，不可 cast dtype，只迁移设备
+        if args and isinstance(args[0], torch.dtype):
+            args = args[1:]
+        new = super().to(*args, **kwargs)
+        ts = getattr(self, "tensor_shape", None)
+        new.tensor_type = getattr(self, "tensor_type", None)
+        new.tensor_shape = ts if ts is not None else tuple(new.data.size())
+        return new
+
+    def clone(self, *args, **kwargs):
+        return self
+
+    def detach(self, *args, **kwargs):
+        return self
+
+    @property
+    def shape(self):
+        return self.tensor_shape
+
+
+class QuantizedLinear(nn.Module):
+    """前向时反量化权重的 Linear（ComfyUI-GGUF GGMLOps.Linear 同款，纯 torch）。
+
+    weight 为普通属性而非 Parameter: 避免 Module.to(dtype)/Parameter 包装破坏
+    GGMLTensor 的量化元数据；设备在 forward 懒迁移。
+    weight_perm: 反量化后的一次性行/列置换（处理 GGUF 的 value-major 头序）。
+    """
+
+    def __init__(self, in_features, out_features, bias=True,
+                 weight_perm=None, weight_perm_dim=None):
+        super().__init__()
+        self.in_features = in_features
+        self.out_features = out_features
+        self.weight = None
+        self.bias = None
+        self.weight_perm = weight_perm
+        self.weight_perm_dim = weight_perm_dim
+
+    def forward(self, x):
+        w = self.weight
+        if w is None:
+            w = torch.zeros(self.in_features, self.out_features, device=x.device, dtype=x.dtype)
+        if w.device != x.device:
+            w = self.weight = w.to(x.device)
+        if not isinstance(w, GGMLTensor):
+            return F.linear(x, w, self.bias)
+        w = _dequant_ggml(w, x.dtype)
+        if self.weight_perm is not None:
+            if self.weight_perm.device != x.device:
+                self.weight_perm = self.weight_perm.to(x.device)
+            w = w[self.weight_perm] if self.weight_perm_dim == 0 else w[:, self.weight_perm]
+        return F.linear(x, w, self.bias)
+
+
+class QuantizedEmbedding(nn.Module):
+    def __init__(self, num_embeddings, embedding_dim, dtype=torch.bfloat16):
+        super().__init__()
+        self.num_embeddings = num_embeddings
+        self.embedding_dim = embedding_dim
+        self.dtype = dtype
+        self.weight = None
+
+    def forward(self, x):
+        w = self.weight
+        if w is None:
+            w = torch.zeros(self.num_embeddings, self.embedding_dim, device=x.device, dtype=self.dtype)
+        if w.device != x.device:
+            w = self.weight = w.to(x.device)
+        if not isinstance(w, GGMLTensor):
+            return F.embedding(x, w)
+        w = _dequant_ggml(w, self.dtype)
+        return F.embedding(x, w)
+
+
+def _qperm_inv32() -> torch.Tensor:
+    return torch.tensor([(i % V_PER_KEY) * (V_HEADS // V_PER_KEY) + (i // V_PER_KEY)
+                         for i in range(V_HEADS)], dtype=torch.long)
+
+
+def _qperm_vrows() -> torch.Tensor:
+    """4096 行（32 头 x 128 维）value-major -> key-major 行序索引。"""
+    inv = _qperm_inv32()
+    return inv.repeat_interleave(128) * 128 + torch.arange(128).repeat(V_HEADS)
+
+
+def _qperm_qkv() -> torch.Tensor:
+    """8192 行: 前 2 段 key（各 2048 行）保持，末段 4096 行 value 置换。"""
+    v_base = 2 * (V_HEADS // V_PER_KEY) * 128  # 4096: 两段 key 行数
+    return torch.cat([torch.arange(v_base), v_base + _qperm_vrows()])
+
+
+def _dequant_ggml(w: "GGMLTensor", dtype: torch.dtype) -> torch.Tensor:
+    """GGMLTensor -> fp16/bf16。先 as_subclass 转普通张量（零拷贝）再走 city96 反量化。
+
+    不能直接传 GGMLTensor: 其派生实例（reshape/view）无 tensor_shape 元数据，
+    .data 属性同样丢失元数据，会触发 shape property 的 AttributeError。
+    """
+    from gguf import GGMLQuantizationType
+    try:
+        from .gguf_dequant import dequantize
+    except ImportError:
+        from gguf_dequant import dequantize
+
+    qtype = w.tensor_type
+    raw = w.as_subclass(torch.Tensor)
+    if qtype in (None, GGMLQuantizationType.F32, GGMLQuantizationType.F16):
+        return raw.to(dtype)
+    return dequantize(raw, qtype, w.tensor_shape, dtype=dtype).to(dtype)
+
+
+def _head_perm() -> torch.Tensor:
+    """HF key-major head i -> GGUF value-major 位置: (i % 2) * 16 + (i // 2)。"""
+    return torch.tensor([(i % V_PER_KEY) * (V_HEADS // V_PER_KEY) + (i // V_PER_KEY)
+                         for i in range(V_HEADS)], dtype=torch.long)
+
+
+def _v_reorder(w: torch.Tensor) -> torch.Tensor:
+    """GGUF value-major -> HF key-major 行序逆置换（仅 linear_attn 的 v-head 参数）。"""
+    if w.numel() == V_HEADS:
+        return w[_head_perm()]
+    if w.dim() == 2 and w.shape[0] == V_HEADS:
+        return w[_head_perm()]
+    if w.dim() == 2 and w.shape[0] == V_HEADS * 128:  # 4096 = 32 头 x 128 维
+        return w.view(V_HEADS, 128, -1)[_head_perm()].reshape(w.shape)
+    if w.dim() == 2 and w.shape[0] == 2 * V_HEADS * 128:  # 8192: 前 2 段是 key，末段是 value
+        w = w.clone()
+        w[V_HEADS * 128:] = w[V_HEADS * 128:].view(V_HEADS, 128, -1)[_head_perm()].reshape(-1, w.shape[1])
+        return w
+    if w.dim() == 2 and w.shape[1] == V_HEADS * 128:  # out_proj: value 维在列
+        return w.view(w.shape[0], V_HEADS, 128)[:, _head_perm(), :].reshape(w.shape)
+    return w
+
+
+def _dequant(t, dtype: torch.dtype = torch.float16) -> torch.Tensor:
+    """gguf ReaderTensor -> torch 反量化。
+
+    2D 张量按文件实际 [out, in] 行序 reshape；1D 按 t.shape。
+    """
+    tt = torch.from_numpy(t.data)
+    tt.tensor_type = t.tensor_type
+    tt.tensor_shape = tuple(int(s) for s in t.shape)
+    w = dequantize_tensor(tt, dtype=dtype, dequant_dtype=torch.float32)
+    if len(t.shape) == 2:
+        return w.reshape(int(t.shape[1]), int(t.shape[0])).contiguous()
+    return w.reshape(tuple(int(s) for s in t.shape)).contiguous()
+
+
+def _norm(w: torch.Tensor) -> torch.Tensor:
+    """RMSNorm 增量约定: GGUF 真值 -> HF checkpoint 格式 (w - 1)。"""
+    return w - 1.0
+
+
+def _map_gguf(path: str, quantized: bool = False):
+    """GGUF -> HF state dict。quantized=True 时量化 2D 张量产出 GGMLTensor（驻留量化块）。
+
+    返回 (sd, perms, skipped)。perms: {hf_key: (perm_tensor, dim)} 反量化后的行/列置换。
+    """
+    from gguf import GGUFReader, GGMLQuantizationType
+
+    reader = GGUFReader(path)
+    sd: dict[str, torch.Tensor] = {}
+    perms: dict[str, tuple[torch.Tensor, int]] = {}
+    skipped: list[str] = []
+
+    def qmat(t, hf_key: str, perm: torch.Tensor | None = None, dim: int = 0):
+        if quantized and t.tensor_type not in (None, GGMLQuantizationType.F32, GGMLQuantizationType.F16):
+            sd[hf_key] = GGMLTensor(torch.from_numpy(t.data), tensor_type=t.tensor_type,
+                                    tensor_shape=(int(t.shape[1]), int(t.shape[0])))
+            if perm is not None:
+                perms[hf_key] = (perm, dim)
+        else:
+            w = _dequant(t)
+            if perm is not None:
+                w = w[perm] if dim == 0 else w[:, perm]
+            sd[hf_key] = w
+
+    for t in reader.tensors:
+        n = t.name
+        if n == "token_embd.weight":
+            qmat(t, "language_model.embed_tokens.weight")
+        elif n == "output_norm.weight":
+            sd["language_model.norm.weight"] = _norm(_dequant(t))
+        elif n == "output.weight":
+            qmat(t, "language_model.lm_head.weight")
+        elif n.startswith("blk."):
+            parts = n.split(".")
+            i, rest = int(parts[1]), ".".join(parts[2:])
+            base = f"language_model.layers.{i}"
+            if rest == "attn_norm.weight":
+                sd[f"{base}.input_layernorm.weight"] = _norm(_dequant(t))
+            elif rest in ("post_attention_norm.weight", "attn_output_norm.weight"):
+                sd[f"{base}.post_attention_layernorm.weight"] = _norm(_dequant(t))
+            elif rest == "ffn_gate.weight":
+                qmat(t, f"{base}.mlp.gate_proj.weight")
+            elif rest == "ffn_up.weight":
+                qmat(t, f"{base}.mlp.up_proj.weight")
+            elif rest == "ffn_down.weight":
+                qmat(t, f"{base}.mlp.down_proj.weight")
+            elif rest == "attn_q.weight":            # Q+Gate 融合，HF q_proj 同布局
+                qmat(t, f"{base}.self_attn.q_proj.weight")
+            elif rest == "attn_k.weight":
+                qmat(t, f"{base}.self_attn.k_proj.weight")
+            elif rest == "attn_v.weight":
+                qmat(t, f"{base}.self_attn.v_proj.weight")
+            elif rest == "attn_output.weight":
+                qmat(t, f"{base}.self_attn.o_proj.weight")
+            elif rest == "attn_q_norm.weight":
+                sd[f"{base}.self_attn.q_norm.weight"] = _norm(_dequant(t))
+            elif rest == "attn_k_norm.weight":
+                sd[f"{base}.self_attn.k_norm.weight"] = _norm(_dequant(t))
+            elif rest == "attn_qkv.weight":           # 融合 qkv，v 段头序置换
+                qmat(t, f"{base}.linear_attn.in_proj_qkv.weight", perm=_qperm_qkv())
+            elif rest == "attn_gate.weight":
+                qmat(t, f"{base}.linear_attn.in_proj_z.weight", perm=_qperm_vrows())
+            elif rest == "ssm_conv1d.weight":
+                w = _v_reorder(_dequant(t))           # (conv_dim, 4) -> 深度卷积 (conv_dim, 1, 4)
+                sd[f"{base}.linear_attn.conv1d.weight"] = w.unsqueeze(1)
+            elif rest == "ssm_dt.bias":
+                sd[f"{base}.linear_attn.dt_bias"] = _v_reorder(_dequant(t))
+            elif rest in ("ssm_a", "ssm_a_noscan"):
+                sd[f"{base}.linear_attn.A_log"] = _v_reorder(-_dequant(t)).clamp_min(1e-12).log()
+            elif rest == "ssm_beta.weight":
+                qmat(t, f"{base}.linear_attn.in_proj_b.weight", perm=_qperm_inv32())
+            elif rest == "ssm_alpha.weight":
+                qmat(t, f"{base}.linear_attn.in_proj_a.weight", perm=_qperm_inv32())
+            elif rest == "ssm_norm.weight":
+                sd[f"{base}.linear_attn.norm.weight"] = _dequant(t)  # Gated 范数，无增量约定
+            elif rest == "ssm_out.weight":
+                qmat(t, f"{base}.linear_attn.out_proj.weight", perm=_qperm_vrows(), dim=1)
+            else:
+                skipped.append(n)
+        else:
+            skipped.append(n)
+
+    if skipped:
+        print(f"  [gguf] 忽略 {len(skipped)} 个未映射张量: {skipped[:6]}", flush=True)
+    return sd, perms, skipped
+
+
+def load_gguf_state_dict(path: str) -> dict[str, torch.Tensor]:
+    """fp16 全展开模式（对比/调试用）。"""
+    sd, _, _ = _map_gguf(path, quantized=False)
+    return sd
+
+
+def _build_model(config_path: str | None):
+    from transformers import AutoConfig, AutoModel
+    cfg = AutoConfig.from_pretrained(config_path or os.path.join(os.path.dirname(__file__), "qwen35_config.json"))
+    return AutoModel.from_config(cfg)
+
+
+def build_quantized_model(state_dict: dict[str, torch.Tensor],
+                          perms: dict[str, tuple[torch.Tensor, int]],
+                          config_path: str | None = None):
+    """量化模型: GGMLTensor 权重 + 前向时逐层反量化的 QuantizedLinear/Embedding。
+
+    只替换实际带量化权重的层；范数/conv1d 等普通张量走原层。
+    """
+    model = _build_model(config_path)
+    quant_keys = {k for k, v in state_dict.items() if isinstance(v, GGMLTensor)}
+
+    def walk(module, prefix: str = ""):
+        for name, child in list(module.named_children()):
+            full = f"{prefix}.{name}" if prefix else name
+            if isinstance(child, nn.Linear) and f"{full}.weight" in quant_keys:
+                perm, dim = perms.get(f"{full}.weight", (None, None))
+                setattr(module, name, QuantizedLinear(child.in_features, child.out_features,
+                                                      child.bias is not None, perm, dim))
+            elif isinstance(child, nn.Embedding) and f"{full}.weight" in quant_keys:
+                setattr(module, name, QuantizedEmbedding(child.num_embeddings, child.embedding_dim))
+            else:
+                walk(child, full)
+
+    walk(model)
+    for k, v in state_dict.items():
+        parts = k.split(".")
+        obj = model
+        for p in parts[:-1]:
+            obj = getattr(obj, p)
+        # GGMLTensor 不包 Parameter（推理无梯度，且 Parameter 会破坏量化元数据）
+        setattr(obj, parts[-1], v if isinstance(v, GGMLTensor)
+                else torch.nn.Parameter(v, requires_grad=False))
+    model_keys = set(model.state_dict()) | {k for k, v in state_dict.items() if isinstance(v, GGMLTensor)}
+    unexpected = sorted(set(state_dict) - model_keys)
+    return model, unexpected
+
+
+def load_gguf_state_dict(path: str) -> dict[str, torch.Tensor]:
+    from gguf import GGUFReader
+
+    reader = GGUFReader(path)
+    sd: dict[str, torch.Tensor] = {}
+    skipped: list[str] = []
+
+    for t in reader.tensors:
+        n = t.name
+        if n == "token_embd.weight":
+            sd["language_model.embed_tokens.weight"] = _dequant(t)
+        elif n == "output_norm.weight":
+            sd["language_model.norm.weight"] = _norm(_dequant(t))
+        elif n == "output.weight":
+            sd["language_model.lm_head.weight"] = _dequant(t)  # 可能绑定 embed，可缺省
+        elif n.startswith("blk."):
+            parts = n.split(".")
+            i, rest = int(parts[1]), ".".join(parts[2:])
+            base = f"language_model.layers.{i}"
+            if rest == "attn_norm.weight":
+                sd[f"{base}.input_layernorm.weight"] = _norm(_dequant(t))
+            elif rest in ("post_attention_norm.weight", "attn_output_norm.weight"):
+                sd[f"{base}.post_attention_layernorm.weight"] = _norm(_dequant(t))
+            elif rest == "ffn_gate.weight":
+                sd[f"{base}.mlp.gate_proj.weight"] = _dequant(t)
+            elif rest == "ffn_up.weight":
+                sd[f"{base}.mlp.up_proj.weight"] = _dequant(t)
+            elif rest == "ffn_down.weight":
+                sd[f"{base}.mlp.down_proj.weight"] = _dequant(t)
+            elif rest == "attn_q.weight":            # Q+Gate 融合，HF q_proj 同布局
+                sd[f"{base}.self_attn.q_proj.weight"] = _dequant(t)
+            elif rest == "attn_k.weight":
+                sd[f"{base}.self_attn.k_proj.weight"] = _dequant(t)
+            elif rest == "attn_v.weight":
+                sd[f"{base}.self_attn.v_proj.weight"] = _dequant(t)
+            elif rest == "attn_output.weight":
+                sd[f"{base}.self_attn.o_proj.weight"] = _dequant(t)
+            elif rest == "attn_q_norm.weight":
+                sd[f"{base}.self_attn.q_norm.weight"] = _norm(_dequant(t))
+            elif rest == "attn_k_norm.weight":
+                sd[f"{base}.self_attn.k_norm.weight"] = _norm(_dequant(t))
+            elif rest == "attn_qkv.weight":           # 融合 qkv，HF in_proj_qkv 同布局
+                sd[f"{base}.linear_attn.in_proj_qkv.weight"] = _v_reorder(_dequant(t))
+            elif rest == "attn_gate.weight":
+                sd[f"{base}.linear_attn.in_proj_z.weight"] = _v_reorder(_dequant(t))
+            elif rest == "ssm_conv1d.weight":
+                w = _v_reorder(_dequant(t))           # (conv_dim, 4) -> 深度卷积 (conv_dim, 1, 4)
+                sd[f"{base}.linear_attn.conv1d.weight"] = w.unsqueeze(1)
+            elif rest == "ssm_dt.bias":
+                sd[f"{base}.linear_attn.dt_bias"] = _v_reorder(_dequant(t))
+            elif rest in ("ssm_a", "ssm_a_noscan"):
+                sd[f"{base}.linear_attn.A_log"] = _v_reorder(-_dequant(t)).clamp_min(1e-12).log()
+            elif rest == "ssm_beta.weight":
+                sd[f"{base}.linear_attn.in_proj_b.weight"] = _v_reorder(_dequant(t))
+            elif rest == "ssm_alpha.weight":
+                sd[f"{base}.linear_attn.in_proj_a.weight"] = _v_reorder(_dequant(t))
+            elif rest == "ssm_norm.weight":
+                sd[f"{base}.linear_attn.norm.weight"] = _dequant(t)  # Gated 范数，无增量约定
+            elif rest == "ssm_out.weight":
+                sd[f"{base}.linear_attn.out_proj.weight"] = _v_reorder(_dequant(t))
+            else:
+                skipped.append(n)
+        else:
+            skipped.append(n)
+
+    if skipped:
+        print(f"  [gguf] 忽略 {len(skipped)} 个未映射张量: {skipped[:6]}", flush=True)
+    return sd
+
+
+def build_hf_model(state_dict: dict[str, torch.Tensor], config_path: str | None = None):
+    """按 state dict 构建 HF 模型（Qwen3_5Model）。
+
+    vision 权重缺省（text-only GGUF）属正常；仅用 language_model 子模块前向。
+    返回 (model, missing, unexpected)。
+    """
+    from transformers import AutoConfig, AutoModel
+
+    cfg = AutoConfig.from_pretrained(config_path or os.path.join(os.path.dirname(__file__), "qwen35_config.json"))
+    model = AutoModel.from_config(cfg)
+    missing, unexpected = model.load_state_dict(state_dict, strict=False)
+    return model, missing, unexpected
+
+
+def load_gguf_model(path: str, config_path: str | None = None):
+    """fp16 全展开加载（对比/调试用）。返回 (model, info)。"""
+    sd, _, _ = _map_gguf(path, quantized=False)
+    model, missing, unexpected = build_hf_model(sd, config_path)
+    return model, {"keys": len(sd), "missing": len(missing), "unexpected": len(unexpected)}
+
+
+def load_gguf_model_quantized(path: str, config_path: str | None = None):
+    """量化驻留加载（ComfyUI 生产路径）: 量化块���驻，前向时逐层反量化。
+
+    embed/lm_head 在加载期 CPU 一次性反量化成 bf16（GPU 上 Q6_K 反量化的
+    float32 中间张量峰值达数 GB，远大于 1.27GB 常驻收益）。
+    返回 (model, info)。
+    """
+    sd, perms, _ = _map_gguf(path, quantized=True)
+    for k in ("language_model.embed_tokens.weight", "language_model.lm_head.weight"):
+        v = sd.get(k)
+        if isinstance(v, GGMLTensor):
+            sd[k] = _dequant_ggml(v, torch.bfloat16)
+    model, unexpected = build_quantized_model(sd, perms, config_path)
+    return model, {"keys": len(sd), "missing": 0, "unexpected": len(unexpected), "quantized": True}

custom_nodes/ComfyUI-MiniMaxH3-Adapter/inspect_gguf.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""检查 GGUF 文件的张量布局（自定义加载器的映射依据）。
+
+用法:
+    python inspect_gguf.py <模型.gguf> [--limit 200]
+输出:
+    - 每个张量的名字 / 形状 / 量化类型（按层分组）
+    - 顶层张量（token_embd / output_norm / output）
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("gguf_path")
+    ap.add_argument("--limit", type=int, default=0, help="只显示前 N 个张量（默认全量）")
+    args = ap.parse_args()
+
+    try:
+        from gguf import GGUFReader
+    except ImportError as e:
+        print(f"需要 gguf 包: pip install gguf ({e})")
+        sys.exit(1)
+
+    reader = GGUFReader(args.gguf_path)
+    tensors = reader.tensors
+    print(f"文件: {args.gguf_path}")
+    print(f"张量总数: {len(tensors)}")
+    try:
+        arch = reader.fields.get("general.architecture")
+        print(f"architecture: {arch.parts[-1] if arch else '?'}")
+    except Exception:
+        pass
+
+    # 按层分组
+    from collections import OrderedDict
+    layers: dict[str, list] = OrderedDict()
+    top = []
+    for t in tensors:
+        name = t.name
+        if name.startswith("blk."):
+            layer = name.split(".")[1]
+            layers.setdefault(layer, []).append(t)
+        else:
+            top.append(t)
+
+    print(f"\n===== 顶层张量 ({len(top)}) =====")
+    for t in top:
+        print(f"  {t.name}  shape={list(t.shape)}  {t.tensor_type.name}")
+
+    shown = 0
+    for layer, ts in layers.items():
+        print(f"\n===== 第 {layer} 层 ({len(ts)} 张量) =====")
+        for t in ts:
+            print(f"  {t.name}  shape={list(t.shape)}  {t.tensor_type.name}")
+            shown += 1
+            if args.limit and shown >= args.limit:
+                print("...(截断)")
+                sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-MiniMaxH3-Adapter/nodes.py

@@ -0,0 +1,129 @@
+"""ComfyUI 节点: MiniMax H3 Adapter Loader（假 CLIP 注入）。
+
+用法（T2V 工作流）:
+    UNETLoader(fl2va) -> model
+    MiniMaxH3AdapterLoader(student=<Qwen3.5-4B 文件夹>, adapter=<adapter.safetensors>) -> clip
+    VAELoader(video_vae) -> vae
+    MiniMaxH3ImageToVideo(clip=clip, vae=vae, prompt=..., width, height, length) -> positive + latent
+    BasicGuider(model, positive) -> RandomNoise -> SamplerCustomAdvanced -> VAEDecode -> SaveVideo
+
+原理:
+    ComfyUI 的 MiniMaxH3 DiT (comfy/ldm/minimax/model.py) 在
+    preprocess_text_embeds / _forward 中条件式跳过投影:
+        if text_states.shape[-1] != self.hidden_size:  # 5376
+            text_states = token_refiner(condition_proj(text_states))
+    适配器输出已是 [1, S_T, 5376]（post-refiner），DiT 直接使用，零手术。
+
+    官方 MiniMaxH3ImageToVideo 只对 clip 调用 tokenize(prompt) +
+    encode_from_tokens_scheduled(tokens)，故用鸭子类型 CLIP 对象替换即可，
+    latent 创建 / keyframe / duration 网格全部保留。
+"""
+from __future__ import annotations
+
+import os
+
+import torch
+
+import folder_paths
+import comfy.utils
+import comfy.model_management as mm
+
+from .adapter.model import H3Adapter
+from .adapter_clip import MiniMaxH3AdapterCLIP, MiniMaxH3AdapterFromCLIP
+from .student import StudentTextEncoder, get_torch_device
+
+ADAPTER_FOLDER = "minimax_h3_adapter"   # models/minimax_h3_adapter/
+STUDENT_FOLDER = "minimax_h3_student"   # -> models/text_encoders/
+
+
+def _h3_tokenizer() -> object:
+    from transformers import AutoTokenizer
+    tok_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "tokenizer")
+    return AutoTokenizer.from_pretrained(tok_dir)
+
+
+def _student_folder_options() -> list[str]:
+    """models/text_encoders/ 下的子目录（HF 格式）或 .gguf 文件（transformers GGUF 加载）。"""
+    opts = []
+    for root in folder_paths.get_folder_paths(STUDENT_FOLDER):
+        if os.path.isdir(root):
+            opts += [d for d in sorted(os.listdir(root))
+                     if os.path.isdir(os.path.join(root, d)) and os.path.exists(os.path.join(root, d, "config.json"))]
+            opts += [f for f in sorted(os.listdir(root)) if f.endswith(".gguf")]
+    return opts or ["<把 Qwen3.5-4B 文件夹或 .gguf 放到 models/text_encoders/>"]
+
+
+class MiniMaxH3AdapterLoader:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {"required": {
+            "student": (_student_folder_options(),),
+            "adapter": (folder_paths.get_filename_list(ADAPTER_FOLDER),),
+        }, "optional": {
+            # 留空 = 整卡；24GB 及以下填 "16GiB" 等启用层间 offload
+            "gpu_mem": ("STRING", {"default": ""}),
+        }}
+
+    RETURN_TYPES = ("CLIP",)
+    RETURN_NAMES = ("clip",)
+    FUNCTION = "load_adapter"
+    CATEGORY = "model/conditioning/minimax"
+
+    def load_adapter(self, student: str, adapter: str, gpu_mem: str = ""):
+        dev = get_torch_device()
+        model = _load_adapter_weights(adapter, dev)
+
+        student_root = folder_paths.get_folder_paths(STUDENT_FOLDER)[0]
+        student_dir = os.path.join(student_root, student)
+        stu = StudentTextEncoder(student_dir, lowvram=True, gpu_mem=gpu_mem)
+
+        tok = _h3_tokenizer()
+        clip = MiniMaxH3AdapterCLIP(model, stu, tok, dev)
+        return (clip,)
+
+
+def _load_adapter_weights(adapter: str, dev: torch.device) -> H3Adapter:
+    """加载适配器 safetensors -> bf16 H3Adapter（容错 model. 前缀）。"""
+    adapter_path = folder_paths.get_full_path(ADAPTER_FOLDER, adapter)
+    sd = comfy.utils.load_torch_file(adapter_path)
+    if any(k.startswith("model.") for k in sd):
+        sd = {k[len("model."):]: v for k, v in sd.items()}
+    model = H3Adapter().to(torch.bfloat16)
+    missing, unexpected = model.load_state_dict(sd, strict=False)
+    assert not missing, f"adapter 缺 key: {missing[:10]}"
+    if unexpected:
+        print(f"    [adapter] ignored {len(unexpected)} unexpected keys", flush=True)
+    model.to(dev).eval()
+    for m in model.modules():
+        if hasattr(m, "use_sdpa"):
+            m.use_sdpa = True
+    print(f"    [adapter] loaded {adapter} ({sum(p.numel() for p in model.parameters())/1e9:.3f}B)", flush=True)
+    return model
+
+
+class MiniMaxH3AdapterFromCLIPLoader:
+    """CLIP→CLIP 包装: 学生 CLIP（CLIPLoader GGUF 等）的 encode 输出经适配器 -> 可喂给官方 MiniMaxH3ImageToVideo。
+
+    工作流:
+        CLIPLoader(GGUF, 学生模型) -> clip
+        MiniMaxH3AdapterFromCLIPLoader(clip=clip, adapter=adapter_stage2.safetensors) -> clip'
+        MiniMaxH3ImageToVideo(clip=clip', ...)  # 官方节点原样
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {"required": {
+            "clip": ("CLIP",),
+            "adapter": (folder_paths.get_filename_list(ADAPTER_FOLDER),),
+        }}
+
+    RETURN_TYPES = ("CLIP",)
+    RETURN_NAMES = ("clip",)
+    FUNCTION = "wrap_clip"
+    CATEGORY = "model/conditioning/minimax"
+
+    def wrap_clip(self, clip, adapter):
+        dev = get_torch_device()
+        model = _load_adapter_weights(adapter, dev)
+        wrapped = MiniMaxH3AdapterFromCLIP(clip, model, _h3_tokenizer(), dev)
+        return (wrapped,)

custom_nodes/ComfyUI-MiniMaxH3-Adapter/qwen35_config.json

@@ -0,0 +1,104 @@
+{
+    "architectures": [
+        "Qwen3_5ForConditionalGeneration"
+    ],
+    "image_token_id": 248056,
+    "model_type": "qwen3_5",
+    "text_config": {
+        "attention_bias": false,
+        "attention_dropout": 0.0,
+        "attn_output_gate": true,
+        "dtype": "bfloat16",
+        "eos_token_id": 248044,
+        "full_attention_interval": 4,
+        "head_dim": 256,
+        "hidden_act": "silu",
+        "hidden_size": 2560,
+        "initializer_range": 0.02,
+        "intermediate_size": 9216,
+        "layer_types": [
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention"
+        ],
+        "linear_conv_kernel_dim": 4,
+        "linear_key_head_dim": 128,
+        "linear_num_key_heads": 16,
+        "linear_num_value_heads": 32,
+        "linear_value_head_dim": 128,
+        "max_position_embeddings": 262144,
+        "mlp_only_layers": [],
+        "model_type": "qwen3_5_text",
+        "mtp_num_hidden_layers": 1,
+        "mtp_use_dedicated_embeddings": false,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 4,
+        "rms_norm_eps": 1e-06,
+        "tie_word_embeddings": true,
+        "use_cache": true,
+        "vocab_size": 248320,
+        "mamba_ssm_dtype": "float32",
+        "rope_parameters": {
+            "mrope_interleaved": true,
+            "mrope_section": [
+                11,
+                11,
+                10
+            ],
+            "rope_type": "default",
+            "rope_theta": 10000000,
+            "partial_rotary_factor": 0.25
+        }
+    },
+    "tie_word_embeddings": true,
+    "transformers_version": "4.57.0.dev0",
+    "video_token_id": 248057,
+    "vision_config": {
+        "deepstack_visual_indexes": [],
+        "depth": 24,
+        "hidden_act": "gelu_pytorch_tanh",
+        "hidden_size": 1024,
+        "in_channels": 3,
+        "initializer_range": 0.02,
+        "intermediate_size": 4096,
+        "model_type": "qwen3_5",
+        "num_heads": 16,
+        "num_position_embeddings": 2304,
+        "out_hidden_size": 2560,
+        "patch_size": 16,
+        "spatial_merge_size": 2,
+        "temporal_patch_size": 2
+    },
+    "vision_end_token_id": 248054,
+    "vision_start_token_id": 248053
+}

custom_nodes/ComfyUI-MiniMaxH3-Adapter/student.py

@@ -0,0 +1,161 @@
+"""Qwen3.5-4B 学生模型加载 + 隐藏态提取 + ComfyUI 感知的显存 offload。
+
+load_student 移植自训练管线 extract_student_features.py:
+    - 修复 checkpoint 的 `model.` 多余前缀（否则全层随机初始化）
+    - 隐藏态取 hidden_states[-1]（tie_last_hidden_states -> post-final-norm，与训练/评估同源）
+"""
+from __future__ import annotations
+
+import json
+import os
+from collections import defaultdict
+
+import torch
+
+try:  # ComfyUI 内运行
+    import comfy.model_management as comfy_mm
+
+    def get_torch_device() -> torch.device:
+        return comfy_mm.get_torch_device()
+
+    def soft_empty_cache() -> None:
+        comfy_mm.soft_empty_cache()
+except ImportError:  # 独立测试环境
+    def get_torch_device() -> torch.device:
+        return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    def soft_empty_cache() -> None:
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+
+def load_student(model_dir: str) -> torch.nn.Module:
+    """加载 Qwen3.5-4B 权重（CPU），剥离 `model.` 前缀。
+
+    model_dir 为 .gguf 文件时走自研加载器（gguf_qwen35）:
+    读取 + 反量化 + 张量名映射均自实现，不依赖 transformers 的 GGUF 支持，
+    产出与训练 checkpoint 同格式的 state dict。
+    """
+    from safetensors import safe_open
+    from transformers import AutoConfig, AutoModel
+
+    if model_dir.endswith(".gguf"):
+        try:
+            from . import gguf_qwen35
+        except ImportError:
+            import gguf_qwen35
+        # 生产路径: 量化块驻留 + 前向逐层反量化（显存 ≈ 量化大小而非 fp16 展开）
+        model, info = gguf_qwen35.load_gguf_model_quantized(model_dir)
+        print(f"    [student] GGUF loaded: {info}", flush=True)
+        return model
+
+    cfg = AutoConfig.from_pretrained(model_dir)
+    model = AutoModel.from_config(cfg)  # 无权重实例化，避免 from_pretrained 错误初始化
+    index = json.load(open(os.path.join(model_dir, "model.safetensors.index.json")))
+    by_shard: dict[str, list[str]] = defaultdict(list)
+    for k, sh in index["weight_map"].items():
+        by_shard[sh].append(k)
+    sd: dict[str, torch.Tensor] = {}
+    for shard, keys in by_shard.items():
+        with safe_open(os.path.join(model_dir, shard), framework="pt", device="cpu") as sf:
+            for k in keys:
+                newk = k[len("model."):] if k.startswith("model.") else k
+                sd[newk] = sf.get_tensor(k)
+    missing, unexpected = model.load_state_dict(sd, strict=False)
+    del sd
+    assert not missing, f"missing after prefix strip: {missing[:10]}"
+    if unexpected:
+        print(f"    [student] ignored {len(unexpected)} unexpected keys (e.g. {unexpected[:3]})", flush=True)
+    return model
+
+
+def find_language_model(model: torch.nn.Module) -> torch.nn.Module:
+    for name in ("language_model", "model", "text_model"):
+        if hasattr(model, name):
+            sub = getattr(model, name)
+            if hasattr(sub, "layers") or hasattr(sub, "config"):
+                return sub
+    raise RuntimeError(f"cannot locate language model submodule; attrs={[n for n in dir(model) if not n.startswith('_')]}")
+
+
+def _move_plain_tensors(module: torch.nn.Module, device: torch.device) -> None:
+    """迁移普通 tensor 属性（GGMLTensor 量化权重/embed 权重等非 Parameter/buffer）。
+
+    nn.Module.to() 只迁移 Parameter 与 registered buffer，量化权重是普通属性，
+    必须手动搬——否则 encode 后 offload 不彻底，量化权重滞留 GPU。
+    """
+    for name, attr in list(module.__dict__.items()):
+        if isinstance(attr, torch.Tensor) and not isinstance(attr, torch.nn.Parameter):
+            setattr(module, name, attr.to(device))
+    for child in module.children():
+        _move_plain_tensors(child, device)
+
+
+class StudentTextEncoder:
+    """学生模型封装: prompt -> [S_S, 2560] bf16 hidden（post-final-norm）。
+
+    gpu_mem=""（默认）: 整模型进 GPU；encode 后 lowvram 搬回 CPU。
+    gpu_mem="5GiB"/"16GiB" 等: accelerate 层间 offload（权重驻留 RAM、按层流式进 GPU），
+        适合 24GB 及以下卡（33B DiT + 4B 学生错峰）。
+    lowvram=True（默认）: encode 完成后立即释放 GPU 占用，让位给 DiT 采样。
+    """
+
+    def __init__(self, model_dir: str, dtype: torch.dtype = torch.bfloat16,
+                 lowvram: bool = True, gpu_mem: str = ""):
+        self.model_dir = model_dir
+        self.dtype = dtype
+        self.lowvram = lowvram
+        self.gpu_mem = gpu_mem
+        self._dispatched = False
+        self._model: torch.nn.Module | None = None
+        self._lm: torch.nn.Module | None = None
+        self._tok = None
+
+    def _ensure_ready(self):
+        if self._model is None:
+            from transformers import AutoTokenizer
+            model = load_student(self.model_dir).to(self.dtype)
+            if self.gpu_mem:
+                from accelerate import dispatch_model, infer_auto_device_map
+                max_memory = {"cpu": "20GiB", 0: self.gpu_mem}
+                no_split = getattr(model, "_no_split_modules", None) or None
+                device_map = infer_auto_device_map(model, max_memory=max_memory,
+                                                   no_split_module_classes=no_split)
+                dispatch_model(model, device_map=device_map)
+                self._dispatched = True
+            self._model = model
+            self._lm = find_language_model(self._model)
+            if self.model_dir.endswith(".gguf"):
+                tok_dir = os.path.dirname(self.model_dir)
+                if not os.path.exists(os.path.join(tok_dir, "tokenizer.json")):
+                    raise RuntimeError(
+                        f"GGUF 同目录 {tok_dir} 缺少 tokenizer.json —— 请把 Qwen3.5-4B 的 tokenizer 文件"
+                        "（tokenizer.json / tokenizer_config.json / vocab.json / merges.txt / chat_template.jinja）拷到该目录")
+                self._tok = AutoTokenizer.from_pretrained(tok_dir)
+            else:
+                self._tok = AutoTokenizer.from_pretrained(self.model_dir)
+            print(f"    [student] loaded {self.model_dir} (gpu_mem={self.gpu_mem or 'whole'})", flush=True)
+        dev = get_torch_device()
+        if not self._dispatched and next(self._lm.parameters()).device != dev:
+            self._model.to(dev)
+
+    def offload(self) -> None:
+        if self._lm is None:
+            return
+        if self._dispatched:
+            soft_empty_cache()
+            return
+        self._model.to("cpu")
+        _move_plain_tensors(self._model, torch.device("cpu"))
+        soft_empty_cache()
+
+    @torch.no_grad()
+    def __call__(self, prompt: str) -> torch.Tensor:
+        self._ensure_ready()
+        dev = get_torch_device()
+        ids = self._tok(prompt, add_special_tokens=False)["input_ids"]
+        out = self._lm(input_ids=torch.tensor([ids], device=dev), output_hidden_states=True)
+        h = out.hidden_states[-1][0].to(self.dtype)  # [S_S, 2560] post-final-norm
+        if self.lowvram:
+            self.offload()
+        return h

custom_nodes/ComfyUI-MiniMaxH3-Adapter/test_fake_clip.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""本地冒烟: 验证 MiniMaxH3AdapterCLIP 契约（无 ComfyUI 依赖也可跑）。
+
+模式:
+    python test_fake_clip.py                     # quick: 假 student_fn，验证契约/形状/tags/透传
+    python test_fake_clip.py --real-student <qwen35 目录>   # 真实 4B: 全链路 + offload 后显存回落
+
+验证点:
+    1. tokenize(prompt) 捕获官方节点传入的 prompt
+    2. encode_from_tokens_scheduled -> CONDITIONING [[embeds, {"minimax_token_tags": tags}]]
+       - embeds [1, S_T, 5376] fp16 finite, tags [S_T] 全 1 long, S_T == len(h3 ids)
+    3. 5376 透传: 复刻 ComfyUI MiniMaxH3Model.preprocess_text_embeds —— shape[-1]==5376 恒等
+    4. add_dict 路径 (conditioning_set_values)
+    5. --real-student: encode 后学生模型已 offload（GPU 显存回落）
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import torch
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+from adapter.model import H3Adapter  # noqa: E402
+from student import StudentTextEncoder, get_torch_device, soft_empty_cache  # noqa: E402
+
+PROMPTS = [
+    "A cinematic shot of a tiny robot repairing a broken music box in a giant's attic, dust motes floating in the light",
+    "Close-up of papercraft hands folding an origami crane, warm studio light, shallow depth of field",
+]
+
+
+def comfy_preprocess_text_embeds(text_states, hidden_size: int = 5376):
+    """复刻 comfy/ldm/minimax/model.py preprocess_text_embeds（仅判定分支）。"""
+    if text_states.shape[-1] == hidden_size:
+        return text_states
+    raise AssertionError("输入不是 5376 维 -> 会被 condition_proj+token_refiner 处理（不应发生）")
+
+
+def conditioning_set_values(cond, new_values):
+    """node_helpers.conditioning_set_values 的 torch 版（无 ComfyUI 依赖）。"""
+    if len(cond) == 1 and len(cond[0][1]) == 0:
+        return [[cond[0][0], new_values]]
+    return [[c[0], {**c[1], **new_values}] for c in cond]
+
+
+def run_checks(clip, prompts, tag: str) -> int:
+    fails = 0
+    for p in prompts:
+        clip.tokenize(p)  # 官方节点会调 tokenize
+        cond = clip.encode_from_tokens_scheduled({})
+        assert len(cond) == 1, "CONDITIONING 应含 1 个元素"
+        embeds, extras = cond[0]
+        s_t = embeds.shape[1]
+        ids = clip._tok(p, add_special_tokens=False)["input_ids"]
+
+        checks = {
+            "embeds.shape == [1, S_T, 5376]": tuple(embeds.shape) == (1, s_t, 5376),
+            "S_T == len(h3 ids)": s_t == len(ids),
+            "dtype fp16": embeds.dtype == torch.float16,
+            "finite": bool(torch.isfinite(embeds).all()),
+            "extras 含 minimax_token_tags": "minimax_token_tags" in extras,
+            "tags 长度 == S_T": extras["minimax_token_tags"].shape[0] == s_t,
+            "tags 全 1": bool((extras["minimax_token_tags"] == 1).all()),
+            "tags dtype long": extras["minimax_token_tags"].dtype == torch.long,
+        }
+        # 5376 透传: DiT 应直接使用
+        passthrough = comfy_preprocess_text_embeds(embeds)
+        checks["preprocess_text_embeds 5376 透传恒等"] = torch.equal(passthrough, embeds)
+
+        for name, ok in checks.items():
+            print(f"  [{'PASS' if ok else 'FAIL'}] {name}")
+            fails += 0 if ok else 1
+    print(f"--- {tag}: {'全部通过' if fails == 0 else f'{fails} 项失败'}")
+    return fails
+
+
+def check_wrapper_path(adapter, tok, dev) -> int:
+    """验证 MiniMaxH3AdapterFromCLIP: 内层学生 CLIP 的 encode 输出被正确消费。"""
+    from adapter_clip import MiniMaxH3AdapterFromCLIP
+
+    class FakeInnerCLIP:
+        """模拟 CLIPLoader(GGUF) 的 CLIP 对象契约（内层在 CPU 低显存模式——复现真实报错场景）。"""
+        def tokenize(self, prompt, images=None, **kwargs):
+            return {"g": prompt}
+
+        @torch.no_grad()
+        def encode_from_tokens(self, tokens, return_pooled=False, return_dict=False):
+            p = tokens["g"]
+            s_s = max(1, len(tok(p, add_special_tokens=False)["input_ids"]) // 2)
+            emb = torch.randn(1, s_s, 2560, dtype=torch.float16, device="cpu") * 0.1  # CPU!
+            return [[emb, {}]]
+
+    wrapped = MiniMaxH3AdapterFromCLIP(FakeInnerCLIP(), adapter, tok, dev)
+    assert next(adapter.parameters()).device != torch.device("cpu"), "测试前提: 适配器应在 GPU"
+    print("--- 包装器路径 (CLIPLoader(GGUF, CPU) -> 适配器(GPU) -> 官方节点):")
+    return run_checks(wrapped, PROMPTS, "CLIP→CLIP 包装(内层CPU)")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--real-student", default="", help="Qwen3.5-4B 目录（真实全链路 + offload 验证）")
+    ap.add_argument("--device", default="")
+    args = ap.parse_args()
+
+    dev = torch.device(args.device) if args.device else get_torch_device()
+    print(f"device: {dev}")
+
+    # 适配器: 随机初始化（机制验证；真实权重在云端导出的 safetensors）
+    adapter = H3Adapter().to(torch.bfloat16).to(dev).eval()
+    for m in adapter.modules():
+        if hasattr(m, "use_sdpa"):
+            m.use_sdpa = True
+
+    from transformers import AutoTokenizer
+    tok = AutoTokenizer.from_pretrained(os.path.join(HERE, "tokenizer"))
+    print(f"tokenizer: {type(tok).__name__} | vocab={tok.vocab_size}")
+
+    if args.real_student:
+        stu = StudentTextEncoder(args.real_student, lowvram=True, gpu_mem="5GiB")
+        tag = "真实学生模型(dispatch offload)"
+    else:
+        # 假 student_fn: 返回随机 [S_S, 2560]（S_S 与 prompt token 数成比例）
+        def fake_student(prompt: str) -> torch.Tensor:
+            s_s = max(1, len(tok(prompt, add_special_tokens=False)["input_ids"]) // 2)
+            return torch.randn(s_s, 2560, dtype=torch.bfloat16, device=dev) * 0.1
+        stu = type("FakeStudent", (), {"__call__": staticmethod(fake_student)})()
+        tag = "假学生模型(机制验证)"
+
+    from adapter_clip import MiniMaxH3AdapterCLIP
+    clip = MiniMaxH3AdapterCLIP(adapter, stu, tok, dev)
+
+    fails = run_checks(clip, PROMPTS, tag)
+    fails += check_wrapper_path(adapter, tok, dev)
+
+    # add_dict 路径（模拟官方节点传入 keyframes 等 extras）
+    clip.tokenize(PROMPTS[0])
+    cond = clip.encode_from_tokens_scheduled({}, add_dict={"minimax_frame_count": 124})
+    assert "minimax_frame_count" in cond[0][1], "add_dict 未并入 extras"
+    print("  [PASS] add_dict 并入 conditioning extras")
+
+    if args.real_student:
+        # offload 验证: 整卡模式 -> 已搬回 CPU; dispatch 模式 -> 权重层间驻留(首层在 CPU)
+        lm = stu._lm
+        on_cpu = next(lm.parameters()).device.type == "cpu" or stu._dispatched
+        print(f"  [{'PASS' if on_cpu else 'FAIL'}] encode 后学生模型已释放 GPU 常驻 (dispatched={stu._dispatched})")
+        fails += 0 if on_cpu else 1
+        if torch.cuda.is_available():
+            free = torch.cuda.mem_get_info()[0] / 2 ** 30
+            print(f"  [info] encode 后 GPU 可用显存 {free:.1f} GiB")
+
+    print("SMOKE", "PASS ✅" if fails == 0 else f"FAIL ({fails})")
+    raise SystemExit(0 if fails == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-MiniMaxH3-Adapter/test_gguf_loader.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""合成迷你 GGUF 回环测试: 复刻真实 HauhauCS GGUF 的全部布局约定
+（2D 数据 [out,in] + 元数据 [in,out]、v-head value-major 置换、范数增量 -1、ssm_a 存 -A），
+验证 gguf_qwen35 加载器的映射/反量化/置换/变换正确，含数值断言（cos）。
+
+量化类型用 Q8_0（gguf 库支持量化；Q4_K 反量化已由真实文件 426/426 逐张量验证）。
+
+用法: python test_gguf_loader.py [--keep]（--keep 保留临时文件供 inspect_gguf 查看）
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+
+import numpy as np
+import torch
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+N_EMBD = 2560
+FFN = 9216
+N_HEAD, N_HEAD_KV, HEAD_DIM = 16, 4, 256
+L_KEY_HEADS, L_KEY_HD, L_V_HEADS, L_V_HD = 16, 128, 32, 128
+CONV_K = 4
+
+GGUF_TO_HF = np.array([(i % 16) * 2 + (i // 16) for i in range(32)], dtype=np.int64)
+
+
+def hf_to_gguf(x):
+    return x[GGUF_TO_HF]
+
+
+def w2d(rng, out, inn):
+    return rng.standard_normal((out, inn)).astype(np.float32)
+
+
+def add2d(w, name, data, qtype=None):
+    from gguf.quants import quantize
+    from gguf import GGML_QUANT_SIZES
+    out, inn = int(data.shape[0]), int(data.shape[1])
+    if qtype is not None:
+        data = quantize(np.ascontiguousarray(data), qtype)
+        block, tsize = GGML_QUANT_SIZES[qtype]
+        w.add_tensor(name, data, raw_shape=(out, inn * tsize // block), raw_dtype=qtype)
+    else:
+        w.add_tensor(name, data, raw_shape=(out, inn))
+
+
+def add1d(w, name, data):
+    w.add_tensor(name, data)
+
+
+def add_layer(w, rng, i: int, is_full: bool, expect: dict):
+    base = f"blk.{i}"
+    pref = f"language_model.layers.{i}."
+    norm_in = w2d(rng, N_EMBD, 1).ravel() + 0.5
+    norm_out = w2d(rng, N_EMBD, 1).ravel() + 0.5
+    add1d(w, f"{base}.attn_norm.weight", norm_in)
+    add1d(w, f"{base}.post_attention_norm.weight", norm_out)
+    expect[f"{pref}input_layernorm.weight"] = norm_in - 1.0
+    expect[f"{pref}post_attention_layernorm.weight"] = norm_out - 1.0
+    gate = w2d(rng, FFN, N_EMBD)
+    up = w2d(rng, FFN, N_EMBD)
+    down = w2d(rng, N_EMBD, FFN)
+    add2d(w, f"{base}.ffn_gate.weight", gate, qtype=Q8)
+    add2d(w, f"{base}.ffn_up.weight", up, qtype=Q8)
+    add2d(w, f"{base}.ffn_down.weight", down, qtype=Q8)
+    expect[f"{pref}mlp.gate_proj.weight"] = gate
+    expect[f"{pref}mlp.up_proj.weight"] = up
+    expect[f"{pref}mlp.down_proj.weight"] = down
+    if is_full:
+        q = w2d(rng, 2 * N_HEAD * HEAD_DIM, N_EMBD)
+        k = w2d(rng, N_HEAD_KV * HEAD_DIM, N_EMBD)
+        v = w2d(rng, N_HEAD_KV * HEAD_DIM, N_EMBD)
+        o = w2d(rng, N_EMBD, N_HEAD * HEAD_DIM)
+        qn = w2d(rng, HEAD_DIM, 1).ravel() + 0.5
+        kn = w2d(rng, HEAD_DIM, 1).ravel() + 0.5
+        add2d(w, f"{base}.attn_q.weight", q, qtype=Q8)
+        add2d(w, f"{base}.attn_k.weight", k, qtype=Q8)
+        add2d(w, f"{base}.attn_v.weight", v, qtype=Q8)
+        add2d(w, f"{base}.attn_output.weight", o, qtype=Q8)
+        add1d(w, f"{base}.attn_q_norm.weight", qn)
+        add1d(w, f"{base}.attn_k_norm.weight", kn)
+        expect[f"{pref}self_attn.q_proj.weight"] = q
+        expect[f"{pref}self_attn.k_proj.weight"] = k
+        expect[f"{pref}self_attn.v_proj.weight"] = v
+        expect[f"{pref}self_attn.o_proj.weight"] = o
+        expect[f"{pref}self_attn.q_norm.weight"] = qn - 1.0
+        expect[f"{pref}self_attn.k_norm.weight"] = kn - 1.0
+    else:
+        k_dim, v_dim = L_KEY_HEADS * L_KEY_HD, L_V_HEADS * L_V_HD
+        conv_dim = k_dim * 2 + v_dim
+        qkv = w2d(rng, conv_dim, N_EMBD)
+        qkv_hf = qkv.copy()
+        qkv[v_dim:] = hf_to_gguf(qkv[v_dim:].reshape(32, 128, -1)).reshape(v_dim, -1)
+        z = w2d(rng, v_dim, N_EMBD)
+        z_hf = z.copy()
+        z = hf_to_gguf(z.reshape(32, 128, -1)).reshape(v_dim, -1)
+        conv = w2d(rng, conv_dim, CONV_K)
+        conv_hf = conv.copy()
+        conv[v_dim:] = hf_to_gguf(conv[v_dim:].reshape(32, 128, -1)).reshape(v_dim, -1)
+        dt_hf = rng.standard_normal(L_V_HEADS).astype(np.float32)
+        dt = hf_to_gguf(dt_hf)
+        a_log = rng.standard_normal(L_V_HEADS).astype(np.float32)
+        beta_hf = w2d(rng, L_V_HEADS, N_EMBD)
+        beta = hf_to_gguf(beta_hf)
+        alpha_hf = w2d(rng, L_V_HEADS, N_EMBD)
+        alpha = hf_to_gguf(alpha_hf)
+        s_norm = w2d(rng, L_V_HD, 1).ravel() + 0.5
+        out_proj = w2d(rng, N_EMBD, v_dim)
+        out_proj_gguf = out_proj.reshape(N_EMBD, 32, 128)[:, GGUF_TO_HF, :].reshape(N_EMBD, v_dim)
+        add2d(w, f"{base}.attn_qkv.weight", qkv, qtype=Q8)
+        add2d(w, f"{base}.attn_gate.weight", z, qtype=Q8)
+        w.add_tensor(f"{base}.ssm_conv1d.weight", conv, raw_shape=(conv_dim, CONV_K))
+        add1d(w, f"{base}.ssm_dt.bias", dt)
+        add1d(w, f"{base}.ssm_a", hf_to_gguf(-np.exp(a_log)).astype(np.float32))
+        add2d(w, f"{base}.ssm_beta.weight", beta, qtype=Q8)
+        add2d(w, f"{base}.ssm_alpha.weight", alpha, qtype=Q8)
+        add1d(w, f"{base}.ssm_norm.weight", s_norm)
+        add2d(w, f"{base}.ssm_out.weight", out_proj_gguf, qtype=Q8)
+        expect[f"{pref}linear_attn.in_proj_qkv.weight"] = qkv_hf
+        expect[f"{pref}linear_attn.in_proj_z.weight"] = z_hf
+        expect[f"{pref}linear_attn.conv1d.weight"] = conv_hf.reshape(conv_dim, 1, CONV_K)
+        expect[f"{pref}linear_attn.dt_bias"] = dt_hf
+        expect[f"{pref}linear_attn.A_log"] = a_log
+        expect[f"{pref}linear_attn.in_proj_b.weight"] = beta_hf
+        expect[f"{pref}linear_attn.in_proj_a.weight"] = alpha_hf
+        expect[f"{pref}linear_attn.norm.weight"] = s_norm
+        expect[f"{pref}linear_attn.out_proj.weight"] = out_proj
+
+
+def main() -> None:
+    global Q8
+    from gguf import GGUFWriter, GGMLQuantizationType
+    Q8 = GGMLQuantizationType.Q8_0
+
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--keep", action="store_true")
+    args = ap.parse_args()
+
+    tmpdir = tempfile.mkdtemp(prefix="gguf_test_")
+    path = os.path.join(tmpdir, "toy_qwen35.gguf")
+    print(f"写入合成 GGUF -> {path}")
+
+    rng = np.random.default_rng(42)
+    expect: dict[str, np.ndarray] = {}
+    w = GGUFWriter(path, "qwen35")
+    emb = w2d(rng, 248320, N_EMBD)
+    add2d(w, "token_embd.weight", emb)
+    expect["language_model.embed_tokens.weight"] = emb
+    out_norm = w2d(rng, N_EMBD, 1).ravel() + 0.5
+    add1d(w, "output_norm.weight", out_norm)
+    expect["language_model.norm.weight"] = out_norm - 1.0
+    add_layer(w, rng, 0, is_full=False, expect=expect)
+    add_layer(w, rng, 3, is_full=True, expect=expect)
+    w.write_header_to_file()
+    w.write_kv_data_to_file()
+    w.write_tensors_to_file()
+    w.close()
+    print(f"GGUF 写入完成 ({os.path.getsize(path) / 1e6:.0f} MB)")
+
+    from gguf_qwen35 import load_gguf_state_dict, build_hf_model
+    sd = load_gguf_state_dict(path)
+    print(f"映射出 {len(sd)} 个键")
+
+    fails = 0
+    for key, want in sorted(expect.items()):
+        if key not in sd:
+            print(f"  [FAIL] {key} MISSING")
+            fails += 1
+            continue
+        got = sd[key]
+        ws = torch.from_numpy(want).float()
+        gs = got.float()
+        if tuple(gs.shape) != tuple(ws.shape):
+            print(f"  [FAIL] {key} shape {tuple(gs.shape)} 期望 {tuple(ws.shape)}")
+            fails += 1
+            continue
+        dot = torch.zeros((), dtype=torch.float64)
+        na = torch.zeros((), dtype=torch.float64)
+        nb = torch.zeros((), dtype=torch.float64)
+        CH = 1 << 22
+        ga, wf = gs.flatten(), ws.flatten()
+        for i in range(0, ga.numel(), CH):
+            x, y = ga[i:i + CH], wf[i:i + CH]
+            dot += (x * y).sum().double()
+            na += (x * x).sum().double()
+            nb += (y * y).sum().double()
+        c = float(dot / (na.sqrt() * nb.sqrt() + 1e-30))
+        ok = c > 0.99
+        print(f"  [{'PASS' if ok else 'FAIL'}] {key} {tuple(gs.shape)} cos={c:.5f}")
+        fails += 0 if ok else 1
+
+    model, missing, unexpected = build_hf_model(sd, os.path.join(HERE, "qwen35_config.json"))
+    unexp_ok = len(unexpected) == 0
+    print(f"  [{'PASS' if unexp_ok else 'FAIL'}] load_state_dict unexpected={len(unexpected)} (应=0)"
+          + (f": {unexpected[:4]}" if unexpected else ""))
+    fails += 0 if unexp_ok else 1
+    print(f"  [info] missing={len(missing)}（其余 30 层 + vision 属正常缺省）")
+
+    if not args.keep:
+        import shutil
+        shutil.rmtree(tmpdir)
+    print("GGUF 回环", "PASS ✅" if fails == 0 else f"FAIL ({fails})")
+    raise SystemExit(0 if fails == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-MiniMaxH3-Adapter/tokenizer/tokenizer_config.json

@@ -0,0 +1,246 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151665": {
+      "content": "<tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151666": {
+      "content": "</tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151667": {
+      "content": "<think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151668": {
+      "content": "</think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>",
+    "<d>",
+    "</d>",
+    "<|cutoff|>",
+    "<|lyrics_start|>",
+    "<|lyrics_end|>",
+    "<|caption_start|>",
+    "<|caption_end|>"
+  ],
+  "bos_token": null,
+  "chat_template": "{%- if tools %}\n    {{- '<|im_start|>system\\n' }}\n    {%- if messages[0].role == 'system' %}\n        {%- if messages[0].content is string %}\n            {{- messages[0].content }}\n        {%- else %}\n            {%- for content in messages[0].content %}\n                {%- if 'text' in content %}\n                    {{- content.text }}\n                {%- endif %}\n            {%- endfor %}\n        {%- endif %}\n        {{- '\\n\\n' }}\n    {%- endif %}\n    {{- \"# Tools\\n\\nYou may call one or more functions to assist with the user query.\\n\\nYou are provided with function signatures within <tools></tools> XML tags:\\n<tools>\" }}\n    {%- for tool in tools %}\n        {{- \"\\n\" }}\n        {{- tool | tojson }}\n    {%- endfor %}\n    {{- \"\\n</tools>\\n\\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\\n<tool_call>\\n{\\\"name\\\": <function-name>, \\\"arguments\\\": <args-json-object>}\\n</tool_call><|im_end|>\\n\" }}\n{%- else %}\n    {%- if messages[0].role == 'system' %}\n        {{- '<|im_start|>system\\n' }}\n        {%- if messages[0].content is string %}\n            {{- messages[0].content }}\n        {%- else %}\n            {%- for content in messages[0].content %}\n                {%- if 'text' in content %}\n                    {{- content.text }}\n                {%- endif %}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- endif %}\n{%- endif %}\n{%- set image_count = namespace(value=0) %}\n{%- set video_count = namespace(value=0) %}\n{%- for message in messages %}\n    {%- if message.role == \"user\" %}\n        {{- '<|im_start|>' + message.role + '\\n' }}\n        {%- if message.content is string %}\n            {{- message.content }}\n        {%- else %}\n            {%- for content in message.content %}\n                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}\n                    {%- set image_count.value = image_count.value + 1 %}\n                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}\n                    <|vision_start|><|image_pad|><|vision_end|>\n                {%- elif content.type == 'video' or 'video' in content %}\n                    {%- set video_count.value = video_count.value + 1 %}\n                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}\n                    <|vision_start|><|video_pad|><|vision_end|>\n                {%- elif 'text' in content %}\n                    {{- content.text }}\n                {%- endif %}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"assistant\" %}\n        {{- '<|im_start|>' + message.role + '\\n' }}\n        {%- if message.content is string %}\n            {{- message.content }}\n        {%- else %}\n            {%- for content_item in message.content %}\n                {%- if 'text' in content_item %}\n                    {{- content_item.text }}\n                {%- endif %}\n            {%- endfor %}\n        {%- endif %}\n        {%- if message.tool_calls %}\n            {%- for tool_call in message.tool_calls %}\n                {%- if (loop.first and message.content) or (not loop.first) %}\n                    {{- '\\n' }}\n                {%- endif %}\n                {%- if tool_call.function %}\n                    {%- set tool_call = tool_call.function %}\n                {%- endif %}\n                {{- '<tool_call>\\n{\"name\": \"' }}\n                {{- tool_call.name }}\n                {{- '\", \"arguments\": ' }}\n                {%- if tool_call.arguments is string %}\n                    {{- tool_call.arguments }}\n                {%- else %}\n                    {{- tool_call.arguments | tojson }}\n                {%- endif %}\n                {{- '}\\n</tool_call>' }}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"tool\" %}\n        {%- if loop.first or (messages[loop.index0 - 1].role != \"tool\") %}\n            {{- '<|im_start|>user' }}\n        {%- endif %}\n        {{- '\\n<tool_response>\\n' }}\n        {%- if message.content is string %}\n            {{- message.content }}\n        {%- else %}\n            {%- for content in message.content %}\n                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}\n                    {%- set image_count.value = image_count.value + 1 %}\n                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}\n                    <|vision_start|><|image_pad|><|vision_end|>\n                {%- elif content.type == 'video' or 'video' in content %}\n                    {%- set video_count.value = video_count.value + 1 %}\n                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}\n                    <|vision_start|><|video_pad|><|vision_end|>\n                {%- elif 'text' in content %}\n                    {{- content.text }}\n                {%- endif %}\n            {%- endfor %}\n        {%- endif %}\n        {{- '\\n</tool_response>' }}\n        {%- if loop.last or (messages[loop.index0 + 1].role != \"tool\") %}\n            {{- '<|im_end|>\\n' }}\n        {%- endif %}\n    {%- endif %}\n{%- endfor %}\n{%- if add_generation_prompt %}\n    {{- '<|im_start|>assistant\\n' }}\n{%- endif %}\n",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "model_max_length": 262144,
+  "pad_token": "<|endoftext|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}