Add files using upload-large-folder tool

ComfyUI-GGUF/.github/workflows/registry.yaml

@@ -0,0 +1,21 @@
+name: ComfyUI Registry publish
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - stable
+    paths:
+      - "pyproject.toml"
+
+jobs:
+  publish-node:
+    name: ComfyUI Registry publish
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Publish Custom Node
+        uses: Comfy-Org/publish-node-action@main
+        with:
+          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

ComfyUI-GGUF/.gitignore

@@ -0,0 +1,167 @@
+*.bin
+*.gguf
+*.safetensors
+tools/llama.cpp*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

ComfyUI-GGUF/.tracking

@@ -0,0 +1,17 @@
+.github/workflows/registry.yaml
+.gitignore
+LICENSE
+README.md
+__init__.py
+dequant.py
+loader.py
+nodes.py
+ops.py
+pyproject.toml
+requirements.txt
+tools/README.md
+tools/convert.py
+tools/fix_5d_tensors.py
+tools/fix_lines_ending.py
+tools/lcpp.patch
+tools/read_tensors.py

ComfyUI-GGUF/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ComfyUI-GGUF/README.md

@@ -0,0 +1,49 @@
+# ComfyUI-GGUF
+GGUF Quantization support for native ComfyUI models
+
+This is currently very much WIP. These custom nodes provide support for model files stored in the GGUF format popularized by [llama.cpp](https://github.com/ggerganov/llama.cpp).
+
+While quantization wasn't feasible for regular UNET models (conv2d), transformer/DiT models such as flux seem less affected by quantization. This allows running it in much lower bits per weight variable bitrate quants on low-end GPUs. For further VRAM savings, a node to load a quantized version of the T5 text encoder is also included.
+
+![Comfy_Flux1_dev_Q4_0_GGUF_1024](https://github.com/user-attachments/assets/70d16d97-c522-4ef4-9435-633f128644c8)
+
+Note: The "Force/Set CLIP Device" is **NOT** part of this node pack. Do not install it if you only have one GPU. Do not set it to cuda:0 then complain about OOM errors if you do not undestand what it is for. There is not need to copy the workflow above, just use your own workflow and replace the stock "Load Diffusion Model" with the "Unet Loader (GGUF)" node.
+
+## Installation
+
+> [!IMPORTANT]  
+> Make sure your ComfyUI is on a recent-enough version to support custom ops when loading the UNET-only.
+
+To install the custom node normally, git clone this repository into your custom nodes folder (`ComfyUI/custom_nodes`) and install the only dependency for inference (`pip install --upgrade gguf`)
+
+```
+git clone https://github.com/city96/ComfyUI-GGUF
+```
+
+To install the custom node on a standalone ComfyUI release, open a CMD inside the "ComfyUI_windows_portable" folder (where your `run_nvidia_gpu.bat` file is) and use the following commands:
+
+```
+git clone https://github.com/city96/ComfyUI-GGUF ComfyUI/custom_nodes/ComfyUI-GGUF
+.\python_embeded\python.exe -s -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-GGUF\requirements.txt
+```
+
+On MacOS sequoia, torch 2.4.1 seems to be required, as 2.6.X nightly versions cause a "M1 buffer is not large enough" error. See [this issue](https://github.com/city96/ComfyUI-GGUF/issues/107) for more information/workarounds.
+
+## Usage
+
+Simply use the GGUF Unet loader found under the `bootleg` category. Place the .gguf model files in your `ComfyUI/models/unet` folder.
+
+LoRA loading is experimental but it should work with just the built-in LoRA loader node(s).
+
+Pre-quantized models:
+
+- [flux1-dev GGUF](https://huggingface.co/city96/FLUX.1-dev-gguf)
+- [flux1-schnell GGUF](https://huggingface.co/city96/FLUX.1-schnell-gguf)
+- [stable-diffusion-3.5-large GGUF](https://huggingface.co/city96/stable-diffusion-3.5-large-gguf)
+- [stable-diffusion-3.5-large-turbo GGUF](https://huggingface.co/city96/stable-diffusion-3.5-large-turbo-gguf)
+
+Initial support for quantizing T5 has also been added recently, these can be used using the various `*CLIPLoader (gguf)` nodes which can be used inplace of the regular ones. For the CLIP model, use whatever model you were using before for CLIP. The loader can handle both types of files - `gguf` and regular `safetensors`/`bin`.
+
+- [t5_v1.1-xxl GGUF](https://huggingface.co/city96/t5-v1_1-xxl-encoder-gguf)
+
+See the instructions in the [tools](https://github.com/city96/ComfyUI-GGUF/tree/main/tools) folder for how to create your own quants.

ComfyUI-GGUF/__init__.py

@@ -0,0 +1,9 @@
+# only import if running as a custom node
+try:
+    import comfy.utils
+except ImportError:
+    pass
+else:
+    from .nodes import NODE_CLASS_MAPPINGS
+    NODE_DISPLAY_NAME_MAPPINGS = {k:v.TITLE for k,v in NODE_CLASS_MAPPINGS.items()}
+    __all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS']

ComfyUI-GGUF/dequant.py

@@ -0,0 +1,301 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import gguf
+import torch
+from tqdm import 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,
+}

ComfyUI-GGUF/loader.py

@@ -0,0 +1,506 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import warnings
+import logging
+import torch
+import gguf
+import re
+import os
+
+from .ops import GGMLTensor
+from .dequant import is_quantized, dequantize_tensor
+
+IMG_ARCH_LIST = {"flux", "sd1", "sdxl", "sd3", "aura", "hidream", "cosmos", "ltxv", "hyvid", "wan", "lumina2", "qwen_image"}
+TXT_ARCH_LIST = {"t5", "t5encoder", "llama", "qwen2vl", "qwen3", "qwen3vl", "gemma3"}
+VIS_TYPE_LIST = {"clip-vision", "mmproj"}
+
+def get_orig_shape(reader, tensor_name):
+    field_key = f"comfy.gguf.orig_shape.{tensor_name}"
+    field = reader.get_field(field_key)
+    if field is None:
+        return None
+    # Has original shape metadata, so we try to decode it.
+    if len(field.types) != 2 or field.types[0] != gguf.GGUFValueType.ARRAY or field.types[1] != gguf.GGUFValueType.INT32:
+        raise TypeError(f"Bad original shape metadata for {field_key}: Expected ARRAY of INT32, got {field.types}")
+    return torch.Size(tuple(int(field.parts[part_idx][0]) for part_idx in field.data))
+
+def get_field(reader, field_name, field_type):
+    field = reader.get_field(field_name)
+    if field is None:
+        return None
+    elif field_type == str:
+        # extra check here as this is used for checking arch string
+        if len(field.types) != 1 or field.types[0] != gguf.GGUFValueType.STRING:
+            raise TypeError(f"Bad type for GGUF {field_name} key: expected string, got {field.types!r}")
+        return str(field.parts[field.data[-1]], encoding="utf-8")
+    elif field_type in [int, float, bool]:
+        return field_type(field.parts[field.data[-1]].item())
+    else:
+        raise TypeError(f"Unknown field type {field_type}")
+
+def get_list_field(reader, field_name, field_type):
+    field = reader.get_field(field_name)
+    if field is None:
+        return None
+    elif field_type == str:
+        return tuple(str(field.parts[part_idx], encoding="utf-8") for part_idx in field.data)
+    elif field_type in [int, float, bool]:
+        return tuple(field_type(field.parts[part_idx][0]) for part_idx in field.data)
+    else:
+        raise TypeError(f"Unknown field type {field_type}")
+
+def get_gguf_metadata(reader):
+    """Extract all simple metadata fields like safetensors"""
+    metadata = {}
+    for field_name in reader.fields:
+        try:
+            field = reader.get_field(field_name)
+            if len(field.types) == 1:  # Simple scalar fields only
+                if field.types[0] == gguf.GGUFValueType.STRING:
+                    metadata[field_name] = str(field.parts[field.data[-1]], "utf-8")
+                elif field.types[0] == gguf.GGUFValueType.INT32:
+                    metadata[field_name] = int(field.parts[field.data[-1]])
+                elif field.types[0] == gguf.GGUFValueType.F32:
+                    metadata[field_name] = float(field.parts[field.data[-1]])
+                elif field.types[0] == gguf.GGUFValueType.BOOL:
+                    metadata[field_name] = bool(field.parts[field.data[-1]])
+        except:
+            continue
+    return metadata
+
+def gguf_sd_loader(path, handle_prefix="model.diffusion_model.", is_text_model=False):
+    """
+    Read state dict as fake tensors
+    """
+    reader = gguf.GGUFReader(path)
+
+    # filter and strip prefix
+    has_prefix = False
+    if handle_prefix is not None:
+        prefix_len = len(handle_prefix)
+        tensor_names = set(tensor.name for tensor in reader.tensors)
+        has_prefix = any(s.startswith(handle_prefix) for s in tensor_names)
+
+    tensors = []
+    for tensor in reader.tensors:
+        sd_key = tensor_name = tensor.name
+        if has_prefix:
+            if not tensor_name.startswith(handle_prefix):
+                continue
+            sd_key = tensor_name[prefix_len:]
+        tensors.append((sd_key, tensor))
+
+    # detect and verify architecture
+    compat = None
+    arch_str = get_field(reader, "general.architecture", str)
+    type_str = get_field(reader, "general.type", str)
+    if arch_str in [None, "pig", "cow"]:
+        if is_text_model:
+            raise ValueError(f"This gguf file is incompatible with llama.cpp!\nConsider using safetensors or a compatible gguf file\n({path})")
+        compat = "sd.cpp" if arch_str is None else arch_str
+        # import here to avoid changes to convert.py breaking regular models
+        from .tools.convert import detect_arch
+        try:
+            arch_str = detect_arch(set(val[0] for val in tensors)).arch
+        except Exception as e:
+            raise ValueError(f"This model is not currently supported - ({e})")
+    elif arch_str not in TXT_ARCH_LIST and is_text_model:
+        if type_str not in VIS_TYPE_LIST:
+            raise ValueError(f"Unexpected text model architecture type in GGUF file: {arch_str!r}")
+    elif arch_str not in IMG_ARCH_LIST and not is_text_model:
+        raise ValueError(f"Unexpected architecture type in GGUF file: {arch_str!r}")
+
+    if compat:
+        logging.warning(f"Warning: This gguf model file is loaded in compatibility mode '{compat}' [arch:{arch_str}]")
+
+    # main loading loop
+    state_dict = {}
+    qtype_dict = {}
+    for sd_key, tensor in tensors:
+        tensor_name = tensor.name
+        # torch_tensor = torch.from_numpy(tensor.data) # mmap
+
+        # NOTE: line above replaced with this block to avoid persistent numpy warning about mmap
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message="The given NumPy array is not writable")
+            torch_tensor = torch.from_numpy(tensor.data) # mmap
+
+        shape = get_orig_shape(reader, tensor_name)
+        if shape is None:
+            shape = torch.Size(tuple(int(v) for v in reversed(tensor.shape)))
+            # Workaround for stable-diffusion.cpp SDXL detection.
+            if compat == "sd.cpp" and arch_str == "sdxl":
+                if any([tensor_name.endswith(x) for x in (".proj_in.weight", ".proj_out.weight")]):
+                    while len(shape) > 2 and shape[-1] == 1:
+                        shape = shape[:-1]
+
+        # add to state dict
+        if tensor.tensor_type in {gguf.GGMLQuantizationType.F32, gguf.GGMLQuantizationType.F16}:
+            torch_tensor = torch_tensor.view(*shape)
+        state_dict[sd_key] = GGMLTensor(torch_tensor, tensor_type=tensor.tensor_type, tensor_shape=shape)
+
+        # 1D tensors shouldn't be quantized, this is a fix for BF16
+        if len(shape) <= 1 and tensor.tensor_type == gguf.GGMLQuantizationType.BF16:
+            state_dict[sd_key] = dequantize_tensor(state_dict[sd_key], dtype=torch.float32)
+
+        # keep track of loaded tensor types
+        tensor_type_str = getattr(tensor.tensor_type, "name", repr(tensor.tensor_type))
+        qtype_dict[tensor_type_str] = qtype_dict.get(tensor_type_str, 0) + 1
+
+    # print loaded tensor type counts
+    logging.info("gguf qtypes: " + ", ".join(f"{k} ({v})" for k, v in qtype_dict.items()))
+
+    # mark largest tensor for vram estimation
+    qsd = {k:v for k,v in state_dict.items() if is_quantized(v)}
+    if len(qsd) > 0:
+        max_key = max(qsd.keys(), key=lambda k: qsd[k].numel())
+        state_dict[max_key].is_largest_weight = True
+
+    # extra info to return
+    extra = {
+        "arch_str": arch_str,
+        "metadata": get_gguf_metadata(reader)
+    }
+    return (state_dict, extra)
+
+# for remapping llama.cpp -> original key names
+T5_SD_MAP = {
+    "enc.": "encoder.",
+    ".blk.": ".block.",
+    "token_embd": "shared",
+    "output_norm": "final_layer_norm",
+    "attn_q": "layer.0.SelfAttention.q",
+    "attn_k": "layer.0.SelfAttention.k",
+    "attn_v": "layer.0.SelfAttention.v",
+    "attn_o": "layer.0.SelfAttention.o",
+    "attn_norm": "layer.0.layer_norm",
+    "attn_rel_b": "layer.0.SelfAttention.relative_attention_bias",
+    "ffn_up": "layer.1.DenseReluDense.wi_1",
+    "ffn_down": "layer.1.DenseReluDense.wo",
+    "ffn_gate": "layer.1.DenseReluDense.wi_0",
+    "ffn_norm": "layer.1.layer_norm",
+}
+
+LLAMA_SD_MAP = {
+    "blk.": "model.layers.",
+    "attn_norm": "input_layernorm",
+    "attn_q_norm.": "self_attn.q_norm.",
+    "attn_k_norm.": "self_attn.k_norm.",
+    "attn_v_norm.": "self_attn.v_norm.",
+    "attn_q": "self_attn.q_proj",
+    "attn_k": "self_attn.k_proj",
+    "attn_v": "self_attn.v_proj",
+    "attn_output": "self_attn.o_proj",
+    "ffn_up": "mlp.up_proj",
+    "ffn_down": "mlp.down_proj",
+    "ffn_gate": "mlp.gate_proj",
+    "ffn_norm": "post_attention_layernorm",
+    "token_embd": "model.embed_tokens",
+    "output_norm": "model.norm",
+    "output.weight": "lm_head.weight",
+}
+
+GEMMA3_SD_MAP = LLAMA_SD_MAP.copy()
+GEMMA3_SD_MAP.update({
+    "ffn_norm": "pre_feedforward_layernorm",
+    "post_ffw_norm": "post_feedforward_layernorm",
+    "post_attention_norm": "post_attention_layernorm",
+})
+
+CLIP_VISION_SD_MAP = {
+    "mm.": "visual.merger.mlp.",
+    "v.post_ln.": "visual.merger.ln_q.",
+    "v.patch_embd": "visual.patch_embed.proj",
+    "v.blk.": "visual.blocks.",
+    "ffn_up": "mlp.up_proj",
+    "ffn_down": "mlp.down_proj",
+    "ffn_gate": "mlp.gate_proj",
+    "attn_out.": "attn.proj.",
+    "ln1.": "norm1.",
+    "ln2.": "norm2.",
+}
+
+def sd_map_replace(raw_sd, key_map):
+    sd = {}
+    for k,v in raw_sd.items():
+        for s,d in key_map.items():
+            k = k.replace(s,d)
+        sd[k] = v
+    return sd
+
+def llama_permute(raw_sd, n_head, n_head_kv):
+    # Reverse version of LlamaModel.permute in llama.cpp convert script
+    sd = {}
+    permute = lambda x,h: x.reshape(h, x.shape[0] // h // 2, 2, *x.shape[1:]).swapaxes(1, 2).reshape(x.shape)
+    for k,v in raw_sd.items():
+        if k.endswith(("q_proj.weight", "q_proj.bias")):
+            v.data = permute(v.data, n_head)
+        if k.endswith(("k_proj.weight", "k_proj.bias")):
+            v.data = permute(v.data, n_head_kv)
+        sd[k] = v
+    return sd
+
+def gemma3_norm_corrections(sd):
+    # Reverse change from Gemma3Model modify_tensors in llama.cpp convert script
+    norm_patterns = [
+        "input_layernorm.weight",
+        "post_attention_layernorm.weight",
+        "pre_feedforward_layernorm.weight",
+        "post_feedforward_layernorm.weight",
+        "self_attn.q_norm.weight",
+        "self_attn.k_norm.weight",
+        "model.norm.weight"
+    ]
+    corrected = 0
+    for key in list(sd.keys()):
+        if any(p in key for p in norm_patterns):
+            if is_quantized(sd[key]):
+                sd[key] = dequantize_tensor(sd[key], dtype=torch.float32) - 1.0
+            else:
+                sd[key] = sd[key].float() - 1.0
+            corrected += 1
+    #logging.info(f"Gemma3: Applied -1 norm correction to {corrected} tensors")
+    return sd
+
+def strip_quant_suffix(name):
+    pattern = r"[-_]?(?:ud-)?i?q[0-9]_[a-z0-9_\-]{1,8}$"
+    match = re.search(pattern, name, re.IGNORECASE)
+    if match:
+        name = name[:match.start()]
+    return name
+
+def gguf_mmproj_loader(path):
+    # Reverse version of Qwen2VLVisionModel.modify_tensors
+    logging.info("Attenpting to find mmproj file for text encoder...")
+
+    # get name to match w/o quant suffix
+    tenc_fname = os.path.basename(path)
+    tenc = os.path.splitext(tenc_fname)[0].lower()
+    tenc = strip_quant_suffix(tenc)
+
+    # try and find matching mmproj
+    target = []
+    root = os.path.dirname(path)
+    for fname in os.listdir(root):
+        name, ext = os.path.splitext(fname)
+        if ext.lower() != ".gguf":
+            continue
+        if "mmproj" not in name.lower():
+            continue
+        if tenc in name.lower():
+            target.append(fname)
+
+    if len(target) == 0:
+        logging.error(f"Error: Can't find mmproj file for '{tenc_fname}' (matching:'{tenc}')! Qwen-Image-Edit will be broken!")
+        return {}
+    if len(target) > 1:
+        logging.error(f"Ambiguous mmproj for text encoder '{tenc_fname}', will use first match.")
+
+    logging.info(f"Using mmproj '{target[0]}' for text encoder '{tenc_fname}'.")
+    target = os.path.join(root, target[0])
+    vsd, _ = gguf_sd_loader(target, is_text_model=True)
+
+    # concat 4D to 5D
+    if "v.patch_embd.weight.1" in vsd:
+        w1 = dequantize_tensor(vsd.pop("v.patch_embd.weight"), dtype=torch.float32)
+        w2 = dequantize_tensor(vsd.pop("v.patch_embd.weight.1"), dtype=torch.float32)
+        vsd["v.patch_embd.weight"] = torch.stack([w1, w2], dim=2)
+
+    # run main replacement
+    vsd = sd_map_replace(vsd, CLIP_VISION_SD_MAP)
+
+    # handle split Q/K/V
+    if "visual.blocks.0.attn_q.weight" in vsd:
+        attns = {}
+        # filter out attentions + group
+        for k,v in vsd.items():
+            if any(x in k for x in ["attn_q", "attn_k", "attn_v"]):
+                k_attn, k_name = k.rsplit(".attn_", 1)
+                k_attn += ".attn.qkv." + k_name.split(".")[-1]
+                if k_attn not in attns:
+                    attns[k_attn] = {}
+                attns[k_attn][k_name] = dequantize_tensor(
+                    v, dtype=(torch.bfloat16 if is_quantized(v) else torch.float16)
+                )
+
+        # recombine
+        for k,v in attns.items():
+            suffix = k.split(".")[-1]
+            vsd[k] = torch.cat([
+                v[f"q.{suffix}"],
+                v[f"k.{suffix}"],
+                v[f"v.{suffix}"],
+            ], dim=0)
+        del attns
+
+    return vsd
+
+def gguf_tokenizer_loader(path, temb_shape):
+    # convert gguf tokenizer to spiece
+    logging.info("Attempting to recreate sentencepiece tokenizer from GGUF file metadata...")
+    try:
+        from sentencepiece import sentencepiece_model_pb2 as model
+    except ImportError:
+        raise ImportError("Please make sure sentencepiece and protobuf are installed.\npip install sentencepiece protobuf")
+    spm = model.ModelProto()
+
+    reader = gguf.GGUFReader(path)
+
+    if get_field(reader, "tokenizer.ggml.model", str) == "t5":
+        if temb_shape == (256384, 4096): # probably UMT5
+            spm.trainer_spec.model_type == 1 # Unigram (do we have a T5 w/ BPE?)
+        else:
+            raise NotImplementedError("Unknown model, can't set tokenizer!")
+    else:
+        raise NotImplementedError("Unknown model, can't set tokenizer!")
+
+    spm.normalizer_spec.add_dummy_prefix = get_field(reader, "tokenizer.ggml.add_space_prefix", bool)
+    spm.normalizer_spec.remove_extra_whitespaces = get_field(reader, "tokenizer.ggml.remove_extra_whitespaces", bool)
+
+    tokens = get_list_field(reader, "tokenizer.ggml.tokens", str)
+    scores = get_list_field(reader, "tokenizer.ggml.scores", float)
+    toktypes = get_list_field(reader, "tokenizer.ggml.token_type", int)
+
+    for idx, (token, score, toktype) in enumerate(zip(tokens, scores, toktypes)):
+        # # These aren't present in the original?
+        # if toktype == 5 and idx >= temb_shape[0]%1000):
+        #     continue
+
+        piece = spm.SentencePiece()
+        piece.piece = token
+        piece.score = score
+        piece.type = toktype
+        spm.pieces.append(piece)
+
+    # unsure if any of these are correct
+    spm.trainer_spec.byte_fallback = True
+    spm.trainer_spec.vocab_size = len(tokens) # split off unused?
+    spm.trainer_spec.max_sentence_length = 4096
+    spm.trainer_spec.eos_id = get_field(reader, "tokenizer.ggml.eos_token_id", int)
+    spm.trainer_spec.pad_id = get_field(reader, "tokenizer.ggml.padding_token_id", int)
+
+    logging.info(f"Created tokenizer with vocab size of {len(spm.pieces)}")
+    del reader
+    return torch.ByteTensor(list(spm.SerializeToString()))
+
+def gguf_tekken_tokenizer_loader(path, temb_shape):
+    # convert ggml (hf) tokenizer metadata to tekken/comfy data
+    logging.info("Attempting to recreate tekken tokenizer from GGUF file metadata...")
+    import json
+    import base64
+    from transformers.convert_slow_tokenizer import bytes_to_unicode
+
+    reader = gguf.GGUFReader(path)
+
+    model_str = get_field(reader, "tokenizer.ggml.model", str)
+    if model_str == "gpt2":
+        if temb_shape == (131072, 5120): # probably Mistral
+            data = {
+                "config": {"num_vocab_tokens": 150000, "default_vocab_size": 131072},
+                "vocab": [],
+                "special_tokens": [],
+            }
+        else:
+            raise NotImplementedError("Unknown model, can't set tokenizer!")
+    else:
+        raise NotImplementedError("Unknown model, can't set tokenizer!")
+
+    tokens = get_list_field(reader, "tokenizer.ggml.tokens", str)
+    toktypes = get_list_field(reader, "tokenizer.ggml.token_type", int)
+
+    decoder = {v: k for k, v in bytes_to_unicode().items()}
+    for idx, (token, toktype) in enumerate(zip(tokens, toktypes)):
+        if toktype == 3:
+            data["special_tokens"].append(
+                {'rank': idx, 'token_str': token, 'is_control': True}
+            )
+        else:
+            tok = bytes([decoder[char] for char in token])
+            data["vocab"].append({
+                "rank": len(data["vocab"]),
+                "token_bytes": base64.b64encode(tok).decode("ascii"),
+                "token_str": tok.decode("utf-8", errors="replace") # ?
+            })
+
+    logging.info(f"Created tekken tokenizer with vocab size of {len(data['vocab'])} (+{len(data['special_tokens'])})")
+    del reader
+    return torch.ByteTensor(list(json.dumps(data).encode('utf-8')))
+
+def gguf_gemma3_tokenizer_loader(path):
+    #TODO: merge into gguf_tokenizer_loader
+    logging.info("Attempting to recreate sentencepiece tokenizer from GGUF file metadata...")
+    try:
+        from sentencepiece import sentencepiece_model_pb2 as model
+    except ImportError:
+        raise ImportError("Please install sentencepiece and protobuf.\npip install sentencepiece protobuf")
+    spm = model.ModelProto()
+    reader = gguf.GGUFReader(path)
+
+    spm.normalizer_spec.name = "identity"
+    spm.normalizer_spec.add_dummy_prefix = False
+    spm.trainer_spec.model_type = 2
+    spm.trainer_spec.input_format = "tsv"
+    spm.trainer_spec.byte_fallback = True
+    spm.trainer_spec.max_sentence_length = 4192
+    spm.trainer_spec.bos_piece = "<bos>"
+
+    tokens = get_list_field(reader, "tokenizer.ggml.tokens", str)
+    scores = get_list_field(reader, "tokenizer.ggml.scores", float)
+    toktype = get_list_field(reader, "tokenizer.ggml.token_type", int)
+    
+    if not tokens or not scores or not toktype:
+        raise ValueError("Missing tokenizer metadata")
+    
+    for idx in range(len(tokens)):
+        piece = spm.SentencePiece()
+        piece.piece = tokens[idx]
+        if idx == 3:  # UNK position
+            piece.type = 2  # UNK Token
+            piece.score = 0.0 # UNK Score
+        else:
+            piece.type = toktype[idx]
+            piece.score = scores[idx]
+        spm.pieces.append(piece)
+    
+    spm.trainer_spec.vocab_size = len(spm.pieces)
+    logging.info(f"Created tokenizer with vocab size of {len(spm.pieces)}")
+    
+    del reader
+    return torch.ByteTensor(list(spm.SerializeToString()))
+
+def gguf_clip_loader(path):
+    sd, extra = gguf_sd_loader(path, is_text_model=True)
+    arch = extra.get("arch_str", None)
+    if arch in {"t5", "t5encoder"}:
+        temb_key = "token_embd.weight"
+        if temb_key in sd and sd[temb_key].shape == (256384, 4096):
+            # non-standard Comfy-Org tokenizer
+            sd["spiece_model"] = gguf_tokenizer_loader(path, sd[temb_key].shape)
+            # TODO: dequantizing token embed here is janky but otherwise we OOM due to tensor being massive.
+            logging.warning(f"Dequantizing {temb_key} to prevent runtime OOM.")
+            sd[temb_key] = dequantize_tensor(sd[temb_key], dtype=torch.float16)
+        sd = sd_map_replace(sd, T5_SD_MAP)
+    elif arch in {"llama", "qwen2vl", "qwen3", "qwen3vl", "gemma3"}:
+        # TODO: pass model_options["vocab_size"] to loader somehow
+        temb_key = "token_embd.weight"
+        if temb_key in sd and sd[temb_key].shape[0] >= (64 * 1024):
+            if arch == "llama" and sd[temb_key].shape == (131072, 5120):
+                # non-standard Comfy-Org tokenizer
+                sd["tekken_model"] = gguf_tekken_tokenizer_loader(path, sd[temb_key].shape)
+            elif arch == "gemma3":
+                sd["spiece_model"] = gguf_gemma3_tokenizer_loader(path)
+            # See note above for T5.
+            logging.warning(f"Dequantizing {temb_key} to prevent runtime OOM.")
+            sd[temb_key] = dequantize_tensor(sd[temb_key], dtype=torch.float16)
+        if arch == "gemma3":
+            sd = sd_map_replace(sd, GEMMA3_SD_MAP)
+            sd = gemma3_norm_corrections(sd)
+        else:
+            sd = sd_map_replace(sd, LLAMA_SD_MAP)
+        if arch == "llama":
+            sd = llama_permute(sd, 32, 8) # L3 / Mistral
+        if arch == "qwen2vl":
+            vsd = gguf_mmproj_loader(path)
+            sd.update(vsd)
+    else:
+        pass
+    return sd

ComfyUI-GGUF/nodes.py

@@ -0,0 +1,329 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import torch
+import logging
+import inspect
+import collections
+
+import nodes
+import comfy.sd
+import comfy.lora
+import comfy.float
+import comfy.utils
+import comfy.model_patcher
+import comfy.model_management
+import folder_paths
+
+from .ops import GGMLOps, move_patch_to_device
+from .loader import gguf_sd_loader, gguf_clip_loader
+from .dequant import is_quantized, is_torch_compatible
+
+def update_folder_names_and_paths(key, targets=[]):
+    # check for existing key
+    base = folder_paths.folder_names_and_paths.get(key, ([], {}))
+    base = base[0] if isinstance(base[0], (list, set, tuple)) else []
+    # find base key & add w/ fallback, sanity check + warning
+    target = next((x for x in targets if x in folder_paths.folder_names_and_paths), targets[0])
+    orig, _ = folder_paths.folder_names_and_paths.get(target, ([], {}))
+    folder_paths.folder_names_and_paths[key] = (orig or base, {".gguf"})
+    if base and base != orig:
+        logging.warning(f"Unknown file list already present on key {key}: {base}")
+
+# Add a custom keys for files ending in .gguf
+update_folder_names_and_paths("unet_gguf", ["diffusion_models", "unet"])
+update_folder_names_and_paths("clip_gguf", ["text_encoders", "clip"])
+
+class GGUFModelPatcher(comfy.model_patcher.ModelPatcher):
+    patch_on_device = False
+
+    def patch_weight_to_device(self, key, device_to=None, inplace_update=False):
+        if key not in self.patches:
+            return
+        weight = comfy.utils.get_attr(self.model, key)
+
+        patches = self.patches[key]
+        if is_quantized(weight):
+            out_weight = weight.to(device_to)
+            patches = move_patch_to_device(patches, self.load_device if self.patch_on_device else self.offload_device)
+            # TODO: do we ever have legitimate duplicate patches? (i.e. patch on top of patched weight)
+            out_weight.patches = [(patches, key)]
+        else:
+            inplace_update = self.weight_inplace_update or inplace_update
+            if key not in self.backup:
+                self.backup[key] = collections.namedtuple('Dimension', ['weight', 'inplace_update'])(
+                    weight.to(device=self.offload_device, copy=inplace_update), inplace_update
+                )
+
+            if device_to is not None:
+                temp_weight = comfy.model_management.cast_to_device(weight, device_to, torch.float32, copy=True)
+            else:
+                temp_weight = weight.to(torch.float32, copy=True)
+
+            out_weight = comfy.lora.calculate_weight(patches, temp_weight, key)
+            out_weight = comfy.float.stochastic_rounding(out_weight, weight.dtype)
+
+        if inplace_update:
+            comfy.utils.copy_to_param(self.model, key, out_weight)
+        else:
+            comfy.utils.set_attr_param(self.model, key, out_weight)
+
+    def unpatch_model(self, device_to=None, unpatch_weights=True):
+        if unpatch_weights:
+            for p in self.model.parameters():
+                if is_torch_compatible(p):
+                    continue
+                patches = getattr(p, "patches", [])
+                if len(patches) > 0:
+                    p.patches = []
+        # TODO: Find another way to not unload after patches
+        return super().unpatch_model(device_to=device_to, unpatch_weights=unpatch_weights)
+
+
+    def pin_weight_to_device(self, key):
+        op_key = key.rsplit('.', 1)[0]
+        if not self.mmap_released and op_key in self.named_modules_to_munmap:
+            # TODO: possible to OOM, find better way to detach
+            self.named_modules_to_munmap[op_key].to(self.load_device).to(self.offload_device)
+            del self.named_modules_to_munmap[op_key]
+        super().pin_weight_to_device(key)
+
+    mmap_released = False
+    named_modules_to_munmap = {}
+
+    def load(self, *args, force_patch_weights=False, **kwargs):
+        if not self.mmap_released:
+            self.named_modules_to_munmap = dict(self.model.named_modules())
+
+        # always call `patch_weight_to_device` even for lowvram
+        super().load(*args, force_patch_weights=True, **kwargs)
+
+        # make sure nothing stays linked to mmap after first load
+        if not self.mmap_released:
+            linked = []
+            if kwargs.get("lowvram_model_memory", 0) > 0:
+                for n, m in self.named_modules_to_munmap.items():
+                    if hasattr(m, "weight"):
+                        device = getattr(m.weight, "device", None)
+                        if device == self.offload_device:
+                            linked.append((n, m))
+                            continue
+                    if hasattr(m, "bias"):
+                        device = getattr(m.bias, "device", None)
+                        if device == self.offload_device:
+                            linked.append((n, m))
+                            continue
+            if linked and self.load_device != self.offload_device:
+                logging.info(f"Attempting to release mmap ({len(linked)})")
+                for n, m in linked:
+                    # TODO: possible to OOM, find better way to detach
+                    m.to(self.load_device).to(self.offload_device)
+            self.mmap_released = True
+            self.named_modules_to_munmap = {}
+
+    def clone(self, *args, **kwargs):
+        src_cls = self.__class__
+        self.__class__ = GGUFModelPatcher
+        n = super().clone(*args, **kwargs)
+        n.__class__ = GGUFModelPatcher
+        self.__class__ = src_cls
+        # GGUF specific clone values below
+        n.patch_on_device = getattr(self, "patch_on_device", False)
+        n.mmap_released = getattr(self, "mmap_released", False)
+        if src_cls != GGUFModelPatcher:
+            n.size = 0 # force recalc
+        return n
+
+class UnetLoaderGGUF:
+    @classmethod
+    def INPUT_TYPES(s):
+        unet_names = [x for x in folder_paths.get_filename_list("unet_gguf")]
+        return {
+            "required": {
+                "unet_name": (unet_names,),
+            }
+        }
+
+    RETURN_TYPES = ("MODEL",)
+    FUNCTION = "load_unet"
+    CATEGORY = "bootleg"
+    TITLE = "Unet Loader (GGUF)"
+
+    def load_unet(self, unet_name, dequant_dtype=None, patch_dtype=None, patch_on_device=None):
+        ops = GGMLOps()
+
+        if dequant_dtype in ("default", None):
+            ops.Linear.dequant_dtype = None
+        elif dequant_dtype in ["target"]:
+            ops.Linear.dequant_dtype = dequant_dtype
+        else:
+            ops.Linear.dequant_dtype = getattr(torch, dequant_dtype)
+
+        if patch_dtype in ("default", None):
+            ops.Linear.patch_dtype = None
+        elif patch_dtype in ["target"]:
+            ops.Linear.patch_dtype = patch_dtype
+        else:
+            ops.Linear.patch_dtype = getattr(torch, patch_dtype)
+
+        # init model
+        unet_path = folder_paths.get_full_path("unet", unet_name)
+        sd, extra = gguf_sd_loader(unet_path)
+
+        kwargs = {}
+        valid_params = inspect.signature(comfy.sd.load_diffusion_model_state_dict).parameters
+        if "metadata" in valid_params:
+            kwargs["metadata"] = extra.get("metadata", {})
+
+        model = comfy.sd.load_diffusion_model_state_dict(
+            sd, model_options={"custom_operations": ops}, **kwargs,
+        )
+        if model is None:
+            logging.error("ERROR UNSUPPORTED UNET {}".format(unet_path))
+            raise RuntimeError("ERROR: Could not detect model type of: {}".format(unet_path))
+        model = GGUFModelPatcher.clone(model)
+        model.patch_on_device = patch_on_device
+        return (model,)
+
+class UnetLoaderGGUFAdvanced(UnetLoaderGGUF):
+    @classmethod
+    def INPUT_TYPES(s):
+        unet_names = [x for x in folder_paths.get_filename_list("unet_gguf")]
+        return {
+            "required": {
+                "unet_name": (unet_names,),
+                "dequant_dtype": (["default", "target", "float32", "float16", "bfloat16"], {"default": "default"}),
+                "patch_dtype": (["default", "target", "float32", "float16", "bfloat16"], {"default": "default"}),
+                "patch_on_device": ("BOOLEAN", {"default": False}),
+            }
+        }
+    TITLE = "Unet Loader (GGUF/Advanced)"
+
+class CLIPLoaderGGUF:
+    @classmethod
+    def INPUT_TYPES(s):
+        base = nodes.CLIPLoader.INPUT_TYPES()
+        return {
+            "required": {
+                "clip_name": (s.get_filename_list(),),
+                "type": base["required"]["type"],
+            }
+        }
+
+    RETURN_TYPES = ("CLIP",)
+    FUNCTION = "load_clip"
+    CATEGORY = "bootleg"
+    TITLE = "CLIPLoader (GGUF)"
+
+    @classmethod
+    def get_filename_list(s):
+        files = []
+        files += folder_paths.get_filename_list("clip")
+        files += folder_paths.get_filename_list("clip_gguf")
+        return sorted(files)
+
+    def load_data(self, ckpt_paths):
+        clip_data = []
+        for p in ckpt_paths:
+            if p.endswith(".gguf"):
+                sd = gguf_clip_loader(p)
+            else:
+                sd = comfy.utils.load_torch_file(p, safe_load=True)
+                if "scaled_fp8" in sd: # NOTE: Scaled FP8 would require different custom ops, but only one can be active
+                    raise NotImplementedError(f"Mixing scaled FP8 with GGUF is not supported! Use regular CLIP loader or switch model(s)\n({p})")
+            clip_data.append(sd)
+        return clip_data
+
+    def load_patcher(self, clip_paths, clip_type, clip_data):
+        clip = comfy.sd.load_text_encoder_state_dicts(
+            clip_type = clip_type,
+            state_dicts = clip_data,
+            model_options = {
+                "custom_operations": GGMLOps,
+                "initial_device": comfy.model_management.text_encoder_offload_device()
+            },
+            embedding_directory = folder_paths.get_folder_paths("embeddings"),
+        )
+        clip.patcher = GGUFModelPatcher.clone(clip.patcher)
+        return clip
+
+    def load_clip(self, clip_name, type="stable_diffusion"):
+        clip_path = folder_paths.get_full_path("clip", clip_name)
+        clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+        return (self.load_patcher([clip_path], clip_type, self.load_data([clip_path])),)
+
+class DualCLIPLoaderGGUF(CLIPLoaderGGUF):
+    @classmethod
+    def INPUT_TYPES(s):
+        base = nodes.DualCLIPLoader.INPUT_TYPES()
+        file_options = (s.get_filename_list(), )
+        return {
+            "required": {
+                "clip_name1": file_options,
+                "clip_name2": file_options,
+                "type": base["required"]["type"],
+            }
+        }
+
+    TITLE = "DualCLIPLoader (GGUF)"
+
+    def load_clip(self, clip_name1, clip_name2, type):
+        clip_path1 = folder_paths.get_full_path("clip", clip_name1)
+        clip_path2 = folder_paths.get_full_path("clip", clip_name2)
+        clip_paths = (clip_path1, clip_path2)
+        clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+        return (self.load_patcher(clip_paths, clip_type, self.load_data(clip_paths)),)
+
+class TripleCLIPLoaderGGUF(CLIPLoaderGGUF):
+    @classmethod
+    def INPUT_TYPES(s):
+        file_options = (s.get_filename_list(), )
+        return {
+            "required": {
+                "clip_name1": file_options,
+                "clip_name2": file_options,
+                "clip_name3": file_options,
+            }
+        }
+
+    TITLE = "TripleCLIPLoader (GGUF)"
+
+    def load_clip(self, clip_name1, clip_name2, clip_name3, type="sd3"):
+        clip_path1 = folder_paths.get_full_path("clip", clip_name1)
+        clip_path2 = folder_paths.get_full_path("clip", clip_name2)
+        clip_path3 = folder_paths.get_full_path("clip", clip_name3)
+        clip_paths = (clip_path1, clip_path2, clip_path3)
+        clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+        return (self.load_patcher(clip_paths, clip_type, self.load_data(clip_paths)),)
+
+class QuadrupleCLIPLoaderGGUF(CLIPLoaderGGUF):
+    @classmethod
+    def INPUT_TYPES(s):
+        file_options = (s.get_filename_list(), )
+        return {
+            "required": {
+            "clip_name1": file_options,
+            "clip_name2": file_options,
+            "clip_name3": file_options,
+            "clip_name4": file_options,
+        }
+    }
+
+    TITLE = "QuadrupleCLIPLoader (GGUF)"
+
+    def load_clip(self, clip_name1, clip_name2, clip_name3, clip_name4, type="stable_diffusion"):
+        clip_path1 = folder_paths.get_full_path("clip", clip_name1)
+        clip_path2 = folder_paths.get_full_path("clip", clip_name2)
+        clip_path3 = folder_paths.get_full_path("clip", clip_name3)
+        clip_path4 = folder_paths.get_full_path("clip", clip_name4)
+        clip_paths = (clip_path1, clip_path2, clip_path3, clip_path4)
+        clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+        return (self.load_patcher(clip_paths, clip_type, self.load_data(clip_paths)),)
+
+NODE_CLASS_MAPPINGS = {
+    "UnetLoaderGGUF": UnetLoaderGGUF,
+    "CLIPLoaderGGUF": CLIPLoaderGGUF,
+    "DualCLIPLoaderGGUF": DualCLIPLoaderGGUF,
+    "TripleCLIPLoaderGGUF": TripleCLIPLoaderGGUF,
+    "QuadrupleCLIPLoaderGGUF": QuadrupleCLIPLoaderGGUF,
+    "UnetLoaderGGUFAdvanced": UnetLoaderGGUFAdvanced,
+}
+

ComfyUI-GGUF/ops.py

@@ -0,0 +1,281 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import gguf
+import torch
+import logging
+
+import comfy.ops
+import comfy.lora
+import comfy.model_management
+from .dequant import dequantize_tensor, is_quantized
+
+def chained_hasattr(obj, chained_attr):
+    probe = obj
+    for attr in chained_attr.split('.'):
+        if hasattr(probe, attr):
+            probe = getattr(probe, attr)
+        else:
+            return False
+    return True
+
+# A bakcward and forward compatible way to get `torch.compiler.disable`.
+def get_torch_compiler_disable_decorator():
+    def dummy_decorator(*args, **kwargs):
+        def noop(x):
+            return x
+        return noop
+
+    from packaging import version
+
+    if not chained_hasattr(torch, "compiler.disable"):
+        logging.info("ComfyUI-GGUF: Torch too old for torch.compile - bypassing")
+        return dummy_decorator # torch too old
+    elif version.parse(torch.__version__) >= version.parse("2.8"):
+        logging.info("ComfyUI-GGUF: Allowing full torch compile")
+        return dummy_decorator # torch compile works
+    if chained_hasattr(torch, "_dynamo.config.nontraceable_tensor_subclasses"):
+        logging.info("ComfyUI-GGUF: Allowing full torch compile (nightly)")
+        return dummy_decorator # torch compile works, nightly before 2.8 release
+    else:
+        logging.info("ComfyUI-GGUF: Partial torch compile only, consider updating pytorch")
+        return torch.compiler.disable
+
+torch_compiler_disable = get_torch_compiler_disable_decorator()
+
+class GGMLTensor(torch.Tensor):
+    """
+    Main tensor-like class for storing quantized weights
+    """
+    def __init__(self, *args, tensor_type, tensor_shape, patches=[], **kwargs):
+        super().__init__()
+        self.tensor_type = tensor_type
+        self.tensor_shape = tensor_shape
+        self.patches = patches
+
+    def __new__(cls, *args, tensor_type, tensor_shape, patches=[], **kwargs):
+        return super().__new__(cls, *args, **kwargs)
+
+    def to(self, *args, **kwargs):
+        new = super().to(*args, **kwargs)
+        new.tensor_type = getattr(self, "tensor_type", None)
+        new.tensor_shape = getattr(self, "tensor_shape", new.data.shape)
+        new.patches = getattr(self, "patches", []).copy()
+        return new
+
+    def clone(self, *args, **kwargs):
+        return self
+
+    def detach(self, *args, **kwargs):
+        return self
+
+    def copy_(self, *args, **kwargs):
+        # fixes .weight.copy_ in comfy/clip_model/CLIPTextModel
+        try:
+            return super().copy_(*args, **kwargs)
+        except Exception as e:
+            logging.warning(f"ignoring 'copy_' on tensor: {e}")
+
+    def new_empty(self, size, *args, **kwargs):
+        # Intel Arc fix, ref#50
+        new_tensor = super().new_empty(size, *args, **kwargs)
+        return GGMLTensor(
+                new_tensor,
+                tensor_type = getattr(self, "tensor_type", None),
+                tensor_shape = size,
+                patches = getattr(self, "patches", []).copy()
+        )
+
+    @property
+    def shape(self):
+        if not hasattr(self, "tensor_shape"):
+            self.tensor_shape = self.size()
+        return self.tensor_shape
+
+class GGMLLayer(torch.nn.Module):
+    """
+    This (should) be responsible for de-quantizing on the fly
+    """
+    comfy_cast_weights = True
+    dequant_dtype = None
+    patch_dtype = None
+    largest_layer = False
+    torch_compatible_tensor_types = {None, gguf.GGMLQuantizationType.F32, gguf.GGMLQuantizationType.F16}
+
+    def is_ggml_quantized(self, *, weight=None, bias=None):
+        if weight is None:
+            weight = self.weight
+        if bias is None:
+            bias = self.bias
+        return is_quantized(weight) or is_quantized(bias)
+
+    def _load_from_state_dict(self, state_dict, prefix, *args, **kwargs):
+        weight, bias = state_dict.get(f"{prefix}weight"), state_dict.get(f"{prefix}bias")
+        # NOTE: using modified load for linear due to not initializing on creation, see GGMLOps todo
+        if self.is_ggml_quantized(weight=weight, bias=bias) or isinstance(self, torch.nn.Linear):
+            return self.ggml_load_from_state_dict(state_dict, prefix, *args, **kwargs)
+        # Not strictly required, but fixes embedding shape mismatch. Threshold set in loader.py
+        if isinstance(self, torch.nn.Embedding) and self.weight.shape[0] >= (64 * 1024):
+            return self.ggml_load_from_state_dict(state_dict, prefix, *args, **kwargs)
+        return super()._load_from_state_dict(state_dict, prefix, *args, **kwargs)
+
+    def ggml_load_from_state_dict(self, state_dict, prefix, local_metadata, strict, missing_keys, unexpected_keys, error_msgs):
+        prefix_len = len(prefix)
+        for k,v in state_dict.items():
+            if k[prefix_len:] == "weight":
+                self.weight = torch.nn.Parameter(v, requires_grad=False)
+            elif k[prefix_len:] == "bias" and v is not None:
+                self.bias = torch.nn.Parameter(v, requires_grad=False)
+            else:
+                unexpected_keys.append(k)
+
+        # For Linear layer with missing weight
+        if self.weight is None and isinstance(self, torch.nn.Linear):
+            v = torch.zeros(self.in_features, self.out_features)
+            self.weight = torch.nn.Parameter(v, requires_grad=False)
+            missing_keys.append(prefix+"weight")
+
+        # for vram estimation (TODO: less fragile logic?)
+        if getattr(self.weight, "is_largest_weight", False):
+            self.largest_layer = True
+
+    def _save_to_state_dict(self, *args, **kwargs):
+        if self.is_ggml_quantized():
+            return self.ggml_save_to_state_dict(*args, **kwargs)
+        return super()._save_to_state_dict(*args, **kwargs)
+
+    def ggml_save_to_state_dict(self, destination, prefix, keep_vars):
+        # This is a fake state dict for vram estimation
+        weight = torch.zeros_like(self.weight, device=torch.device("meta"))
+        destination[prefix + "weight"] = weight
+        if self.bias is not None:
+            bias = torch.zeros_like(self.bias, device=torch.device("meta"))
+            destination[prefix + "bias"] = bias
+
+        # Take into account space required for dequantizing the largest tensor
+        if self.largest_layer:
+            shape = getattr(self.weight, "tensor_shape", self.weight.shape)
+            dtype = self.dequant_dtype if self.dequant_dtype and self.dequant_dtype != "target" else torch.float16
+            temp = torch.empty(*shape, device=torch.device("meta"), dtype=dtype)
+            destination[prefix + "temp.weight"] = temp
+
+        return
+        # This would return the dequantized state dict
+        destination[prefix + "weight"] = self.get_weight(self.weight)
+        if bias is not None:
+            destination[prefix + "bias"] = self.get_weight(self.bias)
+
+    def get_weight(self, tensor, dtype):
+        if tensor is None:
+            return
+
+        # consolidate and load patches to GPU in async
+        patch_list = []
+        device = tensor.device
+        for patches, key in getattr(tensor, "patches", []):
+            patch_list += move_patch_to_device(patches, device)
+
+        # dequantize tensor while patches load
+        weight = dequantize_tensor(tensor, dtype, self.dequant_dtype)
+
+        # prevent propagating custom tensor class
+        if isinstance(weight, GGMLTensor):
+            weight = torch.Tensor(weight)
+
+        # apply patches
+        if len(patch_list) > 0:
+            if self.patch_dtype is None:
+                weight = comfy.lora.calculate_weight(patch_list, weight, key)
+            else:
+                # for testing, may degrade image quality
+                patch_dtype = dtype if self.patch_dtype == "target" else self.patch_dtype
+                weight = comfy.lora.calculate_weight(patch_list, weight, key, patch_dtype)
+        return weight
+
+    @torch_compiler_disable()
+    def cast_bias_weight(s, input=None, dtype=None, device=None, bias_dtype=None):
+        if input is not None:
+            if dtype is None:
+                dtype = getattr(input, "dtype", torch.float32)
+            if bias_dtype is None:
+                bias_dtype = dtype
+            if device is None:
+                device = input.device
+
+        bias = None
+        non_blocking = comfy.model_management.device_supports_non_blocking(device)
+        if s.bias is not None:
+            bias = s.get_weight(s.bias.to(device), dtype)
+            bias = comfy.ops.cast_to(bias, bias_dtype, device, non_blocking=non_blocking, copy=False)
+
+        weight = s.get_weight(s.weight.to(device), dtype)
+        weight = comfy.ops.cast_to(weight, dtype, device, non_blocking=non_blocking, copy=False)
+        return weight, bias
+
+    def forward_comfy_cast_weights(self, input, *args, **kwargs):
+        if self.is_ggml_quantized():
+            out = self.forward_ggml_cast_weights(input, *args, **kwargs)
+        else:
+            out = super().forward_comfy_cast_weights(input, *args, **kwargs)
+
+        # non-ggml forward might still propagate custom tensor class
+        if isinstance(out, GGMLTensor):
+            out = torch.Tensor(out)
+        return out
+
+    def forward_ggml_cast_weights(self, input):
+        raise NotImplementedError
+
+class GGMLOps(comfy.ops.manual_cast):
+    """
+    Dequantize weights on the fly before doing the compute
+    """
+    class Linear(GGMLLayer, comfy.ops.manual_cast.Linear):
+        def __init__(self, in_features, out_features, bias=True, device=None, dtype=None):
+            torch.nn.Module.__init__(self)
+            # TODO: better workaround for reserved memory spike on windows
+            # Issue is with `torch.empty` still reserving the full memory for the layer
+            # Windows doesn't over-commit memory so without this 24GB+ of pagefile is used
+            self.in_features = in_features
+            self.out_features = out_features
+            self.weight = None
+            self.bias = None
+
+        def forward_ggml_cast_weights(self, input):
+            weight, bias = self.cast_bias_weight(input)
+            return torch.nn.functional.linear(input, weight, bias)
+
+    class Conv2d(GGMLLayer, comfy.ops.manual_cast.Conv2d):
+        def forward_ggml_cast_weights(self, input):
+            weight, bias = self.cast_bias_weight(input)
+            return self._conv_forward(input, weight, bias)
+
+    class Embedding(GGMLLayer, comfy.ops.manual_cast.Embedding):
+        def forward_ggml_cast_weights(self, input, out_dtype=None):
+            output_dtype = out_dtype
+            if self.weight.dtype == torch.float16 or self.weight.dtype == torch.bfloat16:
+                out_dtype = None
+            weight, _bias = self.cast_bias_weight(self, device=input.device, dtype=out_dtype)
+            return torch.nn.functional.embedding(
+                input, weight, self.padding_idx, self.max_norm, self.norm_type, self.scale_grad_by_freq, self.sparse
+            ).to(dtype=output_dtype)
+
+    class LayerNorm(GGMLLayer, comfy.ops.manual_cast.LayerNorm):
+        def forward_ggml_cast_weights(self, input):
+            if self.weight is None:
+                return super().forward_comfy_cast_weights(input)
+            weight, bias = self.cast_bias_weight(input)
+            return torch.nn.functional.layer_norm(input, self.normalized_shape, weight, bias, self.eps)
+
+    class GroupNorm(GGMLLayer, comfy.ops.manual_cast.GroupNorm):
+        def forward_ggml_cast_weights(self, input):
+            weight, bias = self.cast_bias_weight(input)
+            return torch.nn.functional.group_norm(input, self.num_groups, weight, bias, self.eps)
+
+def move_patch_to_device(item, device):
+    if isinstance(item, torch.Tensor):
+        return item.to(device, non_blocking=True)
+    elif isinstance(item, tuple):
+        return tuple(move_patch_to_device(x, device) for x in item)
+    elif isinstance(item, list):
+        return [move_patch_to_device(x, device) for x in item]
+    else:
+        return item

ComfyUI-GGUF/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "ComfyUI-GGUF"
+description = "GGUF Quantization support for native ComfyUI models."
+version = "1.1.10" # 2.0.0 = GitHub main, 1.X.X = ComfyUI Registry
+license = { file = "LICENSE" }
+dependencies = ["gguf>=0.13.0", "sentencepiece", "protobuf"]
+
+[project.urls]
+Repository = "https://github.com/city96/ComfyUI-GGUF"
+
+[tool.comfy]
+PublisherId = "city96"
+DisplayName = "ComfyUI-GGUF"
+Icon = ""

ComfyUI-GGUF/requirements.txt

@@ -0,0 +1,5 @@
+# main
+gguf>=0.13.0
+# optional - tokenizer
+sentencepiece
+protobuf

ComfyUI-GGUF/tools/README.md

@@ -0,0 +1,93 @@
+## Converting initial model
+
+To convert your initial safetensors/ckpt model to FP16/BF16 GGUF, run the following command:
+
+```
+python convert.py --src E:\models\unet\flux1-dev.safetensors
+```
+Make sure `gguf>=0.13.0` is installed for this step. Optionally, specify the output gguf file with the `--dst` arg.
+
+> [!NOTE]  
+> Do not use the diffusers UNET format for flux, it won't work, use the default/reference checkpoint key format. This is due to q/k/v being merged into one qkv key.
+> You can convert it by loading it in ComfyUI and saving it using the built-in "ModelSave" node.
+
+> [!WARNING] 
+> For hunyuan video/wan 2.1, you will see a warning about 5D tensors. This means the script will save a **non functional** model to disk first, that you can quantize. I recommend saving these in a separate `raw` folder to avoid confusion.
+> 
+> After quantization, you will have to run `fix_5d_tensor.py` manually to add back the missing key that was saved by the conversion code.
+
+## Quantizing using custom llama.cpp
+
+Depending on your git settings, you may need to run the following script first in order to make sure the patch file is valid. It will convert Windows (CRLF) line endings to Unix (LF) ones.
+
+```
+python fix_lines_ending.py
+```
+
+Git clone llama.cpp into the current folder:
+
+```
+git clone https://github.com/ggerganov/llama.cpp
+```
+
+Check out the correct branch, then apply the custom patch needed to add image model support to the repo you just cloned.
+
+```
+cd llama.cpp
+git checkout tags/b3962
+git apply ..\lcpp.patch
+```
+
+Compile the llama-quantize binary. This example uses cmake, on linux you can just use make.
+
+### Visual Studio 2019, Linux, etc...
+
+```
+mkdir build
+cmake -B build
+cmake --build build --config Debug -j10 --target llama-quantize
+cd ..
+```
+
+### Visual Studio 2022
+
+```
+mkdir build
+cmake -B build -DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=ON -DCMAKE_CXX_FLAGS="-std=c++17"
+```
+
+Edit the `llama.cpp\common\log.cpp` file, inserts two lines after the existing first line:
+
+```
+#include "log.h"
+
+#define _SILENCE_CXX23_CHRONO_DEPRECATION_WARNING
+#include <chrono>
+```
+
+Then you can build the project:
+```
+cmake --build build --config Debug -j10 --target llama-quantize
+cd ..
+```
+
+### Quantize your model
+
+
+Now you can use the newly build binary to quantize your model to the desired format:
+```
+llama.cpp\build\bin\Debug\llama-quantize.exe E:\models\unet\flux1-dev-BF16.gguf E:\models\unet\flux1-dev-Q4_K_S.gguf Q4_K_S
+```
+
+You can extract the patch again with `git diff src\llama.cpp > lcpp.patch` if you wish to change something and contribute back.
+
+> [!WARNING] 
+> For hunyuan video/wan 2.1, you will have to run `fix_5d_tensor.py` after the quantization step is done.
+>
+> Example usage:  `fix_5d_tensors.py --src E:\models\video\raw\wan2.1-t2v-1.3b-Q8_0.gguf --dst E:\models\video\wan2.1-t2v-1.3b-Q8_0.gguf`
+>
+> By default, this also saves a `fix_5d_tensors_[arch].safetensors` file in the `ComfyUI-GGUF/tools` folder, it's recommended to delete this after all models have been converted.
+
+> [!NOTE]
+> Do not quantize SDXL / SD1 / other Conv2D heavy models. If you do, make sure to **extract the UNET model first**.
+>This should be obvious, but also don't use the resulting llama-quantize binary with LLMs.

ComfyUI-GGUF/tools/convert.py

@@ -0,0 +1,365 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import os
+import gguf
+import torch
+import logging
+import argparse
+from tqdm import tqdm
+from safetensors.torch import load_file, save_file
+
+QUANTIZATION_THRESHOLD = 1024
+REARRANGE_THRESHOLD = 512
+MAX_TENSOR_NAME_LENGTH = 127
+MAX_TENSOR_DIMS = 4
+
+class ModelTemplate:
+    arch = "invalid"  # string describing architecture
+    shape_fix = False # whether to reshape tensors
+    keys_detect = []  # list of lists to match in state dict
+    keys_banned = []  # list of keys that should mark model as invalid for conversion
+    keys_hiprec = []  # list of keys that need to be kept in fp32 for some reason
+    keys_ignore = []  # list of strings to ignore keys by when found
+
+    def handle_nd_tensor(self, key, data):
+        raise NotImplementedError(f"Tensor detected that exceeds dims supported by C++ code! ({key} @ {data.shape})")
+
+class ModelFlux(ModelTemplate):
+    arch = "flux"
+    keys_detect = [
+        ("transformer_blocks.0.attn.norm_added_k.weight",),
+        ("double_blocks.0.img_attn.proj.weight",),
+    ]
+    keys_banned = ["transformer_blocks.0.attn.norm_added_k.weight",]
+
+class ModelSD3(ModelTemplate):
+    arch = "sd3"
+    keys_detect = [
+        ("transformer_blocks.0.attn.add_q_proj.weight",),
+        ("joint_blocks.0.x_block.attn.qkv.weight",),
+    ]
+    keys_banned = ["transformer_blocks.0.attn.add_q_proj.weight",]
+
+class ModelAura(ModelTemplate):
+    arch = "aura"
+    keys_detect = [
+        ("double_layers.3.modX.1.weight",),
+        ("joint_transformer_blocks.3.ff_context.out_projection.weight",),
+    ]
+    keys_banned = ["joint_transformer_blocks.3.ff_context.out_projection.weight",]
+
+class ModelHiDream(ModelTemplate):
+    arch = "hidream"
+    keys_detect = [
+        (
+            "caption_projection.0.linear.weight",
+            "double_stream_blocks.0.block.ff_i.shared_experts.w3.weight"
+        )
+    ]
+    keys_hiprec = [
+        # nn.parameter, can't load from BF16 ver
+        ".ff_i.gate.weight",
+        "img_emb.emb_pos"
+    ]
+
+class CosmosPredict2(ModelTemplate):
+    arch = "cosmos"
+    keys_detect = [
+        (
+            "blocks.0.mlp.layer1.weight",
+            "blocks.0.adaln_modulation_cross_attn.1.weight",
+        )
+    ]
+    keys_hiprec = ["pos_embedder"]
+    keys_ignore = ["_extra_state", "accum_"]
+
+class ModelHyVid(ModelTemplate):
+    arch = "hyvid"
+    keys_detect = [
+        (
+            "double_blocks.0.img_attn_proj.weight",
+            "txt_in.individual_token_refiner.blocks.1.self_attn_qkv.weight",
+        )
+    ]
+
+    def handle_nd_tensor(self, key, data):
+        # hacky but don't have any better ideas
+        path = f"./fix_5d_tensors_{self.arch}.safetensors" # TODO: somehow get a path here??
+        if os.path.isfile(path):
+            raise RuntimeError(f"5D tensor fix file already exists! {path}")
+        fsd = {key: torch.from_numpy(data)}
+        tqdm.write(f"5D key found in state dict! Manual fix required! - {key} {data.shape}")
+        save_file(fsd, path)
+
+class ModelWan(ModelHyVid):
+    arch = "wan"
+    keys_detect = [
+        (
+            "blocks.0.self_attn.norm_q.weight",
+            "text_embedding.2.weight",
+            "head.modulation",
+        )
+    ]
+    keys_hiprec = [
+        ".modulation" # nn.parameter, can't load from BF16 ver
+    ]
+
+class ModelLTXV(ModelTemplate):
+    arch = "ltxv"
+    keys_detect = [
+        (
+            "adaln_single.emb.timestep_embedder.linear_2.weight",
+            "transformer_blocks.27.scale_shift_table",
+            "caption_projection.linear_2.weight",
+        )
+    ]
+    keys_hiprec = [
+        "scale_shift_table" # nn.parameter, can't load from BF16 base quant
+    ]
+
+class ModelSDXL(ModelTemplate):
+    arch = "sdxl"
+    shape_fix = True
+    keys_detect = [
+        ("down_blocks.0.downsamplers.0.conv.weight", "add_embedding.linear_1.weight",),
+        (
+            "input_blocks.3.0.op.weight", "input_blocks.6.0.op.weight",
+            "output_blocks.2.2.conv.weight", "output_blocks.5.2.conv.weight",
+        ), # Non-diffusers
+        ("label_emb.0.0.weight",),
+    ]
+
+class ModelSD1(ModelTemplate):
+    arch = "sd1"
+    shape_fix = True
+    keys_detect = [
+        ("down_blocks.0.downsamplers.0.conv.weight",),
+        (
+            "input_blocks.3.0.op.weight", "input_blocks.6.0.op.weight", "input_blocks.9.0.op.weight",
+            "output_blocks.2.1.conv.weight", "output_blocks.5.2.conv.weight", "output_blocks.8.2.conv.weight"
+        ), # Non-diffusers
+    ]
+
+class ModelLumina2(ModelTemplate):
+    arch = "lumina2"
+    keys_detect = [
+        ("cap_embedder.1.weight", "context_refiner.0.attention.qkv.weight")
+    ]
+
+arch_list = [ModelFlux, ModelSD3, ModelAura, ModelHiDream, CosmosPredict2, 
+             ModelLTXV, ModelHyVid, ModelWan, ModelSDXL, ModelSD1, ModelLumina2]
+
+def is_model_arch(model, state_dict):
+    # check if model is correct
+    matched = False
+    invalid = False
+    for match_list in model.keys_detect:
+        if all(key in state_dict for key in match_list):
+            matched = True
+            invalid = any(key in state_dict for key in model.keys_banned)
+            break
+    assert not invalid, "Model architecture not allowed for conversion! (i.e. reference VS diffusers format)"
+    return matched
+
+def detect_arch(state_dict):
+    model_arch = None
+    for arch in arch_list:
+        if is_model_arch(arch, state_dict):
+            model_arch = arch()
+            break
+    assert model_arch is not None, "Unknown model architecture!"
+    return model_arch
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Generate F16 GGUF files from single UNET")
+    parser.add_argument("--src", required=True, help="Source model ckpt file.")
+    parser.add_argument("--dst", help="Output unet gguf file.")
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.src):
+        parser.error("No input provided!")
+
+    return args
+
+def strip_prefix(state_dict):
+    # prefix for mixed state dict
+    prefix = None
+    for pfx in ["model.diffusion_model.", "model."]:
+        if any([x.startswith(pfx) for x in state_dict.keys()]):
+            prefix = pfx
+            break
+
+    # prefix for uniform state dict
+    if prefix is None:
+        for pfx in ["net."]:
+            if all([x.startswith(pfx) for x in state_dict.keys()]):
+                prefix = pfx
+                break
+
+    # strip prefix if found
+    if prefix is not None:
+        logging.info(f"State dict prefix found: '{prefix}'")
+        sd = {}
+        for k, v in state_dict.items():
+            if prefix not in k:
+                continue
+            k = k.replace(prefix, "")
+            sd[k] = v
+    else:
+        logging.debug("State dict has no prefix")
+        sd = state_dict
+
+    return sd
+
+def load_state_dict(path):
+    if any(path.endswith(x) for x in [".ckpt", ".pt", ".bin", ".pth"]):
+        state_dict = torch.load(path, map_location="cpu", weights_only=True)
+        for subkey in ["model", "module"]:
+            if subkey in state_dict:
+                state_dict = state_dict[subkey]
+                break
+        if len(state_dict) < 20:
+            raise RuntimeError(f"pt subkey load failed: {state_dict.keys()}")
+    else:
+        state_dict = load_file(path)
+
+    return strip_prefix(state_dict)
+
+def handle_tensors(writer, state_dict, model_arch):
+    name_lengths = tuple(sorted(
+        ((key, len(key)) for key in state_dict.keys()),
+        key=lambda item: item[1],
+        reverse=True,
+    ))
+    if not name_lengths:
+        return
+    max_name_len = name_lengths[0][1]
+    if max_name_len > MAX_TENSOR_NAME_LENGTH:
+        bad_list = ", ".join(f"{key!r} ({namelen})" for key, namelen in name_lengths if namelen > MAX_TENSOR_NAME_LENGTH)
+        raise ValueError(f"Can only handle tensor names up to {MAX_TENSOR_NAME_LENGTH} characters. Tensors exceeding the limit: {bad_list}")
+    for key, data in tqdm(state_dict.items()):
+        old_dtype = data.dtype
+
+        if any(x in key for x in model_arch.keys_ignore):
+            tqdm.write(f"Filtering ignored key: '{key}'")
+            continue
+
+        if data.dtype == torch.bfloat16:
+            data = data.to(torch.float32).numpy()
+        # this is so we don't break torch 2.0.X
+        elif data.dtype in [getattr(torch, "float8_e4m3fn", "_invalid"), getattr(torch, "float8_e5m2", "_invalid")]:
+            data = data.to(torch.float16).numpy()
+        else:
+            data = data.numpy()
+
+        n_dims = len(data.shape)
+        data_shape = data.shape
+        if old_dtype == torch.bfloat16:
+            data_qtype = gguf.GGMLQuantizationType.BF16
+        # elif old_dtype == torch.float32:
+        #     data_qtype = gguf.GGMLQuantizationType.F32
+        else:
+            data_qtype = gguf.GGMLQuantizationType.F16
+
+        # The max no. of dimensions that can be handled by the quantization code is 4
+        if len(data.shape) > MAX_TENSOR_DIMS:
+            model_arch.handle_nd_tensor(key, data)
+            continue # needs to be added back later
+
+        # get number of parameters (AKA elements) in this tensor
+        n_params = 1
+        for dim_size in data_shape:
+            n_params *= dim_size
+
+        if old_dtype in (torch.float32, torch.bfloat16):
+            if n_dims == 1:
+                # one-dimensional tensors should be kept in F32
+                # also speeds up inference due to not dequantizing
+                data_qtype = gguf.GGMLQuantizationType.F32
+
+            elif n_params <= QUANTIZATION_THRESHOLD:
+                # very small tensors
+                data_qtype = gguf.GGMLQuantizationType.F32
+
+            elif any(x in key for x in model_arch.keys_hiprec):
+                # tensors that require max precision
+                data_qtype = gguf.GGMLQuantizationType.F32
+
+        if (model_arch.shape_fix                        # NEVER reshape for models such as flux
+            and n_dims > 1                              # Skip one-dimensional tensors
+            and n_params >= REARRANGE_THRESHOLD         # Only rearrange tensors meeting the size requirement
+            and (n_params / 256).is_integer()           # Rearranging only makes sense if total elements is divisible by 256
+            and not (data.shape[-1] / 256).is_integer() # Only need to rearrange if the last dimension is not divisible by 256
+        ):
+            orig_shape = data.shape
+            data = data.reshape(n_params // 256, 256)
+            writer.add_array(f"comfy.gguf.orig_shape.{key}", tuple(int(dim) for dim in orig_shape))
+
+        try:
+            data = gguf.quants.quantize(data, data_qtype)
+        except (AttributeError, gguf.QuantError) as e:
+            tqdm.write(f"falling back to F16: {e}")
+            data_qtype = gguf.GGMLQuantizationType.F16
+            data = gguf.quants.quantize(data, data_qtype)
+
+        new_name = key # do we need to rename?
+
+        shape_str = f"{{{', '.join(str(n) for n in reversed(data.shape))}}}"
+        tqdm.write(f"{f'%-{max_name_len + 4}s' % f'{new_name}'} {old_dtype} --> {data_qtype.name}, shape = {shape_str}")
+
+        writer.add_tensor(new_name, data, raw_dtype=data_qtype)
+
+def convert_file(path, dst_path=None, interact=True, overwrite=False):
+    # load & run model detection logic
+    state_dict = load_state_dict(path)
+    model_arch = detect_arch(state_dict)
+    logging.info(f"* Architecture detected from input: {model_arch.arch}")
+
+    # detect & set dtype for output file
+    dtypes = [x.dtype for x in state_dict.values()]
+    dtypes = {x:dtypes.count(x) for x in set(dtypes)}
+    main_dtype = max(dtypes, key=dtypes.get)
+
+    if main_dtype == torch.bfloat16:
+        ftype_name = "BF16"
+        ftype_gguf = gguf.LlamaFileType.MOSTLY_BF16
+    # elif main_dtype == torch.float32:
+    #     ftype_name = "F32"
+    #     ftype_gguf = None
+    else:
+        ftype_name = "F16"
+        ftype_gguf = gguf.LlamaFileType.MOSTLY_F16
+
+    if dst_path is None:
+        dst_path = f"{os.path.splitext(path)[0]}-{ftype_name}.gguf"
+    elif "{ftype}" in dst_path: # lcpp logic
+        dst_path = dst_path.replace("{ftype}", ftype_name)
+
+    if os.path.isfile(dst_path) and not overwrite:
+        if interact:
+            input("Output exists enter to continue or ctrl+c to abort!")
+        else:
+            raise OSError("Output exists and overwriting is disabled!")
+
+    # handle actual file
+    writer = gguf.GGUFWriter(path=None, arch=model_arch.arch)
+    writer.add_quantization_version(gguf.GGML_QUANT_VERSION)
+    if ftype_gguf is not None:
+        writer.add_file_type(ftype_gguf)
+
+    handle_tensors(writer, state_dict, model_arch)
+    writer.write_header_to_file(path=dst_path)
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file(progress=True)
+    writer.close()
+
+    fix = f"./fix_5d_tensors_{model_arch.arch}.safetensors"
+    if os.path.isfile(fix):
+        logging.warning(f"\n### Warning! Fix file found at '{fix}'")
+        logging.warning(" you most likely need to run 'fix_5d_tensors.py' after quantization.")
+
+    return dst_path, model_arch
+
+if __name__ == "__main__":
+    args = parse_args()
+    convert_file(args.src, args.dst)
+

ComfyUI-GGUF/tools/fix_5d_tensors.py

@@ -0,0 +1,82 @@
+# (c) City96 || Apache-2.0 (apache.org/licenses/LICENSE-2.0)
+import os
+import gguf
+import torch
+import argparse
+from tqdm import tqdm
+from safetensors.torch import load_file
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--src", required=True)
+    parser.add_argument("--dst", required=True)
+    parser.add_argument("--fix", required=False, help="Defaults to ./fix_5d_tensors_[arch].pt")
+    parser.add_argument("--overwrite", action="store_true")
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.src):
+        parser.error(f"Invalid source file '{args.src}'")
+    if not args.overwrite and os.path.exists(args.dst):
+        parser.error(f"Output exists, use '--overwrite' ({args.dst})")
+
+    return args
+
+def get_arch_str(reader):
+    field = reader.get_field("general.architecture")
+    return str(field.parts[field.data[-1]], encoding="utf-8")
+
+def get_file_type(reader):
+    field = reader.get_field("general.file_type")
+    ft = int(field.parts[field.data[-1]])
+    return gguf.LlamaFileType(ft)
+
+if __name__ == "__main__":
+    args = get_args()
+
+    # read existing
+    reader = gguf.GGUFReader(args.src)
+    arch = get_arch_str(reader)
+    file_type = get_file_type(reader)
+    print(f"Detected arch: '{arch}' (ftype: {str(file_type)})")
+
+    # prep fix
+    if args.fix is None:
+        args.fix = f"./fix_5d_tensors_{arch}.safetensors"
+ 
+    if not os.path.isfile(args.fix):
+        raise OSError(f"No 5D tensor fix file: {args.fix}")
+
+    sd5d = load_file(args.fix)
+    sd5d = {k:v.numpy() for k,v in sd5d.items()}
+    print("5D tensors:", sd5d.keys())
+
+    # prep output
+    writer = gguf.GGUFWriter(path=None, arch=arch)
+    writer.add_quantization_version(gguf.GGML_QUANT_VERSION)
+    writer.add_file_type(file_type)
+
+    added = []
+    def add_extra_key(writer, key, data):
+        global added
+        data_qtype = gguf.GGMLQuantizationType.F32
+        data = gguf.quants.quantize(data, data_qtype)
+        tqdm.write(f"Adding key {key} ({data.shape})")
+        writer.add_tensor(key, data, raw_dtype=data_qtype)
+        added.append(key)
+
+    # main loop to add missing 5D tensor(s)
+    for tensor in tqdm(reader.tensors):
+        writer.add_tensor(tensor.name, tensor.data, raw_dtype=tensor.tensor_type)
+        key5d = tensor.name.replace(".bias", ".weight")
+        if key5d in sd5d.keys():
+            add_extra_key(writer, key5d, sd5d[key5d])
+
+    # brute force for any missed
+    for key, data in sd5d.items():
+        if key not in added:
+            add_extra_key(writer, key, data)
+
+    writer.write_header_to_file(path=args.dst)
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file(progress=True)
+    writer.close()

ComfyUI-GGUF/tools/fix_lines_ending.py

@@ -0,0 +1,31 @@
+import os
+
+files = ["lcpp.patch", "lcpp_sd3.patch"]
+
+def has_unix_line_endings(file_path):
+    try:
+        with open(file_path, 'rb') as file:
+            content = file.read()
+        return b'\r\n' not in content
+    except Exception as e:
+        print(f"Error checking '{file_path}': {e}")
+        return False
+
+def convert_to_linux_format(file_path):
+    try:
+        with open(file_path, 'rb') as file:
+            content = file.read().replace(b'\r\n', b'\n')
+        with open(file_path, 'wb') as file:
+            file.write(content)
+        print(f"'{file_path}' converted to Linux line endings (LF).")
+    except Exception as e:
+        print(f"Error processing '{file_path}': {e}")
+
+for file in files:
+    if os.path.exists(file):
+        if has_unix_line_endings(file):
+            print(f"'{file}' already has Unix line endings (LF). No conversion needed.")
+        else:
+            convert_to_linux_format(file)
+    else:
+        print(f"File '{file}' does not exist.")

ComfyUI-GGUF/tools/lcpp.patch

@@ -0,0 +1,451 @@
+diff --git a/ggml/include/ggml.h b/ggml/include/ggml.h
+index de3c706f..0267c1fa 100644
+--- a/ggml/include/ggml.h
++++ b/ggml/include/ggml.h
+@@ -223,7 +223,7 @@
+ #define GGML_MAX_OP_PARAMS      64
+ 
+ #ifndef GGML_MAX_NAME
+-#   define GGML_MAX_NAME        64
++#   define GGML_MAX_NAME        128
+ #endif
+ 
+ #define GGML_DEFAULT_N_THREADS  4
+@@ -2449,6 +2449,7 @@ extern "C" {
+ 
+     // manage tensor info
+     GGML_API void gguf_add_tensor(struct gguf_context * ctx, const struct ggml_tensor * tensor);
++    GGML_API void gguf_set_tensor_ndim(struct gguf_context * ctx, const char * name, int n_dim);
+     GGML_API void gguf_set_tensor_type(struct gguf_context * ctx, const char * name, enum ggml_type type);
+     GGML_API void gguf_set_tensor_data(struct gguf_context * ctx, const char * name, const void * data, size_t size);
+ 
+diff --git a/ggml/src/ggml.c b/ggml/src/ggml.c
+index b16c462f..6d1568f1 100644
+--- a/ggml/src/ggml.c
++++ b/ggml/src/ggml.c
+@@ -22960,6 +22960,14 @@ void gguf_add_tensor(
+     ctx->header.n_tensors++;
+ }
+ 
++void gguf_set_tensor_ndim(struct gguf_context * ctx, const char * name, const int n_dim) {
++    const int idx = gguf_find_tensor(ctx, name);
++    if (idx < 0) {
++        GGML_ABORT("tensor not found");
++    }
++    ctx->infos[idx].n_dims = n_dim;
++}
++
+ void gguf_set_tensor_type(struct gguf_context * ctx, const char * name, enum ggml_type type) {
+     const int idx = gguf_find_tensor(ctx, name);
+     if (idx < 0) {
+diff --git a/src/llama.cpp b/src/llama.cpp
+index 24e1f1f0..25db4c69 100644
+--- a/src/llama.cpp
++++ b/src/llama.cpp
+@@ -205,6 +205,17 @@ enum llm_arch {
+     LLM_ARCH_GRANITE,
+     LLM_ARCH_GRANITE_MOE,
+     LLM_ARCH_CHAMELEON,
++    LLM_ARCH_FLUX,
++    LLM_ARCH_SD1,
++    LLM_ARCH_SDXL,
++    LLM_ARCH_SD3,
++    LLM_ARCH_AURA,
++    LLM_ARCH_LTXV,
++    LLM_ARCH_HYVID,
++    LLM_ARCH_WAN,
++    LLM_ARCH_HIDREAM,
++    LLM_ARCH_COSMOS,
++    LLM_ARCH_LUMINA2,
+     LLM_ARCH_UNKNOWN,
+ };
+ 
+@@ -258,6 +269,17 @@ static const std::map<llm_arch, const char *> LLM_ARCH_NAMES = {
+     { LLM_ARCH_GRANITE,         "granite"      },
+     { LLM_ARCH_GRANITE_MOE,     "granitemoe"   },
+     { LLM_ARCH_CHAMELEON,       "chameleon"    },
++    { LLM_ARCH_FLUX,            "flux"         },
++    { LLM_ARCH_SD1,             "sd1"          },
++    { LLM_ARCH_SDXL,            "sdxl"         },
++    { LLM_ARCH_SD3,             "sd3"          },
++    { LLM_ARCH_AURA,            "aura"         },
++    { LLM_ARCH_LTXV,            "ltxv"         },
++    { LLM_ARCH_HYVID,           "hyvid"        },
++    { LLM_ARCH_WAN,             "wan"          },
++    { LLM_ARCH_HIDREAM,         "hidream"      },
++    { LLM_ARCH_COSMOS,          "cosmos"       },
++    { LLM_ARCH_LUMINA2,         "lumina2"      },
+     { LLM_ARCH_UNKNOWN,         "(unknown)"    },
+ };
+ 
+@@ -1531,6 +1553,17 @@ static const std::map<llm_arch, std::map<llm_tensor, const char *>> LLM_TENSOR_N
+             { LLM_TENSOR_ATTN_K_NORM,     "blk.%d.attn_k_norm" },
+         },
+     },
++    { LLM_ARCH_FLUX,    {}},
++    { LLM_ARCH_SD1,     {}},
++    { LLM_ARCH_SDXL,    {}},
++    { LLM_ARCH_SD3,     {}},
++    { LLM_ARCH_AURA,    {}},
++    { LLM_ARCH_LTXV,    {}},
++    { LLM_ARCH_HYVID,   {}},
++    { LLM_ARCH_WAN,     {}},
++    { LLM_ARCH_HIDREAM, {}},
++    { LLM_ARCH_COSMOS,  {}},
++    { LLM_ARCH_LUMINA2, {}},
+     {
+         LLM_ARCH_UNKNOWN,
+         {
+@@ -5403,6 +5436,25 @@ static void llm_load_hparams(
+     // get general kv
+     ml.get_key(LLM_KV_GENERAL_NAME, model.name, false);
+ 
++    // Disable LLM metadata for image models
++    switch (model.arch) {
++        case LLM_ARCH_FLUX:
++        case LLM_ARCH_SD1:
++        case LLM_ARCH_SDXL:
++        case LLM_ARCH_SD3:
++        case LLM_ARCH_AURA:
++        case LLM_ARCH_LTXV:
++        case LLM_ARCH_HYVID:
++        case LLM_ARCH_WAN:
++        case LLM_ARCH_HIDREAM:
++        case LLM_ARCH_COSMOS:
++        case LLM_ARCH_LUMINA2:
++            model.ftype = ml.ftype;
++            return;
++        default:
++            break;
++    }
++
+     // get hparams kv
+     ml.get_key(LLM_KV_VOCAB_SIZE, hparams.n_vocab, false) || ml.get_arr_n(LLM_KV_TOKENIZER_LIST, hparams.n_vocab);
+ 
+@@ -18016,6 +18068,134 @@ static void llama_tensor_dequantize_internal(
+     workers.clear();
+ }
+ 
++static ggml_type img_tensor_get_type(quantize_state_internal & qs, ggml_type new_type, const ggml_tensor * tensor, llama_ftype ftype) {
++    // Special function for quantizing image model tensors
++    const std::string name = ggml_get_name(tensor);
++    const llm_arch arch = qs.model.arch;
++
++    // Sanity check
++    if (
++            (name.find("model.diffusion_model.") != std::string::npos) ||
++            (name.find("first_stage_model.") != std::string::npos) ||
++            (name.find("single_transformer_blocks.") != std::string::npos) ||
++            (name.find("joint_transformer_blocks.") != std::string::npos)
++        ) {
++            throw std::runtime_error("Invalid input GGUF file. This is not a supported UNET model");
++    }
++
++    // Unsupported quant types - exclude all IQ quants for now
++    if (ftype == LLAMA_FTYPE_MOSTLY_IQ2_XXS || ftype == LLAMA_FTYPE_MOSTLY_IQ2_XS  ||
++        ftype == LLAMA_FTYPE_MOSTLY_IQ2_S   || ftype == LLAMA_FTYPE_MOSTLY_IQ2_M  ||
++        ftype == LLAMA_FTYPE_MOSTLY_IQ3_XXS || ftype == LLAMA_FTYPE_MOSTLY_IQ1_S  ||
++        ftype == LLAMA_FTYPE_MOSTLY_IQ1_M   || ftype == LLAMA_FTYPE_MOSTLY_IQ4_NL ||
++        ftype == LLAMA_FTYPE_MOSTLY_IQ4_XS  || ftype == LLAMA_FTYPE_MOSTLY_IQ3_S  ||
++        ftype == LLAMA_FTYPE_MOSTLY_IQ3_M   || ftype == LLAMA_FTYPE_MOSTLY_Q4_0_4_4 ||
++        ftype == LLAMA_FTYPE_MOSTLY_Q4_0_4_8 || ftype == LLAMA_FTYPE_MOSTLY_Q4_0_8_8) {
++        throw std::runtime_error("Invalid quantization type for image model (Not supported)");
++    }
++
++    if ( // Rules for to_v attention
++            (name.find("attn_v.weight") != std::string::npos) ||
++            (name.find(".to_v.weight") != std::string::npos) ||
++            (name.find(".v.weight") != std::string::npos) ||
++            (name.find(".attn.w1v.weight") != std::string::npos) ||
++            (name.find(".attn.w2v.weight") != std::string::npos) ||
++            (name.find("_attn.v_proj.weight") != std::string::npos)
++        ){
++            if (ftype == LLAMA_FTYPE_MOSTLY_Q2_K) {
++                new_type = GGML_TYPE_Q3_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q3_K_M) {
++                new_type = qs.i_attention_wv < 2 ? GGML_TYPE_Q5_K : GGML_TYPE_Q4_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q3_K_L) {
++                new_type = GGML_TYPE_Q5_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_K_M || ftype == LLAMA_FTYPE_MOSTLY_Q5_K_M) {
++                new_type = GGML_TYPE_Q6_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_K_S && qs.i_attention_wv < 4) {
++                new_type = GGML_TYPE_Q5_K;
++            }
++            ++qs.i_attention_wv;
++    } else if ( // Rules for fused qkv attention
++            (name.find("attn_qkv.weight") != std::string::npos) ||
++            (name.find("attn.qkv.weight") != std::string::npos) ||
++            (name.find("attention.qkv.weight") != std::string::npos)
++        ) {
++            if (ftype == LLAMA_FTYPE_MOSTLY_Q3_K_M || ftype == LLAMA_FTYPE_MOSTLY_Q3_K_L) {
++                new_type = GGML_TYPE_Q4_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_K_M) {
++                new_type = GGML_TYPE_Q5_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q5_K_M) {
++                new_type = GGML_TYPE_Q6_K;
++            }
++    } else if ( // Rules for ffn
++            (name.find("ffn_down") != std::string::npos) ||
++            ((name.find("experts.") != std::string::npos) && (name.find(".w2.weight") != std::string::npos)) ||
++            (name.find(".ffn.2.weight") != std::string::npos) || // is this even the right way around?
++            (name.find(".ff.net.2.weight") != std::string::npos) ||
++            (name.find(".mlp.layer2.weight") != std::string::npos) ||
++            (name.find(".adaln_modulation_mlp.2.weight") != std::string::npos) ||
++            (name.find(".feed_forward.w2.weight") != std::string::npos)
++        ) {
++            // TODO: add back `layer_info` with some model specific logic + logic further down
++            if (ftype == LLAMA_FTYPE_MOSTLY_Q3_K_M) {
++                new_type = GGML_TYPE_Q4_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q3_K_L) {
++                new_type = GGML_TYPE_Q5_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_K_S) {
++                new_type = GGML_TYPE_Q5_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_K_M) {
++                new_type = GGML_TYPE_Q6_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q5_K_M) {
++                new_type = GGML_TYPE_Q6_K;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q4_0) {
++                new_type = GGML_TYPE_Q4_1;
++            }
++            else if (ftype == LLAMA_FTYPE_MOSTLY_Q5_0) {
++                new_type = GGML_TYPE_Q5_1;
++            }
++            ++qs.i_ffn_down;
++    }
++
++    // Sanity check for row shape
++    bool convert_incompatible_tensor = false;
++    if (new_type == GGML_TYPE_Q2_K    || new_type == GGML_TYPE_Q3_K    || new_type == GGML_TYPE_Q4_K   ||
++        new_type == GGML_TYPE_Q5_K    || new_type == GGML_TYPE_Q6_K) {
++        int nx = tensor->ne[0];
++        int ny = tensor->ne[1];
++        if (nx % QK_K != 0) {
++            LLAMA_LOG_WARN("\n\n%s : tensor cols %d x %d are not divisible by %d, required for %s", __func__, nx, ny, QK_K, ggml_type_name(new_type));
++            convert_incompatible_tensor = true;
++        } else {
++            ++qs.n_k_quantized;
++        }
++    }
++    if (convert_incompatible_tensor) {
++        // TODO: Possibly reenable this in the future
++        // switch (new_type) {
++        //     case GGML_TYPE_Q2_K:
++        //     case GGML_TYPE_Q3_K:
++        //     case GGML_TYPE_Q4_K:   new_type = GGML_TYPE_Q5_0;   break;
++        //     case GGML_TYPE_Q5_K:   new_type = GGML_TYPE_Q5_1;   break;
++        //     case GGML_TYPE_Q6_K:   new_type = GGML_TYPE_Q8_0;   break;
++        //     default: throw std::runtime_error("\nUnsupported tensor size encountered\n");
++        // }
++        new_type = GGML_TYPE_F16;
++        LLAMA_LOG_WARN(" - using fallback quantization %s\n", ggml_type_name(new_type));
++        ++qs.n_fallback;
++    }
++    return new_type;
++}
++
+ static ggml_type llama_tensor_get_type(quantize_state_internal & qs, ggml_type new_type, const ggml_tensor * tensor, llama_ftype ftype) {
+     const std::string name = ggml_get_name(tensor);
+ 
+@@ -18513,7 +18693,9 @@ static void llama_model_quantize_internal(const std::string & fname_inp, const s
+         if (llama_model_has_encoder(&model)) {
+             n_attn_layer *= 3;
+         }
+-        GGML_ASSERT((qs.n_attention_wv == n_attn_layer) && "n_attention_wv is unexpected");
++        if (model.arch != LLM_ARCH_HYVID) { // TODO: Check why this fails
++            GGML_ASSERT((qs.n_attention_wv == n_attn_layer) && "n_attention_wv is unexpected");
++        }
+     }
+ 
+     size_t total_size_org = 0;
+@@ -18547,6 +18729,51 @@ static void llama_model_quantize_internal(const std::string & fname_inp, const s
+             ctx_outs[i_split] = gguf_init_empty();
+         }
+         gguf_add_tensor(ctx_outs[i_split], tensor);
++        // SD3 pos_embed needs special fix as first dim is 1, which gets truncated here
++        if (model.arch == LLM_ARCH_SD3) {
++            const std::string name = ggml_get_name(tensor);
++            if (name == "pos_embed" && tensor->ne[2] == 1) {
++                const int n_dim = 3;
++                gguf_set_tensor_ndim(ctx_outs[i_split], "pos_embed", n_dim);
++                LLAMA_LOG_INFO("\n%s: Correcting pos_embed shape for SD3: [key:%s]\n", __func__, tensor->name);
++            }
++        }
++        // same goes for auraflow
++        if (model.arch == LLM_ARCH_AURA) {
++            const std::string name = ggml_get_name(tensor);
++            if (name == "positional_encoding" && tensor->ne[2] == 1) {
++                const int n_dim = 3;
++                gguf_set_tensor_ndim(ctx_outs[i_split], "positional_encoding", n_dim);
++                LLAMA_LOG_INFO("\n%s: Correcting positional_encoding shape for AuraFlow: [key:%s]\n", __func__, tensor->name);
++            }
++            if (name == "register_tokens" && tensor->ne[2] == 1) {
++                const int n_dim = 3;
++                gguf_set_tensor_ndim(ctx_outs[i_split], "register_tokens", n_dim);
++                LLAMA_LOG_INFO("\n%s: Correcting register_tokens shape for AuraFlow: [key:%s]\n", __func__, tensor->name);
++            }
++        }
++        // conv3d fails due to max dims - unsure what to do here as we never even reach this check
++        if (model.arch == LLM_ARCH_HYVID) {
++            const std::string name = ggml_get_name(tensor);
++            if (name == "img_in.proj.weight" && tensor->ne[5] != 1 ) {
++                throw std::runtime_error("img_in.proj.weight size failed for HyVid");
++            }
++        }
++        // All the modulation layers also have dim1, and I think conv3d fails here too but we segfaul way before that...
++        if (model.arch == LLM_ARCH_WAN) {
++            const std::string name = ggml_get_name(tensor);
++            if (name.find(".modulation") != std::string::npos && tensor->ne[2] == 1) {
++                const int n_dim = 3;
++                gguf_set_tensor_ndim(ctx_outs[i_split], tensor->name, n_dim);
++                LLAMA_LOG_INFO("\n%s: Correcting shape for Wan: [key:%s]\n", __func__, tensor->name);
++            }
++            // FLF2V model only
++            if (name == "img_emb.emb_pos") {
++                const int n_dim = 3;
++                gguf_set_tensor_ndim(ctx_outs[i_split], tensor->name, n_dim);
++                LLAMA_LOG_INFO("\n%s: Correcting shape for Wan FLF2V: [key:%s]\n", __func__, tensor->name);
++            }
++        }
+     }
+ 
+     // Set split info if needed
+@@ -18647,6 +18874,110 @@ static void llama_model_quantize_internal(const std::string & fname_inp, const s
+         // do not quantize relative position bias (T5)
+         quantize &= name.find("attn_rel_b.weight") == std::string::npos;
+ 
++        // rules for image models
++        bool image_model = false;
++        if (model.arch == LLM_ARCH_FLUX) {
++            image_model = true;
++            quantize &= name.find("txt_in.") == std::string::npos;
++            quantize &= name.find("img_in.") == std::string::npos;
++            quantize &= name.find("time_in.") == std::string::npos;
++            quantize &= name.find("vector_in.") == std::string::npos;
++            quantize &= name.find("guidance_in.") == std::string::npos;
++            quantize &= name.find("final_layer.") == std::string::npos;
++        }
++        if (model.arch == LLM_ARCH_SD1 || model.arch == LLM_ARCH_SDXL) {
++            image_model = true;
++            quantize &= name.find("class_embedding.") == std::string::npos;
++            quantize &= name.find("time_embedding.") == std::string::npos;
++            quantize &= name.find("add_embedding.") == std::string::npos;
++            quantize &= name.find("time_embed.") == std::string::npos;
++            quantize &= name.find("label_emb.") == std::string::npos;
++            quantize &= name.find("conv_in.") == std::string::npos;
++            quantize &= name.find("conv_out.") == std::string::npos;
++            quantize &= name != "input_blocks.0.0.weight";
++            quantize &= name != "out.2.weight";
++        }
++        if (model.arch == LLM_ARCH_SD3) {
++            image_model = true;
++            quantize &= name.find("final_layer.") == std::string::npos;
++            quantize &= name.find("time_text_embed.") == std::string::npos;
++            quantize &= name.find("context_embedder.") == std::string::npos;
++            quantize &= name.find("t_embedder.") == std::string::npos;
++            quantize &= name.find("y_embedder.") == std::string::npos;
++            quantize &= name.find("x_embedder.") == std::string::npos;
++            quantize &= name != "proj_out.weight";
++            quantize &= name != "pos_embed";
++        }
++        if (model.arch == LLM_ARCH_AURA) {
++            image_model = true;
++            quantize &= name.find("t_embedder.") == std::string::npos;
++            quantize &= name.find("init_x_linear.") == std::string::npos;
++            quantize &= name != "modF.1.weight";
++            quantize &= name != "cond_seq_linear.weight";
++            quantize &= name != "final_linear.weight";
++            quantize &= name != "final_linear.weight";
++            quantize &= name != "positional_encoding";
++            quantize &= name != "register_tokens";
++        }
++        if (model.arch == LLM_ARCH_LTXV) {
++            image_model = true;
++            quantize &= name.find("adaln_single.") == std::string::npos;
++            quantize &= name.find("caption_projection.") == std::string::npos;
++            quantize &= name.find("patchify_proj.") == std::string::npos;
++            quantize &= name.find("proj_out.") == std::string::npos;
++            quantize &= name.find("scale_shift_table") == std::string::npos; // last block too
++        }
++        if (model.arch == LLM_ARCH_HYVID) {
++            image_model = true;
++            quantize &= name.find("txt_in.") == std::string::npos;
++            quantize &= name.find("img_in.") == std::string::npos;
++            quantize &= name.find("time_in.") == std::string::npos;
++            quantize &= name.find("vector_in.") == std::string::npos;
++            quantize &= name.find("guidance_in.") == std::string::npos;
++            quantize &= name.find("final_layer.") == std::string::npos;
++        }
++        if (model.arch == LLM_ARCH_WAN) {
++            image_model = true;
++            quantize &= name.find("modulation.") == std::string::npos;
++            quantize &= name.find("patch_embedding.") == std::string::npos;
++            quantize &= name.find("text_embedding.") == std::string::npos;
++            quantize &= name.find("time_projection.") == std::string::npos;
++            quantize &= name.find("time_embedding.") == std::string::npos;
++            quantize &= name.find("img_emb.") == std::string::npos;
++            quantize &= name.find("head.") == std::string::npos;
++        }
++        if (model.arch == LLM_ARCH_HIDREAM) {
++            image_model = true;
++            quantize &= name.find("p_embedder.") == std::string::npos;
++            quantize &= name.find("t_embedder.") == std::string::npos;
++            quantize &= name.find("x_embedder.") == std::string::npos;
++            quantize &= name.find("final_layer.") == std::string::npos;
++            quantize &= name.find(".ff_i.gate.weight") == std::string::npos;
++            quantize &= name.find("caption_projection.") == std::string::npos;
++        }
++        if (model.arch == LLM_ARCH_COSMOS) {
++            image_model = true;
++            quantize &= name.find("p_embedder.") == std::string::npos;
++            quantize &= name.find("t_embedder.") == std::string::npos;
++            quantize &= name.find("t_embedding_norm.") == std::string::npos;
++            quantize &= name.find("x_embedder.") == std::string::npos;
++            quantize &= name.find("pos_embedder.") == std::string::npos;
++            quantize &= name.find("final_layer.") == std::string::npos;
++        }
++        if (model.arch == LLM_ARCH_LUMINA2) {
++            image_model = true;
++            quantize &= name.find("t_embedder.") == std::string::npos;
++            quantize &= name.find("x_embedder.") == std::string::npos;
++            quantize &= name.find("final_layer.") == std::string::npos;
++            quantize &= name.find("cap_embedder.") == std::string::npos;
++            quantize &= name.find("context_refiner.") == std::string::npos;
++            quantize &= name.find("noise_refiner.") == std::string::npos;
++        }
++        // ignore 3D/4D tensors for image models as the code was never meant to handle these
++        if (image_model) {
++            quantize &= ggml_n_dims(tensor) == 2;
++        }
++
+         enum ggml_type new_type;
+         void * new_data;
+         size_t new_size;
+@@ -18655,6 +18986,9 @@ static void llama_model_quantize_internal(const std::string & fname_inp, const s
+             new_type = default_type;
+ 
+             // get more optimal quantization type based on the tensor shape, layer, etc.
++            if (image_model) {
++                new_type = img_tensor_get_type(qs, new_type, tensor, ftype);
++            } else {
+             if (!params->pure && ggml_is_quantized(default_type)) {
+                 new_type = llama_tensor_get_type(qs, new_type, tensor, ftype);
+             }
+@@ -18664,6 +18998,7 @@ static void llama_model_quantize_internal(const std::string & fname_inp, const s
+             if (params->output_tensor_type < GGML_TYPE_COUNT && strcmp(tensor->name, "output.weight") == 0) {
+                 new_type = params->output_tensor_type;
+             }
++            }
+ 
+             // If we've decided to quantize to the same type the tensor is already
+             // in then there's nothing to do.

ComfyUI-GGUF/tools/read_tensors.py

@@ -0,0 +1,21 @@
+#!/usr/bin/python3
+import os
+import sys
+import gguf
+
+def read_tensors(path):
+    reader = gguf.GGUFReader(path)
+    for tensor in reader.tensors:
+        if tensor.tensor_type == gguf.GGMLQuantizationType.F32:
+            continue
+        print(f"{str(tensor.tensor_type):32}: {tensor.name}")
+
+try:
+    path = sys.argv[1]
+    assert os.path.isfile(path), "Invalid path"
+    print(f"input: {path}")
+except Exception as e:
+    input(f"failed: {e}")
+else:
+    read_tensors(path)
+    input()

ComfyUI-Jjk-Nodes/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 jjkramhoeft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ComfyUI-Jjk-Nodes/README.md

@@ -0,0 +1,4 @@
+# ComfyUI-Jjk-Nodes
+A set of custom nodes for ComfyUI - focused on text and parameter utility
+
+Minimal code to get a few nodes working 

ComfyUI-Jjk-Nodes/__init__.py

@@ -0,0 +1,27 @@
+import os
+import shutil
+
+from .jjk_util import *
+
+# A dictionary that contains all nodes you want to export with their names
+# NOTE: names should be globally unique
+NODE_CLASS_MAPPINGS = {
+    "SDXLRecommendedImageSize": SDXLRecommendedImageSize,
+    "JjkText": JjkText,
+    "JjkShowText": JjkShowText,
+    "JjkConcat": JjkConcat,
+}
+
+__all__ = ['NODE_CLASS_MAPPINGS']
+
+THIS_DIR=os.path.dirname(os.path.abspath(__file__))
+DIR_DEV_JS=os.path.abspath(f'{THIS_DIR}/js')
+DIR_PY=os.path.abspath(f'{THIS_DIR}/py')
+DIR_WEB_JS=os.path.abspath(f'{THIS_DIR}/../../web/extensions/jjk_util')
+
+if not os.path.exists(DIR_WEB_JS):
+    os.makedirs(DIR_WEB_JS)
+
+shutil.copytree(DIR_DEV_JS, DIR_WEB_JS, dirs_exist_ok=True)
+
+print("jjk_util loding")

ComfyUI-Jjk-Nodes/jjk_util.py

@@ -0,0 +1,179 @@
+import nodes
+
+"""
+
+
+    Simple utility custom nodes for ComfyUI regarding experimentation with SDXL
+    
+    By Jens Jakob Kramhøft
+
+    Copyright (c) 2023  
+
+"""
+
+MANIFEST = {
+    "name": "JJKUtil",
+    "version": (0,1,1),
+    "author": "Jens Jakob Kramhøft",
+    "project": "https://github.com/jjkramhoeft/util-nodes-for-comfyui",
+    "description": "A small node suite for ComfyUI",
+}
+
+#---------------------------------------------------------------------------------------------------------------------------------------------------#
+
+class SDXLRecommendedImageSize:
+    RESOLUTIONS = ["Cinema (1536x640)", "Widescreen (1344x768)", "Photo (1216x832)", "TV (1152x896)", "Square (1024x1024)"]
+    ASPECT = ["Landscape", "Portrait"]
+
+    @classmethod
+    def INPUT_TYPES(s):
+        return {"required": {
+                    "resolution": (SDXLRecommendedImageSize.RESOLUTIONS, {"default": "Square (1024x1024)"}),
+                    "aspect": (SDXLRecommendedImageSize.ASPECT, {"default": "Portrait"})
+                    },
+                }
+
+    RETURN_TYPES = ("INT", "INT", )
+    RETURN_NAMES = ("width", "height", )
+    FUNCTION = "get_value"
+
+    CATEGORY = "jjk"
+
+    def get_value(self, resolution, aspect, ):
+        if resolution == "Cinema (1536x640)":
+            if aspect == "Landscape":
+                return (1536, 640)
+            else:
+                return (640, 1536)
+        if resolution == "Widescreen (1344x768)":
+            if aspect == "Landscape":
+                return (1344, 768)
+            else:
+                return (768, 1344)
+        if resolution == "Photo (1216x832)":
+            if aspect == "Landscape":
+                return (1216, 832)
+            else:
+                return (832, 1216)
+        if resolution == "TV (1152x896)":
+            if aspect == "Landscape":
+                return (1152, 896)
+            else:
+                return (896, 1152)
+        if resolution == "Square (1024x1024)":
+            return (1024, 1024)
+
+#---------------------------------------------------------------------------------------------------------------------------------------------------#
+
+class JjkText:
+    @classmethod
+    def INPUT_TYPES(s):
+        return {"required": {"text": ("STRING", {"multiline": True})}}
+    
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("text",)
+    FUNCTION = "get_value"
+    CATEGORY = "jjk"
+
+    def get_value(self, text):
+        return (text,)
+
+#---------------------------------------------------------------------------------------------------------------------------------------------------#
+
+class JjkShowText:
+    @classmethod
+    def INPUT_TYPES(s):
+        return {
+            "required": {
+                "text": ("STRING", {"forceInput": True}),
+            }
+        }
+    
+    INPUT_IS_LIST = True
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("text",)
+    FUNCTION = "show_value"
+    CATEGORY = "jjk"
+    OUTPUT_NODE = True
+    OUTPUT_IS_LIST = (True,)
+
+    def show_value(self, text):
+        print(f"show text: {text}")
+        return {"ui": {"text": text}, "result": (text,)}
+
+
+#---------------------------------------------------------------------------------------------------------------------------------------------------#
+
+class JjkConcat:
+    @classmethod
+    def INPUT_TYPES(s):
+        return {
+            "required": {
+                "delimmitor": (["none", "space", "comma"],),
+            },
+            "optional": {
+                "text1": ("STRING", {"forceInput": True}),
+                "text2": ("STRING", {"forceInput": True}),      
+                "text3": ("STRING", {"forceInput": True}),      
+                "text4": ("STRING", {"forceInput": True}),      
+                "text5": ("STRING", {"forceInput": True}),       
+            }
+        }
+    
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("text",)
+    FUNCTION = "get_value"
+    CATEGORY = "jjk"
+
+    def get_value(self, delimmitor, text1=None, text2=None, text3=None, text4=None, text5=None):
+        needdelim = False
+        delim = ""
+        if delimmitor == "space":
+            delim = " "
+        if delimmitor == "comma":
+            delim = ", "
+
+        concatenated = ""
+
+        if text1:
+            concatenated = text1
+            needdelim = True
+        
+        if text2:
+            if needdelim:
+                concatenated += delim
+            concatenated += text2
+            needdelim = True
+        
+        if text3:
+            if needdelim:
+                concatenated += delim
+            concatenated += text3
+            needdelim = True
+
+        if text4:
+            if needdelim:
+                concatenated += delim
+            concatenated += text4
+            needdelim = True
+
+        if text5:
+            if needdelim:
+                concatenated += delim
+            concatenated += text5
+            needdelim = True
+
+        return (concatenated,)
+
+#---------------------------------------------------------------------------------------------------------------------------------------------------#
+
+
+
+
+# A dictionary that contains the friendly/humanly readable titles for the nodes
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "SDXLRecommendedImageSize": "SDXL Recommended image sizes",
+    "JjkText": "Text",
+    "JjkShowText": "ShowText",
+    "JjkConcat": "Concatenate",
+}

ComfyUI-Jjk-Nodes/js/jjkShowText.js

@@ -0,0 +1,36 @@
+import { app } from "../../scripts/app.js";
+import { ComfyWidgets } from "../../scripts/widgets.js";
+
+// Displays input text on a node
+
+app.registerExtension({
+	name: "jjk_util.JjkShowText",
+	async beforeRegisterNodeDef(nodeType, nodeData, app) {
+		if (nodeData.name === "JjkShowText") {
+			// When the node is executed we will be sent the input text, display this in the widget
+			const onExecuted = nodeType.prototype.onExecuted;
+			nodeType.prototype.onExecuted = function (message) {
+				onExecuted?.apply(this, arguments);
+
+				if (this.widgets) {
+					const pos = this.widgets.findIndex((w) => w.name === "text");
+					if (pos !== -1) {
+						for (let i = pos; i < this.widgets.length; i++) {
+							this.widgets[i].onRemove?.();
+						}
+						this.widgets.length = pos;
+					}
+				}
+
+				for (const list of message.text) {
+					const w = ComfyWidgets["STRING"](this, "text", ["STRING", { multiline: true }], app).widget;
+					w.inputEl.readOnly = true;
+					w.inputEl.style.opacity = 0.6;
+					w.value = list;
+				}
+
+				this.onResize?.(this.size);
+			};
+		}
+	},
+});

ComfyUI-JoyCaption/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to Comfy registry
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "pyproject.toml"
+
+permissions:
+  issues: write
+
+jobs:
+  publish-node:
+    name: Publish Custom Node to registry
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == '1038lab' }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Publish Custom Node
+        uses: Comfy-Org/publish-node-action@v1
+        with:
+          ## Add your own personal access token to your Github Repository secrets and reference it here.
+          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

ComfyUI-JoyCaption/.tracking

@@ -0,0 +1,36 @@
+.github/workflows/publish.yml
+CaptionTools.py
+JC.py
+JC_GGUF.py
+LICENSE
+README.md
+README_ZH.md
+__init__.py
+custom_models.md
+custom_models_example.json
+example_workflows/JoyCaption-GGUF.json
+example_workflows/JoyCaption-GGUF.png
+example_workflows/Joycaption_node.json
+example_workflows/Joycaption_node.png
+example_workflows/batch_image_text_output.jpg
+example_workflows/batch_image_text_output.json
+jc_data.json
+llama_cpp_install/llama_cpp_install.md
+llama_cpp_install/llama_cpp_install.py
+llama_cpp_install/llama_cpp_install_zh.md
+locales/en/main.json
+locales/en/nodeDefs.json
+locales/fr/main.json
+locales/fr/nodeDefs.json
+locales/ja/main.json
+locales/ja/nodeDefs.json
+locales/ko/main.json
+locales/ko/nodeDefs.json
+locales/ru/main.json
+locales/ru/nodeDefs.json
+locales/zh/main.json
+locales/zh/nodeDefs.json
+pyproject.toml
+requirements.txt
+requirements_gguf.txt
+update.md

ComfyUI-JoyCaption/CaptionTools.py

@@ -0,0 +1,153 @@
+import os
+from pathlib import Path
+import torch
+import numpy as np
+from PIL import Image, ImageOps
+
+class ImageBatchPath:
+    @classmethod
+    def INPUT_TYPES(s):
+        return {
+            "required": {"image_dir": ("STRING", {"default": "", "multiline": True, "placeholder": "Input directory containing images"})},
+            "optional": {
+                "batch_size": ("INT", {"default": 0, "min": 0, "step": 1, "tooltip": "Number of images to load (0 = all images)"}),
+                "start_from": ("INT", {"default": 1, "min": 1, "step": 1, "tooltip": "Start from Nth image (1 = first image)"}),
+                "sort_method": (["sequential", "reverse", "random"], {"default": "sequential", "tooltip": "Image loading order: sequential/reverse/random"})
+            }
+        }
+
+    RETURN_TYPES = ("IMAGE", "STRING")
+    RETURN_NAMES = ("IMAGE", "IMAGE_PATH")
+    OUTPUT_IS_LIST = (True, True)
+    FUNCTION = "load_image_batch"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        if 'sort_method' in kwargs and kwargs['sort_method'] == "random":
+            return float("NaN")
+        return hash(frozenset(kwargs))
+
+    def load_image_batch(self, image_dir: str, batch_size: int = 0, start_from: int = 1, sort_method: str = "sequential"):
+        if not os.path.isdir(image_dir):
+            raise FileNotFoundError(f"Directory '{image_dir}' cannot be found.")
+            
+        valid_extensions = ['.jpg', '.jpeg', '.png', '.webp']
+        image_files = [f for f in os.listdir(image_dir) if any(f.lower().endswith(ext) for ext in valid_extensions)]
+        
+        if not image_files:
+            raise FileNotFoundError(f"No valid images found in '{image_dir}'.")
+
+        if sort_method == "sequential":
+            image_files.sort()
+        elif sort_method == "reverse":
+            image_files.sort(reverse=True)
+        elif sort_method == "random":
+            import random
+            random.shuffle(image_files)
+
+        start_index = min(start_from - 1, len(image_files) - 1)
+        image_files = image_files[start_index:]
+        if batch_size > 0:
+            image_files = image_files[:batch_size]
+        
+        images = []
+        image_paths = []
+        for filename in image_files:
+            img_path = os.path.join(image_dir, filename)
+            try:
+                image = ImageOps.exif_transpose(Image.open(img_path)).convert("RGB")
+                image = torch.from_numpy(np.array(image).astype(np.float32) / 255.0)[None,]
+                images.append(image)
+                image_paths.append(img_path)
+            except Exception as e:
+                print(f'\033[91mError loading {filename}: {str(e)}\033[0m')
+                continue
+
+        return (images, image_paths)
+
+class CaptionSaver:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "string": ("STRING", {"forceInput": True}),
+                "image_path": ("STRING", {"forceInput": True}),
+            },
+            "optional": {
+                "image": ("IMAGE",),
+                "custom_output_path": ("STRING", {"default": "", "multiline": True, "placeholder": "Custom output directory path. If empty, will use the directory of image_path"}),
+                "custom_file_name": ("STRING", {"default": "", "multiline": False, "placeholder": "Custom filename (without extension)"}),
+                "overwrite": ("BOOLEAN", {"default": True, "tooltip": "if true, will overwrite the existing txt file, if false, will add a number to the filename to make it unique"})
+            }
+        }
+    
+    RETURN_TYPES = ()
+    FUNCTION = "save_caption"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+    OUTPUT_NODE = True
+
+    def get_unique_filename(self, base_path: Path) -> Path:
+        """Get a unique filename by adding numbers if file exists."""
+        if not base_path.exists():
+            return base_path
+        
+        counter = 1
+        while True:
+            new_path = base_path.parent / f"{base_path.stem}_{counter:02d}{base_path.suffix}"
+            if not new_path.exists():
+                return new_path
+            counter += 1
+
+    def save_caption(self, string, image_path, image=None, custom_output_path="", custom_file_name="", overwrite=True):
+        try:
+            image_path = Path(image_path)
+            save_dir = Path(custom_output_path.strip()) if custom_output_path.strip() else image_path.parent
+            save_dir.mkdir(parents=True, exist_ok=True)
+            
+            try:
+                base_name = custom_file_name.strip() if custom_file_name.strip() else image_path.stem
+                txt_path = save_dir / f"{base_name}.txt"
+                
+                if not overwrite and txt_path.exists():
+                    txt_path = self.get_unique_filename(txt_path)
+                    base_name = txt_path.stem
+                
+                with open(txt_path, 'w', encoding='utf-8') as f:
+                    f.write(string)
+                print(f'\033[93m[{txt_path.name}]:\033[0m {string}')
+                
+                if image is not None and custom_output_path.strip():
+                    try:
+                        if isinstance(image, torch.Tensor):
+                            while len(image.shape) > 3:
+                                image = image.squeeze(0)
+                            
+                            image = (image.cpu().numpy() * 255).astype(np.uint8)
+                            if image.shape[-1] != 3:
+                                image = np.transpose(image, (1, 2, 0))
+                            image = Image.fromarray(image)
+                        
+                        img_out_path = save_dir / f"{base_name}{image_path.suffix}"
+                        image.save(img_out_path)
+                        
+                    except Exception as e:
+                        print(f'\033[91mFailed to copy image: {str(e)}\033[0m')
+                
+            except Exception as e:
+                print(f'\033[91mError saving caption: {str(e)}\033[0m')
+            
+        except Exception as e:
+            print(f'\033[91mCritical error: {str(e)}\033[0m')
+        
+        return ()
+
+NODE_CLASS_MAPPINGS = {
+    "ImageBatchPath": ImageBatchPath,
+    "CaptionSaver": CaptionSaver
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "ImageBatchPath": "Image Batch Path 🖼️",
+    "CaptionSaver": "Caption Saver 📝"
+} 

ComfyUI-JoyCaption/JC.py

@@ -0,0 +1,443 @@
+import torch
+from transformers import AutoProcessor, LlavaForConditionalGeneration, BitsAndBytesConfig
+import folder_paths
+from pathlib import Path
+from PIL import Image
+from torchvision.transforms import ToPILImage
+import json
+import gc
+import os
+
+class ModelLoadError(Exception):
+    pass
+
+def handle_model_error(e, cleanup_func=None):
+    if cleanup_func:
+        cleanup_func()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+    gc.collect()
+    raise ModelLoadError(f"Error loading model: {str(e)}")
+
+def cleanup_model_resources(model=None, processor=None):
+    if model is not None:
+        del model
+    if processor is not None:
+        del processor
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+    gc.collect()
+
+def validate_model_parameters(quantization, valid_modes):
+    if quantization not in valid_modes:
+        raise ValueError(f"Invalid quantization mode: {quantization}. Valid modes: {', '.join(valid_modes)}")
+
+with open(Path(__file__).parent / "jc_data.json", "r", encoding="utf-8") as f:
+    config = json.load(f)
+    CAPTION_TYPE_MAP = config["caption_type_map"]
+    EXTRA_OPTIONS = config["extra_options"]
+    MEMORY_EFFICIENT_CONFIGS = config["memory_efficient_configs"]
+    MODEL_SETTINGS = config["model_settings"]
+    CAPTION_LENGTH_CHOICES = config["caption_length_choices"]
+    HF_MODELS = config["hf_models"]
+
+# --- Custom Models Merge Logic (for HF models only) ---
+custom_path = Path(__file__).parent / "custom_models.json"
+
+if custom_path.exists():
+    try:
+        with open(custom_path, "r", encoding="utf-8") as f:
+            custom_data = json.load(f) or {}
+        HF_MODELS.update(custom_data.get("hf_models", {}))
+        print("[JoyCaption] ✅ Loaded custom HF custom models.")
+    except Exception as e:
+        print(f"[JoyCaption] ⚠️ Failed to load custom models → {e}")
+else:
+    print("[JoyCaption] ℹ️ No custom models found, skipping user-defined HF models.")
+# ------------------------------------------------------
+
+def build_prompt(caption_type: str, caption_length: str | int, extra_options: list[str], name_input: str) -> str:
+    """Constructs the prompt for the model based on user selections."""
+    if caption_length == "any":
+        map_idx = 0
+    elif isinstance(caption_length, str) and caption_length.isdigit():
+        map_idx = 1
+    else:
+        map_idx = 2
+    
+    prompt = CAPTION_TYPE_MAP[caption_type][map_idx]
+
+    if extra_options:
+        prompt += " " + " ".join(extra_options)
+    
+    return prompt.format(
+        name=name_input or "{NAME}",
+        length=caption_length,
+        word_count=caption_length,
+    )
+
+_MODEL_CACHE = {}
+
+class JC_Models:
+    """Handles loading, caching, and running the LLaVA models."""
+    def __init__(self, model: str, memory_mode: str):
+        cache_key = f"{model}_{memory_mode}"
+        
+        if cache_key in _MODEL_CACHE:
+            try:
+                self.processor = _MODEL_CACHE[cache_key]["processor"]
+                self.model = _MODEL_CACHE[cache_key]["model"]
+                self.device = _MODEL_CACHE[cache_key]["device"]
+                if not next(self.model.parameters()).is_cuda:
+                    raise RuntimeError("Cached model not on GPU")
+                print(f"Using cached model: {cache_key}")
+                return
+            except Exception as e:
+                print(f"Cache validation failed: {e}, reloading model...")
+                if cache_key in _MODEL_CACHE:
+                    del _MODEL_CACHE[cache_key]
+                torch.cuda.empty_cache()
+        
+        checkpoint_path = Path(folder_paths.models_dir) / "LLM" / Path(model).stem
+        if not checkpoint_path.exists():
+            from huggingface_hub import snapshot_download
+            snapshot_download(repo_id=model, local_dir=str(checkpoint_path), force_download=False, local_files_only=False)
+        
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        if self.device == "cuda":
+            torch.backends.cudnn.benchmark = True
+            if hasattr(torch.backends, 'cuda'):
+                if hasattr(torch.backends.cuda, 'matmul'):
+                    torch.backends.cuda.matmul.allow_tf32 = True
+                if hasattr(torch.backends.cuda, 'allow_tf32'):
+                    torch.backends.cuda.allow_tf32 = True
+            
+            os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "max_split_size_mb:128"
+        
+        self.processor = AutoProcessor.from_pretrained(
+            str(checkpoint_path), 
+            use_fast=True,
+            image_processor_type="CLIPImageProcessor",
+            image_size=336
+        )
+
+        if hasattr(self.processor, 'image_processor') and hasattr(self.processor.image_processor, 'size'):
+            expected_size = self.processor.image_processor.size
+            if isinstance(expected_size, dict):
+                self.target_size = (expected_size.get('height', 336), expected_size.get('width', 336))
+            elif isinstance(expected_size, (list, tuple)):
+                self.target_size = tuple(expected_size) if len(expected_size) == 2 else (expected_size[0], expected_size[0])
+            else:
+                self.target_size = (expected_size, expected_size)
+        else:
+            self.target_size = (336, 336)
+
+        model_kwargs = {
+            "device_map": "cuda" if self.device == "cuda" else "cpu",
+        }
+
+        try:
+            if "FP8-Dynamic" in model:
+                print("Loading FP8 model with automatic configuration...")
+                self.model = LlavaForConditionalGeneration.from_pretrained(
+                    str(checkpoint_path),
+                    torch_dtype="auto",
+                    **model_kwargs
+                )
+            elif memory_mode == "Full Precision (bf16)":
+                self.model = LlavaForConditionalGeneration.from_pretrained(
+                    str(checkpoint_path), 
+                    torch_dtype=torch.bfloat16,
+                    **model_kwargs
+                )
+            elif memory_mode == "Balanced (8-bit)":
+                qnt_config = BitsAndBytesConfig(
+                    load_in_8bit=True,
+                    bnb_8bit_compute_dtype=torch.float16,
+                    bnb_8bit_use_double_quant=True,
+                    llm_int8_skip_modules=["vision_tower", "multi_modal_projector"],
+                    llm_int8_enable_fp32_cpu_offload=True
+                )
+                self.model = LlavaForConditionalGeneration.from_pretrained(
+                    str(checkpoint_path), 
+                    torch_dtype=torch.float16,
+                    quantization_config=qnt_config,
+                    **model_kwargs
+                )
+            else:
+                qnt_config = BitsAndBytesConfig(
+                    load_in_4bit=True,
+                    bnb_4bit_compute_dtype=torch.float16,
+                    bnb_4bit_quant_type="nf4",
+                    bnb_4bit_use_double_quant=True,
+                    llm_int8_skip_modules=["vision_tower", "multi_modal_projector"],
+                    llm_int8_enable_fp32_cpu_offload=True
+                )
+                self.model = LlavaForConditionalGeneration.from_pretrained(
+                    str(checkpoint_path), 
+                    torch_dtype="auto",
+                    quantization_config=qnt_config,
+                    **model_kwargs
+                )
+            
+            self.model.eval()
+            
+            if self.device == "cuda" and not next(self.model.parameters()).is_cuda:
+                raise RuntimeError("Model failed to load on GPU")
+            
+            if memory_mode == "Global Cache":
+                _MODEL_CACHE[cache_key] = {
+                    "processor": self.processor,
+                    "model": self.model,
+                    "device": self.device
+                }
+                
+        except Exception as e:
+            cleanup_model_resources(self.model, self.processor)
+            handle_model_error(e)
+    
+    @torch.inference_mode()
+    def generate(self, image: Image.Image, system: str, prompt: str, max_new_tokens: int, temperature: float, top_p: float, top_k: int) -> str:
+        """Generates a caption for the given image."""
+        convo = [
+            {"role": "system", "content": system.strip()},
+            {"role": "user", "content": prompt.strip()},
+        ]
+
+        convo_string = self.processor.apply_chat_template(convo, tokenize=False, add_generation_prompt=True)
+        assert isinstance(convo_string, str)
+
+        if image.mode != 'RGB':
+            image = image.convert('RGB')
+        
+        image = image.resize(self.target_size, Image.Resampling.LANCZOS)
+        
+        inputs = self.processor(text=[convo_string], images=[image], return_tensors="pt").to(self.device)
+        
+        if hasattr(inputs, 'pixel_values') and inputs['pixel_values'] is not None:
+            inputs['pixel_values'] = inputs['pixel_values'].to(self.model.dtype)
+
+        with torch.cuda.amp.autocast(enabled=True):
+            generate_ids = self.model.generate(
+                **inputs,
+                max_new_tokens=max_new_tokens,
+                do_sample=True if temperature > 0 else False,
+                suppress_tokens=None,
+                use_cache=True,
+                temperature=temperature,
+                top_k=None if top_k == 0 else top_k,
+                top_p=top_p,
+            )[0]
+
+        generate_ids = generate_ids[inputs['input_ids'].shape[1]:]
+        caption = self.processor.tokenizer.decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)
+        return caption.strip()
+
+class JC_ExtraOptions:
+    """A node to collect extra options for captioning."""
+    @classmethod
+    def INPUT_TYPES(cls):
+        inputs = {"required": {}}
+        for key, value in EXTRA_OPTIONS.items():
+            inputs["required"][key] = ("BOOLEAN", {"default": value["default"]})
+        inputs["required"]["character_name"] = ("STRING", {"default": "", "multiline": True, "placeholder": "Character Name"})
+        return inputs
+
+    RETURN_TYPES = ("JOYCAPTION_EXTRA_OPTIONS",)
+    RETURN_NAMES = ("extra_options",)
+    FUNCTION = "get_extra_options"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    def get_extra_options(self, character_name, **kwargs):
+        ret_list = []
+        for key, value in EXTRA_OPTIONS.items():
+            if kwargs.get(key, False):
+                ret_list.append(value["description"])
+        return ([ret_list, character_name],)
+
+class JC:
+    """The main, simple JoyCaption node."""
+    @classmethod
+    def INPUT_TYPES(cls):
+        model_list = list(HF_MODELS.keys())
+        return {
+            "required": {
+                "image": ("IMAGE",),
+                "model": (model_list, {"default": model_list[1], "tooltip": "Select the AI model to use for caption generation"}),
+                "quantization": (list(MEMORY_EFFICIENT_CONFIGS.keys()), {"default": "Balanced (8-bit)", "tooltip": "Choose between speed and quality. 8-bit is recommended for most users"}),
+                "prompt_style": (list(CAPTION_TYPE_MAP.keys()), {"default": "Descriptive", "tooltip": "Select the style of caption you want to generate"}),
+                "caption_length": (CAPTION_LENGTH_CHOICES, {"default": "any", "tooltip": "Control the length of the generated caption"}),
+                "memory_management": (["Keep in Memory", "Clear After Run", "Global Cache"], {"default": "Keep in Memory", "tooltip": "Choose how to manage model memory. 'Keep in Memory' for faster processing, 'Clear After Run' for limited VRAM, 'Global Cache' for fastest processing if you have enough VRAM"}),
+            },
+            "optional": {
+                "extra_options": ("JOYCAPTION_EXTRA_OPTIONS", {"tooltip": "Additional options to customize the caption generation"}),
+            }
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("STRING",)
+    FUNCTION = "generate"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    def __init__(self):
+        self.predictor = None
+        self.current_memory_mode = None
+        self.current_model = None
+    
+    def generate(self, image, model, quantization, prompt_style, caption_length, memory_management, extra_options=None):
+        try:
+            validate_model_parameters(quantization, list(MEMORY_EFFICIENT_CONFIGS.keys()))
+            
+            if memory_management == "Global Cache":
+                try:
+                    model_name = HF_MODELS[model]["name"]
+                    self.predictor = JC_Models(model_name, quantization)
+                except Exception as e:
+                    return (f"Error loading model: {e}",)
+            elif self.predictor is None or self.current_memory_mode != quantization or self.current_model != model:
+                if self.predictor is not None:
+                    del self.predictor
+                    self.predictor = None
+                    torch.cuda.empty_cache()
+                    gc.collect()
+                try:
+                    model_name = HF_MODELS[model]["name"]
+                    self.predictor = JC_Models(model_name, quantization)
+                    self.current_memory_mode = quantization
+                    self.current_model = model
+                except Exception as e:
+                    return (f"Error loading model: {e}",)
+
+            prompt = build_prompt(prompt_style, caption_length, extra_options[0] if extra_options else [], extra_options[1] if extra_options else "{NAME}")
+            system_prompt = MODEL_SETTINGS["default_system_prompt"]
+            pil_image = ToPILImage()(image[0].permute(2, 0, 1))
+            
+            response = self.predictor.generate(
+                image=pil_image,
+                system=system_prompt,
+                prompt=prompt,
+                max_new_tokens=MODEL_SETTINGS["default_max_tokens"],
+                temperature=MODEL_SETTINGS["default_temperature"],
+                top_p=MODEL_SETTINGS["default_top_p"],
+                top_k=MODEL_SETTINGS["default_top_k"],
+            )
+
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+
+            return (response,)
+        except Exception as e:
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+            raise e
+
+class JC_adv:
+    """The advanced JoyCaption node with more settings."""
+    @classmethod
+    def INPUT_TYPES(cls):
+        model_list = list(HF_MODELS.keys())
+        return {
+            "required": {
+                "image": ("IMAGE",),
+                "model": (model_list, {"default": model_list[1], "tooltip": "Select the AI model to use for caption generation"}),
+                "quantization": (list(MEMORY_EFFICIENT_CONFIGS.keys()), {"default": "Balanced (8-bit)", "tooltip": "Choose between speed and quality. 8-bit is recommended for most users"}),
+                "prompt_style": (list(CAPTION_TYPE_MAP.keys()), {"default": "Descriptive", "tooltip": "Select the style of caption you want to generate"}),
+                "caption_length": (CAPTION_LENGTH_CHOICES, {"default": "any", "tooltip": "Control the length of the generated caption"}),
+                "max_new_tokens": ("INT", {"default": MODEL_SETTINGS["default_max_tokens"], "min": 1, "max": 2048, "tooltip": "Maximum number of tokens to generate. Higher values allow longer captions"}),
+                "temperature": ("FLOAT", {"default": MODEL_SETTINGS["default_temperature"], "min": 0.0, "max": 2.0, "step": 0.05, "tooltip": "Control the randomness of the output. Higher values make the output more creative but less predictable"}),
+                "top_p": ("FLOAT", {"default": MODEL_SETTINGS["default_top_p"], "min": 0.0, "max": 1.0, "step": 0.01, "tooltip": "Control the diversity of the output. Higher values allow more diverse word choices"}),
+                "top_k": ("INT", {"default": MODEL_SETTINGS["default_top_k"], "min": 0, "max": 100, "tooltip": "Limit the number of possible next tokens. Lower values make the output more focused"}),
+                "custom_prompt": ("STRING", {"default": "", "multiline": True, "tooltip": "Custom prompt template. If empty, will use the selected prompt style"}),
+                "memory_management": (["Keep in Memory", "Clear After Run", "Global Cache"], {"default": "Keep in Memory", "tooltip": "Choose how to manage model memory. 'Keep in Memory' for faster processing, 'Clear After Run' for limited VRAM, 'Global Cache' for fastest processing if you have enough VRAM"}),
+            },
+            "optional": {
+                "extra_options": ("JOYCAPTION_EXTRA_OPTIONS", {"tooltip": "Additional options to customize the caption generation"}),
+            }
+        }
+
+    RETURN_TYPES = ("STRING", "STRING")
+    RETURN_NAMES = ("PROMPT", "STRING")
+    FUNCTION = "generate"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    def __init__(self):
+        self.predictor = None
+        self.current_memory_mode = None
+        self.current_model = None
+    
+    def generate(self, image, model, quantization, prompt_style, caption_length, max_new_tokens, temperature, top_p, top_k, custom_prompt, memory_management, extra_options=None):
+        try:
+            validate_model_parameters(quantization, list(MEMORY_EFFICIENT_CONFIGS.keys()))
+            
+            if memory_management == "Global Cache":
+                try:
+                    model_name = HF_MODELS[model]["name"]
+                    self.predictor = JC_Models(model_name, quantization)
+                except Exception as e:
+                    return (f"Error loading model: {e}", "")
+            elif self.predictor is None or self.current_memory_mode != quantization or self.current_model != model:
+                if self.predictor is not None:
+                    del self.predictor
+                    self.predictor = None
+                    torch.cuda.empty_cache()
+                    gc.collect()
+                try:
+                    model_name = HF_MODELS[model]["name"]
+                    self.predictor = JC_Models(model_name, quantization)
+                    self.current_memory_mode = quantization
+                    self.current_model = model
+                except Exception as e:
+                    return (f"Error loading model: {e}", "")
+
+            if custom_prompt and custom_prompt.strip():
+                prompt = custom_prompt.strip()
+            else:
+                prompt = build_prompt(prompt_style, caption_length, extra_options[0] if extra_options else [], extra_options[1] if extra_options else "{NAME}")
+            
+            system_prompt = MODEL_SETTINGS["default_system_prompt"]
+            pil_image = ToPILImage()(image[0].permute(2, 0, 1))
+            
+            response = self.predictor.generate(
+                image=pil_image,
+                system=system_prompt,
+                prompt=prompt,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature,
+                top_p=top_p,
+                top_k=top_k,
+            )
+
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+
+            return (prompt, response)
+        except Exception as e:
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+            raise e
+
+NODE_CLASS_MAPPINGS = {
+    "JC": JC,
+    "JC_adv": JC_adv,
+    "JC_ExtraOptions": JC_ExtraOptions,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "JC": "JoyCaption",
+    "JC_adv": "JoyCaption (Advanced)",
+    "JC_ExtraOptions": "JoyCaption Extra Options",
+}
+

ComfyUI-JoyCaption/JC_GGUF.py

@@ -0,0 +1,388 @@
+import torch
+import folder_paths
+from pathlib import Path
+from PIL import Image
+from torchvision.transforms import ToPILImage
+import json
+from llama_cpp import Llama
+from llama_cpp.llama_chat_format import Llava15ChatHandler
+import base64
+import io
+import sys
+import gc
+import os
+from huggingface_hub import hf_hub_download
+
+class ModelLoadError(Exception):
+    pass
+
+def suppress_output(func):
+    import sys
+    import io
+    def wrapper(*args, **kwargs):
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+        try:
+            sys.stdout = io.StringIO()
+            sys.stderr = io.StringIO()
+            return func(*args, **kwargs)
+        finally:
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+    return wrapper
+
+os.environ['TRANSFORMERS_VERBOSITY'] = 'error'
+os.environ['TOKENIZERS_PARALLELISM'] = 'false'
+
+if torch.cuda.is_available():
+    torch.backends.cudnn.benchmark = True
+    if hasattr(torch.backends, 'cuda'):
+        if hasattr(torch.backends.cuda, 'matmul'):
+            torch.backends.cuda.matmul.allow_tf32 = True
+        if hasattr(torch.backends.cuda, 'allow_tf32'):
+            torch.backends.cuda.allow_tf32 = True
+    os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "max_split_size_mb:128"
+
+with open(Path(__file__).parent / "jc_data.json", "r", encoding="utf-8") as f:
+    config = json.load(f)
+    CAPTION_TYPE_MAP = config["caption_type_map"]
+    EXTRA_OPTIONS = config["extra_options"]
+    MODEL_SETTINGS = config["model_settings"]
+    CAPTION_LENGTH_CHOICES = config["caption_length_choices"]
+    GGUF_MODELS = config["gguf_models"]
+    GGUF_SETTINGS = config["gguf_settings"]
+
+# --- Custom Models Merge Logic (for GGUF models only) ---
+custom_path = Path(__file__).parent / "custom_models.json"
+
+if custom_path.exists():
+    try:
+        with open(custom_path, "r", encoding="utf-8") as f:
+            custom_data = json.load(f) or {}
+        GGUF_MODELS.update(custom_data.get("gguf_models", {}))
+        print("[JoyCaption GGUF] ✅ Loaded custom GGUF custom models")
+    except Exception as e:
+        print(f"[JoyCaption GGUF] ⚠️ Failed to load custom models → {e}")
+else:
+    print("[JoyCaption GGUF] ℹ️ No custom models found, skipping user-defined GGUF models.")
+# -------------------------------------------------------
+
+_MODEL_CACHE = {}
+
+def build_prompt(caption_type: str, caption_length: str | int, extra_options: list[str], name_input: str) -> str:
+    if caption_length == "any":
+        map_idx = 0
+    elif isinstance(caption_length, str) and caption_length.isdigit():
+        map_idx = 1
+    else:
+        map_idx = 2
+    
+    prompt = CAPTION_TYPE_MAP[caption_type][map_idx]
+    if extra_options:
+        prompt += " " + " ".join(extra_options)
+    return prompt.format(name=name_input or "{NAME}", length=caption_length, word_count=caption_length)
+
+class JC_GGUF_Models:
+    def __init__(self, model: str, processing_mode: str):
+        try:
+            models_dir = Path(folder_paths.models_dir).resolve()
+            llm_models_dir = (models_dir / "LLM" / "GGUF").resolve()
+            llm_models_dir.mkdir(parents=True, exist_ok=True)
+            
+            model_filename = Path(model).name
+            local_path = llm_models_dir / model_filename
+            
+            if not local_path.exists():
+                if "/" not in model:
+                    raise ValueError("Invalid model path")
+                repo_path, filename = model.rsplit("/", 1)
+                local_path = Path(hf_hub_download(
+                    repo_id=repo_path,
+                    filename=filename,
+                    local_dir=str(llm_models_dir),
+                    local_dir_use_symlinks=False
+                )).resolve()
+            
+            mmproj_filename = GGUF_SETTINGS["mmproj_filename"]
+            mmproj_path = llm_models_dir / mmproj_filename
+            if not mmproj_path.exists():
+                mmproj_path = Path(hf_hub_download(
+                    repo_id="concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf",
+                    filename=mmproj_filename,
+                    local_dir=str(llm_models_dir),
+                    local_dir_use_symlinks=False
+                )).resolve()
+            
+            n_ctx = MODEL_SETTINGS["context_window"]
+            n_batch = 2048
+            n_threads = max(4, MODEL_SETTINGS["cpu_threads"])
+            if processing_mode == "Auto":
+                n_gpu_layers = -1 if torch.cuda.is_available() else 0
+            elif processing_mode == "GPU":
+                n_gpu_layers = -1
+            else:  # CPU
+                n_gpu_layers = 0
+            
+            self.model = self._initialize_model(local_path, mmproj_path, n_ctx, n_batch, n_threads, n_gpu_layers)
+            
+        except Exception as e:
+            raise ModelLoadError(f"Model initialization failed: {str(e)}")
+    
+    @suppress_output
+    def _initialize_model(self, local_path, mmproj_path, n_ctx, n_batch, n_threads, n_gpu_layers):
+        """Initialize the GGUF model with suppressed output"""
+        return Llama(
+            model_path=str(local_path),
+            n_ctx=n_ctx,
+            n_batch=n_batch,
+            n_threads=n_threads,
+            n_gpu_layers=n_gpu_layers,
+            verbose=False,
+            chat_handler=Llava15ChatHandler(clip_model_path=str(mmproj_path)),
+            offload_kqv=True,
+            numa=True
+        )
+    
+    def generate(self, image: Image.Image, system: str, prompt: str, max_new_tokens: int, temperature: float, top_p: float, top_k: int) -> str:
+        try:
+            if image.mode != 'RGB':
+                image = image.convert('RGB')
+            
+            image = image.resize(GGUF_SETTINGS["default_image_size"], Image.Resampling.BILINEAR)
+            
+            import io
+            import base64
+
+            img_buffer = io.BytesIO()
+            image.save(img_buffer, format='PNG')
+            img_buffer.seek(0)
+
+            img_base64 = base64.b64encode(img_buffer.read()).decode('utf-8')
+            data_uri = f"data:image/png;base64,{img_base64}"
+
+            messages = [
+                {"role": "system", "content": system.strip()},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt.strip()},
+                        {"type": "image_url", "image_url": {"url": data_uri}}
+                    ]
+                }
+            ]
+
+            completion_params = {
+                "messages": messages,
+                "max_tokens": max_new_tokens,
+                "temperature": temperature,
+                "top_p": top_p,
+                "stop": ["</s>", "User:", "Assistant:"],
+                "stream": False,
+                "repeat_penalty": 1.1,
+                "mirostat_mode": 0
+            }
+
+            if top_k > 0:
+                completion_params["top_k"] = top_k
+
+            response = self._create_completion(completion_params)
+            
+            del messages
+            
+            return response["choices"][0]["message"]["content"].strip()
+            
+        except Exception as e:
+            return f"Generation error: {str(e)}"
+        finally:
+            gc.collect()
+    
+    @suppress_output
+    def _create_completion(self, completion_params):
+        """Create chat completion with suppressed output"""
+        return self.model.create_chat_completion(**completion_params)
+
+class JC_GGUF:
+    @classmethod
+    def INPUT_TYPES(cls):
+        model_list = list(GGUF_MODELS.keys())
+        return {
+            "required": {
+                "image": ("IMAGE",),
+                "model": (model_list, {"default": model_list[0], "tooltip": "Select the GGUF model to use for caption generation"}),
+                "processing_mode": (["Auto", "GPU", "CPU"], {"default": "Auto", "tooltip": "Auto: Automatically detect best mode\nGPU: Faster but requires more VRAM\nCPU: Slower but saves VRAM"}),
+                "prompt_style": (list(CAPTION_TYPE_MAP.keys()), {"default": "Descriptive", "tooltip": "Select the style of caption you want to generate"}),
+                "caption_length": (CAPTION_LENGTH_CHOICES, {"default": "any", "tooltip": "Control the length of the generated caption"}),
+                "memory_management": (["Keep in Memory", "Clear After Run", "Global Cache"], {"default": "Keep in Memory", "tooltip": "Choose how to manage model memory. 'Keep in Memory' for faster processing, 'Clear After Run' for limited VRAM, 'Global Cache' for fastest processing if you have enough VRAM"}),
+            },
+            "optional": {
+                "extra_options": ("JOYCAPTION_EXTRA_OPTIONS", {"tooltip": "Additional options to customize the caption generation"}),
+            }
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("STRING",)
+    FUNCTION = "generate"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    def __init__(self):
+        self.predictor = None
+        self.current_processing_mode = None
+        self.current_model = None
+    
+    def generate(self, image, model, processing_mode, prompt_style, caption_length, memory_management, extra_options=None):
+        try:
+            print(f"JoyCaption GGUF: Processing image with {model} ({processing_mode} mode)")
+            cache_key = f"{model}_{processing_mode}"
+            
+            if memory_management == "Global Cache":
+                try:
+                    if cache_key in _MODEL_CACHE:
+                        self.predictor = _MODEL_CACHE[cache_key]
+                    else:
+                        model_name = GGUF_MODELS[model]["name"]
+                        self.predictor = JC_GGUF_Models(model_name, processing_mode)
+                        _MODEL_CACHE[cache_key] = self.predictor
+                except Exception as e:
+                    return (f"Error loading model: {e}",)
+            elif self.predictor is None or self.current_processing_mode != processing_mode or self.current_model != model:
+                if self.predictor is not None:
+                    del self.predictor
+                    self.predictor = None
+                    torch.cuda.empty_cache()
+                try:
+                    model_name = GGUF_MODELS[model]["name"]
+                    self.predictor = JC_GGUF_Models(model_name, processing_mode)
+                    self.current_processing_mode = processing_mode
+                    self.current_model = model
+                except Exception as e:
+                    return (f"Error loading model: {e}",)
+
+            prompt_text = build_prompt(prompt_style, caption_length, extra_options[0] if extra_options else [], extra_options[1] if extra_options else "{NAME}")
+
+            print("JoyCaption GGUF: Generating caption...")
+            with torch.inference_mode():
+                pil_image = ToPILImage()(image[0].permute(2, 0, 1))
+                response = self.predictor.generate(
+                    image=pil_image,
+                    system=MODEL_SETTINGS["default_system_prompt"],
+                    prompt=prompt_text,
+                    max_new_tokens=MODEL_SETTINGS["default_max_tokens"],
+                    temperature=MODEL_SETTINGS["default_temperature"],
+                    top_p=MODEL_SETTINGS["default_top_p"],
+                    top_k=MODEL_SETTINGS["default_top_k"],
+                )
+            print("JoyCaption GGUF: Caption generation completed")
+
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+
+            return (response,)
+        except Exception as e:
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+            raise e
+
+class JC_GGUF_adv:
+    @classmethod
+    def INPUT_TYPES(cls):
+        model_list = list(GGUF_MODELS.keys())
+        return {
+            "required": {
+                "image": ("IMAGE",),
+                "model": (model_list, {"default": model_list[0], "tooltip": "Select the GGUF model to use for caption generation"}),
+                "processing_mode": (["Auto", "GPU", "CPU"], {"default": "Auto", "tooltip": "Auto: Automatically detect best mode\nGPU: Faster but requires more VRAM\nCPU: Slower but saves VRAM"}),
+                "prompt_style": (list(CAPTION_TYPE_MAP.keys()), {"default": "Descriptive", "tooltip": "Select the style of caption you want to generate"}),
+                "caption_length": (CAPTION_LENGTH_CHOICES, {"default": "any", "tooltip": "Control the length of the generated caption"}),
+                "max_new_tokens": ("INT", {"default": MODEL_SETTINGS["default_max_tokens"], "min": 1, "max": 2048, "tooltip": "Maximum number of tokens to generate. Higher values allow longer captions"}),
+                "temperature": ("FLOAT", {"default": MODEL_SETTINGS["default_temperature"], "min": 0.0, "max": 2.0, "step": 0.05, "tooltip": "Control the randomness of the output. Higher values make the output more creative but less predictable"}),
+                "top_p": ("FLOAT", {"default": MODEL_SETTINGS["default_top_p"], "min": 0.0, "max": 1.0, "step": 0.01, "tooltip": "Control the diversity of the output. Higher values allow more diverse word choices"}),
+                "top_k": ("INT", {"default": MODEL_SETTINGS["default_top_k"], "min": 0, "max": 100, "tooltip": "Limit the number of possible next tokens. Lower values make the output more focused"}),
+                "custom_prompt": ("STRING", {"default": "", "multiline": True, "tooltip": "Custom prompt template. If empty, will use the selected prompt style"}),
+                "memory_management": (["Keep in Memory", "Clear After Run", "Global Cache"], {"default": "Keep in Memory", "tooltip": "Choose how to manage model memory. 'Keep in Memory' for faster processing, 'Clear After Run' for limited VRAM, 'Global Cache' for fastest processing if you have enough VRAM"}),
+            },
+            "optional": {
+                "extra_options": ("JOYCAPTION_EXTRA_OPTIONS", {"tooltip": "Additional options to customize the caption generation"}),
+            }
+        }
+
+    RETURN_TYPES = ("STRING", "STRING")
+    RETURN_NAMES = ("PROMPT", "STRING")
+    FUNCTION = "generate"
+    CATEGORY = "🧪AILab/📝JoyCaption"
+
+    def __init__(self):
+        self.predictor = None
+        self.current_processing_mode = None
+        self.current_model = None
+    
+    def generate(self, image, model, processing_mode, prompt_style, caption_length, max_new_tokens, temperature, top_p, top_k, custom_prompt, memory_management, extra_options=None):
+        try:
+            cache_key = f"{model}_{processing_mode}"
+            
+            if memory_management == "Global Cache":
+                try:
+                    if cache_key in _MODEL_CACHE:
+                        self.predictor = _MODEL_CACHE[cache_key]
+                    else:
+                        model_name = GGUF_MODELS[model]["name"]
+                        self.predictor = JC_GGUF_Models(model_name, processing_mode)
+                        _MODEL_CACHE[cache_key] = self.predictor
+                except Exception as e:
+                    return ("", f"Error loading model: {e}")
+            elif self.predictor is None or self.current_processing_mode != processing_mode or self.current_model != model:
+                if self.predictor is not None:
+                    del self.predictor
+                    self.predictor = None
+                    torch.cuda.empty_cache()
+                try:
+                    model_name = GGUF_MODELS[model]["name"]
+                    self.predictor = JC_GGUF_Models(model_name, processing_mode)
+                    self.current_processing_mode = processing_mode
+                    self.current_model = model
+                except Exception as e:
+                    return ("", f"Error loading model: {e}")
+
+            prompt = custom_prompt if custom_prompt.strip() else build_prompt(prompt_style, caption_length, extra_options[0] if extra_options else [], extra_options[1] if extra_options else "{NAME}")
+            system_prompt = MODEL_SETTINGS["default_system_prompt"]
+            
+            pil_image = ToPILImage()(image[0].permute(2, 0, 1))
+            response = self.predictor.generate(
+                image=pil_image,
+                system=system_prompt,
+                prompt=prompt,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature,
+                top_p=top_p,
+                top_k=top_k,
+            )
+
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+
+            return (prompt, response)
+        except Exception as e:
+            if memory_management == "Clear After Run":
+                del self.predictor
+                self.predictor = None
+                torch.cuda.empty_cache()
+                gc.collect()
+            return ("", f"Error: {str(e)}")
+
+NODE_CLASS_MAPPINGS = {
+    "JC_GGUF": JC_GGUF,
+    "JC_GGUF_adv": JC_GGUF_adv,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "JC_GGUF": "JoyCaption GGUF",
+    "JC_GGUF_adv": "JoyCaption GGUF (Advanced)",
+}

ComfyUI-JoyCaption/LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

ComfyUI-JoyCaption/README.md

@@ -0,0 +1,334 @@
+# ComfyUI-JoyCaption
+
+Joy Caption is a ComfyUI custom node powered by the LLaVA model for efficient, stylized image captioning. Caption Tools nodes handle batch image processing and automatic separation of caption text.
+
+![Joycaption_node](example_workflows/Joycaption_node.png)
+
+## News & Updates
+- **2025/10/27**: Added Custom Models **v2.0.2**  ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v202-2025-10-27) )
+- **2025/10/20**: Update and bug fix ComfyUI-JoyCaption to **v2.0.1**  ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v201-2025-10-20) )
+- **2025/08/22**: Update ComfyUI-JoyCaption to **v2.0.0** ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v200-2025-08-22) )
+ ![Joycaption GGUF](example_workflows/JoyCaption-GGUF.png)
+  - Added GGUF model support for better performance and compatibility
+  - Fixed critical parameter handling issues (top_k, image format)
+  - Improved console output (no more base64 spam)
+  - Enhanced error handling and stability
+  - Added JoyCaption GGUF and JoyCaption GGUF (Advanced) nodes
+  - **Enhanced GGUF Support**: Comprehensive support for 12 quantization levels (Q2_K to F16)
+  - **llama_cpp_install folder**: [Complete installation guides](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/llama_cpp_install/llama_cpp_install.md) and automated scripts for llama-cpp-python
+  - **Simplified Installation**: [One-click llama-cpp-python installation](https://github.com/1038lab/ComfyUI-JoyCaption/tree/main/llama_cpp_install) with automatic CUDA support
+  - **Cross-Platform Support**: Windows, macOS, and Linux installation guides
+  - **Performance Improvements**: Optimized model loading and memory management
+
+- **2025/06/15**: Update ComfyUI-JoyCaption to **v1.2.0** ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v120-20250615) )
+  - Enhanced CUDA performance optimization
+  - Improved memory management strategies
+  - Added Global Cache mode for faster processing
+
+![v1 2 0](https://github.com/user-attachments/assets/bcb6cadd-1294-4fd0-a5b4-fe8cd3784801)
+
+- **2025/06/07**: Update ComfyUI-JoyCaption to **v1.1.1** ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v111-20250607) )
+
+- **2025/06/05**: Update ComfyUI-JoyCaption to **v1.1.0** ( [update.md](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/update.md#v110-20250605) )
+- Add Caption tools
+
+[![Joycaption_node](example_workflows/batch_image_text_output.jpg)](https://github.com/1038lab/ComfyUI-JoyCaption/blob/main/example_workflows/batch_image_text_output.json)
+
+## Features
+
+- Simple and user-friendly interface
+- Multiple caption types support
+- Flexible length control
+- Memory optimization options
+- **GGUF model support** - Efficient quantized models for better performance and lower memory usage
+- **Automatic model download** - Models will be downloaded automatically and properly renamed on first use
+- Support for multiple caption types
+- Support for advanced customization options
+- Multiple precision options (fp32, bf16, fp16, 8-bit, 4-bit)
+- Enhanced memory management with Global Cache mode
+- Clean console output (no debug spam)
+- Robust error handling and parameter validation
+- **llama_cpp_install folder** - Complete installation guides and automated scripts for llama-cpp-python
+
+## Installation
+
+1. Clone this repository to your `ComfyUI/custom_nodes` directory:
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/1038lab/ComfyUI-JoyCaption.git
+```
+
+2. Install the required dependencies:
+```bash
+cd ComfyUI/custom_nodes/ComfyUI-JoyCaption
+pip install -r requirements.txt
+```
+
+3. **For GGUF Models (Recommended)**: Install llama-cpp-python with CUDA support:
+```bash
+# Option 1: Automated installation (Recommended)
+python llama_cpp_install/llama_cpp_install.py
+
+# Option 2: Manual installation
+pip install -r requirements_gguf.txt
+```
+
+**Installation Guides Available:**
+- **English**: [llama_cpp_install/llama_cpp_install.md](llama_cpp_install/llama_cpp_install.md)
+- **中文**: [llama_cpp_install/llama_cpp_install_zh.md](llama_cpp_install/llama_cpp_install_zh.md)
+
+## Download Models
+The models will be automatically downloaded and renamed on first use, or you can manually download them:
+
+### Standard Models (HuggingFace Format)
+| Model | Link | Memory Usage |
+| ----- | ---- | ------------ |
+| JoyCaption Beta One | [Download](https://huggingface.co/fancyfeast/llama-joycaption-beta-one-hf-llava) | ~8-16GB |
+| JoyCaption Alpha Two | [Download](https://huggingface.co/fancyfeast/llama-joycaption-alpha-two-hf-llava) | ~8-16GB |
+
+### GGUF Models (Quantized, Recommended)
+| Model | Size | Memory Usage | Quality | Recommended For | Link |
+| ----- | ---- | ------------ | ------- | --------------- | ---- |
+| JoyCaption Beta One (Q2_K) | 3.18GB | ~4GB | Good | Low VRAM (6GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q2_K.gguf) |
+| JoyCaption Beta One (Q3_K_S) | 3.66GB | ~5GB | Good+ | Budget systems (8GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_S.gguf) |
+| JoyCaption Beta One (Q3_K_M) | 4.02GB | ~5GB | Better | Balanced performance | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_M.gguf) |
+| JoyCaption Beta One (Q3_K_L) | 4.32GB | ~6GB | Better+ | Good quality/size ratio | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_L.gguf) |
+| JoyCaption Beta One (IQ4_XS) | 4.48GB | ~6GB | Very Good | **Recommended** (8GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.IQ4_XS.gguf) |
+| JoyCaption Beta One (Q4_K_S) | 4.69GB | ~6GB | Very Good | Quality focused | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q4_K_S.gguf) |
+| JoyCaption Beta One (Q4_K_M) | 4.92GB | ~7GB | Very Good+ | Balanced choice | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q4_K_M.gguf) |
+| JoyCaption Beta One (Q5_K_S) | 5.60GB | ~7GB | Excellent | High quality (10GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q5_K_S.gguf) |
+| JoyCaption Beta One (Q5_K_M) | 5.73GB | ~8GB | Excellent+ | Premium quality | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q5_K_M.gguf) |
+| JoyCaption Beta One (Q6_K) | 6.60GB | ~8GB | Near Original | Maximum quality (12GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q6_K.gguf) |
+| JoyCaption Beta One (Q8_0) | 8.54GB | ~10GB | Original- | Full precision alternative | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q8_0.gguf) |
+| JoyCaption Beta One (F16) | 16.1GB | ~18GB | Original | Full precision (24GB+) | [Download](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.f16.gguf) |
+
+#### Alternative GGUF Sources
+| Model | Size | Source | Link |
+| ----- | ---- | ------ | ---- |
+| JoyCaption Beta One (Q4_K) | 4.92GB | concedo | [Download](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-Q4_K.gguf) |
+| JoyCaption Beta One (Q8_0) | 8.54GB | concedo | [Download](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-Q8_0.gguf) |
+| JoyCaption Beta One (F16) | 16.1GB | concedo | [Download](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-F16.gguf) |
+
+**Note**: GGUF models also require the vision projection model:
+- [llama-joycaption-beta-one-llava-mmproj-model-f16.gguf](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/llama-joycaption-beta-one-llava-mmproj-model-f16.gguf)
+
+After downloading, place the model files in your `ComfyUI/models/LLM/GGUF` directory.
+
+## Basic Usage
+
+### Standard Nodes (HuggingFace Models)
+
+#### Basic Node
+1. Add the "JoyCaption" node from the `🧪AILab/📝JoyCaption` category
+2. Connect an image source to the node
+3. Select the model file (defaults to `llama-joycaption-beta-one-hf-llava`)
+4. Adjust the parameters as needed
+5. Run the workflow
+
+#### Advanced Node
+1. Add the "JoyCaption (Advanced)" node from the `🧪AILab/📝JoyCaption` category
+2. Connect an image source to the node
+3. Select the caption type
+4. Adjust the parameters as needed
+5. Run the workflow
+
+### GGUF Nodes (Recommended for Better Performance)
+
+#### GGUF Basic Node
+1. Add the "JoyCaption GGUF" node from the `🧪AILab/📝JoyCaption-GGUF` category
+2. Connect an image source to the node
+3. Select the GGUF model (e.g., "JoyCaption Beta One (IQ4_XS)")
+4. Choose processing mode (GPU/CPU)
+5. Select caption style and length
+6. Run the workflow
+
+#### GGUF Advanced Node
+1. Add the "JoyCaption GGUF (Advanced)" node from the `🧪AILab/📝JoyCaption-GGUF` category
+2. Connect an image source to the node
+3. Configure all generation parameters (temperature, top_p, top_k, etc.)
+4. Set custom prompts if needed
+5. Run the workflow
+
+## Caption Tools
+
+### Image Batch Path 🖼️
+
+This node allows you to load multiple images from a directory for batch processing:
+
+| Parameter | Description |
+| --------- | ----------- |
+| **image_dir** | Directory path containing images |
+| **batch_size** | Number of images to load (0 = all images) |
+| **start_from** | Start from Nth image (1 = first image) |
+| **sort_method** | Image loading order: sequential/reverse/random |
+
+### Caption Saver 📝
+
+This node saves generated captions to text files:
+
+| Parameter | Description |
+| --------- | ----------- |
+| **string** | Caption text to save |
+| **image_path** | Path to the image being captioned |
+| **image** | (Optional) Image to save alongside the caption |
+| **custom_output_path** | (Optional) Custom output directory path |
+| **custom_file_name** | (Optional) Custom filename (without extension) |
+| **overwrite** | If true, will overwrite existing files; if false, will add a number to make the filename unique |
+
+### Parameters
+
+#### Standard Nodes
+
+##### Basic Node
+| Parameter | Description | Default | Range |
+| --------- | ----------- | ------- | ----- |
+| **Model** | The JoyCaption model to use | `llama-joycaption-beta-one-hf-llava` | - |
+| **Memory Control** | Memory optimization settings | Default | Default (fp32), Balanced (8-bit), Maximum Savings (4-bit) |
+| **Caption Type** | Caption style selection | Descriptive | Descriptive, Descriptive (Casual), Straightforward, Tags, Technical, Artistic |
+| **Caption Length** | Output length control | medium | any, very short, short, medium, long, very long |
+
+#### GGUF Nodes
+
+##### GGUF Basic Node
+| Parameter | Description | Default | Range |
+| --------- | ----------- | ------- | ----- |
+| **Model** | GGUF model to use | JoyCaption Beta One (IQ4_XS) | Q2_K, IQ4_XS, Q5_K_M, Q6_K |
+| **Processing Mode** | Hardware acceleration | GPU | GPU, CPU |
+| **Caption Type** | Caption style selection | Descriptive | Descriptive, Descriptive (Casual), Straightforward, Tags, Technical, Artistic |
+| **Caption Length** | Output length control | any | any, very short, short, medium, long, very long |
+| **Memory Management** | Model memory handling | Keep in Memory | Keep in Memory, Clear After Run, Global Cache |
+
+##### GGUF Advanced Node
+| Parameter | Description | Default | Range |
+| --------- | ----------- | ------- | ----- |
+| **Model** | GGUF model to use | JoyCaption Beta One (IQ4_XS) | Q2_K, IQ4_XS, Q5_K_M, Q6_K |
+| **Processing Mode** | Hardware acceleration | GPU | GPU, CPU |
+| **Max New Tokens** | Maximum tokens to generate | 512 | 1-2048 |
+| **Temperature** | Generation randomness | 0.6 | 0.0-2.0 |
+| **Top-p** | Nucleus sampling | 0.9 | 0.0-1.0 |
+| **Top-k** | Top-k sampling | 0 | 0-100 |
+| **Custom Prompt** | Custom prompt template | "" | Any text |
+| **Memory Management** | Model memory handling | Keep in Memory | Keep in Memory, Clear After Run, Global Cache |
+
+
+### Quantization Options
+
+#### Standard Models (HuggingFace)
+| Mode | Precision | Memory Usage | Speed | Quality | Recommended GPU |
+|------|-----------|--------------|-------|---------|----------------|
+| Default | fp32 | ~16GB | 1x | Best | 24GB+ |
+| Default | bf16 | ~8GB | 1.5x | Excellent | 16GB+ |
+| Default | fp16 | ~8GB | 2x | Very Good | 16GB+ |
+| Balanced | 8-bit | ~4GB | 2.5x | Good | 12GB+ |
+| Maximum Savings | 4-bit | ~2GB | 3x | Acceptable | 8GB+ |
+
+#### GGUF Models (Recommended)
+| Quantization | Model Size | Memory Usage | Speed | Quality | Recommended GPU |
+|-------------|------------|--------------|-------|---------|----------------|
+| Q2_K | 3.18GB | ~4GB | 4x | Good | 6GB+ |
+| Q3_K_S | 3.66GB | ~5GB | 3.5x | Good+ | 8GB+ |
+| Q3_K_M | 4.02GB | ~5GB | 3.5x | Better | 8GB+ |
+| Q3_K_L | 4.32GB | ~6GB | 3x | Better+ | 8GB+ |
+| IQ4_XS | 4.48GB | ~6GB | 3x | Very Good | 8GB+ |
+| Q4_K_S | 4.69GB | ~6GB | 3x | Very Good | 8GB+ |
+| Q4_K_M | 4.92GB | ~7GB | 2.5x | Very Good+ | 10GB+ |
+| Q5_K_S | 5.60GB | ~7GB | 2.5x | Excellent | 10GB+ |
+| Q5_K_M | 5.73GB | ~8GB | 2.5x | Excellent+ | 12GB+ |
+| Q6_K | 6.60GB | ~8GB | 2x | Near Original | 12GB+ |
+| Q8_0 | 8.54GB | ~10GB | 1.8x | Original- | 16GB+ |
+| F16 | 16.1GB | ~18GB | 1.5x | Original | 24GB+ |
+
+**Note**: GGUF models provide better performance and lower memory usage compared to standard models. IQ4_XS offers the best balance of quality and efficiency.
+
+#### Advanced Node
+
+| Parameter | Description | Default | Range |
+| --------- | ----------- | ------- | ----- |
+| **Extra Options** | Additional feature options | [] | Multiple options |
+| **Person Name** | Name for person descriptions | "" | Any text |
+| **Max New Tokens** | Maximum tokens to generate | 512 | 1-2048 |
+| **Temperature** | Generation temperature | 0.6 | 0.0-2.0 |
+| **Top-p** | Sampling parameter | 0.9 | 0.0-1.0 |
+| **Top-k** | Top-k sampling | 0 | 0-100 |
+| **Precision** | Use fp32 for best quality, bf16 for balanced performance, fp16 for maximum speed. 8-bit and 4-bit quantization provide significant memory savings with minimal quality impact |
+
+### Memory Management Options
+
+| Mode | Description | Recommended Use |
+|------|-------------|-----------------|
+| Global Cache | Keeps model in memory for fastest processing | High VRAM GPUs (16GB+) |
+| Keep in Memory | Maintains model in memory until workflow ends | Medium VRAM GPUs (8GB+) |
+| Clear After Run | Clears model after each generation | Low VRAM GPUs (<8GB) |
+
+## Setting Tips
+
+| Setting | Recommendation |
+| ------- | -------------- |
+| **Model Choice** | Use GGUF models for better performance and lower memory usage. IQ4_XS offers the best balance of quality and efficiency |
+| **Memory Mode** | Based on GPU VRAM: 24GB+ use Global Cache, 12GB+ use Keep in Memory, 8GB+ use Clear After Run |
+| **Processing Mode** | Use GPU mode for faster processing, CPU mode for systems with limited VRAM |
+| **Input Resolution** | The model works best with images of 512x512 or higher resolution |
+| **Memory Usage** | If you encounter memory issues, try GGUF Q2_K model or use Clear After Run mode |
+| **Performance** | For batch processing, consider using Global Cache mode with GGUF models if you have sufficient VRAM |
+| **Temperature** | Lower values (0.6-0.7) for more stable results, higher values (0.8-1.0) for more diverse results |
+| **Top-k Parameter** | Set to 0 to disable, or use values like 40-50 for more focused generation |
+
+## About Model
+
+This implementation uses LLaVA-based image captioning models, optimized to provide fast and accurate image descriptions.
+
+Model features:
+* Free and open weights
+* Uncensored content coverage
+* Broad style diversity (digital art, photoreal, anime, etc.)
+* Fast processing with bfloat16 precision
+* High-quality caption generation
+* Memory-efficient operation
+* Consistent results across various image types
+* Support for multiple caption styles
+* Optimized for training diffusion models
+
+The models are trained on diverse datasets, ensuring:
+* Balanced representation across different image types
+* High accuracy in various scenarios
+* Robust performance with complex scenes
+* Support for both SFW and NSFW content
+* Equal coverage of different styles and concepts
+
+## Roadmap
+
+### ✅ Completed (v1.3.0)
+* ✅ GGUF model support for better performance
+* ✅ Support for 12 GGUF quantization formats (Q2_K to F16)
+* ✅ Enhanced error handling and parameter validation
+* ✅ Clean console output (no debug spam)
+* ✅ Improved memory management options
+* ✅ Batch processing support (Caption Tools)
+* ✅ Performance optimizations for CPU processing (GGUF CPU mode)
+* ✅ Enhanced batch processing features with memory management
+
+### 🔄 Future Plans
+* More caption style options and custom prompts
+* Advanced fine-tuning support for custom models
+* Real-time processing optimizations
+* Multi-language caption support
+* Integration with more vision-language models
+
+## Credits
+
+* **Original JoyCaption Model**: [fancyfeast](https://huggingface.co/fancyfeast) - Creator of the base JoyCaption models
+* **GGUF Quantized Models**: [mradermacher](https://huggingface.co/mradermacher) - Provider of comprehensive GGUF quantized models (Q2_K to F16)
+* **Alternative GGUF Models**: [concedo](https://huggingface.co/concedo) - Provider of alternative GGUF models with vision projection
+* **ComfyUI Integration**: [1038lab](https://github.com/1038lab) - Developer of this ComfyUI custom node
+* **LLaVA Framework**: Microsoft Research - Base vision-language model architecture
+* **llama-cpp-python**: [abetlen](https://github.com/abetlen/llama-cpp-python) - Python bindings for llama.cpp
+
+## License
+
+
+This repository's code is released under the GPL-3.0 License.
+
+
+
+
+

ComfyUI-JoyCaption/README_ZH.md

@@ -0,0 +1,300 @@
+# ComfyUI-JoyCaption
+
+[English](README.md) | [简体中文](README_ZH.md)
+
+ComfyUI 自定义节点，基于 LLaVA VLM 提供高级图像描述功能，支持自定义风格和内存优化推理。
+
+## 功能特点
+
+- 简单友好的用户界面
+- 支持多种描述类型
+- 灵活的长度控制
+- 内存优化选项
+- **GGUF 模型支持** - 高效的量化模型，提供更好的性能和更低的内存使用
+- **自动模型下载** - 首次使用时自动下载并正确重命名模型
+- 支持多种描述类型
+- 支持高级自定义选项
+- 多种精度选项 (fp32, bf16, fp16, 8-bit, 4-bit)
+- 增强的内存管理，支持全局缓存模式
+- 干净的控制台输出（无调试垃圾信息）
+- 强大的错误处理和参数验证
+- **llama_cpp_install文件夹** - 完整的llama-cpp-python安装指南和自动化脚本
+
+## 安装
+
+1. 将此仓库克隆到您的 `ComfyUI/custom_nodes` 目录：
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/1038lab/ComfyUI-JoyCaption.git
+```
+
+2. 安装所需依赖：
+```bash
+cd ComfyUI/custom_nodes/ComfyUI-JoyCaption
+pip install -r requirements.txt
+```
+
+3. **GGUF模型（推荐）**: 安装支持CUDA的llama-cpp-python：
+```bash
+# 选项1: 自动化安装（推荐）
+python llama_cpp_install/llama_cpp_install.py
+
+# 选项2: 手动安装
+pip install -r requirements_gguf.txt
+```
+
+**可用安装指南:**
+- **English**: [llama_cpp_install/llama_cpp_install.md](llama_cpp_install/llama_cpp_install.md)
+- **中文**: [llama_cpp_install/llama_cpp_install_zh.md](llama_cpp_install/llama_cpp_install_zh.md)
+
+## 下载模型
+模型将在首次使用时自动下载并重命名，或者您可以手动下载：
+
+### 标准模型（HuggingFace 格式）
+| 模型 | 链接 | 内存使用 |
+| ----- | ---- | ------------ |
+| JoyCaption Beta One | [下载](https://huggingface.co/fancyfeast/llama-joycaption-beta-one-hf-llava) | ~8-16GB |
+| JoyCaption Alpha Two | [下载](https://huggingface.co/fancyfeast/llama-joycaption-alpha-two-hf-llava) | ~8-16GB |
+
+### GGUF 模型（量化，推荐）
+| 模型 | 大小 | 内存使用 | 质量 | 推荐用途 | 链接 |
+| ----- | ---- | ------------ | ------- | --------------- | ---- |
+| JoyCaption Beta One (Q2_K) | 3.18GB | ~4GB | 良好 | 低显存 (6GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q2_K.gguf) |
+| JoyCaption Beta One (Q3_K_S) | 3.66GB | ~5GB | 良好+ | 预算系统 (8GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_S.gguf) |
+| JoyCaption Beta One (Q3_K_M) | 4.02GB | ~5GB | 更好 | 平衡性能 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_M.gguf) |
+| JoyCaption Beta One (Q3_K_L) | 4.32GB | ~6GB | 更好+ | 质量/大小平衡 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q3_K_L.gguf) |
+| JoyCaption Beta One (IQ4_XS) | 4.48GB | ~6GB | 很好 | **推荐** (8GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.IQ4_XS.gguf) |
+| JoyCaption Beta One (Q4_K_S) | 4.69GB | ~6GB | 很好 | 质量导向 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q4_K_S.gguf) |
+| JoyCaption Beta One (Q4_K_M) | 4.92GB | ~7GB | 很好+ | 平衡选择 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q4_K_M.gguf) |
+| JoyCaption Beta One (Q5_K_S) | 5.60GB | ~7GB | 优秀 | 高质量 (10GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q5_K_S.gguf) |
+| JoyCaption Beta One (Q5_K_M) | 5.73GB | ~8GB | 优秀+ | 高端质量 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q5_K_M.gguf) |
+| JoyCaption Beta One (Q6_K) | 6.60GB | ~8GB | 接近原版 | 最高质量 (12GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q6_K.gguf) |
+| JoyCaption Beta One (Q8_0) | 8.54GB | ~10GB | 原版- | 全精度替代 | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.Q8_0.gguf) |
+| JoyCaption Beta One (F16) | 16.1GB | ~18GB | 原版 | 全精度 (24GB+) | [下载](https://huggingface.co/mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/resolve/main/llama-joycaption-beta-one-hf-llava.f16.gguf) |
+
+#### 备选 GGUF 源
+| 模型 | 大小 | 来源 | 链接 |
+| ----- | ---- | ------ | ---- |
+| JoyCaption Beta One (Q4_K) | 4.92GB | concedo | [下载](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-Q4_K.gguf) |
+| JoyCaption Beta One (Q8_0) | 8.54GB | concedo | [下载](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-Q8_0.gguf) |
+| JoyCaption Beta One (F16) | 16.1GB | concedo | [下载](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/Llama-Joycaption-Beta-One-Hf-Llava-F16.gguf) |
+
+**注意**：GGUF 模型还需要视觉投影模型：
+- [llama-joycaption-beta-one-llava-mmproj-model-f16.gguf](https://huggingface.co/concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/resolve/main/llama-joycaption-beta-one-llava-mmproj-model-f16.gguf)
+
+下载后，将模型文件放置在 `ComfyUI/models/LLM/GGUF` 目录中。
+
+## 基本使用
+
+### 标准节点（HuggingFace 模型）
+
+#### 基础节点
+1. 从 `🧪AILab/📝JoyCaption` 类别添加 "JoyCaption" 节点
+2. 将图像源连接到节点
+3. 选择模型文件（默认为 `llama-joycaption-beta-one-hf-llava`）
+4. 根据需要调整参数
+5. 运行工作流
+
+#### 高级节点
+1. 从 `🧪AILab/📝JoyCaption` 类别添加 "JoyCaption (Advanced)" 节点
+2. 将图像源连接到节点
+3. 选择描述类型
+4. 根据需要调整参数
+5. 运行工作流
+
+### GGUF 节点（推荐，性能更佳）
+
+#### GGUF 基础节点
+1. 从 `🧪AILab/📝JoyCaption-GGUF` 类别添加 "JoyCaption GGUF" 节点
+2. 将图像源连接到节点
+3. 选择 GGUF 模型（例如 "JoyCaption Beta One (IQ4_XS)"）
+4. 选择处理模式（GPU/CPU）
+5. 选择描述风格和长度
+6. 运行工作流
+
+#### GGUF 高级节点
+1. 从 `🧪AILab/📝JoyCaption-GGUF` 类别添加 "JoyCaption GGUF (Advanced)" 节点
+2. 将图像源连接到节点
+3. 配置所有生成参数（temperature、top_p、top_k 等）
+4. 如需要可设置自定义提示
+5. 运行工作流
+
+## 描述工具
+
+### 图像批处理路径 🖼️
+
+此节点允许您从目录中加载多个图像进行批处理：
+
+| 参数 | 描述 |
+| --------- | ----------- |
+| **image_dir** | 包含图像的目录路径 |
+| **batch_size** | 要加载的图像数量（0 = 所有图像） |
+| **start_from** | 从第N张图像开始（1 = 第一张图像） |
+| **sort_method** | 图像加载顺序：顺序/倒序/随机 |
+
+### 描述保存器 📝
+
+此节点将生成的描述保存到文本文件：
+
+| 参数 | 描述 |
+| --------- | ----------- |
+| **string** | 要保存的描述文本 |
+| **image_path** | 被描述图像的路径 |
+| **image** | （可选）要与描述一起保存的图像 |
+| **custom_output_path** | （可选）自定义输出目录路径 |
+| **custom_file_name** | （可选）自定义文件名（不带扩展名） |
+| **overwrite** | 如果为true，将覆盖现有文件；如果为false，将添加数字使文件名唯一 |
+
+### 参数说明
+
+#### 标准节点
+
+##### 基础节点
+| 参数 | 描述 | 默认值 | 范围 |
+| --------- | ----------- | ------- | ----- |
+| **Model** | 使用的 JoyCaption 模型 | `llama-joycaption-beta-one-hf-llava` | - |
+| **Memory Control** | 内存优化设置 | Default | Default (fp32), Balanced (8-bit), Maximum Savings (4-bit) |
+| **Caption Type** | 描述风格选择 | Descriptive | Descriptive, Descriptive (Casual), Straightforward, Tags, Technical, Artistic |
+| **Caption Length** | 输出长度控制 | medium | any, very short, short, medium, long, very long |
+
+#### GGUF 节点
+
+##### GGUF 基础节点
+| 参数 | 描述 | 默认值 | 范围 |
+| --------- | ----------- | ------- | ----- |
+| **Model** | 使用的 GGUF 模型 | JoyCaption Beta One (IQ4_XS) | Q2_K, IQ4_XS, Q5_K_M, Q6_K |
+| **Processing Mode** | 硬件加速 | GPU | GPU, CPU |
+| **Caption Type** | 描述风格选择 | Descriptive | Descriptive, Descriptive (Casual), Straightforward, Tags, Technical, Artistic |
+| **Caption Length** | 输出长度控制 | any | any, very short, short, medium, long, very long |
+| **Memory Management** | 模型内存处理 | Keep in Memory | Keep in Memory, Clear After Run, Global Cache |
+
+##### GGUF 高级节点
+| 参数 | 描述 | 默认值 | 范围 |
+| --------- | ----------- | ------- | ----- |
+| **Model** | 使用的 GGUF 模型 | JoyCaption Beta One (IQ4_XS) | Q2_K, IQ4_XS, Q5_K_M, Q6_K |
+| **Processing Mode** | 硬件加速 | GPU | GPU, CPU |
+| **Max New Tokens** | 最大生成标记数 | 512 | 1-2048 |
+| **Temperature** | 生成随机性 | 0.6 | 0.0-2.0 |
+| **Top-p** | 核采样 | 0.9 | 0.0-1.0 |
+| **Top-k** | Top-k 采样 | 0 | 0-100 |
+| **Custom Prompt** | 自定义提示模板 | "" | 任意文本 |
+| **Memory Management** | 模型内存处理 | Keep in Memory | Keep in Memory, Clear After Run, Global Cache |
+
+### 量化选项
+
+#### 标准模型（HuggingFace���
+| 模式 | 精度 | 内存使用 | 速度 | 质量 | 推荐 GPU |
+|------|-----------|--------------|-------|---------|----------------|
+| Default | fp32 | ~16GB | 1x | 最佳 | 24GB+ |
+| Default | bf16 | ~8GB | 1.5x | 优秀 | 16GB+ |
+| Default | fp16 | ~8GB | 2x | 很好 | 16GB+ |
+| Balanced | 8-bit | ~4GB | 2.5x | 良好 | 12GB+ |
+| Maximum Savings | 4-bit | ~2GB | 3x | 可接受 | 8GB+ |
+
+#### GGUF 模型（推荐）
+| 量化 | 模型大小 | 内存使用 | 速度 | 质量 | 推荐 GPU |
+|-------------|------------|--------------|-------|---------|----------------|
+| Q2_K | 3.18GB | ~4GB | 4x | 良好 | 6GB+ |
+| Q3_K_S | 3.66GB | ~5GB | 3.5x | 良好+ | 8GB+ |
+| Q3_K_M | 4.02GB | ~5GB | 3.5x | 更好 | 8GB+ |
+| Q3_K_L | 4.32GB | ~6GB | 3x | 更好+ | 8GB+ |
+| IQ4_XS | 4.48GB | ~6GB | 3x | 很好 | 8GB+ |
+| Q4_K_S | 4.69GB | ~6GB | 3x | 很好 | 8GB+ |
+| Q4_K_M | 4.92GB | ~7GB | 2.5x | 很好+ | 10GB+ |
+| Q5_K_S | 5.60GB | ~7GB | 2.5x | 优秀 | 10GB+ |
+| Q5_K_M | 5.73GB | ~8GB | 2.5x | 优秀+ | 12GB+ |
+| Q6_K | 6.60GB | ~8GB | 2x | 接近原版 | 12GB+ |
+| Q8_0 | 8.54GB | ~10GB | 1.8x | 原版- | 16GB+ |
+| F16 | 16.1GB | ~18GB | 1.5x | 原版 | 24GB+ |
+
+**注意**：GGUF 模型相比标准模型提供更好的性能和更低的内存使用。IQ4_XS 提供质量和效率的最佳平衡。
+
+#### 高级节点
+
+| 参数 | 描述 | 默认值 | 范围 |
+| --------- | ----------- | ------- | ----- |
+| **Extra Options** | 额外功能选项 | [] | 多个选项 |
+| **Person Name** | 人物描述名称 | "" | 任意文本 |
+| **Max New Tokens** | 最大生成标记数 | 512 | 1-2048 |
+| **Temperature** | 生成温度 | 0.6 | 0.0-2.0 |
+| **Top-p** | 采样参数 | 0.9 | 0.0-1.0 |
+| **Top-k** | Top-k 采样 | 0 | 0-100 |
+
+### 内存管理选项
+
+| 模式 | 描述 | 推荐使用 |
+|------|-------------|-----------------|
+| 全局缓存 | 将模型保持在内存中以获得最快的处理速度 | 高显存 GPU (16GB+) |
+| 保持内存 | 在工作流结束前保持模型在内存中 | 中等显存 GPU (8GB+) |
+| 运行后清除 | 每次生成后清除模型 | 低显存 GPU (<8GB) |
+
+## 设置建议
+
+| 设置 | 建议 |
+| ------- | -------------- |
+| **模型选择** | 使用 GGUF 模型获得更好的性能和更低的内存使用。IQ4_XS 提供质量和效率的最佳平衡 |
+| **内存模式** | 根据 GPU 显存：24GB+ 使用全局缓存，12GB+ 使用保持内存，8GB+ 使用运行后清除 |
+| **处理模式** | 使用 GPU 模式获得更快处理速度，CPU 模式适用于显存有限的系统 |
+| **输入分辨率** | 模型最适合 512x512 或更高分辨率的图像 |
+| **内存使用** | 如果遇到内存问题，尝试 GGUF Q2_K 模型或使用运行后清除模式 |
+| **性能** | 对于批处理，如果有足够的显存，考虑使用 GGUF 模型的全局缓存模式 |
+| **Temperature** | 较低值 (0.6-0.7) 获得更稳定的结果，较高值 (0.8-1.0) 获得更多样化的结果 |
+| **Top-k 参数** | 设置为 0 禁用，或使用 40-50 等值获得更集中的生成 |
+
+## 关于模型
+
+本实现使用基于 LLaVA 的图像描述模型，经过优化以提供快速准确的图像描述。
+
+模型特点：
+* 免费开源权重
+* 无内容审查限制
+* 广泛的风格多样性（数字艺术、照片级真实感、动漫等）
+* 使用 bfloat16 精度快速处理
+* 高质量描述生成
+* 内存高效运行
+* 在各种图像类型上保持一致性
+* 支持多种描述风格
+* 针对扩散模型训练优化
+
+模型在多样化数据集上训练，确保：
+* 不同图像类型的平衡表示
+* 各种场景下的高准确性
+* 复杂场景的稳健性能
+* 支持 SFW 和 NSFW 内容
+* 不同风格和概念的平等覆盖
+
+## 路线图
+
+### ✅ 已完成（v1.3.0）
+* ✅ GGUF 模型支持，提供更好的性能
+* ✅ 支持 12 种 GGUF 量化格式（Q2_K 到 F16）
+* ✅ 增强的错误处理和参数验证
+* ✅ 干净的控制台输出（无调试垃圾信息）
+* ✅ 改进的内存管理选项
+* ✅ 批处理支持（描述工具）
+* ✅ CPU 处理性能优化（GGUF CPU 模式）
+* ✅ 增强的批处理功能与内存管理
+
+### 🔄 未来计划
+* 更多描述风格选项和自定义提示
+* 高级微调支持自定义模型
+* 实时处理优化
+* 多语言描述支持
+* 集成更多视觉-语言模型
+
+## 致谢
+
+* **原始 JoyCaption 模型**: [fancyfeast](https://huggingface.co/fancyfeast) - 基础 JoyCaption 模型的创建者
+* **GGUF 量化模型**: [mradermacher](https://huggingface.co/mradermacher) - 提供全面的 GGUF 量化模型 (Q2_K 到 F16)
+* **备选 GGUF 模型**: [concedo](https://huggingface.co/concedo) - 提供带视觉投影的备选 GGUF 模型
+* **ComfyUI 集成**: [1038lab](https://github.com/1038lab) - 此 ComfyUI 自定义节点的开发者
+* **LLaVA 框架**: Microsoft Research - 基础视觉-语言模型架构
+* **llama-cpp-python**: [abetlen](https://github.com/abetlen/llama-cpp-python) - llama.cpp 的 Python 绑定
+
+## 许可证
+
+本仓库代码基于 GPL-3.0 许可证发布。
+
+
+模型采用 GPL-3.0 许可证发布。请参阅 [LICENSE](LICENSE) 文件了解详情。 
+

ComfyUI-JoyCaption/__init__.py

@@ -0,0 +1,71 @@
+import os
+import importlib
+import sys
+from pathlib import Path
+
+current_dir = Path(__file__).parent
+
+if str(current_dir) not in sys.path:
+    sys.path.insert(0, str(current_dir))
+
+NODE_CLASS_MAPPINGS = {}
+NODE_DISPLAY_NAME_MAPPINGS = {}
+
+EXCLUDE_FILES = ['__init__.py', '__pycache__']
+
+# Enable Windows color support
+if sys.platform == 'win32':
+    os.system('color')
+
+# Check if llama-cpp-python is available for GGUF functionality
+GGUF_AVAILABLE = False
+try:
+    import llama_cpp
+    GGUF_AVAILABLE = True
+except ImportError:
+    # Use Windows color codes for better visibility
+    print("\n" + "=" * 80)
+    print("\033[91mWARNING: llama-cpp-python library not found, GGUF functionality is not available\033[0m")
+    print("\033[93mTo use GGUF features, install additional dependencies:\033[0m")
+    print("\033[96mpip install -r requirements_gguf.txt\033[0m")
+    
+    # Check if installation guide exists and provide link
+    install_guide = current_dir / "llama_cpp_install.md"
+    if install_guide.exists():
+        print("\033[93mFor detailed installation instructions with CUDA support, please see:\033[0m")
+        print(f"\033[96m{install_guide}\033[0m")
+    
+    print("\033[92mBasic JoyCaption functionality is still available\033[0m")
+    print("=" * 80 + "\n")
+except Exception as e:
+    print("\n" + "=" * 80)
+    print(f"\033[91mError loading GGUF dependencies: {str(e)}\033[0m")
+    print("\033[92mBasic JoyCaption functionality is still available\033[0m")
+    print("=" * 80 + "\n")
+
+# Process all Python files in a deterministic order to avoid import-time races
+for file in sorted(current_dir.glob('*.py')):
+    if file.name not in EXCLUDE_FILES:
+        try:
+            module_name = file.stem
+            spec = importlib.util.spec_from_file_location(module_name, str(file))
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            
+            # Skip GGUF module if llama-cpp-python is not available
+            if not GGUF_AVAILABLE and module_name == 'JC_GGUF':
+                continue
+                
+            spec.loader.exec_module(module)
+            
+            if hasattr(module, 'NODE_CLASS_MAPPINGS'):
+                NODE_CLASS_MAPPINGS.update(module.NODE_CLASS_MAPPINGS)
+            
+            if hasattr(module, 'NODE_DISPLAY_NAME_MAPPINGS'):
+                NODE_DISPLAY_NAME_MAPPINGS.update(module.NODE_DISPLAY_NAME_MAPPINGS)
+        except Exception as e:
+            print(f"Error loading module {module_name}: {str(e)}")
+            if module_name != 'JC_GGUF':  # Only show warning for non-GGUF modules
+                print(f"Warning: Failed to load {module_name} module")
+
+__all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS']

ComfyUI-JoyCaption/custom_models.md

@@ -0,0 +1,154 @@
+# 🧩 JoyCaption Custom Models Guide
+Supports both **HF** and **GGUF** model customization.
+
+---
+
+## 💡 Overview
+Starting from **JoyCaption v2.0.2**, users can register **their own models** —  
+without modifying any of the repository’s internal configuration files.
+
+This makes it easy to:
+- Test your own LLaVA / Phi / Qwen / Mistral etc. models  
+- Add new quantized GGUF models  
+- Keep your changes persistent between JoyCaption updates  
+
+---
+
+## 📁 File Location
+Create or edit this file in your JoyCaption directory:
+
+```
+
+ComfyUI/custom_nodes/ComfyUI-JoyCaption/custom_models.json
+
+````
+
+If the file doesn’t exist, JoyCaption will **skip it safely** (no errors).  
+You can also copy the provided `custom_models_example.json` and rename it.
+
+---
+
+## ⚙️ File Structure
+
+```json
+{
+  "hf_models": {
+    "My-LLaVA-Model": {
+      "name": "myusername/llava-custom-model",
+      "description": "Example Hugging Face model for JoyCaption (HF format)."
+    }
+  },
+  "gguf_models": {
+    "My-GGUF-Caption-Model": {
+      "name": "myusername/llava-custom-gguf/model.gguf",
+      "description": "Example GGUF model with image captioning support."
+    }
+  }
+}
+````
+
+### 🧱 Explanation
+
+| Key           | Description                                                           |
+| ------------- | --------------------------------------------------------------------- |
+| `hf_models`   | Models loaded through HuggingFace / Transformers (used by `JC.py`)    |
+| `gguf_models` | Models using llama.cpp GGUF format (used by `JC_GGUF.py`)             |
+| `name`        | Model identifier — either full HF repo path or local `.gguf` filename |
+| `description` | Optional. Appears as tooltip in ComfyUI node interface                |
+
+---
+
+## 🧩 Empty Default File
+
+For users who haven’t added anything yet,
+you can safely ship this minimal empty version in the repo:
+
+```json
+{
+  "hf_models": {},
+  "gguf_models": {}
+}
+```
+
+If the file is empty or missing, JoyCaption will continue using built-in models.
+
+---
+
+## 🧱 Example Template
+
+An example file `custom_models_example.json` is provided in the repository root:
+
+```json
+{
+  "__comment__": "Example for user customization",
+  "hf_models": {
+    "My-Phi-Vision": {
+      "name": "myusername/phi-vision-captioner",
+      "description": "Custom Phi-based visual captioning model."
+    }
+  },
+  "gguf_models": {
+    "My-Gemma-GGUF": {
+      "name": "mlabonne/gemma-3-27b-it-abliterated-GGUF",
+      "description": "High-quality GGUF model for image captioning."
+    }
+  }
+}
+```
+
+Rename this file to `custom_models.json` to activate it.
+
+---
+
+## 🧰 Behavior Notes
+
+* ✅ The system merges your `custom_models.json` entries with internal presets.
+* ⚙️ The merging happens **at runtime** — no need to modify `jc_data.json`.
+* 🧼 Safe: if parsing fails, JoyCaption prints a warning and continues running.
+* 🔒 Your file is ignored during updates (no overwriting by git pulls).
+* 🖥️ Works for both `JC.py` and `JC_GGUF.py` independently.
+
+---
+
+## 📘 Related Files
+
+| File                         | Purpose                                          |
+| ---------------------------- | ------------------------------------------------ |
+| `JC.py`                      | Handles HF-based models (e.g., LLaVA, Phi, Qwen) |
+| `JC_GGUF.py`                 | Handles quantized GGUF models                    |
+| `custom_models.json`         | Your personal model definitions                  |
+| `custom_models_example.json` | Example reference file                           |
+
+---
+
+## 🧠 Tips for Power Users
+
+* You can define **multiple entries** under each section.
+* Hugging Face repos can include **subfolders or filenames** if needed:
+
+  ```
+  "name": "myrepo/models/llava-custom-4bit/ggml-model-q4_k.gguf"
+  ```
+* For local models, use the **relative path** under your `ComfyUI/models` directory.
+* Descriptions are optional but highly recommended.
+
+---
+
+## 🪄 Troubleshooting
+
+| Issue                                       | Possible Cause                                        | Fix                                          |
+| ------------------------------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| Model not showing in dropdown               | JSON syntax error or missing section                  | Validate JSON format                         |
+| “Failed to load custom_models.json” warning | Invalid JSON content                                  | Check braces/quotes                          |
+| Model loads but errors on inference         | Wrong path or unsupported format                      | Verify `name` path and model type            |
+| GGUF model missing mmproj                   | Ensure `GGUF_SETTINGS["mmproj_filename"]` file exists | Download via `hf_hub_download` automatically |
+
+---
+
+## 🏁 Summary
+
+✅ **No internal edits needed**
+✅ **Both HF and GGUF supported**
+✅ **Safe and optional**
+✅ **Updatable without conflicts**
+

ComfyUI-JoyCaption/custom_models_example.json

@@ -0,0 +1,29 @@
+{
+  "hf_models": {
+    "__comment__": "For HuggingFace-format models (handled by JC.py). Each key appears in the dropdown list.",
+
+    "My-LLaVA-Model": {
+      "name": "myusername/llava-custom-model",
+      "description": "Example custom Hugging Face model with image captioning capability (LLaVA-based)."
+    },
+
+    "My-Phi-Vision": {
+      "name": "myusername/phi-vision-captioner",
+      "description": "Optional: a different HF model supporting visual-language tasks."
+    }
+  },
+
+  "gguf_models": {
+    "__comment__": "For GGUF-format models (handled by JC_GGUF.py). Each key appears in the GGUF model dropdown.",
+
+    "My-GGUF-Caption-Model": {
+      "name": "myusername/llava-custom-gguf-model/model.gguf",
+      "description": "Example GGUF model file from Hugging Face (must include correct mmproj if needed)."
+    },
+
+    "My-Gemma-GGUF": {
+      "name": "mlabonne/gemma-3-27b-it-abliterated-GGUF",
+      "description": "Example: large GGUF model known to work well with JoyCaption."
+    }
+  }
+}

ComfyUI-JoyCaption/example_workflows/JoyCaption-GGUF.json

@@ -0,0 +1,345 @@
+{
+  "id": "6cdda1b6-9bfc-4b5f-9d6b-60ef9a9d93fc",
+  "revision": 0,
+  "last_node_id": 22,
+  "last_link_id": 26,
+  "nodes": [
+    {
+      "id": 16,
+      "type": "ImageBatchPath",
+      "pos": [
+        -611.5386352539062,
+        298.06317138671875
+      ],
+      "size": [
+        242.22389221191406,
+        180
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "shape": 6,
+          "type": "IMAGE",
+          "links": [
+            26
+          ]
+        },
+        {
+          "name": "IMAGE_PATH",
+          "shape": 6,
+          "type": "STRING",
+          "links": []
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "ImageBatchPath"
+      },
+      "widgets_values": [
+        "O:\\images",
+        1,
+        2,
+        "sequential"
+      ]
+    },
+    {
+      "id": 19,
+      "type": "JC_GGUF",
+      "pos": [
+        235.76669311523438,
+        298.06317138671875
+      ],
+      "size": [
+        298.5727233886719,
+        174
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 20
+        },
+        {
+          "name": "extra_options",
+          "shape": 7,
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            22
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "JC_GGUF"
+      },
+      "widgets_values": [
+        "JoyCaption Beta One (IQ4_XS)",
+        "GPU",
+        "Descriptive",
+        "any",
+        "Keep in Memory"
+      ]
+    },
+    {
+      "id": 11,
+      "type": "PreviewAny",
+      "pos": [
+        563.1483154296875,
+        782.4658813476562
+      ],
+      "size": [
+        551.0270385742188,
+        254.4538116455078
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 24
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.3.49",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": []
+    },
+    {
+      "id": 20,
+      "type": "JC_GGUF_adv",
+      "pos": [
+        239.39669799804688,
+        712.919677734375
+      ],
+      "size": [
+        298.3599853515625,
+        324
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 21
+        },
+        {
+          "name": "extra_options",
+          "shape": 7,
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "PROMPT",
+          "type": "STRING",
+          "links": [
+            23
+          ]
+        },
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            24
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "JC_GGUF_adv"
+      },
+      "widgets_values": [
+        "JoyCaption Beta One (IQ4_XS)",
+        "GPU",
+        "Stable Diffusion Prompt",
+        "any",
+        512,
+        0.6,
+        0.9,
+        0,
+        "",
+        "Keep in Memory"
+      ]
+    },
+    {
+      "id": 17,
+      "type": "AILab_ImagePreview",
+      "pos": [
+        -348.1651306152344,
+        298.06317138671875
+      ],
+      "size": [
+        551.80078125,
+        738.8565063476562
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 26
+        }
+      ],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            20,
+            21
+          ]
+        }
+      ],
+      "properties": {
+        "cnr_id": "comfyui-rmbg",
+        "ver": "c36a6a819fef2208316693c29c055b5c558c89e8",
+        "Node name for S&R": "AILab_ImagePreview"
+      },
+      "widgets_values": [],
+      "color": "#2e3e57",
+      "bgcolor": "#4b5b73"
+    },
+    {
+      "id": 9,
+      "type": "PreviewAny",
+      "pos": [
+        557.0983276367188,
+        298.06317138671875
+      ],
+      "size": [
+        546.5134887695312,
+        241.1837158203125
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 22
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.3.49",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": []
+    },
+    {
+      "id": 21,
+      "type": "PreviewAny",
+      "pos": [
+        563.1483154296875,
+        629.5003051757812
+      ],
+      "size": [
+        385.2570495605469,
+        88
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 23
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.3.49",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": []
+    }
+  ],
+  "links": [
+    [
+      20,
+      17,
+      0,
+      19,
+      0,
+      "IMAGE"
+    ],
+    [
+      21,
+      17,
+      0,
+      20,
+      0,
+      "IMAGE"
+    ],
+    [
+      22,
+      19,
+      0,
+      9,
+      0,
+      "*"
+    ],
+    [
+      23,
+      20,
+      0,
+      21,
+      0,
+      "*"
+    ],
+    [
+      24,
+      20,
+      1,
+      11,
+      0,
+      "*"
+    ],
+    [
+      26,
+      16,
+      0,
+      17,
+      0,
+      "IMAGE"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.8264462809917356,
+      "offset": [
+        751.8155895059733,
+        96.63700520386863
+      ]
+    },
+    "frontendVersion": "1.24.4"
+  },
+  "version": 0.4
+}

ComfyUI-JoyCaption/example_workflows/Joycaption_node.json

@@ -0,0 +1,526 @@
+{
+  "id": "00000000-0000-0000-0000-000000000000",
+  "revision": 0,
+  "last_node_id": 51,
+  "last_link_id": 77,
+  "nodes": [
+    {
+      "id": 39,
+      "type": "JC",
+      "pos": [
+        1864.2611083984375,
+        930
+      ],
+      "size": [
+        290,
+        150
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 68
+        },
+        {
+          "name": "extra_options",
+          "shape": 7,
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "link": 64
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            73
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "JC",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "joycaption-alpha-two",
+        "Balanced (8-bit)",
+        "Stable Diffusion Prompt",
+        "any"
+      ],
+      "color": "#233",
+      "bgcolor": "#355"
+    },
+    {
+      "id": 40,
+      "type": "JC_adv",
+      "pos": [
+        1864.2611083984375,
+        1260
+      ],
+      "size": [
+        290,
+        300
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 69
+        },
+        {
+          "name": "extra_options",
+          "shape": 7,
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "link": 65
+        }
+      ],
+      "outputs": [
+        {
+          "name": "PROMPT",
+          "type": "STRING",
+          "links": [
+            74
+          ]
+        },
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            75
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "JC_adv",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "joycaption-beta-one",
+        "Balanced (8-bit)",
+        "Descriptive",
+        "very long",
+        512,
+        0.6,
+        0.9,
+        0,
+        ""
+      ],
+      "color": "#233",
+      "bgcolor": "#355"
+    },
+    {
+      "id": 41,
+      "type": "JC_ExtraOptions",
+      "pos": [
+        1425.7388916015625,
+        1024
+      ],
+      "size": [
+        382.783203125,
+        736
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "extra_options",
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "links": [
+            64,
+            65
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "JC_ExtraOptions",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        false,
+        true,
+        "Amy"
+      ],
+      "color": "#232",
+      "bgcolor": "#353"
+    },
+    {
+      "id": 42,
+      "type": "AILab_LoadImage",
+      "pos": [
+        1020,
+        930
+      ],
+      "size": [
+        350,
+        830
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            67
+          ]
+        },
+        {
+          "name": "MASK",
+          "type": "MASK",
+          "links": null
+        },
+        {
+          "name": "MASK_IMAGE",
+          "type": "IMAGE",
+          "links": null
+        },
+        {
+          "name": "WIDTH",
+          "type": "INT",
+          "links": null
+        },
+        {
+          "name": "HEIGHT",
+          "type": "INT",
+          "links": null
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-rmbg",
+        "ver": "4faa7c7c12147db95345ee78b30f38273443ff99",
+        "widget_ue_connectable": {},
+        "Node name for S&R": "AILab_LoadImage"
+      },
+      "widgets_values": [
+        "ComfyUI_temp_jbrru_00003_.png",
+        "alpha",
+        1,
+        "longest_side",
+        0,
+        "image"
+      ]
+    },
+    {
+      "id": 43,
+      "type": "Reroute",
+      "pos": [
+        1730,
+        930
+      ],
+      "size": [
+        75,
+        26
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "",
+          "type": "*",
+          "link": 67
+        }
+      ],
+      "outputs": [
+        {
+          "name": "",
+          "type": "IMAGE",
+          "links": [
+            68,
+            69
+          ]
+        }
+      ],
+      "properties": {
+        "showOutputText": false,
+        "horizontal": false
+      }
+    },
+    {
+      "id": 47,
+      "type": "ShowText|pysssss",
+      "pos": [
+        2210,
+        930
+      ],
+      "size": [
+        600,
+        260
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "text",
+          "type": "STRING",
+          "link": 73
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "shape": 6,
+          "type": "STRING",
+          "links": []
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-custom-scripts",
+        "ver": "aac13aa7ce35b07d43633c3bbe654a38c00d74f5",
+        "widget_ue_connectable": {},
+        "Node name for S&R": "ShowText|pysssss"
+      },
+      "widgets_values": [
+        "Photo of a young Asian woman walking barefoot on a city street at night, wearing a white t-shirt and high-waisted white shorts with a gold belt, short black hair, full body, long legs, slender physique, fair skin, urban setting, streetlights, blurry background, people walking, trees, plants in planters, casual attire, confident pose, high quality, jpeg artifacts"
+      ]
+    },
+    {
+      "id": 48,
+      "type": "ShowText|pysssss",
+      "pos": [
+        2210,
+        1260
+      ],
+      "size": [
+        600,
+        170
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "text",
+          "type": "STRING",
+          "link": 74
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "shape": 6,
+          "type": "STRING",
+          "links": []
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-custom-scripts",
+        "ver": "aac13aa7ce35b07d43633c3bbe654a38c00d74f5",
+        "widget_ue_connectable": {},
+        "Node name for S&R": "ShowText|pysssss"
+      },
+      "widgets_values": [
+        "Write a very long detailed description for this image."
+      ]
+    },
+    {
+      "id": 49,
+      "type": "ShowText|pysssss",
+      "pos": [
+        2210,
+        1500
+      ],
+      "size": [
+        600,
+        260
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "text",
+          "type": "STRING",
+          "link": 75
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "shape": 6,
+          "type": "STRING",
+          "links": null
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-custom-scripts",
+        "ver": "aac13aa7ce35b07d43633c3bbe654a38c00d74f5",
+        "widget_ue_connectable": {},
+        "Node name for S&R": "ShowText|pysssss"
+      },
+      "widgets_values": [
+        "The image is a photograph taken at night on a bustling urban sidewalk. The central subject is an Asian woman with a slim, toned physique and medium-sized breasts. She has straight, shoulder-length black hair with bangs, and her skin tone is light. She is wearing a simple, fitted white t-shirt and matching white high-waisted shorts that accentuate her long legs. She is barefoot, walking confidently down the sidewalk, her feet slightly apart.\n\nIn the background, the sidewalk is lined with people, some of whom are blurred, indicating motion. The people are dressed in casual summer clothing, including t-shirts, shorts, and backpacks. To the left, there is a black lamppost, and to the right, a wooden planter with green foliage. The background also features a mix of storefronts with illuminated signs and trees, adding a sense of depth and urban vibrancy to the scene. The lighting is soft and warm, with streetlights and neon signs creating a cozy, late-night atmosphere. The overall composition of the photograph emphasizes the woman's poised and confident presence amidst the busy cityscape. The textures in the image range from the smoothness of her clothing to the roughness of the sidewalk and the soft glow of the streetlights."
+      ]
+    }
+  ],
+  "links": [
+    [
+      64,
+      41,
+      0,
+      39,
+      1,
+      "JOYCAPTION_EXTRA_OPTIONS"
+    ],
+    [
+      65,
+      41,
+      0,
+      40,
+      1,
+      "JOYCAPTION_EXTRA_OPTIONS"
+    ],
+    [
+      67,
+      42,
+      0,
+      43,
+      0,
+      "*"
+    ],
+    [
+      68,
+      43,
+      0,
+      39,
+      0,
+      "IMAGE"
+    ],
+    [
+      69,
+      43,
+      0,
+      40,
+      0,
+      "IMAGE"
+    ],
+    [
+      73,
+      39,
+      0,
+      47,
+      0,
+      "STRING"
+    ],
+    [
+      74,
+      40,
+      0,
+      48,
+      0,
+      "STRING"
+    ],
+    [
+      75,
+      40,
+      1,
+      49,
+      0,
+      "STRING"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.6830134553650705,
+      "offset": [
+        -175.6426170595139,
+        -471.9308396036945
+      ]
+    },
+    "ue_links": [],
+    "links_added_by_ue": [],
+    "frontendVersion": "1.19.9",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

ComfyUI-JoyCaption/example_workflows/batch_image_text_output.json

@@ -0,0 +1,342 @@
+{
+  "id": "d7f22f6a-de79-4884-b925-2621f86c6dc6",
+  "revision": 0,
+  "last_node_id": 11,
+  "last_link_id": 11,
+  "nodes": [
+    {
+      "id": 3,
+      "type": "JC_adv",
+      "pos": [
+        1043.3333740234375,
+        0
+      ],
+      "size": [
+        400,
+        380
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 8
+        },
+        {
+          "name": "extra_options",
+          "shape": 7,
+          "type": "JOYCAPTION_EXTRA_OPTIONS",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "PROMPT",
+          "type": "STRING",
+          "links": []
+        },
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            6
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "JC_adv",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "joycaption-beta-one",
+        "Maximum Savings (4-bit)",
+        "Descriptive",
+        "short",
+        512,
+        0.6,
+        0.9,
+        0,
+        "",
+        "Keep in Memory"
+      ]
+    },
+    {
+      "id": 8,
+      "type": "CaptionSaver",
+      "pos": [
+        1870,
+        -80
+      ],
+      "size": [
+        400,
+        200
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "string",
+          "type": "STRING",
+          "link": 7
+        },
+        {
+          "name": "image_path",
+          "type": "STRING",
+          "link": 5
+        },
+        {
+          "name": "image",
+          "shape": 7,
+          "type": "IMAGE",
+          "link": 11
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "CaptionSaver",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "C:\\Images\\JC",
+        "JC_img",
+        false
+      ]
+    },
+    {
+      "id": 9,
+      "type": "ImageBatchPath",
+      "pos": [
+        630,
+        -60
+      ],
+      "size": [
+        400,
+        200
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE_PATH",
+          "shape": 6,
+          "type": "STRING",
+          "links": [
+            5
+          ]
+        },
+        {
+          "name": "IMAGE",
+          "shape": 6,
+          "type": "IMAGE",
+          "links": [
+            8,
+            10
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "Node name for S&R": "ImageBatchPath",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "C:\\Images",
+        0,
+        1,
+        "sequential"
+      ]
+    },
+    {
+      "id": 10,
+      "type": "ShowText|pysssss",
+      "pos": [
+        1456.6666259765625,
+        0
+      ],
+      "size": [
+        400,
+        380
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "text",
+          "type": "STRING",
+          "link": 6
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "shape": 6,
+          "type": "STRING",
+          "links": [
+            7
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-custom-scripts",
+        "ver": "aac13aa7ce35b07d43633c3bbe654a38c00d74f5",
+        "Node name for S&R": "ShowText|pysssss",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [
+        "Monochromatic digital drawing of a young woman with wavy, shoulder-length blonde hair, wearing a white collared shirt. She has a serene expression, large eyes, and subtle makeup. The background is a gradient grey, emphasizing her delicate features. The style is realistic with smooth textures and fine lines.",
+        "Digital grayscale portrait of a young woman with wavy, shoulder-length hair, light skin, and delicate features. She wears a simple necklace, long earrings, and a sleeveless top. Her expression is calm and confident, with subtle shadows enhancing her facial contours. The background is a smooth gradient.",
+        "Digital black-and-white portrait of a young, handsome man with short, slightly tousled hair, light stubble, and serious expression. He wears a collared shirt with visible buttons, set against a plain grey background. The detailed shading and realistic texture emphasize his facial features and subtle skin texture.",
+        "Realistic black-and-white digital portrait of an elderly man with wavy, gray hair, a trimmed beard, and deep wrinkles. He wears a collared shirt with a zip-up jacket. The background is a plain, light gray gradient. The detailed texture highlights his aged skin and expressive eyes, creating a lifelike, somber effect."
+      ]
+    },
+    {
+      "id": 11,
+      "type": "AILab_ImagePreview",
+      "pos": [
+        1043.3333740234375,
+        -380
+      ],
+      "size": [
+        810,
+        330
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 10
+        }
+      ],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            11
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui-rmbg",
+        "ver": "4faa7c7c12147db95345ee78b30f38273443ff99",
+        "Node name for S&R": "AILab_ImagePreview",
+        "widget_ue_connectable": {}
+      },
+      "widgets_values": [],
+      "color": "#2e3e57",
+      "bgcolor": "#4b5b73"
+    }
+  ],
+  "links": [
+    [
+      5,
+      9,
+      0,
+      8,
+      1,
+      "STRING"
+    ],
+    [
+      6,
+      3,
+      1,
+      10,
+      0,
+      "STRING"
+    ],
+    [
+      7,
+      10,
+      0,
+      8,
+      0,
+      "STRING"
+    ],
+    [
+      8,
+      9,
+      1,
+      3,
+      0,
+      "IMAGE"
+    ],
+    [
+      10,
+      9,
+      1,
+      11,
+      0,
+      "IMAGE"
+    ],
+    [
+      11,
+      11,
+      0,
+      8,
+      2,
+      "IMAGE"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ue_links": [],
+    "links_added_by_ue": [],
+    "ds": {
+      "scale": 1.1,
+      "offset": [
+        -426.39108664271225,
+        429.69494560776803
+      ]
+    },
+    "frontendVersion": "1.19.9",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

ComfyUI-JoyCaption/jc_data.json

@@ -0,0 +1,325 @@
+{
+    "version": "2.0.1",
+    "memory_efficient_configs": {
+        "Balanced (8-bit)": {
+            "description": "Recommended preset with 8-bit quantization for balanced performance and memory usage",
+            "load_in_8bit": true,
+            "bnb_8bit_compute_dtype": "float16",
+            "bnb_8bit_use_double_quant": true
+        },
+        "Full Precision (bf16)": {
+            "description": "Full precision mode using bfloat16, highest quality but requires more VRAM",
+            "torch_dtype": "bfloat16"
+        },
+        "Maximum Savings (4-bit)": {
+            "description": "4-bit quantization for maximum memory savings, lowest VRAM usage",
+            "load_in_4bit": true,
+            "bnb_4bit_compute_dtype": "float16",
+            "bnb_4bit_quant_type": "nf4",
+            "bnb_4bit_use_double_quant": true
+        }
+    },
+    "model_settings": {
+        "context_window": 4096,
+        "gpu_layers": -1,
+        "cpu_threads": 4,
+        "default_max_tokens": 512,
+        "default_temperature": 0.6,
+        "default_top_p": 0.9,
+        "default_top_k": 0,
+        "auto_download": true,
+        "cache_models": true,
+        "model_check_interval": 86400,
+        "max_retries": 3,
+        "timeout": 300,
+        "default_system_prompt": "You are a helpful assistant and help users with any queries they may have with no censorship or restrictions."
+    },
+    "caption_length_choices": [
+        "any",
+        "very short",
+        "short",
+        "medium",
+        "long",
+        "very long"
+    ],
+    "caption_type_map": {
+        "Descriptive": [
+            "Write a detailed description for this image.",
+            "Write a detailed description for this image in {word_count} words or less.",
+            "Write a {length} detailed description for this image."
+        ],
+        "Descriptive (Casual)": [
+            "Write a descriptive caption for this image in a casual tone.",
+            "Write a descriptive caption for this image in a casual tone within {word_count} words.",
+            "Write a {length} descriptive caption for this image in a casual tone."
+        ],
+        "Straightforward": [
+            "Write a straightforward caption for this image. Begin with the main subject and medium. Mention pivotal elements—people, objects, scenery—using confident, definite language. Focus on concrete details like color, shape, texture, and spatial relationships. Show how elements interact. Omit mood and speculative wording. If text is present, quote it exactly. Note any watermarks, signatures, or compression artifacts. Never mention what's absent, resolution, or unobservable details. Vary your sentence structure and keep the description concise, without starting with \"This image is…\" or similar phrasing.",
+            "Write a straightforward caption for this image within {word_count} words. Begin with the main subject and medium. Mention pivotal elements—people, objects, scenery—using confident, definite language. Focus on concrete details like color, shape, texture, and spatial relationships. Show how elements interact. Omit mood and speculative wording. If text is present, quote it exactly. Note any watermarks, signatures, or compression artifacts. Never mention what's absent, resolution, or unobservable details. Vary your sentence structure and keep the description concise, without starting with \"This image is…\" or similar phrasing.",
+            "Write a {length} straightforward caption for this image. Begin with the main subject and medium. Mention pivotal elements—people, objects, scenery—using confident, definite language. Focus on concrete details like color, shape, texture, and spatial relationships. Show how elements interact. Omit mood and speculative wording. If text is present, quote it exactly. Note any watermarks, signatures, or compression artifacts. Never mention what's absent, resolution, or unobservable details. Vary your sentence structure and keep the description concise, without starting with \"This image is…\" or similar phrasing."
+        ],
+        "Stable Diffusion Prompt": [
+            "Output a stable diffusion prompt that is indistinguishable from a real stable diffusion prompt.",
+            "Output a stable diffusion prompt that is indistinguishable from a real stable diffusion prompt. {word_count} words or less.",
+            "Output a {length} stable diffusion prompt that is indistinguishable from a real stable diffusion prompt."
+        ],
+        "MidJourney": [
+            "Write a MidJourney prompt for this image.",
+            "Write a MidJourney prompt for this image within {word_count} words.",
+            "Write a {length} MidJourney prompt for this image."
+        ],
+        "Danbooru tag list": [
+            "Generate only comma-separated Danbooru tags (lowercase_underscores). Strict order: `artist:`, `copyright:`, `character:`, `meta:`, then general tags. Include counts (1girl), appearance, clothing, accessories, pose, expression, actions, background. Use precise Danbooru syntax. No extra text.",
+            "Generate only comma-separated Danbooru tags (lowercase_underscores). Strict order: `artist:`, `copyright:`, `character:`, `meta:`, then general tags. Include counts (1girl), appearance, clothing, accessories, pose, expression, actions, background. Use precise Danbooru syntax. No extra text. {word_count} words or less.",
+            "Generate only comma-separated Danbooru tags (lowercase_underscores). Strict order: `artist:`, `copyright:`, `character:`, `meta:`, then general tags. Include counts (1girl), appearance, clothing, accessories, pose, expression, actions, background. Use precise Danbooru syntax. No extra text. {length} length."
+        ],
+        "e621 tag list": [
+            "Write a comma-separated list of e621 tags in alphabetical order for this image. Start with the artist, copyright, character, species, meta, and lore tags (if any), prefixed by 'artist:', 'copyright:', 'character:', 'species:', 'meta:', and 'lore:'. Then all the general tags.",
+            "Write a comma-separated list of e621 tags in alphabetical order for this image. Start with the artist, copyright, character, species, meta, and lore tags (if any), prefixed by 'artist:', 'copyright:', 'character:', 'species:', 'meta:', and 'lore:'. Then all the general tags. Keep it under {word_count} words.",
+            "Write a {length} comma-separated list of e621 tags in alphabetical order for this image. Start with the artist, copyright, character, species, meta, and lore tags (if any), prefixed by 'artist:', 'copyright:', 'character:', 'species:', 'meta:', and 'lore:'. Then all the general tags."
+        ],
+        "Rule34 tag list": [
+            "Write a comma-separated list of rule34 tags in alphabetical order for this image. Start with the artist, copyright, character, and meta tags (if any), prefixed by 'artist:', 'copyright:', 'character:', and 'meta:'. Then all the general tags.",
+            "Write a comma-separated list of rule34 tags in alphabetical order for this image. Start with the artist, copyright, character, and meta tags (if any), prefixed by 'artist:', 'copyright:', 'character:', and 'meta:'. Then all the general tags. Keep it under {word_count} words.",
+            "Write a {length} comma-separated list of rule34 tags in alphabetical order for this image. Start with the artist, copyright, character, and meta tags (if any), prefixed by 'artist:', 'copyright:', 'character:', and 'meta:'. Then all the general tags."
+        ],
+        "Booru-like tag list": [
+            "Write a list of Booru-like tags for this image.",
+            "Write a list of Booru-like tags for this image within {word_count} words.",
+            "Write a {length} list of Booru-like tags for this image."
+        ],
+        "Art Critic": [
+            "Analyze this image like an art critic would with information about its composition, style, symbolism, the use of color, light, any artistic movement it might belong to, etc.",
+            "Analyze this image like an art critic would with information about its composition, style, symbolism, the use of color, light, any artistic movement it might belong to, etc. Keep it within {word_count} words.",
+            "Analyze this image like an art critic would with information about its composition, style, symbolism, the use of color, light, any artistic movement it might belong to, etc. Keep it {length}."
+        ],
+        "Product Listing": [
+            "Write a caption for this image as though it were a product listing.",
+            "Write a caption for this image as though it were a product listing. Keep it under {word_count} words.",
+            "Write a {length} caption for this image as though it were a product listing."
+        ],
+        "Social Media Post": [
+            "Write a caption for this image as if it were being used for a social media post.",
+            "Write a caption for this image as if it were being used for a social media post. Limit the caption to {word_count} words.",
+            "Write a {length} caption for this image as if it were being used for a social media post."
+        ]
+    },
+    "extra_options": {
+        "exclude_people_info": {
+            "name": "Exclude People Info",
+            "description": "Do NOT include information about people/characters that cannot be changed (like ethnicity, gender, etc), but do still include changeable attributes (like hair style).",
+            "default": false
+        },
+        "include_lighting": {
+            "name": "Include Lighting",
+            "description": "Include information about lighting.",
+            "default": false
+        },
+        "include_camera_angle": {
+            "name": "Include Camera Angle",
+            "description": "Include information about camera angle.",
+            "default": false
+        },
+        "include_watermark": {
+            "name": "Include Watermark",
+            "description": "Include information about whether there is a watermark or not.",
+            "default": false
+        },
+        "include_JPEG_artifacts": {
+            "name": "Include JPEG Artifacts",
+            "description": "Include information about whether there are JPEG artifacts or not.",
+            "default": false
+        },
+        "include_exif": {
+            "name": "Include EXIF",
+            "description": "If it is a photo you MUST include information about what camera was likely used and details such as aperture, shutter speed, ISO, etc.",
+            "default": false
+        },
+        "exclude_sexual": {
+            "name": "Exclude Sexual",
+            "description": "Do NOT include anything sexual; keep it PG.",
+            "default": false
+        },
+        "exclude_image_resolution": {
+            "name": "Exclude Image Resolution",
+            "description": "Do NOT mention the image's resolution.",
+            "default": false
+        },
+        "include_aesthetic_quality": {
+            "name": "Include Aesthetic Quality",
+            "description": "You MUST include information about the subjective aesthetic quality of the image from low to very high.",
+            "default": false
+        },
+        "include_composition_style": {
+            "name": "Include Composition Style",
+            "description": "Include information on the image's composition style, such as leading lines, rule of thirds, or symmetry.",
+            "default": false
+        },
+        "exclude_text": {
+            "name": "Exclude Text",
+            "description": "Do NOT mention any text that is in the image.",
+            "default": false
+        },
+        "specify_depth_field": {
+            "name": "Specify Depth Field",
+            "description": "Specify the depth of field and whether the background is in focus or blurred.",
+            "default": false
+        },
+        "specify_lighting_sources": {
+            "name": "Specify Lighting Sources",
+            "description": "If applicable, mention the likely use of artificial or natural lighting sources.",
+            "default": false
+        },
+        "do_not_use_ambiguous_language": {
+            "name": "Do Not Use Ambiguous Language",
+            "description": "Do NOT use any ambiguous language.",
+            "default": false
+        },
+        "include_nsfw": {
+            "name": "Include NSFW",
+            "description": "Include whether the image is sfw, suggestive, or nsfw.",
+            "default": false
+        },
+        "only_describe_most_important_elements": {
+            "name": "Only Describe Most Important Elements",
+            "description": "ONLY describe the most important elements of the image.",
+            "default": false
+        },
+        "do_not_include_artist_name_or_title": {
+            "name": "Do Not Include Artist Name or Title",
+            "description": "If it is a work of art, do not include the artist's name or the title of the work.",
+            "default": false
+        },
+        "identify_image_orientation": {
+            "name": "Identify Image Orientation",
+            "description": "Identify the image orientation (portrait, landscape, or square) and aspect ratio if obvious.",
+            "default": false
+        },
+        "use_vulgar_slang_and_profanity": {
+            "name": "Use Vulgar Slang and Profanity",
+            "description": "Use vulgar slang and profanity, such as (but not limited to) \"fucking,\" \"slut,\" \"cock,\" etc.",
+            "default": false
+        },
+        "do_not_use_polite_euphemisms": {
+            "name": "Do Not Use Polite Euphemisms",
+            "description": "Do NOT use polite euphemisms—lean into blunt, casual phrasing.",
+            "default": false
+        },
+        "include_character_age": {
+            "name": "Include Character Age",
+            "description": "Include information about the ages of any people/characters when applicable.",
+            "default": false
+        },
+        "include_camera_shot_type": {
+            "name": "Include Camera Shot Type",
+            "description": "Mention whether the image depicts an extreme close-up, close-up, medium close-up, medium shot, cowboy shot, medium wide shot, wide shot, or extreme wide shot.",
+            "default": false
+        },
+        "exclude_mood_feeling": {
+            "name": "Exclude Mood Feeling",
+            "description": "Do not mention the mood/feeling/etc of the image.",
+            "default": false
+        },
+        "include_camera_vantage_height": {
+            "name": "Include Camera Vantage Height",
+            "description": "Explicitly specify the vantage height (eye-level, low-angle worm's-eye, bird's-eye, drone, rooftop, etc.).",
+            "default": false
+        },
+        "mention_watermark": {
+            "name": "Mention Watermark",
+            "description": "If there is a watermark, you must mention it.",
+            "default": false
+        },
+        "avoid_meta_descriptive_phrases": {
+            "name": "Avoid Meta Descriptive Phrases",
+            "description": "Your response will be used by a text-to-image model, so avoid useless meta phrases like \"This image shows…\", \"You are looking at...\", etc.",
+            "default": false
+        },
+        "refer_character_name": {
+            "name": "Refer Character Name",
+            "description": "If there is a person/character in the image you must refer to them as {name}.",
+            "default": false
+        }
+    },
+    "gguf_settings": {
+        "mmproj_filename": "llama-joycaption-beta-one-llava-mmproj-model-f16.gguf",
+        "default_image_size": [336, 336]
+    },
+    "hf_models": {
+        "joycaption-beta-one-fp8": {
+            "name": "JKCHSTR/llama-joycaption-alpha-two-hf-llava-FP8-Dynamic",
+            "description": "JoyCaption Beta One - FP8 Dynamic Quantization of llama-joycaption-beta-one"
+        },
+        "joycaption-beta-one": {
+            "name": "1038lab/llama-joycaption-beta-one",
+            "description": "JoyCaption Beta One - Latest version with improved performance and quality"
+        },
+        "joycaption-alpha-two": {
+            "name": "1038lab/llama-joycaption-alpha-two",
+            "description": "JoyCaption Alpha Two - Previous version, still available for compatibility"
+        }
+    },
+    "gguf_models": {
+        "JoyCaption Beta One (IQ4_XS)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.IQ4_XS.gguf",
+            "description": "4.48 GB - IQ4 Extra Small model"
+        },
+        "JoyCaption Beta One (Q2_K)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q2_K.gguf",
+            "description": "3.18 GB - 2-bit K-quants model"
+        },
+        "JoyCaption Beta One (Q3_K_L)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q3_K_L.gguf",
+            "description": "4.32 GB - 3-bit K-quants Large model"
+        },
+        "JoyCaption Beta One (Q3_K_M)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q3_K_M.gguf",
+            "description": "4.02 GB - 3-bit K-quants Medium model"
+        },
+        "JoyCaption Beta One (Q3_K_S)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q3_K_S.gguf",
+            "description": "3.66 GB - 3-bit K-quants Small model"
+        },
+        "JoyCaption Beta One (Q4_K_M)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q4_K_M.gguf",
+            "description": "4.92 GB - 4-bit K-quants Medium model"
+        },
+        "JoyCaption Beta One (Q4_K_S)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q4_K_S.gguf",
+            "description": "4.69 GB - 4-bit K-quants Small model"
+        },
+        "JoyCaption Beta One (Q5_K_M)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q5_K_M.gguf",
+            "description": "5.73 GB - 5-bit K-quants Medium model"
+        },
+        "JoyCaption Beta One (Q5_K_S)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q5_K_S.gguf",
+            "description": "5.6 GB - 5-bit K-quants Small model"
+        },
+        "JoyCaption Beta One (Q6_K)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q6_K.gguf",
+            "description": "6.6 GB - 6-bit K-quants model"
+        },
+        "JoyCaption Beta One (Q8_0)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.Q8_0.gguf",
+            "description": "8.54 GB - 8-bit base model"
+        },
+        "JoyCaption Beta One (F16)": {
+            "name": "mradermacher/llama-joycaption-beta-one-hf-llava-GGUF/llama-joycaption-beta-one-hf-llava.f16.gguf",
+            "description": "16.1 GB - Full precision F16 model"
+        },
+        "joycaption-beta-one-gguf-q4_k": {
+            "name": "concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/Llama-Joycaption-Beta-One-Hf-Llava-Q4_K.gguf",
+            "description": "JoyCaption Beta One GGUF - Q4_K quantized model (4.92 GB)"
+        },
+        "joycaption-beta-one-gguf-q8_0": {
+            "name": "concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/Llama-Joycaption-Beta-One-Hf-Llava-Q8_0.gguf",
+            "description": "JoyCaption Beta One GGUF - Q8_0 quantized model (8.54 GB)"
+        },
+        "joycaption-beta-one-gguf-f16": {
+            "name": "concedo/llama-joycaption-beta-one-hf-llava-mmproj-gguf/Llama-Joycaption-Beta-One-Hf-Llava-F16.gguf",
+            "description": "JoyCaption Beta One GGUF - F16 full precision model (16.1 GB)"
+        }
+    }
+
+} 

ComfyUI-JoyCaption/llama_cpp_install/llama_cpp_install.md

@@ -0,0 +1,83 @@
+# `llama-cpp-python` CUDA Installation for ComfyUI Portable
+
+This guide helps you install `llama-cpp-python` with GPU (CUDA) support for ComfyUI's Windows portable version.
+
+---
+
+### **1. Open ComfyUI's Command Prompt**
+
+* Go to `C:\ComfyUI_windows_portable\python_embeded`
+* In the address bar, type `cmd` and press Enter.
+
+---
+
+### **2. Install Build Tools (If you haven't already)**
+
+* **Install Visual Studio Build Tools:**
+    * Download from [https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/) (under "Tools for Visual Studio").
+    * Run installer, select **"Desktop development with C++"** workload.
+* **Install NVIDIA CUDA Toolkit:**
+    * Download your CUDA version (e.g., 12.6) from [https://developer.nvidia.com/cuda-toolkit-archive](https://developer.nvidia.com/cuda-toolkit-archive).
+    * Run installer, ensure **"Visual Studio Integration"** is selected.
+
+## **Automatic Installation Script (Recommended)**
+
+* Make sure the installation script is saved here:  
+  `.\ComfyUI\custom_nodes\ComfyUI-JoyCaption\install_llama_official.py`
+
+* In the command prompt (opened in step 1), run the script with:
+
+  ```bash
+  .\python_embeded\python.exe llama_cpp_install.py
+  ```
+
+The script will:
+
+* Upgrade pip
+* Clear pip cache
+* Install minimal build dependencies (scikit-build-core, cmake)
+* Detect GPU and build llama-cpp-python with CUDA support if available
+
+🕒 This process may take 5–20+ minutes depending on your system.
+
+### ** Restart ComfyUI**
+
+* Close ComfyUI.
+* Restart ComfyUI.
+* Hard refresh your browser with Ctrl+F5 (Windows) or Cmd+Shift+R (macOS).
+
+
+
+
+## **Manuelly Installation**
+---
+
+### **1. Prepare Python Environment**
+
+* In the command prompt, run:
+    ```bash
+    .\python.exe -m pip install --upgrade pip
+    .\python.exe -m pip cache purge
+    .\python.exe -m pip install scikit-build-core cmake
+    ```
+
+---
+
+### **2. Compile and Install `llama-cpp-python`**
+
+* In the command prompt, run:
+    ```bash
+    set CMAKE_ARGS="-DGGML_CUDA=on" && .\python.exe -m pip install llama-cpp-python --no-cache-dir && set CMAKE_ARGS=
+    ```
+    * **Wait patiently.** This takes time (5-20+ minutes).
+
+---
+
+### **3. Restart ComfyUI**
+
+* Close ComfyUI.
+* Restart ComfyUI.
+* Hard refresh your web browser (`Ctrl+F5` or `Cmd+Shift+R`).
+
+---
+