Hugging Face's logo

Transformers documentation

Bộ trích xuất đặc trưng

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Bộ trích xuất đặc trưng

Feature extractor chịu trách nhiệm chuẩn bị các đặc trưng đầu vào cho các mô hình âm thanh. Điều này bao gồm việc trích xuất đặc trưng từ các chuỗi, ví dụ như tiền xử lý các tệp âm thanh để tạo ra các đặc trưng Log-Mel Spectrogram, và chuyển đổi sang các tensor NumPy và PyTorch.

FeatureExtractionMixin

lớp transformers.FeatureExtractionMixin

< >

( **kwargs )

Đây là một mixin trích xuất đặc trưng được sử dụng để cung cấp chức năng lưu/tải cho các bộ trích xuất đặc trưng tuần tự và âm thanh.

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 )

Tham số

  • pretrained_model_name_or_path (str hoặc os.PathLike) — Đây có thể là:
    • một chuỗi, model id của một feature_extractor được huấn luyện trước lưu trữ trong một kho model trên huggingface.co.
    • đường dẫn đến một thư mục chứa tệp feature extractor được lưu bằng phương thức save_pretrained(), ví dụ: ./my_model_directory/.
    • đường dẫn đến tệp JSON bộ trích xuất đặc trưng đã lưu tệp, ví dụ: ./my_model_directory/preprocessor_config.json.
  • cache_dir (str hoặc os.PathLike, tùy chọn) — Đường dẫn đến thư mục mà trình trích xuất đặc trưng của mô hình được huấn luyện trước đã tải xuống sẽ được lưu đệm, nếu không sử dụng bộ lưu đệm tiêu chuẩn.
  • force_download (bool, tùy chọn, mặc định là False) — Có nên buộc (tải lại) các tệp feature extractor và ghi đè lên các phiên bản được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
  • proxies (dict[str, str], tuỳ chọn) — Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Các proxy này được sử dụng cho mỗi yêu cầu.
  • token (str hoặc bool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True, hoặc không được chỉ định, sẽ sử dụng token được tạo khi chạy hf auth login (được lưu trong ~/.huggingface).
  • revision (str, tùy chọn, mặc định là "main") — Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ hoặc id commit, vì chúng tôi sử dụng hệ thống dựa trên git để lưu trữ các mô hình và các sản phẩm khác trên huggingface.co, do đó revision có thể là bất kỳ định danh nào được git cho phép.

Tạo một kiểu FeatureExtractionMixin từ một bộ trích xuất đặc trưng, ví dụ một lớp kế thừa của SequenceFeatureExtractor.

Ví dụ:

# 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

< >

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

Tham số

  • save_directory (str hoặc os.PathLike) — Thư mục nơi tệp JSON của bộ trích xuất đặc trưng sẽ được lưu (sẽ được tạo nếu chưa tồn tại).
  • push_to_hub (bool, tùy chọn, mặc định là False) — Có đẩy mô hình của bạn lên Hugging Face model hub sau khi lưu hay không. Bạn có thể chỉ định kho lưu trữ muốn đẩy đến bằng repo_id (mặc định sẽ là tên của save_directory trong namespace của bạn).
  • kwargs (dict[str, Any], tùy chọn) — Các đối số từ khóa bổ sung được truyền đến phương thức push_to_hub().

Lưu đối tượng feature_extractor vào thư mục save_directory để có thể nạp lại bằng phương thức lớp from_pretrained().

SequenceFeatureExtractor

lớp transformers.SequenceFeatureExtractor

< >

( feature_size: intsampling_rate: intpadding_value: float**kwargs )

Tham số

  • feature_size (int) — Kích thước chiều của các đặc trưng đã trích xuất.
  • sampling_rate (int) — Tần số lấy mẫu (tính bằng hertz (Hz)) mà các tệp âm thanh cần được số hóa.
  • padding_value (float) — Giá trị được sử dụng để điền vào các giá trị / vector đệm.

Đây là một lớp trích xuất đặc trưng chung cho nhận dạng giọng nói.

pad

< >

( 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 )

Tham số

  • processed_features (BatchFeature, danh sách BatchFeature, dict[str, list[float]], dict[str, list[list[float]] hoặc list[dict[str, list[float]]]) — Đầu vào đã xử lý. Có thể đại diện cho một đầu vào (BatchFeature hoặc dict[str, list[float]]) hoặc một batch các giá trị / vector đầu vào (danh sách BatchFeature, dict[str, list[list[float]]] hoặc list[dict[str, list[float]]]) để bạn có thể sử dụng phương thức này trong cả tiền xử lý và trong hàm collate của PyTorch Dataloader.

    Thay vì list[float], bạn có thể dùng tensor (mảng numpy hoặc tensor PyTorch), xem ghi chú phía trên về kiểu trả về.

  • padding (bool, str hoặc PaddingStrategy, tùy chọn, mặc định là True) — Chọn một chiến lược để đệm các chuỗi trả về (theo phía đệm và chỉ số đệm của mô hình) trong số các lựa chọn sau:
    • True hoặc 'longest': Lấp đầy đến trình tự dài nhất trong lô (hoặc không lấp đầy nếu chỉ có một trình tự được cung cấp).
    • 'max_length': Đệm (pad) đến độ dài tối đa được chỉ định bằng tham số max_length hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp.
    • False hoặc 'do_not_pad' (mặc định): Không đệm (tức là có thể xuất ra một lô với các chuỗi có độ dài khác nhau).
  • max_length (int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên).
  • truncation (bool) — Bật cắt để giảm các chuỗi đầu vào dài hơn max_length xuống còn max_length.
  • pad_to_multiple_of (int, tuỳ chọn) — Nếu được đặt, chuỗi sẽ được đệm (pad) đến bội số của giá trị được cung cấp.

    Điều này đặc biệt hữu ích để cho phép sử dụng Tensor Cores trên phần cứng NVIDIA có khả năng tính toán >= 7.5 (Volta), hoặc trên TPU, nơi mà việc có độ dài chuỗi là bội số của 128 sẽ mang lại lợi ích.

  • return_attention_mask (bool, tuỳ chọn) — Có trả về attention mask hay không. Nếu để mặc định, sẽ trả về attention mask theo mặc định của feature_extractor cụ thể.

    Mặt nạ chú ý là gì?

  • return_tensors (str hoặc TensorType, tùy chọn) — Nếu được đặt, sẽ trả về tensor thay vì danh sách các số nguyên Python. Các giá trị chấp nhận được là:
    • 'pt': Trả về các đối tượng torch.Tensor của PyTorch.
    • 'np': Trả về các đối tượng Numpy np.ndarray.

Đệm các giá trị đầu vào / vector đầu vào hoặc một lô các giá trị đầu vào / vector đầu vào lên đến độ dài định trước hoặc độ dài chuỗi tối đa trong lô.

Bên đệm (trái/phải) các giá trị đệm được định nghĩa ở cấp bộ trích xuất đặc trưng (với self.padding_side, self.padding_value)

Nếu processed_features được truyền vào là từ điển các mảng numpy hoặc tensor PyTorch, kết quả sẽ sử dụng cùng loại đó, trừ khi bạn cung cấp một loại tensor khác bằng return_tensors. Trong trường hợp tensor PyTorch, bạn sẽ mất thông tin về thiết bị cụ thể của các tensor đó.

BatchFeature

lớp transformers.BatchFeature

< >

( data: dict[str, typing.Any] | None = Nonetensor_type: None | str | transformers.utils.generic.TensorType = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

Tham số

  • data (dict, tùy chọn) — Từ điển chứa các danh sách/mảng/tensor được trả về bởi các phương thức call/pad (‘input_values’, ‘attention_mask’, v.v.).
  • tensor_type (Union[None, str, TensorType], tùy chọn) — Bạn có thể cung cấp tensor_type tại đây để chuyển đổi các danh sách số nguyên trong Tensor PyTorch/Numpy khi khởi tạo.
  • skip_tensor_conversion (list[str] hoặc set[str], tuỳ chọn) — Danh sách hoặc tập hợp các key không được chuyển đổi thành tensor, ngay cả khi tensor_type được chỉ định.

Chứa kết quả đầu ra của các phương thức pad() và __call__ cụ thể của bộ trích xuất đặc trưng.

Lớp này được kế thừa từ một từ điển python và có thể được sử dụng như một từ điển.

convert_to_tensors

< >

( tensor_type: str | transformers.utils.generic.TensorType | None = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

Tham số

  • tensor_type (str hoặc TensorType, tuỳ chọn) — Loại tensor cần sử dụng. Nếu là str, phải là một trong các giá trị của enum TensorType. Nếu là None, sẽ không thực hiện thay đổi nào.
  • skip_tensor_conversion (list[str] hoặc set[str], tuỳ chọn) — Danh sách hoặc tập hợp các key không được chuyển đổi thành tensor, ngay cả khi tensor_type được chỉ định.

Chuyển đổi nội dung bên trong thành các tensor.

Note: Các giá trị không có cấu trúc dạng mảng (ví dụ: chuỗi, dict, danh sách các chuỗi) sẽ được tự động bỏ qua và không được chuyển đổi thành tensor. Các mảng không đều (danh sách các mảng có độ dài khác nhau) vẫn được thử chuyển đổi, mặc dù chúng có thể gây ra lỗi trong quá trình chuyển đổi.

đến

< >

( *args**kwargs ) → BatchFeature

Tham số

  • args (Tuple) — Sẽ được truyền vào hàm to(...) của các tensor.
  • kwargs (Dict, tùy chọn) — Sẽ được truyền cho hàm to(...) của các tensor. Để bật chuyển dữ liệu bất đồng bộ, hãy đặt cờ non_blocking trong kwargs (mặc định là False).

Trả về

BatchFeature

Cùng một instance sau khi được sửa đổi.

Gửi tất cả các giá trị đến thiết bị bằng cách gọi v.to(*args, **kwargs) (chỉ PyTorch). Thao tác này nên hỗ trợ chuyển đổi sang các dtypes khác nhau và gửi BatchFeature đến một device khác.

ImageFeatureExtractionMixin

lớp transformers.ImageFeatureExtractionMixin

< >

( )

Mixin chứa các tiện ích để chuẩn bị các đặc trưng hình ảnh.

center_crop

< >

( imagesize ) → new_image

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor có shape (n_channels, height, width) hoặc (height, width, n_channels)) — Hình ảnh cần thay đổi kích thước.
  • size (int hoặc tuple[int, int]) — Kích thước để cắt ảnh.

Trả về

new_image

Một PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor được cắt ở giữa, có hình dạng: (n_channels, height, width).

Cắt image thành kích thước cho trước bằng cách cắt ở giữa. Lưu ý rằng nếu ảnh quá nhỏ để cắt thành kích thước cho trước, nó sẽ được đệm (để kết quả trả về có đúng kích thước yêu cầu).

convert_rgb

< >

( image )

Tham số

  • image (PIL.Image.Image) — Hình ảnh cần chuyển đổi.

Chuyển đổi PIL.Image.Image sang định dạng RGB.

expand_dims

< >

( image )

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh cần mở rộng.

Mở rộng image 2 chiều thành 3 chiều.

flip_channel_order

< >

( image )

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh có các kênh màu cần đảo. Nếu là np.ndarray hoặc torch.Tensor, chiều kênh phải là chiều đầu tiên.

Đảo thứ tự kênh của image từ RGB sang BGR, hoặc ngược lại. Lưu ý rằng điều này sẽ kích hoạt việc chuyển đổi image thành mảng NumPy nếu nó là một hình ảnh PIL.

normalize

< >

( imagemeanstdrescale = False )

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh cần chuẩn hóa.
  • mean (list[float] hoặc np.ndarray hoặc torch.Tensor) — Giá trị trung bình (theo từng kênh) được sử dụng để chuẩn hóa.
  • std (list[float] hoặc np.ndarray hoặc torch.Tensor) — Độ lệch chuẩn (theo từng kênh) được sử dụng để chuẩn hóa.
  • rescale (bool, tùy chọn, mặc định là False) — Có nên điều chỉnh lại tỷ lệ hình ảnh để nằm trong khoảng từ 0 đến 1 hay không. Nếu hình ảnh PIL được cung cấp, việc điều chỉnh tỷ lệ sẽ được thực hiện tự động.

Chuẩn hóa image bằng mean và std. Lưu ý rằng điều này sẽ kích hoạt việc chuyển đổi image thành mảng NumPy nếu nó là ảnh PIL.

rescale

< >

( image: ndarrayscale: float | int )

Thay đổi tỷ lệ của một ảnh numpy theo giá trị scale

resize

< >

( imagesizeresample = Nonedefault_to_square = Truemax_size = None ) → image

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh cần thay đổi kích thước.
  • size (int hoặc tuple[int, int]) — Kích thước được sử dụng để thay đổi kích thước ảnh. Nếu size là một chuỗi như (h, w), kích thước đầu ra sẽ được khớp với giá trị này.

    Nếu size là int và default_to_square là True, thì ảnh sẽ được thay đổi kích thước thành (size, size). Nếu size là int và default_to_square là False, thì cạnh nhỏ hơn của ảnh sẽ được khớp với số này. Ví dụ, nếu chiều cao > chiều rộng, thì ảnh sẽ được thay đổi tỷ lệ thành (size * height / width, size).

  • resample (int, tùy chọn, mặc định là PILImageResampling.BILINEAR) — Bộ lọc dùng để lấy mẫu lại.
  • default_to_square (bool, tùy chọn, mặc định là True) — Cách chuyển đổi size khi nó là một int đơn lẻ. Nếu đặt thành True, size sẽ được chuyển đổi thành hình vuông (size,size). Nếu đặt thành False, sẽ sao chép torchvision.transforms.Resize với khả năng hỗ trợ chỉ thay đổi kích thước cạnh nhỏ nhất và cung cấp max_size tùy chọn.
  • max_size (int, tùy chọn, mặc định là None) — Giá trị tối đa cho phép của cạnh dài hơn của ảnh sau khi thay đổi kích thước: nếu cạnh dài hơn của ảnh lớn hơn max_size sau khi được thay đổi kích thước theo size, thì ảnh sẽ được thay đổi kích thước một lần nữa để cạnh dài hơn bằng max_size. Kết quả là, size có thể bị ghi đè, tức là cạnh ngắn hơn có thể ngắn hơn size. Chỉ được sử dụng nếu default_to_square là False.

Trả về

image

Một PIL.Image.Image đã được thay đổi kích thước.

Đổi kích thước image. Buộc chuyển đổi đầu vào sang PIL.Image.

rotate

< >

( imageangleresample = Noneexpand = 0center = Nonetranslate = Nonefillcolor = None ) → image

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh cần xoay. Nếu là np.ndarray hoặc torch.Tensor, sẽ được chuyển đổi sang PIL.Image.Image trước khi xoay.

Trả về

image

Một PIL.Image.Image đã được xoay.

Trả về một bản sao đã xoay của image. Phương thức này trả về một bản sao của image, được xoay một số độ cho trước theo chiều ngược kim đồng hồ quanh tâm của nó.

to_numpy_array

< >

( imagerescale = Nonechannel_first = True )

Tham số

  • image (PIL.Image.Image hoặc np.ndarray hoặc torch.Tensor) — Hình ảnh cần chuyển đổi thành mảng NumPy.
  • rescale (bool, tùy chọn) — Có áp dụng hệ số tỷ lệ (để giá trị pixel trở thành số float nằm trong khoảng từ 0. đến 1.) hay không. Mặc định là True nếu ảnh là PIL Image hoặc mảng/tensor của các số nguyên, ngược lại là False.
  • channel_first (bool, tùy chọn, mặc định là True) — Có nên hoán vị các chiều của hình ảnh để đặt chiều kênh lên đầu hay không.

Chuyển đổi image thành mảng numpy. Tùy chọn để tỷ lệ lại và đặt chiều kênh làm chiều đầu tiên.

to_pil_image

< >

( imagerescale = None )

Tham số

  • image (PIL.Image.Image hoặc numpy.ndarray hoặc torch.Tensor) — Hình ảnh cần chuyển đổi sang định dạng PIL Image.
  • rescale (bool, tùy chọn) — Có áp dụng hệ số tỷ lệ (để làm cho giá trị pixel là số nguyên từ 0 đến 255) hay không. Mặc định là True nếu kiểu ảnh là kiểu số thực, False trong các trường hợp khác.

Chuyển đổi image thành một hình ảnh PIL. Tùy chọn để thay đổi tỷ lệ và đưa chiều kênh về làm trục cuối nếu cần.

Update on GitHub

←ExecuTorch Bộ xử lý ảnh→