# HunYuanVL ## Visão geral HunYuanVL é um modelo de visão-linguagem para compreensão e geração de imagem-texto proposto em [HunyuanOCR Technical Report ](https://huggingface.co/papers/2511.19575). A integração open-source `hunyuan_vl` em Transformers é uma variante de imagem-texto apenas densa, adaptada para cargas de trabalho no estilo de OCR e compreensão de documentos, como [`tencent/HunyuanOCR`](https://huggingface.co/tencent/HunyuanOCR). O resumo do artigo é o seguinte: *Este artigo apresenta o HunyuanOCR, um Vision-Language Model (VLM) de nível comercial, de código aberto e leve (1B de parâmetros), dedicado a tarefas de OCR. A arquitetura compreende um Native Vision Transformer (ViT) e um LLM leve conectados por um adaptador MLP. O HunyuanOCR demonstra desempenho superior, superando APIs comerciais, pipelines tradicionais e modelos maiores (por exemplo, Qwen3-VL-4B). Especificamente, ele supera as soluções públicas atuais em tarefas de percepção (Text Spotting, Parsing) e se destaca em tarefas semânticas (IE, Text Image Translation), conquistando o primeiro lugar no ICDAR 2025 DIMT Challenge (Small Model Track). Além disso, alcança resultados state-of-the-art (SOTA) no OCRBench entre VLMs com menos de 3B de parâmetros.* *O HunyuanOCR alcança avanços em três aspectos-chave: 1) Unificação de versatilidade e eficiência: implementamos suporte abrangente para capacidades centrais, incluindo spotting, parsing, IE, VQA e tradução, dentro de um framework leve. Isso aborda as limitações dos "modelos especialistas em OCR" de escopo restrito e dos "VLMs gerais" ineficientes. 2) Arquitetura end-to-end simplificada: a adoção de um paradigma puramente end-to-end elimina as dependências de módulos de pré-processamento (por exemplo, análise de layout). Isso resolve fundamentalmente a propagação de erros comum em pipelines tradicionais e simplifica o deploy do sistema. 3) Estratégias orientadas por dados e RL: confirmamos o papel crítico de dados de alta qualidade e, pela primeira vez na indústria, demonstramos que estratégias de Reinforcement Learning (RL) geram ganhos significativos de desempenho em tarefas de OCR.* *O HunyuanOCR foi oficialmente aberto no HuggingFace. Também fornecemos uma solução de implantação de alto desempenho baseada no vLLM, colocando sua eficiência em produção no topo. Esperamos que este modelo avance a pesquisa de fronteira e forneça uma base sólida para aplicações industriais.* ## Pontos de verificação recomendados - [tencent/HunyuanOCR](https://huggingface.co/tencent/HunyuanOCR) para cargas de trabalho de OCR e extração de documentos. ## Dicas de uso Esta integração do Transformers expõe intencionalmente o caminho de imagem-texto que é exercitado por checkpoints públicos de estilo OCR. - Suportado: backbone de texto apenas denso, prompting de imagem e texto, geração no estilo OCR/entendimento de documentos. - Não suportado como parte desta variante de código aberto: entradas de vídeo e caminhos de execução MoE em tempo de execução. - Nota de compatibilidade: alguns campos de configuração legados exportados pela Tencent ainda são aceitos para que checkpoints existentes possam ser carregados, mas esses campos não implicam que a implementação de código aberto habilite recursos extras em tempo de execução. - Para o caminho de OCR atualmente validado, `attn_implementation="eager"` é o ponto de partida recomendado. - `backend="pil"` é recomendado ao carregar o processador para os checkpoints públicos atuais de OCR. - Ao agrupar prompts de comprimento variável, passe `padding=True` se precisar de saídas em tensor do processador. ## Uso ```python import torch from transformers import AutoModelForImageTextToText, AutoProcessor model_name_or_path = "tencent/HunyuanOCR" processor = AutoProcessor.from_pretrained(model_name_or_path, backend="pil") model = AutoModelForImageTextToText.from_pretrained( model_name_or_path, device_map="auto", ) messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, tokenize=True, add_generation_prompt=True, return_tensors="pt", ).to(model.device) generated_ids = model.generate(**inputs, max_new_tokens=1024) generated_ids_trimmed = generated_ids[0][len(inputs["input_ids"][0]) :] output = processor.decode(generated_ids_trimmed, skip_special_tokens=True) print(output) ``` ## HunYuanVLProcessor[[transformers.HunYuanVLProcessor]] #### transformers.HunYuanVLProcessor[[transformers.HunYuanVLProcessor]] ```python transformers.HunYuanVLProcessor(image_processor = None, tokenizer = None, chat_template = None, cat_extra_token: bool = True, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/processing_hunyuan_vl.py#L36) **Parâmetros:** image_processor (`HunYuanVLImageProcessor`) : O processador de imagens é uma entrada obrigatória. tokenizer (`Qwen2Tokenizer`) : O tokenizer é uma entrada obrigatória. chat_template (`str`) : Um modelo Jinja para converter listas de mensagens em um chat em uma string tokenizável. cat_extra_token (`bool`, *opcional*, padrão `True`) : Se deve considerar os dois tokens extras que o HunYuanVL insere em torno de cada intervalo de imagem ao calcular a sequência expandida de tokens de imagem. Constrói um HunYuanVLProcessor que encapsula um processador de imagem e um tokenizer em um único processador. [HunYuanVLProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLProcessor) oferece todas as funcionalidades de [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor) e [Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer). Consulte [~HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor) e [~Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer) para mais informações. #### __call__[[transformers.HunYuanVLProcessor.__call__]] ```python __call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] | None = None, videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/processing_utils.py#L653) **Parâmetros:** images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opcional*) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`. text (`Union[str, list[str], list[list[str]]]`, *opcional*) : A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se você passar uma entrada pretokenizada, defina `is_split_into_words=True` para evitar ambiguidade com entradas em lote. videos (`Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]`, *opcional*) : Vídeo para pré-processar. Espera um único vídeo ou um lote de vídeos com valores de pixel variando de 0 a 255. Se estiver passando vídeos com valores de pixel entre 0 e 1, defina `do_rescale=False`. audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *opcional*) : O áudio ou lote de áudios a ser preparado. Cada áudio pode ser um array NumPy ou um tensor PyTorch. No caso de um array NumPy/tensor PyTorch, cada áudio deve ter a forma (C, T), onde C é o número de canais e T é o comprimento de amostras do áudio. return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores de um framework específico. Os valores aceitos são: - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy. - ****kwargs** ([ProcessingKwargs](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessingKwargs), *opcional*) : Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados. ## HunYuanVLImageProcessor[[transformers.HunYuanVLImageProcessor]] #### transformers.HunYuanVLImageProcessor[[transformers.HunYuanVLImageProcessor]] ```python transformers.HunYuanVLImageProcessor(**kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_hunyuan_vl.py#L88) **Parâmetros:** do_convert_rgb (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve converter a imagem para RGB. do_resize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve redimensionar a imagem. size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, padrão `{'shortest_edge' : 262144, 'longest_edge': 4194304}`): Descreve as dimensões máximas de entrada para o modelo. default_to_square (`bool`, *kwargs*, *opcional*, padrão `False`) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro. crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Tamanho da imagem de saída após aplicar `center_crop`. resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, padrão `3`) : Filtro de reamostragem a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`. do_rescale (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve reescalar a imagem. rescale_factor (`float`, *kwargs*, *opcional*, padrão `0.00392156862745098`) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`. do_normalize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se a imagem deve ser normalizada. image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.48145466, 0.4578275, 0.40821073]`) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.26862954, 0.26130258, 0.27577711]`) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. do_pad (`bool`, *kwargs*, *opcional*) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo. pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.` do_center_crop (`bool`, *kwargs*, *opcional*) : Se deve centralizar o recorte da imagem. data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos. input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width). device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada. return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores. disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157 image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros. min_pixels (`int`, *kwargs*, *opcional*, padrão `512 * 512`) : O número mínimo de pixels da imagem para redimensionar a imagem. max_pixels (`int`, *kwargs*, *opcional*, padrão `2048 * 2048`) : O número máximo de pixels da imagem para redimensionar a imagem. patch_size (`int`, *kwargs*, *opcional*, padrão 16) : O tamanho do patch espacial do codificador de visão. temporal_patch_size (`int`, *kwargs*, *opcional*, padrão 1) : O tamanho do patch temporal do codificador de visão. merge_size (`int`, *kwargs*, *opcional*, padrão é 2) : O tamanho de mesclagem do codificador de visão para o codificador LLM. Constrói um processador de imagem HunYuanVLImageProcessor. #### get_number_of_image_patches[[transformers.HunYuanVLImageProcessor.get_number_of_image_patches]] ```python get_number_of_image_patches(height: int, width: int, images_kwargs: dict | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_hunyuan_vl.py#L268) **Parâmetros:** height (`int`) : Altura da imagem de entrada. width (`int`) : Largura da imagem de entrada. images_kwargs (`dict`, *opcional*) : Quaisquer kwargs para substituir os padrões do processador de imagem. **Retorna:** `tuple[int, int]` Número de patches de imagem por imagem, como uma grade `(height, width)`. Um utilitário que retorna o número de patches de imagem para um determinado tamanho de imagem. Observação: Não remova este método! Ele é usado pelo vLLM para inferir o número de patches e placeholders sem uma entrada de imagem. #### patchify[[transformers.HunYuanVLImageProcessor.patchify]] ```python patchify(images: torch.Tensor, patch_size: int, merge_size: int, temporal_patch_size: int) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_hunyuan_vl.py#L176) Converte cada imagem em um layout plano de forma (`seq_len`, `patch_dim`) para que possamos concatenar pixels com formas dinâmicas. #### preprocess[[transformers.HunYuanVLImageProcessor.preprocess]] ```python preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_hunyuan_vl.py#L139) **Parâmetros:** images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`. do_convert_rgb (`bool`, *kwargs*, *opcional*) : Se deve converter a imagem para RGB. do_resize (`bool`, *kwargs*, *opcional*) : Se deve redimensionar a imagem. size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Descreve as dimensões máximas de entrada para o modelo. default_to_square (`bool`, *kwargs*, *opcional*) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro. crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Tamanho da imagem de saída após aplicar `center_crop`. resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : Filtro de redimensionamento a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`. do_rescale (`bool`, *kwargs*, *opcional*) : Se deve reescalar a imagem. rescale_factor (`float`, *kwargs*, *opcional*) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`. do_normalize (`bool`, *kwargs*, *opcional*) : Se a imagem deve ser normalizada. image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. do_pad (`bool`, *kwargs*, *opcional*) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo. pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.` do_center_crop (`bool`, *kwargs*, *opcional*) : Se deve centralizar o recorte da imagem. data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos. input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width). device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada. return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores. disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157 image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros. min_pixels (`int`, *kwargs*, *opcional*, padrão `512 * 512`) : O número mínimo de pixels da imagem para redimensionar a imagem. max_pixels (`int`, *kwargs*, *opcional*, padrão `2048 * 2048`) : O número máximo de pixels da imagem para redimensionar a imagem. patch_size (`int`, *kwargs*, *opcional*, padrão 16) : O tamanho do patch espacial do codificador de visão. temporal_patch_size (`int`, *kwargs*, *opcional*, padrão 1) : O tamanho do patch temporal do codificador de visão. merge_size (`int`, *kwargs*, *opcional*, padrão é 2) : O tamanho de mesclagem do codificador de visão para o codificador LLM. **Retorna:** `~image_processing_base.BatchFeature` - **data** (`dict`) -- Dicionário de listas/arrays/tensors retornados pelo método __call__ ('pixel_values', etc.). - **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização. #### resize[[transformers.HunYuanVLImageProcessor.resize]] ```python resize(images: torch.Tensor, size: SizeDict, resample: PILImageResampling | tvF.InterpolationMode | int | None, factor: int, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_hunyuan_vl.py#L147) Redimensione dinamicamente com base na proporção da imagem de entrada. ## HunYuanVLImageProcessorPil[[transformers.HunYuanVLImageProcessorPil]] #### transformers.HunYuanVLImageProcessorPil[[transformers.HunYuanVLImageProcessorPil]] ```python transformers.HunYuanVLImageProcessorPil(**kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_pil_hunyuan_vl.py#L87) **Parâmetros:** do_convert_rgb (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve converter a imagem para RGB. do_resize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve redimensionar a imagem. size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, padrão `{'shortest_edge' : 262144, 'longest_edge': 4194304}`): Descreve as dimensões máximas de entrada para o modelo. default_to_square (`bool`, *kwargs*, *opcional*, padrão `False`) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro. crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Tamanho da imagem de saída após aplicar `center_crop`. resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, padrão `3`) : Filtro de reamostragem a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`. do_rescale (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve reescalar a imagem. rescale_factor (`float`, *kwargs*, *opcional*, padrão `0.00392156862745098`) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`. do_normalize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se a imagem deve ser normalizada. image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.48145466, 0.4578275, 0.40821073]`) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.26862954, 0.26130258, 0.27577711]`) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. do_pad (`bool`, *kwargs*, *opcional*) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo. pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.` do_center_crop (`bool`, *kwargs*, *opcional*) : Se deve centralizar o recorte da imagem. data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos. input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width). device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada. return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores. disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157 image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros. min_pixels (`int`, *kwargs*, *opcional*, padrão `512 * 512`) : O número mínimo de pixels da imagem para redimensionar a imagem. max_pixels (`int`, *kwargs*, *opcional*, padrão `2048 * 2048`) : O número máximo de pixels da imagem para redimensionar a imagem. patch_size (`int`, *kwargs*, *opcional*, padrão 16) : O tamanho do patch espacial do codificador de visão. temporal_patch_size (`int`, *kwargs*, *opcional*, padrão 1) : O tamanho do patch temporal do codificador de visão. merge_size (`int`, *kwargs*, *opcional*, padrão é 2) : O tamanho de mesclagem do codificador de visão para o codificador LLM. Constrói um processador de imagem HunYuanVLImageProcessor. #### get_number_of_image_patches[[transformers.HunYuanVLImageProcessorPil.get_number_of_image_patches]] ```python get_number_of_image_patches(height: int, width: int, images_kwargs: dict | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_pil_hunyuan_vl.py#L263) **Parâmetros:** height (`int`) : Altura da imagem de entrada. width (`int`) : Largura da imagem de entrada. images_kwargs (`dict`, *opcional*) : Quaisquer kwargs para substituir os padrões do processador de imagem. **Retorna:** `tuple[int, int]` Número de patches de imagem por imagem, como uma grade `(height, width)`. Um utilitário que retorna o número de patches de imagem para um determinado tamanho de imagem. Observação: Não remova este método! Ele é usado pelo vLLM para inferir o número de patches e placeholders sem uma entrada de imagem. #### patchify[[transformers.HunYuanVLImageProcessorPil.patchify]] ```python patchify(image: ndarray, patch_size: int, merge_size: int, temporal_patch_size: int) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_pil_hunyuan_vl.py#L167) Converte cada imagem em um layout plano de forma (`seq_len`, `patch_dim`) para que possamos concatenar pixels com formas dinâmicas. #### preprocess[[transformers.HunYuanVLImageProcessorPil.preprocess]] ```python preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_pil_hunyuan_vl.py#L204) **Parâmetros:** images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`. do_convert_rgb (`bool`, *kwargs*, *opcional*) : Se deve converter a imagem para RGB. do_resize (`bool`, *kwargs*, *opcional*) : Se deve redimensionar a imagem. size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Descreve as dimensões máximas de entrada para o modelo. default_to_square (`bool`, *kwargs*, *opcional*) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro. crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Tamanho da imagem de saída após aplicar `center_crop`. resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : Filtro de redimensionamento a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`. do_rescale (`bool`, *kwargs*, *opcional*) : Se deve reescalar a imagem. rescale_factor (`float`, *kwargs*, *opcional*) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`. do_normalize (`bool`, *kwargs*, *opcional*) : Se a imagem deve ser normalizada. image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`. do_pad (`bool`, *kwargs*, *opcional*) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo. pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.` do_center_crop (`bool`, *kwargs*, *opcional*) : Se deve centralizar o recorte da imagem. data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos. input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width). device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada. return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores. disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157 image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros. min_pixels (`int`, *kwargs*, *opcional*, padrão `512 * 512`) : O número mínimo de pixels da imagem para redimensionar a imagem. max_pixels (`int`, *kwargs*, *opcional*, padrão `2048 * 2048`) : O número máximo de pixels da imagem para redimensionar a imagem. patch_size (`int`, *kwargs*, *opcional*, padrão 16) : O tamanho do patch espacial do codificador de visão. temporal_patch_size (`int`, *kwargs*, *opcional*, padrão 1) : O tamanho do patch temporal do codificador de visão. merge_size (`int`, *kwargs*, *opcional*, padrão é 2) : O tamanho de mesclagem do codificador de visão para o codificador LLM. **Retorna:** `~image_processing_base.BatchFeature` - **data** (`dict`) -- Dicionário de listas/arrays/tensors retornados pelo método __call__ ('pixel_values', etc.). - **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização. #### resize[[transformers.HunYuanVLImageProcessorPil.resize]] ```python resize(image: ndarray, size: SizeDict, resample: PILImageResampling | int | None, factor: int, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/image_processing_pil_hunyuan_vl.py#L138) Redimensione dinamicamente com base na proporção da imagem de entrada. `HunYuanVLForConditionalGeneration` é o principal ponto de entrada público para a geração de texto a partir de imagem. `HunYuanVLModel` expõe o modelo base multimodal sem a cabeça de modelagem de linguagem, enquanto `HunYuanVLTextModel` expõe o backbone de texto de nível inferior. ## HunYuanVLConfig[[transformers.HunYuanVLConfig]] #### transformers.HunYuanVLConfig[[transformers.HunYuanVLConfig]] ```python transformers.HunYuanVLConfig(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, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_id: int = 120120, tie_word_embeddings: bool = True, im_start_id: int = 120118, im_end_id: int = 120119, im_newline_id: int = 120121) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/configuration_hunyuan_vl.py#L237) **Parâmetros:** text_config (`HunYuanVLTextConfig` ou `dict`, *opcional*) : Configuração do backbone de texto. Quando `None`, os valores padrão são usados. vision_config (`HunYuanVLVisionConfig` ou `dict`, *opcional*) : Configuração da torre de visão. Quando `None`, os valores padrão são usados. image_token_id (`int`, *opcional*, padrão `120120`) : O índice do token de imagem usado como marcador para as imagens de entrada. tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo. im_start_id (`int`, *opcional*, padrão 120118) : ID do token que marca o início de uma faixa de imagem em prompts multimodais. im_end_id (`int`, *opcional*, padrão 120119) : ID do token que marca o fim de uma faixa de imagem em prompts multimodais. im_newline_id (`int`, *opcional*, padrão 120121) : ID do token usado para separadores no estilo quebra de linha inseridos dentro de regiões de imagem serializadas. Configuração de nível superior para a integração open-source do HunYuanVL. Esta configuração descreve a variante apenas densa e apenas de imagem-texto, usada para cargas de trabalho de OCR e compreensão de documentos. Ela espelha o layout da família `Qwen2_5_VL` / `Qwen3_VL`: a configuração de nível superior simplesmente compõe um [HunYuanVLTextConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLTextConfig) (backbone de texto) e um [HunYuanVLVisionConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLVisionConfig) (torre de visão), além de alguns ids de tokens que delimitam spans de imagem em prompts multimodais. Exemplo: ```python >>> from transformers import HunYuanVLConfig, HunYuanVLForConditionalGeneration >>> >>> configuration = HunYuanVLConfig() >>> model = HunYuanVLForConditionalGeneration(configuration) >>> configuration = model.config ``` ## HunYuanVLVisionConfig[[transformers.HunYuanVLVisionConfig]] #### transformers.HunYuanVLVisionConfig[[transformers.HunYuanVLVisionConfig]] ```python transformers.HunYuanVLVisionConfig(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, hidden_act: str = 'gelu', hidden_size: int = 1152, intermediate_size: int = 4304, interpolate_mode: str = 'bilinear', rms_norm_eps: float = 1e-05, attention_dropout: float = 0.0, num_attention_heads: int = 16, num_key_value_heads: int | None = None, num_channels: int = 3, num_hidden_layers: int = 27, out_hidden_size: int = 4096, patch_size: int = 16, spatial_merge_size: int = 2, temporal_patch_size: int = 1, img_max_token_num: int = 4096, max_image_size: int = 2048, min_image_size: int = 512, max_vit_seq_len: int = 16384, text_hidden_size: int = 3072) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/configuration_hunyuan_vl.py#L35) **Parâmetros:** hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc. hidden_size (`int`, *opcional*, padrão `1152`) : Dimensão das representações ocultas. intermediate_size (`int`, *opcional*, padrão `4304`) : Dimensão das representações do MLP. interpolate_mode (`str`, *opcional*, padrão `"bilinear"`) : Modo de interpolação usado ao redimensionar as incorporações posicionais de patches aprendidas para corresponder à grade de imagem atual. rms_norm_eps (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização rms. attention_dropout (`float`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção. num_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. num_key_value_heads (`int`, *opcional*) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`. num_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada. num_hidden_layers (`int`, *opcional*, padrão `27`) : Número de camadas ocultas no decodificador do Transformer. out_hidden_size (`int`, *opcional*, padrão 4096) : Tamanho oculto de saída produzido pela torre de visão antes de ser consumido pelo backbone de texto. patch_size (`int`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch. spatial_merge_size (`int`, *opcional*, padrão `2`) : O tamanho da janela de mesclagem espacial usada para reduzir o número de tokens visuais mesclando patches vizinhos. temporal_patch_size (`int`, *opcional*, padrão `1`) : Tamanho do patch temporal usado no embedding de patch 3D para entradas de vídeo. img_max_token_num (`int`, *opcional*, padrão 4096) : Número máximo de tokens de imagem esperado pela pilha de visão. max_image_size (`int`, *opcional*, padrão 2048) : Tamanho máximo de imagem suportado pela configuração de visão de código aberto atual. min_image_size (`int`, *opcional*, padrão 512) : Tamanho mínimo de imagem suportado pela configuração de visão de código aberto atual. max_vit_seq_len (`int`, *opcional*, padrão 16384) : Comprimento máximo da sequência produzida pelo vision transformer. text_hidden_size (`int`, *opcional*, padrão 3072) : Tamanho oculto esperado pelo backbone de texto ao consumir embeddings visuais. Configuração do backbone de visão para a variante open-source de imagem e texto, apenas densa, do HunYuanVL. Exemplo: ```python >>> from transformers import HunYuanVLVisionConfig >>> >>> configuration = HunYuanVLVisionConfig() >>> configuration.hidden_size 1152 ``` ## HunYuanVLTextConfig[[transformers.HunYuanVLTextConfig]] #### transformers.HunYuanVLTextConfig[[transformers.HunYuanVLTextConfig]] ```python transformers.HunYuanVLTextConfig(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, vocab_size: int = 290943, hidden_size: int = 4096, intermediate_size: int = 11008, num_hidden_layers: int = 32, num_attention_heads: int = 32, num_key_value_heads: int | None = None, hidden_act: str = 'silu', max_position_embeddings: int = 2048, initializer_range: float = 0.02, rms_norm_eps: float = 1e-05, use_cache: bool = True, pad_token_id: int | None = 0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, eod_token_id: int | None = 3, pretraining_tp: int = 1, tie_word_embeddings: bool = True, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: float | int = 0.0, head_dim: int | None = None, sep_token_id: int | None = 4) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/configuration_hunyuan_vl.py#L106) **Parâmetros:** vocab_size (`int`, *opcional*, padrão `290943`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`. hidden_size (`int`, *opcional*, padrão `4096`) : Dimensão das representações ocultas. intermediate_size (`int`, *opcional*, padrão `11008`) : Dimensão das representações do MLP. num_hidden_layers (`int`, *opcional*, padrão `32`) : Número de camadas ocultas no decodificador do Transformer. num_attention_heads (`int`, *opcional*, padrão `32`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. num_key_value_heads (`int`, *opcional*) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`. hidden_act (`str`, *opcional*, padrão `silu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc. max_position_embeddings (`int`, *opcional*, padrão `2048`) : O comprimento máximo de sequência com o qual este modelo pode ser utilizado. initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. rms_norm_eps (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização rms. use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador. pad_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para preenchimento no vocabulário. bos_token_id (`int`, *opcional*, padrão `1`) : ID do token usado para o início do fluxo no vocabulário. eos_token_id (`Union[int, list[int]]`, *opcional*, padrão `2`) : ID do token usado para o fim do fluxo no vocabulário. eod_token_id (`int`, *opcional*, padrão 3) : ID do token que representa o marcador de fim de documento. Herdado de [HunYuanDenseV1Config](/docs/transformers/main/pt/model_doc/hunyuan_v1_dense#transformers.HunYuanDenseV1Config) e re-documentado aqui para manter a docstring gerada automaticamente sincronizada. pretraining_tp (`int`, *opcional*, padrão `1`) : Funcionalidade experimental. Rank de paralelismo de tensor usado durante o pré-treinamento. Consulte [este documento](https://huggingface.co/docs/transformers/main/perf_train_gpu_many#tensor-parallelism) para entender mais sobre isso. Esse valor é necessário para garantir a reprodutibilidade exata dos resultados do pré-treinamento. Consulte [esta issue](https://github.com/pytorch/pytorch/issues/76232). tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo. rope_parameters (`dict`, *opcional*) : Configuração de RoPE herdada de [HunYuanDenseV1Config](/docs/transformers/main/pt/model_doc/hunyuan_v1_dense#transformers.HunYuanDenseV1Config). Quando `mrope_section` está presente, ela divide metade de cada cabeçalho de atenção entre os eixos de RoPE multimodal do HunYuanVL. A ordem esperada é `(width, height, image_index)` para RoPE multimodal de 3 eixos e `(position, width, height, image_index)` para RoPE multimodal de 4 eixos. O eixo `image_index` é o ordinal da imagem/quadro na sequência de entrada; todos os tokens visuais de uma mesma imagem compartilham o mesmo valor nesse eixo. attention_bias (`bool`, *opcional*, padrão `False`) : Se deve usar um viés nas camadas de projeção de query, key, value e output durante a autoatenção. attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção. head_dim (`int`, *opcional*) : A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads sep_token_id (`int`, *opcional*, padrão 4) : ID do token usado como marcador de separador pelos tokenizers do HunYuan. Configuração do backbone de texto para a variante open-source HunYuanVL, apenas densa, de imagem e texto. Herdita os campos padrão de [HunYuanDenseV1Config](/docs/transformers/main/pt/model_doc/hunyuan_v1_dense#transformers.HunYuanDenseV1Config) e declara os nomes de campos canônicos (`pad_token_id`, `head_dim`, `vocab_size`) como os únicos atributos públicos. Os aliases legados que alguns checkpoints da Tencent persistem em disco (`pad_id`, `attention_head_dim`, `org_vocab_size`) são mapeados para esses campos canônicos por meio de `attribute_map`, de modo que o restante do modelo só precisa ler os campos canônicos. As cargas de dados legadas de RoPE persistidas como `rope_scaling` / `rope_theta` são normalizadas pela classe de configuração base em `rope_parameters`. ## HunYuanVLVisionTransformer[[transformers.HunYuanVLVisionTransformer]] #### transformers.HunYuanVLVisionTransformer[[transformers.HunYuanVLVisionTransformer]] ```python transformers.HunYuanVLVisionTransformer(config: HunYuanVLVisionConfig) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L657) Torre de visão do HunYuanVL: incorporação de patches -> blocos de transformador -> mesclador de patches por imagem. As entradas são tensores de pixels planos por patch, além de um tensor `image_grid_thw` que descreve o layout espacial de cada imagem no lote. A saída é a concatenação dos embeddings de imagem mesclados, prontos para serem distribuídos no fluxo de embeddings do modelo de linguagem. #### forward[[transformers.HunYuanVLVisionTransformer.forward]] ```python forward(pixel_values: Tensor, grid_thw: LongTensor, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L683) **Parâmetros:** pixel_values (`torch.Tensor` de forma `(num_patches, num_channels * patch_size * patch_size)`) : Características de pixels aplanadas por patch produzidas pelo processador de imagem. grid_thw (`torch.LongTensor` de forma `(num_images, 3)`) : As dimensões temporal, de altura e de largura para cada imagem. Cada linha contém as contagens de patches `[t, h, w]`. **Retorna:** [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)` Um [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. O método forward do [HunYuanVLVisionTransformer](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLVisionTransformer) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo. - **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. ## HunYuanVLTextModel[[transformers.HunYuanVLTextModel]] #### transformers.HunYuanVLTextModel[[transformers.HunYuanVLTextModel]] ```python transformers.HunYuanVLTextModel(config: HunYuanVLTextConfig) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L726) **Parâmetros:** config ([HunYuanVLTextConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLTextConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. O modelo de texto Hunyuan Vl básico, que gera estados ocultos brutos sem nenhum cabeçalho específico no topo. Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### forward[[transformers.HunYuanVLTextModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L748) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`. [O que são IDs de posição?](../glossary#position-ids) past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). **Retorna:** [BaseModelOutputWithPast](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) ou `tuple(torch.Tensor)` Um [BaseModelOutputWithPast](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. O método forward do [HunYuanVLTextModel](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLTextModel) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo. Se `past_key_values` for usado, apenas o último hidden-state das sequências, com forma `(batch_size, 1, hidden_size)`, é retornado. - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e, opcionalmente, se `config.is_encoder_decoder=True`, nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. ## HunYuanVLModel[[transformers.HunYuanVLModel]] #### transformers.HunYuanVLModel[[transformers.HunYuanVLModel]] ```python transformers.HunYuanVLModel(config: HunYuanVLConfig) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L827) **Parâmetros:** config ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. O modelo HunYuanVL, que consiste em um backbone de visão e um modelo de linguagem, sem uma cabeça de modelagem de linguagem. Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### forward[[transformers.HunYuanVLModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, mm_token_type_ids: typing.Optional[torch.IntTensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L1039) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`. [O que são IDs de posição?](../glossary#position-ids) past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor). Veja [HunYuanVLImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([HunYuanVLProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLProcessor) usa [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor) para processar imagens). image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM. mm_token_type_ids (`torch.IntTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada correspondentes a cada modalidade. Por exemplo, texto (0), imagem (1), vídeo (2). Os ids de tipo de token multimodal podem ser obtidos usando [AutoProcessor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoProcessor). Veja [ProcessorMixin.__call__()](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessorMixin.__call__) para detalhes. mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *opcional*) : Dicionário em que as chaves são as modalidades suportadas e os valores são as saídas codificadas para essa modalidade. Cada saída codificada é uma tupla que consiste em (`pooler_output`, *opcional*: `last_hidden_states`, *opcional*: `hidden_states`, *opcional*: `attentions`) `pooler_output` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de recursos multimodais do codificador mesclados em incorporações de texto. **Retorna:** `HunYuanVLModelOutputWithPast` ou `tuple(torch.Tensor)` Um `HunYuanVLModelOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. O método forward do [HunYuanVLModel](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLModel) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo. Se `past_key_values` for usado, apenas o último hidden-state das sequências, com forma `(batch_size, 1, hidden_size)`, é retornado. - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e, opcionalmente, se `config.is_encoder_decoder=True`, nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **image_hidden_states** (`torch.Tensor`, *opcional*) -- Últimas características de imagem produzidas pela torre de visão e espalhadas no fluxo de tokens do modelo de linguagem. #### get_image_features[[transformers.HunYuanVLModel.get_image_features]] ```python get_image_features(pixel_values: Tensor, image_grid_thw: typing.Optional[torch.LongTensor] = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L968) **Parâmetros:** pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor). Veja [HunYuanVLImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([HunYuanVLProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLProcessor) usa [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor) para processar imagens). image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM. **Retorna:** [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)` Um [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. - **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo. - **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. ## HunYuanVLForConditionalGeneration[[transformers.HunYuanVLForConditionalGeneration]] #### transformers.HunYuanVLForConditionalGeneration[[transformers.HunYuanVLForConditionalGeneration]] ```python transformers.HunYuanVLForConditionalGeneration(config: HunYuanVLConfig) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L1108) **Parâmetros:** config ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. O Modelo Hunyuan Vl para geração de tokens condicionado a outras modalidades (por exemplo, geração de texto a partir de imagem e texto). Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### forward[[transformers.HunYuanVLForConditionalGeneration.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, mm_token_type_ids: typing.Optional[torch.IntTensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L1134) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`. [O que são IDs de posição?](../glossary#position-ids) past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo. labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência). pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor). Veja [HunYuanVLImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([HunYuanVLProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLProcessor) usa [HunYuanVLImageProcessor](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLImageProcessor) para processar imagens). image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM. mm_token_type_ids (`torch.IntTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada correspondentes a cada modalidade. Por exemplo, texto (0), imagem (1), vídeo (2). Os ids de tipo de token multimodal podem ser obtidos usando [AutoProcessor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoProcessor). Veja [ProcessorMixin.__call__()](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessorMixin.__call__) para detalhes. mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *opcional*) : Dicionário em que as chaves são as modalidades suportadas e os valores são as saídas codificadas para essa modalidade. Cada saída codificada é uma tupla que consiste em (`pooler_output`, *opcional*: `last_hidden_states`, *opcional*: `hidden_states`, *opcional*: `attentions`) `pooler_output` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de recursos multimodais do codificador mesclados em incorporações de texto. **Retorna:** [CausalLMOutputWithPast](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) ou `tuple(torch.Tensor)` Um [CausalLMOutputWithPast](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. O método forward de [HunYuanVLForConditionalGeneration](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLForConditionalGeneration) sobrescreve o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token). - **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax). - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. Exemplo: ```python >>> from transformers import AutoProcessor, HunYuanVLForConditionalGeneration >>> import torch >>> model_id = "tencent/HunyuanOCR" >>> processor = AutoProcessor.from_pretrained(model_id, backend="pil") >>> model = HunYuanVLForConditionalGeneration.from_pretrained( ... model_id, attn_implementation="eager", torch_dtype=torch.bfloat16, device_map="auto" ... ) >>> messages = [ ... { ... "role": "user", ... "content": [ ... {"type": "image", "image": "path/to/your/image.jpg"}, ... {"type": "text", "text": "Extract the text from the image."}, ... ], ... } ... ] >>> inputs = processor.apply_chat_template( ... messages, ... tokenize=True, ... add_generation_prompt=True, ... return_tensors="pt", ... return_dict=True, ... processor_kwargs={"padding": True}, ... ) >>> with torch.no_grad(): ... generated_ids = model.generate(**inputs, max_new_tokens=128) >>> generated_trimmed = generated_ids[0][inputs["input_ids"].shape[-1]:] >>> print(processor.decode(generated_trimmed, skip_special_tokens=True)) ``` #### get_image_features[[transformers.HunYuanVLForConditionalGeneration.get_image_features]] ```python get_image_features(pixel_values: Tensor, image_grid_thw: typing.Optional[torch.LongTensor] = None, **kwargs: *) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hunyuan_vl/modeling_hunyuan_vl.py#L1121) **Parâmetros:** pixel_values (`torch.Tensor`) : Características de pixels planas por patch produzidas pelo processador de imagem. image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM. **Retorna:** [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)` Um [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([HunYuanVLConfig](/docs/transformers/main/pt/model_doc/hunyuan_vl#transformers.HunYuanVLConfig)) e das entradas. - **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo. - **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento. - **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial. - **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. Exemplo: ```python >>> from PIL import Image >>> from transformers import AutoProcessor, HunYuanVLForConditionalGeneration >>> model = HunYuanVLForConditionalGeneration.from_pretrained("None") >>> processor = AutoProcessor.from_pretrained("None") >>> messages = [ ... { ... "role": "user", "content": [ ... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"}, ... {"type": "text", "text": "Where is the cat standing?"}, ... ] ... }, ... ] >>> inputs = processor.apply_chat_template( ... messages, ... tokenize=True, ... return_dict=True, ... return_tensors="pt", ... add_generation_prompt=True ... ) >>> # Generate >>> generate_ids = model.generate(**inputs) >>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0] ```