Compel

由 @damian0815 开发的、用于 Transformer 类文本嵌入系统的文本提示加权与混合库。

借助灵活直观的语法，你可以对提示字符串的不同部分进行重新加权，从而调整由此字符串生成的嵌入张量中各部分的权重。

该库已在 Hugging Face 的 StableDiffusionPipeline 上进行了测试和开发，但理论上也适用于任何基于 diffusers 并使用某种 Tokenizer 和 Text Encoder 的系统。

本库改编自 InvokeAI 的提示编写代码（同样由 @damian0815 编写）。

需要注意的是，当前 Compel 会忽略交叉注意力控制 .swap()，不过你也可以通过自行调用 build_conditioning_tensor_for_prompt_object() 方法，并在扩散循环中实现交叉注意力控制来使用它。

安装

pip install compel

文档

文档请见 这里。

演示

参见 compel-demo.ipynb

快速入门

使用 Hugging Face diffusers >=0.12：

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)

# 加强“ball”的权重
prompt = "a cat playing with a ball++ in the forest"
conditioning = compel(prompt)

# 生成图像
images = pipeline(prompt_embeds=conditioning.embeds, num_inference_steps=20).images
images[0].save("image.jpg")

使用负面提示：

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)

# 加强“ball”的权重
prompt = "a cat playing with a ball++ in the forest"
negative_prompt = "blurry, low quality, deformed"
conditioning = compel(prompt, negative_prompt=negative_prompt)

# 生成图像
images = pipeline(prompt_embeds=conditioning.embeds, negative_prompt_embed=conditioning.negative_embeds, num_inference_steps=20).images
images[0].save("image.jpg")

批量处理：

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)

prompt = ["a cat playing with a ball++ in the forest", "a dog wearing a hat++"]
negative_prompt = ["blurry, low quality, deformed", "painting"] 
# 或者：negative_prompt = "blurry, low quality, deformed" # 共享给所有生成的图像
conditioning = compel(prompt, negative_prompt=negative_prompt)

# 生成图像
images = pipeline(prompt_embeds=conditioning.embeds, negative_prompt_embed=conditioning.negative_embeds, num_inference_steps=20).images
images[0].save("image.jpg")

SDXL：

from diffusers import DiffusionPipeline
from compel import CompelForSDXL
import torch

device = 'cuda'
pipeline = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", variant="fp16", 
                                             use_safetensors=True, torch_dtype=torch.float16).to(device)

prompt = "a cat playing with a ball++ in the forest"
negative_prompt = "low quality, blurry"
compel = CompelForSDXL(pipeline)
conditioning = compel(prompt, negative_prompt=negative_prompt)

generator = torch.Generator().manual_seed(42)
image = pipeline(prompt_embeds=conditioning.embeds, 
                 pooled_prompt_embeds=conditioning.pooled_embeds,
                 negative_prompt_embeds=conditioning.negative_embeds,
                 negative_pooled_prompt_embeds=conditioning.negative_pooled_embeds,
                 num_inference_steps=25, width=1024, height=1024, generator=generator).images[0]
image.save('sdxl_image.jpg')

Flux

from diffusers import FluxPipeline
from compel import CompelForFlux
import torch

device = "mps"
pipe = FluxPipeline.from_pretrained("black-forest-labs/FLUX.1-schnell", torch_dtype=torch.float32).to(device) # bfloat16 在 MPS 上会导致 NaN
compel = CompelForFlux(pipe)

prompt = "Astronaut---- in a jungle++++, cold color palette, muted colors, detailed, 8k"

conditioning = compel(prompt)
generator = torch.Generator().manual_seed(42)
images = pipe(prompt_embeds=conditioning.embeds, pooled_prompt_embeds=conditioning.pooled_embeds,
             num_inference_steps=4, width=512, height=512, generator=generator)

风格提示

适用于 SDXL 或 Flux：

from diffusers import DiffusionPipeline
from compel import CompelForSDXL
import torch

device = 'cuda'
pipeline = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", variant="fp16", 
                                             use_safetensors=True, torch_dtype=torch.float16).to(device)

prompt = "a cat playing with a ball++ in the forest"
style_prompt = "painting by van gogh, impasto, thick brush strokes"
negative_prompt = "low quality, blurry"
negative_style_prompt = "photography"
compel = CompelForSDXL(pipeline) # 或 CompelForFlux
conditioning = compel(prompt=prompt, negative_prompt=negative_prompt, 
                      style_prompt=style_prompt, negative_style_prompt=negative_style_prompt)

generator = torch.Generator().manual_seed(42)
image = pipeline(prompt_embeds=conditioning.embeds, 
                 pooled_prompt_embeds=conditioning.pooled_embeds,
                 negative_prompt_embeds=conditioning.negative_embeds,
                 negative_pooled_prompt_embeds=conditioning.negative_pooled_embeds,
                 num_inference_steps=25, width=1024, height=1024, generator=generator).images[0]
image.save('sdxl_image.jpg')

文本反转支持

如果你想使用 🤗diffusers 的文本反转功能，请实例化一个 DiffusersTextualInversionManager，并在初始化 Compel 时传入：

from diffusers import StableDiffusionPipeline
from compel import CompelForSD, DiffusersTextualInversionManager
pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
textual_inversion_manager = DiffusersTextualInversionManager(pipeline)
compel = CompelForSD(pipe=pipeline, textual_inversion_manager=textual_inversion_manager)

内存使用/显存泄漏

如果遇到内存问题，请确保在 with torch.no_grad(): 块中运行 Compel。

如果这样仍无法解决问题，可以尝试 @kshieh1 提供的建议：

图像生成后，应显式地解除对张量对象的引用（即 prompt_embeds = None），并调用 gc.collect()。

更多详情请参阅 https://github.com/damian0815/compel/issues/24。感谢 @kshieh1！

更改记录

2.3.1 - 修复 SDXL 中 78 个 token / 77 个 token 的问题；为 CompelFor* 构造函数添加 device 参数（感谢 @dx2-66）

2.3.0 - 分词信息、SplitLongTextMode 中 CLS 令牌处理、负向/风格提示错误修复

• CompelFor* 对象现在通过 conditioning.tokenization_info 字典返回分词信息，该字典包含 main_positive 和（在适用时）main_negative、style_positive 和 style_negative 键。
• SplitLongTextMode 枚举新增了处理 CLS（EOS）令牌的选项——CLS 令牌可以从第一个分块复制到后续分块，或者将所有 CLS 令牌合并后在所有分块上重复。详情请参阅 SplitLongTextMode 枚举。
• 针对 SDXL/Flux 处理不同组合的风格提示和负向提示的一些边缘情况进行了修复。

2.2.1 - 修复 #116 问题

2.2.0 - 支持 Flux，提升易用性

• 现已支持 Flux。
• 新增 CompelForSD、CompelForFlux 和 CompelForSDXL，以简化并优化嵌入与池化嵌入、负向提示以及风格提示的处理。使用示例请参见 compel-demo-*.py/.ipynb。
• 在处理非加权提示时性能有所提升。如果传递的提示未加权重，则会完全跳过加权逻辑。这可能会略微改变未加权时的输出结果——可通过调用 compel.disable_no_weights_bypass() 恢复旧版较慢的行为。
• 使用 CompelForSD 和 CompelForSDXL 类时，非截断现为默认设置。

2.1.1 - 将 split_long_text_mode 暴露至顶层 Compel，默认值设为 SENTENCES，修复有时分割会失败的 bug。

2.1.0 - 添加 split_long_text_mode 参数，用于在 truncate_long_prompts 为 False 时控制长提示的分词方式。详见 SplitLongTextMode。默认值为 WORDS。

2.0.3 - 包含贡献的修复 #64、#80，并修复 pyproject.toml/pypi 中的许可证问题。

2.0.2 - 修复 SDXL 模型配合 pipeline.enable_sequential_cpu_offloading() 使用时的问题（需在初始化 Compel 时传入 device='cuda'）。

2.0.1 - 修复 #45 关于 SDXL 非截断提示及 .and() 方法的填充问题。

2.0.0 - 支持 SDXL

特别感谢 Hugging Face 的 Patrick von Platen 提供的 拉取请求，Compel 现已支持 SDXL。使用方法如下：

from compel import Compel, ReturnedEmbeddingsType
from diffusers import DiffusionPipeline
import torch

pipeline = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", variant="fp16", use_safetensors=True, torch_dtype=torch.float16).to("cuda")
compel = Compel(tokenizer=[pipeline.tokenizer, pipeline.tokenizer_2] , text_encoder=[pipeline.text_encoder, pipeline.text_encoder_2], returned_embeddings_type=ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NON_NORMALIZED, requires_pooled=[False, True])
# 提升“ball”的权重
prompt = "a cat playing with a ball++ in the forest"
conditioning, pooled = compel(prompt)
# 生成图像
image = pipeline(prompt_embeds=conditioning, pooled_prompt_embeds=pooled, num_inference_steps=30).images[0]

请注意，如果您一直使用 clip skip 功能，此次更新属于破坏性变更：旧的布尔型参数 use_penultimate_clip_layer 已被枚举类型 ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NORMALIZED 所取代。

1.2.1 - 正确应用 .and() 权重

1.2.0 - 使用 .and() 连接嵌入

对于 Stable Diffusion 2.1，我一直在尝试一项新功能：连接嵌入。我发现，例如，当提示词较为复杂时，如果将提示词拆分成多个部分并分别输入到 OpenCLIP 中，生成图像的质量会显著提升。

简而言之：现在你可以尝试将提示词拆分成若干段，这对 SD2.1 来说似乎能改善生成的图像质量。语法是 ("prompt part 1", "prompt part 2").and()。你也可以有超过两个部分，并且可以为它们设置权重，比如 ("a man eating an apple", "sitting on the roof of a car", "high quality, trending on artstation, 8K UHD").and(1, 0.5, 0.5)，这会为 man eating an apple 分配权重 1，而为 sitting on the roof of a car 和 high quality, trending on artstation, 8K UHD 各分配权重 0.5。

这里有一个来自 InvokeAI Discord #garbage-bin 频道的无厘头例子，由 gogurt enjoyer 的超赞 噩梦提示词生成器 创作：

a moist sloppy pindlesackboy sloppy hamblin' bogomadong, Clem Fandango is pissed-off, Wario's Woods in background, making a noise like ga-woink-a

直接将这个提示词输入 SD2.1，得到的结果并不理想：

然而，如果将提示词拆分成几块，分别作为四个独立的提示词输入 OpenCLIP，然后再进行连接：

a moist sloppy pindlesackboy sloppy hamblin' bogomadong

Clem Fandango is pissed-off

Wario's Woods in background

making a noise like ga-woink-a

那么使用相同种子生成的图像就会好很多：

在新的 .and() 语法中，你可以这样写提示词：

("a moist sloppy pindlesackboy sloppy hamblin' bogomadong", "Clem Fandango is pissed-off", "Wario's Woods in background", "making a noise like ga-woink-a").and()

这种效果有时可能不太明显。例如，以下是一个例子：

A dream of a distant galaxy, by Caspar David Friedrich, matte painting, trending on artstation, HQ

而将其拆分为两部分：

A dream of a distant galaxy, by Caspar David Friedrich, matte painting

trending on artstation, HQ

对应的 Compel 提示词是：

("A dream of a distant galaxy, by Caspar David Friedrich, matte painting", "trending on artstation, HQ").and()

1.1.6 - 其他小修复

• 添加 DiffusersTextualInversionManager（感谢 @pdoane）
• 修复批处理嵌入生成时提示词长度截断或未截断的问题（#18，感谢 @abassino）
• 增加关于内存泄漏的说明（ref #24，感谢 @kshieh1）
• 修复逗号后没有空格时解析错误的问题（#34，感谢 @moono）

1.1.5 - 修复 Compel 将括号内的数字转换为浮点数的问题

1.1.4 - 修复 #23（顺序卸载）和 InvokeAI 问题 #3442（允许 LoRA 名称中包含连字符）的相关问题

1.1.3 - 支持获取倒数第二层 CLIP 隐藏层（即“clip skip”）

要使用，请在初始化 Compel 实例时传入 use_penultimate_clip_layer=True。请注意，对于 SD2.0/SD2.1，无需传递此标志，因为 diffusers 在加载 SD2.0 及以上版本的文本编码器时已经会丢弃最后一层隐藏层。

1.1.2 - 修复 #21（启用截断时解析长提示词，若存在超出截断边界的加权片段，则会导致崩溃）的问题

1.1.1 - 修复 #22（解析括号内 . 字符时出现问题）的问题

1.1.0 - 支持在 parse_prompt_string() 中解析 withLora/useLora

• Compel.parse_prompt_string() 现在会返回一个 Conjunction
• 提示词字符串中任何出现的 withLora(name[, weight]) 或 useLora(name[, weight]) 都会被解析为 LoraWeight 实例，并在 parse_prompt_string() 返回的最外层 Conjunction 中体现出来。

1.0.5 - 修复输入无效（auto1111）语法中的浮点数时的解析错误

同时修复默认交换参数的测试用例

1.0.4 - 修复禁用截断时空交换目标（如 cat.swap("")）的嵌入问题

1.0.3 - 改进 .swap 的默认行为（https://github.com/damian0815/compel/issues/8）

1.0.2 - 修复非截断批量嵌入的填充问题（https://github.com/damian0815/compel/issues/9）

1.0.1 - 修复 InvokeAI 的 --free_gpu_mem 选项问题

1.0.0 - 新的降权算法

现在的降权机制是通过应用注意力掩码来移除被降权的标记，而不是直接从序列中删除它们。这是默认行为，但可以通过在初始化 Compel 实例时传入 downweight_mode=DownweightMode.REMOVE 来恢复旧的行为。

过去，降权一个标记的做法是同时乘以该标记嵌入的权重，并与一个移除了被降权标记的标记序列副本进行反向加权混合。其背后的直觉是：当权重趋近于零时，被降权的标记应该真正从序列中移除。然而，移除这些标记会导致所有后续标记的位置错乱，最终混合的效果远远超出了原本需要处理的标记范围。

自 v1.0.0 起，根据 @keturn 和 @bonlime 的建议（https://github.com/damian0815/compel/issues/7），默认的处理方式发生了变化。降权仍然涉及混合操作，但现在混合的是一个将被降权标记屏蔽掉的标记序列版本，而不是直接移除它们。这样可以正确地保留其他标记的嵌入位置。

此外还修复了一个 bug：解决了权重为 0 时生成黑色图像的问题（https://github.com/invoke-ai/InvokeAI/issues/2832）

0.1.10 - 添加对超过模型最大标记长度的提示的支持。

要启用此功能，请使用 truncate_long_prompts=False 初始化 Compel（默认值为 True）。超过模型 max_token_length 的提示将被分块，并填充到 max_token_length 的整数倍。

请注意，即使您不使用负面提示，也需要为至少包含空字符串 "" 的负面提示构建条件张量，并调用 compel.pad_conditioning_tensors_to_same_length()，否则会因条件张量长度不匹配而报错：

compel = Compel(..., truncate_long_prompts=False)
prompt = "一只猫在森林里玩球++，惊艳、精致、令人惊叹、杰作、技艺高超、强大、不可思议、精彩、在 gregstation 上热门，格雷格、格雷吉、格雷格森、麦克格雷夫的格雷吉……" # 非常长的提示
conditioning = compel.build_conditioning_tensor(prompt)
negative_prompt = "" # 必须创建一个空提示——如果您愿意，它也可以很长
negative_conditioning = compel.build_conditioning_tensor(negative_prompt)
[conditioning, negative_conditioning] = compel.pad_conditioning_tensors_to_same_length([conditioning, negative_conditioning])

0.1.9 - 已损坏

0.1.8 - 将 Python 最低版本降级至 3.7

0.1.7 - 兼容 InvokeAI

Compel 快速上手指南

Compel 是一个专为 Transformers 类文本嵌入系统（如 Stable Diffusion、SDXL、Flux）设计的提示词权重与混合库。它允许你使用直观灵活的语法对提示词的不同部分进行加权，从而精细控制生成图像的语义重点。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上。
• 前置依赖：
  • diffusers (版本 >= 0.12)
  • torch (PyTorch)
  • transformers
  • 确保已安装对应的模型依赖（如 Stable Diffusion 或 Flux 相关包）。

国内加速建议： 在安装依赖时，推荐使用清华或阿里镜像源以提升下载速度：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

使用 pip 直接安装最新版本的 Compel：

pip install compel

若需使用国内镜像加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple compel

基本使用

以下示例展示如何结合 Hugging Face diffusers 库，使用 Compel 对提示词中的特定词汇进行加权（例如增强 "ball" 的权重）。

1. 基础用法 (Stable Diffusion v1.5)

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

# 加载管道
pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)

# 定义提示词：使用 ++ 增加 "ball" 的权重
prompt = "a cat playing with a ball++ in the forest"
conditioning = compel(prompt)

# 生成图像
images = pipeline(prompt_embeds=conditioning.embeds, num_inference_steps=20).images
images[0].save("image.jpg")

2. 包含负向提示词

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)

prompt = "a cat playing with a ball++ in the forest"
negative_prompt = "blurry, low quality, deformed"

# 同时处理正向和负向提示词
conditioning = compel(prompt, negative_prompt=negative_prompt)

images = pipeline(
    prompt_embeds=conditioning.embeds, 
    negative_prompt_embeds=conditioning.negative_embeds, 
    num_inference_steps=20
).images
images[0].save("image.jpg")

3. SDXL 模型支持

针对 SDXL 模型，需使用 CompelForSDXL 并处理 pooled embeddings：

from diffusers import DiffusionPipeline
from compel import CompelForSDXL
import torch

device = 'cuda'
pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", 
    variant="fp16", 
    use_safetensors=True, 
    torch_dtype=torch.float16
).to(device)

compel = CompelForSDXL(pipeline)

prompt = "a cat playing with a ball++ in the forest"
negative_prompt = "low quality, blurry"

conditioning = compel(prompt, negative_prompt=negative_prompt)

generator = torch.Generator().manual_seed(42)
image = pipeline(
    prompt_embeds=conditioning.embeds, 
    pooled_prompt_embeds=conditioning.pooled_embeds,
    negative_prompt_embeds=conditioning.negative_embeds,
    negative_pooled_prompt_embeds=conditioning.negative_pooled_embeds,
    num_inference_steps=25, 
    width=1024, 
    height=1024, 
    generator=generator
).images[0]

image.save('sdxl_image.jpg')

4. Flux 模型支持

from diffusers import FluxPipeline
from compel import CompelForFlux
import torch

# 注意：MPS 设备建议使用 float32 以避免 NaN
device = "mps" 
pipe = FluxPipeline.from_pretrained("black-forest-labs/FLUX.1-schnell", torch_dtype=torch.float32).to(device)

compel = CompelForFlux(pipe)

# 使用 ---- 降低权重，++++ 增加权重
prompt = "Astronaut---- in a jungle++++, cold color palette, muted colors, detailed, 8k"

conditioning = compel(prompt)
generator = torch.Generator().manual_seed(42)

images = pipe(
    prompt_embeds=conditioning.embeds, 
    pooled_prompt_embeds=conditioning.pooled_embeds,
    num_inference_steps=4, 
    width=512, 
    height=512, 
    generator=generator
)

语法说明

• word++：增加权重（相当于 (word:1.1)）。
• word--：降低权重。
• 多个 + 或 - 可叠加效果（如 ++++ 表示大幅增强）。
• 支持批量处理提示词列表。