JoyAI-Image-Edit 是京东开源的指令驱动图像编辑模型，支持以下能力：

• 通用图像编辑（改变颜色、添加/移除物体等）
• 空间编辑（物体移动、旋转、相机控制）
• 文生图（Text-to-Image）

ComfyUI 中 JoyAI-Image-Edit 节点工作流的截图

示例效果展示（点击展开）

物体移动

Prompt: Move the board into the red box and finally remove the red box.

输入图像	输出图像

旋转

Prompt: Rotate the dog to show the left side view.

输入图像	输出图像

相机控制

Prompt:

Move the camera.
- Camera rotation: Yaw 0.0°, Pitch -15.0°.
- Camera zoom: unchanged.
- Keep the 3D scene static; only change the viewpoint.

输入图像	输出图像

说明：

• 模型权重总计约 47GB（BF16精度），其中 Transformer 31GB、Text Encoder 17GB、VAE 243MB
• 开启 cpu_offload 模式时，任意时刻仅一个大模块在 GPU 上，峰值显存实测约 33GiB（建议预留 35GB+）
• 关闭 cpu_offload 时全部模型同时加载到 GPU，需要 55GB 显存
• 如果显存不足 35GB，后续我们会发布量化版本权重，敬请期待

模型权重需要放置在 ComfyUI 的 models/diffusers/ 目录下。

# 安装 huggingface_hub（如未安装）
pip install huggingface_hub

# 下载到 ComfyUI/models/diffusers/ 目录
huggingface-cli download jdopensource/JoyAI-Image-Edit-Diffusers \
  --local-dir /path/to/ComfyUI/models/diffusers/JoyAI-Image-Edit-Diffusers

modelscope download --model jd-opensource/JoyAI-Image-Edit-Diffusers \
  --local_dir /path/to/ComfyUI/models/diffusers/JoyAI-Image-Edit-Diffusers

下载完成后 ComfyUI/models/diffusers/JoyAI-Image-Edit-Diffusers/ 目录的文件列表

ComfyUI/models/diffusers/
└── JoyAI-Image-Edit-Diffusers/
    ├── model_index.json
    ├── transformer/         # ~31GB, 核心扩散模型
    ├── text_encoder/        # ~17GB, Qwen3VL 文本编码器
    ├── tokenizer/           # ~16MB
    ├── processor/           # ~16MB
    ├── vae/                 # ~243MB
    └── scheduler/           # ~1KB

将自定义节点代码克隆或复制到 ComfyUI 的 custom_nodes/ 目录中。

cd /path/to/ComfyUI/custom_nodes/

# 克隆仓库
git clone https://github.com/jd-opensource/JoyAI-Image.git

# 提取 diffusers 版 ComfyUI 节点
cp -r JoyAI-Image/joyai_image_diffusers_comfyui ./

# 清理（可选）
rm -rf JoyAI-Image

如果你已经有代码文件，确保 custom_nodes/ 下存在如下结构：

ComfyUI/custom_nodes/
└── joyai_image_diffusers_comfyui/
    ├── __init__.py
    ├── nodes.py
    ├── joyai-image-edit-workflow.json    # 预置工作流
    └── README.md

本节点依赖以下关键包：

重要：截至 diffusers 0.38.0 正式版，JoyImageEditPipeline 已合并到主分支，但尚未包含在 release 中。需从源码安装：

# 进入 ComfyUI 使用的 Python 环境
# 如果 ComfyUI 用的 conda 环境:
# conda activate comfyui

pip install git+https://github.com/huggingface/diffusers.git

pip install transformers>=4.57.0

python -c "
from diffusers import JoyImageEditPipeline, JoyImageEditTransformer3DModel
from transformers import Qwen3VLForConditionalGeneration
print('All imports successful!')
"

如果输出 All imports successful! 表示安装成功。

1. 重启 ComfyUI
2. 在节点搜索中搜索 "JoyAI"

应该能看到以下 4 个节点：

1. 打开 ComfyUI
2. 将 custom_nodes/joyai_image_diffusers_comfyui/joyai-image-edit-workflow.json 拖入画布，或通过菜单 Load 导入

1. 在三个 Loader 节点中选择模型路径：下拉列表中应出现 JoyAI-Image-Edit-Diffusers
2. 连接输入图像：使用 Load Image 节点加载待编辑图片
3. 设置 Prompt：在 Pipeline 节点的 prompt 框中输入编辑指令（英文）

点击 Run 运行工作流。

首次运行时模型加载需要较长时间（约1-3分钟，取决于磁盘速度）。后续运行若模型已缓存则会快很多。

原因：ComfyUI 未正确加载节点包

解决方案：

1. 确认目录名正确：custom_nodes/joyai_image_diffusers_comfyui/
2. 检查 ComfyUI 启动日志是否有 import 错误
3. 确认 diffusers 和 transformers 已正确安装到 ComfyUI 使用的 Python 环境中

原因：模型权重目录未正确放置

解决方案：

1. 确认 ComfyUI/models/diffusers/JoyAI-Image-Edit-Diffusers/ 目录存在
2. 确认该目录下包含 model_index.json 文件
3. 如果 ComfyUI 配置了自定义路径，检查 extra_model_paths.yaml

原因：diffusers 版本过低，未包含 JoyImageEditPipeline

解决方案：

pip install git+https://github.com/huggingface/diffusers.git

原因：显存不足

解决方案：

1. 确保 Pipeline 节点中 cpu_offload 设为 True
2. 降低输出分辨率（height/width）
3. 将 num_images_per_prompt 设为 1
4. 关闭其他占用显存的程序

可能原因：

• 开启了 cpu_offload，模型在 CPU/GPU 间来回搬运正常会慢一些
• 磁盘 I/O 瓶颈

优化建议：

• 如有充足显存（80GB），关闭 cpu_offload
• 使用 NVMe SSD 存放模型权重

Turn the plate blue.
Add sunglasses to the person.
Remove the background.
Make it look like a painting.

Move the apple into the red box and finally remove the red box.

（需要在输入图像上标注红色方框表示目标位置）

Rotate the chair to show the front side view.
Rotate the car to show the rear left side view.

支持的方向：front, right, left, rear, front right, front left, rear right, rear left

Move the camera.
- Camera rotation: Yaw 45°, Pitch 0°.
- Camera zoom: in.
- Keep the 3D scene static; only change the viewpoint.

开启 cpu_offload=True 时，推理分为 4 个阶段，每个阶段仅有一个大模型在 GPU 上：

阶段1: Text Encoder → GPU   编码文本提示   → 卸载到 CPU
阶段2: VAE         → GPU   编码参考图像   → 卸载到 CPU
阶段3: Transformer → GPU   去噪循环       → 卸载到 CPU
阶段4: VAE         → GPU   解码输出图像   → 卸载到 CPU

这使得峰值显存占用仅为最大单模块的大小加上中间张量（实测峰值约 33GiB）。