[0.14.1] 8B rewriter runs the sft

Author: pytraveler

CHANGELOG.md

@@ -6,6 +6,62 @@ 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.14.1 - 2026-08-21
+
+### Added
+
+- **The 8B rewriter runs the safetensors build as well as the GGUF one.** The
+  adapter is published as `adapter_model.safetensors` on
+  `lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B`, trained on the official
+  `Qwen/Qwen3-VL-8B-Instruct` folder, and until now the node could only reach
+  the GGUF conversion of both. Now the base model list offers either shape and
+  the node picks the engine from it.
+
+  What the route buys is residency. A GGUF base with frames runs through
+  `llama-mtmd-cli`, a fresh process each time, so `keep_model_loaded` could only
+  ever work for T2VA; safetensors loads in ComfyUI's own process through
+  Transformers and PEFT and stays there for every task. What it costs is the
+  download: 17.5 GB of base and 2.8 GB of adapter against 4.7 + 0.7 + 0.7.
+
+- **`quantization` on the 8B rewriter**, the same widget the 27B has and for the
+  same reason: `nf4` needs about 8 GB of VRAM, `int8` about 13, `bfloat16` about
+  20. Ignored for a GGUF base, which carries its own.
+
+- **The "Open model list" button on two nodes that were missing it** - the 8B
+  rewriter and Multi Reference Caption. Both pick their model from `models.json`
+  like every other node, so both had every reason to offer the button and no
+  reason not to.
+
+### Changed
+
+- **The base-model check knows which adapter is about to be applied.** It
+  compared four numbers from `config.json` against constants that always
+  described Qwen3.6-27B, so it could only ever answer for the 27B; the four now
+  travel together as a `Shape` and the caller says which one it means. A
+  Qwen3-VL-4B is refused for the 8B adapter by name and number -
+  `hidden_size is 2560, the adapter needs 4096` - rather than after the
+  download. Nothing changes for the 27B, which passes its own shape.
+
+- The transformers engine splits generation into a step that prepares inputs and
+  a step that runs them, so the multimodal path could be added without a second
+  copy of the sampling, streaming and interrupt handling. A checkpoint's
+  processor is loaded and cached beside its model, and a text-only checkpoint
+  simply has none.
+
+- **The adapter sections reach your `models.json` at last.** `adapters` and
+  `adapters_8b` are dicts, and the merge that keeps a live list current is set
+  algebra over named entries in a *list*, so it had never walked them: no
+  adapter entry has ever been written into anybody's copy. Reading still worked,
+  because an unconfigured entry falls back to the packaged value, but there was
+  no line to point at a conversion of your own - which is the whole reason the
+  file is yours to edit. They are now merged one format at a time and recorded
+  in `seed_offered` under the section name, so a format published later arrives
+  and one you delete on purpose stays deleted.
+
+- A chat template found on the tokenizer rather than on the processor is used
+  rather than refused. Qwen3-VL-4B is one such checkpoint, and its tokenizer's
+  template writes the same image placeholders.
+
 ## 0.14.0 - 2026-08-21
 
 ### Added

CHANGELOG_RU.md

@@ -6,6 +6,60 @@
 workflow релиза отклонит тег, который расходится с `pyproject.toml`, и тег, для
 которого нет раздела ни в одном из двух changelog'ов.
 
+## 0.14.1 - 2026-08-21
+
+### Добавлено
+
+- **Ререйтер 8B работает и на сборке safetensors, а не только на GGUF.** Адаптер
+  издан как `adapter_model.safetensors` в
+  `lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B` и обучен на официальной папке
+  `Qwen/Qwen3-VL-8B-Instruct`, а нода до сих пор умела дотянуться только до
+  GGUF-конвертации того и другого. Теперь список базовых моделей предлагает обе
+  формы, и нода выбирает движок по ней.
+
+  Что этот путь даёт - резидентность. База в GGUF с кадрами идёт через
+  `llama-mtmd-cli`, каждый раз новым процессом, поэтому `keep_model_loaded` мог
+  работать только для T2VA; safetensors грузится в сам процесс ComfyUI через
+  Transformers и PEFT и остаётся там для любой задачи. Чего стоит - загрузки:
+  17.5 ГБ базы и 2.8 ГБ адаптера против 4.7 + 0.7 + 0.7.
+
+- **`quantization` на ноде 8B** - тот же виджет, что у 27B, и по той же причине:
+  `nf4` требует около 8 ГБ VRAM, `int8` около 13, `bfloat16` около 20. Для базы
+  в GGUF игнорируется: там своя квантизация.
+
+- **Кнопка "Open model list" на двух нодах, где её не было** - на ререйтере 8B и
+  на Multi Reference Caption. Обе берут модель из `models.json`, как и все
+  остальные, так что причин её не показывать не было никаких.
+
+### Изменено
+
+- **Проверка базовой модели знает, какой адаптер сейчас будут применять.** Она
+  сравнивала четыре числа из `config.json` с константами, которые всегда
+  описывали Qwen3.6-27B, и потому могла отвечать только за 27B. Теперь эти
+  четыре числа ездят вместе как `Shape`, и вызывающий говорит, о каком адаптере
+  речь. Qwen3-VL-4B отклоняется для адаптера 8B по имени и числам -
+  `hidden_size is 2560, the adapter needs 4096`, - а не после загрузки. Для 27B
+  не меняется ничего: он передаёт свою форму.
+
+- Движок на transformers разделён на подготовку входа и его прогон, чтобы
+  мультимодальный путь появился без второй копии сэмплинга, стриминга и
+  обработки прерывания. Процессор чекпоинта грузится и кэшируется рядом с
+  моделью, а у текстового чекпоинта его просто нет.
+
+- **Секции с адаптерами наконец доходят до вашего `models.json`.** `adapters` и
+  `adapters_8b` — словари, а слияние, которое держит списки актуальными, есть
+  теоретико-множественная операция над именованными записями *списка*, так что до них оно
+  никогда не доходило: ни одна запись об адаптере никогда не попадала ни в чей файл.
+  Чтение при этом работало — ненастроенная запись откатывается к пакетному значению, —
+  но строки, которую можно нацелить на свою конвертацию, не было, а ведь ради этого
+  файл и отдаётся вам. Теперь они сливаются поформатно и записываются в
+  `seed_offered` под именем секции: формат, изданный позже, приходит, а удалённый
+  вами намеренно — остаётся удалённым.
+
+- Шаблон чата, лежащий на токенизаторе, а не на процессоре, теперь используется,
+  а не приводит к отказу. Qwen3-VL-4B - как раз такой чекпоинт, и шаблон его
+  токенизатора расставляет те же плейсхолдеры под картинки.
+
 ## 0.14.0 - 2026-08-21
 
 ### Добавлено

README.md

@@ -141,21 +141,29 @@ interchangeable downstream.
 **Inputs**
 
 - `prompt`, `resolution`, `duration`, `greedy`, `seed` — as above.
-- `model` — a Qwen3-VL base and its projector, which are two files from the same
-  conversion. Entries prefixed `on disk:` are pairs already in your model
-  folders. **Only the 8B fits the adapter**; a Qwen3-VL of another size loads and
-  then runs as a plain model with no rewriter, and the node says so before
-  downloading anything.
+- `model` — a Qwen3-VL-8B base, in either shape the adapter is published for.
+  A **GGUF** entry is two files from the same conversion, the model and its
+  projector. A **safetensors** entry is the official
+  [Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)
+  folder, which is what the adapter was trained on and what it is published as.
+  Entries prefixed `on disk:` are already in your model folders.
+  **Only the 8B fits the adapter**; a Qwen3-VL of another size is refused by name
+  and number before anything is downloaded.
+- `quantization` — how to load a **safetensors** base: `nf4` needs about 8 GB of
+  VRAM, `int8` about 13, `bfloat16` about 20. Ignored for GGUF, which carries its
+  own.
 - `task` — `T2VA`, `I2VA`, `FL2VA`, `L2VA`. The model's own name for these is
   T2AV, I2AV, FL2AV and L2AV; they are the same four tasks.
 - `first_frame` / `last_frame` — optional IMAGE inputs. `I2VA` reads
   `first_frame`, `L2VA` reads `last_frame`, `FL2VA` reads both, `T2VA` reads
   neither. Connect the wrong one and the node says which is missing before
   anything loads — which end of the clip a picture belongs to is part of what
   the model is told.
-- `keep_model_loaded` — **only `T2VA` can honour it.** The three tasks with
-  frames run through `llama-mtmd-cli`, a fresh process each time, which takes
-  the model with it when it exits.
+- `keep_model_loaded` — on a **safetensors** base every task honours it: the
+  model is loaded in ComfyUI's own process and stays there. On a **GGUF** base
+  only `T2VA` can, because the three tasks with frames run through
+  `llama-mtmd-cli`, a fresh process each time that takes the model with it when
+  it exits. The node says which it did rather than ignoring the switch.
 - `options` — the same options node as everything else. Its `adapter` dropdown
   lists both LoRAs; the first entry picks whichever one matches the base model
   you chose, so it needs no attention.
@@ -166,6 +174,14 @@ interchangeable downstream.
 |---|---|---|
 | Q4_K_M base + projector + Q8_0 adapter | 4.7 + 0.7 + 0.7 GB | ~9 GB |
 | Q8_0 base + projector + F16 adapter | 8.1 + 0.7 + 1.3 GB | ~13 GB |
+| safetensors base + adapter, `nf4` | 17.5 + 2.8 GB | ~8 GB |
+| safetensors base + adapter, `bfloat16` | 17.5 + 2.8 GB | ~20 GB |
+
+The GGUF route is much the smaller download and needs nothing installed. The
+safetensors route is the shape the adapter was published in, keeps the model
+resident for every task rather than only for `T2VA`, and is the one to reach for
+if you already have the checkpoint — but it needs `transformers` and `peft`,
+which the pack lists as dependencies.
 
 **What to expect of it.** All four tasks produce the trained shape: `T2VA` starts
 straight in on the three fields, and the other three open with the alignment

README_RU.md

@@ -140,20 +140,27 @@ python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\MiniMax-H3-Prom
 **Входы**
 
 - `prompt`, `resolution`, `duration`, `greedy`, `seed` — как выше.
-- `model` — база Qwen3-VL и её проектор: два файла из одной конвертации. Записи с
-  префиксом `on disk:` — это пары, уже лежащие в ваших папках моделей. **К
-  адаптеру подходит только 8B**; Qwen3-VL другого размера загрузится и будет
-  работать как обычная модель без ререйтера, и нода скажет об этом до того, как
-  что-то скачает.
+- `model` — база Qwen3-VL-8B в любой из двух форм, в которых издан адаптер.
+  **GGUF** — это два файла из одной конвертации: модель и её проектор.
+  **safetensors** — официальная папка
+  [Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct), то
+  самое, на чём адаптер обучался и в чём он опубликован. Записи с
+  префиксом `on disk:` уже лежат в ваших папках моделей. **К адаптеру
+  подходит только 8B**; Qwen3-VL другого размера отклоняется по имени и
+  числам до того, как что-то скачается.
+- `quantization` — как грузить базу в **safetensors**: `nf4` — около 8 ГБ VRAM,
+  `int8` — около 13, `bfloat16` — около 20. Для GGUF игнорируется: там своя.
 - `task` — `T2VA`, `I2VA`, `FL2VA`, `L2VA`. Сама модель называет их T2AV, I2AV,
   FL2AV и L2AV; это те же четыре задачи.
 - `first_frame` / `last_frame` — опциональные входы IMAGE. `I2VA` читает
   `first_frame`, `L2VA` — `last_frame`, `FL2VA` — оба, `T2VA` — ни одного. Если
   подключить не тот, нода назовёт недостающий до загрузки: к какому концу клипа
   относится картинка — часть того, что модели сообщают.
-- `keep_model_loaded` — **работает только для `T2VA`.** Три задачи с кадрами идут
-  через `llama-mtmd-cli`, каждый раз новым процессом, и модель уходит вместе с
-  ним.
+- `keep_model_loaded` — на базе в **safetensors** работает для любой задачи:
+  модель грузится в сам процесс ComfyUI и там же остаётся. На **GGUF** — только
+  для `T2VA`: три задачи с кадрами идут через `llama-mtmd-cli`, каждый раз новым
+  процессом, и модель уходит вместе с ним. Нода сообщает, как поступила, а не
+  молча игнорирует переключатель.
 - `options` — та же нода настроек, что и везде. В её списке `adapter` обе LoRA, а
   первая запись подставляет ту, что подходит выбранной базовой модели, — трогать
   её не нужно.
@@ -164,6 +171,13 @@ python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\MiniMax-H3-Prom
 |---|---|---|
 | База Q4_K_M + проектор + адаптер Q8_0 | 4.7 + 0.7 + 0.7 ГБ | ~9 ГБ |
 | База Q8_0 + проектор + адаптер F16 | 8.1 + 0.7 + 1.3 ГБ | ~13 ГБ |
+| База safetensors + адаптер, `nf4` | 17.5 + 2.8 ГБ | ~8 ГБ |
+| База safetensors + адаптер, `bfloat16` | 17.5 + 2.8 ГБ | ~20 ГБ |
+
+Путь через GGUF — заметно меньшая загрузка, и ставить ничего не надо. Путь через
+safetensors — та форма, в которой адаптер издан; модель остаётся в памяти на любой
+задаче, а не только на `T2VA`, и это то, что стоит брать, если чекпоинт уже есть.
+Взамен ему нужны `transformers` и `peft` — они у пака в зависимостях.
 
 **Чего от неё ждать.** Все четыре задачи дают обученную форму: `T2VA` сразу
 начинает с трёх полей, остальные три открываются той самой строкой выравнивания,

minimax_h3_rewriter/catalog.py

@@ -194,6 +194,43 @@ def _names(entries) -> list[str]:
     return [str(raw["name"]) for raw in entries if isinstance(raw, dict) and raw.get("name")]
 
 
+def _merge_adapters(merged: dict, seed: dict, offered: dict, changes: list[str]) -> None:
+    """Fold new adapter entries in, one format at a time.
+
+    An adapter section is a dict, not a list, so the set algebra that keeps the
+    lists current never reached it: a section or a format published after
+    somebody's copy was made simply never appeared in their file. Reading still
+    worked -- ``adapter`` falls back to the packaged value for anything
+    unconfigured -- but there was no line for them to point at a conversion of
+    their own, which is the whole reason the file is theirs to edit.
+
+    Tracked in ``seed_offered`` under the section name, the same way and for the
+    same reason as the lists: a format somebody deleted on purpose stays
+    deleted, and only something genuinely new arrives.
+    """
+    for section in ADAPTER_SECTIONS:
+        available = seed.get(section)
+        if not isinstance(available, dict) or not available:
+            continue
+
+        current = merged.get(section)
+        current = dict(current) if isinstance(current, dict) else {}
+        seen = set(offered.get(section) or [])
+        fresh = [
+            fmt for fmt, entry in available.items()
+            if isinstance(entry, dict) and fmt not in current and fmt not in seen
+        ]
+        if fresh:
+            for fmt in fresh:
+                current[fmt] = json.loads(json.dumps(available[fmt]))
+            merged[section] = current
+            changes.append(f"{section}: added {', '.join(fresh)}")
+        elif not isinstance(merged.get(section), dict) and current:
+            merged[section] = current
+
+        offered[section] = sorted(seen | set(available))
+
+
 def merge(live: dict, seed: dict) -> tuple[dict, list[str]]:
     """Fold new seed entries into a live list. Returns ``(merged, what changed)``.
 
@@ -228,6 +265,8 @@ def merge(live: dict, seed: dict) -> tuple[dict, list[str]]:
 
         offered[section] = sorted(set(offered.get(section) or []) | set(_names(available)))
 
+    _merge_adapters(merged, seed, offered, changes)
+
     if offered == (live.get(OFFERED_KEY) or {}) and not changes:
         return merged, changes