Diffusers 中 LongCat-Image 文生图管线实战：中文渲染、提示词改写与编辑能力全解析

Diffusers 中 LongCat-Image 文生图管线实战：中文渲染、提示词改写与编辑能力全解析

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers

导读

LongCat-Image 是一个由美团 LongCat 团队提出的开源、中英双语图像生成基础模型，其核心亮点在于以仅 6B 参数量的规模，在中文文字渲染、逼真度与部署效率之间取得平衡，并配套了面向指令编辑的 LongCat-Image-Edit 模型。本文以 LongCat-Image 官方 API 文档 为主体，结合本仓库中 LongCatImagePipeline 源码、LongCatImageEditPipeline 源码 与对应模型实现，系统讲解如何在 Diffusers 中加载该模型、理解其独有的提示词改写（Prompt Rewrite）与 CFG Renorm 机制、掌握文生图与图像编辑两条调用路径，以及底层 Transformer 与调度器的实现原理。

LongCat-Image 是什么：定位与核心特性

根据 LongCat-Image 官方文档，LongCat-Image 是一个开源、中英双语（Chinese-English）的图像生成基础模型，设计初衷是应对当前主流模型在多语言文字渲染、照片级真实感、部署效率与开发者可及性等方面的核心挑战。其特性可以归纳为五点：

• 卓越的效率与性能：仅约 6B 参数，即在多个基准上超越参数量数倍于自身的开源模型，体现高效模型设计的潜力；
• 领先的编辑能力：LongCat-Image-Edit 在开源模型中达到领先水平，指令遵循与图像质量出色，且与原始图像保持高度视觉一致性；
• 强大的中文文字渲染：在常见汉字渲染的准确性与稳定性上优于现有开源 SOTA 模型，对中文字典的覆盖达到行业领先水平；
• 出色的照片级真实感：通过创新的数据策略与训练框架实现；
• 完整的开源生态：提供从中间 checkpoint 到完整训练代码的一整套工具链，降低研究与二次开发门槛。

该模型的完整技术细节可参考 LongCat-Image 技术报告（arXiv:2412.11963）。在本文仓库中，与之对应的实现分散在三处：管线代码位于 src/diffusers/pipelines/longcat_image/，核心扩散 Transformer 位于 src/diffusers/models/transformers/transformer_longcat_image.py，模型级测试位于 tests/models/transformers/test_models_transformer_longcat_image.py。

可用模型一览

三个模型在 Diffusers 中均可通过from_pretrained加载，管线入口分别是LongCatImagePipeline与LongCatImageEditPipeline。

快速上手：文生图示例

官方文档给出了一段可直接运行的最小示例（见 文档「Usage Example」）。下面结合源码对每一步进行解读：

import torch import diffusers from diffusers import LongCatImagePipeline weight_dtype = torch.bfloat16 pipe = LongCatImagePipeline.from_pretrained("meituan-longcat/LongCat-Image", dtype=torch.bfloat16) pipe.to('cuda') # or "mps", "xpu", "cpu" # pipe.enable_model_cpu_offload() prompt = '一个年轻的亚裔女性，身穿黄色针织衫，搭配白色项链。她的双手放在膝盖上，表情恬静。背景是一堵粗糙的砖墙，午后的阳光温暖地洒在她身上，营造出一种宁静而温馨的氛围。镜头采用中距离视角，突出她的神态和服饰的细节。光线柔和地打在她的脸上，强调她的五官和饰品的质感，增加画面的层次感与亲和力。整个画面构图简洁，砖墙的纹理与阳光的光影效果相得益彰，突显出人物的优雅与从容。' image = pipe( prompt, height=768, width=1344, guidance_scale=4.0, num_inference_steps=50, num_images_per_prompt=1, generator=torch.Generator("cpu").manual_seed(43), enable_cfg_renorm=True, enable_prompt_rewrite=True, ).images[0] image.save(f'./longcat_image_t2i_example.png')

几个要点说明：

1. 精度与设备：示例使用torch.bfloat16加载权重以降低显存占用；pipe.to('cuda')支持"cuda"、"mps"、"xpu"、"cpu"等设备。显存紧张时可改用注释掉的pipe.enable_model_cpu_offload()，其内部依赖源码中声明的model_cpu_offload_seq = "text_encoder->transformer->vae"（见 pipeline_longcat_image.py），即按文本编码器 → 扩散 Transformer → VAE 的顺序做 CPU 卸载。
2. 中英文提示词均可：管线内部会通过正则[\u4e00-\u9fff]自动判断提示词语言（get_prompt_language），中文输入走中文改写模板，英文输入走英文改写模板。
3. 输出：pipe(...)返回LongCatImagePipelineOutput，其images字段是list[PIL.Image.Image]（或np.ndarray）列表，取[0]即得到首张图像。

__call__核心参数速查

结合 pipeline_longcat_image.py 的__call__签名与文档字符串，将常用参数整理如下：

架构拆解：五个组件如何协作

LongCatImagePipeline.__init__（见 pipeline_longcat_image.py）注册了五个核心模块，这一组合决定了 LongCat-Image 的架构形态：

源码中还设置了几个关键内部参数：default_sample_size = 128（默认潜变量采样尺寸，乘以 VAE 缩放因子后得到默认输出分辨率）、tokenizer_max_length = 512（提示词最大 token 数，超出即截断并告警）、vae_scale_factor = 2 ** (len(block_out_channels) - 1)（通常为 8，即 VAE 对图像做 8 倍压缩）。

3D 位置编码：文本与图像统一坐标

LongCat-Image 的 Transformer 不使用传统一维位置嵌入，而是通过 prepare_pos_ids 构造3 维位置 id：每个 token 携带(modality_id, pos_h, pos_w)。文本 token 使用modality_id=0，图像 token 使用modality_id=1（编辑管线中还有modality_id=2表示参考图像）。文本与图像位置起始偏移均从tokenizer_max_length（512）开始，配合模型内部的LongCatImagePosEmbed（基于theta=10000的三维 RoPE，见 transformer_longcat_image.py），让单一阵列中不同模态各自拥有独立、可区分的坐标系统。

潜变量打包：16 通道与 2×2 拼接

与 SDXL/FLUX 等模型一致，LongCat-Image 采用潜变量打包（latent packing）：_pack_latents将(B, 16, H, W)的潜变量重排为(B, (H/2)×(W/2), 64)的 token 序列，_unpack_latents则执行逆操作（见 pipeline_longcat_image.py）。因此生成时要求height/width能被vae_scale_factor * 2（即 16）整除，源码中的check_inputs会对此发出告警并自动调整。

时间步调度：基于图像序列长度的 mu 偏移

管线通过 calculate_shift 依据打包后的图像序列长度image_seq_len线性插值计算调度器偏移量mu（默认base_seq_len=256、max_seq_len=4096、base_shift=0.5、max_shift=1.15，均可从 scheduler config 覆盖）。随后通过retrieve_timesteps（从 Stable Diffusion 管线复制而来）把自定义sigmas与mu一并传给FlowMatchEulerDiscreteScheduler.set_timesteps，得到最终的 timestep 序列。

两大特色机制：提示词改写与 CFG Renorm

提示词改写（Prompt Rewrite）

LongCat-Image 认为文生图模型对用户提示词的理解能力有限，因此在推理前端内置了一个"专家改写"步骤（rewire_prompt，见 pipeline_longcat_image.py）：

1. 根据提示词语言（中文/英文）选用 system_messages.py 中定义的SYSTEM_PROMPT_ZH或SYSTEM_PROMPT_EN，构造"用户输入为：...\n改写后的prompt为："这样的提问模板；
2. 用text_processor.apply_chat_template组装对话并交给Qwen2.5-VL文本编码器做generate（max_new_tokens=512）；
3. 对生成结果做batch_decode，把改写后的提示词作为后续编码的输入。

改写模板本身是 Few-Shot 的，内含 7 组中英文示例，约束包括：保留原始信息不删改、输入输出语言一致、未指定风格时默认"真实摄影风格"、需要生成文字时用双引号圈定（如"限时5折"）、移除否定词、禁止擅自添加文字内容等。这正是 LongCat-Image 在中文文字海报、标语渲染上表现出色的关键设计：先让语言模型把"要写什么字"显式化，再交给扩散模型渲染。

此外，_encode_prompt中的split_quotation（pipeline_longcat_image.py）会把提示词按单双引号（含中文弯引号）拆分为"普通文本"与"引号内文本"两段，分别分词后再拼接，从而保证引号内的文字内容被完整、独立地编码，避免与其他描述混淆。

CFG Renorm

当guidance_scale > 1时启用无分类器引导，去噪循环会对同一潜变量分别执行条件（cache_context("cond")）与无条件（cache_context("uncond")）前向，然后按noise_pred = noise_pred_uncond + guidance_scale * (noise_pred_text - noise_pred_uncond)合并。若enable_cfg_renorm=True，管线还会额外做一步归一化（见 pipeline_longcat_image.py）：

cond_norm = torch.norm(noise_pred_text, dim=-1, keepdim=True) noise_norm = torch.norm(noise_pred, dim=-1, keepdim=True) scale = (cond_norm / (noise_norm + 1e-8)).clamp(min=cfg_renorm_min, max=1.0) noise_pred = noise_pred * scale

即按条件预测的范数对融合后的噪声预测做逐位置缩放，并将缩放系数限制在[cfg_renorm_min, 1.0]区间内。官方文档说明：开启 renorm 能提升图像质量，但可能降低部分输出的稳定性；cfg_renorm_min=1.0相当于关闭 renorm，cfg_renorm_min=0.0则让调整范围最宽。

图像编辑：LongCatImageEditPipeline

与文生图共用同一套 Transformer 与调度器的LongCatImageEditPipeline（pipeline_longcat_image_edit.py）面向指令式编辑，官方示例：

from PIL import Image import torch from diffusers import LongCatImageEditPipeline pipe = LongCatImageEditPipeline.from_pretrained( "meituan-longcat/LongCat-Image-Edit", torch_dtype=torch.bfloat16 ) pipe.to("cuda") prompt = "change the cat to dog." input_image = Image.open("test.jpg").convert("RGB") image = pipe( input_image, prompt, num_inference_steps=50, guidance_scale=4.5, generator=torch.Generator("cpu").manual_seed(43), ).images[0] image.save("longcat_image_edit.png")

编辑管线与文生图管线的主要差异：

• 多模态输入：_encode_prompt通过text_processor.image_processor对输入图像做预处理（pixel_values与image_grid_thw），把<|image_pad|>占位符按视觉 token 数量展开后拼入系统模板，再一并送入 Qwen2.5-VL 编码，使模型"看见"原图；
• 参考图像潜变量：prepare_latents会用 VAE 以argmax模式编码输入图像得到image_latents（位置 id 的modality_id=2），去噪时与待生成的latents在序列维拼接（torch.cat([latents, image_latents], dim=1)），预测结果再截取回image_seq_len；
• 自动尺寸适配：calculate_dimensions依据输入图像宽高比，把总像素面积约束在约 1024×1024 并向上取整到 16 的倍数；
• 无提示词改写：编辑管线__call__不包含enable_prompt_rewrite/enable_cfg_renorm参数，指令由用户直接给定。

底层模型：LongCatImageTransformer2DModel

作为扩散主干，LongCatImageTransformer2DModel 采用类 MMDiT 的双流结构：transformer_blocks（默认 19 层，同时处理文本与图像分支的联合注意力）+single_transformer_blocks（默认 38 层单流块），完整参数如下（默认值取自@register_to_config）：

注意力实现LongCatImageAttnProcessor依赖F.scaled_dot_product_attention（要求 PyTorch 2.0+），支持文本/图像联合注意力（encoder_query/encoder_key/encoder_value与视觉分支拼接后再做 RoPE 与注意力计算），并通过dispatch_attention_fn支持后端分发。模型声明支持梯度检查点（_supports_gradient_checkpointing = True），对应测试 test_models_transformer_longcat_image.py 中专门断言了LongCatImageTransformer2DModel的梯度检查点会被正确应用。

调用链与可复现性提示

文生图的完整调用链可概括为：

__call__ ├─ check_inputs（尺寸/参数合法性） ├─ rewire_prompt（可选：Qwen2.5-VL 改写提示词） ├─ encode_prompt（分词 + 模板拼接 + hidden_states 提取 + 3D text_ids） ├─ prepare_latents（随机噪声 + 2×2 打包 + 3D img_ids） ├─ 调度器 set_timesteps（sigmas + mu 偏移） └─ 去噪循环（cond/uncond 双前向 → CFG → renorm → scheduler.step） └─ VAE decode + postprocess → LongCatImagePipelineOutput

实际使用中几点建议：想要可复现输出时务必传入固定种子的torch.Generator；希望节省显存时开启enable_model_cpu_offload()或改用torch.bfloat16；需要深度控制采样过程时可通过latents、prompt_embeds、sigmas等高级参数接管管线内部步骤；negative_prompt仅在guidance_scale > 1时生效。若想验证模型前向逻辑，可参考 test_models_transformer_longcat_image.py 中的测试配置（小尺寸num_layers=1、num_attention_heads=2等）进行轻量复现。

小结

LongCat-Image 在 Diffusers 中的落地体现了"小模型 + 强工程"的思路：6B 规模的双流 Transformer 配合 Flow Matching Euler 调度器完成高效去噪；Qwen2.5-VL 编码器同时承担提示词编码与改写推理，配合引号分词策略解决多语言文字渲染难题；CFG Renorm 与基于图像序列长度的 mu 偏移则为输出质量与稳定性提供精细控制；而 LongCat-Image-Edit 通过多模态编码与参考潜变量拼接，在统一的架构上实现了指令式图像编辑。无论是文生图、中文海报文字生成还是图像编辑，都可以直接基于LongCatImagePipeline/LongCatImageEditPipeline两条管线快速落地。

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers