[0.16.5] reference caption issue (#7)

Author: pytraveler

.gitignore

@@ -223,4 +223,7 @@ uv.exe
 # Local development: junction helper and the ComfyUI path it remembers
 dev-junction.ps1
 dev-junction.bat
-comfyui-path.txt
+comfyui-path.txt
+# Seeded when the package is imported outside ComfyUI, where folder_paths is
+# absent and the user directory falls back into the package itself
+minimax_h3_rewriter/_user/

CHANGELOG.md

@@ -6,6 +6,50 @@ The version in `pyproject.toml`, the git tag and the release on GitHub always sa
 the same thing; the release workflow refuses a tag that disagrees with
 `pyproject.toml`, or one that neither changelog has a section for.
 
+## 0.16.5 - 2026-08-24
+
+### Fixed
+
+- **A captioner no longer reserves the whole context the model was trained on.**
+  `--ctx-size 0` reads as "let llama.cpp decide" and means "the context this
+  model was trained for", and the packaged captioners hid the difference:
+  Qwen2.5-Omni asks for 32k and fits anywhere. Qwen3-VL asks for 262144 tokens,
+  and its cache is 36 layers of 8 KV heads at 128 dimensions, K and V, in f16 -
+  144 KiB a token, so 36 GiB of KV cache allocated before a single pixel has
+  been read. On a 32 GB card the run died at `failed to allocate buffer for kv
+  cache`, having never looked at the picture, and llama.cpp's own auto-fit could
+  not rescue it because the node pins `--n-gpu-layers`.
+
+  0 now means "what this run needs, and never more than the card can hold". The
+  context length and the shape of the cache are read from the GGUF header the
+  model scan already parses, and sized against the number of references and the
+  memory of the device the run is bound for. A number typed into `context_size`
+  is still honoured exactly as typed, and a header too thin to size against
+  falls back to letting llama.cpp decide, as before.
+
+  Reported by [@808charlie](https://github.com/808charlie) in
+  [#7](https://github.com/pytraveler/MiniMax-H3-Prompt-Rewriter-ComfyUI/issues/7).
+
+### Changed
+
+- **A failed caption says which way it failed.** The note about projector
+  formats was printed on every non-zero exit from `llama-mtmd-cli`, so an
+  out-of-memory came back dressed as a model mtmd cannot read - and sent the
+  reader to study the model while the child had already said `cudaMalloc
+  failed`. An allocation that did not fit and a context too small for the frames
+  now each get their own answer, naming the widget that moves them, and the
+  projector note is left for the exits that are actually about the projector.
+
+- **The captioner scan stops narrating.** A model sharing a folder with an
+  mmproj it could not be paired with printed a line naming every projector in
+  that folder, at INFO. A flat `models/LLM` holding a dozen unrelated quants and
+  five projectors therefore announced twelve models by five names each - four
+  times over, once for every node that offers a captioner dropdown, every time
+  ComfyUI asked for the node definitions. One line per folder now, at DEBUG.
+
+  Reported by [@808charlie](https://github.com/808charlie) in
+  [#7](https://github.com/pytraveler/MiniMax-H3-Prompt-Rewriter-ComfyUI/issues/7).
+
 ## 0.16.4 - 2026-08-24
 
 ### Changed

CHANGELOG_RU.md

@@ -6,6 +6,51 @@
 workflow релиза отклонит тег, который расходится с `pyproject.toml`, и тег, для
 которого нет раздела ни в одном из двух changelog'ов.
 
+## 0.16.5 - 2026-08-24
+
+### Исправлено
+
+- **Капшенер больше не резервирует весь контекст, на котором модель обучали.**
+  `--ctx-size 0` читается как "пусть llama.cpp решит сама", а означает "контекст,
+  на который модель обучена", и упакованные капшенеры эту разницу скрывали:
+  Qwen2.5-Omni просит 32k и помещается где угодно. Qwen3-VL просит 262144
+  токена, а её кэш - это 36 слоёв по 8 KV-голов размерности 128, K и V, в f16:
+  144 КиБ на токен, то есть 36 ГиБ KV-кэша, выделяемых до того, как прочитан
+  первый пиксель. На карте в 32 ГБ запуск падал на `failed to allocate buffer
+  for kv cache`, так и не посмотрев на картинку, а собственный auto-fit
+  llama.cpp его не спасал, потому что нода жёстко задаёт `--n-gpu-layers`.
+
+  Теперь 0 означает "сколько нужно этому запуску и не больше, чем поместится в
+  карту". Длина контекста и форма кэша читаются из заголовка GGUF, который скан
+  моделей и так разбирает, и соотносятся с числом референсов и памятью
+  устройства, куда запуск направлен. Число, вписанное в `context_size`,
+  по-прежнему выполняется буквально, а заголовок, из которого посчитать нечего,
+  как и раньше оставляет решение за llama.cpp.
+
+  Сообщил [@808charlie](https://github.com/808charlie) в
+  [#7](https://github.com/pytraveler/MiniMax-H3-Prompt-Rewriter-ComfyUI/issues/7).
+
+### Изменено
+
+- **Упавший капшенер говорит, в какую сторону он упал.** Заметка про форматы
+  проекторов печаталась при любом ненулевом коде выхода `llama-mtmd-cli`, и
+  нехватка памяти возвращалась в костюме модели, которую mtmd не умеет читать, -
+  отправляя читателя изучать модель в тот момент, когда потомок уже сказал
+  `cudaMalloc failed`. У невлезшего выделения и у слишком тесного под кадры
+  контекста теперь свои ответы, с именем виджета, который их двигает, а заметка
+  про проектор осталась тем выходам, которые действительно о проекторе.
+
+- **Скан капшенеров перестал вести репортаж.** Модель, лежащая в одной папке с
+  mmproj, к которому её не удалось привязать, печатала строку с перечислением
+  всех проекторов этой папки, уровнем INFO. Плоский `models/LLM` с дюжиной
+  посторонних квантов и пятью проекторами объявлял двенадцать моделей по пять
+  имён каждая - и четырежды, по разу на каждую ноду с выпадающим списком
+  капшенеров, при каждом запросе описаний нод от ComfyUI. Теперь одна строка на
+  папку, уровнем DEBUG.
+
+  Сообщил [@808charlie](https://github.com/808charlie) в
+  [#7](https://github.com/pytraveler/MiniMax-H3-Prompt-Rewriter-ComfyUI/issues/7).
+
 ## 0.16.4 - 2026-08-24
 
 ### Изменено

README.md

@@ -658,10 +658,14 @@ Other inputs:
   two seconds at 25 fps is 56 images through the vision tower, and thirty seconds
   is 750. This is what makes the cost of describing a clip independent of its
   length.
-- `context_size` — `0` means the model's own, which is what its projector was
-  sized against; one 1024×1024 frame is already twenty-odd media chunks. Lower it
-  only to cut the KV cache, and know that too small a value fails the run instead
-  of truncating it.
+- `context_size` — `0` sizes the context from the references and from the card,
+  which is not the same as the model's own: llama.cpp reserves the whole KV cache
+  before it reads a pixel, and a model trained for 262144 tokens asks tens of
+  gigabytes for it — Qwen3-VL-8B asks 36 GB, on a card that would have captioned
+  the picture in three seconds. One 1024×1024 frame is already twenty-odd media
+  chunks, so the count of references is half of the answer and the memory of the
+  device is the other half. Type a number to say it yourself; too small a value
+  fails the run instead of truncating it.
 
 > **Not every multimodal GGUF works here**, and the ones that do not fail loudly.
 > llama.cpp's `mtmd` has to understand the projector format: Gemma 4's aborts the

README_RU.md

@@ -649,10 +649,14 @@ delivery, speaking in Russian».*
   Все сразу переполнили бы и контекст, и терпение: две секунды при 25 fps — это
   56 картинок через визуальную башню, а тридцать секунд — 750. Именно это и
   делает стоимость описания клипа не зависящей от его длины.
-- `context_size` — `0` означает «контекст самой модели», под который её проектор
-  и рассчитан: один кадр 1024×1024 — это уже больше двадцати медиа-чанков.
-  Уменьшайте только чтобы срезать KV-кэш, и учтите, что слишком малое значение
-  роняет запуск, а не обрезает его.
+- `context_size` — `0` подбирает контекст под референсы и под карту, а это не то
+  же самое, что «контекст самой модели»: llama.cpp резервирует весь KV-кэш до
+  того, как прочтёт первый пиксель, и модель, обученная на 262144 токена,
+  требует под него десятки гигабайт — Qwen3-VL-8B ровно 36 ГБ, на карте, которая
+  описала бы картинку за три секунды. Один кадр 1024×1024 — это уже больше двадцати
+  медиа-чанков, поэтому число референсов — половина ответа, а память устройства —
+  вторая. Вписанное число выполняется буквально; слишком малое роняет запуск,
+  а не обрезает его.
 
 > **Не всякий мультимодальный GGUF здесь работает**, и те, что не работают,
 > падают громко. `mtmd` в llama.cpp должен понимать формат проектора: у Gemma 4

minimax_h3_rewriter/devices.py

@@ -70,6 +70,28 @@ def describe(index: int) -> str:
         return ""
 
 
+def vram_bytes(spec: str = AUTO) -> int:
+    """Total memory of the card a run is bound for, or 0 when it cannot be read.
+
+    Total rather than free, deliberately. What is free at the moment of asking
+    is mostly a statement about the diffusion model that is about to be evicted
+    anyway, so it would size a context differently depending on what happened to
+    be loaded when the node ran -- and the same graph would then fail only on
+    the second pass. The headroom that covers the difference is the caller's.
+    """
+    if is_cpu(spec):
+        return 0
+    ordinal = index(spec) or 0
+    try:
+        torch = _torch()
+        if not torch.cuda.is_available():
+            return 0
+        return int(torch.cuda.get_device_properties(ordinal).total_memory)
+    except Exception:
+        log.debug("[minimax_h3_rewriter.devices.vram_bytes] %s unreadable", spec, exc_info=True)
+        return 0
+
+
 def choices() -> list[str]:
     """The values offered by the options node, in a stable spelling."""
     return [AUTO] + [f"{PREFIX}{index}" for index in range(count())] + [CPU]

minimax_h3_rewriter/discovery.py

@@ -393,9 +393,54 @@ def consider(directory: str, name: str) -> None:
     return found
 
 
+ARCH_KEYS = (
+    "block_count",
+    "embedding_length",
+    "context_length",
+    "attention.head_count",
+    "attention.head_count_kv",
+    "attention.key_length",
+    "attention.value_length",
+)
+
+KV_ELEMENT_BYTES = 2
+
 _GGUF_HEADER_CACHE: dict[tuple[str, int, int], dict] = {}
 
 
+def _header_int(value) -> int | None:
+    """One integer out of a header value that is sometimes a per-layer array."""
+    if isinstance(value, (list, tuple)):
+        value = max(value) if value else None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _kv_per_token(value, arch: str, blocks: int | None, width: int | None) -> int | None:
+    """Bytes one token costs in the KV cache, or ``None`` from a header too thin.
+
+    ``key_length`` and ``value_length`` are optional and often absent; the head
+    dimension is then ``embedding_length / head_count``, which is the same
+    fallback llama.cpp makes. ``head_count_kv`` missing means the model has no
+    grouped-query attention and every head keeps its own cache.
+    """
+    if not arch or not blocks:
+        return None
+    heads = _header_int(value(f"{arch}.attention.head_count"))
+    kv_heads = _header_int(value(f"{arch}.attention.head_count_kv")) or heads
+    if not kv_heads:
+        return None
+    key_length = _header_int(value(f"{arch}.attention.key_length"))
+    if key_length is None and heads and width:
+        key_length = width // heads
+    value_length = _header_int(value(f"{arch}.attention.value_length")) or key_length
+    if not key_length or not value_length:
+        return None
+    return blocks * kv_heads * (key_length + value_length) * KV_ELEMENT_BYTES
+
+
 def gguf_header(path: str) -> dict:
     """Architecture, type and shape of a GGUF, read from its header only.
 
@@ -407,7 +452,10 @@ def gguf_header(path: str) -> dict:
     Cached per file identity, so a folder of large quants costs no more than a
     stat each after the first pass.
     """
-    empty = {"arch": "", "kind": "", "blocks": None, "width": None, "vision": False, "audio": False}
+    empty = {
+        "arch": "", "kind": "", "blocks": None, "width": None,
+        "vision": False, "audio": False, "context": None, "kv_per_token": None,
+    }
     try:
         stat = os.stat(path)
     except OSError:
@@ -423,7 +471,7 @@ def gguf_header(path: str) -> dict:
 
         def also(found: dict) -> tuple[str, ...]:
             arch = found.get("general.architecture")
-            return (f"{arch}.block_count", f"{arch}.embedding_length") if arch else ()
+            return tuple(f"{arch}.{name}" for name in ARCH_KEYS) if arch else ()
 
         value = gguf_meta.keys(path, HEADER_KEYS, probe=also, verify=True).get
 
@@ -438,6 +486,10 @@ def also(found: dict) -> tuple[str, ...]:
             width = value(f"{header['arch']}.embedding_length")
             header["blocks"] = int(blocks) if blocks is not None else None
             header["width"] = int(width) if width is not None else None
+            header["context"] = _header_int(value(f"{header['arch']}.context_length"))
+            header["kv_per_token"] = _kv_per_token(
+                value, header["arch"], header["blocks"], header["width"]
+            )
     except Exception:
         log.debug("[minimax_h3_rewriter.gguf_header] %s unreadable", path, exc_info=True)
 
@@ -653,20 +705,18 @@ def scan_captioner_gguf(arch: str | None = None) -> list[tuple[str, str, str]]:
             elif header["kind"] == "model":
                 models.append(path)
 
-    for _directory, (models, projectors) in sorted(by_directory.items()):
+    for directory, (models, projectors) in sorted(by_directory.items()):
         if not projectors:
             continue
+        unpaired: list[str] = []
         for model in sorted(models):
             # After counting the models, not before: how many there are is what
             # decides whether a lone projector in the folder can be trusted.
             if arch is not None and gguf_header(model)["arch"] != arch:
                 continue
             projector = _pair_mmproj(model, projectors, len(models))
             if not projector:
-                log.info(
-                    "[minimax_h3_rewriter.scan_captioner_gguf] no obvious projector for %s among %s",
-                    model, [os.path.basename(p) for p in projectors],
-                )
+                unpaired.append(os.path.basename(model))
                 continue
             header = gguf_header(projector)
             modalities = ", ".join(
@@ -678,5 +728,11 @@ def scan_captioner_gguf(arch: str | None = None) -> list[tuple[str, str, str]]:
                 size = 0.0
             label = f"{os.path.basename(model)} [+mmproj, {modalities}, {size:.1f} GB]"
             found.append((label, model, projector))
+        if unpaired:
+            log.debug(
+                "[minimax_h3_rewriter.scan_captioner_gguf] %s: %d model(s) with no projector "
+                "of their own among %s: %s",
+                directory, len(unpaired), [os.path.basename(p) for p in projectors], unpaired,
+            )
 
     return found