Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /pt /api /pipelines /bria_fibo2.md
mishig
3 days ago
preview code
download
raw
22.5 kB
# Bria Fibo 2.0

Fibo 2.0 é um transformer de flow-matching com 8,1 bilhões de parâmetros da [Bria](https://huggingface.co/briaai) que gera imagens a partir de legendas JSON estruturadas. Seu codificador de texto é o [Qwen3-VL](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct): um Perceiver condensa os estados ocultos do Qwen3-VL em tokens de resumo que se juntam aos tokens de imagem em um único fluxo, e cinco dos blocos do transformer também leem o Qwen3-VL diretamente por meio de atenção cruzada com gate.

Há dois checkpoints:

- [`briaai/Fibo-2.0-dev`](https://huggingface.co/briaai/Fibo-2.0-dev), o modelo completo para texto-para-imagem e edição, com classifier-free guidance. Os padrões do pipeline, 30 passos com guidance 5, são para este checkpoint.
- [`briaai/Fibo-2.0-edit-turbo`](https://huggingface.co/briaai/Fibo-2.0-edit-turbo), destilado para edição em 4 etapas sem orientação (`guidance_scale=1.0`).

Com a orientação ativada, o prompt negativo padrão é a legenda nula com a qual o modelo foi treinado: a legenda estruturada com todos os valores deixados vazios.

## Gerando

Fibo 2.0 é treinado em legendas JSON estruturadas e não funcionará bem com texto livre. Passe a legenda como uma string JSON:

```py
import json
import torch
from diffusers import BriaFibo2Pipeline
pipe = BriaFibo2Pipeline.from_pretrained("briaai/Fibo-2.0-dev", dtype=torch.bfloat16).to("cuda")
caption = {
    "short_description": "A red vintage bicycle leaning against a whitewashed wall on a narrow Mediterranean street.",
    "objects": [
        {
            "description": "A red vintage bicycle with a wicker basket of lemons on its handlebars.",
            "location": "center",
            "relative_size": "large within frame",
        }
    ],
    "background_setting": "A whitewashed wall with a blue wooden door and potted red geraniums.",
    "lighting": {"conditions": "bright morning sun", "direction": "from the right", "shadows": "long and crisp"},
    "aesthetics": {"composition": "centered", "color_scheme": "red, white and blue", "mood_atmosphere": "calm"},
    "photographic_characteristics": {"depth_of_field": "deep", "focus": "sharp on the bicycle", "camera_angle": "eye level"},
    "style_medium": "photograph",
    "context": "A travel photograph.",
    "artistic_style": "realistic",
}
image = pipe(json.dumps(caption)).images[0]
image.save("bicycle.png")
```

O pipeline limpa a legenda da mesma forma que o treinamento: remove valores vazios e os campos `aesthetic_score` e `preference_score`, que não existiam em nenhuma legenda de treinamento, e serializa a legenda de forma compacta. Duas formas curtas também foram treinadas e são mantidas como estão:

```py
# The caption's short description alone, as plain text
image = pipe("A red vintage bicycle leaning against a whitewashed wall on a narrow Mediterranean street.").images[0]
# Exactly a "short_description" and a "text_render" list. The list is kept even when it's empty, to say the image
# has no text
caption = {"short_description": "A bakery storefront at dawn with a painted sign.", "text_render": [{"text": "FRESH BREAD"}]}
image = pipe(json.dumps(caption)).images[0]
```

Para transformar texto livre em uma legenda estruturada, consulte os modelos de prompt para JSON na página [Bria Fibo](https://huggingface.co/briaai/FIBO).

## Edição

O mesmo pipeline edita imagens. Passe a imagem como `image` e a instrução de edição como o prompt:

```py
import torch
from diffusers import BriaFibo2Pipeline
from diffusers.utils import load_image
pipe = BriaFibo2Pipeline.from_pretrained("briaai/Fibo-2.0-dev", dtype=torch.bfloat16).to("cuda")
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
)
edited = pipe("Make the background a snowy forest", image=image).images[0]
edited.save("pikachu_snow.png")
```

Para edições mais rápidas, carregue o checkpoint turbo e desative o guidance:

```py
import torch
from diffusers import BriaFibo2Pipeline
from diffusers.utils import load_image
pipe = BriaFibo2Pipeline.from_pretrained("briaai/Fibo-2.0-edit-turbo", dtype=torch.bfloat16).to("cuda")
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
)
edited = pipe("Make the background a snowy forest", image=image, num_inference_steps=4, guidance_scale=1.0).images[0]
edited.save("pikachu_snow.png")
```

Os exemplos abaixo partem de um dos dois, com seu `pipe` e `image`. Com o checkpoint turbo, passe `num_inference_steps=4` e `guidance_scale=1.0` para cada chamada.

### O prompt de edição

O prompt também pode ser um objeto JSON com a chave `"edit_instruction"` e uma legenda do resultado, em qualquer um dos formatos com os quais o Fibo 2.0 foi treinado para editar. O pipeline o converte no prompt com o qual o Fibo 2.0 foi treinado para editar.

Legenda completa: as chaves da legenda ao lado de `"edit_instruction"`, conforme os modelos prompt-to-JSON da Bria escrevem para edições. O pipeline remove valores vazios e os campos `aesthetic_score` e `preference_score`, que o treinamento removeu de todas as legendas.

```py
import json
prompt = {
    "short_description": "A crocheted yellow Pikachu doll sitting in a snowy pine forest.",
    "objects": [{"description": "A crocheted yellow Pikachu doll with red cheeks.", "location": "center"}],
    "background_setting": "A snowy pine forest with falling snow.",
    "edit_instruction": "Make the background a snowy forest",
}
edited = pipe(json.dumps(prompt), image=image).images[0]
```

Uma breve descrição: uma string em uma chave `"structured_caption"`.

```py
prompt = {
    "structured_caption": "A crocheted yellow Pikachu doll sitting in a snowy pine forest.",
    "edit_instruction": "Make the background a snowy forest",
}
edited = pipe(json.dumps(prompt), image=image).images[0]
```

Uma breve descrição e seu texto: exatamente uma `"short_description"` e uma lista `"text_render"`. A lista é mantida mesmo quando está vazia, o que informa ao Fibo 2.0 que o resultado não possui texto. Uma chave `"structured_caption"` pode conter esse formato, ou também uma legenda completa.

```py
prompt = {
    "short_description": "A crocheted yellow Pikachu doll holding a small wooden sign.",
    "text_render": [{"text": "HELLO"}],
    "edit_instruction": "Give the doll a small wooden sign that reads HELLO",
}
edited = pipe(json.dumps(prompt), image=image).images[0]
```

### Várias imagens

Até 5 imagens podem ser editadas juntas, por exemplo, para colocar um objeto de uma em outra. A instrução se refere a elas em ordem como `<image_1>`, `<image_2>` e assim por diante.

```py
cat = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
edited = pipe("Put the cat from <image_2> next to the doll in <image_1>", image=[image, cat]).images[0]
```

### Tamanho da saída

A menos que `height` e `width` sejam fornecidos, o resultado assume o tamanho em que o Fibo 2.0 foi treinado para a proporção de aspecto da primeira imagem, cerca de um megapixel. Uma única imagem é recortada para o tamanho do resultado. Várias imagens são recortadas individualmente para o tamanho treinado correspondente à proporção de aspecto de cada uma.

```py
edited = pipe("Make the background a snowy forest", image=image, width=1424, height=800).images[0]
```

### Edições mascaradas

`mask` marca a região de uma única imagem a ser regenerada, em branco sobre preto, no tamanho da imagem. O Fibo 2.0 foi treinado em edições cuja imagem tem essa região acinzentada, e o pipeline a acinzentar da mesma forma antes de a imagem ser codificada: cinza plano (128, 128, 128), através da máscara feita binária em 128.

```py
from PIL import Image, ImageDraw
mask = Image.new("L", image.size, 0)
ImageDraw.Draw(mask).rectangle((image.width // 2, 0, image.width, image.height // 2), fill=255)
edited = pipe("Add a red balloon floating in the sky", image=image, mask=mask).images[0]
```

## Texto em imagens

Quando a legenda pede por texto, em suas entradas `text_render`, o Fibo 2.0 tende a renderizá-lo melhor se o Qwen3-VL também vir cada texto desenhado individualmente. O pipeline desenha essas imagens por padrão, da mesma forma que no treinamento, e elas podem ser desativadas. Para uma legenda com texto, como a da padaria acima:

```py
prompt = json.dumps(caption)
image = pipe(prompt, render_text_images=False).images[0]
```

O treinamento mostrou ao Fibo 2.0 essas imagens para algumas legendas com texto e não para outras, então funciona de qualquer forma.

- Cada entrada `text_render` que possui `text` recebe uma imagem: o texto em uma linha, preto sobre branco, na fonte embutida do Pillow, tamanho 20. Um texto com mais de 256 caracteres é dividido em linhas de 256.
- Caracteres que a fonte não possui são desenhados com a primeira das `fonts` que os contém. O treinamento usou Aileron e, em seguida, DejaVu Sans, que estão na pasta `fonts` de [`briaai/Fibo-2.0-dev`](https://huggingface.co/briaai/Fibo-2.0-dev). Sem `fonts`, esses caracteres são desenhados como a fonte embutida do Pillow os desenha, e o pipeline emite um aviso.
- O pipeline marca cada entrada com um campo `image_tokens` para sua imagem, e o Qwen3-VL vê as imagens após quaisquer imagens a serem editadas.
- Uma geração executa seus primeiros passos, enquanto o nível de ruído estiver acima de `pipe.text_images_max_noise_level` (0.9), na legenda sem as imagens. Uma edição as utiliza em cada passo.
- Uma legenda sem texto não recebe imagens, assim como uma descrição curta, como no treinamento.

Para desenhá-los com as fontes usadas no treinamento:

```py
from huggingface_hub import hf_hub_download
fonts = [
    hf_hub_download("briaai/Fibo-2.0-dev", name, subfolder="fonts")
    for name in ("Aileron-Regular.otf", "DejaVuSans.ttf")
]
image = pipe(prompt, fonts=fonts).images[0]
```

Para desenhar as imagens você mesmo, passe-as como `text_images`, uma para cada entrada de `text_render` que possui `text`, em ordem, para um único prompt. Elas têm precedência sobre as do próprio pipeline. Imagens desenhadas de forma diferente da do treinamento estão fora da distribuição.

## Backends de atenção

O transformer é executado em qualquer um dos [backends de atenção](../../optimization/attention_backends) do diffusers, por exemplo, FlashAttention-3 em GPUs Hopper, como a H100:

```py
pipe.transformer.set_attention_backend("_flash_3_varlen_hub")
```

`_flash_3_hub` também funciona para um único prompt, mas não aceita máscaras, portanto não consegue executar um lote de prompts de comprimentos diferentes (veja abaixo).

## Lote

Vários prompts podem ser gerados em uma única chamada. Prompts de diferentes comprimentos são preenchidos (padded), e o preenchimento é mascarado em todas as camadas de atenção, portanto, um lote (batch) assim requer um backend de atenção que aceite uma máscara: o padrão, ou um backend varlen, como `flash_varlen`. Em float32, um lote reproduz as imagens das chamadas separadas; em bfloat16, os kernels de atenção diferem entre entradas preenchidas e não preenchidas, de modo que as imagens em lote podem diferir das chamadas individuais em detalhes finos.

## BriaFibo2Pipeline[[diffusers.BriaFibo2Pipeline]]

#### diffusers.BriaFibo2Pipeline[[diffusers.BriaFibo2Pipeline]]

```python
diffusers.BriaFibo2Pipeline(transformer: BriaFibo2Transformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Qwen3VLForConditionalGeneration, processor: Qwen3VLProcessor)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/bria_fibo2/pipeline_bria_fibo2.py#L171)

**Parâmetros:**

transformer ([BriaFibo2Transformer2DModel](/docs/diffusers/main/pt/api/models/transformer_bria_fibo2#diffusers.BriaFibo2Transformer2DModel)) : O transformer que remove o ruído dos latentes da imagem.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Agendador usado com `transformer` para desruidar os latentes.

vae (`AutoencoderKLFlux2`) : Autoencoder variacional que mapeia imagens para latentes e vice-versa.

text_encoder (`Qwen3VLForConditionalGeneration`) : Qwen3-VL. Seus estados ocultos condicionam o transformer.
processor (`Qwen3VLProcessor`) : Converte o prompt e as imagens a serem editadas em entradas do Qwen3-VL.
Pipeline para geração de texto para imagem e edição de imagem com Fibo 2.0.
#### __call__[[diffusers.BriaFibo2Pipeline.__call__]]
```python
__call__(prompt: str | list[str] | None = None, image: PIL.Image.Image | list[PIL.Image.Image] | None = None, mask: PIL.Image.Image | None = None, text_images: list[PIL.Image.Image] | None = None, render_text_images: bool = True, fonts: list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 30, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str = 'pil', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/bria_fibo2/pipeline_bria_fibo2.py#L571)
**Parâmetros:**
prompt (`str` ou `list[str]`, *opcional*) : O prompt para orientar a geração da imagem, geralmente um prompt JSON estruturado, que é limpo conforme as legendas limpas do treinamento do Fibo 2.0: valores vazios e os campos `aesthetic_score` e `preference_score` são descartados, e ele é serializado de forma compacta. Com `image`, a instrução de edição, ou um objeto JSON com uma chave `"edit_instruction"` e a legenda do resultado: suas outras chaves, ou uma chave `"structured_caption"` contendo a legenda ou uma breve descrição.
image (`PIL.Image.Image` ou `list[PIL.Image.Image]`, *opcional*) : A imagem a ser editada, ou até 5 imagens a serem editadas juntas, às quais a instrução pode se referir como `<image_1>`, `<image_2>` e assim por diante. Sem `image`, o pipeline gera uma imagem a partir do prompt.
mask (`PIL.Image.Image`, *opcional*) : A região de `image` a ser regenerada, em branco sobre preto, ao editar uma única imagem. Assim como no treinamento, a região é esmaecida antes de a imagem ser codificada, por meio da máscara binarizada em 128.
text_images (`list[PIL.Image.Image]`, *opcional*) : Imagens do texto que a legenda solicita, uma para cada entrada de `text_render` que possui `text`, na ordem: o texto de cada entrada desenhado individualmente, conforme desenhado por `render_text_images`. O Qwen3-VL as visualiza junto com o prompt, cada uma marcada em sua entrada de legenda, o que ajuda o Fibo 2.0 a renderizar o texto. Exige `prompt` como uma única legenda em JSON e tem precedência sobre `render_text_images`. Uma geração executa seus primeiros passos, enquanto o nível de ruído estiver acima de `text_images_max_noise_level` (0.9), sem elas; uma edição as utiliza em cada passo.

render_text_images (`bool`, *opcional*, padrão `True`) : Se deve desenhar as `text_images` de cada legenda, da mesma forma que o treinamento do Fibo 2.0 as desenhava: cada texto em uma linha, preto sobre branco, na fonte embutida do Pillow com tamanho 20, e os caracteres que essa fonte não possui na primeira das `fonts` que os tiver. Uma legenda sem texto, e um prompt sem uma legenda em JSON, como uma descrição curta, não recebem imagens, assim como no treinamento.

fonts (`list[str]`, *opcional*) : Caminhos das fontes para desenhar os caracteres de `text_images` que a fonte embutida do Pillow não possui, em ordem. O treinamento os desenhou em Aileron e, em seguida, em DejaVu Sans, que estão na pasta `fonts` de `briaai/Fibo-2.0-dev`. Sem elas, tais caracteres são desenhados da mesma forma que a fonte embutida do Pillow os desenha.

height (`int`, *opcional*) : A altura em pixels da imagem gerada. Deve ser divisível por 16. O valor padrão é 1024, ou, ao editar, o tamanho Fibo 2.0 foi treinado para a proporção de aspecto da primeira imagem, cerca de um megapixel.

width (`int`, *opcional*) : A largura em pixels da imagem gerada. Deve ser divisível por 16. Padrão semelhante ao de `height`.

num_inference_steps (`int`, *opcional*, padrão 30) : O número de etapas de desruidamento.

guidance_scale (`float`, *opcional*, padrão 5.0) : Escala de orientação sem classificador. Valores acima de 1 executam o prompt negativo como uma segunda passagem em cada etapa, e 1.0 desativa a orientação.
negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt para guiar a geração para longe de quando o guidance está ativado. O padrão é a legenda nula com a qual o Fibo 2.0 foi treinado: a legenda estruturada com todos os valores vazios.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.
generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Gerador(es) usados para extrair o ruído inicial, para geração determinística.
latents (`torch.Tensor`, *opcional*) : Ruído inicial pré-gerado com forma `(batch_size, 32, height // 8, width // 8)`.

prompt_embeds (`torch.Tensor`, *opcional*) : Incorporações de texto pré-computadas de `encode_prompt`, usadas no lugar de `prompt`.

prompt_embeds_mask (`torch.Tensor`, *opcional*) : A máscara `encode_prompt` retornada junto com `prompt_embeds`. Necessária quando eles são preenchidos (padded).

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Incorporações de texto pré-computadas do prompt negativo, usadas no lugar de `negative_prompt`.

negative_prompt_embeds_mask (`torch.Tensor`, *opcional*) : A máscara `encode_prompt` retornada com `negative_prompt_embeds`. Necessária quando eles são preenchidos.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída: `"pil"`, `"np"`, `"pt"` ou `"latent"`.
return_dict (`bool`, *opcional*, padrão `True`) : Se deve retornar um `BriaFibo2PipelineOutput` em vez de uma tupla simples.

callback_on_step_end (`Callable`, *opcional*) : Uma função chamada no final de cada etapa de desruidamento como `callback_on_step_end(self, step, timestep, callback_kwargs)`.
callback_on_step_end_tensor_inputs (`list[str]`, *opcional*, padrão `["latents"]`) : Os tensores passados para `callback_on_step_end` em `callback_kwargs`.

**Retorna:** `BriaFibo2PipelineOutput` ou `tuple`

as imagens geradas.

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

Exemplos:
```py
>>> import json
>>> import torch
>>> from diffusers import BriaFibo2Pipeline
>>> from diffusers.utils import load_image
>>> # Fibo 2.0 reads structured JSON captions, serialized compactly the way it was trained
>>> caption = {
...     "short_description": "A red bicycle leaning against a white brick wall on a sunny morning.",
...     "objects": [{"description": "a red city bicycle with a wicker basket", "location": "center"}],
...     "background_setting": "a white brick wall with a green door",
...     "lighting": {"conditions": "bright morning sun", "direction": "from the right"},
...     "style_medium": "photograph",
... }
>>> prompt = json.dumps(caption, separators=(",", ":"), ensure_ascii=False)
>>> # 30 steps with guidance 5, the defaults
>>> pipe = BriaFibo2Pipeline.from_pretrained("briaai/Fibo-2.0-dev", dtype=torch.bfloat16).to("cuda")
>>> image = pipe(prompt).images[0]
>>> image.save("fibo2.png")
>>> # editing: pass the image, and the instruction as the prompt
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
... )
>>> edited = pipe("Make the background a snowy forest", image=image).images[0]
>>> edited.save("fibo2_edit.png")
```

#### encode_prompt[[diffusers.BriaFibo2Pipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], image: list[PIL.Image.Image] | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, text_images: list[PIL.Image.Image] | list[list[PIL.Image.Image]] | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/bria_fibo2/pipeline_bria_fibo2.py#L351)

**Parâmetros:**

prompt (`str` ou `list[str]`) : O prompt ou os prompts a serem codificados. Com `image`, cada prompt é uma instrução de edição ou um objeto JSON com uma chave `"edit_instruction"` e a legenda do resultado: suas outras chaves, ou uma chave `"structured_caption"` contendo a legenda ou uma breve descrição. Um prompt de geração é codificado como fornecido: `__call__` primeiro coloca uma legenda JSON no formato com o qual o Fibo 2.0 foi treinado.

image (`list[PIL.Image.Image]`, *opcional*) : As imagens a serem editadas, conforme vistas pelo Qwen3-VL. Cada prompt edita todas elas.

device (`torch.device`, *opcional*) : O dispositivo em que as embeddings serão colocadas.

num_images_per_prompt (`int`, padrão 1) : Número de imagens a serem geradas por prompt.
prompt_embeds (`torch.Tensor`, *opcional*) : Incorporações de texto pré-computadas com forma `(batch_size, 6, text_len, 7680)`, usadas no lugar de `prompt`.

prompt_embeds_mask (`torch.Tensor`, *opcional*) : Máscara Bool dos tokens reais em `prompt_embeds`, de forma `(batch_size, text_len)`.

text_images (`list[PIL.Image.Image]` ou `list[list[PIL.Image.Image]]`, *opcional*) : Imagens do texto da legenda, uma para cada entrada de `text_render` que possui `text`, em ordem, ou uma lista delas por prompt. Cada entrada recebe o marcador de visão da sua imagem, e o Qwen3-VL vê as imagens após quaisquer imagens a serem editadas.

**Retorna:**

Os embeddings de texto, e sua máscara, ou `None` quando nenhum prompt foi preenchido.
Xet Storage Details

Size:: 22.5 kB
Xet hash:: 72acb958e43c3422dac44705c22a976add7332f878ab0f8ec3e298f52a9961b6
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.