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

# NucleusMoE-Image

[NucleusMoE-Image](https://huggingface.co/NucleusAI/NucleusMoE-Image)는 단일 스트림 DiT에 Mixture-of-Experts 피드포워드 레이어, Qwen3-VL 텍스트 인코더와의 크로스 어텐션, flow-matching Euler discrete 스케줄러를 결합한 텍스트-이미지 생성 모델입니다.

> [!TIP]
> Scheduler의 [가이드](../../using-diffusers/schedulers)를 확인하여 스케줄러의 속도와 품질 사이의 트레이드오프를 탐색하는 방법을 배우고, [파이프라인 간 구성 요소 재사용](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) 섹션을 확인하여 동일한 구성 요소를 여러 파이프라인에 효율적으로 로드하는 방법을 배워보세요.

## NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

#### diffusers.NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

```python
diffusers.NucleusMoEImagePipeline(transformer: NucleusMoEImageTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen3VLForConditionalGeneration, processor: Qwen3VLProcessor)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L132)

**매개변수:**

transformer (`NucleusMoEImageTransformer2DModel`) : 인코딩된 이미지 레이턴트를 디노이즈하기 위한 조건부 Transformer (MMDiT) 아키텍처.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer`와 함께 사용하여 인코딩된 이미지 라텐트를 디노이즈하는 데 사용되는 스케줄러입니다.

vae ([AutoencoderKLQwenImage](/docs/diffusers/main/ko/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : 이미지를 잠재 표현으로 인코딩하고 잠재 표현에서 이미지로 디코딩하는 Variational Auto-Encoder (VAE) 모델입니다.

text_encoder (`Qwen3VLForConditionalGeneration`) : 프롬프트 임베딩을 계산하는 텍스트 인코더.

processor (`Qwen3VLProcessor`) : 텍스트 입력을 토큰화하는 프로세서입니다.

NucleusMoE를 사용한 텍스트-이미지 생성을 위한 Pipeline

이 파이프라인은 단일 스트림 DiT, Mixture-of-Experts 피드포워드 레이어, Qwen3-VL 텍스트 인코더에 대한 크로스 어텐션, 그리고 flow-matching Euler discrete 스케줄러를 사용합니다.

#### __호출__[[diffusers.NucleusMoEImagePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, guidance_scale: float = 4.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, num_images_per_prompt: int = 1, max_sequence_length: int | None = None, return_index: int | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'])
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L379)

**매개변수:**

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

negative_prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 `true_cfg_scale > 1`이면 빈 문자열이 사용됩니다.

guidance_scale (`float`, *선택 사항*, 기본값 4.0) : Classifier-free guidance scale. 1보다 큰 값은 CFG를 활성화합니다.

return_index (`int`, *선택 사항*) : 프롬프트 임베딩에 사용할 텍스트 인코더 출력의 레이어 인덱스.

height (`int`, *선택 사항*, 기본값은 `self.default_sample_size * self.vae_scale_factor`) : 생성된 이미지의 픽셀 단위 높이.

width (`int`, *선택 사항*, 기본값은 `self.default_sample_size * self.vae_scale_factor`) : 생성된 이미지의 픽셀 단위 너비.

num_inference_steps (`int`, *선택 사항*, 기본값 50) : 디노이징 단계 수입니다.

sigmas (`list[float]`, *선택 사항*) : 노이즈 제거 스케줄에 사용할 커스텀 시그마입니다. 정의되지 않은 경우 선형 스케줄이 사용됩니다.

num_images_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 이미지의 수.

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

latents (`torch.Tensor`, *선택 사항*) : 이미지 생성의 입력으로 사용할 사전 생성된 노이즈된 잠재 변수(latents).

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩.

prompt_embeds_mask (`torch.Tensor`, *선택 사항*) : 사전 생성된 텍스트 임베딩에 사용할 어텐션 마스크입니다.

negative_prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 부정 텍스트 임베딩.

negative_prompt_embeds_mask (`torch.Tensor`, *선택 사항*) : 사전 생성된 부정 텍스트 임베딩에 사용할 어텐션 마스크입니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 생성된 이미지의 출력 형식입니다. `"pil"`, `"np"`, `"latent"` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `NucleusMoEImagePipelineOutput`을 반환할지 여부.

attention_kwargs (`dict`, *선택 사항*) : attention processor에 전달되는 Kwargs입니다.

callback_on_step_end (`Callable`, *선택 사항*) : 각 디노이징 단계의 끝에서 호출되는 함수.

callback_on_step_end_tensor_inputs (`list`, *선택 사항*) : `callback_on_step_end` 함수의 Tensor 입력입니다.

max_sequence_length (`int`, 기본값 512) : 텍스트 프롬프트의 최대 시퀀스 길이입니다.

**반환값:** `NucleusMoEImagePipelineOutput` 또는 `tuple`

`return_dict`가 True인 경우 `NucleusMoEImagePipelineOutput`, 그렇지 않으면 첫 번째 요소가 생성된 이미지의 리스트인 `tuple`

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

예:
```py
>>> import torch
>>> from diffusers import NucleusMoEImagePipeline

>>> pipe = NucleusMoEImagePipeline.from_pretrained("NucleusAI/NucleusMoE-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = pipe(prompt, num_inference_steps=50).images[0]
>>> image.save("nucleus_moe.png")
```

#### encode_prompt[[diffusers.NucleusMoEImagePipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str] = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, return_index: int | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L187)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트입니다.

device (`torch.device`, *선택 사항*) : 결과 텐서의 Torch device입니다.

num_images_per_prompt (`int`, 기본값 1) : 프롬프트당 생성할 이미지 수.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩. 값이 제공되면 인코딩을 건너뜁니다.

prompt_embeds_mask (`torch.Tensor`, *선택 사항*) : 사전 생성된 임베딩에 사용할 어텐션 마스크입니다.

max_sequence_length (`int`, 기본값 1024) : 인코딩된 프롬프트의 최대 토큰 길이입니다.

Qwen3-VL 텍스트 인코더를 사용하여 텍스트 프롬프트를 임베딩으로 인코딩합니다.

## NucleusMoEImagePipelineOutput[[diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput]]

#### diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput[[diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput]]

```python
diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_output.py#L10)

**매개변수:**

images (`list[PIL.Image.Image]` 또는 `np.ndarray`) : 길이가 `batch_size`인 노이즈 제거된 PIL 이미지 목록 또는 `(batch_size, height, width, num_channels)` 모양의 numpy 배열입니다. PIL 이미지 또는 numpy 배열은 diffusion 파이프라인의 노이즈 제거된 이미지를 나타냅니다.

NucleusMoE 이미지 파이프라인의 출력 클래스입니다.