hf-doc-build/doc / diffusers /main /ko /api /pipelines /cogvideox.md

|

raw

64.4 kB

Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.

이 파일은 라이선스에 따라만 사용할 수 있습니다.

라이선스 사본은 다음에서 가져올 수 있습니다

http://www.apache.org/licenses/LICENSE-2.0

적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어

라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"

명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.

권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요

라이선스 하의 제한 사항.

-->

CogVideoX

CogVideoX는 텍스트에서 더 길고 일관된 영상을 생성하도록 설계된 대규모 diffusion transformer 모델로, 2B 및 5B 파라미터 버전이 제공됩니다. 이 모델은 3D causal variational autoencoder를 사용하여 시퀀스 길이(및 관련 학습 컴퓨트)를 줄이고 생성된 영상에서 발생하는 깜빡임을 방지함으로써 영상 데이터를 보다 효율적으로 처리합니다. 적응형 LayerNorm을 갖춘 "expert" transformer는 텍스트와 영상 간의 정렬을 개선하고, 3D full attention은 생성된 영상에서 움직임과 시간을 정확하게 포착하는 데 도움을 줍니다.

모든 원본 CogVideoX 체크포인트는 CogVideoX 컬렉션에서 찾을 수 있습니다.

CogVideoX 모델에 대한 다른 비디오 생성 작업의 예시를 보려면 오른쪽 사이드바의 CogVideoX 모델을 클릭하세요.

…

다양한 메모리 절약 기법에 대한 자세한 내용은 메모리 사용량 줄이기 가이드를 참조하세요.

아래의 양자화된 CogVideoX 5B 모델은 약 16GB의 VRAM이 필요합니다.

import torch
from diffusers import CogVideoXPipeline, AutoModel, TorchAoConfig
from diffusers.quantizers import PipelineQuantizationConfig
from diffusers.hooks import apply_group_offloading
from diffusers.utils import export_to_video
from torchao.quantization import Int8WeightOnlyConfig

# quantize weights to int8 with torchao
pipeline_quant_config = PipelineQuantizationConfig(
  quant_mapping={"transformer": TorchAoConfig(Int8WeightOnlyConfig())}
)

# fp8 layerwise weight-casting
transformer = AutoModel.from_pretrained(
    "THUDM/CogVideoX-5b",
    subfolder="transformer",
    dtype=torch.bfloat16
)
transformer.enable_layerwise_casting(
    storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16
)

pipeline = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5b",
    transformer=transformer,
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

# model-offloading
pipeline.enable_model_cpu_offload()

prompt = """
A detailed wooden toy ship with intricately carved masts and sails is seen gliding smoothly over a plush, blue carpet that mimics the waves of the sea. 
The ship's hull is painted a rich brown, with tiny windows. The carpet, soft and textured, provides a perfect backdrop, resembling an oceanic expanse. 
Surrounding the ship are various other toys and children's items, hinting at a playful environment. The scene captures the innocence and imagination of childhood, 
with the toy ship's journey symbolizing endless adventures in a whimsical, indoor setting.
"""

video = pipeline(
    prompt=prompt,
    guidance_scale=6,
    num_inference_steps=50
).frames[0]
export_to_video(video, "output.mp4", fps=8)

Compilation은 첫 번째 호출 시 느리지만, 이후 pipeline 호출은 더 빠릅니다.

80GB A100에서 torch.compile을 적용한 평균 추론 시간은 76.27초로, 컴파일되지 않은 모델의 96.89초보다 빠릅니다.

import torch
from diffusers import CogVideoXPipeline
from diffusers.utils import export_to_video

pipeline = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-2b",
    dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

# torch.compile
pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.transformer = torch.compile(
    pipeline.transformer, mode="max-autotune", fullgraph=True
)

prompt = """
A detailed wooden toy ship with intricately carved masts and sails is seen gliding smoothly over a plush, blue carpet that mimics the waves of the sea. 
The ship's hull is painted a rich brown, with tiny windows. The carpet, soft and textured, provides a perfect backdrop, resembling an oceanic expanse. 
Surrounding the ship are various other toys and children's items, hinting at a playful environment. The scene captures the innocence and imagination of childhood, 
with the toy ship's journey symbolizing endless adventures in a whimsical, indoor setting.
"""

video = pipeline(
    prompt=prompt,
    guidance_scale=6,
    num_inference_steps=50
).frames[0]
export_to_video(video, "output.mp4", fps=8)

The input is a single word "Notes".

참고

CogVideoX는 load_lora_weights()를 통해 LoRA를 지원합니다.

예제 코드 보기

import torch
from diffusers import CogVideoXPipeline
from diffusers.hooks import apply_group_offloading
from diffusers.utils import export_to_video

pipeline = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5b",
    dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

# load LoRA weights
pipeline.load_lora_weights("finetrainers/CogVideoX-1.5-crush-smol-v0", adapter_name="crush-lora")
pipeline.set_adapters("crush-lora", 0.9)

# model-offloading
pipeline.enable_model_cpu_offload()

prompt = """
PIKA_CRUSH A large metal cylinder is seen pressing down on a pile of Oreo cookies, flattening them as if they were under a hydraulic press.
"""
negative_prompt = "inconsistent motion, blurry motion, worse quality, degenerate outputs, deformed outputs"

video = pipeline(
    prompt=prompt, 
    negative_prompt=negative_prompt, 
    num_frames=81, 
    height=480,
    width=768,
    num_inference_steps=50
).frames[0]
export_to_video(video, "output.mp4", fps=16)

텍스트-투-비디오(T2V) 체크포인트는 사전 학습에 사용된 해상도가 1360x768이므로 이 해상도에서 가장 잘 작동합니다.
이미지-비디오(I2V) 체크포인트는 여러 해상도와 함께 작동합니다. 너비는 768에서 1360까지 다양할 수 있지만, 높이는 758이어야 합니다. 높이와 너비 모두 16으로 나누어떨어져야 합니다.
T2V와 I2V 체크포인트 모두 81프레임과 161프레임에서 가장 잘 작동합니다. 생성된 비디오는 16fps로 내보내는 것이 권장됩니다.

…

method	메모리 사용량 (활성화됨)	메모리 사용량(비활성화됨)
enable_model_cpu_offload	19GB	33GB
enable_sequential_cpu_offload	<4GB	~33GB (추론 속도가 매우 느림)
enable_tiling	11GB (enable_model_cpu_offload 사용 시)	---

CogVideoXPipeline[[diffusers.CogVideoXPipeline]]

diffusers.CogVideoXPipeline[[diffusers.CogVideoXPipeline]]

diffusers.CogVideoXPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKLCogVideoX, transformer: CogVideoXTransformer3DModel, scheduler: diffusers.schedulers.scheduling_ddim_cogvideox.CogVideoXDDIMScheduler | diffusers.schedulers.scheduling_dpm_cogvideox.CogVideoXDPMScheduler)

소스

매개변수:

vae (AutoencoderKL) : 비디오를 잠재 표현으로 인코딩하고 디코딩하는 Variational Auto-Encoder (VAE) 모델.

text_encoder (T5EncoderModel) : 고정된 텍스트 인코더입니다. CogVideoX는 T5를 사용하며, 구체적으로 t5-v1_1-xxl 변형을 사용합니다.

tokenizer (T5Tokenizer) : T5Tokenizer 클래스의 토크나이저.

transformer (CogVideoXTransformer3DModel) : 인코딩된 비디오 잠재를 디노이즈하기 위한 텍스트 조건부 CogVideoXTransformer3DModel입니다.

scheduler (SchedulerMixin) : transformer와 함께 사용되어 인코딩된 비디오 latents의 노이즈를 제거하는 스케줄러입니다.

CogVideoX를 사용한 텍스트-비디오 생성을 위한 Pipeline

이 모델은 DiffusionPipeline에서 상속됩니다. 라이브러리가 모든 파이프라인에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

호출[[diffusers.CogVideoXPipeline.call]]

__call__(prompt: str | list[str] | None = None, negative_prompt: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_frames: int | None = None, num_inference_steps: int = 50, timesteps: list[int] | None = None, guidance_scale: float = 6, use_dynamic_cfg: bool = False, num_videos_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 226)

소스

매개변수:

prompt (str 또는 list[str], 선택 사항) : 이미지 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 prompt_embeds를 대신 전달해야 합니다.

negative_prompt (str 또는 list[str], 선택 사항) : 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 negative_prompt_embeds를 전달해야 합니다. 가이던스를 사용하지 않는 경우 무시됩니다(즉, guidance_scale이 1보다 작은 경우 무시됩니다).

height (int, 선택 사항, 기본값은 self.transformer.config.sample_height * self.vae_scale_factor_spatial) : 생성된 이미지의 픽셀 단위 높이입니다. 최적의 결과를 위해 기본값은 480으로 설정되어 있습니다.

width (int, 선택 사항, 기본값은 self.transformer.config.sample_height * self.vae_scale_factor_spatial) : 생성된 이미지의 픽셀 단위 너비입니다. 최적의 결과를 위해 기본값은 720으로 설정됩니다.

num_frames (int, 기본값 48) : 생성할 프레임 수. self.vae_scale_factor_temporal로 나누어떨어져야 합니다. CogVideoX는 num_seconds가 6이고 fps가 8인 (num_seconds * fps + 1) 프레임으로 조건부 생성되므로, 생성된 비디오에는 1개의 추가 프레임이 포함됩니다. 그러나 비디오는 임의의 fps로 저장할 수 있으므로, 충족해야 할 유일한 조건은 위에서 언급한 나누어떨어짐 조건입니다.

num_inference_steps (int, 선택 사항, 기본값 50) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

timesteps (list[int], 선택 사항) : set_timesteps 메서드에 timesteps 인수를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 타임스텝입니다. 정의되지 않은 경우, num_inference_steps가 전달될 때의 기본 동작이 사용됩니다. 내림차순으로 정렬되어 있어야 합니다.

guidance_scale (float, 선택 사항, 기본값 7.0) : Classifier-Free Diffusion Guidance에서 정의한 가이던스 스케일입니다. guidance_scale은 Imagen Paper의 2번 식의 w로 정의됩니다. guidance_scale > 1을 설정하여 가이던스 스케일을 활성화합니다. 가이던스 스케일이 높을수록 prompt 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다.

use_dynamic_cfg (bool, 선택 사항, 기본값 False) : True인 경우 추론 중에 guidance scale을 동적으로 조정합니다.

num_videos_per_prompt (int, 선택 사항, 기본값 1) : 프롬프트당 생성할 비디오의 수입니다.

eta (float, 선택 사항, 기본값 0.0) : DDIM 논문에서 정의한 파라미터 eta (η)에 해당합니다. DDIMScheduler에만 적용되며, 다른 스케줄러에서는 무시됩니다.

generator (torch.Generator 또는 list[torch.Generator], 선택 사항) : 생성을 결정적으로 만들기 위한 torch generator 하나 또는 목록.

latents (torch.FloatTensor, 선택 사항) : 이미지 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 generator를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

prompt_embeds (torch.FloatTensor, 선택 사항) : 미리 생성된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, 예를 들어 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 prompt 입력 인자로부터 텍스트 임베딩이 생성됩니다.

negative_prompt_embeds (torch.FloatTensor, 선택) : 미리 생성된 부정 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, 예를 들어 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 negative_prompt 입력 인수에서 negative_prompt_embeds가 생성됩니다.

output_type (str, 선택 사항, 기본값 "pil") : 이미지 생성의 출력 형식입니다. PIL: PIL.Image.Image 또는 np.array 중 하나를 선택합니다.

return_dict (bool, 선택 사항, 기본값 True) : 일반 튜플 대신 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput을 반환할지 여부.

attention_kwargs (dict, 선택 사항) : 지정된 경우 diffusers.models.attention_processor의 self.processor 아래에서 정의된 AttentionProcessor로 전달되는 kwargs 사전입니다.

callback_on_step_end (Callable, 선택 사항) : 추론 중 각 디노이징 단계의 끝에서 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs에는 callback_on_step_end_tensor_inputs로 지정된 모든 텐서 목록이 포함됩니다.

callback_on_step_end_tensor_inputs (list, 선택 사항) : callback_on_step_end 함수의 텐서 입력 목록입니다. 목록에 지정된 텐서는 callback_kwargs 인수로 전달됩니다. 파이프라인 클래스의 ._callback_tensor_inputs 속성에 나열된 변수만 포함할 수 있습니다.

max_sequence_length (int, 기본값 226) : 인코딩된 프롬프트의 최대 시퀀스 길이입니다. self.transformer.config.max_text_seq_length와 일치하지 않으면 결과가 저하될 수 있습니다.

반환값: CogVideoXPipelineOutput 또는 tuple

return_dict이 True인 경우 CogVideoXPipelineOutput, 그렇지 않으면 tuple입니다. tuple을 반환할 경우 첫 번째 요소는 생성된 이미지 목록입니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:

>>> import torch
>>> from diffusers import CogVideoXPipeline
>>> from diffusers.utils import export_to_video

>>> # Models: "THUDM/CogVideoX-2b" or "THUDM/CogVideoX-5b"
>>> pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-2b", torch_dtype=torch.float16).to("cuda")
>>> prompt = (
...     "A panda, dressed in a small, red jacket and a tiny hat, sits on a wooden stool in a serene bamboo forest. "
...     "The panda's fluffy paws strum a miniature acoustic guitar, producing soft, melodic tunes. Nearby, a few other "
...     "pandas gather, watching curiously and some clapping in rhythm. Sunlight filters through the tall bamboo, "
...     "casting a gentle glow on the scene. The panda's face is expressive, showing concentration and joy as it plays. "
...     "The background includes a small, flowing stream and vibrant green foliage, enhancing the peaceful and magical "
...     "atmosphere of this unique musical performance."
... )
>>> video = pipe(prompt=prompt, guidance_scale=6, num_inference_steps=50).frames[0]
>>> export_to_video(video, "output.mp4", fps=8)

encode_prompt[[diffusers.CogVideoXPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 226, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

소스

매개변수:

prompt (str 또는 list[str], 선택 사항) : 인코딩할 프롬프트

negative_prompt (str 또는 list[str], 선택 사항) : 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 negative_prompt_embeds를 전달해야 합니다. 가이던스를 사용하지 않는 경우 무시됩니다(즉, guidance_scale이 1보다 작은 경우 무시됩니다).

do_classifier_free_guidance (bool, 선택 사항, 기본값 True) : classifier free guidance를 사용할지 여부.

num_videos_per_prompt (int, 선택 사항, 기본값 1) : 프롬프트당 생성할 비디오의 수. 결과 임베딩을 배치할 torch 장치

prompt_embeds (torch.Tensor, 선택 사항) : 미리 생성된 텍스트 임베딩입니다. 예를 들어 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 prompt 입력 인자에서 텍스트 임베딩이 생성됩니다.

negative_prompt_embeds (torch.Tensor, 선택 사항) : 미리 생성된 부정 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, 예를 들어 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 negative_prompt 입력 인수에서 negative_prompt_embeds가 생성됩니다.

device : (torch.device, 선택 사항): torch device

dtype : (torch.dtype, 선택 사항): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

fuse_qkv_projections[[diffusers.CogVideoXPipeline.fuse_qkv_projections]]

fuse_qkv_projections()

소스

융합된 QKV 투영을 활성화합니다.

unfuse_qkv_projections[[diffusers.CogVideoXPipeline.unfuse_qkv_projections]]

unfuse_qkv_projections()

소스

활성화된 경우 QKV 투영 융합을 비활성화합니다.

CogVideoXImageToVideoPipeline[[diffusers.CogVideoXImageToVideoPipeline]]

diffusers.CogVideoXImageToVideoPipeline[[diffusers.CogVideoXImageToVideoPipeline]]

diffusers.CogVideoXImageToVideoPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKLCogVideoX, transformer: CogVideoXTransformer3DModel, scheduler: diffusers.schedulers.scheduling_ddim_cogvideox.CogVideoXDDIMScheduler | diffusers.schedulers.scheduling_dpm_cogvideox.CogVideoXDPMScheduler)

소스

매개변수:

vae (AutoencoderKL) : 비디오를 잠재 표현으로 인코딩하고 디코딩하는 Variational Auto-Encoder (VAE) 모델.

text_encoder (T5EncoderModel) : 고정된 텍스트 인코더입니다. CogVideoX는 T5를 사용하며, 구체적으로 t5-v1_1-xxl 변형을 사용합니다.

tokenizer (T5Tokenizer) : T5Tokenizer 클래스의 토크나이저.

transformer (CogVideoXTransformer3DModel) : 인코딩된 비디오 잠재를 디노이즈하기 위한 텍스트 조건부 CogVideoXTransformer3DModel입니다.

scheduler (SchedulerMixin) : transformer와 함께 사용되어 인코딩된 비디오 latents의 노이즈를 제거하는 스케줄러입니다.

CogVideoX를 사용한 이미지-비디오 생성을 위한 Pipeline

이 모델은 DiffusionPipeline에서 상속됩니다. 라이브러리가 모든 파이프라인에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

호출[[diffusers.CogVideoXImageToVideoPipeline.call]]

__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], prompt: str | list[str] | None = None, negative_prompt: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_frames: int = 49, num_inference_steps: int = 50, timesteps: list[int] | None = None, guidance_scale: float = 6, use_dynamic_cfg: bool = False, num_videos_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 226)

소스

매개변수:

image (PipelineImageInput) : 생성을 조건화할 입력 이미지. 이미지, 이미지 목록 또는 torch.Tensor여야 합니다.