Transformers documentation
ColModernVBert
Ce modèle a été publié dans HF papers le 2025-10-01 et contribué à Hugging Face Transformers le 2026-02-23.
ColModernVBert
Aperçu
ColModernVBert est un modèle pour la récupération efficace de documents visuels. Il exploite ModernVBert pour construire des embeddings multi-vecteurs directement à partir d'images de documents, en suivant l'approche ColPali.
Le modèle a été introduit dans 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
classe 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 )
Paramètres
- vlm_config (
Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L’objet de configuration ou le dictionnaire du backbone vision-langage. - embedding_dim (
int, facultatif, par défaut128) — Dimension des embeddings et des états cachés. - initializer_range (
float, facultatif, par défaut0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
Ceci est la classe de configuration destinée à stocker la configuration d'un ColmodernvbertModel. Elle est utilisée pour instancier un modèle Colmodernvbert en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de ModernVBERT/colmodernvbert-merged
Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.
ColModernVBertProcessor
classe transformers.ColModernVBertProcessor
< source >( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )
Paramètres
- image_processor (
image_processor_class) — Le processeur d’images est une entrée obligatoire. - tokenizer (
tokenizer_class) — Le tokenizer est une entrée obligatoire. - chat_template (
str) — Un modèle Jinja pour convertir des listes de messages d'une conversation en une chaîne tokenisable. - image_seq_len (
int, facultatif, par défaut 64) — La longueur de la séquence d'image, c'est-à-dire le nombre dejetons par image dans l'entrée. - visual_prompt_prefix (
str, facultatif) — Une chaîne de caractères qui est tokenisée et ajoutée avant les jetons d’image. - query_prefix (
str, facultatif) — Un préfixe à utiliser pour la requête.
Construit un ColModernVBertProcessor qui encapsule un processeur d’images et un tokenizer en un seul processeur.
ColModernVBertProcessor offre toutes les fonctionnalités de image_processor_class et de tokenizer_class. Consultez ~image_processor_class et ~tokenizer_class pour plus d’informations.
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
Paramètres
- images (
PIL.Image.Image,np.ndarray,torch.Tensor,list[PIL.Image.Image],list[np.ndarray],list[torch.Tensor]) — L’image ou le lot d’images à préparer. Chaque image peut être une image PIL, un tableau NumPy ou un tenseur PyTorch. Dans le cas d’un tableau NumPy ou d’un tenseur PyTorch, chaque image doit avoir la forme (C, H, W), où C est le nombre de canaux, et H et W sont la hauteur et la largeur de l’image. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
Retourne
Un BatchFeature avec les champs suivants :
- input_ids — Liste des identifiants de jetons à fournir à un modèle.
- attention_mask — Liste d’indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque
return_attention_mask=Trueou si “attention_mask” est présent dansself.model_input_nameset sitextn’est pasNone). - pixel_values — Valeurs des pixels à fournir à un modèle. Renvoyé lorsque
imagesn'est pasNone.
Prépare une ou plusieurs images pour le modèle. Gère la validation des entrées, la conversion en RGB et ajoute le visual_prompt_prefix à chaque image. Calcule éventuellement les étiquettes à partir de token_type_ids lorsqu'un suffix est fourni dans text_kwargs.
process_queries
< source >( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature
Paramètres
- text (
str,list[str],list[list[str]]) — La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaînes pré-tokenisées). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définiris_split_into_words=True(pour lever l’ambiguïté avec un lot de séquences). - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
Retourne
Un BatchFeature avec les champs suivants :
- input_ids — Liste des identifiants de jetons à fournir à un modèle.
- attention_mask — Liste d’indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque
return_attention_mask=Trueou si “attention_mask” est présent dansself.model_input_nameset sitextn’est pasNone).
Prépare une ou plusieurs requêtes textuelles pour le modèle. Gère la validation des entrées, préfixe le query_prefix et ajoute des jetons d’augmentation de requête (utilisés pour rembourrer les embeddings de requête afin d’améliorer les performances de récupération par interaction tardive).
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
Paramètres
- query_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — Embeddings de requête. - passage_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — Embeddings des passages. - batch_size (
int, facultatif, valeur par défaut 128) — Taille du lot pour le calcul des scores. - output_dtype (
torch.dtype, facultatif, par défauttorch.float32) — Le dtype du tenseur de sortie. SiNone, le dtype des embeddings d’entrée est utilisé. - output_device (
torch.deviceoustr, facultatif, par défaut “cpu”) — L’appareil du tenseur de sortie.
Retourne
torch.Tensor
Un tenseur de forme (n_queries, n_passages) contenant les scores. Le tenseur de scores est enregistré sur l’appareil « cpu ».
Calculez le score late-interaction/MaxSim (type ColBERT) pour les embeddings de requête multi-vecteurs (qs) et les embeddings de passage (ps) donnés. Pour ColQwen2, un passage est l’image d’une page de document.
Les tenseurs d'incorporation étant multi-vecteurs et pouvant donc avoir des formes différentes, ils doivent être fournis sous la forme : (1) une liste de tenseurs, où le i-ème tenseur a la forme (sequence_length_i, embedding_dim) (2) un tenseur unique de forme (n_passages, max_sequence_length, embedding_dim) -> obtenu généralement en appliquant un bourrage (padding) à la liste de tenseurs.
ColModernVBertForRetrieval
classe transformers.ColModernVBertForRetrieval
< source >( config: ColModernVBertConfig )
Paramètres
- config (ColModernVBertConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.
Dans la lignée de l’approche ColPali, ColModernVBert exploite les VLM pour construire des embeddings multi-vecteurs efficaces directement à partir d’images de documents (« captures d’écran ») pour la récupération de documents. Le modèle est entraîné pour maximiser la similarité entre ces embeddings de documents et les embeddings de requêtes correspondants, en utilisant la méthode d’interaction tardive introduite dans ColBERT.
L’utilisation de ColModernVBert supprime le besoin de pipelines de reconnaissance de mise en page et d’OCR potentiellement complexes et fragiles, grâce à un modèle unique capable de prendre en compte à la fois le contenu textuel et visuel (mise en page, graphiques, …) d’un document.
ColModernVBert est entraîné à partir de ModernVBert et a été introduit dans l'article suivant : ModernVBERT: Towards Smaller Visual Document Retrievers.
ColModernVBert fait partie de la famille de modèles ColVision, qui a été introduite avec ColPali dans l'article suivant : ColPali: Efficient Document Retrieval with Vision Language Models.
Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)
Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.
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)
Paramètres
- input_ids (
torch.LongTensorde forme(batch_size, sequence_length), facultatif) — Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut.Les indices peuvent être obtenus à l'aide de AutoTokenizer. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.
- pixel_values (
torch.Tensorde forme(batch_size, num_channels, image_size, image_size), facultatif) — Les tenseurs correspondant aux images d'entrée. Les valeurs de pixels peuvent être obtenues à l'aide deimage_processor_class. Consultezimage_processor_class.__call__pour plus de détails (ColModernVBertProcessor utiliseimage_processor_classpour le traitement des images). - attention_mask (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les jetons qui ne sont pas masqués,
- 0 pour les jetons masqués.
Retourne
ColModernVBertForRetrievalOutput ou tuple(torch.Tensor)
Un ColModernVBertForRetrievalOutput ou un tuple de
torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers
éléments en fonction de la configuration (ColModernVBertConfig) et des entrées.
La méthode forward de ColModernVBertForRetrieval redéfinit la méthode spéciale __call__.
Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance
Moduleplutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.
loss (
torch.Tensorde forme(1,), facultatif, renvoyé lorsquelabelsest fourni) — Perte de modélisation du langage (pour la prédiction du jeton suivant).embeddings (
torch.Tensorde forme(batch_size, sequence_length, hidden_size)) — Les embeddings du modèle.hidden_states (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.Tensor(un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme(batch_size, sequence_length, hidden_size).États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
image_hidden_states (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=Trueet quepixel_valuessont fournis) — Tuple detorch.Tensor(un pour la sortie de la projection de la modalité image + un pour la sortie de chaque couche) de forme(batch_size, num_channels, image_size, image_size). États cachés de l’encodeur d’images à la sortie de chaque couche, ainsi que les sorties initiales de la projection de la modalité.attentions (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.Tensor(un par couche) de forme(batch_size, num_heads, sequence_length, sequence_length).Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.