|
| 1 | +<!--Copyright 2024 The HuggingFace Team. All rights reserved. |
| 2 | +
|
| 3 | +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with |
| 4 | +the License. You may obtain a copy of the License at |
| 5 | +
|
| 6 | +http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | +
|
| 8 | +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on |
| 9 | +an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| 10 | +specific language governing permissions and limitations under the License. |
| 11 | +
|
| 12 | +⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be |
| 13 | +rendered properly in your Markdown viewer. |
| 14 | +
|
| 15 | +--> |
| 16 | + |
| 17 | +# Emu3 |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +The Emu3 model was proposed in [Emu3: Next-Token Prediction is All You Need](https://arxiv.org/abs/2409.18869) by Xinlong Wang, Xiaosong Zhang, Zhengxiong Luo, Quan Sun, Yufeng Cui, Jinsheng Wang, Fan Zhang, Yueze Wang, Zhen Li, Qiying Yu, Yingli Zhao, Yulong Ao, Xuebin Min, Tao Li, Boya Wu, Bo Zhao, Bowen Zhang, Liangdong Wang, Guang Liu, Zheqi He, Xi Yang, Jingjing Liu, Yonghua Lin, Tiejun Huang, Zhongyuan Wang. |
| 22 | + |
| 23 | +Emu3 is a multimodal LLM that uses vector quantization to tokenize images into discrete tokens. Discretized image tokens are later fused with text token ids for image and text generation. The model can additionally generate images by predicting image token ids. |
| 24 | + |
| 25 | + |
| 26 | +The abstract from the paper is the following: |
| 27 | + |
| 28 | +*While next-token prediction is considered a promising path towards artificial general intelligence, it has struggled to excel in multimodal tasks, which are still dominated by diffusion models (e.g., Stable Diffusion) and compositional approaches (e.g., CLIP combined with LLMs). In this paper, we introduce Emu3, a new suite of state-of-the-art multimodal models trained solely with next-token prediction. By tokenizing images, text, and videos into a discrete space, we train a single transformer from scratch on a mixture of multimodal sequences. Emu3 outperforms several well-established task-specific models in both generation and perception tasks, surpassing flagship models such as SDXL and LLaVA-1.6, while eliminating the need for diffusion or compositional architectures. Emu3 is also capable of generating high-fidelity video via predicting the next token in a video sequence. We simplify complex multimodal model designs by converging on a singular focus: tokens, unlocking great potential for scaling both during training and inference. Our results demonstrate that next-token prediction is a promising path towards building general multimodal intelligence beyond language. We open-source key techniques and models to support further research in this direction.* |
| 29 | + |
| 30 | +Tips: |
| 31 | + |
| 32 | +- We advise users to set `processor.tokenizer.padding_side = "left"` before batched generation as it leads to more accurate results. |
| 33 | + |
| 34 | +- Note that the model has been trained with a specific prompt format for chatting. Use `processor.apply_chat_template(my_conversation_dict)` to correctly format your prompts. |
| 35 | + |
| 36 | +- Emu3 has two different checkpoints for image-generation and text-generation, make sure to use the correct checkpoint when loading the model. To generate an image, it is advised to use `prefix_constraints` so that the generated tokens are sampled only from possible image tokens. See more below for usage examples. |
| 37 | + |
| 38 | +> [!TIP] |
| 39 | +> Emu3 implementation in Transformers uses a special image token to indicate where to merge image embeddings. The special image token isn't new and uses one of the reserved tokens: `<|extra_0|>`. You have to add `<image>` to your prompt in the place where the image should be embedded for correct generation. |
| 40 | +
|
| 41 | + |
| 42 | +This model was contributed by [RaushanTurganbay](https://huggingface.co/RaushanTurganbay). |
| 43 | +The original code can be found [here](https://github.com/baaivision/Emu3). |
| 44 | + |
| 45 | + |
| 46 | +## Usage example |
| 47 | + |
| 48 | +### Text generation inference |
| 49 | + |
| 50 | +Here's how to load the model and perform inference in half-precision (`torch.bfloat16`) to generate textual output from text or text and image inputs: |
| 51 | + |
| 52 | +```python |
| 53 | +from transformers import Emu3Processor, Emu3ForConditionalGeneration |
| 54 | +import torch |
| 55 | +from PIL import Image |
| 56 | +import requests |
| 57 | + |
| 58 | +processor = Emu3Processor.from_pretrained("Emu3-community/Emu3-Chat-hf") |
| 59 | +model = Emu3ForConditionalGeneration.from_pretrained("Emu3-community/Emu3-Chat-hf", torch_dtype=torch.bfloat16, device_map="cuda") |
| 60 | + |
| 61 | +# prepare image and text prompt |
| 62 | +url = 'http://images.cocodataset.org/val2017/000000039769.jpg' |
| 63 | +image = Image.open(requests.get(url, stream=True).raw) |
| 64 | +prompt = "What do you see in this image?<image>" |
| 65 | + |
| 66 | +inputs = processor(images=image, text=prompt, return_tensors="pt").to(model.device, dtype=torch.bfloat16) |
| 67 | + |
| 68 | +# autoregressively complete prompt |
| 69 | +output = model.generate(**inputs, max_new_tokens=50) |
| 70 | +print(processor.decode(output[0], skip_special_tokens=True)) |
| 71 | +``` |
| 72 | + |
| 73 | +### Image generation inference |
| 74 | + |
| 75 | +Emu3 can also generate images from textual input. Here is how you can do it: |
| 76 | + |
| 77 | +```python |
| 78 | +processor = Emu3Processor.from_pretrained("Emu3-community/Emu3-Gen-hf") |
| 79 | +model = Emu3ForConditionalGeneration.from_pretrained("Emu3-community/Emu3-Gen-hf", torch_dtype="bfloat16", device_map="auto", attn_implementation="flash_attention_2") |
| 80 | + |
| 81 | + |
| 82 | +inputs = processor( |
| 83 | + text=["a portrait of young girl. masterpiece, film grained, best quality.", "a dog running under the rain"], |
| 84 | + padding=True, |
| 85 | + return_tensors="pt", |
| 86 | + return_for_image_generation=True, |
| 87 | +) |
| 88 | +inputs = inputs.to(device="cuda:0", dtype=torch.bfloat16) |
| 89 | + |
| 90 | +neg_prompt = "lowres, bad anatomy, bad hands, text, error, missing fingers, extra digit, fewer digits, cropped, worst quality, low quality, normal quality, jpeg artifacts, signature, watermark, username, blurry." |
| 91 | +neg_inputs = processor(text=[neg_prompt] * 2, return_tensors="pt").to(device="cuda:0") |
| 92 | + |
| 93 | +image_sizes = inputs.pop("image_sizes") |
| 94 | +HEIGHT, WIDTH = image_sizes[0] |
| 95 | +VISUAL_TOKENS = model.vocabulary_mapping.image_tokens |
| 96 | + |
| 97 | +def prefix_allowed_tokens_fn(batch_id, input_ids): |
| 98 | + height, width = HEIGHT, WIDTH |
| 99 | + visual_tokens = VISUAL_TOKENS |
| 100 | + image_wrapper_token_id = torch.tensor([processor.tokenizer.image_wrapper_token_id], device=model.device) |
| 101 | + eoi_token_id = torch.tensor([processor.tokenizer.eoi_token_id], device=model.device) |
| 102 | + eos_token_id = torch.tensor([processor.tokenizer.eos_token_id], device=model.device) |
| 103 | + pad_token_id = torch.tensor([processor.tokenizer.pad_token_id], device=model.device) |
| 104 | + eof_token_id = torch.tensor([processor.tokenizer.eof_token_id], device=model.device) |
| 105 | + eol_token_id = processor.tokenizer.encode("<|extra_200|>", return_tensors="pt")[0] |
| 106 | + |
| 107 | + position = torch.nonzero(input_ids == image_wrapper_token_id, as_tuple=True)[0][0] |
| 108 | + offset = input_ids.shape[0] - position |
| 109 | + if offset % (width + 1) == 0: |
| 110 | + return (eol_token_id, ) |
| 111 | + elif offset == (width + 1) * height + 1: |
| 112 | + return (eof_token_id, ) |
| 113 | + elif offset == (width + 1) * height + 2: |
| 114 | + return (eoi_token_id, ) |
| 115 | + elif offset == (width + 1) * height + 3: |
| 116 | + return (eos_token_id, ) |
| 117 | + elif offset > (width + 1) * height + 3: |
| 118 | + return (pad_token_id, ) |
| 119 | + else: |
| 120 | + return visual_tokens |
| 121 | + |
| 122 | + |
| 123 | +out = model.generate( |
| 124 | + **inputs, |
| 125 | + max_new_tokens=50_000, # make sure to have enough tokens for one image |
| 126 | + prefix_allowed_tokens_fn=prefix_allowed_tokens_fn, |
| 127 | + return_dict_in_generate=True, |
| 128 | + negative_prompt_ids=neg_inputs.input_ids, # indicate for Classifier-Free Guidance |
| 129 | + negative_prompt_attention_mask=neg_inputs.attention_mask, |
| 130 | +) |
| 131 | + |
| 132 | +image = model.decode_image_tokens(out.sequences[:, inputs.input_ids.shape[1]: ], height=HEIGHT, width=WIDTH) |
| 133 | +images = processor.postprocess(list(image.float()), return_tensors="PIL.Image.Image") # internally we convert to np but it's not supported in bf16 precision |
| 134 | +for i, image in enumerate(images['pixel_values']): |
| 135 | + image.save(f"result{i}.png") |
| 136 | + |
| 137 | +``` |
| 138 | + |
| 139 | + |
| 140 | +## Emu3Config |
| 141 | + |
| 142 | +[[autodoc]] Emu3Config |
| 143 | + |
| 144 | +## Emu3VQVAEConfig |
| 145 | + |
| 146 | +[[autodoc]] Emu3VQVAEConfig |
| 147 | + |
| 148 | +## Emu3TextConfig |
| 149 | + |
| 150 | +[[autodoc]] Emu3TextConfig |
| 151 | + |
| 152 | +## Emu3Processor |
| 153 | + |
| 154 | +[[autodoc]] Emu3Processor |
| 155 | + |
| 156 | +## Emu3ImageProcessor |
| 157 | + |
| 158 | +[[autodoc]] Emu3ImageProcessor |
| 159 | + - preprocess |
| 160 | + |
| 161 | +## Emu3VQVAE |
| 162 | + |
| 163 | +[[autodoc]] Emu3VQVAE |
| 164 | + - forward |
| 165 | + |
| 166 | +## Emu3TextModel |
| 167 | + |
| 168 | +[[autodoc]] Emu3TextModel |
| 169 | + - forward |
| 170 | + |
| 171 | +## Emu3ForCausalLM |
| 172 | + |
| 173 | +[[autodoc]] Emu3ForCausalLM |
| 174 | + - forward |
| 175 | + |
| 176 | +## Emu3ForConditionalGeneration |
| 177 | + |
| 178 | +[[autodoc]] Emu3ForConditionalGeneration |
| 179 | + - forward |
0 commit comments