Nunchaku实战教程：从FLUX.1到Qwen-Image的完整应用案例

【免费下载链接】nunchaku [ICLR2025] SVDQuant: Absorbing Outliers by Low-Rank Components for 4-Bit Diffusion Models 项目地址: https://gitcode.com/gh_mirrors/nu/nunchaku

Nunchaku作为开源的AI绘图工具，基于SVDQuant技术实现了4位量化的扩散模型加速，支持FLUX.1和Qwen-Image等主流模型的高效部署。本文将通过实际案例演示如何快速上手Nunchaku，体验从文本生成图像到模型优化的全流程。

快速开始：环境搭建与项目部署

一键安装步骤

首先克隆项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/nu/nunchaku
cd nunchaku

项目提供了多种安装方式，推荐使用Python虚拟环境：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或在Windows上使用: venv\Scripts\activate
pip install -e .

必备依赖检查

确保系统已安装以下组件：

• Python 3.8+
• PyTorch 2.0+
• CUDA 11.7+（推荐）

详细依赖列表可查看项目根目录下的pyproject.toml文件。

FLUX.1模型实战：从文本到图像的魔法

核心功能展示

FLUX.1作为Nunchaku支持的旗舰模型，提供了文本生成图像（T2I）、图像修复（Fill）、深度控制（Depth）等多种能力。以下是使用FLUX.1-dev模型的基础示例：

from nunchaku.pipeline import FluxPipeline
import torch

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    torch_dtype=torch.bfloat16
)
pipe.to("cuda")

image = pipe(
    prompt="a cyberpunk cat wearing neon goggles",
    num_inference_steps=20
).images[0]
image.save("cyberpunk_cat.png")

量化加速效果对比

Nunchaku的SVDQuant技术显著提升了模型运行效率。通过INT4量化，FLUX.1模型在保持图像质量的同时，将推理时间从37.18秒（BF16精度）降至11.00秒，显存占用减少60%以上：

图：INT4量化（左）与BF16精度（右）的图像质量与推理速度对比，提示词为"a cyberpunk cat holding a huge neon sign that says 'SVDQuant is lite and fast', wearing fancy goggles and a black leather jacket"

实用功能扩展

项目提供了多种FLUX.1变体模型的应用示例：

• 图像修复：examples/flux.1-fill-dev.py
• 深度控制：examples/flux.1-depth-dev.py
• 快速生成：examples/flux.1-schnell.py（最快2秒出图）

Qwen-Image模型应用：多模态创作新体验

基础生成流程

Qwen-Image模型支持文本生成图像和图像编辑功能，以下是基础使用示例：

from nunchaku.pipeline import QwenImagePipeline
import torch

pipe = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image",
    torch_dtype=torch.bfloat16
)
pipe.to("cuda")

image = pipe(
    prompt="a futuristic cityscape at sunset",
    height=1024,
    width=1024
).images[0]
image.save("futuristic_city.png")

高级功能探索

Qwen-Image的图像编辑功能可实现局部修改和风格迁移，示例代码位于examples/v1/qwen-image-edit.py。结合ControlNet还能实现更精细的控制，相关案例见examples/v1/qwen-image-controlnet.py。

性能优化与高级配置

缓存加速技术

Nunchaku提供多级缓存机制，通过缓存文本编码器输出和中间特征，显著提升重复生成效率：

# 启用文本编码器缓存
pipe.enable_teacache(batch_size=4)
# 启用特征缓存
pipe.enable_fbcache()

相关实现代码可参考nunchaku/caching/teacache.py和nunchaku/caching/fbcache.py。

显存优化策略

对于显存有限的设备，可采用模型分片和梯度检查点技术：

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    torch_dtype=torch.bfloat16,
    device_map="auto",  # 自动分配模型到CPU/GPU
    gradient_checkpointing=True
)

常见问题与解决方案

模型加载失败

若遇到模型下载问题，可手动下载模型文件并指定本地路径：

pipe = FluxPipeline.from_pretrained("./local/FLUX.1-dev")

推理速度过慢

确保已启用CUDA加速和量化功能：

# 启用INT4量化
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    torch_dtype=torch.bfloat16,
    quantize=True  # 启用SVDQuant量化
)

图像质量问题

尝试调整推理步数和引导尺度：

image = pipe(
    prompt="...",
    num_inference_steps=30,  # 增加步数提升质量
    guidance_scale=7.5       # 调整引导强度
).images[0]

总结与下一步学习

通过本教程，你已掌握Nunchaku的核心功能和应用方法。建议进一步探索：

• LoRA模型应用：nunchaku/lora/flux/目录下的LoRA加载与组合工具
• 性能测试：tests/flux/test_flux_speed.py中的基准测试代码
• Web界面部署：各模型目录下的run_gradio.py文件可快速启动交互界面

Nunchaku持续更新中，更多功能请关注项目docs/目录下的官方文档。

【免费下载链接】nunchaku [ICLR2025] SVDQuant: Absorbing Outliers by Low-Rank Components for 4-Bit Diffusion Models 项目地址: https://gitcode.com/gh_mirrors/nu/nunchaku