#
# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
# このファイルは、ライセンスに準拠した場合にのみ使用できます。
# ライセンスのコピーは以下から入手できます
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
# 権限を管理する特定の言語については、ライセンスを参照してください。
# ライセンスの下での制限事項。
-->

# ConsisID

  

北京大学およびロチェスター大学などによる Shenghai Yuan, Jinfa Huang, Xianyi He, Yunyang Ge, Yujun Shi, Liuhan Chen, Jiebo Luo, Li Yuan による [Identity-Preserving Text-to-Video Generation by Frequency Decomposition](https://huggingface.co/papers/2411.17440)

論文の抄録は以下の通りです：

*アイデンティティを保持したテキストから動画への生成（IPT2V）は、人間のアイデンティティが一貫した高忠実度の動画を生成することを目的としています。これは動画生成における重要なタスクですが、生成モデルにとって未解決の問題として残っています。本論文では、文献において未解決であった2つの方向性からIPT2Vの技術的フロンティアを押し広げます：(1) 面倒なケースバイケースのファインチューニングを必要としないチューニングフリーのパイプライン、および (2) 周波数認識型のヒューリスティックなアイデンティティ保持型Diffusion Transformer（DiT）ベースの制御スキーム。これらの目標を達成するために、私たちは、生成された動画内で人間の**id**entity **consis**tentを維持するための、チューニングフリーのDiTベースの制御可能なIPT2Vモデルである**ConsisID**を提案します。ビジョン/拡散トランスフォーマーの周波数分析に関する先行研究の知見に着想を得て、顔の特徴を低周波数のグローバル特徴（例：プロファイル、比率）と高周波数の固有特徴（例：ポーズの変化に影響を受けないアイデンティティマーカー）に分解できる周波数領域で、アイデンティティ制御シグナルを用います。まず、低周波数の観点から、グローバルな顔エクストラクターを導入し、参照画像と顔のキーポイントを潜在空間にエンコードして、低周波数情報が豊富に含まれた特徴を生成します。これらの特徴は、DiTに関連するトレーニングの課題を軽減するために、ネットワークの浅い層に統合されます。次に、高周波数の観点から、高周波数の詳細をキャプチャし、トランスフォーマーブロックに注入するローカルな顔エクストラクターを設計し、モデルが細粒度の特徴を保持する能力を強化します。周波数情報を利用してアイデンティティを保持するために、階層的なトレーニング戦略を提案し、バニラの事前学習済み動画生成モデルを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の公式チェックポイントが2つあります。

| チェックポイント | 推奨される推論用データ型 |
|:---:|:---:|
| [`BestWishYsh/ConsisID-preview`](https://huggingface.co/BestWishYsh/ConsisID-preview) | torch.bfloat16 |
| [`BestWishYsh/ConsisID-1.5`](https://huggingface.co/BestWishYsh/ConsisID-preview) | torch.bfloat16 |

### メモリ最適化

ConsisID は、出力解像度 720x480 (W x H) で 49 フレーム (8 FPS での 6 秒間の動画) をデコードするために約 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/ja/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)

#### __call__[[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 パイプライン用の出力クラスです。