# UltraVBert

## 개요

UltraVBert는 [ModernVBert](./modernvbert)를 확장하여 [UltraBERT](./ultrabert) 텍스트 인코더와 [SigLIP](./siglip) 비전 인코더를 결합함으로써 시각 문서 이해 및 검색을 지원합니다. 이미지 프로세서가 페이지를 512픽셀 타일과 전체 뷰로 분할합니다. 커넥터가 비전 패치의 각 4 x 4 블록을 하나의 토큰으로 병합하여 타일 하나당 64개의 이미지 토큰을 생성하고, 이를 UltraBERT의 토큰 임베딩 규모에 맞게 RMS 정규화합니다. 기본값이 27인 `max_image_tiles`는 512픽셀 단위로 리사이즈 경계를 낮추어 페이지당 타일 수를 제한합니다.

## 사용 예시

```python
import torch

from transformers import AutoModelForMaskedLM, AutoProcessor
from transformers.image_utils import load_image

processor = AutoProcessor.from_pretrained("athrael-soju/UltraVBERT")
model = AutoModelForMaskedLM.from_pretrained("athrael-soju/UltraVBERT", device_map="auto")

image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/fixtures_image_utils/resolve/main/receipt_00008.png"
)
inputs = processor(text="<image>Rounding 0 <|mask|> 50,000", images=[image], return_tensors="pt").to(model.device)

with torch.no_grad():
    logits = model(**inputs).logits

masked_index = torch.where(inputs["input_ids"] == processor.tokenizer.mask_token_id)
predicted_token_id = logits[masked_index].argmax(dim=-1)
print(processor.tokenizer.decode(predicted_token_id))
```

`fill-mask` 파이프라인은 텍스트만 읽습니다.

```python
from transformers import pipeline

fill_mask = pipeline(task="fill-mask", model="athrael-soju/UltraVBERT", device_map="auto")
print(fill_mask("Plants create <|mask|> through a process known as photosynthesis."))
```

## UltraVBertConfig[[transformers.UltraVBertConfig]]

#### transformers.UltraVBertConfig[[transformers.UltraVBertConfig]]

```python
transformers.UltraVBertConfig(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: transformers.configuration_utils.PreTrainedConfig | dict | None = None, vision_config: transformers.configuration_utils.PreTrainedConfig | dict | None = None, image_token_id: int = 49191, pixel_shuffle_factor: int = 4, initializer_range: float = 0.02, initializer_cutoff_factor: float = 2.0, classifier_pooling: typing.Literal['cls', 'mean'] = 'cls', classifier_dropout: float | int = 0.0, tie_word_embeddings: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/configuration_ultravbert.py#L32)

**매개변수:**

text_config (`Union[~configuration_utils.PreTrainedConfig, dict]`, *선택*) : 텍스트 백본의 config 객체 또는 사전입니다.

vision_config (`Union[~configuration_utils.PreTrainedConfig, dict]`, *선택*) : 비전 백본의 config 객체 또는 사전입니다.

image_token_id (`int`, *선택 사항*, 기본값 `49191`) : 입력 이미지의 자리표시자로 사용되는 이미지 토큰 인덱스입니다.

pixel_shuffle_factor (`int`, *선택 사항*, 기본값 4) : 커넥터가 하나의 이미지 토큰으로 병합하는 비전 패치의 정사각형 한 변의 길이입니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

initializer_cutoff_factor (`float`, *선택 사항*, 기본값 2.0) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 절단 계수입니다.

classifier_pooling (`Literal["cls", "mean"]`, *선택 사항*, 기본값 `"cls"`) : 분류 작업에 사용할 풀링 전략입니다.

classifier_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 분류기의 dropout 비율입니다.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `False`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

이것은 UltraVBertModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Ultravbert 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [athrael-soju/UltraVBERT](https://huggingface.co/athrael-soju/UltraVBERT)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## UltraVBertImageProcessor[[transformers.UltraVBertImageProcessor]]

#### transformers.UltraVBertImageProcessor[[transformers.UltraVBertImageProcessor]]

```python
transformers.UltraVBertImageProcessor(**kwargs: *<class 'transformers.models.ultravbert.image_processing_ultravbert.UltraVBertImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/image_processing_ultravbert.py#L216)

**매개변수:**

do_convert_rgb (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, 기본값 `{'longest_edge' : 3072}`): 모델에 입력되는 최대 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : size가 int인 경우 리사이즈 시 정사각형 이미지로 설정할지 여부.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, 기본값 `1`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. 이는 `PILImageResampling` enum 중 하나일 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택 사항*, 기본값 `0.00392156862745098`) : `do_rescale`이 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*, 기본값은 `[0.5, 0.5, 0.5]`) : 정규화에 사용할 이미지 평균입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*, 기본값 `[0.5, 0.5, 0.5]`) : 정규화에 사용할 이미지 표준 편차. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_pad (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 이미지를 패딩할 `{"height": int, "width" int}` 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. `pad_size`가 제공되지 않으면, 이미지는 배치 내 가장 큰 높이와 너비로 패딩됩니다. `do_pad=True.`일 때만 적용됩니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.

disable_grouping (`bool`, *kwargs*, *선택*) : 이미지의 크기에 따른 그룹화를 비활성화하여 이미지를 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.

image_seq_length (`int`, *kwargs*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

do_image_splitting (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 원본 이미지와 연결된 하위 이미지로 분할할지 여부입니다. 각 패치가 `max_image_size["height"]` x `max_image_size["width"]` 크기를 가지도록 패치로 분할됩니다.

max_image_size (`Dict`, *kwargs*, *선택 사항*, 기본값은 `{"longest_edge" : 512}`): 모델이 허용하는 이미지 패치의 최대 해상도입니다. "longest_edge" 키를 포함하는 사전입니다.

return_row_col_info (`bool`, *kwargs*, *선택 사항*, 기본값 `False`) : 이미지의 행 및 열 정보를 반환할지 여부.

max_image_tiles (`int`, *kwargs*, *optional*, 기본값 27) : 전역 이미지는 제외하고, 이미지가 나뉘는 타일의 최대 개수입니다. 이보다 더 많이 나뉘어야 하는 이미지는 `max_image_size["longest_edge"]` 단위로 가장 긴 변을 줄여가며 조정하여 조건에 맞도록 리사이즈됩니다.

UltraVBertImageProcessor 이미지 프로세서를 생성합니다.

#### preprocess[[transformers.UltraVBertImageProcessor.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: *<class 'transformers.models.ultravbert.image_processing_ultravbert.UltraVBertImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/image_processing_ultravbert.py#L236)

**매개변수:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 이미지를 전달하는 경우 `do_rescale=False`로 설정하세요.

do_convert_rgb (`bool`, *kwargs*, *선택*) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택*) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 모델의 최대 입력 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택*) : size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `PILImageResampling` enum 중 하나를 사용할 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택*) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택*) : `do_rescale`가 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택*) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 평균값. `do_normalize`이 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 표준 편차. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_pad (`bool`, *kwargs*, *선택*) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 이미지를 패딩할 `{"height": int, "width" int}` 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. `pad_size`가 제공되지 않으면, 이미지는 배치 내 가장 큰 높이와 너비로 패딩됩니다. `do_pad=True.`일 때만 적용됩니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.

disable_grouping (`bool`, *kwargs*, *선택*) : 이미지의 크기에 따른 그룹화를 비활성화하여 이미지를 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.

image_seq_length (`int`, *kwargs*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

do_image_splitting (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 원본 이미지와 연결된 하위 이미지로 분할할지 여부입니다. 각 패치가 `max_image_size["height"]` x `max_image_size["width"]` 크기를 가지도록 패치로 분할됩니다.

max_image_size (`Dict`, *kwargs*, *선택 사항*, 기본값은 `{"longest_edge" : 512}`): 모델이 허용하는 이미지 패치의 최대 해상도입니다. "longest_edge" 키를 포함하는 사전입니다.

return_row_col_info (`bool`, *kwargs*, *선택 사항*, 기본값 `False`) : 이미지의 행 및 열 정보를 반환할지 여부.

max_image_tiles (`int`, *kwargs*, *optional*, 기본값 27) : 전역 이미지는 제외하고, 이미지가 나뉘는 타일의 최대 개수입니다. 이보다 더 많이 나뉘어야 하는 이미지는 `max_image_size["longest_edge"]` 단위로 가장 긴 변을 줄여가며 조정하여 조건에 맞도록 리사이즈됩니다.

**반환값:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- __call__ 메서드가 반환하는 리스트/배열/텐서 딕셔너리('pixel_values' 등).
- **tensor_type** (`Union[None, str, TensorType]`, *선택 사항*) -- 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다.

## UltraVBertModel[[transformers.UltraVBertModel]]

#### transformers.UltraVBertModel[[transformers.UltraVBertModel]]

```python
transformers.UltraVBertModel(config: UltraVBertConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L184)

**매개변수:**

config ([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Ultravbert Model입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.UltraVBertModel.forward]]

```python
forward(input_ids: LongTensor = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_attention_mask: typing.Optional[torch.BoolTensor] = None, image_hidden_states: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L268)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [UltraVBertImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Idefics3Processor](/docs/transformers/v5.23.0/ko/model_doc/idefics3#transformers.Idefics3Processor)는 이미지 처리에 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용합니다).

pixel_attention_mask (`torch.BoolTensor`, shape `(batch_size, num_images, image_size, image_size)`, *선택 사항*) : 각 이미지 타일의 실제 픽셀에 대한 마스크.

image_hidden_states (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 모달리티 투영 이후 이미지 인코더의 히든 스테이트입니다.

**반환값:** `UltraVBertBaseModelOutput` 또는 `tuple(torch.Tensor)`

`UltraVBertBaseModelOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig))과 입력에 따라 다양한 요소를 포함합니다.

[UltraVBertModel](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **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 가중치입니다.
- **image_hidden_states** (`tuple(torch.FloatTensor)`, *선택 사항*) -- `torch.FloatTensor`의 튜플 (이미지 임베딩의 출력 하나, `(batch_size, num_images, sequence_length, hidden_size)`. 비전 인코더가 생성한 모델의 image_hidden_states

## UltraVBertForMaskedLM[[transformers.UltraVBertForMaskedLM]]

#### transformers.UltraVBertForMaskedLM[[transformers.UltraVBertForMaskedLM]]

```python
transformers.UltraVBertForMaskedLM(config: UltraVBertConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L358)

**매개변수:**

config ([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

`language modeling` 헤드가 위에 있는 Ultravbert 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.UltraVBertForMaskedLM.forward]]

```python
forward(input_ids: LongTensor = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_attention_mask: typing.Optional[torch.BoolTensor] = None, image_hidden_states: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L379)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [UltraVBertImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Idefics3Processor](/docs/transformers/v5.23.0/ko/model_doc/idefics3#transformers.Idefics3Processor)는 이미지 처리에 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용합니다).

pixel_attention_mask (`torch.BoolTensor`, shape `(batch_size, num_images, image_size, image_size)`, *선택 사항*) : 각 이미지 타일의 실제 픽셀에 대한 마스크.

image_hidden_states (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 모달리티 투영 이후 이미지 인코더의 히든 스테이트입니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : masked language modeling loss를 계산하기 위한 라벨. 인덱스는 `[-100, 0, ..., config.vocab_size]` 범위여야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`로 설정된 토큰은 무시(마스크)되며, loss는 `[0, ..., config.vocab_size]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.

**반환값:** `UltraVBertMaskedLMOutput` 또는 `tuple(torch.Tensor)`

`UltraVBertMaskedLMOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig)) 및 입력에 따라 다양한 요소를 포함합니다.

[UltraVBertForMaskedLM](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertForMaskedLM)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- Masked language modeling(MLM) loss.
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **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 가중치입니다.
- **image_hidden_states** (`tuple(torch.FloatTensor)`, *선택 사항*) -- `torch.FloatTensor`의 튜플 (이미지 임베딩의 출력 하나, `(batch_size, num_images, sequence_length, hidden_size)`. 비전 인코더가 생성한 모델의 image_hidden_states

예:

```python
>>> from transformers import AutoTokenizer, UltraVBertForMaskedLM
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("athrael-soju/UltraVBERT")
>>> model = UltraVBertForMaskedLM.from_pretrained("athrael-soju/UltraVBERT")

>>> inputs = tokenizer("The capital of France is <mask>.", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # retrieve index of <mask>
>>> mask_token_index = (inputs.input_ids == tokenizer.mask_token_id)[0].nonzero(as_tuple=True)[0]

>>> predicted_token_id = logits[0, mask_token_index].argmax(axis=-1)
>>> tokenizer.decode(predicted_token_id)
...

>>> labels = tokenizer("The capital of France is Paris.", return_tensors="pt")["input_ids"]
>>> # mask labels of non-<mask> tokens
>>> labels = torch.where(inputs.input_ids == tokenizer.mask_token_id, labels, -100)

>>> outputs = model(**inputs, labels=labels)
>>> round(outputs.loss.item(), 2)
...
```

## UltraVBertForSequenceClassification[[transformers.UltraVBertForSequenceClassification]]

#### transformers.UltraVBertForSequenceClassification[[transformers.UltraVBertForSequenceClassification]]

```python
transformers.UltraVBertForSequenceClassification(config: UltraVBertConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L433)

**매개변수:**

config ([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

UltraVBert 모델은 상단에 sequence classification 헤드가 있으며, 이 헤드는 풀링을 수행합니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.UltraVBertForSequenceClassification.forward]]

```python
forward(input_ids: LongTensor = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_attention_mask: typing.Optional[torch.BoolTensor] = None, image_hidden_states: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L447)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [UltraVBertImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Idefics3Processor](/docs/transformers/v5.23.0/ko/model_doc/idefics3#transformers.Idefics3Processor)는 이미지 처리에 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용합니다).

pixel_attention_mask (`torch.BoolTensor`, shape `(batch_size, num_images, image_size, image_size)`, *선택 사항*) : 각 이미지 타일의 실제 픽셀에 대한 마스크.

image_hidden_states (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 모달리티 투영 이후 이미지 인코더의 히든 스테이트입니다.

labels (`torch.LongTensor`, shape `(batch_size,)`, *선택 사항*) : 시퀀스 분류/회귀 손실을 계산하는 데 사용되는 라벨. 인덱스는 `[0, ..., config.num_labels - 1]` 범위에 있어야 합니다. `config.num_labels == 1`인 경우 회귀 손실(평균 제곱 오차)이 계산되고, `config.num_labels > 1`인 경우 분류 손실(교차 엔트로피)이 계산됩니다.

**반환값:** [SequenceClassifierOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) 또는 `tuple(torch.Tensor)`

구성([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig))과 입력에 따라 다양한 요소를 포함하는 [SequenceClassifierOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[UltraVBertForSequenceClassification](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertForSequenceClassification)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- 분류(또는 config.num_labels==1인 경우 회귀) 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, config.num_labels)`) -- SoftMax 적용 전 분류(또는 config.num_labels==1인 경우 회귀) 점수.
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **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 가중치입니다.

단일 레이블 분류의 예시:

```python
>>> import torch
>>> from transformers import AutoTokenizer, UltraVBertForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("athrael-soju/UltraVBERT")
>>> model = UltraVBertForSequenceClassification.from_pretrained("athrael-soju/UltraVBERT")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_id = logits.argmax().item()
>>> model.config.id2label[predicted_class_id]
...

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = UltraVBertForSequenceClassification.from_pretrained("athrael-soju/UltraVBERT", num_labels=num_labels)

>>> labels = torch.tensor([1])
>>> loss = model(**inputs, labels=labels).loss
>>> round(loss.item(), 2)
...
```

다중 레이블 분류의 예시:

```python
>>> import torch
>>> from transformers import AutoTokenizer, UltraVBertForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("athrael-soju/UltraVBERT")
>>> model = UltraVBertForSequenceClassification.from_pretrained("athrael-soju/UltraVBERT", problem_type="multi_label_classification")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_ids = torch.arange(0, logits.shape[-1])[torch.sigmoid(logits).squeeze(dim=0) > 0.5]

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = UltraVBertForSequenceClassification.from_pretrained(
...     "athrael-soju/UltraVBERT", num_labels=num_labels, problem_type="multi_label_classification"
... )

>>> labels = torch.sum(
...     torch.nn.functional.one_hot(predicted_class_ids[None, :].clone(), num_classes=num_labels), dim=1
... ).to(torch.float)
>>> loss = model(**inputs, labels=labels).loss
```

## UltraVBertForTokenClassification[[transformers.UltraVBertForTokenClassification]]

#### transformers.UltraVBertForTokenClassification[[transformers.UltraVBertForTokenClassification]]

```python
transformers.UltraVBertForTokenClassification(config: UltraVBertConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L534)

**매개변수:**

config ([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

토큰 분류 헤드가 위에 있는 UltraVBert 모델로, 예: Named Entity Recognition (NER) 작업에 사용됩니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.UltraVBertForTokenClassification.forward]]

```python
forward(input_ids: LongTensor = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_attention_mask: typing.Optional[torch.BoolTensor] = None, image_hidden_states: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/ultravbert/modeling_ultravbert.py#L547)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [UltraVBertImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Idefics3Processor](/docs/transformers/v5.23.0/ko/model_doc/idefics3#transformers.Idefics3Processor)는 이미지 처리에 [UltraVBertImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertImageProcessor)를 사용합니다).

pixel_attention_mask (`torch.BoolTensor`, shape `(batch_size, num_images, image_size, image_size)`, *선택 사항*) : 각 이미지 타일의 실제 픽셀에 대한 마스크.

image_hidden_states (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 모달리티 투영 이후 이미지 인코더의 히든 스테이트입니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 토큰 분류 손실을 계산하기 위한 라벨. 인덱스는 `[0, ..., config.num_labels - 1]` 범위에 있어야 합니다.

**반환값:** [TokenClassifierOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) 또는 `tuple(torch.Tensor)`

구성([UltraVBertConfig](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertConfig))과 입력에 따라 다양한 요소를 포함하는 [TokenClassifierOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[UltraVBertForTokenClassification](/docs/transformers/v5.23.0/ko/model_doc/ultravbert#transformers.UltraVBertForTokenClassification)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 분류 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.num_labels)`) -- SoftMax 적용 전 분류 점수.
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **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 가중치입니다.

예:

```python
>>> from transformers import AutoTokenizer, UltraVBertForTokenClassification
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("athrael-soju/UltraVBERT")
>>> model = UltraVBertForTokenClassification.from_pretrained("athrael-soju/UltraVBERT")

>>> inputs = tokenizer(
...     "HuggingFace is a company based in Paris and New York", add_special_tokens=False, return_tensors="pt"
... )

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_token_class_ids = logits.argmax(-1)

>>> # Note that tokens are classified rather then input words which means that
>>> # there might be more predicted token classes than words.
>>> # Multiple token classes might account for the same word
>>> predicted_tokens_classes = [model.config.id2label[t.item()] for t in predicted_token_class_ids[0]]
>>> predicted_tokens_classes
...

>>> labels = predicted_token_class_ids
>>> loss = model(**inputs, labels=labels).loss
>>> round(loss.item(), 2)
...
```