# LLaVa-NeXT-Video ## Visão geral O modelo LLaVa-NeXT-Video foi proposto em [LLaVA-NeXT: A Strong Zero-shot Video Understanding Model](https://llava-vl.github.io/blog/2024-04-30-llava-next-video/) por Yuanhan Zhang, Bo Li, Haotian Liu, Yong Jae Lee, Liangke Gui, Di Fu, Jiashi Feng, Ziwei Liu, Chunyuan Li. O LLaVa-NeXT-Video aprimora o [LLaVa-NeXT](llava_next) por meio de fine-tuning em uma mistura de conjuntos de dados de vídeo e imagem, aumentando assim o desempenho do modelo em vídeos. [LLaVA-NeXT](llava_next) apresenta, surpreendentemente, um forte desempenho na compreensão de conteúdo de vídeo de forma zero-shot, graças à técnica AnyRes que utiliza. A técnica AnyRes representa naturalmente uma imagem de alta resolução em múltiplas imagens. Essa técnica é naturalmente generalizável para representar vídeos, pois vídeos podem ser considerados como um conjunto de quadros (semelhante a um conjunto de imagens no LLaVA-NeXT). A versão atual do LLaVA-NeXT faz uso do AnyRes e é treinada com fine-tuning supervisionado (SFT) sobre o LLaVA-Next em dados de vídeo para alcançar melhores capacidades de compreensão de vídeo. O modelo é o SOTA atual entre os modelos de código aberto no [VideoMME bench](https://huggingface.co/papers/2405.21075). A introdução do blog é a seguinte: Em 30 de janeiro de 2024, lançamos o LLaVA-NeXT, um Large Multimodal Model (LMM) de código aberto treinado exclusivamente em dados de texto e imagem. Com a técnica AnyRes proposta, ele aprimora as capacidades de raciocínio, OCR e conhecimento do mundo, demonstrando desempenho notável em uma ampla gama de tarefas de compreensão multimodal baseadas em imagem, e até mesmo superando o Gemini-Pro em vários benchmarks de imagem, como MMMU e MathVista. **Na exploração de hoje, mergulhamos no desempenho do LLaVA-NeXT no âmbito de tarefas de compreensão de vídeo. Revelamos que o LLaVA-NeXT surpreendentemente apresenta um forte desempenho na compreensão de conteúdo de vídeo. A versão atual do LLaVA-NeXT para vídeos traz várias melhorias:** - Capacidades de representação de vídeo em zero-shot com AnyRes: a técnica AnyRes representa naturalmente uma imagem de alta resolução em múltiplas imagens que um VIT pré-treinado é capaz de processar, formando-as em uma sequência concatenada. Essa técnica é naturalmente generalizável para representar vídeos (compostos por múltiplos quadros), permitindo que o modelo LLaVA-Next, treinado apenas com imagens, execute-se de forma surpreendentemente bem em tarefas de vídeo. Notavelmente, esta é a primeira vez que LMMs demonstram uma forte capacidade de transferência de modalidade em zero-shot. - A inferência com generalização de comprimento melhora em vídeos mais longos. A técnica de escalonamento linear permite a generalização de comprimento, permitindo que o LLaVA-NeXT processe eficazmente vídeos longos, superando a limitação do "max_token_length" do LLM. - Capacidade robusta de compreensão de vídeo. (1) O LLaVA-Next-Image, que combina as duas técnicas acima, apresenta desempenho zero-shot superior ao de LMMs de código aberto ajustados em vídeos. (2) O LLaVA-Next-Video, que realiza um ajuste fino supervisionado (SFT) do LLaVA-Next-Image em dados de vídeo, atinge melhores capacidades de compreensão de vídeo em comparação com o LLaVA-Next-Image. (3) O LLaVA-Next-Video-DPO, que alinha a resposta do modelo com o feedback de IA usando otimização de preferência direta (DPO), demonstra um aumento significativo no desempenho. - Implantação e inferência eficientes com SGLang. Ele permite inferência 5x mais rápida em tarefas de vídeo, viabilizando um serviço mais escalável, como a re-legendagem de vídeos em escala de milhões. Consulte as instruções em nosso repositório.** Este modelo foi contribuído por [RaushanTurganbay](https://huggingface.co/RaushanTurganbay). O código original pode ser encontrado [aqui](https://github.com/LLaVA-VL/LLaVA-NeXT/tree/inference). ## Dicas de uso - Recomendamos que os usuários utilizem `padding_side="left"` ao realizar a geração em lote, pois isso resulta em resultados mais precisos. Basta garantir que você chame `processor.tokenizer.padding_side = "left"` antes de gerar. - Llava-Next usa um número diferente de patches para as imagens e, portanto, precisa preencher os inputs dentro do código de modelagem, além do preenchimento realizado ao processar os inputs. A configuração padrão é "left-padding" se o modelo estiver em modo `eval()`, caso contrário, "right-padding". > [!NOTE] > Os modelos LLaVA após o lançamento da v4.46 exibirão avisos sobre a adição de `processor.patch_size = {{patch_size}}`, `processor.num_additional_image_tokens = {{num_additional_image_tokens}}` e `processor.vision_feature_select_strategy = {{vision_feature_select_strategy}}`. É fortemente recomendável adicionar os atributos ao processor se você for o proprietário do checkpoint do modelo, ou abrir um PR caso não seja. Adicionar esses atributos faz com que o LLaVA tente inferir o número de tokens de imagem necessários por imagem e expandir o texto com tantos placeholders `` quanto houver tokens. Geralmente, são cerca de 500 tokens por imagem, portanto, certifique-se de que o texto não seja truncado, pois caso contrário ocorrerá falha ao mesclar os embeddings. Os atributos podem ser obtidos da configuração do modelo, como `model.config.vision_config.patch_size` ou `model.config.vision_feature_select_strategy`. O `num_additional_image_tokens` deve ser `1` se o backbone de visão adicionar um token CLS ou `0` se nada extra for adicionado aos patches de visão. ### Formatando prompts com modelos de chat Cada **checkpoint** é treinado com um formato de prompt específico, dependendo do backbone do modelo de linguagem subjacente. Para garantir o formato correto, use o método `apply_chat_template` do processador. **Importante:** - Você deve construir um histórico de conversa — passar uma string simples não funcionará. - Cada mensagem deve ser um dicionário com as chaves `"role"` e `"content"`. - O `"content"` deve ser uma lista de dicionários para diferentes modalidades, como `"text"` e `"image"`. Aqui está um exemplo de como estruturar sua entrada. Usaremos [LLaVA-NeXT-Video-7B-hf](https://huggingface.co/llava-hf/LLaVA-NeXT-Video-7B-hf) e um histórico de conversa com vídeos e imagens. ```python from transformers import LlavaNextVideoProcessor processor = LlavaNextVideoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf") conversation = [ { "role": "system", "content": [ {"type": "text", "text": "A chat between a curious human and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the human's questions."}, ], }, { "role": "user", "content": [ {"type": "text", "text": "What’s shown in this image?"}, {"type": "image"}, ], }, { "role": "assistant", "content": [{"type": "text", "text": "This image shows a red stop sign."},] }, { "role": "user", "content": [ {"type": "text", "text": "Why is this video funny?"}, {"type": "video"}, ], }, ] text_prompt = processor.apply_chat_template(conversation, add_generation_prompt=True) # Note that the template simply formats your prompt, you still have to tokenize it and obtain pixel values for your visuals print(text_prompt) ``` 🚀 **Bônus:** Se você estiver usando `transformers>=4.49.0`, também pode obter uma saída vetorizada de `apply_chat_template`. Consulte os **Exemplos de uso** abaixo para mais detalhes sobre como usá-lo. ## Exemplo de uso ### Modo de Mídia Única O modelo pode aceitar tanto imagens quanto vídeos como entrada. Aqui está um exemplo de código para inferência em meia precisão (`torch.float16`): ```python from huggingface_hub import hf_hub_download from transformers import LlavaNextVideoForConditionalGeneration, LlavaNextVideoProcessor # Load the model in half-precision model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf", device_map="auto") processor = LlavaNextVideoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf") # Load the video as an np.array, sampling uniformly 8 frames (can sample more for longer videos) video_path = hf_hub_download(repo_id="raushan-testing-hf/videos-test", filename="sample_demo_1.mp4", repo_type="dataset") conversation = [ { "role": "user", "content": [ {"type": "text", "text": "Why is this video funny?"}, {"type": "video", "path": video_path}, ], }, ] inputs = processor.apply_chat_template(conversation, num_frames=8, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(model.device) out = model.generate(**inputs, max_new_tokens=60) processor.batch_decode(out, skip_special_tokens=True, clean_up_tokenization_spaces=True) ``` ### Modo de Mídia Mista O modelo também pode gerar a partir de entradas de imagem e vídeo intercaladas. No entanto, observe que ele não foi treinado em um cenário de imagem e vídeo intercalados, o que pode afetar o desempenho. Abaixo, há um exemplo de uso para entrada de mídia mista; adicione as seguintes linhas ao trecho de código acima: ```python # Generate from image and video mixed inputs conversation = [ { "role": "user", "content": [ {"type": "text", "text": "How many cats are there in the image?"}, {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"}, ], }, { "role": "assistant", "content": [{"type": "text", "text": "There are two cats"}], }, { "role": "user", "content": [ {"type": "text", "text": "Why is this video funny?"}, {"type": "video", "path": video_path}, ], }, ] inputs = processor.apply_chat_template(conversation, num_frames=8, add_generation_prompt=True, tokenize=True, return_dict=True, padding=True, return_tensors="pt").to(model.device) # Generate generate_ids = model.generate(**inputs, max_length=50) processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True) ``` ## Otimização de modelos ### Quantização usando Bitsandbytes para eficiência de memória O modelo pode ser carregado em bits menores, reduzindo significativamente a carga de memória e mantendo o desempenho do modelo original. Isso permite uma implantação eficiente em cenários com recursos limitados. Primeiro, certifique-se de instalar o bitsandbytes executando `pip install bitsandbytes` e de ter acesso a uma GPU/acelerador compatível com a biblioteca. bitsandbytes está sendo refatorado para suportar múltiplos backends além do CUDA. Atualmente, as implementações para ROCm (GPU AMD) e CPU Intel estão maduras, com o Intel XPU em andamento e o suporte a Apple Silicon esperado para o Q4/Q1. Para instruções de instalação e as atualizações mais recentes dos backends, visite [este link](https://huggingface.co/docs/bitsandbytes/main/en/installation#multi-backend). Valorizamos seu feedback para ajudar a identificar bugs antes do lançamento completo! Consulte [esses documentos](https://huggingface.co/docs/bitsandbytes/main/en/non_cuda_backends) para mais detalhes e links de feedback. Em seguida, basta carregar o modelo quantizado adicionando [BitsAndBytesConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.BitsAndBytesConfig), conforme mostrado abaixo: ```python from transformers import LlavaNextVideoForConditionalGeneration # specify how to quantize the model quantization_config = BitsAndBytesConfig( load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.float16, ) model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf", quantization_config=quantization_config, device_map="auto") ``` ### Flash-Attention 2 para acelerar a geração Além disso, podemos acelerar significativamente a inferência do modelo usando [Flash Attention](../kernel_doc/loading_kernels#attention-kernels), que é uma implementação mais rápida do mecanismo de atenção usado dentro do modelo. Primeiro, certifique-se de instalar a versão mais recente do Flash Attention 2: ```bash pip install -U flash-attn --no-build-isolation ``` Além disso, você deve ter um hardware compatível com Flash-Attention 2. Leia mais sobre isso na documentação oficial do [repositório flash attention](https://github.com/Dao-AILab/flash-attention). O FlashAttention-2 só pode ser usado quando um modelo é carregado em `torch.float16` ou `torch.bfloat16`. Para carregar e executar um modelo usando Flash Attention-2, basta adicionar `attn_implementation="flash_attention_2"` ao carregar o modelo, conforme mostrado a seguir: ```python from transformers import LlavaNextVideoForConditionalGeneration model = LlavaNextVideoForConditionalGeneration.from_pretrained( "llava-hf/LLaVA-NeXT-Video-7B-hf", , attn_implementation="flash_attention_2", ).to(0, device_map="auto") ``` ## LlavaNextVideoConfig[[transformers.LlavaNextVideoConfig]] #### transformers.LlavaNextVideoConfig[[transformers.LlavaNextVideoConfig]] ```python transformers.LlavaNextVideoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_index: int = 32001, video_token_index: int = 32000, projector_hidden_act: str = 'gelu', vision_feature_select_strategy: typing.Literal['default', 'full'] = 'default', vision_feature_layer: int | list[int] = -2, multimodal_projector_bias: bool = True, tie_word_embeddings: bool = False, image_grid_pinpoints: list | None = None, spatial_pool_mode: str = 'average', spatial_pool_stride: int = 2, image_seq_length: int = 576, video_seq_length: int = 288) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/llava_next_video/configuration_llava_next_video.py#L32) **Parâmetros:** vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de visão. text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de texto. image_token_index (`int`, *opcional*, padrão `32001`) : O índice do token de imagem usado como marcador para as imagens de entrada. video_token_index (`int`, *opcional*, padrão `32000`) : O índice do token de vídeo usado como marcador de posição para os vídeos de entrada. projector_hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação usada pelo projetor multimodal. vision_feature_select_strategy (`Literal[default, full]`, *opcional*, padrão `default`) : A estratégia de seleção de recursos usada para selecionar o recurso visual do backbone visual. vision_feature_layer (`Union[int, list[int]]`, *opcional*, padrão `-2`) : O índice da camada para selecionar o recurso visual. Se vários índices forem fornecidos, os recursos visuais dos índices correspondentes serão concatenados para formar os recursos visuais. multimodal_projector_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés no projetor multimodal. tie_word_embeddings (`bool`, *opcional*, padrão `False`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo. image_grid_pinpoints (`List`, *opcional*, padrão `[[336, 672], [672, 336], [672, 672], [1008, 336], [336, 1008]]`) : Uma lista de resoluções possíveis para processar imagens de alta resolução. Cada item da lista deve ser uma tupla ou lista no formato `(height, width)`. spatial_pool_mode (`str`, *opcional*, padrão `"average"`) : Modo de pooling a ser usado para vídeos. Pode ser "average", "max" ou "conv". spatial_pool_stride (`int`, *opcional*, padrão 2) : Passada usada na camada de pooling para vídeos. image_seq_length (`int`, *opcional*, padrão `576`) : Comprimento da sequência de um embedding de imagem. video_seq_length (`int`, *opcional*, padrão `288`) : Comprimento da sequência de um embedding de vídeo. Esta é a classe de configuração para armazenar a configuração de um LlavaNextVideoModel. Ela é usada para instanciar um modelo Llava Next Video de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [llava-hf/LLaVA-NeXT-Video-7B-hf](https://huggingface.co/llava-hf/LLaVA-NeXT-Video-7B-hf) Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações. Exemplo: ```python >>> from transformers import LlavaNextVideoForConditionalGeneration, LlavaNextVideoConfig, CLIPVisionConfig, LlamaConfig >>> # Initializing a CLIP-vision config >>> vision_config = CLIPVisionConfig() >>> # Initializing a Llama config >>> text_config = LlamaConfig() >>> configuration = LlavaNextVideoConfig(vision_config, text_config) >>> model = LlavaNextVideoForConditionalGeneration(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## LlavaNextVideoProcessor[[transformers.LlavaNextVideoProcessor]] #### transformers.LlavaNextVideoProcessor[[transformers.LlavaNextVideoProcessor]] ```python transformers.LlavaNextVideoProcessor(video_processor = None, image_processor = None, tokenizer = None, chat_template = None, patch_size = None, vision_feature_select_strategy = None, video_token = '