# InternVL

InternVL3 비전 언어 모델(VLM) 계열은 [InternVL3: Exploring Advanced Training and Test-Time Recipes for Open-Source Multimodal Models](https://huggingface.co/papers/2504.10479)에서 소개되었습니다.

해당 논문의 초록은 다음과 같습니다:

*다양한 멀티모달 데이터와 순수 텍스트 코퍼스를 단일 사전 학습 단계에서 함께 활용하여 멀티모달 및 언어 능력을 동시에 습득하는 네이티브 멀티모달 사전 학습 패러다임을 갖춘 InternVL3를 소개합니다. 텍스트 전용 대규모 언어 모델(LLM)을 시각 입력을 지원하는 멀티모달 대규모 언어 모델(MLLM)로 변환하는 방식이 아닌, InternVL3는 이러한 통합 학습 패러다임을 통해 MLLM의 기존 사후 학습 파이프라인에서 흔히 발생하는 복잡성과 정렬 문제를 효과적으로 해결합니다. 성능과 확장성을 한층 높이기 위해 InternVL3는 확장된 멀티모달 컨텍스트를 지원하는 가변 시각 위치 인코딩(V2PE)을 도입하고, 감독 기반 미세 조정(SFT) 및 혼합 선호도 최적화(MPO)와 같은 고급 사후 학습 기법을 활용하며, 최적화된 학습 인프라와 함께 테스트 시 스케일링 전략을 채택합니다. 광범위한 실증 평가를 통해 InternVL3가 다양한 멀티모달 작업 전반에서 우수한 성능을 발휘하는 것으로 확인되었습니다. 특히, InternVL3-78B는 MMMU 벤치마크에서 72.2점을 기록하며 오픈소스 MLLM 중 새로운 최첨단(SOTA) 기록을 세웠습니다. ChatGPT-4o, Claude 3.5 Sonnet, Gemini 2.5 Pro를 비롯한 주요 독점 모델과도 경쟁력 있는 성능을 유지하는 동시에, 순수 언어 능력 또한 뛰어난 수준을 유지합니다. 오픈 사이언스 원칙을 실천하기 위해, 차세대 MLLM의 연구 및 개발을 촉진하고자 학습 데이터와 모델 가중치를 모두 공개할 예정입니다.*

 InternVL3 모델 아키텍처 개요로, InternVL2.5와 동일합니다. 원본 체크포인트에서 가져왔습니다.

 InternVL3의 OpenCompass 성능을 다른 SOTA VLLM과 비교한 것입니다. 원본 체크포인트에서 가져왔습니다.

이 모델은 [yonigozlan](https://huggingface.co/yonigozlan)이(가) 기여했습니다. 원본 코드는 [여기](https://github.com/OpenGVLab/InternVL)에서 찾을 수 있습니다.

> [!TIP]
> `use_kernels=True`를 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained)에 설정하여 Hub의 최적화 커널로 지원되는 레이어를 대체합니다. 자세한 내용은 [커널 로딩](../kernel_doc/loading_kernels)을 참고하세요.

## 사용 예시

### Pipeline을 사용한 추론

`image-text-to-text` 파이프라인을 사용하여 `InternVL3` 모델로 추론을 수행하는 방법은 다음과 같습니다. 몇 줄의 코드로 가능합니다:

```python
from transformers import pipeline

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

pipe = pipeline("image-text-to-text", model="OpenGVLab/InternVL3-1B-hf")
outputs = pipe(text=messages, max_new_tokens=50, return_full_text=False)
outputs[0]["generated_text"]
'The image showcases a vibrant scene of nature, featuring several flowers and a bee. \n\n1. **Foreground Flowers**: \n   - The primary focus is on a large, pink cosmos flower with a prominent yellow center. The petals are soft and slightly r'
```

### 단일 이미지에서 추론

이 예제는 chat templates를 사용하여 InternVL 모델로 단일 이미지에 대해 추론을 수행하는 방법을 보여줍니다.

> [!NOTE]
> 모델은 채팅을 위해 특정 프롬프트 형식으로 학습되었습니다. 프롬프트를 올바르게 포맷하려면 `processor.apply_chat_template(my_conversation_dict)`를 사용하세요.

```python

from transformers import AutoModelForImageTextToText, AutoProcessor

model_checkpoint = "OpenGVLab/InternVL3-1B-hf"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "Please describe the image explicitly."},
        ],
    }
]

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

generate_ids = model.generate(**inputs, max_new_tokens=50)
decoded_output = processor.decode(generate_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=True)

decoded_output
'The image shows two cats lying on a pink blanket. The cat on the left is a tabby with a mix of brown, black, and white fur, and it appears to be sleeping with its head resting on the blanket. The cat on the'
```

### 텍스트 전용 생성

이 예제는 이미지 입력을 제공하지 않고 InternVL 모델을 사용하여 텍스트를 생성하는 방법을 보여줍니다.

```python

from transformers import AutoModelForImageTextToText, AutoProcessor

model_checkpoint = "OpenGVLab/InternVL3-1B-hf"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Write a haiku"},
        ],
    }
]

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

generate_ids = model.generate(**inputs, max_new_tokens=50)
decoded_output = processor.decode(generate_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=True)

print(decoded_output)
"Whispers of dawn,\nSilent whispers of the night,\nNew day's light begins."
```

### 배치된 이미지 및 텍스트 입력

InternVL 모델은 배치된 이미지 및 텍스트 입력도 지원합니다.

```python

from transformers import AutoModelForImageTextToText, AutoProcessor

model_checkpoint = "OpenGVLab/InternVL3-1B-hf"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/llava_view.jpg"},
                {"type": "text", "text": "Write a haiku for this image"},
            ],
        },
    ],
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://www.ilankelman.org/stopsigns/australia.jpg"},
                {"type": "text", "text": "Describe this image"},
            ],
        },
    ],
]

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

output = model.generate(**inputs, max_new_tokens=25)

decoded_outputs = processor.batch_decode(output, skip_special_tokens=True)
decoded_outputs
["user\n\nWrite a haiku for this image\nassistant\nSilky lake,  \nWooden pier,  \nNature's peace.",
 'user\n\nDescribe this image\nassistant\nThe image shows a street scene with a traditional Chinese archway, known as a "Chinese Gate" or "Chinese Gate of']
```

### Batched multi-image input

InternVL 모델의 이 구현은 각 텍스트마다 서로 다른 수의 이미지를 가진 배치된 텍스트-이미지 입력을 지원합니다.

```python
from transformers import AutoProcessor, AutoModelForImageTextToText
import torch

model_checkpoint = "OpenGVLab/InternVL3-1B-hf"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/llava_view.jpg"},
                {"type": "text", "text": "Write a haiku for this image"},
            ],
        },
    ],
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/statue_of_liberty.jpg"},
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dreamstime_golden_gate_flowers.jpg"},
                {"type": "text", "text": "These images depict two different landmarks. Can you identify them?"},
            ],
        },
    ],
]

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

output = model.generate(**inputs, max_new_tokens=25)

decoded_outputs = processor.batch_decode(output, skip_special_tokens=True)
decoded_outputs
["user\n\nWrite a haiku for this image\nassistant\nSilky lake,  \nWooden pier,  \nNature's peace.",
 'user\n\n\nThese images depict two different landmarks. Can you identify them?\nassistant\nYes, these images depict the Statue of Liberty and the Golden Gate Bridge.']
```

### 비디오 입력

InternVL 모델은 비디오 입력도 처리할 수 있습니다. 다음은 chat templates를 사용하여 비디오 입력에 대해 추론을 수행하는 예시입니다.

```python
from transformers import AutoModelForImageTextToText, AutoProcessor, BitsAndBytesConfig

model_checkpoint = "OpenGVLab/InternVL3-8B-hf"
quantization_config = BitsAndBytesConfig(load_in_4bit=True)
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, quantization_config=quantization_config, device_map="auto")

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "video",
                "url": "https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4",
            },
            {"type": "text", "text": "What type of shot is the man performing?"},
        ],
    }
]
inputs = processor.apply_chat_template(
    messages,
    return_tensors="pt",
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    num_frames=8,
).to(model.device)

output = model.generate(**inputs, max_new_tokens=25)

decoded_output = processor.decode(output[0, inputs["input_ids"].shape[1] :], skip_special_tokens=True)
decoded_output
'The man is performing a forehand shot.'
```

### 이미지와 비디오 입력의 교차

이 예제는 chat template를 사용하여 이미지와 비디오 입력이 교차 배치된 채팅 대화 배치(batch)를 처리하는 방법을 보여줍니다.

```python
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig
import torch

model_checkpoint = "OpenGVLab/InternVL3-1B-hf"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/statue_of_liberty.jpg"},
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dreamstime_golden_gate_flowers.jpg"},
                {"type": "text", "text": "These images depict two different landmarks. Can you identify them?"},
            ],
        },
    ],
    [
        {
            "role": "user",
            "content": [
                {"type": "video", "url": "https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4"},
                {"type": "text", "text": "What type of shot is the man performing?"},
            ],
        },
    ],
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/llava_view.jpg"},
                {"type": "text", "text": "Write a haiku for this image"},
            ],
        },
    ],
]
inputs = processor.apply_chat_template(
    messages,
    padding=True,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=25)

decoded_outputs = processor.batch_decode(outputs, skip_special_tokens=True)
decoded_outputs
['user\n\n\nThese images depict two different landmarks. Can you identify them?\nassistant\nThe images depict the Statue of Liberty and the Golden Gate Bridge.',
 'user\nFrame1: \nFrame2: \nFrame3: \nFrame4: \nFrame5: \nFrame6: \nFrame7: \nFrame8: \nWhat type of shot is the man performing?\nassistant\nA forehand shot',
 "user\n\nWrite a haiku for this image\nassistant\nSilky lake,  \nWooden pier,  \nNature's peace."]
```

## InternVLVisionConfig[[transformers.InternVLVisionConfig]]

#### transformers.InternVLVisionConfig[[transformers.InternVLVisionConfig]]

```python
transformers.InternVLVisionConfig(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, hidden_size: int = 1024, num_hidden_layers: int = 24, num_attention_heads: int = 16, attention_bias: bool = False, use_qk_norm: bool = False, intermediate_size: int = 4096, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, attention_dropout: float | int = 0.0, projection_dropout: float | int = 0.0, initializer_range: float = 0.02, norm_type: str = 'layer_norm', layer_norm_eps: float = 1e-06, image_size: int | list[int] | tuple[int, ...] = (448, 448), patch_size: int | list[int] | tuple[int, ...] = (14, 14), num_channels: int = 3, use_mask_token: bool = False, use_absolute_position_embeddings: bool = True, layer_scale_init_value: float = 0.1, use_mean_pooling: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/configuration_internvl.py#L25)

**매개변수:**

hidden_size (`int`, *선택 사항*, 기본값 `1024`) : 숨겨진 표현의 차원.

num_hidden_layers (`int`, *선택 사항*, 기본값 `24`) : Transformer decoder의 숨겨진 레이어 수.

num_attention_heads (`int`, *선택 사항*, 기본값 `16`) : Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.

attention_bias (`bool`, *선택 사항*, 기본값 `False`) : self-attention에서 query, key, value 및 output projection layer에 bias를 사용할지 여부.

use_qk_norm (`bool`, *선택 사항*, 기본값 `False`) : attention에서 query-key 정규화를 사용할지 여부.

intermediate_size (`int`, *선택 사항*, 기본값 `4096`) : MLP 표현의 차원.

hidden_act (`str`, *선택 사항*, 기본값 `gelu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다.

hidden_dropout_prob (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 임베딩, 인코더, 풀러의 모든 완전 연결 계층에 적용되는 dropout 확률입니다.

attention_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다.

projection_dropout (`float`, *선택 사항*, 기본값 0.0) : 투영 레이어의 Dropout 확률입니다.

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

norm_type (`str`, *선택 사항*, 기본값 `"layer_norm"`) : 인코더에서 사용할 정규화 유형입니다. `"layer_norm"` 또는 `"rms_norm"`를 사용할 수 있습니다.

layer_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : 레이어 정규화 레이어에서 사용되는 epsilon 값입니다.

image_size (`Union[int, list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(448, 448)`) : 각 이미지의 크기(해상도).

patch_size (`Union[int, list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(14, 14)`) : 각 패치의 크기(해상도).

num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력 채널의 수입니다.

use_mask_token (`bool`, *선택 사항*, 기본값 `False`) : masked image modeling에 mask token을 사용할지 여부

use_absolute_position_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 절대 위치 임베딩을 사용할지 여부.

layer_scale_init_value (`float`, *선택 사항*, 기본값 `0.1`) : self-attention 레이어에서 사용할 스케일입니다. base 모델은 0.1, large 모델은 1e-6을 사용합니다. 0으로 설정하면 layer scale을 비활성화합니다.

use_mean_pooling (`bool`, *선택 사항*, 기본값 `True`) : 분류 헤드를 적용하기 전에, CLS 토큰의 최종 숨겨진 상태를 사용하는 대신 패치의 최종 숨겨진 상태를 평균 풀링할지 여부.

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

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)의 문서를 참고하세요.

예:

```python
>>> from transformers import InternVLVisionConfig, InternVLVisionModel

>>> # Initializing a InternVLVisionModel OpenGVLab/InternVL3-1B-hf style configuration
>>> configuration = InternVLVisionConfig()

>>> # Initializing a model (with random weights) from the OpenGVLab/InternVL3-1B-hf configuration
>>> model = InternVLVisionModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## InternVLConfig[[transformers.InternVLConfig]]

#### transformers.InternVLConfig[[transformers.InternVLConfig]]

```python
transformers.InternVLConfig(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, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_id: int = 151667, image_seq_length: int = 256, downsample_ratio: float = 0.5, projector_hidden_act: str = 'gelu', vision_feature_layer: int | list[int] = -1, vision_feature_select_strategy: str = 'default', tie_word_embeddings: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/configuration_internvl.py#L88)

**매개변수:**

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

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

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

image_seq_length (`int`, *선택 사항*, 기본값 `256`) : 이미지 임베딩 하나의 시퀀스 길이.

downsample_ratio (`float`, *선택 사항*, 기본값 0.5) : 이미지를 다운샘플링할 비율.

projector_hidden_act (`str`, *선택 사항*, 기본값 `gelu`) : 멀티모달 프로젝터에 사용되는 활성화 함수입니다.

vision_feature_layer (`Union[int, list[int]]`, *선택 사항*, 기본값 `-1`) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.

vision_feature_select_strategy (`str`, *선택 사항*, 기본값 `default`) : 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다.

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

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

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)의 문서를 참고하세요.

예:

```python
>>> from transformers import InternVLForConditionalGeneration, InternVLConfig

>>> # Initializing a InternVL style configuration
>>> configuration = InternVLConfig()

>>> # Initializing a model (with random weights) from the OpenGVLab/InternVL3-1B-hf configuration
>>> model = InternVLForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## InternVLVisionModel[[transformers.InternVLVisionModel]]

#### transformers.InternVLVisionModel[[transformers.InternVLVisionModel]]

```python
transformers.InternVLVisionModel(config: InternVLVisionConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L428)

**매개변수:**

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

Internvl 모델은 상단에 특정 헤드가 없는 상태에서 원시 hidden-states를 출력하는 기본 모델입니다.

이 모델은 [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.InternVLVisionModel.forward]]

```python
forward(pixel_values: Tensor, bool_masked_pos: typing.Optional[torch.BoolTensor] = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L446)

**매개변수:**

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

bool_masked_pos (`torch.BoolTensor`, shape `(batch_size, num_patches)`, *선택 사항*) : Boolean masked positions. 어떤 patch가 mask(1)되고 어떤 patch는 mask되지(0) 않았는지를 나타냅니다.

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

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

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

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

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **pooler_output** (`torch.Tensor`, shape `(batch_size, hidden_size)`) -- *config.use_mean_pooling*이 True로 설정된 경우, *[CLS]* 토큰을 제외한 패치 토큰의 마지막 레이어 hidden states의 평균입니다. False로 설정된 경우, *[CLS]* 토큰의 최종 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 가중치입니다.

## InternVLModel[[transformers.InternVLModel]]

#### transformers.InternVLModel[[transformers.InternVLModel]]

```python
transformers.InternVLModel(config: InternVLConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L529)

**매개변수:**

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

언어 모델링 헤드가 없는 비전 백본과 언어 모델로 구성된 InternVL 모델

이 모델은 [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.InternVLModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, vision_feature_layer: int | list[int] | None = None, vision_feature_select_strategy: str | None = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L612)

**매개변수:**

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)

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

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)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

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

vision_feature_layer (`Union[int, list[int]]`, *선택 사항*) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.

vision_feature_select_strategy (`str`, *선택 사항*) : 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다. `"default"` 또는 `"full"` 중 하나여야 합니다.

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *선택 사항*) : 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 Dict입니다. 각 인코딩된 출력은 (`pooler_output`, *선택 사항*: `last_hidden_states`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`)의 튜플로 구성되며, `pooler_output`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

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

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

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

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

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **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** (`torch.Tensor`, *선택 사항*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 비전 인코더가 생성한 모델의 image_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.

#### get_image_features[[transformers.InternVLModel.get_image_features]]

```python
get_image_features(pixel_values: Tensor, vision_feature_layer: int | list[int] | None = None, vision_feature_select_strategy: str | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L538)

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, channels, height, width)`) : 입력 이미지에 해당하는 텐서입니다.

vision_feature_layer (`int` 또는 `list[int]`) : 특징을 추출할 레이어 인덱스 또는 레이어 인덱스 목록.

vision_feature_layer (`Union[int, list[int]]`, *선택 사항*) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.

vision_feature_select_strategy (`str`, *선택 사항*) : 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다. `"default"` 또는 `"full"` 중 하나여야 합니다.

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

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

비전 타워에서 이미지 마지막 hidden states를 가져와서 멀티모달 프로젝션을 적용합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **pooler_output** (`torch.Tensor`, shape `(batch_size, hidden_size)`) -- 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 보조 사전학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 값입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전학습 단계에서 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.
- **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 가중치입니다.

## InternVLForConditionalGeneration[[transformers.InternVLForConditionalGeneration]]

#### transformers.InternVLForConditionalGeneration[[transformers.InternVLForConditionalGeneration]]

```python
transformers.InternVLForConditionalGeneration(config: InternVLConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L740)

**매개변수:**

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

비전 백본과 언어 모델로 구성된 INTERNVL 모델

이 모델은 [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.InternVLForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, vision_feature_layer: int | list[int] | None = None, vision_feature_select_strategy: str | None = None, labels: typing.Optional[torch.LongTensor] = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, image_sizes: typing.Optional[torch.Tensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L768)

**매개변수:**

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)

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

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)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

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

vision_feature_layer (`Union[int, list[int]]`, *선택 사항*) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.

vision_feature_select_strategy (`str`, *선택 사항*) : 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다. `"default"` 또는 `"full"` 중 하나여야 합니다.

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

logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

image_sizes (`torch.Tensor`, shape `(batch_size, 2)`, *선택 사항*) : 배치 내 각 이미지의 크기입니다. 각 이미지에 대해 (height, width) 형식입니다.

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *선택 사항*) : 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 Dict입니다. 각 인코딩된 출력은 (`pooler_output`, *선택 사항*: `last_hidden_states`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`)의 튜플로 구성되며, `pooler_output`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

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

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

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **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** (`torch.Tensor`, *선택 사항*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 비전 인코더가 생성한 모델의 image_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.

예:

```python
>>> import torch
>>> from transformers import AutoProcessor, AutoModelForImageTextToText

>>> torch_device = "cuda"
>>> processor = AutoProcessor.from_pretrained("OpenGVLab/InternVL3-1B-hf")
>>> model = AutoModelForImageTextToText.from_pretrained(
...     "OpenGVLab/InternVL3-1B-hf", dtype=torch.bfloat16, device_map=torch_device
... )

>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {
...                 "type": "image",
...                 "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/statue_of_liberty.jpg",
...             },
...             {
...                 "type": "image",
...                 "url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dreamstime_golden_gate_flowers.jpg",
...             },
...             {"type": "text", "text": "These images depict two different landmarks. Can you identify them?"},
...         ],
...     },
... ]

>>> inputs = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(torch_device)
>>> generate_ids = model.generate(**inputs, max_new_tokens=200)
>>> print(processor.decode(generate_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=True))
The images depict the Statue of Liberty and the Golden Gate Bridge.
```

#### get_image_features[[transformers.InternVLForConditionalGeneration.get_image_features]]

```python
get_image_features(pixel_values: Tensor, vision_feature_layer: int | list[int] | None = None, vision_feature_select_strategy: str | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/modeling_internvl.py#L753)

**매개변수:**

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

vision_feature_layer (`Union[int, list[int]]`, *선택 사항*) : 시각 특징을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특징이 연결되어 시각 특징을 형성합니다.

vision_feature_select_strategy (`str`, *선택 사항*) : 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다. `"default"` 또는 `"full"` 중 하나여야 합니다.

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

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

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **pooler_output** (`torch.Tensor`, shape `(batch_size, hidden_size)`) -- 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 보조 사전학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 값입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전학습 단계에서 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.
- **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 PIL import Image
>>> from transformers import AutoProcessor, InternVLForConditionalGeneration

>>> model = InternVLForConditionalGeneration.from_pretrained("OpenGVLab/InternVL3-1B-hf")
>>> processor = AutoProcessor.from_pretrained("OpenGVLab/InternVL3-1B-hf")

>>> messages = [
...     {
...         "role": "user", "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "Where is the cat standing?"},
...         ]
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
...     add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]
```

## InternVLProcessor[[transformers.InternVLProcessor]]

#### transformers.InternVLProcessor[[transformers.InternVLProcessor]]

```python
transformers.InternVLProcessor(image_processor = None, tokenizer = None, video_processor = None, image_seq_length: int = 256, chat_template = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/processing_internvl.py#L29)

**매개변수:**

image_processor (`GotOcr2ImageProcessor`) : 이미지 프로세서가 필수 입력입니다.

tokenizer (`Qwen2Tokenizer`) : 토크나이저는 필수 입력값입니다.

video_processor (`InternVLVideoProcessor`) : 비디오 프로세서가 필수 입력입니다.

image_seq_length (`int`, *선택 사항*, 기본값 256) : 이미지 패치당 사용할 이미지 토큰의 수입니다. 다음을 만족하도록 설정해야 합니다: image_seq_length = (config.image_size // config.patch_size) ** 2 * (config.scale_factor**2)

chat_template (`str`) : 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.

이미지 프로세서, 토크나이저, 비디오 프로세서를 단일 프로세서로 묶는 InternVLProcessor를 생성합니다.

[InternVLProcessor](/docs/transformers/v5.23.0/ko/model_doc/internvl#transformers.InternVLProcessor)는 [GotOcr2ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/got_ocr2#transformers.GotOcr2ImageProcessor), [Qwen2Tokenizer](/docs/transformers/v5.23.0/ko/model_doc/qwen2#transformers.Qwen2Tokenizer), [InternVLVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/internvl#transformers.InternVLVideoProcessor)의 모든 기능을 제공합니다. 자세한 내용은 [~GotOcr2ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/got_ocr2#transformers.GotOcr2ImageProcessor), [~Qwen2Tokenizer](/docs/transformers/v5.23.0/ko/model_doc/qwen2#transformers.Qwen2Tokenizer), [~InternVLVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/internvl#transformers.InternVLVideoProcessor)를 참고하세요.

#### __call__[[transformers.InternVLProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] | None = None, videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/processing_internvl.py#L72)

**매개변수:**

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`로 설정하세요.

text (`Union[str, list[str], list[list[str]]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치 입력과의 혼동을 피하기 위해 `is_split_into_words=True`를 설정하세요.

videos (`Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]`, *선택*) : 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위를 가지는 단일 비디오 또는 비디오 배치(batch)를 기대합니다. 픽셀 값이 0에서 1 범위를 가지는 비디오를 전달하는 경우 `do_rescale=False`로 설정하세요.

return_mm_token_type_ids (`bool`, *kwargs*) : 멀티모달 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부.

return_text_replacement_offsets (`bool`, *kwargs*) : 각 멀티모달 플레이스홀더 및 그 대체 문자열의 문자 오프셋을 반환할지 여부.

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

**반환값:** [BatchFeature](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.BatchFeature)

다음 필드를 가진 [BatchFeature](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- 모델에 입력할 토큰 ID 목록. `text`가 `None`이 아닌 경우 반환됩니다.
- **attention_mask** -- 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록 (`return_attention_mask=True`이거나, `self.model_input_names`에 *"attention_mask"*가 포함되어 있고 `text`가 `None`이 아닌 경우).
- **pixel_values** -- 모델에 입력할 픽셀 값. `images`가 `None`이 아닌 경우 반환됩니다.

## InternVLVideoProcessor[[transformers.InternVLVideoProcessor]]

#### transformers.InternVLVideoProcessor[[transformers.InternVLVideoProcessor]]

```python
transformers.InternVLVideoProcessor(**kwargs: *<class 'transformers.models.internvl.video_processing_internvl.InternVLVideoProcessorInitKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/video_processing_internvl.py#L38)

**매개변수:**

- ****kwargs** (`InternVLVideoProcessorInitKwargs`, *선택*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

InternVLVideoProcessor 비디오 프로세서를 생성합니다.

#### sample_frames[[transformers.InternVLVideoProcessor.sample_frames]]

```python
sample_frames(metadata: VideoMetadata, num_frames: int | None = None, fps: int | float | None = None, initial_shift: bool | float | int | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/internvl/video_processing_internvl.py#L54)

**매개변수:**

metadata (`VideoMetadata`) : 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다.

num_frames (`int`, *선택 사항*) : 샘플링할 최대 프레임 수. 기본값은 `self.num_frames`입니다.

fps (`int` 또는 `float`, *선택 사항*) : 초당 샘플링할 대상 프레임 수. 기본값은 `self.fps`입니다.

initial_shift (`bool`, `float` 또는 `int`, 기본값은 `self.initial_shift`) : 프레임 샘플링 시 적용할 초기 shift입니다. `True`인 경우, shift가 비디오 중간에서 프레임이 샘플링되도록 설정됩니다.

**반환값:** `torch.Tensor`

video 프레임에서 샘플링할 인덱스.

0부터 총 프레임 수까지 원하는 프레임 수를 균등하게 샘플링하는 기본 샘플링 함수입니다. 메타데이터와 함께 `fps`가 전달되면, 초당 `fps` 프레임이 균등하게 샘플링됩니다. `num_frames`와 `fps` 인수는 상호 배타적입니다.

