Comfy Quants

Comfy Quants is an offline quantization toolkit for building ComfyUI-loadable model checkpoints from local model weights. Start by choosing the quantization format you want to produce, then open that format guide for supported model-family commands and examples.

中文说明见：中文说明。

Quick start

Install from a local checkout:

git clone https://github.com/Comfy-Org/comfy-quants.git
cd comfy-quants
pip install -e .

Check the CLI:

comfy-quants --help

Typical workflow:

1. choose an output format from Quantization formats;
2. open the linked format guide;
3. pick the model-family export command listed in that guide;
4. run the export and inspect the produced .safetensors artifact;
5. copy or symlink the artifact into the target ComfyUI model path and load it with a compatible loader.

Source-tree equivalent:

PYTHONPATH=src python -m comfy_quants.cli.main --help

Quantization formats

Each format guide links to the model-family flows currently implemented for that format. CLI syntax is summarized in docs/cli.md, and the full documentation index is docs/README.md.

Public names

How it fits with ComfyUI

Comfy Quants runs quantization and checkpoint export outside ComfyUI, then writes artifacts for ComfyUI-compatible loaders. A typical workflow is:

1. prepare the source model and calibration data locally;
2. run the selected comfy-quants export flow;
3. copy or symlink the produced .safetensors file into the target ComfyUI model path;
4. load the checkpoint in ComfyUI for sampling and image validation.

If you want in-ComfyUI quantization nodes, build them as a separate custom-node project and call this package through its CLI or Python API. This keeps the export library reusable while still allowing downstream UI/workflow integrations.

Repository layout

src/comfy_quants/
├── cli/              # command entrypoints
├── sdk/              # Python API surface
├── core/             # schemas and domain objects
├── model_adapters/   # model-family tensor contracts and selection rules
├── algorithms/       # quantization algorithms and planners
├── formats/          # reusable storage formats
├── backends/         # safetensors writers, importers, and export pipelines
├── calibration/      # calibration manifests and reducers
├── registry/         # local registry
├── validation/       # artifact reports and checks
└── utils/            # JSON, hashing, and system helpers

Architecture details: docs/architecture.md.

Test

python -m pytest tests/unit -q

中文说明

Comfy Quants 是一个离线量化工具库，用于把本地模型权重量化并导出为 ComfyUI 可以加载的模型 checkpoint。使用时先选择要产出的量化格式，再进入 对应格式文档查看已经支持的模型家族命令和示例。

快速开始

从本地源码安装：

git clone https://github.com/Comfy-Org/comfy-quants.git
cd comfy-quants
pip install -e .

查看 CLI：

comfy-quants --help

常见流程：

1. 从 量化格式 中选择输出格式；
2. 打开对应格式文档；
3. 在格式文档中选择已经支持的模型家族导出命令；
4. 运行导出，并检查产出的 .safetensors artifact；
5. 将 artifact 复制或软链到目标 ComfyUI 模型目录，并使用兼容 loader 加载。

源码树运行方式：

PYTHONPATH=src python -m comfy_quants.cli.main --help

量化格式

每个格式文档会继续链接到该格式当前支持的模型家族流程。CLI 语法见 docs/cli.md，完整文档索引见 docs/README.md。

公开命名

和 ComfyUI 怎么配合

Comfy Quants 在 ComfyUI 外完成量化和 checkpoint 导出，输出文件面向 ComfyUI-compatible loader。常见流程是：

1. 在本地准备源模型和校准数据；
2. 运行选定的 comfy-quants 导出流程；
3. 将产出的 .safetensors 文件复制或软链到目标 ComfyUI 模型目录；
4. 在 ComfyUI 中加载 checkpoint，进行采样和出图验证。

如果需要在 ComfyUI 里通过节点执行量化，可以在独立 custom-node 项目中依赖 本包，并调用本包的 CLI 或 Python API。这样量化导出能力可以复用，UI / workflow 集成也可以独立迭代。

仓库结构

src/comfy_quants/
├── cli/              # 命令入口
├── sdk/              # Python API
├── core/             # schema 和领域对象
├── model_adapters/   # 模型族 tensor contract 与层选择规则
├── algorithms/       # 量化算法与 planner
├── formats/          # 可复用存储格式
├── backends/         # safetensors writer、importer、export pipeline
├── calibration/      # 校准 manifest 与统计 reducer
├── registry/         # 本地 registry
├── validation/       # artifact 检查与报告
└── utils/            # JSON、hash、系统工具

架构说明见：docs/architecture.md。

测试

python -m pytest tests/unit -q