#
# Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
# 이 파일은 라이선스에 따라만 사용할 수 있습니다.
# 라이선스 사본은 다음에서 가져올 수 있습니다
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어
# 라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"
# 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.
# 권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요
# 라이선스 하의 제한 사항. -->

# PRX 픽셀

PRXPixel은 Photoroom에서 개발한 픽셀 공간 텍스트-이미지 생성 모델입니다. 약 7B 규모의 `PRXTransformer2DModel`이 VAE 없이 원본 RGB 이미지를 직접 디노이즈합니다. 이 모델은 Qwen3-VL 텍스트 인코더로 조건화되며, 각 단계에서 트랜스포머가 깨끗한 이미지를 예측하는(x-prediction) 플로우 매칭을 사용합니다. 생성 해상도는 타임스텝 변조(timestep modulation)에 입력되어 모델이 대상 크기를 인지할 수 있도록 합니다.

## 사용 가능한 모델

| 모델 | 해결 | 설명 | 권장 매개변수 | 권장 dtype |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Qwen3-VL 텍스트 인코더를 사용하는 픽셀 공간 ~7B 모델 | 28 단계, cfg=5.0 | `torch.bfloat16` |

## 파이프라인 로드

[PRXPixelPipeline](/docs/diffusers/main/ko/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline)에는 `transformers >= 4.57`(`Qwen3VLTextModel`을 도입한 버전)이 필요합니다. [from_pretrained()](/docs/diffusers/main/ko/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")
```

## 메모리 최적화

메모리가 제한된 환경의 경우:

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

**매개변수:**

transformer (`PRXTransformer2DModel`) : 약 7B 파라미터의 PRX 디노이저입니다. PRXPixel의 경우 `in_channels=3`, 병목 `img_in`, `resolution_embeds=True`로 구성되며, 깨끗한 이미지 `x0`를 예측하도록 학습됩니다.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : (픽셀 공간) latents의 노이즈를 제거하는 데 사용되는 Flow-matching 스케줄러입니다.

text_encoder (`PreTrainedModel`) : 프롬프트를 인코딩하는 데 사용되는 Qwen3-VL 텍스트 백본입니다(비전 타워는 제거됩니다). `last_hidden_state`를 반환해야 합니다.

tokenizer (`PreTrainedTokenizerBase`) : `text_encoder`용 Tokenizer(일반적으로 `AutoTokenizer`를 통해 로드됨).

default_sample_size (`int`, *선택 사항*, 기본값 1024) : `__call__`에 높이가 제공되지 않을 때 사용되는 기본 높이/너비입니다.

prompt_max_tokens (`int`, *선택 사항*, 기본값 256) : 인코딩 전에 프롬프트가 패딩/잘림되는 텍스트 토큰 수.

noise_scale (`float`, *선택 사항*, 기본값 2.0) : 초기 가우시안 노이즈에 적용되는 스케일입니다. PRXPixel은 단위(unit)가 아닌 초기 노이즈 스케일로 학습되므로, 샘플링은 `randn * noise_scale`에서 시작해야 합니다.

PRXPixel 모델을 사용한 텍스트-이미지 생성을 위한 Pipeline입니다.

PRXPixel은 독립형 픽셀 공간 텍스트-이미지 생성 파이프라인입니다. 약 7B 파라미터의 `PRXTransformer2DModel`로 원시 RGB를 직접 디노이즈하며 VAE가 없습니다(생성이 완전히 픽셀 공간에서 이루어지므로 디노이즈된 출력 *이* 곧 이미지입니다). 프롬프트는 Qwen3-VL 텍스트 인코더로 인코딩되며(비전 타워는 폐기됩니다). [PRXPipeline](/docs/diffusers/main/ko/api/pipelines/prx#diffusers.PRXPipeline)과 달리 이 트랜스포머는 x-prediction으로 학습됩니다. 모든 단계에서 깨끗한 이미지 `x0`를 예측한 후 스케줄러 단계 전에 flow-matching 속도로 변환합니다. 샘플링은 `randn * noise_scale`에서 시작되며(`noise_scale=2.0` 기본값), 기본 해상도는 1024px입니다.

이 모델은 [DiffusionPipeline](/docs/diffusers/main/ko/api/pipelines/overview#diffusers.DiffusionPipeline)에서 상속됩니다. 라이브러리가 모든 파이프라인에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

예:
```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")
```

#### __호출__[[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 = 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 = ['latents'])
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`를 대신 전달해야 합니다.

negative_prompt (`str`, *선택 사항*, 기본값 `""`) : 이미지 생성을 안내하지 않을 프롬프트입니다. 가이던스를 사용하지 않는 경우 무시됩니다(즉, `guidance_scale`이 `1`보다 작은 경우 무시됩니다).

height (`int`, *선택 사항*, 기본값은 `default_sample_size`) : 생성된 이미지의 픽셀 단위 높이.

width (`int`, *선택 사항*, 기본값은 `default_sample_size`) : 생성된 이미지의 픽셀 단위 너비입니다.

num_inference_steps (`int`, *선택 사항*, 기본값 28) : 디노이징 단계의 수입니다. 디노이징 단계를 늘리면 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 얻을 수 있습니다.

timesteps (`list[int]`, *선택 사항*) : `set_timesteps` 메서드에 `timesteps` 인수를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 타임스텝입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다. 내림차순으로 정렬되어 있어야 합니다.

guidance_scale (`float`, *선택 사항*, 기본값 4.0) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다.

num_images_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 이미지의 수.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

latents (`torch.Tensor`, *선택 사항*) : 이미지 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

prompt_embeds (`torch.FloatTensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자로부터 텍스트 임베딩이 생성됩니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않고 `guidance_scale > 1`인 경우, 빈 문자열에서 부정 임베딩이 생성됩니다.

prompt_attention_mask (`torch.BoolTensor`, *선택 사항*) : `prompt_embeds`에 대한 사전 생성된 attention mask입니다. 제공되지 않으면 `prompt` 입력 인자로부터 attention mask가 생성됩니다.

negative_prompt_attention_mask (`torch.BoolTensor`, *선택 사항*) : `negative_prompt_embeds`에 사용할 사전 생성된 attention mask입니다. 제공되지 않고 `guidance_scale > 1`인 경우, 빈 문자열로부터 attention mask가 생성됩니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 [PRXPipelineOutput](/docs/diffusers/main/ko/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput)를 반환할지 여부.

use_resolution_binning (`bool`, *선택 사항*, 기본값 `True`) : `True`로 설정하면, 요청된 높이와 너비는 미리 정의된 종횡비 bins를 사용하여 가장 가까운 해상도로 먼저 매핑됩니다. 생성된 latents가 이미지로 디코딩된 후, 요청된 해상도로 다시 리사이즈됩니다. 최적의 해상도로 정사각형이 아닌 이미지를 생성하는 데 유용합니다.

callback_on_step_end (`Callable`, *선택 사항*) : 추론 중 각 디노이징 단계의 끝에서 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: `callback_on_step_end(self, step, timestep, callback_kwargs)`. `callback_kwargs`에는 `callback_on_step_end_tensor_inputs`로 지정된 모든 텐서 목록이 포함됩니다.

callback_on_step_end_tensor_inputs (`list`, *선택 사항*) : `callback_on_step_end` 함수의 텐서 입력 목록입니다. 목록에 지정된 텐서는 `callback_kwargs` 인수로 전달됩니다. `._callback_tensor_inputs` 속성에 나열된 텐서만 포함할 수 있습니다.

**반환값:** [PRXPipelineOutput](/docs/diffusers/main/ko/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) 또는 `tuple`

`return_dict`이 True인 경우 [PRXPipelineOutput](/docs/diffusers/main/ko/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput), 그렇지 않으면 `tuple`을 반환합니다. tuple을 반환할 경우 첫 번째 요소는 생성된 이미지의 목록입니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

모든 입력이 올바른 형식인지 확인합니다.

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

표준 텍스트 인코더와 토크나이저를 사용하여 텍스트 프롬프트를 인코딩하거나, 사전 계산된 임베딩을 사용합니다.

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

확산 프로세스를 위한 초기 latents를 준비합니다.

PRXPixel은 비단위(non-unit) 초기 노이즈 스케일로 학습되므로, 샘플링된 노이즈는 `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)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_output.py#L24)

**매개변수:**

images (`list[PIL.Image.Image]` 또는 `np.ndarray`) : 길이가 `batch_size`인 노이즈 제거된 PIL 이미지 목록 또는 `(batch_size, height, width, num_channels)` 모양의 numpy 배열. PIL 이미지 또는 numpy 배열은 diffusion 파이프라인의 노이즈 제거된 이미지를 나타냅니다.

PRX 파이프라인의 출력 클래스입니다.