Transformers documentation

Imagen-texto-a-texto

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Imagen-texto-a-texto

Los modelos de imagen y texto a texto, también conocidos como modelos de lenguaje visual (VLM), son modelos de lenguaje que reciben una imagen como entrada. Estos modelos pueden abordar diversas tareas, desde la respuesta a preguntas visuales hasta la segmentación de imágenes. Esta tarea presenta muchas similitudes con la de imagen a texto, aunque comparte algunos casos de uso, como la generación de descripciones de imágenes. Los modelos de imagen a texto solo aceptan entradas de imagen y suelen realizar una tarea específica, mientras que los VLM aceptan entradas de texto y de imagen abiertas y son modelos más generalistas.

En esta guía, ofrecemos una breve descripción general de los VLM y mostramos cómo usarlos con Transformers para inferencia.

Para empezar, existen varios tipos de VLM:

  • modelos base utilizados para el ajuste fino
  • modelos de chat afinados para conversación
  • modelos ajustados con instrucciones

Esta guía se centra en la inferencia con un modelo ajustado con instrucciones.

Comencemos instalando las dependencias.

pip install -q transformers accelerate 
pip install flash-attn --no-build-isolation

Iniciemos el modelo y el procesador.

from transformers import AutoProcessor, AutoModelForImageTextToText
from accelerate import Accelerator
import torch

device = Accelerator().device
model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen3-VL-4B-Instruct",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
).to(device)

Los modelos de resolución dinámica como Qwen3-VL y Qwen3.5 usan por defecto un longest_edge de ~16MP, lo que puede generar más de 10.000 tokens visuales por imagen y provocar que la inferencia se detenga o que se agote la memoria (OOM) en GPUs de consumo. Establece min_pixels y max_pixels al cargar el procesador para limitar esto.

processor = AutoProcessor.from_pretrained(
    "Qwen/Qwen3-VL-4B-Instruct",
    min_pixels=224 * 224,
    max_pixels=1024 * 1024,
)

Este modelo tiene una plantilla de chat que ayuda al usuario a analizar las salidas del chat. Además, el modelo también puede aceptar múltiples imágenes como entrada en una sola conversación o mensaje. Ahora prepararemos las entradas.

Las entradas de imagen tienen el siguiente aspecto.

Two cats sitting on a net
A bee on a pink flower

Estructure su conversación como se muestra a continuación para un único prompt con entradas de imagen y texto.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cats.png"},
            {"type": "text", "text": "What do we see in this image?"},
        ]
    }
]

Alterne entre el rol user y el rol assistant para proporcionar al modelo el contexto previo necesario y generar mejores respuestas.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cats.png"},
            {"type": "text", "text": "What do we see in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "In this image we can see two cats on the nets."},
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"},
            {"type": "text", "text": "And how about this image?"},
        ]
    },
]

Ahora llamaremos al método apply_chat_template() de los procesadores para preprocesar su salida junto con las entradas de imagen.

inputs = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(device)

Ahora podemos pasar las entradas preprocesadas al modelo.

input_len = len(inputs.input_ids[0])

with torch.no_grad():
    generated_ids = model.generate(**inputs, max_new_tokens=200)
generated_texts = processor.batch_decode(generated_ids[:, input_len:], skip_special_tokens=True)

print(generated_texts)
## ['In this image we can see flowers, plants and insect.']

Pipeline

La forma más rápida de empezar es utilizar la API Pipeline. Especifique la tarea "image-text-to-text" y el modelo que desea utilizar.

from transformers import pipeline
pipe = pipeline("image-text-to-text", model="llava-hf/llava-interleave-qwen-0.5b-hf")

El siguiente ejemplo utiliza plantillas de chat para formatear las entradas de texto.

messages = [
     {
         "role": "user",
         "content": [
             {
                 "type": "image",
                 "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg",
             },
             {"type": "text", "text": "Describe this image."},
         ],
     },
     {
         "role": "assistant",
         "content": [
             {"type": "text", "text": "There's a pink flower"},
         ],
     },
 ]

Pasa el texto y la imagen con el formato de plantilla de chat a Pipeline y establece return_full_text=False para eliminar la entrada de la salida generada.

outputs = pipe(text=messages, max_new_tokens=20, return_full_text=False)
outputs[0]["generated_text"]
#  with a yellow center in the foreground. The flower is surrounded by red and white flowers with green stems

Si lo prefiere, también puede cargar las imágenes por separado y pasarlas a la pipeline de la siguiente manera:

import requests
from PIL import Image
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="HuggingFaceTB/SmolVLM-256M-Instruct")

img_urls = [
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cats.png",
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg",
]
images = [
    Image.open(requests.get(img_urls[0], stream=True).raw),
    Image.open(requests.get(img_urls[1], stream=True).raw),
]

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "image"},
            {"type": "text", "text": "What do you see in these images?"},
        ],
    }
]
outputs = pipe(text=messages, images=images, max_new_tokens=50, return_full_text=False)
outputs[0]["generated_text"]
" In the first image, there are two cats sitting on a plant. In the second image, there are flowers with a pinkish hue."

Las imágenes seguirán incluidas en el campo "input_text" de la salida:

outputs[0]['input_text']
"""
[{'role': 'user',
  'content': [{'type': 'image',
    'image': <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=622x412>},
   {'type': 'image',
    'image': <PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=5184x3456>},
   {'type': 'text', 'text': 'What do you see in these images?'}]}]
"""

Streaming

Podemos usar text streaming para mejorar la experiencia de generación. Transformers admite streaming con las clases TextStreamer o TextIteratorStreamer. Utilizaremos TextIteratorStreamer con IDEFICS-8B.

Supongamos que tenemos una aplicación que conserva el historial de chat y recibe la nueva entrada del usuario. Preprocesaremos las entradas de la forma habitual e inicializaremos TextIteratorStreamer para gestionar la generación en un hilo separado. Esto permite transmitir los tokens de texto generados en tiempo real. Se pueden pasar cualquier argumento de generación a TextIteratorStreamer.

import time
from transformers import TextIteratorStreamer
from threading import Thread

def model_inference(
    user_prompt,
    chat_history,
    max_new_tokens,
    images
):
    user_prompt = {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": user_prompt},
        ]
    }
    chat_history.append(user_prompt)
    streamer = TextIteratorStreamer(
        processor.tokenizer,
        skip_prompt=True,
        timeout=5.0,
    )

    generation_args = {
        "max_new_tokens": max_new_tokens,
        "streamer": streamer,
        "do_sample": False
    }

    # add_generation_prompt=True makes model generate bot response
    prompt = processor.apply_chat_template(chat_history, add_generation_prompt=True)
    inputs = processor(
        text=prompt,
        images=images,
        return_tensors="pt",
    ).to(device)
    generation_args.update(inputs)

    thread = Thread(
        target=model.generate,
        kwargs=generation_args,
    )
    thread.start()

    acc_text = ""
    for text_token in streamer:
        time.sleep(0.04)
        acc_text += text_token
        if acc_text.endswith("<end_of_utterance>"):
            acc_text = acc_text[:-18]
        yield acc_text

    thread.join()

Ahora llamemos a la función model_inference que creamos y transmitamos los valores.

generator = model_inference(
    user_prompt="And what is in this image?",
    chat_history=messages[:2],
    max_new_tokens=100,
    images=images
)

for value in generator:
  print(value)

# In
# In this
# In this image ...

Ajustar modelos en hardware más pequeño

Los VLM suelen ser grandes y necesitan optimizarse para adaptarse a hardware más pequeño. Transformers admite muchas bibliotecas de cuantización de modelos, y aquí solo mostraremos la cuantización int8 con Quanto. La cuantización int8 ofrece mejoras de memoria de hasta el 75 por ciento (si se cuantizan todos los pesos). Sin embargo, no es gratis, ya que 8 bits no es una precisión nativa de CUDA, por lo que los pesos se cuantizan y descuantizan sobre la marcha, lo que aumenta la latencia.

Primero, instala las dependencias.

pip install -U optimum-quanto bitsandbytes

Para cuantizar un modelo durante su carga, primero debemos crear QuantoConfig. Luego, cargamos el modelo como de costumbre, pero pasamos quantization_config durante la inicialización del modelo.

from transformers import AutoModelForImageTextToText, QuantoConfig

model_id = "Qwen/Qwen3-VL-4B-Instruct"
quantization_config = QuantoConfig(weights="int8")
quantized_model = AutoModelForImageTextToText.from_pretrained(
    model_id, device_map="auto", quantization_config=quantization_config
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cats.png"},
            {"type": "text", "text": "What do we see in this image?"},
        ]
    },
]
inputs = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(quantized_model.device)
input_len = len(inputs.input_ids[0])

with torch.no_grad():
    generated_ids = quantized_model.generate(**inputs, cache_implementation="static", max_new_tokens=100)
generated_texts = processor.batch_decode(generated_ids[:, input_len:], skip_special_tokens=True)

print(generated_texts[0])
## ['In this image, we see two tabby cats resting on a large, tangled pile of fishing nets. The nets are a mix of brown, orange, and red colors, with some blue and green ropes visible in the background. The cats appear relaxed and comfortable, nestled into the fibers of the nets. One cat is in the foreground, looking slightly to the side, while the other is positioned further back, looking directly at the camera. The scene suggests a coastal or fishing-related setting, possibly near']

Y eso es todo, podemos usar el modelo de la misma manera, sin cambios.

Chat iterativo con caché

Si estás construyendo agentes de chat multimodales, es probable que estés pasando las mismas imágenes o audio entre turnos. El caché te permite reutilizar sus representaciones codificadas en lugar de reprocesarlos cada vez, reduciendo el cálculo redundante.

Al igual que los modelos solo de texto, los modelos multimodales rastrean el historial de la conversación mediante una plantilla de chat. La diferencia clave es que aplica la plantilla de chat únicamente en formato "text" y procesa el nuevo contenido multimodal por separado. Si aplicas la plantilla con procesamiento, toda la conversación se vuelve a procesar en cada turno, ya que Jinja no puede distinguir entre las entradas codificadas previamente y las nuevas.

El siguiente ejemplo demuestra este patrón. Para modelos solo de texto, consulte la guía de generación iterativa.

Aquí hay un ejemplo simple en Python que demuestra este patrón. Para un ejemplo con modelos solo de texto, consulte esta guía.

import torch
from transformers import AutoProcessor, Gemma4ForConditionalGeneration, TextStreamer
from transformers.cache_utils import DynamicCache
from transformers.image_utils import load_image
from transformers.audio_utils import load_audio

model_id = 'google/gemma-4-E2B-it'
processor = AutoProcessor.from_pretrained(model_id)
model = Gemma4ForConditionalGeneration.from_pretrained(model_id, dtype=torch.float32, device_map='cpu')

past_key_values = DynamicCache()
streamer = TextStreamer(processor.tokenizer, skip_prompt=True, skip_special_tokens=True)

## Turn 1: multimodal input (text + image + audio)
audio = load_audio("https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/jfk.wav")
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "In detail, describe the following audio and image."},
            {"type": "audio"},
            {"type": "image"},
        ],
    },
]
input_string = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(text=input_string, images=[image], audio=[audio], return_tensors='pt')
output = model.generate(**inputs, past_key_values=past_key_values, max_new_tokens=1024, do_sample=False, streamer=streamer)
first_response = processor.decode(output[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)

## Turn 2: text-only follow-up (reuses KV cache, no new media)
messages.append({"role": "assistant", "content": [{"type": "text", "text": first_response}]})
cached_string = processor.apply_chat_template(messages, tokenize=False)
messages.append({"role": "user", "content": [{"type": "text", "text": "Summarize the previous descriptions in one sentence."}]})
full_string = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
new_string = full_string[len(cached_string):]

new_input_ids = processor.tokenizer(new_string, add_special_tokens=False, return_tensors='pt')['input_ids']
# Build and pass an attention mask only if batched input or there is padding
# attention_mask = torch.ones(1, past_key_values.get_seq_length() + new_input_ids.shape[1], dtype=torch.long)

output2 = model.generate(input_ids=new_input_ids, past_key_values=past_key_values, max_new_tokens=1024, do_sample=False, streamer=streamer)
second_response = processor.decode(output2[0][new_input_ids.shape[1]:], skip_special_tokens=True)

## Turn 3: new image (must go through processor for image token expansion + encoding)
image2 = load_image("https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/artemis.jpeg")
messages.append({"role": "assistant", "content": [{"type": "text", "text": second_response}]})
cached_string2 = processor.apply_chat_template(messages, tokenize=False)
messages.append({"role": "user", "content": [{"type": "text", "text": "Describe this image."}, {"type": "image"}]})
full_string2 = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
new_string2 = full_string2[len(cached_string2):]

new_inputs2 = processor(text=new_string2, images=[image2], add_special_tokens=False, return_tensors='pt')
# new_inputs2['attention_mask'] = torch.ones(1, past_key_values.get_seq_length() + new_inputs2['input_ids'].shape[1], dtype=torch.long)
new_inputs2['past_key_values'] = past_key_values

output3 = model.generate(**new_inputs2, max_new_tokens=1024, do_sample=False, streamer=streamer)

Lecturas adicionales

Aquí tienes más recursos para la tarea de imagen y texto a texto.

Update on GitHub