#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença.
-->

# CogView3Plus

[CogView3: Geração de texto para imagem mais detalhada e rápida via difusão em sequência](https://huggingface.co/papers/2403.05121) da Universidade de Tsinghua e da ZhipuAI, por Wendi Zheng, Jiayan Teng, Zhuoyi Yang, Weihan Wang, Jidong Chen, Xiaotao Gu, Yuxiao Dong, Ming Ding, Jie Tang.

O resumo do artigo é:

*Os avanços recentes em sistemas generativos de texto para imagem foram impulsionados em grande parte por modelos de difusão. No entanto, os modelos de difusão de texto para imagem de estágio único ainda enfrentam desafios em termos de eficiência computacional e refinamento dos detalhes da imagem. Para abordar esse problema, propomos o CogView3, um framework em cascata inovador que melhora o desempenho da difusão de texto para imagem. O CogView3 é o primeiro modelo a implementar difusão por retransmissão no campo da geração de texto para imagem, executando a tarefa primeiro criando imagens de baixa resolução e, em seguida, aplicando super-resolução baseada em retransmissão. Essa metodologia não apenas resulta em saídas competitivas de texto para imagem, mas também reduz significativamente os custos de treinamento e inferência. Nossos resultados experimentais demonstram que o CogView3 supera o SDXL, o modelo de difusão de texto para imagem open-source atual com estado da arte, em 77,0% nas avaliações humanas, tudo isso exigindo apenas cerca de 1/2 do tempo de inferência. A variante destilada do CogView3 atinge desempenho comparável utilizando apenas 1/10 do tempo de inferência do SDXL.*

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

Este pipeline foi contribuído por [zRzRzRzRzRzRzR](https://github.com/zRzRzRzRzRzRzR). A base de código original pode ser encontrada [aqui](https://huggingface.co/THUDM). Os pesos originais podem ser encontrados em [hf.co/THUDM](https://huggingface.co/THUDM).

## CogView3PlusPipeline[[diffusers.CogView3PlusPipeline]]

#### diffusers.CogView3PlusPipeline[[diffusers.CogView3PlusPipeline]]

```python
diffusers.CogView3PlusPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKL, transformer: CogView3PlusTransformer2DModel, scheduler: diffusers.schedulers.scheduling_ddim_cogvideox.CogVideoXDDIMScheduler | diffusers.schedulers.scheduling_dpm_cogvideox.CogVideoXDPMScheduler)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cogview3/pipeline_cogview3plus.py#L118)

**Parâmetros:**

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`T5EncoderModel`) : Codificador de texto congelado. O CogView3Plus usa [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel); especificamente a variante [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

tokenizer (`T5Tokenizer`) : Tokenizer da classe [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

transformer ([CogView3PlusTransformer2DModel](/docs/diffusers/main/pt/api/models/cogview3plus_transformer2d#diffusers.CogView3PlusTransformer2DModel)) : Um `CogView3PlusTransformer2DModel` condicionado por texto para desruidar os latentes da imagem codificada.

scheduler ([SchedulerMixin](/docs/diffusers/main/pt/api/schedulers/overview#diffusers.SchedulerMixin)) : Um scheduler para ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

Pipeline para geração de texto para imagem usando CogView3Plus.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

#### __call__[[diffusers.CogView3PlusPipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, negative_prompt: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] | None = None, guidance_scale: float = 5.0, num_images_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, original_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), output_type: str = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 224)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cogview3/pipeline_cogview3plus.py#L407)

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração da imagem. Se não definido, é necessário passar `prompt_embeds`.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

height (`int`, *opcional*, padrão é self.transformer.config.sample_size * self.vae_scale_factor) : A altura em pixels da imagem gerada. Se não for fornecida, é definida como 1024.

width (`int`, *opcional*, padrão é self.transformer.config.sample_size * self.vae_scale_factor) : A largura em pixels da imagem gerada. Se não for fornecida, é definida como 1024.

num_inference_steps (`int`, *opcional*, padrão `50`) : O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, em detrimento de uma inferência mais lenta.

timesteps (`list[int]`, *opcional*) : Passos de tempo personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumento `timesteps` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. Deve estar em ordem decrescente.

guidance_scale (`float`, *opcional*, padrão `5.0`) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao `prompt` de texto, geralmente em detrimento de uma menor qualidade de imagem.

num_images_per_prompt (`int`, *opcional*, padrão `1`) : O número de imagens a serem geradas por prompt.

eta (`float`, *opcional*, padrão 0.0) : Corresponde ao parâmetro eta (η) do paper [DDIM](https://arxiv.org/abs/2010.02502). Aplica-se apenas ao [DDIMScheduler](/docs/diffusers/main/pt/api/schedulers/ddim#diffusers.DDIMScheduler) e é ignorado em outros agendadores.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.FloatTensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto negativos pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

original_size (`tuple[int]`, *opcional*, padrão (1024, 1024)) : Se `original_size` não for o mesmo que `target_size`, a imagem parecerá ter sido reduzida ou ampliada. `original_size` tem como padrão `(height, width)` se não for especificado. Parte do micro-condicionamento do SDXL, conforme explicado na seção 2.2 de [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

crops_coords_top_left (`tuple[int]`, *opcional*, padrão (0, 0)) : `crops_coords_top_left` pode ser usado para gerar uma imagem que parece ter sido "recortada" a partir da posição `crops_coords_top_left` para baixo. Imagens favoráveis e bem centralizadas são geralmente obtidas ao definir `crops_coords_top_left` como (0, 0). Parte do micro-condicionamento do SDXL, conforme explicado na seção 2.2 de [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` em vez de uma tupla simples.

callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int`, padrão `224`) : Comprimento máximo da sequência no prompt codificado. Pode ser definido para outros valores, mas isso pode levar a resultados piores.

**Retorna:** [CogView3PipelineOutput](/docs/diffusers/main/pt/api/pipelines/cogview3#diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput) ou `tuple`

[CogView3PipelineOutput](/docs/diffusers/main/pt/api/pipelines/cogview3#diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput) se `return_dict` for True, caso contrário, uma `tuple`. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:
```python
>>> import torch
>>> from diffusers import CogView3PlusPipeline

>>> pipe = CogView3PlusPipeline.from_pretrained("THUDM/CogView3-Plus-3B", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A photo of an astronaut riding a horse on mars"
>>> image = pipe(prompt).images[0]
>>> image.save("output.png")
```

#### encode_prompt[[diffusers.CogView3PlusPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 224, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cogview3/pipeline_cogview3plus.py#L210)

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : prompt a ser codificado

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

do_classifier_free_guidance (`bool`, *opcional*, padrão `True`) : Se deve ou não usar classifier free guidance.

num_images_per_prompt (`int`, *opcional*, padrão 1) : Número de imagens que devem ser geradas por prompt. Dispositivo torch para colocar os embeddings resultantes

prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativos pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

max_sequence_length (`int`, padrão `224`) : Comprimento máximo da sequência no prompt codificado. Pode ser definido para outros valores, mas isso pode levar a resultados piores.

device : (`torch.device`, *opcional*): dispositivo torch

dtype : (`torch.dtype`, *opcional*): dtype do torch

Codifica o prompt em estados ocultos do codificador de texto.

## CogView3PipelineOutput[[diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput]]

#### diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput[[diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput]]

```python
diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cogview3/pipeline_output.py#L10)

**Parâmetros:**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : lista de imagens PIL desruidas de comprimento `batch_size` ou array numpy de forma `(batch_size, height, width, num_channels)`. As imagens PIL ou o array numpy apresentam as imagens desruidas do pipeline de difusão.

Classe de saída para os pipelines do CogView3.