Hugging Face's logo

Diffusers documentation

가이드

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

가이드

Guider는 Modular Diffusers에서 생성 중 확산 프로세스가 어떻게 유도되는지를 제어하는 구성 요소입니다. 생성 품질과 제어를 개선하기 위해 다양한 유도 기법을 구현합니다.

BaseGuidance

클래스 diffusers.BaseGuidance

< >

( start: float = 0.0stop: float = 1.0enabled: bool = True )

가이던스 기법을 구현하기 위한 골격을 제공하는 베이스 클래스.

cleanup_models

< >

( denoiser: torch.nn.Module )

주어진 데이터 배치 이후 guidance 기법을 위한 모델들을 정리합니다. 이 메서드는 서브클래스에서 오버라이드하여 특정 모델 정리 로직을 구현해야 합니다. prepare_models 실행 중에 추가된 훅이나 기타 상태가 있는 수정 사항을 제거하는 데 유용합니다.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None = Nonesubfolder: str | None = Nonereturn_unused_kwargs = False**kwargs )

매개변수

  • pretrained_model_name_or_path (str 또는 os.PathLike, 선택 사항) — 다음 중 하나일 수 있습니다:
    • Hub에 호스팅된 사전 학습 모델의 model id 문자열(예: google/ddpm-celebahq-256).
    • save_pretrained()로 저장된 guider 구성이 포함된 디렉터리의 경로(예: ./my_model_directory)
  • subfolder (str, 선택 사항) — Hub 또는 로컬의 더 큰 모델 저장소 내에서 모델 파일의 서브폴더 위치입니다.
  • return_unused_kwargs (bool, 선택 사항, 기본값 False) — Python 클래스에서 소비되지 않는 kwargs를 반환할지 여부입니다.
  • cache_dir (str | os.PathLike, 선택 사항) — 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성이 캐시되는 디렉터리의 경로입니다.
  • force_download (bool, 선택 사항, 기본값 False) — 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부입니다. 캐시된 버전이 존재하는 경우 이를 무시합니다.
  • proxies (dict[str, str], 선택) — 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}와 같습니다. 각 요청에 프록시가 사용됩니다.
  • output_loading_info(bool, optional, 기본값 False) — 누락된 키, 예상치 못한 키 및 오류 메시지를 포함하는 사전도 함께 반환할지 여부.
  • local_files_only(bool, 선택 사항, 기본값 False) — 로컬 모델 가중치 및 구성 파일만 로드할지 여부를 지정합니다. True로 설정하면 Hub에서 모델을 다운로드하지 않습니다.
  • token (str 또는 bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. True인 경우, diffusers-cli login에서 생성된 토큰(~/.huggingface에 저장됨)이 사용됩니다.
  • revision (str, 선택 사항, 기본값 "main") — 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다.

로컬 디렉터리 또는 Hub 저장소의 사전 정의된 JSON 구성 파일에서 guider를 초기화합니다.

> 비공개 또는 게이트된 모델을 사용하려면 hf > auth login으로 로그인하세요. 또한 방화벽이 있는 환경에서 이 방법을 사용하려면 특수 > “오프라인 모드”를 활성화할 수도 있습니다.

get_state

< >

( )

가이던스 기법의 현재 상태를 딕셔너리로 반환합니다. 상태 변수는 repr 메서드에 포함됩니다. 반환값: dict[str, Any]: 다음을 포함하는 현재 상태 변수를 담은 딕셔너리:

  • step: 현재 추론 단계
  • num_inference_steps: 총 추론 단계 수
  • timestep: 현재 timestep 텐서
  • count_prepared: prepare_models가 호출된 횟수
  • enabled: 가이던스가 활성화되어 있는지 여부
  • num_conditions: 조건 수

새로움

< >

( **kwargs )

매개변수

  • **kwargs — 새 인스턴스에서 오버라이드할 구성 매개변수입니다. kwargs가 제공되지 않으면 동일한 구성을 가진 정확한 사본을 반환합니다.

이 guider 인스턴스의 사본을 생성하며, 선택적으로 수정된 구성 매개변수를 포함할 수 있습니다.

예:

# Create a CFG guider
guider = ClassifierFreeGuidance(guidance_scale=3.5)

# Create an exact copy
same_guider = guider.new()

# Create a copy with different start step, keeping other config the same
new_guider = guider.new(guidance_scale=5)

prepare_models

< >

( denoiser: torch.nn.Module )

주어진 데이터 배치에 대해 guidance 기법을 적용하기 위해 모델을 준비합니다. 이 메서드는 서브클래스에서 오버라이드하여 특정 모델 준비 로직을 구현해야 합니다.

save_pretrained

< >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

매개변수

  • save_directory (str 또는 os.PathLike) — 설정 JSON 파일이 저장될 디렉터리(존재하지 않으면 생성됩니다).
  • push_to_hub (bool, 선택 사항, 기본값 False) — 모델을 저장한 후 Hugging Face Hub에 푸시할지 여부입니다. repo_id를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 save_directory의 이름이 기본값으로 사용됩니다.
  • kwargs (dict[str, Any], 선택) — push_to_hub() 메서드에 함께 전달되는 추가 키워드 인자입니다.

guider 구성 객체를 디렉토리에 저장하여 from_pretrained() 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.

ClassifierFreeGuidance

클래스 diffusers.ClassifierFreeGuidance

< >

( guidance_scale: float = 7.5guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — 후처리 단계에서 이 guider가 적용하는 CFG scale입니다. 값이 높을수록 프롬프트 조건화가 강해지지만 품질이 저하될 수 있습니다. 일반적인 범위: 1.0-20.0.
  • guidance_rescale (float, 기본값 0.0) — 높은 guidance scale로 인한 과노출을 방지하기 위한 리스케일링 계수입니다. 일반적인 디퓨전 노이즈 스케줄 및 샘플 단계는 결함이 있습니다에 기반합니다. 범위: 0.0(리스케일링 없음)~ 1.0(완전 리스케일링).
  • use_original_formulation (bool, 기본값 False) — True인 경우, 논문에서 제시한 원래의 CFG 수식을 사용합니다. False(기본값)인 경우, Imagen 논문에서 제시한 diffusers 네이티브 수식을 사용합니다.
  • start (float, 기본값 0.0) — CFG가 시작되는 디노이징 단계의 비율(0.0-1.0). 초기 디노이징 단계에서 CFG를 비활성화하려면 > 0.0을 사용하세요.
  • stop (float, 기본값 1.0) — CFG가 중단되는 디노이징 단계의 비율(0.0-1.0). 후기 디노이징 단계에서 CFG를 비활성화하려면 1.0보다 작은 값을 사용하세요.
  • enabled (bool, 기본값 True) — CFG가 활성화되어 있는지 여부입니다. CFG를 완전히 비활성화하려면 False로 설정하세요(조건부 예측만 사용).

확산 모델에 Classifier-Free Guidance(CFG)를 구현합니다.

참고: https://huggingface.co/papers/2207.12598

CFG는 조건부 데이터와 무조건부 데이터 모두를 사용하여 모델을 함께 학습한 후, 추론 시 예측을 결합함으로써 생성 품질과 프롬프트 준수도를 향상시킵니다. 이를 통해 품질(높은 guidance)과 다양성(낮은 guidance) 사이의 트레이드오프를 조절할 수 있습니다.

두 가지 CFG 공식:

  1. 원래 공식 (논문에서):

    x_pred = x_cond + guidance_scale * (x_cond - x_uncond)

    무조건적 예측에서 조건부 예측을 더 멀리 이동시킵니다.

  2. Diffusers 네이티브 공식 (기본값, Imagen 논문에서 가져옴):

    x_pred = x_uncond + guidance_scale * (x_cond - x_uncond)

    무조건적 예측을 조건부 예측으로 이동시켜, 부정적 특징(예: “bad quality”, “watermarks”)을 효과적으로 억제합니다. 이론적으로는 동등하지만 더 직관적입니다.

use_original_formulation=True를 사용하여 원래의 수식으로 전환합니다.

ClassifierFreeZeroStarGuidance

class diffusers.ClassifierFreeZeroStarGuidance

< >

( guidance_scale: float = 7.5zero_init_steps: int = 1guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • zero_init_steps (int, 기본값 1) — 노이즈 예측이 0으로 설정되는 추론 단계의 수입니다(4.2절 참조).
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.01) — 가이드가 시작되는 시점, 즉 전체 디노이징 단계 수의 비율.
  • stop (float, 기본값 0.2) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수에 대한 비율입니다.

Classifier-free Zero(CFG-Zero): https://huggingface.co/papers/2503.18886

이것은 classifier-free guidance의 변형인 Classifier-Free Zero* guidance 기법의 구현입니다. 이 기법은 diffusion process의 초기 몇 단계에서 노이즈 예측값을 0으로 초기화하는 것을 제안하며, 노이즈 예측값에 대한 최적의 rescaling factor를 도입하여 생성된 이미지의 품질을 향상시키는 데 도움을 줄 수 있습니다.

해당 논문의 저자들은 추론 단계의 처음 4%에서 zero initialization을 설정하는 것을 제안합니다.

SkipLayerGuidance

클래스 diffusers.SkipLayerGuidance

< >

( guidance_scale: float = 7.5skip_layer_guidance_scale: float = 2.8skip_layer_guidance_start: float = 0.01skip_layer_guidance_stop: float = 0.2skip_layer_guidance_layers: int | list[int] | None = Noneskip_layer_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • skip_layer_guidance_scale (float, 기본값 2.8) — skip layer guidance의 scale 파라미터입니다. 값이 높을수록 해부학적 구조와 구조적 일관성이 향상될 수 있지만, 과도한 노출과 포화 현상을 유발할 수도 있습니다.
  • skip_layer_guidance_start (float, 기본값 0.01) — denoising 단계 총 개수 중 skip layer guidance가 시작되는 비율입니다.
  • skip_layer_guidance_stop (float, 기본값 0.2) — denoising 단계 총 개수 중 skip layer guidance가 중단되는 비율입니다.
  • skip_layer_guidance_layers (int 또는 list[int], 선택 사항) — skip layer guidance를 적용할 레이어 인덱스입니다. 단일 정수 또는 정수 목록으로 지정할 수 있습니다. 값을 제공하지 않으면 skip_layer_config를 제공해야 합니다. Stable Diffusion 3.5 Medium의 경우 권장 값은 [7, 8, 9]입니다.
  • skip_layer_config (LayerSkipConfig 또는 list[LayerSkipConfig], 선택 사항) — skip layer guidance에 대한 설정입니다. 단일 LayerSkipConfig 또는 LayerSkipConfig 목록일 수 있습니다. 제공되지 않으면 skip_layer_guidance_layers를 제공해야 합니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.01) — 가이드가 시작되는 시점, 즉 전체 디노이징 단계 수의 비율.
  • stop (float, 기본값 0.2) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수에 대한 비율입니다.

Skip Layer Guidance (SLG): https://github.com/Stability-AI/sd3.5

공간-시간 유도(STG): https://huggingface.co/papers/2411.18664

SLG는 StabilityAI에 의해 생성된 이미지의 구조 및 해부학적 일관성을 개선하기 위해 도입되었습니다. 이는 이미 CFG([~guiders.classifier_free_guidance.ClassifierFreeGuidance])에서 사용 중인 조건부 및 무조건 배치 외에, 추가적인 조건부 데이터 배치에서 디노이징 과정 중 지정된 transformer 블록의 forward pass를 건너뛰는 방식으로 작동합니다. 그런 다음, 건너뛰지 않은 조건부 예측과 건너뛴 조건부 예측 간의 차이를 기반으로 CFG 예측을 스케일링 및 시프트합니다.

SLG의 직관은 조건부 분포 추정치의 더 나쁜 버전(레이어를 건너뛰는 것은 조건부 예측에 더 나쁜 버전의 모델을 사용하는 것과 동등하므로)으로부터 CFG 예측 분포 추정치를 더 멀리 이동시키는 것으로 이해할 수 있습니다.

STG는 비디오 확산 모델의 생성 품질을 개선하기 위해 SLG, PAG 및 유사한 기법의 아이디어를 결합한 개선 및 후속 작업입니다.

추가 참고 자료:

skip_layer_guidance_scale, skip_layer_guidance_start, skip_layer_guidance_stop의 값은 StabilityAI가 Stable Diffusion 3.5 Medium에 대해 권장하는 값으로 기본 설정됩니다.

SmoothedEnergyGuidance

class diffusers.SmoothedEnergyGuidance

< >

( guidance_scale: float = 7.5seg_guidance_scale: float = 2.8seg_blur_sigma: float = 9999999.0seg_blur_threshold_inf: float = 9999.0seg_guidance_start: float = 0.0seg_guidance_stop: float = 1.0seg_guidance_layers: int | list[int] | None = Noneseg_guidance_config: SmoothedEnergyGuidanceConfig | list[SmoothedEnergyGuidanceConfig] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • seg_guidance_scale (float, 기본값 3.0) — 부드러운 에너지 가이던스에 사용되는 스케일 파라미터입니다. 값이 높을수록 해부학적 및 구조적 일관성이 향상될 수 있지만, 과도한 노출과 포화 현상을 유발할 수도 있습니다.
  • seg_blur_sigma (float, 기본값 9999999.0) — 어텐션 가중치를 흐리게 하는 정도입니다. 이 값을 9999.0보다 크게 설정하면 무한한 블러가 적용되어 균일한 쿼리가 됩니다. 지수적으로 제어하는 것이 경험적으로 효과적입니다.
  • seg_blur_threshold_inf (float, 기본값 9999.0) — 블러가 무한대로 간주되는 임계값입니다.
  • seg_guidance_start (float, 기본값 0.0) — 디노이징 단계 총 개수 중 어느 비율 이후부터 매끄러운 에너지 가이던스가 시작되는지 나타냅니다.
  • seg_guidance_stop (float, 기본값 1.0) — 노이즈 제거 단계의 총 개수 중, 매끄러운 에너지 가이던스가 중단되는 비율입니다.
  • seg_guidance_layers (int 또는 list[int], 선택 사항) — smoothed energy guidance를 적용할 레이어 인덱스입니다. 단일 정수 또는 정수 목록으로 지정할 수 있습니다. 값을 제공하지 않으면 seg_guidance_config를 제공해야 합니다. Stable Diffusion 3.5 Medium의 경우 권장 값은 [7, 8, 9]입니다.
  • seg_guidance_config (SmoothedEnergyGuidanceConfig 또는 list[SmoothedEnergyGuidanceConfig], 선택 사항) — smoothed energy layer guidance에 대한 설정입니다. 단일 SmoothedEnergyGuidanceConfig 또는 SmoothedEnergyGuidanceConfig의 리스트일 수 있습니다. 제공되지 않으면 seg_guidance_layers를 제공해야 합니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.01) — 가이드가 시작되는 시점, 즉 전체 디노이징 단계 수의 비율.
  • stop (float, 기본값 0.2) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수에 대한 비율입니다.

Smoothed Energy Guidance (SEG): https://huggingface.co/papers/2408.00760

SEG는 현재 실험적 프로토타입 기능으로만 지원되므로, 향후 사전 통보나 재현 가능성 보장 없이 구현이 변경될 수 있습니다. 이 구현은 다음을 가정합니다:

  • 생성된 이미지는 정사각형(높이 == 너비)입니다
  • 모델은 서로 다른 모달리티를 결합하지 않습니다(예: Flux와 달리 텍스트와 이미지 잠재 스트림을 함께 결합하지 않음).

PerturbedAttentionGuidance

class diffusers.PerturbedAttentionGuidance

< >

( guidance_scale: float = 7.5perturbed_guidance_scale: float = 2.8perturbed_guidance_start: float = 0.01perturbed_guidance_stop: float = 0.2perturbed_guidance_layers: int | list[int] | None = Noneperturbed_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • perturbed_guidance_scale (float, 기본값 2.8) — perturbed attention guidance의 scale 매개변수입니다.
  • perturbed_guidance_start (float, 기본값 0.01) — denoising 단계 총 개수 중 perturbed attention guidance가 시작되는 비율입니다.
  • perturbed_guidance_stop (float, 기본값 0.2) — denoising 단계 총 개수 중 perturbed attention guidance가 중단되는 비율입니다.
  • perturbed_guidance_layers (int 또는 list[int], 선택 사항) — perturbed attention guidance를 적용할 레이어 인덱스입니다. 단일 정수 또는 정수 목록일 수 있습니다. 제공되지 않으면 perturbed_guidance_config를 제공해야 합니다.
  • perturbed_guidance_config (LayerSkipConfig 또는 list[LayerSkipConfig], 선택 사항) — perturbed attention guidance에 대한 설정입니다. 단일 LayerSkipConfig 또는 LayerSkipConfig 목록일 수 있습니다. 제공되지 않으면 perturbed_guidance_layers를 제공해야 합니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.01) — 가이드가 시작되는 시점, 즉 전체 디노이징 단계 수의 비율.
  • stop (float, 기본값 0.2) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수에 대한 비율입니다.

Perturbed Attention Guidance (PAG): https://huggingface.co/papers/2403.17377

PAG의 직관은 CFG가 예측한 분포 추정치를 조건부 분포 추정치의 더 나쁜 버전에서 더 멀리 이동시키는 것으로 이해할 수 있습니다. PAG는 학습된 모델의 더 나쁜 버전을 사용하여 디노이징 과정에서 스스로를 더 잘 유도하는 아이디어를 도입한 최초의 기법 중 하나였습니다. PAG는 선택적으로 선택된 레이어에 대해 점수 행렬을 항등 행렬로 대체하여 잠재 스트림의 어텐션 점수를 교란시킵니다.

추가 참고 자료:

PAG는 구성 매개변수와 구현 세부 사항이 중복되어 있기 때문에 SkipLayerGuidance와 유사한 방식으로 구현됩니다.

AdaptiveProjectedGuidance

class diffusers.AdaptiveProjectedGuidance

< >

( guidance_scale: float = 7.5adaptive_projected_guidance_momentum: float | None = Noneadaptive_projected_guidance_rescale: float = 15.0adaptive_projected_guidance_norm_dim: int | tuple[int, ...] | None = Noneeta: float = 1.0guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • adaptive_projected_guidance_momentum (float, 기본값 None) — 적응형 투영 가이던스의 모멘텀 파라미터입니다. None으로 설정하면 비활성화됩니다.
  • adaptive_projected_guidance_rescale (float, 기본값 15.0) — 노이즈 예측에 적용되는 rescale 계수입니다. 이미지 품질을 개선하고
  • adaptive_projected_guidance_norm_dim (int 또는 tuple[int], 선택 사항) — APG 노름과 투영을 계산할 차원입니다. 생략할 경우 원래 동작을 유지하기 위해 배치 차원을 제외한 모든 차원이 사용됩니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.0) — 가이던스가 시작되는 시점. 전체 디노이징 스텝 수의 비율로 나타냅니다.
  • stop (float, 기본값 1.0) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수 비율입니다.

적응형 투영 유도(APG): https://huggingface.co/papers/2410.02416

AutoGuidance

클래스 diffusers.AutoGuidance

< >

( guidance_scale: float = 7.5auto_guidance_layers: int | list[int] | None = Noneauto_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Nonedropout: float | None = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • auto_guidance_layers (int 또는 list[int], 선택 사항) — skip layer guidance를 적용할 레이어 인덱스입니다. 단일 정수 또는 정수 목록일 수 있습니다. 제공되지 않으면 skip_layer_config를 제공해야 합니다.
  • auto_guidance_config (LayerSkipConfig 또는 list[LayerSkipConfig], 선택 사항) — skip layer guidance에 대한 설정입니다. 단일 LayerSkipConfig 또는 LayerSkipConfig 목록일 수 있습니다. 제공되지 않으면 skip_layer_guidance_layers를 제공해야 합니다.
  • dropout (float, 선택 사항) — 활성화된 스킵 레이어(즉, auto_guidance_layers 또는 auto_guidance_config를 통해 지정된 레이어)에 대한 autoguidance의 dropout 확률입니다. 값을 제공하지 않으면 dropout 확률은 1.0으로 설정됩니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.0) — 가이던스가 시작되는 시점. 전체 디노이징 스텝 수의 비율로 나타냅니다.
  • stop (float, 기본값 1.0) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수 비율입니다.

AutoGuidance: https://huggingface.co/papers/2406.02507

TangentialClassifierFreeGuidance

class diffusers.TangentialClassifierFreeGuidance

< >

( guidance_scale: float = 7.5guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 7.5) — classifier-free guidance의 scale 파라미터입니다. 값이 높을수록 텍스트 프롬프트에 대한 조건화가 강해지고, 값이 낮을수록 생성 과정에서 더 많은 자유도가 허용됩니다. 값이 너무 높으면 포화 현상이 발생하거나 이미지 품질이 저하될 수 있습니다.
  • guidance_rescale (float, 기본값 0.0) — 노이즈 예측에 적용되는 리스케일 계수입니다. 이미지 품질을 개선하고 과도한 노출을 수정하는 데 사용됩니다. 공통 확산 노이즈 스케줄 및 샘플 단계는 결함이 있다의 3.4절을 기반으로 합니다.
  • use_original_formulation (bool, 기본값 False) — 논문에서 제안한 classifier-free guidance의 원래 수식을 사용할지 여부입니다. 기본적으로 코드베이스에 오랫동안 존재해 온 diffusers 네이티브 구현을 사용합니다. 자세한 내용은 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]를 참고하세요.
  • start (float, 기본값 0.0) — 가이던스가 시작되는 시점. 전체 디노이징 스텝 수의 비율로 나타냅니다.
  • stop (float, 기본값 1.0) — 가이던스가 중단되는 시점까지의 전체 디노이징 스텝 수 비율입니다.

Tangential Classifier Free Guidance (TCFG): https://huggingface.co/papers/2503.18137

LTX2Guidance

클래스 diffusers.LTX2Guidance

< >

( guidance_scale: float = 1.0stg_scale: float = 0.0modality_scale: float = 1.0guidance_rescale: float = 0.0spatio_temporal_guidance_blocks: list[int] | None = Nonestart: float = 0.0stop: float = 1.0enabled: bool = True )

매개변수

  • guidance_scale (float, 기본값 1.0) — 해당 모달리티에 대한 CFG scale입니다. 1.0인 경우 CFG pass가 완전히 건너뜁니다.
  • stg_scale (float, 기본값 0.0) — 해당 모달리티에 대한 시공간 가이던스 스케일입니다. 0.0인 경우 STG 패스가 완전히 건너뜁니다.
  • modality_scale (float, 기본값 1.0) — 해당 모달리티에 대한 모달리티 격리 가이던스 스케일입니다. 1.0인 경우 해당 패스가 완전히 건너뜁니다.
  • guidance_rescale (float, 기본값 0.0) — 높은 guidance scale로 인한 과노출을 방지하기 위한 리스케일링 계수입니다. 일반적인 디퓨전 노이즈 스케줄 및 샘플 단계는 결함이 있습니다에 기반합니다. 범위: 0.0(리스케일링 없음)~ 1.0(완전 리스케일링).
  • spatio_temporal_guidance_blocks (list[int], 선택 사항) — STG 패스에서 교란할 Transformer 블록입니다. 이 값의 사용 방식은 denoiser 블록에 따라 달라집니다: LTX-2는 모든 모달리티를 공급하는 단일 forward에서 전체 블록을 교란하므로, 이 값을 비디오 guider에서만 읽습니다. 오디오 guider에 설정해도 효과가 없으며, 해당 guider는 자체 stg_scale을 통해 같은 STG forward에 참여합니다.
  • start (float, 기본값 0.0) — 가이던스가 시작되는 디노이징 단계의 비율(0.0-1.0).
  • stop (float, 기본값 1.0) — 가이드가 중단되는 디노이징 단계의 비율(0.0-1.0).
  • enabled (bool, 기본값 True) — 이 guider가 가이던스를 적용할지 여부입니다. False인 경우 조건부 패스만 실행됩니다.

LTX-2.X용 단일 모달리티 guider입니다. 델타 형식을 통해 최대 3개의 용어를 결합합니다:

  • classifier-free guidance (CFG),
  • 공간-시간 가이던스(STG), 즉 변형된 트랜스포머 블록 세트로 추가 패스를 수행하는 기법
  • modality-isolation guidance, A2V/V2A cross-attention을 비활성화한 추가 패스

하나의 인스턴스가 하나의 모달리티를 처리하므로, 멀티모달 체크포인트에는 여러 인스턴스가 포함됩니다. LTX-2.X는 비디오 guider와 audio_guider를 페어링하며, 각각은 자체 스케일을 보유합니다. 최종 가이던스 추정값은 호출자가 입력하는 공간에서 계산됩니다. LTX-2 디노이저는 이 함수를 호출하기 전에 velocity->x0로 변환하고, 호출 후에는 다시 원래 공간으로 변환하므로 forward는 x0 예측값을 대상으로 동작합니다.

SkipLayerGuidance는 훅을 통해 교란을 적용하는 반면, LTX2Guidance는 비-CFG 교란이 모델의 forward 인수를 통해 구성되도록 기대합니다(LTX2VideoTransformer3DModel의 spatio_temporal_guidance_blocks 및 isolate_modalities). 호출하는 denoiser 블록이 패스별 식별자를 설정하는 책임을 집니다. 사용 예는 LTX2LoopDenoiser를 참고하세요.

Update on GitHub

←컴포넌트 및 구성 IP-Adapter→