# P-H3-Image

P-H3-Imageは、[MiniMax-H3](./minimax_h3)をベースとしたPruna AIの画像モデルで、テキストから画像を生成したり、指示に基づいて画像を編集したりできます。チェックポイントは[PrunaAI/P-H3-Image](https://huggingface.co/PrunaAI/P-H3-Image)で確認できます。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu"

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, generator=torch.Generator().manual_seed(3), output="images")[0]
edited = pipe(prompt="let it snow on the street", image=image, output="images")[0]
```

すべてのリクエストはまず[プロンプトアップサンプラー](#prompt-upsampling)を通過します。すべてのコンポーネントがアクセラレーター上に配置される場合、このパイプラインは8メガピクセルのbfloat16で約101 GBのメモリを必要とするため、例ではオートオフローディングを使用しています。[ComponentsManager](/docs/diffusers/main/ja/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)は、ブロックがコンポーネントを必要とするたびに、そのコンポーネントをアクセラレーター上に移動し、パイプラインは80 GBのGPU上で実行されます。

## コンポーネント

| コンポーネント | クラス |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/main/ja/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration`（Qwen3-VL-4B） |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/main/ja/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/main/ja/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | テキストエンコーダーのトークナイザー、およびMiniMax-H3の画像プロセッサーを備えた`Qwen3VLProcessor` |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/ja/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration`（Qwen3.5-9B ベース）とそのプロセッサ |

## ワークフロー

ワークフローは`image`入力に基づいて選択されます:

- **`text2image`** は `prompt` から生成します。`height` と `width` のデフォルト値は 2912 で、32 の倍数に丸められます。モデルは 8 メガピクセルで最もよく動作し、例えば 2912x2912、3872x2176、2176x3872 などです。
- **`image_conditioned`** は、`prompt` の指示に従って `image` を編集し、4 メガピクセルまたは 8 メガピクセルの解像度で最も良好に動作します。画像は、テキストエンコーダー用に約 `vision_pixels`（1 メガピクセル）でエンコードされ、VAE には元のサイズで渡されます。この範囲外の場合は、`reference_min_pixels`（1 メガピクセル）に拡大、または `reference_max_pixels`（8 メガピクセル）に縮小されます。`height` と `width` が指定されない場合、編集は最初の画像のサイズで生成され、それより小さい場合は `canvas_min_pixels`（4 メガピクセル）に拡大されます。32 の倍数に丸められた `height` と `width` が指定されると、キャンバスサイズは変更されますが、画像自体は変更されません。`image` は最大 8 枚の画像のリスト也可以是ります。最初の画像が編集対象となり、残りは `<Picture 2>`、`<Picture 3>` のように参照画像として扱われます。

## プロンプトのアップサンプリング

P-H3-Image は短いリクエストではなく完全なプロンプトのレンダリングを目的としているため、パイプラインはすべてのリクエストに対して最初にプロンプトアプサンプリャーを実行します。リクエストを考慮した上で、`height` と `width` のアスペクト比に合わせた詳細なテキストから画像へのプロンプト、または編集時には画像内で何を保持し何を変更すべきかを示す要約を作成します。作成されたプロンプトは `prompt` 出力として返されます。

```py
out = pipe(prompt=prompt, height=3360, width=2496, output=["images", "prompt"])
print(out["prompt"])
```

`max_new_tokens` は、推論とプロンプトの合計を制限します。デフォルトでは、テキストから画像への生成が 1024 トークン、編集が 1536 トークンです。アップサンプラーが使用可能なプロンプトを返さない場合、パイプラインはレンダリングを行うのではなくエラーを送出します。

`prompt`をそのままレンダリングするには、ブロックからステップをポップします。ポップされたブロックは単独でも実行でき、例えばレンダリング前にユーザーへプロンプトを表示する用途に使用できます。

```py
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

blocks = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image").blocks
upsampler_block = blocks.sub_blocks.pop("prompt_upsampler")

upsampler = upsampler_block.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
upsampler.load_components(dtype=torch.bfloat16)
upsampled = upsampler(prompt=prompt, height=3360, width=2496, output="prompt")

pipe = blocks.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
image = pipe(prompt=upsampled, height=3360, width=2496, output="images")[0]
```

がない場合、アップサマーが書き出すいずれかの形式の編集プロンプト、つまり6セクションのブリーフまたは`Edit <Picture 1>.`で始まる段落は、そのままエンコードされます。それ以外の指示には、そのプレフィックスが付けられます。

## サンプリング

- 8つのステップは、チェックポイントの`sample_sigmas`上で実行されます。別のグリッドを使用するには、`sigmas`を渡します。
- モデルはガイダンス蒸留されているため、guider、`negative_prompt`、`guidance_scale` は存在しません。

## PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

#### diffusers.PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

```python
diffusers.PH3ImageModularPipeline(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/main/src/diffusers/modular_pipelines/p_h3_image/modular_pipeline.py#L22)

MiniMax-H3をベースとした画像モデルP-H3-Image用のModularPipelineです。テキストから画像を生成(`text2image`)し、指示に基づいて画像を編集(`image_conditioned`)できます。

この画像は単一の潜在フレームであり、2つの破棄されるオーディオ潜在変数を含む1つのパックされたシーケンス内でノイズ除去されます。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, output="images")[0]
```

## PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

#### diffusers.PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

```python
diffusers.PH3ImageBlocks()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/p_h3_image/modular_blocks_p_h3_image.py#L376)

P-H3-Image用のモジュラーなパイプラインブロック: `text2image`、および`image`が渡された場合の指示ベースの編集(`image_conditioned`)。`prompt`はまずプロンプトアップサンプラーを通過します。`prompt_upsampler`ステップを除去すると、指定されたままレンダリングされます。

サポートされているワークフロー:
- `text2image`: `prompt` が必要です
- `image_conditioned`: `prompt`と`image`が必要です

コンポーネント: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): プロンプトアップサンプラー。 prompt_upsampler_processor (`AutoProcessor`): そのプロセッサー。 text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

設定: reference_min_pixels (デフォルト: 1048576) reference_max_pixels (デフォルト: 8388608) canvas_min_pixels (デフォルト:
4194304) vision_pixels （デフォルト: 1000000）sample_sigmas（デフォルト: [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]): `sigmas` が渡されない場合に使用される、チェックポイントのサンプリンググリッド。

Inputs: image (`Image | list`, *任意*): 編集対象の画像、または最大8枚の画像のリストです。最初の画像が編集対象となり、残りは参照画像として使用されます。 height (`int`, *任意*): 生成される画像の高さ（ピクセル単位）です。32の倍数に丸められます。`text2image`ではデフォルトが2912で、8メガピクセルで最も良好な結果が得られます。編集の場合、デフォルトは最初の画像のサイズ（`canvas_min_pixels`以上）で、4または8メガピクセルで最も良好な結果が得られます。 width (`int`, *任意*): 生成される画像の幅（ピクセル単位）です。32の倍数に丸められます。`text2image`ではデフォルトが2912で、8メガピクセルで最も良好な結果が得られます。編集の場合、デフォルトは最初の画像のサイズ（`canvas_min_pixels`以上）で、4または8メガピクセルで最も良好な結果が得られます。 prompt (`str`): プロンプト、または`image`が渡された場合の編集指示です。単一の文字列です。 max_new_tokens (`int`, *任意*, ワークフローに応じてデフォルトは1536または1024): アップサンプラーが生成し得る最大トークン数です。推論プロセスを含む場合も同様です。 vision_images (`list`, *任意*): テキストエンコーダー用にリサイズされた編集対象の画像のリストです。編集対象の画像が先頭に来ます。 reference_images (`list`, *任意*): VAE用にリサイズされた編集対象の画像のリストです。編集対象の画像が先頭に来ます。 condition_latents (`list`, *任意*): 編集対象の画像の条件付き潜在変数です。これらの形状が参照ブロックの幾何学構造を決定します。 generator (`Generator`, *任意*): リクエストのジェネレーターです。条件付きノイズは、生成される行のノイズよりも先に、条件ごとに1回ずつこのジェネレーターから抽出されます。 latents (`Tensor`): 形状`(1, latent_channels, 1, latent_height, latent_width)`の事前生成された画像ノイズです。ジェネレーターからの抽出の代わりに使用されます。 sigmas (`list`, *任意*): 厳密に減少し0で終わるカスタムサンプリンググリッドです。デフォルトはチェックポイントの`sample_sigmas`です。 **denoiser_input_fields (`None`, *任意*): トランスフォーマーが名前によって読み取るパックされたシーケンスの構造記述です。`token_tags`、`position_ids`、および3つの行インデックステンソルを含みます。 attention_kwargs (`dict`, *任意*): アテンションプロセッサー用の追加のキーワード引数です。 output_type (`str`, *任意*, デフォルトはpil): 出力形式です。'pil'、'np'、'pt'のいずれかです。

出力: 画像 (`list`): 生成された画像。

## PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

#### diffusers.PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

```python
diffusers.PH3ImageTextConnector(hidden_state_indices: tuple = (13, 19, 25, 31, 36), text_hidden_size: int = 2560, out_channels: int = 5120)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L22)

**パラメータ:**

hidden_state_indices (`tuple[int, ...]`、デフォルトは`(13, 19, 25, 31, 36)`) : テキストエンコーダーの`hidden_states`のうち、`output_hidden_states`の番号付けに従ってどのエントリを読み込むかを指定します（`0`は埋め込み出力、`i`はデコーダー層`i`の出力、最後のものは最終的な正規化済み隠れ状態を指します）。

text_hidden_size (`int`、デフォルトは`2560`) : テキストエンコーダーの隠れ層サイズです。

out_channels (`int`、デフォルトは`5120`) : MiniMax-H3のtransformerが読み取る条件付けのチャネル数です。

P-H3-Image の Qwen3-VL テキストエンコーダーの隠れ状態を、その Transformer が読み込むテキスト条件付けにマッピングします。

`hidden_state_indices` に列挙された隠れ状態は、連結、標準化、線形射影、逆標準化の順に処理されます。最初のトークンはアテンションシンクであり、すべてのプロンプトに対して同じ条件付けを持つため、`sink_embedding` に置き換えられます。

#### forward[[diffusers.PH3ImageTextConnector.forward]]

```python
forward(hidden_states: tuple)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L61)

**パラメータ:**

hidden_states (`tuple[torch.Tensor, ...]`) : テキストエンコーダーの隠れ状態です。`output_hidden_states=True` が返す形式で、各エントリが `(batch_size, num_tokens, text_hidden_size)` の形状を持つテンソルです。

**戻り値:** `torch.Tensor`

形状が`(batch_size, num_tokens, out_channels)`で、コネクタのパラメータのdtypeである条件付け。