Diffusers documentation
P-H3-Image
P-H3-Image
P-H3-Imageは、MiniMax-H3をベースとしたPruna AIの画像モデルで、テキストから画像を生成したり、指示に基づいて画像を編集したりできます。チェックポイントはPrunaAI/P-H3-Imageで確認できます。
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]すべてのリクエストはまずプロンプトアップサンプラーを通過します。すべてのコンポーネントがアクセラレーター上に配置される場合、このパイプラインは8メガピクセルのbfloat16で約101 GBのメモリを必要とするため、例ではオートオフローディングを使用しています。ComponentsManagerは、ブロックがコンポーネントを必要とするたびに、そのコンポーネントをアクセラレーター上に移動し、パイプラインは80 GBのGPU上で実行されます。
コンポーネント
| コンポーネント | クラス |
|---|---|
transformer | MiniMaxH3Transformer3DModel |
text_encoder | Qwen3VLForConditionalGeneration（Qwen3-VL-4B） |
text_connector | PH3ImageTextConnector |
vae | AutoencoderKLPH3Image |
tokenizer, processor | テキストエンコーダーのトークナイザー、およびMiniMax-H3の画像プロセッサーを備えたQwen3VLProcessor |
scheduler, audio_scheduler | 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 出力として返されます。
out = pipe(prompt=prompt, height=3360, width=2496, output=["images", "prompt"])
print(out["prompt"])max_new_tokens は、推論とプロンプトの合計を制限します。デフォルトでは、テキストから画像への生成が 1024 トークン、編集が 1536 トークンです。アップサンプラーが使用可能なプロンプトを返さない場合、パイプラインはレンダリングを行うのではなくエラーを送出します。
promptをそのままレンダリングするには、ブロックからステップをポップします。ポップされたブロックは単独でも実行でき、例えばレンダリング前にユーザーへプロンプトを表示する用途に使用できます。
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
class diffusers.PH3ImageModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
MiniMax-H3をベースとした画像モデルP-H3-Image用のModularPipelineです。テキストから画像を生成(text2image)し、指示に基づいた編集(image_conditioned)を行うことができます。
この画像は単一の潜在フレームであり、2つの破棄されるオーディオ潜在変数を含む1つのパックされたシーケンス内でノイズ除去されます。
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
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)
Configs:
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 が渡されない場合に使用される、チェックポイントのサンプリンググリッドです。
入力:
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’のいずれかです。
出力:
images (list):
生成された画像。
PH3ImageTextConnector
class diffusers.PH3ImageTextConnector
< source >( hidden_state_indices: tuple[int, ...] = (13, 19, 25, 31, 36)text_hidden_size: int = 2560out_channels: int = 5120 )
パラメータ
- hidden_state_indices (
tuple[int, ...]、デフォルトは(13, 19, 25, 31, 36)) —output_hidden_statesの番号付けに従い、テキストエンコーダーの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
< source >( hidden_states: tuple[torch.Tensor, ...] ) → torch.Tensor
パラメータ
- 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である条件付け。