Transformers documentation
ColModernVBert
Este modelo se publicó en HF papers el 2025-10-01 y se contribuyó a Hugging Face Transformers el 2026-02-23.
ColModernVBert
Resumen
ColModernVBert es un modelo para la recuperación eficiente de documentos visuales. Utiliza ModernVBert para construir embeddings multivector directamente a partir de imágenes de documentos, siguiendo el enfoque de ColPali.
El modelo fue introducido en ModernVBERT: Towards Smaller Visual Document Retrievers.
import torch
from huggingface_hub import hf_hub_download
from PIL import Image
from transformers import ColModernVBertForRetrieval, ColModernVBertProcessor
processor = ColModernVBertProcessor.from_pretrained("ModernVBERT/colmodernvbert-hf")
model = ColModernVBertForRetrieval.from_pretrained("ModernVBERT/colmodernvbert-hf", device_map="auto")
# Load the test dataset
queries = [
"A paint on the wall",
"ColModernVBERT matches the performance of models nearly 10x larger on visual document benchmarks."
]
images = [
Image.open(hf_hub_download("HuggingFaceTB/SmolVLM", "example_images/rococo.jpg", repo_type="space")),
Image.open(hf_hub_download("ModernVBERT/colmodernvbert", "table.png", repo_type="model"))
]
# Preprocess the examples
batch_images = processor(images=images).to(model.device)
batch_queries = processor(text=queries).to(model.device)
# Run inference
with torch.inference_mode():
image_embeddings = model(**batch_images).embeddings
query_embeddings = model(**batch_queries).embeddings
# Compute retrieval scores
scores = processor.score_retrieval(
query_embeddings=query_embeddings,
passage_embeddings=image_embeddings,
)
scores = torch.softmax(scores, dim=-1)
print(scores) # [[0.9350, 0.0650], [0.0015, 0.9985]]ColModernVBertConfig
clase transformers.ColModernVBertConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevlm_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneembedding_dim: int = 128initializer_range: float = 0.02 )
Parámetros
- vlm_config (
Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — El objeto de configuración o el diccionario del backbone de visión-lenguaje. - embedding_dim (
int, opcional, valor predeterminado128) — Dimensionalidad de los embeddings y los estados ocultos. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
Esta es la clase de configuración para almacenar la configuración de un ColmodernvbertModel. Se utiliza para instanciar un modelo Colmodernvbert según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de ModernVBERT/colmodernvbert-merged
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
ColModernVBertProcessor
clase transformers.ColModernVBertProcessor
< source >( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )
Parámetros
- image_processor (
image_processor_class) — El procesador de imágenes es una entrada obligatoria. - tokenizer (
tokenizer_class) — El tokenizador es una entrada obligatoria. - chat_template (
str) — Plantilla de Jinja para convertir listas de mensajes de un chat en una cadena tokenizable. - image_seq_len (
int, opcional, valor predeterminado 64) — La longitud de la secuencia de imagen, es decir, el número detokens por imagen en la entrada. - visual_prompt_prefix (
str, opcional) — Una cadena que se tokeniza y se antepone a los tokens de imagen. - query_prefix (
str, opcional) — Un prefijo que se usará para la consulta.
Construye un ColModernVBertProcessor que envuelve un procesador de imágenes y un tokenizador en un único procesador.
ColModernVBertProcessor ofrece todas las funcionalidades de image_processor_class y tokenizer_class. Consulte ~image_processor_class y ~tokenizer_class para obtener más información.
process_images
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature
Parámetros
- images (
PIL.Image.Image,np.ndarray,torch.Tensor,list[PIL.Image.Image],list[np.ndarray],list[torch.Tensor]) — La imagen o lote de imágenes que se va a preparar. Cada imagen puede ser una imagen PIL, un array de NumPy o un tensor de PyTorch. En el caso de un array de NumPy/tensor de PyTorch, cada imagen debe tener la forma (C, H, W), donde C es el número de canales, y H y W son la altura y el ancho de la imagen. - return_tensors (
stro TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:'pt': Devuelve objetostorch.Tensorde PyTorch.'np': Devuelve objetosnp.ndarrayde NumPy.
Devuelve
Un BatchFeature con los siguientes campos:
- input_ids — Lista de ids de tokens que se enviarán a un modelo.
- attention_mask — Lista de índices que especifica qué tokens deben ser atendidos por el modelo (cuando
return_attention_mask=Trueo si “attention_mask” está enself.model_input_namesy sitextno esNone). - pixel_values — Valores de píxeles que se enviarán a un modelo. Se devuelve cuando
imagesno esNone.
Prepara una o varias imágenes para el modelo. Maneja la validación de la entrada, la conversión a RGB y antepone visual_prompt_prefix a cada imagen. Opcionalmente, calcula las etiquetas a partir de token_type_ids cuando se proporciona un suffix en text_kwargs.
process_queries
< source >( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature
Parámetros
- text (
str,list[str],list[list[str]]) — La secuencia o lote de secuencias que se va a codificar. Cada secuencia puede ser una cadena de caracteres o una lista de cadenas de caracteres (cadenas precodificadas). Si las secuencias se proporcionan como lista de cadenas de caracteres (precodificadas), debe estableceris_split_into_words=True(para eliminar la ambigüedad con un lote de secuencias). - return_tensors (
stro TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:'pt': Devuelve objetostorch.Tensorde PyTorch.'np': Devuelve objetosnp.ndarrayde NumPy.
Devuelve
Un BatchFeature con los siguientes campos:
- input_ids — Lista de ids de tokens que se enviarán a un modelo.
- attention_mask — Lista de índices que especifica qué tokens deben ser atendidos por el modelo (cuando
return_attention_mask=Trueo si “attention_mask” está enself.model_input_namesy sitextno esNone).
Prepara una o varias consultas de texto para el modelo. Maneja la validación de la entrada, antepone el query_prefix y añade tokens de aumento de consulta (utilizados para rellenar los embeddings de consulta para un mejor rendimiento de recuperación de interacción tardía).
score_retrieval
< source >( query_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']]passage_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']]batch_size: int = 128output_dtype: typing.Optional[ForwardRef('torch.dtype')] = Noneoutput_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu' ) → torch.Tensor
Parámetros
- query_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — Embeddings de consulta. - passage_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — Embeddings de pasajes. - batch_size (
int, opcional, valor predeterminado 128) — Tamaño del lote para el cálculo de las puntuaciones. - output_dtype (
torch.dtype, opcional, por defectotorch.float32) — El dtype del tensor de salida. Si esNone, se utiliza el dtype de las embeddings de entrada. - output_device (
torch.deviceostr, opcional, valor predeterminado “cpu”) — El dispositivo del tensor de salida.
Devuelve
torch.Tensor
Un tensor de forma (n_queries, n_passages) que contiene las puntuaciones. El tensor de puntuaciones se guarda en el dispositivo “cpu”.
Calcule la puntuación de interacción tardía/MaxSim (similar a ColBERT) para los embeddings de consulta multivector (qs) y los embeddings de pasaje (ps) dados. Para ColQwen2, un pasaje es la imagen de una página de un documento.
Dado que los tensores de incrustación son de múltiples vectores y, por lo tanto, pueden tener formas diferentes, deben proporcionarse como: (1) una lista de tensores, donde el tensor i-ésimo tiene la forma (sequence_length_i, embedding_dim) (2) un único tensor de forma (n_passages, max_sequence_length, embedding_dim) -> generalmente obtenido mediante el relleno (padding) de la lista de tensores.
ColModernVBertForRetrieval
clase transformers.ColModernVBertForRetrieval
< source >( config: ColModernVBertConfig )
Parámetros
- config (ColModernVBertConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Siguiendo el enfoque de ColPali, ColModernVBert aprovecha los VLM para construir embeddings multivectoriales eficientes directamente a partir de imágenes de documentos («capturas de pantalla») para la recuperación de documentos. El modelo se entrena para maximizar la similitud entre estos embeddings de documentos y los embeddings de consulta correspondientes, utilizando el método de interacción tardía introducido en ColBERT.
El uso de ColModernVBert elimina la necesidad de pipelines de reconocimiento de diseño y OCR que pueden ser complejos y frágiles, mediante un único modelo que puede tener en cuenta tanto el contenido textual como el visual (diseño, gráficos, …) de un documento.
ColModernVBert se entrena sobre ModernVBert y fue introducido en el siguiente artículo: ModernVBERT: Towards Smaller Visual Document Retrievers.
ColModernVBert forma parte de la familia de modelos ColVision, que se presentó con ColPali en el siguiente artículo: ColPali: Efficient Document Retrieval with Vision Language Models.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ColModernVBertForRetrievalOutput or tuple(torch.Tensor)
Parámetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizandoimage_processor_class. Consulteimage_processor_class.__call__para más detalles (ColModernVBertProcessor utilizaimage_processor_classpara procesar las imágenes). - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
Devuelve
ColModernVBertForRetrievalOutput o tuple(torch.Tensor)
Un ColModernVBertForRetrievalOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (ColModernVBertConfig) y las entradas.
El método forward de ColModernVBertForRetrieval sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
loss (
torch.Tensorde forma(1,), opcional, se devuelve cuando se proporcionalabels) — Pérdida de modelado de lenguaje (para la predicción del siguiente token).embeddings (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Los embeddings del modelo.hidden_states (
tuple[torch.Tensor], opcional, se devuelve cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
image_hidden_states (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=Truey se proporcionanpixel_values) — Tupla detorch.Tensor(una para la salida de la proyección de la modalidad de imagen + una para la salida de cada capa) de forma(batch_size, num_channels, image_size, image_size). Estados ocultos del codificador de imagen en la salida de cada capa, más las salidas iniciales de la proyección de modalidad.attentions (
tuple[torch.Tensor], opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.