#
# 根据 Apache 许可证 2.0 版本（“许可证”）授权
# 您只能在遵守许可证的情况下使用本文件。
# 您可以在以下位置获取许可证副本
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 除非适用法律要求或双方书面同意，软件
# 根据许可证分发，本软件按“原样”
# 不附带任何明示或暗示的保证或条件。
# 请参阅许可证中关于权限的具体语言
# 许可证下的限制。
-->

# ConsisID

  

来自北京大学、罗切斯特大学等机构的 [基于频率分解的身份保持文本到视频生成](https://huggingface.co/papers/2411.17440)，作者为 Shenghai Yuan、Jinfa Huang、Xianyi He、Yunyang Ge、Yujun Shi、Liuhan Chen、Jiebo Luo、Li Yuan。

该论文的摘要如下：

*保持身份一致性的文本到视频（IPT2V）生成旨在创建具有稳定人物身份的高保真视频。这是视频生成中的一项重要任务，但对于生成式模型而言仍是一个未解决的问题。本文在文献中尚未解决的 IPT2V 技术前沿上推进了两个方向：（1）一个无需繁琐的逐案例微调的免调优（tuning-free）流水线，以及（2）一种频率感知的启发式身份保持 Diffusion Transformer（DiT）控制方案。为实现这些目标，我们提出了 **ConsisID**，这是一个基于 DiT 的免调优可控 IPT2V 模型，旨在使生成视频中的人物身**id**份（identity）保持一**consis**致（tency）。受视觉/扩散 Transformer 频率分析中先前发现的启发，它在频率域中使用身份控制信号，其中面部特征可以分解为低频全局特征（例如，轮廓、比例）和高频内在特征（例如，不受姿态变化影响的身份标记）。首先，从低频角度出发，我们引入了一个全局面部提取器，它将参考图像和面部关键点编码到潜在空间中，生成富含低频信息的特征。然后，将这些特征集成到网络的浅层中，以缓解与 DiT 相关的训练挑战。其次，从高频角度出发，我们设计了一个局部面部提取器来捕获高频细节，并将其注入 Transformer 块中，以增强模型保留细粒度特征的能力。为了利用频率信息进行身份保持，我们提出了一种分层训练策略，将一个普通的预训练视频生成模型转化为 IPT2V 模型。大量实验表明，我们的频率感知启发式方案为基于 DiT 的模型提供了最优的控制解决方案。得益于该方案，我们的 **ConsisID** 在生成高质量、保持身份一致性的视频方面取得了优异的结果，朝着更有效的 IPT2V 迈出了重要一步。ConsisID 的模型权重已公开于 https://github.com/PKU-YuanGroup/ConsisID。*

> [!TIP]
> 请务必参阅 [调度器指南](../../using-diffusers/schedulers)，了解如何探索调度器速度与质量之间的权衡，并查看 [跨流水线复用组件](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) 部分，了解如何高效地将相同组件加载到多个流水线中。

此流水线由 [SHYuanBest](https://github.com/SHYuanBest) 贡献。原始代码库可在 [此处](https://github.com/PKU-YuanGroup/ConsisID) 找到。原始权重可在 [hf.co/BestWishYsh](https://huggingface.co/BestWishYsh) 下找到。

有两个官方的 ConsisID 检查点，用于保持身份一致性的文本到视频生成。

| 检查点 | 推荐的推理数据类型 |
|:---:|:---:|
| [`BestWishYsh/ConsisID-preview`](https://huggingface.co/BestWishYsh/ConsisID-preview) | torch.bfloat16 |
| [`BestWishYsh/ConsisID-1.5`](https://huggingface.co/BestWishYsh/ConsisID-preview) | torch.bfloat16 |

### 内存优化

ConsisID 在解码 49 帧（8 FPS 下 6 秒的视频）且输出分辨率为 720x480（宽 x 高）时，大约需要 44 GB 的 GPU 显存，因此无法在消费级 GPU 或免费层级的 T4 Colab 上运行。可以使用以下显存优化方法来降低显存占用。如需复现，请参考 [此](https://gist.github.com/SHYuanBest/bc4207c36f454f9e969adbb50eaf8258) 脚本。

| 功能（覆盖之前的） | 最大内存分配 | 最大预留内存 |
| :----------------------------- | :------------------- | :------------------ |
| -                              | 37 GB                | 44 GB               |
| enable_model_cpu_offload       | 22 GB                | 25 GB               |
| enable_sequential_cpu_offload  | 16 GB                | 22 GB               |
| vae.enable_slicing             | 16 GB                | 22 GB               |
| vae.enable_tiling              | 5 GB                 | 7 GB                |

## 加载模型检查点

模型权重可能存储在 Hub 或本地的不同子文件夹中，在这种情况下，您应使用 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 方法。

```python
# !pip install consisid_eva_clip insightface facexlib
import torch
from diffusers import ConsisIDPipeline
from diffusers.pipelines.consisid.consisid_utils import prepare_face_models, process_face_embeddings_infer
from huggingface_hub import snapshot_download

# Download ckpts
snapshot_download(repo_id="BestWishYsh/ConsisID-preview", local_dir="BestWishYsh/ConsisID-preview")

# Load face helper model to preprocess input face image
face_helper_1, face_helper_2, face_clip_model, face_main_model, eva_transform_mean, eva_transform_std = prepare_face_models("BestWishYsh/ConsisID-preview", device="cuda", dtype=torch.bfloat16)  # or "mps", "xpu", "cpu"

# Load consisid base model
pipe = ConsisIDPipeline.from_pretrained("BestWishYsh/ConsisID-preview", dtype=torch.bfloat16)
pipe.to("cuda")
```

## 保持身份一致性的文本到视频

对于保持身份一致性的文本生成视频任务，请传入文本提示词以及一张包含清晰人脸的图像（例如，最好为半身或全身照）。默认情况下，ConsisID 会生成 720x480 的视频，以获得最佳效果。

```python
from diffusers.utils import export_to_video

prompt = "The video captures a boy walking along a city street, filmed in black and white on a classic 35mm camera. His expression is thoughtful, his brow slightly furrowed as if he's lost in contemplation. The film grain adds a textured, timeless quality to the image, evoking a sense of nostalgia. Around him, the cityscape is filled with vintage buildings, cobblestone sidewalks, and softly blurred figures passing by, their outlines faint and indistinct. Streetlights cast a gentle glow, while shadows play across the boy's path, adding depth to the scene. The lighting highlights the boy's subtle smile, hinting at a fleeting moment of curiosity. The overall cinematic atmosphere, complete with classic film still aesthetics and dramatic contrasts, gives the scene an evocative and introspective feel."
image = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/consisid/consisid_input.png?download=true"

id_cond, id_vit_hidden, image, face_kps = process_face_embeddings_infer(face_helper_1, face_clip_model, face_helper_2, eva_transform_mean, eva_transform_std, face_main_model, "cuda", torch.bfloat16, image, is_align_face=True)

video = pipe(image=image, prompt=prompt, num_inference_steps=50, guidance_scale=6.0, use_dynamic_cfg=False, id_vit_hidden=id_vit_hidden, id_cond=id_cond, kps_cond=face_kps, generator=torch.Generator("cuda").manual_seed(42))
export_to_video(video.frames[0], "output.mp4", fps=8)
```

  
    人脸图像视频描述
  
  
    
    
    这段视频采用精美制作的动画风格，展现了一位自信的女性骑着马穿过郁郁葱葱的林间空地。她神情专注而宁静，熟练地用手调整着宽檐帽。她身穿飘逸的波西米亚长裙，裙摆随着马的节奏优雅地摆动，面料在动画的动态中流畅地飘动。斑驳的阳光透过树冠洒落，在林间地面上投下柔和的、如画般的图案。她的姿态从容不迫，在轻松驾驭马匹的同时，展现出掌控力与优雅。动画柔和流畅的风格为场景增添了一种梦幻般的质感，女性平静的神态与宁静的环境共同唤起一种自由与和谐的感觉。
  
  
    
    
    这段视频以引人入胜的动画风格呈现，画面中一位女子伫立在雪林中央，目光专注地凝视前方，缓缓伸出手臂。她身披深蓝色斗篷，在寒冷的空气中，她呼出的气息清晰可见，并以柔和空灵的笔触加以描绘。当她召唤出一缕冰霜魔法时，她的嘴角浮现出一丝淡淡的微笑，全神贯注地注视着周围的树木和地面开始闪烁并冻结，覆盖上精致的冰晶。动画流畅的动态效果让魔法栩栩如生，霜花以复杂而闪耀的图案向外蔓延。环境以柔和的水彩般色调渲染，进一步烘托出梦幻般的魔法氛围。整体氛围宁静而充满力量，静谧的冬日空气放大了这冰封景象的精致之美。
  
  
    
    
    这段动画描绘了一位在微风中伫立的气球小贩的俏皮肖像，柔和朦胧的笔触营造出宁静春日般的氛围。他的脸庞被温和的微笑所环绕，双眼因阳光而微微眯起，几缕发丝随风轻扬。他身穿一件浅淡的粉彩衬衫，周围的气球随风摇曳，为画面增添了几分俏皮感。背景柔和地虚化，隐约可见充满活力的集市或公园，进一步烘托出这一刻轻松愉悦却又温柔细腻的情绪。
  
  
    
    
    这段视频捕捉了一个男孩沿着城市街道行走的画面，由一台经典的 35mm 相机以黑白胶片拍摄。他的神情若有所思，眉头微蹙，仿佛陷入了沉思。胶片颗粒为画面增添了富有质感的永恒气息，唤起一种怀旧感。在他周围，城市景观中充满了复古的建筑、鹅卵石人行道，以及模糊地匆匆而过的人影，他们的轮廓隐约而模糊。路灯投下柔和的光芒，阴影在男孩的行进路径上交错，为场景增添了层次感。光线突出了男孩嘴角那抹含蓄的微笑，暗示着一丝转瞬即逝的好奇。整体电影般的氛围，配合经典电影静帧的美学风格和强烈的明暗对比，赋予场景一种引人遐想且内省的感觉。
  
  
    
    
    视频中的宝宝身穿一件色彩鲜艳的超级英雄披风，自信地站立着，双臂高举，摆出充满力量的姿势。宝宝神情坚定，双眼圆睁，嘴唇紧抿，全神贯注，仿佛随时准备迎接挑战。场景显得活泼有趣，周围散落着五颜六色的玩具，脚下铺着柔软的地毯，阳光透过附近的窗户洒进来，照亮了飘动的披风，更增添了英雄气概。整体氛围轻松愉快，宝宝的表情捕捉到了天真与可爱勇敢尝试的混合，仿佛真的准备好拯救世界了。
  

## 资源

通过以下资源进一步了解 ConsisID。
- 演示 ConsisID 主要功能的[视频](https://www.youtube.com/watch?v=PhlgC-bI5SQ)。
- 有关更多详细信息，请参阅研究论文 [通过频率分解实现身份保持的文本到视频生成](https://hf.co/papers/2411.17440)。

## ConsisIDPipeline[[diffusers.ConsisIDPipeline]]

#### diffusers.ConsisIDPipeline[[diffusers.ConsisIDPipeline]]

```python
diffusers.ConsisIDPipeline(*args, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/dummy_torch_and_transformers_and_opencv_objects.py#L5)

#### __调用__[[diffusers.ConsisIDPipeline.__call__]]

```python
__call__(*args, **kwargs)
```

将 self 作为函数调用。

## ConsisIDPipelineOutput[[diffusers.pipelines.consisid.pipeline_output.ConsisIDPipelineOutput]]

#### diffusers.pipelines.consisid.pipeline_output.ConsisIDPipelineOutput[[diffusers.pipelines.consisid.pipeline_output.ConsisIDPipelineOutput]]

```python
diffusers.pipelines.consisid.pipeline_output.ConsisIDPipelineOutput(frames: Tensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/consisid/pipeline_output.py#L9)

**参数：**

frames (`torch.Tensor`、`np.ndarray` 或 list[list[PIL.Image.Image]]) : 视频输出列表 - 它可以是一个长度为 `batch_size,` 的嵌套列表，其中每个子列表包含长度为 `num_frames.` 的去噪 PIL 图像序列。它也可以是一个形状为 `(batch_size, num_frames, channels, height, width)` 的 NumPy 数组或 Torch 张量。

ConsisID 管道的输出类。