프로세서

멀티모달 프로세서

멀티모달 모델은 텍스트, 비전, 오디오 등 여러 모달리티의 데이터를 인코딩하거나 디코딩하는 객체를 필요로 합니다. 이는 프로세서(processor)라는 객체가 담당하며, 토크나이저(텍스트 모달리티용), 이미지 프로세서(비전용), 피처 엑스트랙터(오디오용)와 같은 두 개 이상의 처리 객체를 하나로 묶어 제공합니다.

이 프로세서들은 저장 및 로드 기능을 구현하는 다음 기본 클래스를 상속합니다:

클래스 transformers.ProcessorMixin

< source >

( *args**kwargs )

이것은 모든 프로세서 클래스에 저장/로드 기능을 제공하기 위해 사용되는 믹스인입니다.

call

< source >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: 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] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

매개변수

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로 설정하십시오.
audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], 선택 사항) — 준비할 오디오 또는 오디오 배치입니다. 각 오디오는 NumPy 배열 또는 PyTorch 텐서일 수 있습니다. NumPy 배열/PyTorch 텐서의 경우, 각 오디오의 shape은 (C, T)여야 하며, 여기서 C는 채널 수, T는 오디오의 샘플 길이입니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.
**kwargs (ProcessingKwargs, 선택) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

prepare_inputs_layout

< source >

처리 전에 입력을 정규화하고 사전 가져오기(prefetch)합니다. 멀티모달 프로세서의 경우 텍스트를 리스트로 감싸고, URL이 제공된 경우 원격 이미지와 오디오를 가져오며, 오디오가 올바르게 배치(batch)되도록 보장합니다. 정규화된 (images, text, videos, audio) 튜플을 반환합니다.

validate_inputs

< source >

적어도 하나의 입력이 제공되고, 더 이상 사용되지 않는 키워드 인수가 사용되지 않는지 검증합니다. 그렇지 않으면 ValueError를 발생시킵니다.

processor가 입력 인자에 대한 추가 검증이 필요한 경우 오버라이드합니다.

get_text_with_replacements

< source >

( text: listimages_replacements: list = []videos_replacements: list = []audio_replacements: list = [] ) → tuple[list[str], list[dict[str, Any]]]

매개변수

text (list[str]) — 원시 텍스트 문자열 배치로, 각 문자열에는 멀티모달 플레이스홀더 토큰이 포함될 수 있습니다. 주의: 이 값은 인플레이스(in-place)로 수정된 후 반환됩니다.
images_replacements (list[str], optional, 기본값 []) — 배치 내에서 이미지가 나타나는 순서대로 각 이미지에 대한 확장된 치환 문자열입니다. self._process_images에서 생성됩니다.
videos_replacements (list[str], 선택 사항, 기본값 []) — 각 비디오에 대한 확장된 치환 문자열입니다. self._process_videos에서 생성됩니다.
audio_replacements (list[str], optional, 기본값 []) — 각 오디오 입력에 대한 확장된 치환 문자열입니다. self._process_audio에서 생성됩니다.

반환값

tuple[list[str], list[dict[str, Any]]]

다음의 튜플:

모든 플레이스홀더 토큰이 확장된 수정된 text 배치입니다.
batch_replacement_offsets: 배치 항목당 하나의 항목이며, 각 항목은 다음 키를 가진 딕셔너리의 리스트입니다:
“type” (str): 모달리티 이름 — “image”, “video” 또는 “audio”
“span” (tuple[int, int]): 플레이스홀더 토큰의 원래 (start, end) 문자 오프셋
“new_span” (tuple[int, int]): 확장된 문자열에서 플레이스홀더의 (start, end) 오프셋
“text” (str): 일치한 원래의 플레이스홀더 토큰 문자열
“replacement” (str): 대체된 문자열

배치된 텍스트 문자열에서 멀티모달 플레이스홀더 토큰을 확장된 표현으로 대체하고, 수정된 텍스트와 오프셋 메타데이터를 함께 반환합니다.

이 메서드는 멀티모달 입력에 대한 텍스트 측 전처리 단계의 핵심입니다. 배치 내 각 텍스트를 스캔하여 특수 토큰(이미지, 비디오, 오디오)을 찾은 뒤, self.replace_image_token / self.replace_video_token / self.replace_audio_token에서 생성된 사전 계산된 치환 문자열로 순서대로 대체합니다. 치환은 각 모달리티의 리스트에서 순차적으로 소비되므로, 예를 들어 self.image_token의 i번째 출현은 images_replacements[i]로 대체됩니다.

플레이스홀더 토큰을 사용하는 새로운 멀티모달 프로세서를 추가하려면, 입력 텍스트에 임베드되고 플레이스홀더로 사용되어 여러 번 반복되는 동일한 토큰인 올바른 self.image_token을 정의해야 합니다. 그런 다음 self.replace_image_token을 오버라이드하여 인덱스 i에 해당하는 이미지에 대한 올바른 치환 문자열을 반환하도록 해야 합니다. 다른 모든 지원되는 모달리티도 마찬가지입니다.

create_mm_token_type_ids

< source >

( input_ids: list ) → list[list[int]]

매개변수

input_ids (list[list[int]]) — 토큰 ID 시퀀스의 배치입니다. 패딩이 되지 않은(길이 불균일) 상태일 수 있으므로, 텐서나 균일한 모양의 배열이 아닌 일반 Python 리스트의 리스트가 기대됩니다.

반환값

list[list[int]]

input_ids와 동일한 구조의 목록으로, 각 정수는 해당 토큰의 모달리티 유형 ID입니다.

token_id 시퀀스 배치에 대해 토큰별 모달리티 유형 ID를 생성합니다.

각 위치에는 해당 위치가 어떤 모달리티에 속하는지를 나타내는 정수가 할당됩니다: 일반 텍스트는 0, 이미지 토큰은 1, 비디오 토큰은 2, 오디오 토큰은 3입니다. 소속은 self.image_token_ids, self.video_token_ids, self.audio_token_ids와 비교하여 결정됩니다.

apply_chat_template

< source >

( conversation: list[dict[str, str]] | list[list[dict[str, str]]]chat_template: str | None = Nonetools: list[dict] | None = Nonedocuments: list[dict[str, str]] | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsereturn_assistant_tokens_mask: bool = Falsetokenize: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = 'auto'return_dict: bool = Falseload_audio_from_video: bool = Falseprocessor_kwargs: dict | None = None**kwargs )

매개변수

conversation (Union[list[Dict, [str, str]], list[list[dict[str, str]]]]) — 포맷할 대화입니다.
chat_template (Optional[str], 선택) — 대화를 포맷팅하는 데 사용할 Jinja 템플릿입니다. 제공되지 않으면 토크나이저의 chat template이 사용됩니다.

토크나이저의 apply_chat_template 메서드와 유사하게, 이 메서드는 입력 대화에 Jinja 템플릿을 적용하여 이를 단일 토큰화 가능한 문자열로 변환합니다.

입력은 각 메시지 콘텐츠가 텍스트와 선택적으로 이미지 또는 비디오 입력으로 구성된 리스트인 다음 형식으로 예상됩니다. return_dict=True인 경우, pixel_values를 형성하는 데 사용되는 이미지, 비디오, URL 또는 로컬 경로를 제공할 수도 있습니다. 제공하지 않으면 포맷된 텍스트만, 선택적으로 토큰화된 텍스트만 반환됩니다.

conversation = [ { “role”: “user”, “content”: [ {“type”: “image”, “url”: “https://www.ilankelman.org/stopsigns/australia.jpg”}, {“type”: “text”, “text”: “Please describe this image in detail.”}, ], }, ]

kwargs 처리

Processor의 __call__ 메서드는 모달리티별로 정리된 키워드 인수를 받습니다. 다음 TypedDict 클래스는 각 모달리티에 사용할 수 있는 키워드 인수를 정의합니다. 모델별 Processor는 이 클래스를 서브클래스로 상속하여 필드를 추가하거나 재정의할 수 있습니다.

class transformers.ProcessingKwargs

< source >

( )

프로세서에 전달되는 kwargs를 위한 베이스 클래스입니다. 모델에 베이스 클래스에 없는 특정 kwargs가 있거나 기존 키의 기본값이 있는 경우, 해당 모델은 ProcessingKwargs를 상속하는 자체 ModelProcessorKwargs 클래스를 가져야 하며, 이를 통해 다음을 제공해야 합니다: 1) 입력을 처리하는 데 이 모델이 요구하는 추가적인 타입 지정 키. 2) _defaults 속성 아래에 기존 키의 기본값. 타입 힌팅이 올바르게 수행되도록 새로운 키는 다음과 같이 정의해야 합니다.

# adding a new image kwarg for this model
class ModelImagesKwargs(ImagesKwargs, total=False):
    new_image_kwarg: Optional[bool]

class ModelProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: ModelImagesKwargs
    _defaults = {
        "images_kwargs: {
            "new_image_kwarg": False,
        }
        "text_kwargs": {
            "padding": "max_length",
        },
    }

Python 3.8 호환성을 위해, 이 클래스를 상속받아 kwargs 중 하나를 재정의하는 경우,

annotations 사전은 수동으로 업데이트해야 합니다. 방법은 다음과 같습니다:

class CustomProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: CustomImagesKwargs

CustomProcessorKwargs.__annotations__["images_kwargs"] = CustomImagesKwargs  # python 3.8 compatibility

클래스 transformers.TextKwargs

< source >

( )

매개변수

add_special_tokens (bool, 선택 사항) — 시퀀스를 인코딩할 때 특수 토큰을 추가할지 여부.
padding (bool, str 또는 PaddingStrategy, 선택 사항) — 패딩을 활성화하고 제어합니다.
truncation (bool, str 또는 TruncationStrategy, 선택 사항) — 잘라내기를 활성화하고 제어합니다.
max_length (int, 선택 사항) — truncation/padding 파라미터 중 하나로 사용할 최대 길이를 제어합니다.
stride (int, 선택 사항) — 설정된 경우, 잘려 나간 시퀀스의 끝부분에 있는 일부 토큰이 넘친 토큰에 포함됩니다.
is_split_into_words (bool, 선택) — 입력이 이미 사전 토큰화되어 있는지 여부입니다.
pad_to_multiple_of (int, 선택 사항) — 설정된 경우, 제공된 값의 배수로 시퀀스를 패딩합니다.
return_token_type_ids (bool, 선택) — 토큰 유형 ID를 반환할지 여부.
return_attention_mask (bool, 선택 사항) — attention mask를 반환할지 여부.
return_overflowing_tokens (bool, 선택) — 넘치는 토큰 시퀀스를 반환할지 여부.
return_special_tokens_mask (bool, 선택 사항) — 특별 토큰 마스크 정보를 반환할지 여부.
return_offsets_mapping (bool, 선택 사항) — 각 토큰에 대해 (char_start, char_end)를 반환할지 여부.
return_length (bool, 선택 사항) — 인코딩된 입력의 길이를 반환할지 여부입니다.
verbose (bool, 선택) — 추가 정보와 경고를 출력할지 여부.
padding_side (str, 선택 사항) — 패딩이 적용될 쪽을 지정합니다.
return_mm_token_type_ids (bool, 선택 사항) — mm 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부입니다.
return_text_replacement_offsets (bool, 선택) — 각 mm 플레이스홀더와 그 대체 문자열에 대한 문자 오프셋을 반환할지 여부입니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.

텍스트 처리를 위한 키워드 인자입니다. 확장된 문서에 대해서는 tokenization_utils_base의 메서드 및 관련 docstring을 확인하세요.

class transformers.ImagesKwargs

< source >

( )

매개변수

do_convert_rgb (bool) — 이미지를 RGB 형식으로 변환할지 여부.
do_resize (bool, 선택 사항) — 이미지를 리사이즈할지 여부.
size (dict[str, int], 선택 사항) — 지원되는 크기 사전 중 하나를 사용하여 리사이즈합니다. 픽셀 영역 범위는 {"min_pixels": int, "max_pixels": int}을 사용합니다.
default_to_square (bool, 선택 사항, 기본값 self.default_to_square) — size가 int인 경우 리사이즈 시 정사각형으로 기본 설정할지 여부.
crop_size (dict[str, int], 선택) — 중앙 크롭을 적용할 때 원하는 출력 크기입니다.
resample (PILImageResampling, 선택 사항) — 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다.
do_rescale (bool, 선택) — 지정한 rescale_factor로 이미지를 다시 스케일링할지 여부.
rescale_factor (int 또는 float, 선택) — 이미지를 리스케일할 때 사용할 스케일 팩터입니다.
do_normalize (bool, 선택 사항) — 이미지를 정규화할지 여부입니다.
image_mean (float or list[float] or tuple[float, float, float], optional) — 이미지를 정규화할 때 사용할 평균값입니다.
image_std (float 또는 list[float] or tuple[float, float, float], 선택) — 이미지를 정규화할 때 사용할 표준 편차.
do_pad (bool, 선택 사항) — 배치 내 이미지를 패딩할지 여부.
pad_size (dict[str, int], 선택) — 이미지를 패딩할 크기 {"height": int, "width" int}.
do_center_crop (bool, 선택) — 이미지를 중앙으로 크롭할지 여부.
data_format (ChannelDimension 또는 str, 선택 사항) — 출력 이미지의 채널 차원 형식입니다.
input_data_format (ChannelDimension 또는 str, 선택 사항) — 입력 이미지의 채널 차원 형식입니다.
device (Union[str, torch.Tensor], 선택 사항) — 처리할 때 사용할 디바이스(예: “cpu”, “cuda”). torchvision 백엔드에서만 관련이 있습니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.
disable_grouping (bool, 선택 사항) — 이미지를 처리할 때 모양별로 그룹화할지 여부를 지정합니다. torchvision 백엔드에서만 관련이 있습니다.
image_seq_length (int, 선택) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

이미지 처리를 위한 키워드 인자입니다. 확장된 문서에 대해서는 해당 ImageProcessor 클래스의 메서드와 docstring을 확인하세요.

class transformers.VideosKwargs

< source >

( )

매개변수

do_convert_rgb (bool) — 영상을 RGB 형식으로 변환할지 여부.
do_resize (bool) — 비디오를 리사이즈할지 여부.
size (dict[str, int], 선택 사항) — 입력의 짧은 변을 size["shortest_edge"]로 리사이즈합니다.
default_to_square (bool, 선택 사항, 기본값 self.default_to_square) — size가 int인 경우 리사이즈 시 정사각형으로 기본 설정할지 여부.
resample (PILImageResampling, 선택 사항) — 비디오를 리사이즈할 때 사용할 리샘플링 필터입니다.
do_rescale (bool, 선택 사항) — 지정한 rescale_factor로 비디오를 다시 스케일링할지 여부입니다.
rescale_factor (int 또는 float, 선택) — 비디오를 리스케일할 때 사용할 스케일 팩터입니다.
do_normalize (bool, 선택 사항) — 동영상을 정규화할지 여부입니다.
image_mean (float 또는 list[float] or tuple[float, float, float], 선택) — 비디오 정규화 시 사용할 평균값.
image_std (float 또는 list[float] or tuple[float, float, float], 선택) — 동영상을 정규화할 때 사용할 표준 편차입니다.
do_center_crop (bool, 선택) — 영상을 중앙으로 크롭할지 여부입니다.
do_pad (bool, 선택 사항) — 배치 내 이미지를 패딩할지 여부.
do_sample_frames (bool, 선택 사항) — 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지를 결정합니다.
video_metadata (Union[VideoMetadata, dict], 선택) — 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다.
num_frames (int, 선택) — do_sample_frames=True일 때 샘플링할 최대 프레임 수.
fps (int 또는 float, 선택 사항) — do_sample_frames=True일 때 초당 샘플링할 목표 프레임 수.
crop_size (dict[str, int], 선택) — 중앙 크롭을 적용할 때 원하는 출력 크기입니다.
data_format (ChannelDimension 또는 str, 선택 사항) — 출력 비디오의 채널 차원 형식입니다.
input_data_format (ChannelDimension 또는 str, 선택 사항) — 입력 비디오의 채널 차원 형식입니다.
device (Union[str, torch.Tensor], 선택 사항) — 처리할 때 사용할 디바이스(예: “cpu”, “cuda”). 빠른 이미지 처리에만 관련이 있습니다.
return_metadata (bool, 선택) — 비디오 메타데이터를 반환할지 여부를 지정합니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.

Keyword arguments for video processing.

class transformers.AudioKwargs

< source >

( )

매개변수

sampling_rate (int, 선택 사항) — raw_speech 입력이 샘플링된 샘플링 레이트입니다.
raw_speech (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — 패딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 numpy 배열, float 값의 리스트, numpy 배열의 리스트, 또는 float 값의 리스트의 리스트일 수 있습니다. 스테레오가 아닌 모노 채널 오디오여야 하며, 즉 각 타임스텝당 float 값이 하나만 있어야 합니다.
padding (bool, str 또는 PaddingStrategy, 선택 사항) — 모델의 패딩 방향과 패딩 인덱스에 따라 반환된 시퀀스를 패딩할 전략을 다음 중 선택합니다:
- True 또는 'longest': 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
- 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
- False 또는 'do_not_pad'
max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
truncation (bool, 선택) — max_length보다 긴 입력 시퀀스를 max_length로 잘라내는 truncation을 활성화합니다.
pad_to_multiple_of (int, 선택 사항) — 설정된 경우, 제공된 값의 배수로 시퀀스를 패딩합니다.
return_attention_mask (bool, 선택) — call()에서 attention_mask를 반환할지 여부.
device (str 또는 torch.device, 선택 사항) — 음성 특징을 계산할 장치(예: “cpu”, “cuda”). torch를 사용하여 특징을 계산하는 특징 추출기에만 관련됩니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.
load_audio_backend (str, 선택 사항) — apply_chat_template에서 URL/경로로 참조된 오디오를 디코딩/리샘플링하는 데 load_audio()가 사용하는 백엔드입니다. "auto", "torchcodec", "librosa", "torchaudio" 중 하나입니다.

오디오 처리를 위한 키워드 인자.

Update on GitHub

Transformers

프로세서

멀티모달 프로세서

클래스 transformers.ProcessorMixin

__call__

prepare_inputs_layout

validate_inputs

get_text_with_replacements

create_mm_token_type_ids

apply_chat_template

kwargs 처리

class transformers.ProcessingKwargs

클래스 transformers.TextKwargs

class transformers.ImagesKwargs

class transformers.VideosKwargs

class transformers.AudioKwargs

call