Transformers documentation

이미지 프로세서 유틸리티

Transformers

시작하기

Transformers 설치 빠른 시작

기본 클래스

모델

Preprocessors

추론

Pipeline API

Generate API

최적화

모델과 대화하기

서빙

학습

시작하기

커스터마이징

매개변수 효율적 미세 조정

성능

분산 학습

하드웨어

양자화

생태계 통합

리소스

API

주요 클래스

모델

내부 헬퍼

커스텀 레이어 및 유틸리티 모델 디버깅 유틸리티 파이프라인 유틸리티 토크나이저 유틸리티 Trainer 유틸리티 생성을 위한 유틸리티 이미지 프로세서 유틸리티 오디오 처리 유틸리티 일반 유틸리티 유틸리티 가져오기 시계열 유틸리티 Rotary 임베딩 유틸리티

참고

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이미지 프로세서 유틸리티

이 페이지에서는 이미지 프로세서가 사용하는 모든 유틸리티 함수, 주로 이미지를 처리하는 데 사용되는 함수형 변환을 나열합니다.

이 중 대부분은 라이브러리의 이미지 프로세서 코드를 연구할 때만 유용합니다.

이미지 변환

transformers.image_transforms.center_crop

( image: ndarraysize: tuple[int, int]data_format: str | transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None ) → np.ndarray

매개변수

image (np.ndarray) — 자를 이미지.
size (tuple[int, int]) — 잘라낸 이미지의 대상 크기입니다.
data_format (str 또는 ChannelDimension, 선택 사항) — 출력 이미지의 채널 차원 형식입니다. 다음 중 하나를 사용할 수 있습니다:
- "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
- "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지. 설정되지 않으면 입력 이미지의 추론된 형식을 사용합니다.
input_data_format (str 또는 ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 다음 중 하나를 사용할 수 있습니다:
- "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
- "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지. 설정되지 않으면 입력 이미지의 추론된 형식을 사용합니다.

반환값

np.ndarray

잘라낸 이미지.

image를 중앙 크롭을 사용하여 지정된 size로 자릅니다. 이미지가 주어진 크기로 크롭하기에 너무 작으면 패딩이 적용됩니다(따라서 반환되는 결과는 항상 size 크기입니다).

transformers.image_transforms.center_to_corners_format

( bboxes_center: TensorType )

center 형식의 바운딩 박스를 corners 형식으로 변환합니다.

center 형식: 박스의 중심 좌표와 너비, 높이 차원을 포함합니다 (center_x, center_y, width, height) corners 형식: 박스의 왼쪽 위와 오른쪽 아래 모서리의 좌표를 포함합니다 (top_left_x, top_left_y, bottom_right_x, bottom_right_y)

transformers.image_transforms.corners_to_center_format

( bboxes_corners: TensorType )

바운딩 박스를 코너 형식에서 센터 형식으로 변환합니다.

corners 형식: 박스의 왼쪽 위와 오른쪽 아래 모서리의 좌표를 포함합니다 (top_left_x, top_left_y, bottom_right_x, bottom_right_y) center 형식: 박스의 중심 좌표와 너비, 높이 차원을 포함합니다 (center_x, center_y, width, height)

transformers.image_transforms.id_to_rgb

( id_map )

고유 ID를 RGB 색상으로 변환합니다.

transformers.image_transforms.normalize

( image: ndarraymean: float | collections.abc.Collection[float]std: float | collections.abc.Collection[float]data_format: transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None )

매개변수

image (np.ndarray) — 정규화할 이미지.
mean (float 또는 Collection[float]) — 정규화에 사용할 평균입니다.
std (float 또는 Collection[float]) — 정규화에 사용할 표준 편차입니다.
data_format (ChannelDimension, 선택 사항) — 출력 이미지의 채널 차원 형식입니다. 설정되지 않은 경우 입력에서 추론된 형식을 사용합니다.
input_data_format (ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않은 경우 입력에서 추론된 형식을 사용합니다.

image를 mean과 std로 지정된 평균과 표준편차를 사용하여 정규화합니다.

image = (image - mean) / std

transformers.image_transforms.pad

( image: ndarraypadding: int | tuple[int, int] | collections.abc.Iterable[tuple[int, int]]mode: PaddingMode = <PaddingMode.CONSTANT: 'constant'>constant_values: float | collections.abc.Iterable[float] = 0.0data_format: str | transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None ) → np.ndarray

매개변수

image (np.ndarray) — 패딩할 이미지.
padding (int 또는 tuple[int, int] 또는 Iterable[tuple[int, int]]) — 높이, 너비 축의 가장자리에 적용할 패딩입니다. 다음 세 가지 형식 중 하나를 사용할 수 있습니다:
- 각 축에 대한 고유한 패드 폭 ((before_height, after_height), (before_width, after_width)).
- ((before, after),)은 높이와 폭에 대해 동일한 before와 after 패딩을 생성합니다.
- (pad,) 또는 int는 모든 축에 대해 before = after = pad 폭을 지정하는 단축형입니다.
mode (PaddingMode) — 사용할 패딩 모드입니다. 다음 중 하나를 사용할 수 있습니다:
- "constant": 상수 값으로 패딩합니다.
- "reflect": 각 축을 따라 벡터의 첫 번째 값과 마지막 값을 기준으로 벡터를 반사한 값으로 패딩합니다.
- "replicate": 각 축을 따라 배열 가장자리의 마지막 값을 복제하여 패딩합니다.
- "symmetric": 배열의 가장자리를 기준으로 벡터를 반사한 값으로 패딩합니다.
constant_values (float 또는 Iterable[float], 선택 사항) — mode가 "constant"인 경우 패딩에 사용할 값입니다.
data_format (str 또는 ChannelDimension, 선택 사항) — 출력 이미지의 채널 차원 형식입니다. 다음 중 하나를 사용할 수 있습니다:
- "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
- "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지. 설정되지 않으면 입력 이미지와 동일한 형식을 사용합니다.
input_data_format (str 또는 ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 다음 중 하나를 사용할 수 있습니다:
- "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
- "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지. 설정되지 않으면 입력 이미지의 추론된 형식을 사용합니다.

반환값

np.ndarray

패딩된 이미지.

image를 지정된 (height, width) padding과 mode로 패딩합니다.

transformers.image_transforms.rgb_to_id

( color )

RGB 색상을 고유 ID로 변환합니다.

transformers.image_transforms.rescale

( image: ndarrayscale: floatdata_format: transformers.image_utils.ChannelDimension | None = Nonedtype: dtype = <class 'numpy.float32'>input_data_format: str | transformers.image_utils.ChannelDimension | None = None ) → np.ndarray

매개변수

image (np.ndarray) — 크기를 재조정할 이미지.
scale (float) — 이미지를 다시 스케일링할 때 사용할 스케일입니다.
data_format (ChannelDimension, 선택 사항) — 이미지의 채널 차원 형식입니다. 제공되지 않으면 입력 이미지와 동일합니다.
dtype (np.dtype, 선택 사항, 기본값 np.float32) — 출력 이미지의 dtype입니다. 기본값은 np.float32입니다. feature extractor와의 하위 호환성을 위해 사용됩니다.
input_data_format (ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 제공되지 않으면 입력 이미지에서 추론됩니다.

반환값

np.ndarray

크기가 조정된 이미지.

image를 scale로 다시 스케일링합니다.

transformers.image_transforms.resize

( image: ndarraysize: tuple[int, int]resample: typing.Optional[ForwardRef('PILImageResampling')] = Nonereducing_gap: int | None = Nonedata_format: transformers.image_utils.ChannelDimension | None = Nonereturn_numpy: bool = Trueinput_data_format: str | transformers.image_utils.ChannelDimension | None = None ) → np.ndarray

매개변수

image (np.ndarray) — 크기를 조정할 이미지.
size (tuple[int, int]) — 이미지를 리사이즈할 때 사용할 크기입니다.
resample (int, 선택 사항, 기본값 PILImageResampling.BILINEAR) — 리샘플링에 사용할 필터입니다.
reducing_gap (int, 선택 사항) — 이미지를 두 단계로 리사이즈하여 최적화를 적용합니다. reducing_gap 값이 클수록 결과가 공정한 리샘플링에 더 가까워집니다. 자세한 내용은 해당 Pillow 문서를 참조하세요.
data_format (ChannelDimension, 선택 사항) — 출력 이미지의 채널 차원 형식입니다. 설정되지 않은 경우 입력에서 추론된 형식을 사용합니다.
return_numpy (bool, 선택 사항, 기본값 True) — 크기가 조정된 이미지를 numpy 배열로 반환할지 여부입니다. False인 경우 PIL.Image.Image 객체가 반환됩니다.
input_data_format (ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않은 경우 입력에서 추론된 형식을 사용합니다.

반환값

np.ndarray

크기가 조정된 이미지.

PIL 라이브러리를 사용하여 size로 지정된 (height, width) 크기로 image를 리사이즈합니다.

transformers.image_transforms.to_pil_image

( image: typing.Union[numpy.ndarray, ForwardRef('PIL.Image.Image'), ForwardRef('torch.Tensor')]do_rescale: bool | None = Noneimage_mode: str | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None ) → PIL.Image.Image

매개변수

image (PIL.Image.Image 또는 numpy.ndarray 또는 torch.Tensor) — PIL.Image 형식으로 변환할 이미지입니다.
do_rescale (bool, 선택 사항) — 스케일링 계수를 적용할지 여부(픽셀 값을 0에서 255 사이의 정수로 만들기 위함). 이미지 유형이 부동 소수점 유형이고 int로 캐스팅하면 정밀도가 손실되는 경우 기본값은 True, 그 외에는 False입니다.
image_mode (str, 선택 사항) — PIL 이미지에 사용할 모드입니다. 설정되지 않은 경우 입력 이미지 유형의 기본 모드를 사용합니다.
input_data_format (ChannelDimension, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않은 경우 입력에서 추론된 형식을 사용합니다.

반환값

PIL.Image.Image

변환된 이미지.

image를 PIL Image로 변환합니다. 필요에 따라 크기를 다시 조정하고 채널 차원을 마지막 축으로 되돌립니다.

ImageProcessingMixin

클래스 transformers.ImageProcessingMixin

( **kwargs )

ImageProcessorMixin은 시퀀스 및 이미지 특징 추출기에 저장/로드 기능을 제공하기 위해 사용되는 이미지 프로세서 믹스인입니다.

fetch_images

( image_url_or_urls: str | list[str] | list[list[str]] )

단일 URL 또는 URL 목록을 해당하는 PIL.Image 객체로 변환합니다.

단일 url이 전달되면 반환 값은 단일 객체입니다. 목록이 전달되면 객체의 목록이 반환됩니다.

from_dict

( image_processor_dict: dict[str, typing.Any]**kwargs ) → ImageProcessingMixin

매개변수

image_processor_dict (dict[str, Any]) — 이미지 프로세서 객체를 인스턴스화하는 데 사용되는 사전입니다. 이러한 사전은 사전 학습된 체크포인트에서 to_dict() 메서드를 활용하여 가져올 수 있습니다.
kwargs (dict[str, Any]) — 이미지 프로세서 객체를 초기화할 때 사용할 추가 매개변수.

반환값

ImageProcessingMixin

해당 파라미터에서 인스턴스화된 이미지 프로세서 객체입니다.

Python 매개변수 사전에서 ImageProcessingMixin의 유형을 초기화합니다.

from_json_file

( json_file: str | os.PathLike ) → A image processor of type ImageProcessingMixin

매개변수

json_file (str 또는 os.PathLike) — 파라미터를 포함하는 JSON 파일의 경로.

반환값

ImageProcessingMixin 유형의 이미지 프로세서

해당 JSON 파일에서 인스턴스화된 image_processor 객체

JSON 파일의 경로에서 매개변수를 가져와 ImageProcessingMixin 유형의 이미지 프로세서 인스턴스를 생성합니다.

from_pretrained

( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )

매개변수

pretrained_model_name_or_path (str 또는 os.PathLike) — 다음 중 하나일 수 있습니다:
- 문자열이며, huggingface.co의 모델 저장소에 호스팅된 사전 학습된 image_processor의 model id입니다.
- save_pretrained() 메서드를 사용하여 이미지 프로세서 파일을 저장한 디렉터리의 경로, 예: ./my_model_directory/.
- 저장된 이미지 프로세서 JSON 파일의 경로, 예: ./my_model_directory/preprocessor_config.json.
cache_dir (str 또는 os.PathLike, 선택 사항) — 표준 캐시를 사용하지 않을 경우, 다운로드한 사전 학습된 모델 이미지 프로세서가 캐시될 디렉터리의 경로입니다.
force_download (bool, 선택 사항, 기본값 False) — 이미지 프로세서 파일을 (재)다운로드를 강제하고, 캐시된 버전이 존재하는 경우 이를 덮어쓸지 여부.
proxies (dict[str, str], 선택) — 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. 각 요청에 프록시가 사용됩니다.
token (str 또는 bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. True이거나 지정되지 않은 경우, hf auth login 실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다.
revision (str, 선택 사항, 기본값은 "main") — 사용할 특정 모델 버전입니다. huggingface.co에서 모델과 기타 아티팩트를 저장하기 위해 git 기반 시스템을 사용하므로, 브랜치 이름, 태그 이름, 커밋 ID일 수 있습니다. 따라서 revision 은 git에서 허용하는 모든 식별자를 사용할 수 있습니다.

Hub에서 만든 pull request를 테스트하려면 revision="refs/pr/<pr_number>"를 전달할 수 있습니다.
return_unused_kwargs (bool, 선택 사항, 기본값 False) — False인 경우 이 함수는 최종 image processor 객체만 반환합니다. True인 경우 이 함수는 Tuple(image_processor, unused_kwargs)를 반환하며, 여기서 unused_kwargs는 image processor 속성이 아닌 키/값 쌍으로 구성된 딕셔너리입니다. 즉, kwargs 중 image_processor를 업데이트하는 데 사용되지 않고 무시되는 부분입니다.
subfolder (str, 선택 사항, 기본값 "") — huggingface.co의 모델 저장소에서 관련 파일이 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.
kwargs (dict[str, Any], 선택) — kwargs의 값 중 image processor 속성에 해당하는 키는 로드된 값을 덮어쓰는 데 사용됩니다. 키가 image processor 속성이 아닌 키/값 쌍에 대한 동작은 return_unused_kwargs 키워드 매개변수로 제어됩니다.

이미지 프로세서에서 ImageProcessingMixin의 인스턴스를 생성합니다.

예:

# We can't instantiate directly the base class *ImageProcessingMixin* so let's show the examples on a
# derived class: *CLIPImageProcessor*
image_processor = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32"
)  # Download image_processing_config from huggingface.co and cache.
image_processor = CLIPImageProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. image processor (or model) was saved using *save_pretrained('./test/saved_model/')*
image_processor = CLIPImageProcessor.from_pretrained("./test/saved_model/preprocessor_config.json")
image_processor = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32", do_normalize=False, foo=False
)
assert image_processor.do_normalize is False
image_processor, unused_kwargs = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert image_processor.do_normalize is False
assert unused_kwargs == {"foo": False}

get_image_processor_dict

( pretrained_model_name_or_path: str | os.PathLike**kwargs ) → tuple[Dict, Dict]

매개변수

pretrained_model_name_or_path (str 또는 os.PathLike) — 파라미터 사전(dictionary)을 가져오려는 사전 학습된 체크포인트의 식별자입니다.
subfolder (str, 선택 사항, 기본값 "") — huggingface.co의 모델 저장소에서 관련 파일이 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.
image_processor_filename (str, 선택 사항, 기본값 "config.json") — 모델 디렉터리에서 이미지 프로세서 설정에 사용할 파일 이름입니다.

반환값

tuple[Dict, Dict]

이미지 프로세서 객체를 인스턴스화하는 데 사용될 사전입니다.

pretrained_model_name_or_path에서 매개변수 사전으로 해석하여, from_dict를 사용하여 ~image_processor_utils.ImageProcessingMixin 유형의 이미지 프로세서 인스턴스를 생성하는 데 사용됩니다.

push_to_hub

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

매개변수

repo_id (str) — 이미지 프로세서를 푸시하려는 저장소의 이름입니다. 특정 조직에 푸시할 경우 조직 이름을 포함해야 합니다.
commit_message (str, 선택 사항) — 푸시할 때 커밋할 메시지입니다. 기본값은 "Upload image processor"입니다.
commit_description (str, 선택 사항) — 생성될 커밋의 설명
private (bool, 선택 사항) — 리포지토리를 비공개로 만들지 여부를 지정합니다. None(기본값)인 경우, 조직의 기본 설정이 비공개가 아닌 한 리포지토리는 공개됩니다. 리포지토리가 이미 존재하면 이 값은 무시됩니다.
token (bool 또는 str, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. True(기본값)인 경우, hf auth login 실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다.
revision (str, 선택 사항) — 업로드된 파일을 푸시할 브랜치.
create_pr (bool, 선택 사항, 기본값 False) — 업로드된 파일로 PR을 생성할지 아니면 직접 커밋할지 여부.
max_shard_size (int 또는 str, 선택 사항, 기본값 "50GB") — 모델에만 적용됩니다. 샤딩되기 전 체크포인트의 최대 크기입니다. 샤딩된 각 체크포인트의 크기는 이 크기보다 작아집니다. 문자열로 표현하는 경우, 숫자 뒤에 단위(예: "5MB")가 따라와야 합니다.
tags (list[str], 선택) — Hub에 push할 태그 목록.

이미지 프로세서 파일을 🤗 Model Hub에 업로드합니다.

예:

from transformers import AutoImageProcessor

image processor = AutoImageProcessor.from_pretrained("google-bert/bert-base-cased")

# Push the image processor to your namespace with the name "my-finetuned-bert".
image processor.push_to_hub("my-finetuned-bert")

# Push the image processor to an organization with the name "my-finetuned-bert".
image processor.push_to_hub("huggingface/my-finetuned-bert")

register_for_auto_class

( auto_class = 'AutoImageProcessor' )

매개변수

auto_class (str 또는 type, 선택 사항, 기본값 "AutoImageProcessor ") — 이 새로운 이미지 프로세서를 등록할 auto class입니다.

이 클래스를 주어진 auto 클래스에 등록합니다. 라이브러리에 이미 AutoImageProcessor와 매핑된 것이 있으므로, 이 메서드는 커스텀 이미지 프로세서에만 사용해야 합니다.

save_pretrained

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

매개변수

save_directory (str 또는 os.PathLike) — 이미지 프로세서 JSON 파일이 저장될 디렉터리입니다. (존재하지 않으면 생성됩니다.)
push_to_hub (bool, 선택 사항, 기본값 False) — 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다. repo_id를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 save_directory의 이름이 기본값으로 사용됩니다.
kwargs (dict[str, Any], 선택) — push_to_hub() 메서드에 함께 전달되는 추가 키워드 인자입니다.

save_directory 디렉토리에 이미지 프로세서 객체를 저장하여 from_pretrained() 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.

to_dict

( ) → dict[str, Any]

반환값

dict[str, Any]

이 이미지 프로세서 인스턴스를 구성하는 모든 속성의 사전입니다.

이 인스턴스를 Python 딕셔너리로 직렬화합니다.

to_json_file

( json_file_path: str | os.PathLike )

매개변수

json_file_path (str 또는 os.PathLike) — 이 image_processor 인스턴스의 매개변수가 저장될 JSON 파일의 경로입니다.

이 인스턴스를 JSON 파일로 저장합니다.

to_json_string

( ) → str

반환값

str

이 feature_extractor 인스턴스를 구성하는 모든 속성이 포함된 JSON 형식의 문자열.

이 인스턴스를 JSON 문자열로 직렬화합니다.

Update on GitHub

←생성을 위한 유틸리티 오디오 처리 유틸리티→