Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /ko /api /pipelines /echo.md

mishig

2 days ago

preview code

download

raw

9.19 kB

#
# Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
# 이 파일은 라이선스에 따라만 사용할 수 있습니다.
# 라이선스 사본은 다음에서 가져올 수 있습니다
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어
# 라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"
# 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.
# 권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요
# 라이선스 하의 제한 사항. -->

# Echo

[Echo](https://github.com/jd-opensource/JoyAI-Echo)는 장시간 영상 생성 모델입니다. 선택적인 클린 첫 프레임, 순서화된 이미지/오디오 메모리 슬롯, 그리고 확률적 소수 스텝 Distribution Matching Distillation (DMD) 샘플러를 지원합니다. 이 파이프라인은 동기화된 영상과 오디오를 생성합니다.

Echo는 [ModularPipeline](/docs/diffusers/v0.43.0/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline)으로 구현되어 있어 텍스트 인코딩, 메모리 조건화, 확률적 DMD 디노이징, 디코딩 블록을 완전한 워크플로로 실행하거나 독립적으로 조합할 수 있습니다.

## 추론

공식 [jdopensource/JoyAI-Echo](https://huggingface.co/jdopensource/JoyAI-Echo) 체크포인트를 직접 로드합니다. 이 모델은 [google/gemma-3-12b-it](https://huggingface.co/google/gemma-3-12b-it)의 텍스트 인코더와 토크나이저를 사용합니다. Gemma 저장소는 게이트가 적용되어 있으므로, 파이프라인을 로드하기 전에 해당 라이선스에 동의하고 Hugging Face로 인증해야 합니다.

공개된 모델은 긴 영상 예시에서 241프레임을 사용합니다. 출력 컨테이너의 프레임 레이트와 무관하게, 영상 RoPE 좌표는 학습 시 사용된 24fps로 유지됩니다.

```py
import torch
import torchaudio
from PIL import Image
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import encode_video
manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("jdopensource/JoyAI-Echo", components_manager=manager)
pipe.load_components(dtype={"default": torch.bfloat16, "audio_vae": torch.float32})
manager.enable_auto_cpu_offload(device="cuda")
pipe.vae.enable_tiling()
first_frame = Image.open("first_frame.png").convert("RGB")
memory_images = [Image.open(path).convert("RGB") for path in ["memory_0.png", "memory_1.png"]]
memory_audio_with_rates = [torchaudio.load(path) for path in ["memory_0.wav", "memory_1.wav"]]
memory_audio = [waveform for waveform, _ in memory_audio_with_rates]
memory_audio_rates = [sample_rate for _, sample_rate in memory_audio_with_rates]
output = pipe(
    prompt="A cinematic dialogue scene in a quiet cafe.",
    image=first_frame,
    memory_images=memory_images,
    memory_audio_waveforms=memory_audio,
    memory_audio_sample_rates=memory_audio_rates,
    width=1280,
    height=736,
    num_frames=241,
    frame_rate=25.0,
    model_frame_rate=24.0,
    generator=torch.Generator(device="cuda").manual_seed(42),
    output_type="np",
    output=["videos", "audio"],
)
encode_video(
    output["videos"][0],
    fps=25,
    audio=output["audio"][0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="echo.mp4",
)
```

기본 DMD sigma 스케줄은 공개된 8단계 스케줄입니다. 모든 단계에서 `x0`를 예측하고 다음 sigma에서 새로운 가우시안 노이즈로 재노이즈링을 수행하므로, 시드가 설정된 `torch.Generator`가 초기 노이즈와 모든 중간 재노이즈링을 제어합니다.

Raw 오디오-메모리 인코딩에는 `torchaudio`가 필요합니다. 참조와 동일한 조건을 유지하려면, 위와 같이 `audio_vae`를 FP32로 유지하세요. 모듈형 워크플로에서는 VAE 인코더의 정규화되고 언팩된 텐서를 캐시할 수 있습니다. 비디오 라텐트는 `(batch, channels, frames, height, width)` 형태를, 오디오 라텐트는 `(batch, channels, time, mel_bins)` 형태를 가집니다. 핵심 `denoise` 블록은 해당 텐서를 팩하고, `num_videos_per_prompt`에 맞춰 조건을 확장한 후, 노이즈 제거된 출력을 동일한 VAE 형태로 다시 언팩합니다. 초기 `latents`와 `audio_latents`도 동일한 언팩된 형태로 전달하세요. 디코더는 정규화된 VAE 텐서를 받아, 디코딩 직전에 즉시 비정규화합니다. `output=["latents", "audio_latents"]`를 사용하면 정규화된 VAE 텐서가 반환됩니다. `output_type="latent"`와 `output=["videos", "audio"]`를 함께 사용하면 디코딩 없이 비정규화된 VAE 텐서를 얻을 수 있습니다.

## EchoModularPipeline[[diffusers.EchoModularPipeline]]

#### diffusers.EchoModularPipeline[[diffusers.EchoModularPipeline]]

```python
diffusers.EchoModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/echo/modular_pipeline.py#L27)

Echo 장시간 비디오 DMD 체크포인트용 ModularPipeline.

## EchoBlocks[[diffusers.EchoBlocks]]

#### diffusers.EchoBlocks[[diffusers.EchoBlocks]]

```python
diffusers.EchoBlocks()
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/echo/modular_blocks_echo.py#L220)

clean first-frame conditioning, ordered image/audio memory slots, stochastic DMD denoising를 갖춘 reference-to-video generation을 위한 Echo.

구성 요소: text_encoder (`PreTrainedModel`) tokenizer (`PreTrainedTokenizerBase`) connectors (`LTX2TextConnectors`) vae (`AutoencoderKLLTX2Video`) audio_vae (`AutoencoderKLLTX2Audio`) transformer (`LTX2VideoTransformer3DModel`) video_processor (`VideoProcessor`) vocoder (`LTX2Vocoder`)
Inputs: prompt (`str`): 이미지 생성을 안내하는 프롬프트입니다. max_sequence_length (`int`, *선택 사항*, 기본값 1024): 프롬프트 인코딩을 위한 최대 시퀀스 길이입니다. image (`Image | Tensor`, *선택 사항*): 깨끗한 참조 조건으로 사용되는 선택적 단일 첫 번째 프레임입니다. memory_images (`list`, *선택 사항*): Echo 메모리 슬롯당 하나씩 정렬된 참조 이미지입니다. memory_audio_waveforms (`list`, *선택 사항*): `(channels, samples)` 텐서 형식의 정렬된 메모리 웨이브폼입니다. 9.62초보다 긴 입력은 가장 높은 응답 윈도우로 잘립니다. 무음 슬롯에는 `None`을 사용합니다. memory_audio_sample_rates (`int | list`, *선택 사항*): 모든 메모리 웨이브폼이 공유하는 샘플링 속도 또는 슬롯별 하나의 속도입니다. height (`int`, *선택 사항*, 기본값 512): 생성된 이미지의 픽셀 단위 높이입니다. width (`int`, *선택 사항*, 기본값 704): 생성된 이미지의 픽셀 단위 너비입니다. model_frame_rate (`float`, *선택 사항*, 기본값 24.0): Echo 비디오 RoPE 좌표에 사용되는 학습 시 프레임 속도입니다. memory_position_offset (`float`, *선택 사항*, 기본값 500.0): 첫 번째 메모리 슬롯에 할당되는 시간 중심입니다. memory_position_slot_stride (`float`, *선택 사항*, 기본값 50.0): 연속된 메모리 슬롯 중심 사이의 시간 거리입니다. num_videos_per_prompt (`int`, *선택 사항*, 기본값 1): 프롬프트당 비디오 수입니다. num_frames (`int`, *선택 사항*, 기본값 241): 생성된 픽셀 프레임 수입니다. `1 + k * vae_temporal_compression_ratio`여야 합니다. frame_rate (`float`, *선택 사항*, 기본값 25.0): 생성된 비디오의 프레임 속도입니다. latents (`Tensor`, *선택 사항*): VAE 형식 (B, C, F, H, W)의 선택적 초기 비디오 노이즈입니다. audio_latents (`Tensor`, *선택 사항*): VAE 형식 (B, C, L, M)의 선택적 초기 오디오 노이즈입니다. generator (`Generator`, *선택 사항*): 결정론적 생성을 위한 Torch generator입니다. sigmas (`list | tuple`): 최종 제로를 포함하는 DMD sigma 스케줄입니다. attention_kwargs (`dict`, *선택 사항*): attention 프로세서에 대한 추가 kwargs입니다. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식: 'pil', 'np', 'pt'. decode_timestep (`None`, *선택 사항*, 기본값 0.0): 최종 latents를 디코딩하는 데 사용되는 timestep입니다. decode_noise_scale (`None`, *선택 사항*): 디코딩 timestep에서 적용되는 노이즈 보간 계수입니다.
Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): 생성된 오디오 웨이브폼.

Xet Storage Details

Size:: 9.19 kB
Xet hash:: 6bf6080f33b84514e27feb00b7fb37633617298ed08029ee64c547f846d25f80

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	#
	# Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
	# 이 파일은 라이선스에 따라만 사용할 수 있습니다.
	# 라이선스 사본은 다음에서 가져올 수 있습니다
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# 적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어
	# 라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"
	# 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.
	# 권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요
	# 라이선스 하의 제한 사항. -->

	# Echo

	[Echo](https://github.com/jd-opensource/JoyAI-Echo)는 장시간 영상 생성 모델입니다. 선택적인 클린 첫 프레임, 순서화된 이미지/오디오 메모리 슬롯, 그리고 확률적 소수 스텝 Distribution Matching Distillation (DMD) 샘플러를 지원합니다. 이 파이프라인은 동기화된 영상과 오디오를 생성합니다.

	Echo는 [ModularPipeline](/docs/diffusers/v0.43.0/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline)으로 구현되어 있어 텍스트 인코딩, 메모리 조건화, 확률적 DMD 디노이징, 디코딩 블록을 완전한 워크플로로 실행하거나 독립적으로 조합할 수 있습니다.

	## 추론

	공식 [jdopensource/JoyAI-Echo](https://huggingface.co/jdopensource/JoyAI-Echo) 체크포인트를 직접 로드합니다. 이 모델은 [google/gemma-3-12b-it](https://huggingface.co/google/gemma-3-12b-it)의 텍스트 인코더와 토크나이저를 사용합니다. Gemma 저장소는 게이트가 적용되어 있으므로, 파이프라인을 로드하기 전에 해당 라이선스에 동의하고 Hugging Face로 인증해야 합니다.

	공개된 모델은 긴 영상 예시에서 241프레임을 사용합니다. 출력 컨테이너의 프레임 레이트와 무관하게, 영상 RoPE 좌표는 학습 시 사용된 24fps로 유지됩니다.

	```py
	import torch
	import torchaudio
	from PIL import Image

	from diffusers import ComponentsManager, ModularPipeline
	from diffusers.utils import encode_video

	manager = ComponentsManager()
	pipe = ModularPipeline.from_pretrained("jdopensource/JoyAI-Echo", components_manager=manager)
	pipe.load_components(dtype={"default": torch.bfloat16, "audio_vae": torch.float32})
	manager.enable_auto_cpu_offload(device="cuda")
	pipe.vae.enable_tiling()

	first_frame = Image.open("first_frame.png").convert("RGB")
	memory_images = [Image.open(path).convert("RGB") for path in ["memory_0.png", "memory_1.png"]]
	memory_audio_with_rates = [torchaudio.load(path) for path in ["memory_0.wav", "memory_1.wav"]]
	memory_audio = [waveform for waveform, _ in memory_audio_with_rates]
	memory_audio_rates = [sample_rate for _, sample_rate in memory_audio_with_rates]

	output = pipe(
	prompt="A cinematic dialogue scene in a quiet cafe.",
	image=first_frame,
	memory_images=memory_images,
	memory_audio_waveforms=memory_audio,
	memory_audio_sample_rates=memory_audio_rates,
	width=1280,
	height=736,
	num_frames=241,
	frame_rate=25.0,
	model_frame_rate=24.0,
	generator=torch.Generator(device="cuda").manual_seed(42),
	output_type="np",
	output=["videos", "audio"],
	)

	encode_video(
	output["videos"][0],
	fps=25,
	audio=output["audio"][0].float().cpu(),
	audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
	output_path="echo.mp4",
	)
	```

	기본 DMD sigma 스케줄은 공개된 8단계 스케줄입니다. 모든 단계에서 `x0`를 예측하고 다음 sigma에서 새로운 가우시안 노이즈로 재노이즈링을 수행하므로, 시드가 설정된 `torch.Generator`가 초기 노이즈와 모든 중간 재노이즈링을 제어합니다.

	Raw 오디오-메모리 인코딩에는 `torchaudio`가 필요합니다. 참조와 동일한 조건을 유지하려면, 위와 같이 `audio_vae`를 FP32로 유지하세요. 모듈형 워크플로에서는 VAE 인코더의 정규화되고 언팩된 텐서를 캐시할 수 있습니다. 비디오 라텐트는 `(batch, channels, frames, height, width)` 형태를, 오디오 라텐트는 `(batch, channels, time, mel_bins)` 형태를 가집니다. 핵심 `denoise` 블록은 해당 텐서를 팩하고, `num_videos_per_prompt`에 맞춰 조건을 확장한 후, 노이즈 제거된 출력을 동일한 VAE 형태로 다시 언팩합니다. 초기 `latents`와 `audio_latents`도 동일한 언팩된 형태로 전달하세요. 디코더는 정규화된 VAE 텐서를 받아, 디코딩 직전에 즉시 비정규화합니다. `output=["latents", "audio_latents"]`를 사용하면 정규화된 VAE 텐서가 반환됩니다. `output_type="latent"`와 `output=["videos", "audio"]`를 함께 사용하면 디코딩 없이 비정규화된 VAE 텐서를 얻을 수 있습니다.

	## EchoModularPipeline[[diffusers.EchoModularPipeline]]

	#### diffusers.EchoModularPipeline[[diffusers.EchoModularPipeline]]

	```python
	diffusers.EchoModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks \| None = None, pretrained_model_name_or_path: str \| os.PathLike \| None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager \| None = None, collection: str \| None = None, workflow: str \| None = None, modular_config_dict: dict[str, typing.Any] \| None = None, config_dict: dict[str, typing.Any] \| None = None, **kwargs)
	```

	[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/echo/modular_pipeline.py#L27)

	Echo 장시간 비디오 DMD 체크포인트용 ModularPipeline.

	## EchoBlocks[[diffusers.EchoBlocks]]

	#### diffusers.EchoBlocks[[diffusers.EchoBlocks]]

	```python
	diffusers.EchoBlocks()
	```

	[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/echo/modular_blocks_echo.py#L220)

	clean first-frame conditioning, ordered image/audio memory slots, stochastic DMD denoising를 갖춘 reference-to-video generation을 위한 Echo.

	구성 요소: text_encoder (`PreTrainedModel`) tokenizer (`PreTrainedTokenizerBase`) connectors (`LTX2TextConnectors`) vae (`AutoencoderKLLTX2Video`) audio_vae (`AutoencoderKLLTX2Audio`) transformer (`LTX2VideoTransformer3DModel`) video_processor (`VideoProcessor`) vocoder (`LTX2Vocoder`)

	Inputs: prompt (`str`): 이미지 생성을 안내하는 프롬프트입니다. max_sequence_length (`int`, 선택 사항, 기본값 1024): 프롬프트 인코딩을 위한 최대 시퀀스 길이입니다. image (`Image \| Tensor`, 선택 사항): 깨끗한 참조 조건으로 사용되는 선택적 단일 첫 번째 프레임입니다. memory_images (`list`, 선택 사항): Echo 메모리 슬롯당 하나씩 정렬된 참조 이미지입니다. memory_audio_waveforms (`list`, 선택 사항): `(channels, samples)` 텐서 형식의 정렬된 메모리 웨이브폼입니다. 9.62초보다 긴 입력은 가장 높은 응답 윈도우로 잘립니다. 무음 슬롯에는 `None`을 사용합니다. memory_audio_sample_rates (`int \| list`, 선택 사항): 모든 메모리 웨이브폼이 공유하는 샘플링 속도 또는 슬롯별 하나의 속도입니다. height (`int`, 선택 사항, 기본값 512): 생성된 이미지의 픽셀 단위 높이입니다. width (`int`, 선택 사항, 기본값 704): 생성된 이미지의 픽셀 단위 너비입니다. model_frame_rate (`float`, 선택 사항, 기본값 24.0): Echo 비디오 RoPE 좌표에 사용되는 학습 시 프레임 속도입니다. memory_position_offset (`float`, 선택 사항, 기본값 500.0): 첫 번째 메모리 슬롯에 할당되는 시간 중심입니다. memory_position_slot_stride (`float`, 선택 사항, 기본값 50.0): 연속된 메모리 슬롯 중심 사이의 시간 거리입니다. num_videos_per_prompt (`int`, 선택 사항, 기본값 1): 프롬프트당 비디오 수입니다. num_frames (`int`, 선택 사항, 기본값 241): 생성된 픽셀 프레임 수입니다. `1 + k * vae_temporal_compression_ratio`여야 합니다. frame_rate (`float`, 선택 사항, 기본값 25.0): 생성된 비디오의 프레임 속도입니다. latents (`Tensor`, 선택 사항): VAE 형식 (B, C, F, H, W)의 선택적 초기 비디오 노이즈입니다. audio_latents (`Tensor`, 선택 사항): VAE 형식 (B, C, L, M)의 선택적 초기 오디오 노이즈입니다. generator (`Generator`, 선택 사항): 결정론적 생성을 위한 Torch generator입니다. sigmas (`list \| tuple`): 최종 제로를 포함하는 DMD sigma 스케줄입니다. attention_kwargs (`dict`, 선택 사항): attention 프로세서에 대한 추가 kwargs입니다. output_type (`str`, 선택 사항, 기본값 pil): 출력 형식: 'pil', 'np', 'pt'. decode_timestep (`None`, 선택 사항, 기본값 0.0): 최종 latents를 디코딩하는 데 사용되는 timestep입니다. decode_noise_scale (`None`, 선택 사항): 디코딩 timestep에서 적용되는 노이즈 보간 계수입니다.

	Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): 생성된 오디오 웨이브폼.