#
# 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 離散スケジューラーを組み合わせるテキストから画像を生成するモデルです。

> [!TIP]
> スケジューラーのトレードオフ、すなわち速度と品質のバランスをどのように探求するかを学ぶには、[ガイド](../../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/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L132)

**パラメータ:**

transformer (`NucleusMoEImageTransformer2DModel`) : エンコードされた画像潜在変数をデノイズするための条件付き Transformer (MMDiT) アーキテクチャ。

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer` と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラー。

vae ([AutoencoderKLQwenImage](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (`Qwen3VLForConditionalGeneration`) : プロンプト埋め込みを計算するためのテキストエンコーダー。

processor (`Qwen3VLProcessor`) : テキスト入力をトークン化するためのプロセッサ。

NucleusMoE を使用したテキストから画像への生成を行う Pipeline。

このパイプラインは、単一ストリームのDiTとMixture-of-Expertsフィードフォワード層、Qwen3-VLテキストエンコーダーへのクロスアテンション、およびフローマッチングEuler離散スケジューラを使用しています。

#### __call__[[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[str] = ['latents'])
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/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 のスケール。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 ジェネレーター 1 つまたはそのリスト。

latents (`torch.Tensor`, *任意*) : 画像生成の入力として使用する、事前生成されたノイズ付き潜在変数。

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 プロセッサに渡される 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/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L187)

**パラメータ:**

prompt (`str` または `list[str]`、*省略可能*) : エンコードするプロンプトまたはプロンプトのリスト。

device (`torch.device`, *任意*) : 結果のテンソルに使用する Torch デバイス。

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/v0.43.0/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 配列は、拡散パイプラインのデノイズ済みイメージを表します。

NucleusMoE Image パイプライン用の出力クラスです。