JoyAI-Image 中文教程：先跑通单图编辑，再考虑多图
JoyAI-Image 是京东开源的图像理解与编辑模型家族。当前真正能下载和核对的重点是理解骨干、单图编辑 JoyAI-Image-Edit、Edit-Plus 多图编辑，以及 Diffusers/ComfyUI 接入。它是本地模型工程，不是打开网页就能用的 SaaS；完整权重为数十 GB，还需要 CUDA GPU。
1. 先看清哪些模型已经发布
官方 Model Zoo 中，JoyAI-Image-Und、单图 Edit 与 Edit-Plus 已有下载。Edit-Distilled 和名为 JoyAI-Image 的文生图主模型仍标为 To be released。不要因为项目总介绍写了“理解、生成、编辑”，就把尚未发布的权重写成现成功能。
单图模型把 8B 多模态理解骨干与 16B MMDiT 组合起来。理解部分负责场景、物体关系和指令分解，扩散模型负责实际编辑。Edit-Plus 扩展到多输入图像的组合与一致性操作。
2. 环境与下载规模
当前 pyproject 要求 Python 3.10+，并固定 PyTorch 2.8.0、Diffusers 0.36.0 和 Transformers 4.57.x。Hugging Face 的单图模型树约 50.6 GB，旧格式 transformer 文件单个约 32.5 GB。预留空间时还要算缓存、ComfyUI 重打包和输出图。
git clone https://github.com/jd-opensource/JoyAI-Image.git
cd JoyAI-Image
git rev-parse HEAD
conda create -n joyai python=3.10 -y
conda activate joyai
pip install -e .
pip freeze > environment-lock.txt官方没有给出覆盖全部分辨率、步骤和模型格式的最低显存数字。模型能下载完成，也不代表一定能在你的卡上加载。首次测试只装一套权重，并用系统监控记录峰值。
3. Flash Attention 不是完全离线依赖
kernels 会在首次使用时尝试下载预编译的 Flash Attention 3；如果机器没有匹配二进制，代码会转为本地源码构建。隔离网络或受控生产环境要先把这一步纳入依赖审计，不能等到推理时才发现它联网或需要编译工具链。
4. 用 Diffusers 做最小单图验证
官方说明 JoyImageEditPipeline 要进入 Diffusers 0.38.0 之后的正式版；在此之前，README 要求从 Diffusers 源码安装。这里展示调用形状，版本以你核对时的官方说明为准：
pip install torch transformers torchvision
pip install git+https://github.com/huggingface/diffusers.git
python - <<'PY'
import torch
from diffusers import JoyImageEditPipeline
from diffusers.utils import load_image
pipe = JoyImageEditPipeline.from_pretrained(
"jdopensource/JoyAI-Image-Edit-Diffusers",
torch_dtype=torch.bfloat16,
).to("cuda")
image = load_image("input.png")
result = pipe(
image=image,
prompt="只把盘子的颜色改成蓝色，其他区域不变",
num_inference_steps=40,
guidance_scale=4.0,
generator=torch.Generator("cuda").manual_seed(123),
).images[0]
result.save("output.png")
PY5. 第一次不要开启提示重写
原生脚本的 --rewrite-prompt 默认关闭。开启后会安装可选的 openai 依赖，并调用配置的重写模型；官方参数默认模型名为 gpt-5。这会把提示发送给外部服务，也可能产生费用。先用原始提示建立基准，确认确有收益后再单独评估外发内容和账单。
6. 如何判断编辑是否真的成功
不要只挑一张好看的输出。至少保存原图、指令、seed、步数、guidance、精度、源码 commit、模型 revision、耗时和峰值显存。结果检查分三项：目标区域是否按指令变化；不该变化的区域是否保持；图中文字是否逐字正确。多图编辑还要检查主体身份和物体属性有没有串到另一张图。
7. Diffusers 与 ComfyUI 怎么选
Diffusers 适合写批处理、固定 seed 和做回归测试。ComfyUI 适合交互式调节点和接已有工作流。官方在 2026-07-17 宣布两种编辑模型均可由新版 ComfyUI 原生使用，并提供对应格式的权重和 workflow。不要把 Diffusers 目录、旧 checkpoint root 与 ComfyUI 重打包文件混在同一路径。
8. 同类对比：JoyAI-Image 与 Qwen-Image-Edit
相比 Qwen-Image-Edit，JoyAI-Image 更强调 8B 理解骨干与 16B MMDiT 协作的空间编辑，并同时维护 Edit-Plus 与 ComfyUI 权重；Qwen-Image-Edit 强调语义/外观双路控制和中英文文字编辑。两者都是 Apache-2.0，也都是数十 GB 级模型。公平比较要使用同一组输入、指令、seed 和显存限制，统计主体保持、未编辑区域变化、文字错误和耗时。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合有 CUDA 机器、需要私有图像本地编辑、空间变换、中英文文字编辑或多图合成的研究与制作流程。只想浏览器上传后立即出图、显存有限，或要求稳定批量 SLA 的团队，需要另选托管服务或较小模型。涉及人脸、商标和版权素材时仍要单独取得权限。
采用建议
JoyAI-Image 可保留并持续更新。它没有项目方订阅、充值或转售漏斗，主要成本来自用户自己的 GPU 与可选外部提示重写。适合能承担大权重和 CUDA 运维的人；首次验证优先走官方 Diffusers 单图编辑，关闭 prompt rewrite，记录 commit、模型 revision、seed、显存和失败样例。
原教程未展开的系统信息
核心功能
文字与版式处理
项目把中英文长文本、多行排版、漫画格和场景文字作为重点展示项，但展示图不能替代用户自己的准确率测试。
架构与数据流
模型家族用 8B MLLM 处理图像理解、关系定位和指令分解，以 16B 多模态扩散 Transformer 生成编辑结果。官方原生脚本从 checkpoint root 加载理解骨干、transformer 与 Wan2.1 VAE；Diffusers 将这些组件包装成 JoyImageEditPipeline。权重托管在 Hugging Face/ModelScope，首次运行还可能通过 kernels 下载预编译 Flash Attention 3；不匹配时会转为本地编译。
常见问题
JoyAI-Image 能直接做文生图吗？
项目目标包含文生图，但当前官方 Model Zoo 仍把 JoyAI-Image 文生图主模型列为 To be released。现在可直接核对和下载的重点是理解、单图编辑与 Edit-Plus 多图编辑。
运行 JoyAI-Image 至少要多少显存？
官方只明确要求 CUDA-capable GPU，没有给出覆盖所有分辨率、步骤和模型格式的统一最低显存。权重本身为数十 GB，应先下载一个模型、降低并发，并在目标机器记录峰值后再扩容。
Diffusers 和 ComfyUI 应该选哪个？
需要写 Python、固定 seed 和做批量评测时选 Diffusers；已有节点式工作流、想交互调参时选 ComfyUI。两条路线都应使用官方模型卡给出的权重布局，避免把旧版转换文件混在一起。
--rewrite-prompt 会不会把提示发到外部？
这个参数默认关闭。开启后会使用可选 openai 依赖和所配置的重写模型，提示内容会进入对应外部服务，并可能产生费用；含私密图像说明或内部素材时应保持关闭。
为什么教程不直接保证生成质量？
官方展示和论文可以说明设计目标，但本站没有下载模型并复现实验。主体一致性、文字正确率和未编辑区域变化会受输入、seed、步骤、精度与显卡影响，应使用自己的测试集判断。