Qwen2VL-Flux：统一图像与文本引导的可控图像生成

本仓库包含一个强大的图像生成模型，它结合了Stable Diffusion的能力与多模态理解功能。该模型可以使用文本和图像输入来生成、修改和转换图像。

此实现采用Qwen2VL作为视觉-语言模型以增强多模态理解能力，并将其与Flux架构集成。它还支持ControlNet功能，包括深度估计和线条检测，以便更精确地控制图像生成。

有关技术细节，请参阅我们的技术报告。

模型架构

Flux模型通过用视觉-语言模型（Qwen2VL）替换传统的文本编码器来增强Stable Diffusion，从而实现更出色的多模态理解和生成：

关键架构特性：

• 视觉-语言理解：利用Qwen2VL实现卓越的图像和文本理解能力
• 增强的控制：集成ControlNet以提供精确的结构引导
• 灵活的流程：支持多种生成模式，包括变体生成、图生图和修复填充

特性

• 多种生成模式：

  • variation：生成输入图像的变体
  • img2img：基于参考图像转换图像
  • inpaint：使用掩码进行智能图像修复
  • controlnet：通过结构引导进行精确图像生成
  • controlnet-inpaint：结合ControlNet引导与修复填充

• 多模态理解：

  • 先进的文本到图像能力
  • 图像到图像转换
  • 视觉参考理解

• ControlNet集成：

  • 线条检测引导
  • 深度感知生成
  • 可调节的控制强度

• 高级特性：

  • 注目机制用于聚焦生成
  • 可自定义宽高比
  • 批量图像生成
  • Turbo模式以加快推理速度

需求

• Python 3.8或更高版本
• 支持CUDA的GPU（推荐）
• PyTorch 2.4.1或更高版本
• 48GB及以上显存

环境设置

该模型需要以下主要依赖项：

• PyTorch >= 2.4.1
• Transformers 4.45.0
• Diffusers 0.30.0
• Accelerate 0.33.0

完整的依赖列表请参见requirements.txt。

安装

1. 克隆本仓库：

git clone https://github.com/yourusername/flux-model.git
cd flux-model

2. 创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

3. 安装依赖项：

pip install -r requirements.txt

4. 下载模型检查点：

运行该模型需要若干检查点文件。请按照以下步骤操作：

a) 主要模型文件：

• 从Hugging Face下载Qwen2VL-Flux模型文件
• 将其放置在checkpoints目录中，目录结构如下：

  checkpoints/
  ├── flux/              # 主Flux模型文件
  ├── qwen2-vl/          # Qwen2VL模型文件
  

b) 对于ControlNet功能（可选）：

• depth-anything-v2
• mistoline
• segment-anything-v2

5. 配置模型路径：

修改model.py中的以下路径以匹配您的设置：

FLUX_MODEL_PATH = "/checkpoints/flux"
CONTROLNET_MODEL_PATH = "/checkpoints/controlnet"
QWEN2VL_MODEL_PATH = "/checkpoints/qwen2-vl"
DEPTHANYTHING_MODEL_PATH = "/checkpoints/depth-anything-v2"
MISTOLINE_MODEL_PATH = "/checkpoints/anyline"
SAM2_MODEL_PATH = "/checkpoints/segment-anything-v2"

使用方法

基本命令结构

python main.py --mode <模式> --input_image <路径> [其他选项]

###常用选项

• --mode：生成模式（variation/img2img/inpaint/controlnet/controlnet-inpaint）
• --input_image：输入图像的路径
• --prompt：指导生成的文本提示
• --output_dir：保存生成图像的目录（默认为‘outputs’）
• --image_count：生成图像的数量（默认为1）
• --aspect_ratio：输出图像的宽高比（1:1/16:9/9:16/2.4:1/3:4/4:3）
• --steps：推理步数（默认为28）
• --guidance_scale：生成引导尺度（默认为3.5）
• --device：计算设备（cuda/cpu）

环境配置

可以通过两种方式配置模型路径：

1. 默认路径：将所有模型文件放置在项目根目录下的checkpoints目录中
2. 自定义路径：设置CHECKPOINT_DIR环境变量指向您希望的位置

预期目录结构如下：

checkpoints/
├── flux/              # 主Flux模型文件
├── qwen2-vl/          # Qwen2VL模型文件
├── controlnet/        # ControlNet模型（可选）
├── depth-anything-v2/ # 深度估计模型（可选）
├── anyline/          # 线条检测模型（可选）
└── segment-anything-2/ # SAM2模型（可选）

模型加载优化

该模型实现了智能加载——仅加载完成特定任务所需的组件：

• 基本生成仅加载核心模型
• ControlNet功能仅在使用ControlNet模式时加载
• 深度和线条检测模型仅在明确请求这些功能时加载
• SAM2仅在执行修复填充任务时加载。

示例

1. 基础图像变体（最小化加载）

python main.py --mode variation \
               --input_image path/to/image.jpg \
               --prompt "一幅美丽的风景" \
               --image_count 4

2. 图生图转换

python main.py --mode img2img \
               --input_image source.jpg \
               --reference_image target.jpg \
               --prompt "xxxxxxxxxxxx" \
               --denoise_strength 0.75

3. 带掩码的修复填充

python main.py --mode inpaint \
               --input_image image.jpg \
               --mask_image mask.png \
               --prompt "用美丽的花朵填充"

4. 带有线条和深度引导的ControlNet

python main.py --mode controlnet \
               --input_image image.jpg \
               --line_mode \
               --depth_mode \
               --line_strength 0.4 \
               --depth_strength 0.2 \
               --prompt "xxxxxxxxxxxxxxxxxxxxx"

5. 自定义模型路径配置

# 使用环境变量指定模型位置
CHECKPOINT_DIR=/path/to/models python main.py \
               --mode variation \
               --input_image image.jpg \
               --prompt "xxxxxxxxxxxxxxxxxxxxxxxxx"

6. 内存优化的ControlNet使用

# 仅加载深度模型而不进行线条检测
python main.py --mode controlnet \
               --input_image image.jpg \
               --depth_mode \
               --depth_strength 0.3 \
               --prompt "xxxxxxxxxxxxxxxxxxxxxxxx"

# 仅加载线稿检测，不使用深度模型
python main.py --mode controlnet \
               --input_image image.jpg \
               --line_mode \
               --line_strength 0.4 \
               --prompt "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

7. 注意力聚焦生成

python main.py --mode variation \
               --input_image image.jpg \
               --center_x 0.5 \
               --center_y 0.5 \
               --radius 0.3 \
               --prompt "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

高级选项

• 注意力控制：

  • --center_x：注意力中心的 X 坐标（0-1）
  • --center_y：注意力中心的 Y 坐标（0-1）
  • --radius：注意力圆的半径（0-1）

• ControlNet 设置：

  • --line_mode：启用线稿检测
  • --depth_mode：启用深度感知
  • --line_strength：线稿引导强度（0-1）
  • --depth_strength：深度引导强度（0-1）

• 性能：

  • --turbo：启用更快的推理
  • --device：选择计算设备

模型架构

本模型通过用视觉-语言模型替换 T5-XXL 文本编码器，增强了 Stable Diffusion 架构，从而具备更出色的多模态理解和生成能力。该架构包括：

• 修改后的 Flux 主干网络
• 视觉-语言理解模块
• ControlNet 集成，用于结构引导
• 先进的注意力机制

技术细节

文档

如需全面了解模型架构、实现细节及技术创新，请参阅以下资源：

• 技术报告：详细说明模型架构、训练过程及实验结果
• 架构图：高分辨率版本的模型架构图
• Hugging Face 模型卡片：模型权重及其他技术细节

模型组件

• 核心模型：

  • Qwen2VL-Flux 主干网络
  • 修改后的 Stable Diffusion 流水线
  • 自定义注意力机制

• 附加组件（可选）：

  • Depth Anything V2（深度估计）
  • Mistoline（线稿检测）
  • Segment Anything V2（图像分割）

引用

如果您在研究中使用本模型，请引用我们的技术报告：

@misc{erwold-2024-qwen2vl-flux,
  title={Qwen2VL-Flux：统一图像与文本指导的可控图像生成},
  author={Pengqi Lu},
  year={2024},
  url={https://github.com/erwold/qwen2vl-flux}
}

致谢

• 基于 Stable Diffusion 架构
• 集成了 ControlNet 以增强可控性
• 使用了修改后的 Flux 模型组件

贡献

欢迎贡献！请随时提交 Pull Request。

Qwen2VL-Flux 快速上手指南

Qwen2VL-Flux 是一款强大的可控图像生成模型，它结合了 Stable Diffusion 的生成能力与 Qwen2VL 的多模态理解能力。该模型支持文本和图像双重输入，可实现图像变体生成、图生图、智能修复以及基于深度/线条的精确控制（ControlNet）。

环境准备

在开始之前，请确保您的系统满足以下硬件和软件要求：

• 操作系统: Linux / macOS / Windows
• Python: 3.8 或更高版本
• GPU: 推荐 NVIDIA CUDA 兼容显卡，显存需 48GB+
• 核心依赖:
  • PyTorch >= 2.4.1
  • Transformers 4.45.0
  • Diffusers 0.30.0
  • Accelerate 0.33.0

国内加速建议：安装依赖时建议使用国内镜像源以提升下载速度。 例如使用清华源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 克隆项目

git clone https://github.com/yourusername/flux-model.git
cd flux-model

2. 创建并激活虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
# Windows 用户请使用: venv\Scripts\activate

3. 安装依赖

pip install -r requirements.txt
# 国内用户推荐：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 下载模型权重

从 Hugging Face 下载所需模型文件，并按以下结构放置在 checkpoints 目录中：

checkpoints/
├── flux/              # Flux 主模型文件
├── qwen2-vl/          # Qwen2VL 模型文件
├── controlnet/        # ControlNet 模型 (可选)
├── depth-anything-v2/ # 深度估计模型 (可选)
├── anyline/           # 线条检测模型 (可选)
└── segment-anything-2/# SAM2 分割模型 (可选)

注意：模型具有智能加载机制，仅在使用特定功能（如 ControlNet 或修复）时才会加载对应的辅助模型。

5. 配置模型路径

编辑 model.py 文件，将路径变量修改为您本地的实际路径：

FLUX_MODEL_PATH = "/checkpoints/flux"
CONTROLNET_MODEL_PATH = "/checkpoints/controlnet"
QWEN2VL_MODEL_PATH = "/checkpoints/qwen2-vl"
DEPTHANYTHING_MODEL_PATH = "/checkpoints/depth-anything-v2"
MISTOLINE_MODEL_PATH = "/checkpoints/anyline"
SAM2_MODEL_PATH = "/checkpoints/segment-anything-v2"

或者，您也可以通过设置环境变量 CHECKPOINT_DIR 来指定根目录，无需修改代码。

基本使用

命令格式

python main.py --mode <模式> --input_image <图片路径> [其他选项]

常用参数说明

• --mode: 生成模式 (variation, img2img, inpaint, controlnet, controlnet-inpaint)
• --input_image: 输入图片路径
• --prompt: 引导生成的文本提示词
• --output_dir: 输出目录 (默认: outputs)
• --image_count: 生成图片数量
• --aspect_ratio: 宽高比 (1:1, 16:9, 9:16 等)

使用示例

1. 基础图像变体生成 (Variation)

基于输入图片生成变体，仅需加载核心模型。

python main.py --mode variation \
               --input_image path/to/image.jpg \
               --prompt "A beautiful landscape" \
               --image_count 4

2. 图生图转换 (Image-to-Image)

参考另一张图片进行风格或内容转换。

python main.py --mode img2img \
               --input_image source.jpg \
               --reference_image target.jpg \
               --prompt "xxxxxxxxxxxx" \
               --denoise_strength 0.75

3. 智能修复 (Inpainting)

使用掩码图片对指定区域进行重绘。

python main.py --mode inpaint \
               --input_image image.jpg \
               --mask_image mask.png \
               --prompt "Fill with beautiful flowers"

4. 精确控制生成 (ControlNet)

结合线条和深度信息进行结构化控制生成。

python main.py --mode controlnet \
               --input_image image.jpg \
               --line_mode \
               --depth_mode \
               --line_strength 0.4 \
               --depth_strength 0.2 \
               --prompt "xxxxxxxxxxxxxxxxxxxxx"

5. 自定义模型路径运行

通过环境变量指定模型存放位置，无需修改代码。

CHECKPOINT_DIR=/path/to/models python main.py \
               --mode variation \
               --input_image image.jpg \
               --prompt "xxxxxxxxxxxxxxxxxxxxxxxxx"