# IDEFICS ## 개요 IDEFICS 모델은 Hugo Laurençon, Lucile Saulnier, Léo Tronchon, Stas Bekman, Amanpreet Singh, Anton Lozhkov, Thomas Wang, Siddharth Karamcheti, Alexander M. Rush, Douwe Kiela, Matthieu Cord, Victor Sanh가 [OBELICS: An Open Web-Scale Filtered Dataset of Interleaved Image-Text Documents](https://huggingface.co/papers/2306.16527)에서 제안했습니다. 해당 논문의 초록은 다음과 같습니다: *이미지와 텍스트가 번갈아 배치된 자연 문서로 학습된 대규모 멀티모달 모델은 하나 이상의 이미지를 추론하여 텍스트를 생성해야 하는 다양한 멀티모달 벤치마크에서 이미지-텍스트 쌍으로 학습된 모델보다 우수한 성능을 보입니다. 그러나 이러한 모델을 학습하는 데 사용된 데이터셋은 공개되지 않았으며, 수집 과정이 완전히 명시되지 않았습니다. 우리는 OBELICS 데이터셋을 소개합니다. OBELICS는 Common Crawl에서 추출한 1억 4,100만 개의 웹 페이지, 3억 5,300만 개의 관련 이미지, 1,150억 개의 텍스트 토큰으로 구성된 오픈 웹 규모 필터링된 이미지-텍스트 번갈아 배치 문서 데이터셋입니다. 데이터셋 생성 과정을 설명하고, 포괄적인 필터링 규칙을 제시하며, 데이터셋 콘텐츠에 대한 분석을 제공합니다. OBELICS의 실행 가능성을 보여주기 위해, 해당 데이터셋으로 800억 파라미터의 비전 및 언어 모델을 학습시켜 다양한 멀티모달 벤치마크에서 경쟁력 있는 성능을 달성했습니다. 데이터셋 재현을 위한 코드와 데이터셋 자체를 공개합니다.* 이 모델은 [HuggingFaceM4](https://huggingface.co/HuggingFaceM4)에 의해 기여되었습니다. 원본 코드 저장소는 공개되어 있지 않습니다. Transformers의 IDEFICS 모델링 코드는 사전 학습된 IDEFICS 모델을 fine-tuning하고 inferencing하는 데 사용됩니다. 새로운 IDEFICS 모델을 처음부터 학습하려면 m4 코드베이스를 사용하세요(공개되면 링크가 제공됩니다). ## IdeficsConfig[[transformers.IdeficsConfig]] #### transformers.IdeficsConfig[[transformers.IdeficsConfig]] ```python transformers.IdeficsConfig(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, vocab_size: int = 32000, additional_vocab_size: int = 0, hidden_size: int = 4096, intermediate_size: int = 11008, num_hidden_layers: int = 32, num_attention_heads: int = 32, dropout: float | int = 0.0, hidden_act: str = 'silu', initializer_range: float = 0.02, alpha_initializer: str = 'zeros', alphas_initializer_range: float = 0.0, alpha_type: str = 'float', rms_norm_eps: float = 1e-06, use_cache: bool = True, pad_token_id: int | None = 0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, tie_word_embeddings: bool = False, cross_layer_interval: int = 1, qk_layer_norms: bool = False, freeze_text_layers: bool = True, freeze_text_module_exceptions: list | tuple = (), freeze_lm_head: bool = False, freeze_vision_layers: bool = True, freeze_vision_module_exceptions: list | tuple = (), use_resampler: bool = False, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, max_position_embeddings: int = 2048, perceiver_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, rope_parameters: dict | None = None) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/configuration_idefics.py#L77) **매개변수:** vocab_size (`int`, *선택 사항*, 기본값 `32000`) : 모델의 어휘 크기입니다. `input_ids`로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다. additional_vocab_size (`int`, *선택 사항*, 기본값 0) : 모델의 추가 어휘 크기입니다. 일반적으로 특수 "" 토큰을 위해 사용됩니다. 추가 어휘 토큰은 항상 학습 가능한 반면, 일반 어휘 토큰은 동결하거나 학습하지 않을 수 있습니다. hidden_size (`int`, *선택 사항*, 기본값 `4096`) : 숨겨진 표현의 차원. intermediate_size (`int`, *선택 사항*, 기본값 `11008`) : MLP 표현의 차원. num_hidden_layers (`int`, *선택 사항*, 기본값 `32`) : Transformer decoder의 숨겨진 레이어 수. num_attention_heads (`int`, *선택 사항*, 기본값 `32`) : Transformer decoder의 각 attention layer에 사용할 attention head 수입니다. dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 모든 dropout 레이어에 적용되는 비율입니다. hidden_act (`str`, *선택 사항*, 기본값 `silu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다. initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다. alpha_initializer (`str`, *선택 사항*, 기본값 `"zeros"`) : alphas의 초기화 유형입니다. alphas_initializer_range (`float`, *선택 사항*, 기본값 0.0) : Gated Cross Attention의 alphas를 초기화하는 truncated_normal_initializer의 표준 편차입니다. alpha_type (`str`, *선택 사항*, 기본값 `"float"`) : 게이팅 알파가 벡터인지 단일 float인지 여부. rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : rms normalization 레이어에서 사용되는 epsilon 값입니다. use_cache (`bool`, *선택 사항*, 기본값 `True`) : 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). `config.is_decoder=True`인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다. pad_token_id (`int`, *선택 사항*, 기본값 `0`) : 어휘에서 패딩에 사용되는 토큰 ID입니다. bos_token_id (`int`, *선택 사항*, 기본값 `1`) : 어휘에서 스트림 시작에 사용되는 토큰 ID입니다. eos_token_id (`Union[int, list[int]]`, *선택*, 기본값 `2`) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다. tie_word_embeddings (`bool`, *선택 사항*, 기본값 `False`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부. cross_layer_interval (`int`, *선택 사항*, 기본값 1) : 크로스 어텐션(텍스트에서 이미지로) 레이어 간격. qk_layer_norms (`bool`, *선택 사항*, 기본값 `False`) : q와 k 뒤에 layer norm을 추가할지 여부 freeze_text_layers (`bool`, *선택 사항*, 기본값 `True`) : 텍스트 레이어를 동결할지 여부 freeze_text_module_exceptions (`bool`, *선택 사항*, 기본값 `[]`) : `freeze_text_layers`가 `True`일 때 텍스트 레이어 동결에서 제외할 항목 freeze_lm_head (`bool`, *선택 사항*, 기본값 `False`) : lm head를 동결할지 여부 freeze_vision_layers (`bool`, *선택 사항*, 기본값 `True`) : 비전 레이어를 동결할지 여부 freeze_vision_module_exceptions (`bool`, *선택 사항*, 기본값 `[]`) : `freeze_vision_layers`가 `True`일 때 비동결할 비전 레이어 예외 use_resampler (`bool`, *선택 사항*, 기본값 `False`) : Resampler를 사용할지 여부 vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 비전 백본의 config 객체 또는 사전 정의된 config 딕셔너리입니다. max_position_embeddings (`int`, *선택 사항*, 기본값 `2048`) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다. perceiver_config (`IdeficsPerceiverConfig`, *선택 사항*) : 사용자 지정 perceiver config 또는 dict rope_parameters (`dict`, *선택*) : RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는 `rope_theta` 값이 포함되어야 하며, 더 긴 `max_position_embeddings`로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다. 이것은 IdeficsModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Idefics 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [HuggingFaceM4/idefics-9b](https://huggingface.co/HuggingFaceM4/idefics-9b)와 유사한 구성이 생성됩니다. Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요. 예: ```python >>> from transformers import IdeficsModel, IdeficsConfig >>> # Initializing a Idefics idefics-9b style configuration >>> configuration = IdeficsConfig() >>> # Initializing a model from the idefics-9b style configuration >>> model = IdeficsModel(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## IdeficsVisionConfig[[transformers.IdeficsVisionConfig]] #### transformers.IdeficsVisionConfig[[transformers.IdeficsVisionConfig]] ```python transformers.IdeficsVisionConfig(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, embed_dim: int = 768, image_size: int | list[int] | tuple[int, int] = 224, intermediate_size: int = 5120, patch_size: int | list[int] | tuple[int, int] = 14, num_hidden_layers: int = 32, num_attention_heads: int = 16, num_channels: int = 3, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-05, attention_dropout: float | int = 0.0, initializer_range: float = 0.02, initializer_factor: float = 1.0) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/configuration_idefics.py#L29) **매개변수:** embed_dim (`int`, *선택 사항*, 기본값 `768`) : 임베딩 및 숨겨진 상태의 차원. image_size (`Union[int, list[int], tuple[int, int]]`, *선택*, 기본값 `224`) : 각 이미지의 크기(해상도). intermediate_size (`int`, *선택 사항*, 기본값 `5120`) : MLP 표현의 차원. patch_size (`Union[int, list[int], tuple[int, int]]`, *선택*, 기본값 `14`) : 각 패치의 크기(해상도). num_hidden_layers (`int`, *선택 사항*, 기본값 `32`) : Transformer decoder의 숨겨진 레이어 수. num_attention_heads (`int`, *선택 사항*, 기본값 `16`) : Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다. num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력 채널의 수입니다. hidden_act (`str`, *선택 사항*, 기본값 `gelu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다. layer_norm_eps (`float`, *선택 사항*, 기본값 `1e-05`) : layer normalization 레이어에서 사용되는 epsilon 값입니다. attention_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다. initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다. initializer_factor (`float`, *선택 사항*, 기본값 `1.0`) : 모든 가중치 행렬을 초기화하는 계수입니다(1로 유지해야 하며, 초기화 테스트를 위해 내부적으로 사용됨). 이것은 IdeficsModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Idefics 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [HuggingFaceM4/idefics-9b](https://huggingface.co/HuggingFaceM4/idefics-9b)와 유사한 구성이 생성됩니다. Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요. ## IdeficsPerceiverConfig[[transformers.IdeficsPerceiverConfig]] #### transformers.IdeficsPerceiverConfig[[transformers.IdeficsPerceiverConfig]] ```python transformers.IdeficsPerceiverConfig(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, use_resampler: bool = False, resampler_n_latents: int = 64, resampler_depth: int = 6, resampler_n_heads: int = 16, resampler_head_dim: int = 96, qk_layer_norms_perceiver: bool = False) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/configuration_idefics.py#L49) **매개변수:** use_resampler (`bool`, *선택 사항*, 기본값 `False`) : resampler를 사용할지 여부 resampler_n_latents (`int`, *선택 사항*, 기본값 64) : 입력 시퀀스를 리샘플링("압축")할 잠재 임베딩의 수(보통 < 128). resampler_depth (`int`, *선택 사항*, 기본값 6) : Perceiver Resampler(교차 주의를 사용하는 Transformer)의 깊이. 얕아야 합니다(< 3). resampler_n_heads (`int`, *선택 사항*, 기본값 16) : 각 Transformer 블록의 헤드 수(멀티헤드 셀프 어텐션용). resampler_head_dim (`int`, *선택 사항*, 기본값 96) : Transformer 블록에서 각 헤드 투영의 차원입니다. qk_layer_norms_perceiver (`bool`, *선택 사항*, 기본값 `False`) : perceiver에서 qk layer norms를 사용할지 여부 이것은 IdeficsModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Idefics 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [HuggingFaceM4/idefics-9b](https://huggingface.co/HuggingFaceM4/idefics-9b)와 유사한 구성이 생성됩니다. Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요. ## IdeficsModel[[transformers.IdeficsModel]] #### transformers.IdeficsModel[[transformers.IdeficsModel]] ```python transformers.IdeficsModel(config: IdeficsConfig) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/modeling_idefics.py#L861) **매개변수:** config ([IdeficsConfig](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요. Model은 특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Idefics입니다. 이 모델은 [PreTrainedModel](/docs/transformers/main/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.IdeficsModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, cache: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, image_encoder_embeddings: typing.Optional[torch.Tensor] = None, perceiver_embeddings: typing.Optional[torch.Tensor] = None, image_attention_mask: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, interpolate_pos_encoding: bool | None = False, **kwargs: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/modeling_idefics.py#L936) **매개변수:** input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/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) cache (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 values)입니다. 이는 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때, 이전 디코딩 단계에서 모델이 반환한 `cache`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `cache`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 cache 형식을 출력합니다. `cache`를 사용하는 경우, 이 모델에 과거 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` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다. pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 `image_processor_class`를 사용하여 얻을 수 있습니다. 자세한 내용은 `image_processor_class.__call__`를 참조하세요 (`processor_class`는 이미지 처리에 `image_processor_class`를 사용합니다). image_encoder_embeddings (`torch.Tensor`, *선택 사항*) : 이미지 인코더의 출력입니다. perceiver_embeddings (`torch.Tensor`, *선택 사항*) : perceiver resampler의 출력입니다. image_attention_mask (`torch.LongTensor`, *선택 사항*) : 이미지 인코더의 어텐션 마스크입니다. use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `cache` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`cache` 참조). interpolate_pos_encoding (`bool`, *선택 사항*, 기본값 `False`) : 사전 학습된 위치 인코딩을 보간할지 여부. **반환값:** `IdeficsBaseModelOutputWithPast` 또는 `tuple(torch.Tensor)` `IdeficsBaseModelOutputWithPast` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성(`None`)과 입력에 따라 다양한 요소를 포함합니다. [IdeficsModel](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다. `Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다. - **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다. `cache`가 사용되면 `(batch_size, 1, hidden_size)` 모양의 시퀀스의 마지막 hidden-state만 출력됩니다. - **cache** (`~cache_utils.Cache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv 캐시 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. 순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은 `cache` 입력을 참조). - **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.Tensor)`, *선택*) -- `torch.Tensor`의 튜플 (이미지 임베딩의 출력을 위한 하나, `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states는 비전 인코더, 그리고 선택적으로 퍼셉터에 의해 생성된 모델의 출력입니다 ## IdeficsForVisionText2Text[[transformers.IdeficsForVisionText2Text]] #### transformers.IdeficsForVisionText2Text[[transformers.IdeficsForVisionText2Text]] ```python transformers.IdeficsForVisionText2Text(config: IdeficsConfig, vision_model = None) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/modeling_idefics.py#L1090) #### forward[[transformers.IdeficsForVisionText2Text.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, cache: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, image_encoder_embeddings: typing.Optional[torch.Tensor] = None, perceiver_embeddings: typing.Optional[torch.Tensor] = None, image_attention_mask: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, interpolate_pos_encoding: bool | None = False, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/modeling_idefics.py#L1113) **매개변수:** input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/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) cache (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 values)입니다. 이는 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때, 이전 디코딩 단계에서 모델이 반환한 `cache`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `cache`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 cache 형식을 출력합니다. `cache`를 사용하는 경우, 이 모델에 과거 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` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다. pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 `image_processor_class`를 사용하여 얻을 수 있습니다. 자세한 내용은 `image_processor_class.__call__`를 참조하세요 (`processor_class`는 이미지 처리에 `image_processor_class`를 사용합니다). image_encoder_embeddings (`torch.Tensor`, *선택 사항*) : 이미지 인코더의 출력입니다. perceiver_embeddings (`torch.Tensor`, *선택 사항*) : perceiver resampler의 출력입니다. image_attention_mask (`torch.LongTensor`, *선택 사항*) : 이미지 인코더의 어텐션 마스크입니다. 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]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다. use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `cache` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`cache` 참조). interpolate_pos_encoding (`bool`, *선택 사항*, 기본값 `False`) : 사전 학습된 위치 인코딩을 보간할지 여부. logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다. **반환값:** `IdeficsCausalLMOutputWithPast` 또는 `tuple(torch.Tensor)` `IdeficsCausalLMOutputWithPast` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성(`None`)과 입력에 따라 다양한 요소를 포함합니다. [IdeficsForVisionText2Text](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsForVisionText2Text)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다. `Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다. - **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용). - **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수). - **cache** (`Cache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. 순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `cache` 참조). - **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.Tensor)`, *선택*) -- `torch.Tensor`의 튜플 (이미지 임베딩의 출력을 위한 하나, `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states는 비전 인코더, 그리고 선택적으로 퍼셉터에 의해 생성된 모델의 출력입니다 예: ```python >>> from transformers import AutoProcessor, IdeficsForVisionText2Text >>> model = IdeficsForVisionText2Text.from_pretrained("HuggingFaceM4/idefics-9b") >>> processor = AutoProcessor.from_pretrained("HuggingFaceM4/idefics-9b") >>> dogs_image_url_1 = "https://huggingface.co/datasets/hf-internal-testing/fixtures_nlvr2/raw/main/image1.jpeg" >>> dogs_image_url_2 = "https://huggingface.co/datasets/hf-internal-testing/fixtures_nlvr2/raw/main/image2.jpeg" >>> prompts = [ ... [ ... "User:", ... dogs_image_url_1, ... "Describe this image.\nAssistant: An image of two dogs.\n", ... "User:", ... dogs_image_url_2, ... "Describe this image.\nAssistant:", ... ] ... ] >>> inputs = processor(prompts, return_tensors="pt") >>> generate_ids = model.generate(**inputs, max_new_tokens=6) >>> processor.batch_decode(generate_ids, skip_special_tokens=True) ``` ## IdeficsImageProcessor[[transformers.IdeficsImageProcessor]] #### transformers.IdeficsImageProcessor[[transformers.IdeficsImageProcessor]] ```python transformers.IdeficsImageProcessor(**kwargs: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/image_processing_idefics.py#L52) **매개변수:** 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*, 기본값 `{'height' : 224, 'width': 224}`): 모델에 대한 최대 입력 차원을 설명합니다. 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*, 기본값 `3`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `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.48145466, 0.4578275, 0.40821073]`) : 정규화에 사용할 이미지 평균입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[0.26862954, 0.26130258, 0.27577711]`) : 정규화에 사용할 이미지 표준 편차입니다. `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*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. transform (`Callable`, *kwargs*, *선택 사항*, 기본값은 `None`) : 학습을 위해 단일 이미지를 받는 사용자 정의 변환 함수를 전달할 수 있습니다. 예를 들어, `torchvision.Compose`를 사용하여 여러 변환을 조합할 수 있습니다. `None`인 경우 - 추론 모드로 간주됩니다 - 이미지에는 추론 전용 변환 프리셋이 적용됩니다. image_size (`int`, *kwargs*, *선택 사항*, 기본값은 `self.image_size`) : 이미지 크기로 리사이즈합니다. 이는 `size`의 하위 호환성 별칭입니다. 값이 제공되면 `size`를 `{"height": image_size, "width": image_size}`로 설정하여 `size`를 덮어씁니다. image_num_channels (`int`, *kwargs*, *선택 사항*, 기본값 `3`) : 이미지의 채널 수. IdeficsImageProcessor 이미지 프로세서를 생성합니다. #### preprocess[[transformers.IdeficsImageProcessor.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: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/image_processing_idefics.py#L71) **매개변수:** 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*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. transform (`Callable`, *kwargs*, *선택 사항*, 기본값은 `None`) : 학습을 위해 단일 이미지를 받는 사용자 정의 변환 함수를 전달할 수 있습니다. 예를 들어, `torchvision.Compose`를 사용하여 여러 변환을 조합할 수 있습니다. `None`인 경우 - 추론 모드로 간주됩니다 - 이미지에는 추론 전용 변환 프리셋이 적용됩니다. image_size (`int`, *kwargs*, *선택 사항*, 기본값은 `self.image_size`) : 이미지 크기로 리사이즈합니다. 이는 `size`의 하위 호환성 별칭입니다. 값이 제공되면 `size`를 `{"height": image_size, "width": image_size}`로 설정하여 `size`를 덮어씁니다. image_num_channels (`int`, *kwargs*, *선택 사항*, 기본값 `3`) : 이미지의 채널 수. **반환값:** `TensorType | BatchFeature` ## IdeficsImageProcessorPil[[transformers.IdeficsImageProcessorPil]] #### transformers.IdeficsImageProcessorPil[[transformers.IdeficsImageProcessorPil]] ```python transformers.IdeficsImageProcessorPil(**kwargs: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/image_processing_pil_idefics.py#L51) **매개변수:** 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*, 기본값 `{'height' : 224, 'width': 224}`): 모델에 대한 최대 입력 차원을 설명합니다. 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*, 기본값 `3`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `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.48145466, 0.4578275, 0.40821073]`) : 정규화에 사용할 이미지 평균입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다. image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[0.26862954, 0.26130258, 0.27577711]`) : 정규화에 사용할 이미지 표준 편차입니다. `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*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. transform (`Callable`, *kwargs*, *선택 사항*, 기본값은 `None`) : 학습을 위해 단일 이미지를 받는 사용자 정의 변환 함수를 전달할 수 있습니다. 예를 들어, `torchvision.Compose`를 사용하여 여러 변환을 조합할 수 있습니다. `None`인 경우 - 추론 모드로 간주됩니다 - 이미지에는 추론 전용 변환 프리셋이 적용됩니다. image_size (`int`, *kwargs*, *선택 사항*, 기본값은 `self.image_size`) : 이미지 크기로 리사이즈합니다. 이는 `size`의 하위 호환성 별칭입니다. 값이 제공되면 `size`를 `{"height": image_size, "width": image_size}`로 설정하여 `size`를 덮어씁니다. image_num_channels (`int`, *kwargs*, *선택 사항*, 기본값 `3`) : 이미지의 채널 수. IdeficsImageProcessor 이미지 프로세서를 생성합니다. #### preprocess[[transformers.IdeficsImageProcessorPil.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: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/image_processing_pil_idefics.py#L70) **매개변수:** 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*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. transform (`Callable`, *kwargs*, *선택 사항*, 기본값은 `None`) : 학습을 위해 단일 이미지를 받는 사용자 정의 변환 함수를 전달할 수 있습니다. 예를 들어, `torchvision.Compose`를 사용하여 여러 변환을 조합할 수 있습니다. `None`인 경우 - 추론 모드로 간주됩니다 - 이미지에는 추론 전용 변환 프리셋이 적용됩니다. image_size (`int`, *kwargs*, *선택 사항*, 기본값은 `self.image_size`) : 이미지 크기로 리사이즈합니다. 이는 `size`의 하위 호환성 별칭입니다. 값이 제공되면 `size`를 `{"height": image_size, "width": image_size}`로 설정하여 `size`를 덮어씁니다. image_num_channels (`int`, *kwargs*, *선택 사항*, 기본값 `3`) : 이미지의 채널 수. ## IdeficsProcessor[[transformers.IdeficsProcessor]] #### transformers.IdeficsProcessor[[transformers.IdeficsProcessor]] ```python transformers.IdeficsProcessor(image_processor, tokenizer = None, image_size = 224, add_end_of_utterance_token = None, **kwargs) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/processing_idefics.py#L157) **매개변수:** image_processor (`IdeficsImageProcessor`) : 이미지 프로세서가 필수 입력입니다. tokenizer (`LlamaTokenizer`) : 토크나이저는 필수 입력입니다. image_size (`int`, *선택 사항*, 기본값 224) : 처리할 이미지의 크기입니다. add_end_of_utterance_token (`bool`, *선택 사항*, 기본값 None) : 텍스트에 발화 종료 토큰을 추가할지 여부. 이미지 프로세서와 토크나이저를 단일 프로세서로 감싸는 IdeficsProcessor를 생성합니다. [IdeficsProcessor](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsProcessor)는 [IdeficsImageProcessor](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsImageProcessor)와 [LlamaTokenizer](/docs/transformers/main/ko/model_doc/llama2#transformers.LlamaTokenizer)의 모든 기능을 제공합니다. 자세한 내용은 [~IdeficsImageProcessor](/docs/transformers/main/ko/model_doc/idefics#transformers.IdeficsImageProcessor)와 [~LlamaTokenizer](/docs/transformers/main/ko/model_doc/llama2#transformers.LlamaTokenizer)를 참고하세요. #### __call__[[transformers.IdeficsProcessor.__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'], list[typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]], str, list[str], list[list[str]]] = None, text: str | list[str] | list[list[str]] | list[list[list[str]]] = None, **kwargs: *) ``` [소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/idefics/processing_idefics.py#L195) **매개변수:** images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]], str, list[str], list[list[str]]]`, *선택 사항*) : 전처리할 이미지입니다. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우 `do_rescale=False`로 설정하십시오. text (`Union[str, list[str], list[list[str]], list[list[list[str]]]]`, *선택 사항*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치된 입력과의 모호성을 피하기 위해 `is_split_into_words=True`를 설정하세요. add_eos_token (`bool`, *kwargs*, *선택 사항*) : 비추천됩니다. 대신 `IdeficsProcessorKwargs.add_eos_token`을 사용하세요. 텍스트 입력의 끝에 시퀀스 종료 토큰을 추가할지 여부입니다. 활성화되면 텍스트 시퀀스의 끝을 표시하기 위해 EOS 토큰이 추가되며, 이는 생성 작업에 유용합니다. add_end_of_utterance_token (`bool`, *kwargs*, *선택 사항*) : 비추천됩니다. 대신 `IdeficsProcessorKwargs.add_end_of_utterance_token`을 사용하세요. 대화 컨텍스트에서 사용자 메시지의 끝을 표시하기 위해 발화 종료 토큰을 추가할지 여부입니다. 이 토큰은 모델이 다중 턴 대화에서 서로 다른 발화를 구별하는 데 도움이 되며, 채팅 기반 모델에서 특히 중요합니다. return_mm_token_type_ids (`bool`, *kwargs*) : 멀티모달 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부. return_text_replacement_offsets (`bool`, *kwargs*) : 각 멀티모달 플레이스홀더 및 그 대체 문자열의 문자 오프셋을 반환할지 여부. add_eos_token (`bool`, *kwargs*, *선택 사항*, 기본값 `False`) : 텍스트 입력의 끝에 시퀀스 종료 토큰을 추가할지 여부입니다. 활성화되면 텍스트 시퀀스의 끝을 표시하기 위해 EOS 토큰이 추가되며, 이는 생성 작업에 유용합니다. add_end_of_utterance_token (`bool`, *kwargs*, *선택*) : 대화 컨텍스트에서 사용자 메시지의 끝을 표시하기 위해 발화 종료(end-of-utterance) 토큰을 추가할지 여부입니다. 이 토큰은 모델이 다중 턴 대화에서 서로 다른 발화를 구별하는 데 도움이 되며, 채팅 기반 모델에서 특히 중요합니다. `None`인 경우, 토크나이저가 해당 토큰으로 학습된 경우에만 토큰이 추가됩니다. return_tensors (`str` 또는 [TensorType](/docs/transformers/main/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다: - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다. - ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요. **반환값:** `a dict with entries` `input_ids`, `attention_mask`, `pixel_values`, `image_attention_mask`는 `model.generate`에 직접 전달할 수 있습니다 상세 설명: `text`의 각 항목은 그대로 전달되는 텍스트이거나 처리될 이미지입니다. 이미지는 이미지 객체(`PIL.Image`)이거나 이미지를 가져올 수 있는 url일 수 있습니다. 프로세서가 이미지를 만나면 프롬프트에 `` 항목을 삽입합니다. 예: ```python checkpoint = "HuggingFaceM4/idefics-9b" processor = AutoProcessor.from_pretrained(checkpoint) url = "https://hips.hearstapps.com/hmg-prod/images/cute-photos-of-cats-in-grass-1593184777.jpg" img = processor.image_processor.fetch_images([url])[0] prompts = [ "User:", img, "Describe this image.\nAssistant: An image of two kittens in grass.\n", "User:", "https://hips.hearstapps.com/hmg-prod/images/dog-puns-1581708208.jpg", "Describe this image.\nAssistant:", ] inputs = processor(text=prompts, return_tensors="pt") generated_ids = model.generate(**inputs, max_length=100) generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0] ``` 이 예제에서 `prompts`는 다음과 같이 변환됩니다: ``` User:Describe this image. Assistant: An image of two kittens in grass. User:Describe this image. Assistant:' ``` 두 이미지는 [IdeficsImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) 메서드를 통해 처리되어 반환 값의 `pixel_values` 딕셔너리 항목에 저장됩니다. 이 예제는 이미지가 객체 또는 텍스트 URL로 전달될 수 있음을 보여줍니다. 첫 번째 이미지는 객체로, 두 번째 이미지는 URL로 전달되는 것을 확인할 수 있습니다. 트레이닝을 수행하려면: ```python image_transform = transforms.Compose( [ transforms.RandomResizedCrop( (w, h), scale=(0.9, 1.0), interpolation=transforms.InterpolationMode.BICUBIC ), transforms.ToTensor(), transforms.Normalize(mean=self.image_mean, std=self.image_std), ] ) inputs = processor(text=prompts, transform=image_transform, return_tensors="pt") ``` 프롬프트 생성 디버깅을 돕기 위해 `debug=True`를 활성화하면 어떤 일이 일어나는지 확인할 수 있습니다.