# MiniMax-H3-Image

MiniMax-H3-Image là một mô hình ảnh của MiniMax dựa trên [MiniMax-H3](./minimax_h3), dùng để tạo ảnh từ văn bản và chỉnh sửa ảnh tham chiếu. Bạn có thể tìm thấy checkpoint tại [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).

Tương tự như MiniMax-H3, nó được tích hợp dưới dạng các khối [Modular Diffusers](../../modular_diffusers/overview) duy nhất: [MiniMaxH3ImageBlocks](/docs/diffusers/main/vi/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) và [MiniMaxH3ImageModularPipeline](/docs/diffusers/main/vi/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) của chúng là toàn bộ phần tích hợp.

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

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

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
```

Transformer và text encoder mỗi cái nặng khoảng 62 GB ở bfloat16 và không thể cùng chạy trên một GPU 80 GB, vì vậy các ví dụ sử dụng auto offloading: [ComponentsManager](/docs/diffusers/main/vi/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) sẽ di chuyển từng thành phần lên accelerator khi một block cần đến nó. Một ảnh 4736x3552 sau đó đạt đỉnh khoảng 65 GB.

Văn bản sang hình ảnh:

```py
prompt = (
    "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
    "on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
    prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]
```

Chỉnh sửa hình ảnh tham chiếu:

```py
from diffusers.utils import load_image

reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
    prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
    image=reference,
    height=4096,
    width=4096,
    generator=torch.Generator().manual_seed(1234),
    output="images",
)[0]
```

## Các thành phần

| Thành phần | Lớp |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/main/vi/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/main/vi/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | Tokenizer của text encoder và một `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/vi/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

Bộ mã hóa văn bản là cùng một bộ mà [MiniMax-H3](./minimax_h3) sử dụng. Điểm kiểm tra giữ một bản sao riêng để kho lưu trữ tự chứa; Hub khử trùng lặp các tệp giống nhau giữa các kho lưu trữ, nên bản sao không chiếm thêm dung lượng lưu trữ ở đó.

## 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 ra từ `prompt`.
- **`image_conditioned`** tạo ra nội dung từ `prompt` và một hoặc nhiều hình ảnh tham chiếu được truyền dưới dạng `image`. Prompt đề cập đến chúng theo thứ tự là `<Picture 1>`, `<Picture 2>`, và tiếp tục như vậy. Các hình ảnh tham chiếu giữ nguyên kích thước của chúng: mỗi hình chỉ được thay đổi kích thước khi cạnh ngắn nằm ngoài khoảng từ 1024 đến 2048 pixel, và không bao giờ được điều chỉnh theo kích thước của hình ảnh được tạo ra.

Prompt được sử dụng nguyên văn, không có chat template, và các mô tả dài, đầy đủ sẽ cho kết quả tốt nhất. Một prompt chỉnh sửa thường nêu rõ những gì cần giữ lại, sau đó là những gì cần thay đổi, rồi mô tả đầy đủ hình ảnh đích.

## Tăng cường prompt

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) là mô hình mở rộng prompt của MiniMax: nó viết lại một yêu cầu ngắn thành dạng mô tả chi tiết mà mô hình hình ảnh hoạt động tốt nhất, và đề xuất tỷ lệ khung hình. Các khối tùy chỉnh `diffusers/minimax-h3-image-pe-blocks` chạy nó như một pipeline riêng. Chúng cần `xgrammar` và khoảng 18 GB bộ nhớ GPU.

```py
import torch
from diffusers import ModularPipeline

enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")

state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")
```

Truyền các hình ảnh tham chiếu dưới dạng `image` để mở rộng một chỉ thị chỉnh sửa. Sau đó, truyền `prompt` vào pipeline hình ảnh, với `height` và `width` khớp với `aspect_ratio`.

## Kích thước ảnh

`height` và `width` là kích thước của hình ảnh được trả về, mặc định là 2048. Mô hình tạo ảnh ở độ phân giải 4 megapixel trở lên: yêu cầu nhỏ hơn sẽ được tạo trên một canvas lớn hơn có cùng tỷ lệ khung hình rồi được thu nhỏ lại, do đó yêu cầu 1024x1024 có chi phí tương đương với yêu cầu 2048x2048. `min_generation_area` đặt ngưỡng đó tính bằng pixel; truyền `1024` để luôn tạo ảnh ở kích thước được yêu cầu. Trong mọi trường hợp, các cạnh của canvas sẽ được làm tròn đến bội số của 32.

MiniMax khuyến nghị kích thước 4096x4096 cho tỷ lệ 1:1, 4736x3552 cho 4:3, 5024x3360 cho 3:2, 5472x3072 cho 16:9 và 6272x2688 cho 21:9, hoặc cùng các kích thước đó với chiều cao và chiều rộng hoán đổi cho nhau đối với định dạng dọc.

## Mẫu

- Checkpoint lấy mẫu trong 6 bước trên `sample_sigmas` của nó, và transformer có một đầu ra cho mỗi bước, vì vậy không có `num_inference_steps`.
- Mô hình được chưng cất theo hướng dẫn, do đó không có guider, `negative_prompt` hay `guidance_scale`.

## MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

#### diffusers.MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

```python
diffusers.MiniMaxH3ImageModularPipeline(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/minimax_h3_image/modular_pipeline.py#L27)

Một ModularPipeline cho MiniMax-H3-Image: tạo ảnh từ văn bản (`text2image`) và chỉnh sửa ảnh dựa trên ảnh tham chiếu (`image_conditioned`).

MiniMax-H3-Image chạy transformer MiniMax-H3 không có audio trên một chuỗi đóng gói gồm các hàng văn bản, các hàng của hình ảnh tham chiếu và các hàng của hình ảnh được tạo ra, vốn là một khung tiềm ẩn duy nhất. Điểm kiểm tra được chưng cất hai lần: hướng dẫn được nhúng vào trọng số, nên không có bộ hướng dẫn, không có `negative_prompt` và không có `guidance_scale`, và nó lấy mẫu trên một lưới cố định gồm sáu bước với một đầu ra của transformer cho mỗi bước, nên cũng không có `num_inference_steps`.

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image")
pipe.load_components(dtype=torch.bfloat16)
```

## MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

#### diffusers.MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

```python
diffusers.MiniMaxH3ImageBlocks()
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3_image/modular_blocks_minimax_h3_image.py#L371)

Các khối pipeline mô-đun cho MiniMax-H3-Image: `text2image`, và chỉnh sửa ảnh tham chiếu (`image_conditioned`) khi truyền `image`.

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`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3Image`) scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3ImageTransformer2DModel`)

Configs: reference_min_short_edge (mặc định: 1024) reference_max_short_edge (mặc định: 2048) vision_min_short_edge (mặc định: 1024) vision_max_short_edge (mặc định: 1024) sample_sigmas (mặc định: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): Lưới lấy mẫu mà các đầu ra theo từng bước của checkpoint đã được chưng cất trên đó.

Inputs: image (`Image | list`, *tùy chọn*): Ảnh tham chiếu của bản chỉnh sửa, hoặc một danh sách các ảnh đó. Prompt đề cập đến chúng theo thứ tự là `<Picture 1>`, `<Picture 2>`, ... prompt (`str`): Prompt để hướng dẫn quá trình tạo, một chuỗi duy nhất. vision_images (`list`, *tùy chọn*): Các ảnh tham chiếu đã được thay đổi kích thước cho text encoder. reference_images (`list`, *tùy chọn*): Các ảnh tham chiếu đã được thay đổi kích thước cho VAE. generator (`Generator`, *tùy chọn*): Bộ tạo của yêu cầu. Một mẫu hậu nghiệm cho mỗi ảnh tham chiếu được rút ra từ nó. height (`int`): Chiều cao của ảnh trả về, tính bằng pixel. width (`int`): Chiều rộng của ảnh trả về, tính bằng pixel. min_generation_area (`int`, *tùy chọn*, mặc định là 4194304): Diện tích nhỏ nhất, tính bằng pixel, mà một ảnh được tạo ra. Một `height x width` nhỏ hơn sẽ được tạo trên một canvas được phóng to lên diện tích này và sau đó được thu nhỏ lại về `height x width` sau khi giải mã. Truyền 1024 để luôn tạo ở kích thước được yêu cầu. reference_latents (`list`, *tùy chọn*): Các latents điều kiện của các ảnh tham chiếu. Hình dạng của chúng là nơi hình học của mỗi ảnh tham chiếu được lấy từ đó. latents (`Tensor`): Nhiễu được tạo trước có hình dạng `(1, latent_channels, latent_height, latent_width)`, được sử dụng thay vì việc rút ngẫu nhiên. reference_noise (`list`, *tùy chọn*): Nhiễu được tạo trước cho các ảnh tham chiếu, một tensor có hình dạng của mỗi phần tử trong `reference_latents`, được sử dụng thay vì các lần rút ngẫu nhiên. **denoiser_input_fields (`None`, *tùy chọn*): Mô tả cấu trúc của chuỗi được đóng gói mà transformer đọc theo tên: `token_tags`, `position_ids` và hai tensor chỉ số hàng. 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.