#
# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
# このファイルは、ライセンスに準拠した場合にのみ使用できます。
# ライセンスのコピーは以下から入手できます
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
# 権限を管理する特定の言語については、ライセンスを参照してください。
# ライセンスの下での制限。-->

# PRX Pixel

PRXPixelは、Photoroomが開発したピクセル空間でのテキストから画像を生成するモデルです。約7Bパラメータの`PRXTransformer2DModel`が生のRGB画像を直接デノイズするため、VAEは不要です。このモデルはQwen3-VLテキストエンコーダーで条件付けられ、フローマッチングを用いています。この方式では、トランスフォーマーが各ステップでクリーンな画像を予測します（x-prediction）。生成解像度はタイムステップのモジュレーションに反映されるため、モデルはターゲットサイズを認識できます。

## 利用可能なモデル

| モデル | 解決 | 説明 | 推奨パラメータ | 推奨されるdtype |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Qwen3-VL テキストエンコーダーを備えたピクセル空間の約7Bモデル | 28ステップ、cfg=5.0 | `torch.bfloat16` |

## パイプラインの読み込み

[PRXPixelPipeline](/docs/diffusers/v0.43.0/ja/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline)には`transformers >= 4.57`（`Qwen3VLTextModel`が導入されたバージョン）が必要です。[from_pretrained()](/docs/diffusers/v0.43.0/ja/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)で読み込みます。

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
image.save("prxpixel_output.png")
```

## メモリ最適化

メモリが制約された環境向け:

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

# Or use sequential CPU offload for even lower memory
pipe.enable_sequential_cpu_offload()
```

## PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

#### diffusers.PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

```python
diffusers.PRXPixelPipeline(transformer: PRXTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder: PreTrainedModel, tokenizer: transformers.models.auto.tokenization_auto.AutoTokenizer | transformers.tokenization_utils_base.PreTrainedTokenizerBase, default_sample_size: int | None = 1024, prompt_max_tokens: int = 256, noise_scale: float = 2.0)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

**パラメータ:**

transformer (`PRXTransformer2DModel`) : 約70億パラメータのPRXデノイザーです。PRXPixelでは、`in_channels=3`、ボトルネック付きの`img_in`、および`resolution_embeds=True`で構築され、クリーンな画像`x0`を予測するように学習されます。

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : (ピクセル空間の) 潜在変数をデノイズするために使用されるフローマッチングスケジューラ。

text_encoder (`PreTrainedModel`) : プロンプトをエンコードするために使用される Qwen3-VL のテキストバックボーン（ビジョンタワーは破棄されます）。`last_hidden_state` を返す必要があります。

tokenizer (`PreTrainedTokenizerBase`) : `text_encoder`用のTokenizer（通常は`AutoTokenizer`経由で読み込まれます）。

default_sample_size (`int`、*任意*、デフォルト値は 1024) : `__call__` に何も指定されない場合に使用されるデフォルトの縦幅/横幅。

prompt_max_tokens (`int`、*optional*、デフォルトは 256) : エンコード前にプロンプトがパディングまたは切り詰められるテキストトークンの数。

noise_scale (`float`、*任意*、デフォルト値は 2.0) : 初期ガウスノイズに適用されるスケール。PRXPixel は非 1 の初期ノイズスケールで学習されるため、サンプリングは `randn * noise_scale` から開始する必要があります。

PRXPixelモデルによるテキストから画像への生成を行うPipelineです。

PRXPixel は、独立したピクセル空間のテキストから画像を生成するパイプラインです。約70億パラメータの `PRXTransformer2DModel` を用いて生 RGB を直接ノイズ除去し、VAE は使用しません（生成は完全にピクセル空間で行われるため、ノイズ除去後の出力が *そのまま* 画像となります）。プロンプトは Qwen3-VL テキストエンコーダーでエンコードされます（ビジョンタワーは破棄されます）。[PRXPipeline](/docs/diffusers/v0.43.0/ja/api/pipelines/prx#diffusers.PRXPipeline) とは異なり、このトランスフォーマーは x-prediction で学習されています。各ステップでクリーンな画像 `x0` を予測し、スケジューラのステップに適用する前に flow-matching の速度に変換します。サンプリングは `randn * noise_scale` から開始され（デフォルトは `noise_scale=2.0`）、デフォルトの解像度は 1024px です。

このモデルは [DiffusionPipeline](/docs/diffusers/v0.43.0/ja/api/pipelines/overview#diffusers.DiffusionPipeline) を継承しています。ライブラリがすべてのパイプラインに対して実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

例:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### __call__[[diffusers.PRXPixelPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', height: int | None = None, width: int | None = None, num_inference_steps: int = 28, timesteps: list[int] = None, guidance_scale: float = 4.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, use_resolution_binning: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

**パラメータ:**

prompt (`str` または `list[str]`、*省略可*) : 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに `prompt_embeds` を渡す必要があります。

negative_prompt (`str`、*任意*、デフォルトは`""`) : 画像生成をガイドしないプロンプトです。ガイダンスを使用していない場合は無視されます（`guidance_scale`が`1`未満の場合は無視されます）。

height (`int`、*任意*、デフォルトは`default_sample_size`) : 生成される画像のピクセル単位の縦幅。

width (`int`、*任意*、デフォルトは`default_sample_size`) : 生成される画像の幅（ピクセル単位）。

num_inference_steps (`int`、*任意*、デフォルトは 28) : デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常はより高品質な画像が得られます。

timesteps (`list[int]`、*任意*) : `set_timesteps` メソッドで `timesteps` 引数をサポートするスケジューラーにおいて、デノイジングプロセスに使用するカスタムタイムステップ。`num_inference_steps` が渡された場合のデフォルトの動作が使用されます。降順で指定する必要があります。

guidance_scale (`float`、*任意*、デフォルト値は 4.0) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)で定義されているガイダンススケールです。`guidance_scale` は、[Imagen Paper](https://huggingface.co/papers/2205.11487)の式 2 の `w` として定義されています。`guidance_scale > 1` を設定することで、ガイダンススケールが有効になります。ガイダンススケールを高くすると、`prompt` のテキストと密接に関連した画像の生成が促されますが、通常は画像の品質が低下する傾向があります。

num_images_per_prompt (`int`、*任意*、デフォルトは 1) : プロンプトごとに生成する画像の数。

generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。

latents (`torch.Tensor`, *任意*) : イメージ生成の入力として使用される、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムな`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。

prompt_embeds (`torch.FloatTensor`、*任意*) : 事前に生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを簡単に実行できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。

negative_prompt_embeds (`torch.FloatTensor`, *任意*) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを簡単に実行できます。指定されず、かつ `guidance_scale > 1` の場合、空の文字列からネガティブな埋め込みが生成されます。

prompt_attention_mask (`torch.BoolTensor`、*任意*) : `prompt_embeds`用の事前生成されたアテンションマスクです。指定しない場合、`prompt`入力引数からアテンションマスクが生成されます。

negative_prompt_attention_mask (`torch.BoolTensor`, *任意*) : `negative_prompt_embeds`用の事前生成済みアテンションマスクです。指定されず、かつ`guidance_scale > 1`の場合、空の文字列からアテンションマスクが生成されます。

output_type (`str`、*任意*、デフォルトは `"pil"`) : 生成画像の出力形式。[PIL](https://pillow.readthedocs.io/en/stable/)（`PIL.Image.Image`）または `np.array` から選択します。

return_dict (`bool`, *任意*, デフォルトは `True`) : プレーンなタプルではなく [PRXPipelineOutput](/docs/diffusers/v0.43.0/ja/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) を返すかどうか。

use_resolution_binning (`bool`、*任意*、デフォルトは`True`) : `True`に設定すると、要求された高さおよび幅は、事前に定義されたアスペクト比のビンを使用して、最も近い解像度にマッピングされます。生成された潜在変数が画像にデコードされた後、要求された解像도에リサイズされます。最適な解像度で正方形でない画像を生成する場合に有用です。

callback_on_step_end (`Callable`、*任意*) : 推論中の各デノイジングステップの終了時に呼び出される関数です。この関数は、以下の引数とともに呼び出されます: `callback_on_step_end(self, step, timestep, callback_kwargs)`。 `callback_kwargs` には、`callback_on_step_end_tensor_inputs` で指定されたすべてのテンソルのリストが含まれます。

callback_on_step_end_tensor_inputs (`list`、*任意*) : `callback_on_step_end` 関数へのテンソル入力のリストです。リストで指定されたテンソルは、`callback_kwargs` 引数として渡されます。`._callback_tensor_inputs` 属性にリストアップされているテンソルのみを含めることができます。

**戻り値:** [PRXPipelineOutput](/docs/diffusers/v0.43.0/ja/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) または `tuple`

`return_dict` が True の場合は [PRXPipelineOutput](/docs/diffusers/v0.43.0/ja/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput)、それ以外は `tuple が返されます。tuple を返す場合、最初の要素は生成された画像のリストです。

生成用のパイプラインを呼び出したときに実行される関数。

例:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### check_inputs[[diffusers.PRXPixelPipeline.check_inputs]]

```python
check_inputs(prompt: str | list[str], height: int, width: int, guidance_scale: float, callback_on_step_end_tensor_inputs: list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

すべての入力が正しい形式であることを確認してください。

#### encode_prompt[[diffusers.PRXPixelPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, tokenizer_max_length: int | None = None, skip_text_cleaning: bool = False)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

標準的なテキストエンコーダーとトークナイザーを使用してテキストプロンプトをエンコードするか、事前計算された埋め込みを使用します。

#### prepare_latents[[diffusers.PRXPixelPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, dtype: dtype, device: device, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

拡散プロセス用の初期潜在変数を準備します。

PRXPixel は、初期ノイズのスケールが 1 でない状態で学習されるため、サンプリングされたノイズは `self.config.noise_scale` 倍されます。

## PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

#### diffusers.pipelines.prx.PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

```python
diffusers.pipelines.prx.PRXPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_output.py#L24)

**パラメータ:**

images (`list[PIL.Image.Image]` または `np.ndarray`) : 長さ `batch_size` のデノイズ済み PIL イメージのリスト、または形状 `(batch_size, height, width, num_channels)` の numpy 配列。PIL イメージまたは numpy 配列は、拡散パイプラインのデノイズ済みイメージを表します。

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