Nunchaku 1.3.0 for Python3.14.x＆α

転生chu☆ 鞘師里保

2026年7月11日、Pytorch2.13.0+cu132に合わせて記述の修正を行いました。

Nunchaku1.3.0 for Python3.14.x

whl for Windows

以下公式のpython3.13用whlが公開されてはいますが、現時点においてcu132環境でビルドされておらず、実質的には使えません。

只、後述しますが、cu132用は自作が可能です。

InsightFaceは、後述しますが紆余曲折の末に何とかした(あるいはして頂いた)…のですが、MediaPipeは今の処どうにもなっていませんから…いずれも基礎設計が古いので仕方ない。

Nunchakuは「これから」の技術なので、できればまともに使いたい訳でして、わざわざ「これ」の為に、ここまで苦労して構築したPython3.13.x用ComfyUIを捨てられねえっつの。

Nunchakuが使用しているINT4という量子化形式は、昨年ForgeがFlux1に対応した時に、かの「天才」lllyasviel氏がいち早く、この世界で使用して一時注目は集めたのですが、

結局その後、この世界で主流を占めた量子化フォーマットはGGUF形式で、ずっと来た訳です。

…

Fujitu

ただ、一昨日、日本の富士通が何気に凄い技術を発表しました。以下、GPT-5に総括させています。

額面通りに受け取るならば、INT4処かINT1で、オリジナルに対する89％の精度…と言っている訳ですから、これは仮にComfyUIの世界で持ち込まれたら凄い事になります。あくまでも、「持ち込まれたら」ですが。

HuggingFace上には結果の何がしかは公開されるようなので、もしそうなったらいつもの如く「世界最高レベルの高速化御用達中国勢」が、色々応用して何とかしてくれそうな気もします。
(Nunchakuも、論文制作者の名前はどう見ても中国系である)

ハード的な制約に縛られている中国勢は、この手の高速化には必死…ですしね。(ハード的な制約と言うなら日本とて同様で、日本勢が必死になるべきなのだが、やっと富士通から出た)

…

その前に、Nunchakuです。

当初、余りやる気にならなかったのですが、QIの余りの重さにいい加減切れまして(非量子化GGUFであっても、専用VRAM消費量は16GB未満に収まるにも関わらず)、で更にはGPT-5曰く、どうもBlackwell環境では相当有利に動作できるようなので、導入しました。

SVDQ-FP4 on Blackwell

…

いい質問です 👍
SVDQ-FP4（Singular Value Decomposition Quantization – FP4）は、従来の INT4 量子化 とは発想も内部表現も異なります。順に整理しますね。

1. INT4（従来の 4bit 量子化）

特徴

• 整数形式（INT4 = -8 〜 +7 の 4bit 整数表現）。

• 重みやアクティベーションを「整数スケール + スケール係数」で近似する。

  1. W ≈ (int4_values) * scale

• メリット：実装が単純、ハードウェアサポート豊富。

• デメリット：

  • ダイナミックレンジが狭い → 情報損失が目立ちやすい。

  • スケーリングでの近似なので、精度低下しやすい。

  • 大規模モデルでは特に「小さな差」が蓄積して精度が落ちる。

2. SVDQ-FP4（SVD 分解ベースの FP4 量子化）

発想

• 「単に 4bit に丸める」のではなく、重み行列を SVD（特異値分解）して低ランク近似した上で、各成分を FP4 形式で表現。

  1. W ≈ U * Σ * V^T

  2. ここで Σ の特異値を FP4 で格納し、U/V はランク r で近似。

FP4（4bit 浮動小数）

• NVFP4 互換の 4bit 浮動小数表現。

  • 符号ビット：1

  • 指数ビット：2〜3

  • 仮数ビット：残り

• INT4 と違い、指数があるので ダイナミックレンジが広い。

メリット

• 単純な INT4 よりも 再構成誤差が小さい。

• r（ランク）を増やすと精度を自在に調整可能（r32, r128 など）。

• Blackwell 世代 GPU の FP4 TensorCore に最適化されており、ネイティブ実行可能。

3. 例：誤差イメージ

• INT4：
  重みを「定規でざっくり切りそろえる」ような感じ → 大事な細かい特徴が欠けやすい。

• SVDQ-FP4：
  重みを「圧縮してから、重要成分だけを FP4 で正確に記録」する感じ → 情報保持率が高い。

✅ 結論：
SVDQ-FP4 は INT4 とは全く別物で、
*「FP4 という表現力のある 4bit 浮動小数」＋「SVD による低ランク近似」
を組み合わせることで、精度を維持しつつ大幅圧縮・高速化を実現しています。

SVDQ-FP4 r128 と FP16/BF16 の数値的差整理

Blackwell 世代 GPU 上での SVDQ-FP4 r128 とフルサイズ FP16 / BF16 の比較を、なるべく数値化してまとめます。

1. 比較の評価指標

量子化・精度評価には以下の指標があります：

• PSNR / SSIM：画像生成での画質評価

• Cosine Similarity：埋め込みベクトルの一致度

• Weight Reconstruction Error (MSE, L2)：重みそのものの誤差

SVDQuant は 重みの再構成誤差と推論出力差の両方を抑える設計です。

2. 公開されている定量的結果（一般傾向）

量子化形式 Rank MSE（重み再構成） SSIM（生成結果） 説明 INT4 r32 1e-2 0.95 小さな文字や微細テクスチャで劣化が目立つことあり INT4 r128 1e-3 0.98 再構成精度が向上、見た目で差はほとんどわからない SVDQ-FP4 r128 1e-4〜数e-4 0.99+ フル精度との差は統計的に誤差レベル、人間の目ではほぼ判別不能

3. FP16 / BF16 との違い

データ型 説明 差の目安 FP16 標準的半精度 — BF16 指数部広く丸め誤差やや大 出力差ほぼなし SVDQ-FP4 r128 4bit 量子化＋SVD 低ランク近似 PSNR 40〜50dB、Cosine Similarity 0.999 近く、実用上はほぼ差なし

4. 実用レベルでの差

• 見える差が出るケース

  • 小さな文字やロゴ、微細なグラデーション

  • それ以外は目視でほぼ判別不能

• VRAM / 計算効率

  • r128 SVDQ-FP4：フル精度の約 1/3〜1/4 で VRAM 消費

  • 推論速度：FP16 比で 2.5〜3倍

✅ まとめ

• SVDQ-FP4 r128 は「数値的に FP16/BF16 とほぼ同等」

  • MSE：1e-4〜1e-3

  • SSIM：0.99以上

  • Cosine similarity：0.999近く

• 実際の生成で差が分かるのは、微細テクスチャや小文字レベル

• Blackwell 環境では r128 SVDQ-FP4 が最も実用的・高速・VRAM効率良し

…

Archive of how to build a whl of Nunchaku on Python3.14.x for Windows

前述の如く現在、公式のWindows用whlが存在しますが、cu132用が存在しない為、自力ビルドの必要があります。尚、以下で公開しています。

�� 前提条件

必要なソフトウェア

• Visual Studio 2022 (Community/Professional/Enterprise)

• CUDA 13.2 (NVIDIA GPU Computing Toolkit)

• Python 3.14

• PyTorch 2.12.0+cu132

• Windows 11 (x64)

重要な注意点

⚠️ 管理者権限必須 - 必ず管理者権限でx64 Native Tools Command Prompt for VS2022を起動してください
⚠️ PowerShellは使用禁止 - 通常のコマンドプロンプトでも失敗する可能性があります

🚀 手順

今回の私の環境に合わせた記述です。フォルダ等は、各自の環境に合わせてください。

Step 1: 管理者権限でコマンドプロンプトを起動

1. スタートメニュー → Visual Studio 2022 → x64 Native Tools Command Prompt for VS 2022を右クリック

2. 管理者として実行を選択

3. これが重要：通常のコマンドプロンプトではビルドが失敗する可能性があります

Step 2: 作業ディレクトリの準備

mkdir D:\nu

cd D:\nu

Step 3: Python 3.14仮想環境の作成

C:\Users\ussoe\AppData\Local\Programs\Python\Python314\python.exe -m venv venv

venv\Scripts\activate

Step 4: PyTorchのインストール

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu132

Step 5: ビルド依存関係のインストール(ここだけは、Powershellで一括インストールを行う方が効率的)

pip install numpy
pip install ninja
pip install wheel
pip install setuptools
pip install pybind11
pip install diffusers>=0.35.1
pip install transformers>=4.53.3
pip install accelerate>=1.9.0
pip install accelerate>=1.9.0
pip install sentencepiece
pip install protobuf
pip install huggingface_hub>=0.34
pip install peft>=0.17
pip install einops

Step 6: nunchakuリポジトリのクローン

git clone https://github.com/nunchaku-tech/nunchaku.git
cd nunchaku

必要次第で、ここでgit checkoutとブランチ指定を入れます。

git submodule update --init --recursive

セットアップファイルの修正

問題

wheelファイルを作成してインストールした際に、作業フォルダへの絶対パスリンクが埋め込まれてしまい、インストール後も作業フォルダに依存する形になっていた。

解決策

wheelファイルをビルドする際に、環境変数を設定してデバッグ情報の生成を抑制し、絶対パスの埋め込みを防ぐ。

修正ファイル1: `nunchaku/setup.py`

修正箇所1: NVCC_FLAGSの条件分岐追加（124行目付近）

`NVCC_FLAGS`リストの定義直後、`for target in sm_targets:`の直前に追加:

if os.getenv("NUNCHAKU_BUILD_WHEELS", "0") == "0":
    NVCC_FLAGS.append("--generate-line-info")

コンテキスト（前後のコード）:

    NVCC_FLAGS = [
        "-DENABLE_BF16=1",
        "-DBUILD_NUNCHAKU=1",
        "-g",
        "-std=c++20",
        "-UNDEBUG",
        "-Xcudafe",
        "--diag_suppress=20208",
        *cond("-G"),
        "-U__CUDA_NO_HALF_OPERATORS__",
        "-U__CUDA_NO_HALF_CONVERSIONS__",
        "-U__CUDA_NO_HALF2_OPERATORS__",
        "-U__CUDA_NO_HALF2_CONVERSIONS__",
        "-U__CUDA_NO_BFLOAT16_OPERATORS__",
        "-U__CUDA_NO_BFLOAT16_CONVERSIONS__",
        "-U__CUDA_NO_BFLOAT162_OPERATORS__",
        "-U__CUDA_NO_BFLOAT162_CONVERSIONS__",
        f"--threads={len(sm_targets)}",
        "--expt-relaxed-constexpr",
        "--expt-extended-lambda",
        "--ptxas-options=--allow-expensive-optimizations=true",
    ]

    # ↓↓↓ ここに追加 ↓↓↓
    if os.getenv("NUNCHAKU_BUILD_WHEELS", "0") == "0":
        NVCC_FLAGS.append("--generate-line-info")
    # ↑↑↑ ここまで追加 ↑↑↑

    for target in sm_targets:
        NVCC_FLAGS += ["-gencode", f"arch=compute_{target},code=sm_{target}"]

解説:

• 環境変数`NUNCHAKU_BUILD_WHEELS`が`"0"`の場合のみ`--generate-line-info`を追加

• このフラグはCUDAデバッグ情報を生成し、その情報に作業フォルダの絶対パスが含まれる

• 環境変数を`"1"`に設定することでこのフラグをスキップし、絶対パスの埋め込みを防ぐ

修正箇所2: 環境変数の設定とsetuptoolsの引数追加（最後の部分）

`setuptools.setup()`の直前と引数内を修正:

修正前:

    setuptools.setup(
        name="nunchaku",
        version=version,
        packages=setuptools.find_packages(),
        ext_modules=[nunchaku_extension],
        cmdclass={"build_ext": CustomBuildExtension},
    )

修正後:

    # Set NUNCHAKU_BUILD_WHEELS=1 to avoid embedding absolute paths in wheel
    os.environ.setdefault("NUNCHAKU_BUILD_WHEELS", "1")

    setuptools.setup(
        name="nunchaku",
        version=version,
        packages=setuptools.find_packages(),
        ext_modules=[nunchaku_extension],
        cmdclass={"build_ext": CustomBuildExtension},
        package_data={
            "nunchaku": ["csrc/*.cpp", "csrc/*.h"],
        },
        include_package_data=True,
    )

解説:

• `os.environ.setdefault("NUNCHAKU_BUILD_WHEELS", "1")`で環境変数を設定

• これにより修正箇所1の条件分岐で`--generate-line-info`が追加されない

• `package_data`と`include_package_data=True`でパッケージデータを適切に含める

修正ファイル2: `nunchaku/pyproject.toml`

修正箇所: tool.setuptoolsセクションの追加

`[build-system]`セクションの後、`[project]`セクションの前に追加:

修正前:

[build-system]
build-backend = "setuptools.build_meta"

requires = [
  "ninja",
  "setuptools",
  "torch>=2.5",
  "wheel",
]

[project]
name = "nunchaku"

修正後:

[build-system]
build-backend = "setuptools.build_meta"

requires = [
  "ninja",
  "setuptools",
  "torch>=2.5",
  "wheel",
]

[tool.setuptools]
include-package-data = true

[project]
name = "nunchaku"

解説:

• `[tool.setuptools]`セクションを追加

• `include-package-data = true`で`MANIFEST.in`で指定されたファイルをwheelに含める

これで作業フォルダへの絶対パスリンクを含まないwheelファイルが`dist/`ディレクトリに作成される。

…

Step 7: 環境変数の設定（一行ずつ実行）

set LIB=C:\Users\ussoe\AppData\Local\Programs\Python\Python314\libs;%LIB%

set INCLUDE=C:\Users\ussoe\AppData\Local\Programs\Python\Python314\include;%INCLUDE%

set CUDA_HOME=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.2

set DISTUTILS_USE_SDK=1

set TORCH_CUDA_ARCH_LIST=8.9;9.0;12.0;12.1

set MAX_JOBS=4

set NUNCHAKU_INSTALL_MODE=ALL

Step 8: ビルドの実行

python setup.py build_ext --inplace

Step 9: whlファイルの作成

python setup.py bdist_wheel

Step 10: ComfyUI環境へのインストール

D:\USERFILES\ComfyUI\python_embeded\python.exe -m pip install "D:\nu\nunchaku\dist\nunchaku-1.0.0+torch2.8-cp313-cp313-win_amd64.whl"

✅ 成功時の出力例

running build_ext
building 'nunchaku._C' extension
creating build\temp.win-amd64-3.13\Release
...
copying build\lib.win-amd64-cpython-313\nunchaku\_C.cp313-win_amd64.pyd -> nunchaku

📁 生成されるファイル

• `dist/` フォルダ内に `.whl` ファイルが生成されます

• 例: `nunchaku-1.0.0+torch2.9-cp313-cp313-win_amd64.whl`

❌ よくあるエラーと解決方法

エラー1: "Microsoft Visual C++ 14.0 is required"

原因: 環境変数が正しく設定されていない
解決方法: 上記の環境変数を一行ずつ再設定

エラー2: "Unable to find vcvarsall.bat"

原因: PowerShellまたは通常のコマンドプロンプトを使用している
解決方法: x64 Native Tools Command Prompt for VS 2022を管理者権限で使用

エラー3: "CUDA_HOME not found"

原因: CUDAのインストールパスが正しくない
解決方法: CUDAのインストールパスを確認し、環境変数を再設定

エラー4: "Permission denied"

原因: 管理者権限で実行していない
解決方法: コマンドプロンプトを管理者権限で再起動

エラー5: "Submodule initialization failed"

原因: サブモジュールの初期化を忘れている
解決方法: `git submodule update --init --recursive`を実行

�� 重要な注意事項

1. 管理者権限必須: 必ず管理者権限でx64 Native Tools Command Prompt for VS2022を起動

2. 一行ずつ実行: 環境変数は必ず一行ずつ設定してください

3. ビルド時間: ビルドには時間がかかります（数十分〜1時間程度）

4. NumPy警告: ビルド中はNumPyの警告が出る場合がありますが、正常にビルドされます

5. サブモジュール: サブモジュールの初期化を忘れずに実行してください

🎯 最終確認

ビルドが成功したら、以下のコマンドでwhlファイルを確認できます：

dir dist\*.whl

これで、Python 3.14用のnunchakuパッケージが正常に作成・インストールされ、ComfyUI-nunchakuが使用可能になります！

InsightFace built on Python 3.14

InsightFaceに関しても2026年6月11日現在、公式版は存在しないものの、完全に動作するwhlの作成に成功した為、、Windows版Python3.14用whlは、以下で公開しております。