# P-H3-Image

P-H3-Image là một mô hình ảnh của Pruna AI dựa trên [MiniMax-H3](./minimax_h3), dùng để tạo ảnh từ văn bản và chỉnh sửa ảnh theo hướng dẫn. Bạn có thể tìm checkpoint tại [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]
```

Mọi yêu cầu đều đi qua [prompt upsampler](#prompt-upsampling) trước tiên. Với mọi thành phần trên bộ tăng tốc, pipeline cần khoảng 101 GB ở bfloat16 tại 8 megapixel, vì vậy các ví dụ sử dụng auto offloading: [ComponentsManager](/docs/diffusers/main/vi/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) di chuyển từng thành phần lên bộ tăng tốc khi một khối cần đến, và pipeline chạy trên GPU 80 GB.

## Các thành phần

| Thành phần | Lớp |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/main/vi/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/main/vi/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/main/vi/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | Tokenizer của text encoder, và một `Qwen3VLProcessor` với image processor của MiniMax-H3 |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/vi/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (dựa trên Qwen3.5-9B) và bộ xử lý của nó |

## Quy trình làm việc

Quy trình làm việc được chọn trên đầu vào `image`:

- **`text2image`** tạo ảnh từ `prompt`. `height` và `width` mặc định là 2912 và được làm tròn đến bội số của 32. Mô hình hoạt động tốt nhất ở độ phân giải 8 megapixel, ví dụ 2912x2912, 3872x2176 hoặc 2176x3872.
- **`image_conditioned`** chỉnh sửa `image` theo hướng dẫn trong `prompt`, và hoạt động tốt nhất ở độ phân giải 4 hoặc 8 megapixel. Ảnh được mã hóa ở khoảng `vision_pixels` (một megapixel) cho text encoder và ở kích thước riêng của nó cho VAE, được phóng to lên `reference_min_pixels` (một megapixel) hoặc thu nhỏ xuống `reference_max_pixels` (tám megapixel) khi nằm ngoài khoảng đó. Nếu không có `height` và `width`, bản chỉnh sửa sẽ được tạo ở kích thước của ảnh đầu tiên, được phóng to lên `canvas_min_pixels` (bốn megapixel) nếu nhỏ hơn. Khi truyền `height` và `width`, làm tròn đến bội số của 32, sẽ thay đổi canvas nhưng không thay đổi các ảnh. `image` cũng có thể là một danh sách tối đa 8 ảnh: ảnh đầu tiên được chỉnh sửa và các ảnh còn lại là tham chiếu, như `<Picture 2>`, `<Picture 3>` và tiếp theo.

## Mẫu hóa lại prompt

P-H3-Image được thiết kế để xử lý các prompt đầy đủ thay vì các yêu cầu ngắn, vì vậy pipeline sẽ chạy prompt upsampler trước trên mọi yêu cầu. Nó suy nghĩ về yêu cầu rồi viết prompt: một prompt text-to-image chi tiết cho tỷ lệ khung hình của `height` và `width`, hoặc, khi chỉnh sửa, một bản tóm tắt về những gì cần giữ lại và những gì cần thay đổi trong các hình ảnh. Prompt mà nó viết sẽ được trả về dưới dạng đầu ra `prompt`.

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

`max_new_tokens` giới hạn tổng số token cho cả phần suy luận và prompt, mặc định là 1024 token cho text-to-image và 1536 cho edits. Nếu upsampler không trả về prompt khả dụng, pipeline sẽ ném ra lỗi thay vì render.

Để hiển thị `prompt` đúng như đã cho, hãy lấy bước ra khỏi các khối. Khối được lấy ra cũng có thể chạy độc lập, chẳng hạn để hiển thị prompt cho người dùng trước khi render:

```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]
```

Nếu không có bước này, một prompt chỉnh sửa ở bất kỳ dạng nào mà upsampler viết, có thể là bản tóm tắt gồm sáu phần hoặc một đoạn văn bắt đầu bằng `Edit <Picture 1>.`, sẽ được mã hóa đúng như đã viết; mọi chỉ thị khác sẽ được thêm tiền tố đó.

## Mẫu

- 8 bước được thực hiện trên `sample_sigmas` của checkpoint. Truyền `sigmas` để sử dụng lưới khác.
- Mô hình được chưng cất theo hướng dẫn, do đó không có guider, `negative_prompt` hay `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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/p_h3_image/modular_pipeline.py#L22)

Một ModularPipeline cho P-H3-Image, một mô hình hình ảnh dựa trên MiniMax-H3, cho việc tạo hình ảnh từ văn bản (`text2image`) và chỉnh sửa dựa trên hướng dẫn (`image_conditioned`).

Hình ảnh là một khung tiềm năng đơn lẻ, được khử nhiễu trong một chuỗi đóng gói duy nhất với hai tiềm năng âm thanh bị loại bỏ.

```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()
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/p_h3_image/modular_blocks_p_h3_image.py#L376)

Các khối pipeline mô-đun cho P-H3-Image: `text2image`, và chỉnh sửa dựa trên hướng dẫn (`image_conditioned`) khi `image` được truyền vào. `prompt` sẽ đi qua prompt upsampler trước; hãy bỏ bước `prompt_upsampler` để hiển thị như đã cho.

Các quy trình làm việc được hỗ trợ:
- `text2image`: yêu cầu `prompt`
- `image_conditioned`: yêu cầu `prompt`, `image`

Các thành phần: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): Bộ tăng cấp prompt. prompt_upsampler_processor (`AutoProcessor`): Bộ xử lý của nó. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

Configs: reference_min_pixels (mặc định: 1048576) reference_max_pixels (mặc định: 8388608) canvas_min_pixels (mặc định:
4194304) vision_pixels (mặc định: 1000000) sample_sigmas (mặc định: [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]): Lưới lấy mẫu của checkpoint, được sử dụng khi `sigmas` không được truyền vào.

Inputs: image (`Image | list`, *tùy chọn*): Ảnh cần chỉnh sửa, hoặc một danh sách tối đa 8 ảnh: ảnh đầu tiên sẽ được chỉnh sửa, các ảnh còn lại là ảnh tham chiếu. height (`int`, *tùy chọn*): Chiều cao của ảnh được tạo ra tính bằng pixel, được làm tròn đến bội số của 32. Mặc định là 2912 cho `text2image`, hoạt động tốt nhất ở 8 megapixel. Một bản chỉnh sửa mặc định dùng kích thước của ảnh đầu tiên, ít nhất là `canvas_min_pixels`, và hoạt động tốt nhất ở 4 hoặc 8 megapixel. width (`int`, *tùy chọn*): Chiều rộng của ảnh được tạo ra tính bằng pixel, được làm tròn đến bội số của 32. Mặc định là 2912 cho `text2image`, hoạt động tốt nhất ở 8 megapixel. Một bản chỉnh sửa mặc định dùng kích thước của ảnh đầu tiên, ít nhất là `canvas_min_pixels`, và hoạt động tốt nhất ở 4 hoặc 8 megapixel. prompt (`str`): Prompt, hoặc hướng dẫn chỉnh sửa khi `image` được truyền vào. Một chuỗi duy nhất. max_new_tokens (`int`, *tùy chọn*, mặc định là 1536 hoặc 1024, tùy thuộc vào quy trình làm việc): Số token tối đa mà bộ tăng độ phân giải có thể tạo ra, bao gồm cả phần suy luận. vision_images (`list`, *tùy chọn*): Các ảnh của bản chỉnh sửa đã được thay đổi kích thước cho bộ mã hóa văn bản, ảnh cần chỉnh sửa đứng đầu. reference_images (`list`, *tùy chọn*): Các ảnh của bản chỉnh sửa đã được thay đổi kích thước cho VAE, ảnh cần chỉnh sửa đứng đầu. condition_latents (`list`, *tùy chọn*): Các latents điều kiện của các ảnh trong bản chỉnh sửa. Hình dạng của chúng xác định hình học của các khối tham chiếu. generator (`Generator`, *tùy chọn*): Bộ tạo của yêu cầu. Nhiễu điều kiện được lấy từ nó trước tiên, một lần lấy cho mỗi điều kiện, trước khi lấy nhiễu của các hàng được tạo ra. latents (`Tensor`): Nhiễu ảnh được tạo trước có hình dạng `(1, latent_channels, 1, latent_height, latent_width)`, được sử dụng thay cho việc lấy ngẫu nhiên. sigmas (`list`, *tùy chọn*): Một lưới lấy mẫu tùy chỉnh, giảm nghiêm ngặt và kết thúc ở 0. Mặc định là `sample_sigmas` của checkpoint. **denoiser_input_fields (`None`, *tùy chọn*): Mô tả cấu trúc của chuỗi đóng gói mà transformer đọc theo tên: `token_tags`, `position_ids` và ba tensor chỉ số hàng. attention_kwargs (`dict`, *tùy chọn*): Các kwargs bổ sung cho các bộ xử lý attention. output_type (`str`, *tùy chọn*, mặc định là pil): Định dạng đầu ra: 'pil', 'np', 'pt'.

Đầu ra: hình ảnh (`list`): Các hình ảnh được tạo ra.

## PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

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

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

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L22)

**Tham số:**

hidden_state_indices (`tuple[int, ...]`, mặc định là `(13, 19, 25, 31, 36)`) : Các mục nào của `hidden_states` của text encoder được đọc, theo cách đánh số của `output_hidden_states` (`0` là đầu ra embedding, `i` là đầu ra của lớp decoder `i`, và mục cuối cùng là trạng thái ẩn đã chuẩn hóa cuối cùng).

text_hidden_size (`int`, mặc định là `2560`) : Kích thước ẩn của trình mã hóa văn bản.

out_channels (`int`, mặc định là `5120`) : Số lượng kênh của điều kiện mà transformer của MiniMax-H3 đọc.

Ánh xạ các trạng thái ẩn của bộ mã hóa văn bản Qwen3-VL của P-H3-Image sang điều kiện văn bản mà transformer của nó đọc.

Các trạng thái ẩn được liệt kê trong `hidden_state_indices` được nối lại, chuẩn hóa, chiếu tuyến tính và khử chuẩn hóa. Token đầu tiên là một attention sink với cùng điều kiện cho mọi prompt, do đó nó được thay thế bằng `sink_embedding`.

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

```python
forward(hidden_states: tuple[torch.Tensor, ...])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L61)

**Tham số:**

hidden_states (`tuple[torch.Tensor, ...]`) : Trạng thái ẩn của bộ mã hóa văn bản, như cách `output_hidden_states=True` trả về: một tensor có hình dạng `(batch_size, num_tokens, text_hidden_size)` cho mỗi mục.

**Trả về:** `torch.Tensor`

điều kiện, có hình dạng `(batch_size, num_tokens, out_channels)`, trong dtype của các tham số của bộ kết nối.