Transformers documentation
Feature extractor
Feature extractor
Feature extractor는 오디오 모델의 입력 특징을 준비하는 역할을 담당합니다. 여기에는 시퀀스에서 특징을 추출하는 작업, 예를 들어 오디오 파일을 전처리하여 Log-Mel Spectrogram 특징을 생성하는 작업, 그리고 NumPy 및 PyTorch 텐서로 변환하는 작업이 포함됩니다.
FeatureExtractionMixin
FeatureExtractionMixin은 시퀀스 및 오디오 피처 추출기의 저장/로드 기능을 제공하기 위해 사용되는 피처 추출 믹스인입니다.
from_pretrained
< source >( 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의 모델 저장소에 호스팅된 사전 학습된 feature_extractor의 model id입니다.
- a path to a directory containing a feature extractor file saved using the
save_pretrained() method, e.g.,
./my_model_directory/. - 저장된 feature extractor JSON 파일의 경로, 예:
./my_model_directory/preprocessor_config.json.
- cache_dir (
str또는os.PathLike, 선택 사항) — 표준 캐시를 사용하지 않을 경우, 다운로드한 사전 학습된 모델의 feature extractor를 캐시할 디렉터리의 경로입니다. - force_download (
bool, 선택 사항, 기본값False) — 캐시된 버전이 존재하더라도 feature extractor 파일을 (재)다운로드를 강제하고 캐시된 버전을 덮어쓸지 여부. - 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 기반 시스템을 사용하므로,revision은 git에서 허용하는 모든 식별자, 즉 브랜치 이름, 태그 이름 또는 커밋 ID가 될 수 있습니다.
피처 추출기, 예를 들어 SequenceFeatureExtractor의 파생 클래스에서 FeatureExtractionMixin의 유형을 인스턴스화합니다.
예:
# We can't instantiate directly the base class *FeatureExtractionMixin* nor *SequenceFeatureExtractor* so let's show the examples on a
# derived class: *Wav2Vec2FeatureExtractor*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
"facebook/wav2vec2-base-960h"
) # Download feature_extraction_config from huggingface.co and cache.
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
"./test/saved_model/"
) # E.g. feature_extractor (or model) was saved using *save_pretrained('./test/saved_model/')*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained("./test/saved_model/preprocessor_config.json")
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
"facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False
)
assert feature_extractor.return_attention_mask is False
feature_extractor, unused_kwargs = Wav2Vec2FeatureExtractor.from_pretrained(
"facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False, return_unused_kwargs=True
)
assert feature_extractor.return_attention_mask is False
assert unused_kwargs == {"foo": False}save_pretrained
< source >( 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 디렉토리에 feature_extractor 객체를 저장하여 from_pretrained() 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.
SequenceFeatureExtractor
클래스 transformers.SequenceFeatureExtractor
< source >( feature_size: intsampling_rate: intpadding_value: float**kwargs )
이것은 음성 인식을 위한 일반적인 특징 추출 클래스입니다.
패딩
< source >( processed_features: transformers.feature_extraction_utils.BatchFeature | list[transformers.feature_extraction_utils.BatchFeature] | dict[str, transformers.feature_extraction_utils.BatchFeature] | dict[str, list[transformers.feature_extraction_utils.BatchFeature]] | list[dict[str, transformers.feature_extraction_utils.BatchFeature]]padding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Falsepad_to_multiple_of: int | None = Nonereturn_attention_mask: bool | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None )
매개변수
- processed_features (BatchFeature, 의 목록 BatchFeature,
dict[str, list[float]],dict[str, list[list[float]]또는list[dict[str, list[float]]]) — 처리된 입력입니다. 단일 입력(BatchFeature 또는dict[str, list[float]]) 또는 입력 값/벡터의 배치( BatchFeature, dict[str, list[list[float]]] 또는 list[dict[str, list[float]]]) 이므로 이 메서드를 전처리 단계와 PyTorch Dataloader의 collate 함수에서 모두 사용할 수 있습니다.list[float]대신 텐서(numpy 배열 또는 PyTorch 텐서)를 사용할 수 있으며, 반환 타입은 위의 참고 사항을 참조하세요. - padding (
bool,str또는 PaddingStrategy, 선택 사항, 기본값은True) — 모델의 패딩 방향과 패딩 인덱스에 따라 반환된 시퀀스에 적용할 패딩 전략을 다음 중 선택합니다: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, 선택 사항) — 설정하면 시퀀스를 제공된 값의 배수로 패딩합니다.이 기능은 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용하며, 이는 compute capability가
>= 7.5(Volta)인 하드웨어나, 시퀀스 길이가 128의 배수일 때 성능 향상을 얻는 TPU에서 해당됩니다. - return_attention_mask (
bool, 선택 사항) — attention mask를 반환할지 여부입니다. 기본값을 그대로 두면 해당 feature_extractor의 기본 설정에 따라 attention mask를 반환합니다. - return_tensors (
str또는 TensorType, 선택 사항) — 설정된 경우, Python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': Numpynp.ndarray객체를 반환합니다.
입력 값/입력 벡터 또는 배치의 입력 값/입력 벡터를 사전 정의된 길이 또는 배치 내 최대 시퀀스 길이까지 패딩합니다.
패딩 방향(left/right) 패딩 값은 피처 추출기 수준에서(self.padding_side, self.padding_value를 사용하여) 정의됩니다.
processed_features로 전달된 값이 numpy 배열 또는 PyTorch 텐서의 딕셔너리인 경우,return_tensors로 다른 텐서 유형을 지정하지 않는 한 결과도 동일한 유형을 사용합니다. PyTorch 텐서의 경우, 텐서의 특정 디바이스가 손실됩니다.
BatchFeature
class transformers.BatchFeature
< source >( data: dict[str, typing.Any] | None = Nonetensor_type: None | str | transformers.utils.generic.TensorType = Noneskip_tensor_conversion: list[str] | set[str] | None = None )
매개변수
- data (
dict, 선택 사항) — call/pad 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘input_values’, ‘attention_mask’, 등). - tensor_type (
Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다. - skip_tensor_conversion (
list[str]또는set[str], 선택 사항) —tensor_type가 지정된 경우에도 텐서로 변환하지 않아야 하는 키의 목록 또는 집합.
pad() 및 특징 추출기 전용 __call__ 메서드의 출력을 보유합니다.
이 클래스는 python 딕셔너리에서 파생되어 딕셔너리로 사용할 수 있습니다.
convert_to_tensors
< source >( tensor_type: str | transformers.utils.generic.TensorType | None = Noneskip_tensor_conversion: list[str] | set[str] | None = None )
매개변수
- tensor_type (
str또는 TensorType, 선택 사항) — 사용할 텐서의 유형입니다.str인 경우, TensorType 열거형의 값 중 하나여야 합니다.None인 경우, 수정이 수행되지 않습니다. - skip_tensor_conversion (
list[str]또는set[str], 선택 사항) —tensor_type가 지정된 경우에도 텐서로 변환하지 않아야 하는 키의 목록 또는 집합.
내부 내용을 텐서로 변환합니다.
Note: 배열과 유사한 구조가 없는 값(예: 문자열, 딕셔너리, 문자열 목록)은 자동으로 건너뛰며 텐서로 변환되지 않습니다. 불규칙한 배열(길이가 서로 다른 배열의 목록)은 여전히 변환을 시도하지만, 변환 과정에서 오류가 발생할 수 있습니다.
(으)로
< source >( *args**kwargs ) → BatchFeature
v.to(*args, **kwargs)를 호출하여 모든 값을 device로 전송합니다 (PyTorch 전용). 이는 서로 다른 dtypes로 캐스팅하고 BatchFeature를 다른 device로 전송하는 것을 지원해야 합니다.
ImageFeatureExtractionMixin
이미지 특징을 준비하는 데 필요한 유틸리티를 포함하는 Mixin입니다.
center_crop
< source >( imagesize ) → new_image
image를 주어진 크기로 중앙 크롭합니다. 이미지가 주어진 크기로 크롭할 수 없을 정도로 작으면 패딩이 적용됩니다(따라서 반환되는 결과물은 요청한 크기를 가집니다).
PIL.Image.Image를 RGB 형식으로 변환합니다.
expand_dims
< source >( image )
2차원 image를 3차원으로 확장합니다.
flip_channel_order
< source >( image )
image의 채널 순서를 RGB에서 BGR로, 또는 그 반대로 변경합니다. PIL Image인 경우 image가 NumPy 배열로 변환됩니다.
normalize
< source >( imagemeanstdrescale = False )
매개변수
- image (
PIL.Image.Image또는np.ndarray또는torch.Tensor) — 정규화할 이미지. - mean (
list[float]또는np.ndarray또는torch.Tensor) — 정규화에 사용할 평균(채널별). - std (
list[float]또는np.ndarray또는torch.Tensor) — 정규화에 사용할 표준 편차(채널별). - rescale (
bool, 선택 사항, 기본값False) — 이미지를 0과 1 사이로 다시 스케일링할지 여부입니다. PIL 이미지가 제공되면 스케일링이 자동으로 수행됩니다.
image를 mean과 std로 정규화합니다. image가 PIL Image인 경우 NumPy 배열로 변환이 트리거됩니다.
numpy 이미지를 scale 값으로 재조정합니다
리사이즈
< source >( imagesizeresample = Nonedefault_to_square = Truemax_size = None ) → image
매개변수
- image (
PIL.Image.Image또는np.ndarray또는torch.Tensor) — 크기를 조정할 이미지. - size (
int또는tuple[int, int]) — 이미지를 리사이즈할 때 사용할 크기입니다.size가 (h, w)와 같은 시퀀스인 경우, 출력 크기가 이 값에 맞게 조정됩니다.size가 int이고default_to_square가True인 경우, 이미지는 (size, size)로 리사이즈됩니다.size가 int이고default_to_square가False인 경우, 이미지의 더 짧은 변이 이 숫자에 맞춰집니다. 즉, height > width이면 이미지는 (size * height / width, size)로 리스케일됩니다. - resample (
int, 선택 사항, 기본값PILImageResampling.BILINEAR) — 리샘플링에 사용할 필터입니다. - default_to_square (
bool, 선택 사항, 기본값True) —size가 단일 int인 경우 변환 방법입니다.True로 설정하면size가 정사각형(size,size)으로 변환됩니다.False로 설정하면 가장 작은 변만 리사이즈하는 기능과 선택적인max_size제공을 지원하는torchvision.transforms.Resize와 동일한 동작을 합니다. - max_size (
int, 선택 사항, 기본값None) — 리사이즈된 이미지의 긴 변에 허용되는 최대 크기입니다.size에 따라 리사이즈된 후 이미지의 긴 변이max_size보다 크면, 긴 변이max_size와 같아지도록 이미지가 다시 리사이즈됩니다. 그 결과size가 무시될 수 있으며, 즉 짧은 변이size보다 짧아질 수 있습니다.default_to_square가False인 경우에만 사용됩니다.
반환값
image
크기가 조정된 PIL.Image.Image.
image의 크기를 조정합니다. 입력을 PIL.Image로 변환하도록 강제합니다.
rotate
< source >( imageangleresample = Noneexpand = 0center = Nonetranslate = Nonefillcolor = None ) → image
image의 회전된 복본을 반환합니다. 이 메서드는 image의 복본을 반환하며, 주어진 각도만큼 중심을 기준으로 반시계 방향으로 회전합니다.
to_numpy_array
< source >( imagerescale = Nonechannel_first = True )
image를 numpy 배열로 변환합니다. 필요에 따라 재스케일링하고 채널 차원을 첫 번째 차원으로 배치합니다.
to_pil_image
< source >( imagerescale = None )
image를 PIL Image로 변환합니다. 필요에 따라 크기를 다시 조정하고 채널 차원을 마지막 축으로 되돌립니다.