JoyAI-Image ComfyUI集成教程节点与权重配置全流程低显存CPU Offload策略【免费下载链接】JoyAI-ImageJoyAI-Image is the unified multimodal foundation model for image understanding, text-to-image generation, and instruction-guided image editing.项目地址: https://gitcode.com/gh_mirrors/jo/JoyAI-Image文章摘要本文带来 JoyAI-Image ComfyUI 集成完整教程详解 4 个自定义节点扩散模型 / 文本编码器 / VAE / 推理流水线的连线方式、权重文件放置位置、推理参数配置以及专为低显存环境设计的四阶段 CPU Offload 策略帮助新手快速在 ComfyUI 中跑通指令引导图像编辑。 一、JoyAI-Image ComfyUI 集成能做什么JoyAI-Image 是一个统一的多模态基础模型用 8B 的 MLLM 16B 的 MMDiT 架构同时支持图像理解、文生图与指令引导的图像编辑。仓库中的 joyai_image_comfyui/ 目录就是它的 ComfyUI 节点包基于 Diffusers 后端遵循 ComfyUI 标准的单文件权重加载约定并内置了手动分阶段 CPU Offload让低显存显卡甚至勉强只有一块消费级 GPU 的环境也能跑起来。 二、ComfyUI 节点安装三步完成步骤 1准备环境依赖依赖版本要求用途diffusers≥0.39.0.dev0需含JoyImageEditPipeline提供编辑流水线与 Transformer 类transformers≥4.57.0提供 Qwen3VL 文本编码器JoyImageEditPipeline尚未随旧版 diffusers 正式发布需安装带该支持的 diffusers 开发版否则节点会在加载时报类缺失错误。步骤 2放置节点包把仓库中的joyai_image_comfyui文件夹整个复制到 ComfyUI 的custom_nodes/目录下需要克隆时使用git clone https://gitcode.com/gh_mirrors/jo/JoyAI-ImageComfyUI/custom_nodes/ └── joyai_image_comfyui/ ├── __init__.py # 注册 NODE_CLASS_MAPPINGS ├── nodes.py # 4 个节点的全部实现 └── configs/ # 各组件的结构配置文件自动使用无需下载步骤 3下载权重并放入标准目录从官方模型仓库下载三个单文件 safetensors 权重分别放入 ComfyUI 标准模型目录ComfyUI/models/ ├── diffusion_models/ │ └── joy_image_edit_bf16.safetensors # Transformer去噪主干 ├── text_encoders/ │ └── qwen3vl_joyimage_bf16.safetensors # Qwen3VL 文本编码器 └── vae/ └── joy_image_edit_vae.safetensors # Wan VAE 每个加载节点会自动扫描对应目录下的.safetensors文件并生成下拉框权重放对位置后无需任何额外配置。注意tokenizer/processor 配置已内置在 configs/processor/ 中不需要单独下载分词器。重启 ComfyUI 后节点会自动出现在loaders/joyai和image/joyai分类下。 三、4 个 JoyAI 节点全解名称、类型与连线节点包共提供 4 个节点源码见 nodes.py节点名显示名分类输出类型作用JoyAIImageEditUNETLoaderLoad JoyAI Diffusion Modelloaders/joyaiJOY_MODEL从diffusion_models/加载 MMDiT 主干JoyAIImageEditCLIPLoaderLoad JoyAI CLIPloaders/joyaiJOY_CLIP加载 Qwen3VL 文本编码器并捆绑 tokenizer processorJoyAIImageEditVAELoaderLoad JoyAI VAEloaders/joyaiJOY_VAE从vae/加载 Wan VAEJoyAIImageEditPipelineJoyAI Image Edit Pipelineimage/joyaiIMAGE组装流水线并执行推理⚠️ 三个加载节点输出的是JOY_MODEL / JOY_CLIP / JOY_VAE自定义类型而非 ComfyUI 核心的MODEL/CLIP/VAE——因为底层模型类与核心 API 不兼容。连线时只需按类型拖线即可不能混接其他模型的加载节点。工作流连线共 4 步三个 Loader 分别选中对应权重 → 输出线连入 Pipeline 节点的model / clip / vae输入用 Load Image 载入待编辑图片 → 连入 Pipeline 的image输入可选填写prompt编辑指令Pipeline 输出IMAGE→ 接 Preview / Save Image 节点。编辑效果示例——将画面中的人物移动到右侧位置 如果不接image输入则自动退化为文生图T2I模式此时建议把height/width手动设为 1024。 四、推理参数配置一次调对出图质量Pipeline 节点的全部参数nodes.py参数默认值范围新手建议prompt—编辑指令如 Turn the plate blueheight/width00–20480 跟随输入图自动对齐到 bucketsteps401–200先 30–40追求细节再加guidance_scale4.00–301.0 才启用 CFG默认 4.0 很稳num_images_per_prompt11–8批量对比时调大seed0—支持固定/递增/随机控制cpu_offloadTrue—低显存环境务必保持开启 五、低显存 CPU Offload四阶段显存管理策略这是本集成的核心卖点。当cpu_offloadTrue时流水线会手动接管显存把推理切成 4 个阶段每个阶段只把当前要用的那一个大模块搬上 GPU用完立即搬回 CPU 并empty_cache()nodes.py阶段在 GPU 上的模块做什么完成后① 文本编码文本编码器编码正/负提示词为嵌入嵌入转存 CPU编码器卸回 CPU② VAE 编码VAE把参考图编码成 latentslatents 与 VAE 均回 CPU③ 去噪循环Transformer跑完整 steps 步去噪latents 回 CPUTransformer 卸回 CPU④ VAE 解码VAE最终 latents 解码为图片VAE 卸回 CPU输出结果任何时刻 GPU 上只有一个大模型因此理论所需显存 ≈ 单个最大模块Transformer 中间张量而不是三个模型之和。实践建议显存吃紧保持cpu_offloadTrue默认代价是阶段切换带来少量耗时显存充足如 24GB 且只跑 1024 分辨率可关闭 offload整条流水线常驻 GPU速度更快分辨率越高、steps越大去噪阶段峰值越高OOM 时优先降分辨率而非降 steps。 六、进阶用 ComfyUI 做空间编辑除了常规改图JoyAI-Image 还擅长空间编辑——移动物体、旋转视角、移动相机。官方推荐固定提示模板详见 README.mdMove the object into the red box and finally remove the red box.Move the camera. - Camera rotation: Yaw 45°, Pitch 0°. - Camera zoom: in. - Keep the 3D scene static; only change the viewpoint.这类高保真视角变换还能反过来辅助空间推理——下图中 JoyAI-Image-Edit 生成的新视角能最清晰地验证物体高低关系 七、常见问题排查现象原因与解决节点加载时报 diffusers 类缺失diffusers 版本过旧需安装含JoyImageEditPipeline的开发版下拉框中看不到权重文件没放对目录或文件名不是.safetensors结尾编辑结果与指令偏差大提高guidance_scale如 5.0–6.0或增加stepsOOMout of memory确认cpu_offloadTrue降低输出分辨率或批量数出图尺寸与输入不一致height/width非 0 时会覆盖输入图尺寸设为 0 则自动跟随✅ 小结安装joyai_image_comfyui拷入custom_nodes/三个单文件权重分别放入diffusion_models/、text_encoders/、vae/连线3 个 Loader 1 个 PipelineJOY_*类型线一拖即通调参默认steps40、guidance_scale4.0、height/width0即可开箱出图省显存cpu_offloadTrue四阶段轮转任何时刻 GPU 只驻留一个大模型。完整说明可参考节点包自带文档 joyai_image_comfyui/README.md。【免费下载链接】JoyAI-ImageJoyAI-Image is the unified multimodal foundation model for image understanding, text-to-image generation, and instruction-guided image editing.项目地址: https://gitcode.com/gh_mirrors/jo/JoyAI-Image创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考