#
# Được cấp phép theo Giấy phép Apache, Phiên bản 2.0 (gọi là "Giấy phép");
# bạn có thể không sử dụng tệp này ngoại trừ tuân thủ theo Giấy phép.
# Bạn có thể nhận được một bản sao của Giấy phép tại
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Trừ khi được yêu cầu bởi luật pháp có hiệu lực hoặc được thỏa thuận bằng văn bản, phần mềm
# được phân phối theo Giấy phép được phân phối trên cơ sở
# KHÔNG CÓ BẢO HÀNH HOẶC ĐIỀU KIỆN DƯỚI BẤT KỲ HÌNH THỨC NÀO, dù được nêu rõ hay ngụ ý.
# Xem Giấy phép để biết ngôn ngữ cụ thể điều chỉnh các quyền và
# giới hạn theo Giấy phép. -->

# PRX Pixel

PRXPixel là mô hình tạo ảnh từ văn bản trong không gian pixel do Photoroom phát triển. Một `PRXTransformer2DModel` ~7B khử nhiễu trực tiếp trên ảnh RGB thô — không cần VAE. Mô hình được điều kiện bởi bộ mã hóa văn bản Qwen3-VL và sử dụng flow matching, trong đó transformer dự đoán ảnh sạch ở mỗi bước (x-prediction). Độ phân giải tạo ảnh được đưa vào điều biến bước thời gian (timestep modulation) để mô hình nhận biết kích thước đích.

## Các model khả dụng

| Mô hình | Giải pháp | Mô tả | Các tham số được đề xuất | dtype được khuyến nghị |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Mô hình không gian pixel ~7B với bộ mã hóa văn bản Qwen3-VL | 28 bước, cfg=5.0 | `torch.bfloat16` |

## Tải pipeline

[PRXPixelPipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline) yêu cầu `transformers >= 4.57` (phiên bản giới thiệu `Qwen3VLTextModel`). Nạp nó bằng [from_pretrained()](/docs/diffusers/v0.43.0/vi/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")
```

## Tối ưu hóa bộ nhớ

Đối với các môi trường bị giới hạn bộ nhớ:

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

**Tham số:**

transformer (`PRXTransformer2DModel`) : Bộ khử nhiễu PRX có ~7B tham số. Đối với PRXPixel, mô hình này được xây dựng với `in_channels=3`, một nút thắt cổ chai `img_in`, và `resolution_embeds=True`, và được huấn luyện để dự đoán ảnh sạch `x0`.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Trình lập lịch flow-matching được sử dụng để khử nhiễu các latents (không gian pixel).

text_encoder (`PreTrainedModel`) : Khung xương văn bản Qwen3-VL được sử dụng để mã hóa các prompt (tháp thị giác bị loại bỏ). Phải trả về một `last_hidden_state`.

tokenizer (`PreTrainedTokenizerBase`) : Tokenizer cho `text_encoder` (thường được nạp qua `AutoTokenizer`).

default_sample_size (`int`, *tuỳ chọn*, mặc định là 1024) : Chiều cao/chiều rộng mặc định được sử dụng khi không có giá trị nào được cung cấp cho `__call__`.

prompt_max_tokens (`int`, *tuỳ chọn*, mặc định là 256) : Số lượng token văn bản mà prompt được đệm/cắt ngắn đến trước khi mã hóa.

noise_scale (`float`, *optional*, mặc định là 2.0) : Hệ số tỷ lệ áp dụng cho nhiễu Gaussian ban đầu. PRXPixel được huấn luyện với hệ số tỷ lệ nhiễu ban đầu không đơn vị, do đó quá trình lấy mẫu phải bắt đầu từ `randn * noise_scale`.

Pipeline để tạo ảnh từ văn bản với mô hình PRXPixel.

PRXPixel là một pipeline text-to-image độc lập, hoạt động trong không gian pixel. Nó khử nhiễu trực tiếp trên dữ liệu RGB thô bằng `PRXTransformer2DModel` có khoảng 7B tham số và không có VAE (quá trình tạo ảnh diễn ra hoàn toàn trong không gian pixel, nên đầu ra sau khi khử nhiễu *chính là* ảnh). Prompt được mã hóa bằng text encoder Qwen3-VL (tháp thị giác bị loại bỏ). Khác với [PRXPipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/prx#diffusers.PRXPipeline), transformer được huấn luyện với x-prediction: ở mỗi bước, nó dự đoán ảnh sạch `x0`, sau đó giá trị này được chuyển thành velocity của flow-matching trước khi thực hiện bước scheduler. Quá trình lấy mẫu bắt đầu từ `randn * noise_scale` (mặc định `noise_scale=2.0`) và độ phân giải mặc định là 1024px.

Mô hình này kế thừa từ [DiffusionPipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/overview#diffusers.DiffusionPipeline). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các pipeline (chẳng hạn như tải xuống hoặc lưu, chạy trên một thiết bị cụ thể, v.v.)

Ví dụ:
```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'])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `prompt_embeds` thay thế.

negative_prompt (`str`, *tùy chọn*, mặc định là `""`) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

height (`int`, *tuỳ chọn*, mặc định là `default_sample_size`) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel.

width (`int`, *tuỳ chọn*, mặc định là `default_sample_size`) : Độ rộng của hình ảnh được tạo ra, tính bằng pixel.

num_inference_steps (`int`, *optional*, mặc định là 28) : Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn, với cái giá là suy luận chậm hơn.

timesteps (`list[int]`, *optional*) : Các bước thời gian (timesteps) tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch (scheduler) hỗ trợ tham số `timesteps` trong phương thức `set_timesteps` của chúng. Nếu không được định nghĩa, hành vi mặc định khi `num_inference_steps` được truyền vào sẽ được sử dụng. Phải được sắp xếp theo thứ tự giảm dần.

guidance_scale (`float`, *optional*, mặc định là 4.0) : Thang độ dẫn hướng như được định nghĩa trong [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` được định nghĩa là `w` của phương trình 2. trong [Imagen Paper](https://huggingface.co/papers/2205.11487). Thang độ dẫn hướng được kích hoạt bằng cách đặt `guidance_scale > 1`. Thang độ dẫn hướng cao hơn khuyến khích tạo ra các hình ảnh gắn kết chặt chẽ với `prompt` văn bản, thường phải đánh đổi bằng chất lượng hình ảnh thấp hơn.

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Một hoặc một danh sách [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) để đảm bảo quá trình sinh là tất định.

latents (`torch.Tensor`, *tùy chọn*) : Các latents nhiễu đã được tạo trước, được lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể được sử dụng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo ra bằng cách lấy mẫu sử dụng `generator` ngẫu nhiên được cung cấp.

prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp và `guidance_scale > 1`, các vector nhúng âm sẽ được tạo từ một chuỗi rỗng.

prompt_attention_mask (`torch.BoolTensor`, *tùy chọn*) : Mặt nạ chú ý (attention mask) được tạo trước cho `prompt_embeds`. Nếu không được cung cấp, mặt nạ chú ý sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_attention_mask (`torch.BoolTensor`, *tùy chọn*) : Mặt nạ chú ý (attention mask) được tạo trước cho `negative_prompt_embeds`. Nếu không được cung cấp và `guidance_scale > 1`, mặt nạ chú ý sẽ được tạo từ một chuỗi rỗng.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Định dạng đầu ra của hình ảnh được tạo. Chọn giữa [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` hoặc `np.array`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một [PRXPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) thay vì một tuple thông thường hay không.

use_resolution_binning (`bool`, *tuỳ chọn*, mặc định là `True`) : Nếu được đặt thành `True`, chiều cao và chiều rộng được yêu cầu sẽ trước tiên được ánh xạ sang các độ phân giải gần nhất bằng cách sử dụng các bin tỷ lệ khung hình được định nghĩa trước. Sau khi các latents được tạo ra được giải mã thành hình ảnh, chúng sẽ được thay đổi kích thước trở lại độ phân giải được yêu cầu. Hữu ích để tạo ra các hình ảnh không vuông ở các độ phân giải tối ưu.

callback_on_step_end (`Callable`, *tùy chọn*) : Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau: `callback_on_step_end(self, step, timestep, callback_kwargs)`. `callback_kwargs` sẽ bao gồm một danh sách tất cả các tensor như được chỉ định bởi `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Danh sách các đầu vào tensor cho hàm `callback_on_step_end`. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham số `callback_kwargs`. Bạn chỉ có thể bao gồm các tensor được liệt kê trong thuộc tính `._callback_tensor_inputs`.

**Trả về:** [PRXPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) hoặc `tuple`

[PRXPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) nếu `return_dict` là True, ngược lại là một `tuple. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:
```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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

Kiểm tra xem tất cả các đầu vào có đúng định dạng hay không.

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

Mã hóa prompt văn bản bằng trình mã hóa và bộ phân từ văn bản tiêu chuẩn, hoặc sử dụng các embedding đã được tính toán trước.

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

Chuẩn bị các latent ban đầu cho quá trình khuếch tán.

PRXPixel được huấn luyện với thang đo nhiễu ban đầu không đơn vị, do đó nhiễu được lấy mẫu sẽ được nhân với `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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_output.py#L24)

**Tham số:**

images (`list[PIL.Image.Image]` hoặc `np.ndarray`) : danh sách các hình ảnh PIL đã khử nhiễu có độ dài `batch_size` hoặc mảng numpy có hình dạng `(batch_size, height, width, num_channels)`. Các hình ảnh PIL hoặc mảng numpy thể hiện các hình ảnh đã khử nhiễu của pipeline khuếch tán.

Lớp đầu ra cho các pipeline PRX.