Transformers documentation
ColModernVBert
이 모델은 2025-10-01에 HF papers에 게시되었으며, 2026-02-23에 Hugging Face Transformers에 기여되었습니다.
ColModernVBert
개요
ColModernVBert은 효율적인 시각 문서 검색을 위한 모델입니다. ModernVBert를 활용하여 ColPali 접근 방식을 따르며 문서 이미지에서 직접 멀티 벡터 임베딩을 구성합니다.
해당 모델은 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
클래스 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 )
이것은 ColmodernvbertModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Colmodernvbert 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 ModernVBERT/colmodernvbert-merged와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
ColModernVBertProcessor
class transformers.ColModernVBertProcessor
< source >( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )
매개변수
- image_processor (
image_processor_class) — 이미지 프로세서가 필수 입력값입니다. - tokenizer (
tokenizer_class) — 토크나이저는 필수 입력값입니다. - chat_template (
str) — 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다. - image_seq_len (
int, 선택 사항, 기본값 64) — 이미지 시퀀스의 길이, 즉 입력에서 이미지당토큰 수 입니다. - visual_prompt_prefix (
str, 선택 사항) — 이미지 토큰 앞에 추가되는 문자열로, 토큰화됩니다. - query_prefix (
str, 선택 사항) — 쿼리에 사용할 접두사입니다.
이미지 프로세서와 토크나이저를 단일 프로세서로 감싸는 ColModernVBertProcessor를 생성합니다.
ColModernVBertProcessor는 image_processor_class과 tokenizer_class의 모든 기능을 제공합니다. 자세한 내용은 ~image_processor_class와 ~tokenizer_class를 참고하세요.
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
매개변수
- images (
PIL.Image.Image,np.ndarray,torch.Tensor,list[PIL.Image.Image],list[np.ndarray],list[torch.Tensor]) — 준비할 이미지 또는 이미지 배치입니다. 각 이미지는 PIL 이미지, NumPy 배열 또는 PyTorch 텐서일 수 있습니다. NumPy 배열/PyTorch 텐서의 경우, 각 이미지의 shape은 (C, H, W)여야 하며, 여기서 C는 채널 수, H와 W는 이미지의 높이와 너비입니다. - return_tensors (
str또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': NumPynp.ndarray객체를 반환합니다.
반환값
다음 필드를 가진 BatchFeature:
- input_ids — 모델에 입력할 토큰 ID 목록.
- attention_mask — 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록 (
return_attention_mask=True인 경우 또는self.model_input_names에 “attention_mask”가 포함되어 있고text가None이 아닌 경우). - pixel_values — 모델에 입력할 픽셀 값.
images가None이 아닌 경우 반환됩니다.
모델에 하나 이상의 이미지를 준비합니다. 입력 검증, RGB 변환을 처리하고 각 이미지에 visual_prompt_prefix를 앞에 붙입니다. text_kwargs에 suffix가 제공된 경우, token_type_ids에서 라벨을 계산합니다.
process_queries
< source >( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature
매개변수
- text (
str,list[str],list[list[str]]) — 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 시퀀스가 문자열 목록(사전 토큰화)로 제공되는 경우,is_split_into_words=True를 설정해야 합니다(시퀀스 배치와의 모호성을 제거하기 위함). - return_tensors (
str또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': NumPynp.ndarray객체를 반환합니다.
반환값
다음 필드를 가진 BatchFeature:
- input_ids — 모델에 입력할 토큰 ID 목록.
- attention_mask — 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록 (
return_attention_mask=True인 경우 또는self.model_input_names에 “attention_mask”가 포함되어 있고text가None이 아닌 경우).
query_prefix를 앞에 붙이고, 쿼리 증강 토큰을 뒤에 추가하여(레이트 인터랙션 검색 성능을 높이기 위해 쿼리 임베딩을 패딩하는 데 사용) 입력을 검증하고, 모델에 하나 이상의 텍스트 쿼리를 준비합니다.
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
매개변수
- query_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — Query 임베딩. - passage_embeddings (
Union[torch.Tensor, list[torch.Tensor]) — 패사지 임베딩. - batch_size (
int, 선택 사항, 기본값 128) — 점수를 계산할 때 사용할 배치 크기입니다. - output_dtype (
torch.dtype, 선택 사항, 기본값torch.float32) — 출력 텐서의 dtype입니다.None인 경우 입력 임베딩의 dtype이 사용됩니다. - output_device (
torch.device또는str, 선택 사항, 기본값은 “cpu”) — 출력 텐서의 장치입니다.
반환값
torch.Tensor
(n_queries, n_passages) 모양의 텐서로, 점수를 포함합니다. 점수 텐서는 “cpu” 디바이스에 저장됩니다.
주어진 멀티 벡터 쿼리 임베딩(qs)과 패스지 임베딩(ps)에 대해 레이트 인터랙션/MaxSim 점수(ColBERT 방식)를 계산합니다. ColQwen2의 경우 패스지는 문서 페이지의 이미지입니다.
임베딩 텐서가 멀티벡터이므로 서로 다른 형태를 가질 수 있습니다. 따라서 다음과 같이 전달해야 합니다: (1) i번째 텐서가 (sequence_length_i, embedding_dim) 형태인 텐서 목록 (2) 패딩을 통해 텐서 목록에서 일반적으로 얻어지는 (n_passages, max_sequence_length, embedding_dim) 형태의 단일 텐서
ColModernVBertForRetrieval
class transformers.ColModernVBertForRetrieval
< source >( config: ColModernVBertConfig )
매개변수
- config (ColModernVBertConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
ColPali 접근 방식을 따르는 ColModernVBert는 VLM을 활용하여 문서 이미지(“스크린샷”)에서 직접 효율적인 멀티 벡터 임베딩을 생성하여 문서 검색을 수행합니다. 이 모델은 ColBERT에서 도입된 late interaction 방법을 사용하여 문서 임베딩과 해당 쿼리 임베딩 간의 유사도를 최대화하도록 학습됩니다.
ColModernVBert를 사용하면 문서의 텍스트 및 시각적 콘텐츠(레이아웃, 차트 등)를 모두 고려할 수 있는 단일 모델로, 잠재적으로 복잡하고 취약할 수 있는 레이아웃 인식 및 OCR 파이프라인의 필요성을 제거할 수 있습니다.
ColModernVBert는 ModernVBert를 기반으로 학습되었으며, 다음 논문에서 소개되었습니다: ModernVBERT: Towards Smaller Visual Document Retrievers.
ColModernVBert는 ColPali: Efficient Document Retrieval with Vision Language Models 논문에서 ColPali와 함께 소개된 ColVision 모델 계열의 일부입니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
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)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은image_processor_class.__call__를 참조하세요 (ColModernVBertProcessor는 이미지 처리에image_processor_class를 사용합니다). - attention_mask (
torch.Tensor형상이(batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요?[0, 1]:- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
반환값
ColModernVBertForRetrievalOutput 또는 tuple(torch.Tensor)
ColModernVBertForRetrievalOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우)로, 구성(ColModernVBertConfig)과 입력에 따라 다양한 요소를 포함합니다.
ColModernVBertForRetrieval의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).임베딩 (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 임베딩입니다.hidden_states (
tuple[torch.Tensor], 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
image_hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True이고pixel_values가 제공된 경우 반환됨) —torch.Tensor의 튜플(이미지 모달리티 투영의 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, num_channels, image_size, image_size)입니다. 각 레이어의 출력에서 이미지 인코더의 hidden-states와 초기 모달리티 투영 출력을 포함합니다.attentions (
tuple[torch.Tensor], 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.