Prosesor

Pemroses multi-modal

Setiap model multi-modal akan memerlukan objek untuk mengodekan atau mendekodekan data yang menggabungkan beberapa modalitas (di antara teks, visi, dan audio). Hal ini ditangani oleh objek yang disebut processor, yang mengelompokkan dua atau lebih objek pemrosesan seperti tokenizer (untuk modalitas teks), image processor (untuk visi), dan feature extractor (untuk audio).

Pemroses tersebut mewarisi dari kelas dasar berikut yang mengimplementasikan fungsionalitas penyimpanan dan pemuatan:

kelas transformers.ProcessorMixin

< source >

( *args**kwargs )

Ini adalah mixin yang digunakan untuk menyediakan fungsionalitas penyimpanan/pemuatan untuk semua kelas prosesor.

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

Parameter

images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opsional) — Gambar yang akan dipreprocess. Mengharapkan satu gambar atau batch gambar dengan nilai piksel berkisar dari 0 hingga 255. Jika mengirimkan gambar dengan nilai piksel antara 0 dan 1, atur do_rescale=False.
text (Union[str, list[str], list[list[str]]], opsional) — Sequens atau batch dari sequens yang akan dienkod. Setiap sequens dapat berupa string atau daftar string (string yang sudah dipretokenisasi). Jika Anda memasukkan input yang sudah dipretokenisasi, atur is_split_into_words=True untuk menghindari ambiguitas dengan input yang di-batch.
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]]], opsional) — Video yang akan dipreprocess. Mengharapkan satu video atau batch video dengan nilai piksel berkisar dari 0 hingga 255. Jika mengirimkan video dengan nilai piksel antara 0 dan 1, atur do_rescale=False.
audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], opsional) — Audio atau batch audio yang akan disiapkan. Setiap audio dapat berupa array NumPy atau tensor PyTorch. Jika berupa array NumPy/tensor PyTorch, setiap audio harus memiliki bentuk (C, T), di mana C adalah jumlah channel, dan T adalah panjang sampel dari audio tersebut.
return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.
**kwargs (ProcessingKwargs, opsional) — Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

prepare_inputs_layout

< source >

Normalisasi dan prefetch input sebelum diproses. Membungkus teks dalam list untuk pemroses multimodal, mengambil gambar dan audio jarak jauh jika URL diberikan, dan memastikan audio di-batch dengan benar. Mengembalikan tuple (images, text, videos, audio) yang telah dinormalisasi.

validate_inputs

< source >

Validasi bahwa setidaknya satu input diberikan dan tidak ada argumen kata kunci yang tidak lagi didukung yang digunakan. Jika tidak, lempar ValueError.

Override ketika prosesor memerlukan validasi tambahan pada argumen input.

get_text_with_replacements

< source >

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

Parameter

text (list[str]) — Batch dari string teks mentah, di mana masing-masing dapat berisi token placeholder multimodal. Perhatikan bahwa nilai ini akan dimodifikasi secara in-place dan dikembalikan.
images_replacements (list[str], opsional, default []) — String pengganti yang diperluas untuk setiap gambar, sesuai urutan kemunculannya di seluruh batch. Dihasilkan oleh self._process_images.
videos_replacements (list[str], opsional, default []) — String pengganti yang diperluas untuk setiap video. Dihasilkan oleh self._process_videos.
audio_replacements (list[str], opsional, default []) — String pengganti yang diperluas untuk setiap input audio. Dihasilkan oleh self._process_audio.

Mengembalikan

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

Tuple dari:

Batch text yang dimodifikasi dengan semua token placeholder yang diperluas.
batch_replacement_offsets: satu entri per item batch, masing-masing berupa daftar dict dengan kunci:
“type” (str): nama modality — “image”, “video”, atau “audio”
“span” (tuple[int, int]): offset karakter (start, end) asli dari token placeholder
“new_span” (tuple[int, int]): offset (start, end) dari placeholder dalam string yang diperluas
“text” (str): string token placeholder asli yang cocok
“replacement” (str): string yang menggantikan

Ganti token placeholder multimodal dalam kumpulan string teks dengan representasi yang diperluasnya, dan kembalikan teks yang telah dimodifikasi beserta metadata offset.

Metode ini adalah langkah pra-pemrosesan sisi teks inti untuk input multimodal. Metode ini memindai setiap teks dalam batch untuk token khusus (gambar, video, audio) dan menggantinya secara berurutan dengan string pengganti yang telah dihitung sebelumnya yang dihasilkan oleh self.replace_image_token / self.replace_video_token / self.replace_audio_token. Penggantian dikonsumsi secara berurutan dari daftar setiap modalitas, sehingga kemunculan ke-i dari misalnya self.image_token diganti dengan images_replacements[i].

Untuk menambahkan pemroses multimodal baru dengan token placeholder, Anda perlu mendefinisikan self.image_token yang benar, yaitu token yang sama yang tertanam dalam teks input dan juga digunakan sebagai placeholder serta diulang berkali-kali. Kemudian Anda perlu menimpa self.replace_image_token untuk mengembalikan string penggantian yang benar untuk gambar tertentu pada indeks i. Hal yang sama berlaku untuk semua modalitas lain yang didukung.

create_mm_token_type_ids

< source >

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

Parameter

input_ids (list[list[int]]) — Batch dari urutan token ID. Bisa tidak di-pad (panjang bervariasi), sehingga diharapkan berupa list Python biasa berisi list, bukan tensor atau array dengan bentuk seragam.

Mengembalikan

list[list[int]]

Daftar dengan struktur yang sama seperti input_ids, di mana setiap bilangan bulat adalah ID tipe modalitas untuk token yang sesuai.

Bangun ID tipe modalitas per token untuk batch dari sekuens token_id.

Setiap posisi diberi bilangan bulat yang menunjukkan modalitas apa yang dimilikinya: 0 untuk teks biasa, 1 untuk token gambar, 2 untuk token video, dan 3 untuk token audio. Keanggotaan ditentukan dengan membandingkan terhadap self.image_token_ids, self.video_token_ids, dan 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 )

Parameter

conversation (Union[list[Dict, [str, str]], list[list[dict[str, str]]]]) — Percakapan yang akan diformat.
chat_template (Optional[str], opsional) — Template Jinja yang digunakan untuk memformat percakapan. Jika tidak disediakan, template chat dari tokenizer akan digunakan.

Mirip dengan metode apply_chat_template pada tokenizer, metode ini menerapkan template Jinja ke percakapan input untuk mengubahnya menjadi satu string yang dapat ditokenisasi.

Input yang diharapkan berada dalam format berikut, di mana setiap konten pesan adalah daftar yang terdiri dari teks dan secara opsional input gambar atau video. Anda juga dapat menyediakan gambar, video, URL, atau jalur lokal yang akan digunakan untuk membentuk pixel_values ketika return_dict=True. Jika tidak disediakan, Anda hanya akan mendapatkan teks yang diformat, dan secara opsional teks yang ditokenisasi.

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

Memproses kwargs

Metode __call__ Processor menerima argumen kata kunci yang diorganisasikan berdasarkan modalitas. Kelas TypedDict berikut mendefinisikan argumen kata kunci yang tersedia untuk setiap modalitas. Processor yang spesifik untuk model tertentu dapat mewarisi kelas-kelas ini untuk menambahkan atau menimpa field.

kelas transformers.ProcessingKwargs

< source >

( )

Kelas dasar untuk meneruskan kwargs ke prosesor. Jika sebuah model memiliki kwargs spesifik yang tidak ada di kelas dasar atau nilai default untuk kunci yang sudah ada, model tersebut harus memiliki kelas ModelProcessorKwargs miliknya sendiri yang mewarisi dari ProcessingKwargs untuk menyediakan: 1) Kunci bertipe tambahan yang diperlukan model ini untuk memproses input. 2) Nilai default untuk kunci yang sudah ada di bawah atribut _defaults. Kunci baru harus didefinisikan sebagai berikut untuk memastikan type hinting dilakukan dengan benar.

# 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",
        },
    }

Untuk kompatibilitas Python 3.8, saat mewarisi dari kelas ini dan menimpa salah satu kwargs,

Anda perlu memperbarui kamus annotations secara manual. Hal ini dapat dilakukan sebagai berikut:

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

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

kelas transformers.TextKwargs

< source >

( )

Parameter

add_special_tokens (bool, opsional) — Apakah token khusus akan ditambahkan saat mengkodekan urutan.
padding (bool, str atau PaddingStrategy, opsional) — Mengaktifkan dan mengontrol padding.
truncation (bool, str atau TruncationStrategy, opsional) — Mengaktifkan dan mengontrol pemotongan.
max_length (int, opsional) — Mengontrol panjang maksimum yang digunakan oleh salah satu parameter truncation/padding.
stride (int, opsional) — Jika diset, token yang meluap akan berisi beberapa token dari akhir urutan yang dipangkas.
is_split_into_words (bool, opsional) — Apakah input sudah di-tokenisasi sebelumnya.
pad_to_multiple_of (int, opsional) — Jika diatur, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.
return_token_type_ids (bool, opsional) — Apakah akan mengembalikan ID tipe token.
return_attention_mask (bool, opsional) — Apakah akan mengembalikan attention mask.
return_overflowing_tokens (bool, opsional) — Apakah akan mengembalikan urutan token yang meluap.
return_special_tokens_mask (bool, opsional) — Apakah akan mengembalikan informasi mask token khusus.
return_offsets_mapping (bool, opsional) — Apakah akan mengembalikan (char_start, char_end) untuk setiap token.
return_length (bool, opsional) — Apakah akan mengembalikan panjang dari input yang dikodekan.
verbose (bool, opsional) — Apakah akan mencetak lebih banyak informasi dan peringatan.
padding_side (str, opsional) — Sisi tempat padding akan diterapkan.
return_mm_token_type_ids (bool, opsional) — Apakah akan mengembalikan multimodal token type ids yang menunjukkan posisi token placeholder mm.
return_text_replacement_offsets (bool, opsional) — Apakah akan mengembalikan offset karakter untuk setiap placeholder mm dan pengantinya.
return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.

Keyword arguments untuk pemrosesan teks. Untuk dokumentasi yang lebih lengkap, periksa metode dan docstring terkait pada tokenization_utils_base.

kelas transformers.ImagesKwargs

< source >

( )

Parameter

do_convert_rgb (bool) — Apakah akan mengonversi gambar ke format RGB.
do_resize (bool, opsional) — Apakah akan mengubah ukuran gambar.
size (dict[str, int], opsional) — Ukuran ulang menggunakan salah satu kamus ukuran yang didukung. Batas area piksel menggunakan {"min_pixels": int, "max_pixels": int}.
default_to_square (bool, opsional, defaultnya self.default_to_square) — Apakah akan menggunakan bentuk persegi secara default saat mengubah ukuran, jika size berupa int.
crop_size (dict[str, int], opsional) — Ukuran output yang diinginkan saat menerapkan center-cropping.
resample (PILImageResampling, opsional) — Filter resampling yang digunakan jika mengubah ukuran gambar.
do_rescale (bool, opsional) — Apakah akan melakukan penskalaan ulang gambar dengan skala yang ditentukan rescale_factor.
rescale_factor (int atau float, opsional) — Faktor skala yang digunakan jika melakukan penskalaan ulang gambar.
do_normalize (bool, opsional) — Apakah akan menormalisasi gambar.
image_mean (float or list[float] or tuple[float, float, float], optional) — Mean to use if normalizing the image.
image_std (float or list[float] or tuple[float, float, float], optional) — Standard deviation to use if normalizing the image.
do_pad (bool, opsional) — Apakah akan melakukan padding pada gambar dalam batch.
pad_size (dict[str, int], opsional) — Ukuran {"height": int, "width" int} untuk melakukan padding pada gambar.
do_center_crop (bool, opsional) — Apakah akan melakukan center crop pada gambar.
data_format (ChannelDimension atau str, opsional) — Format dimensi channel untuk gambar keluaran.
input_data_format (ChannelDimension atau str, opsional) — Format dimensi channel untuk gambar input.
device (Union[str, torch.Tensor], opsional) — Perangkat yang akan digunakan untuk pemrosesan (misalnya “cpu”, “cuda”), hanya relevan untuk backend torchvision.
return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.
disable_grouping (bool, opsional) — Apakah akan mengelompokkan gambar berdasarkan bentuk saat memproses atau tidak, hanya relevan untuk backend torchvision.
image_seq_length (int, opsional) — Jumlah token gambar yang akan digunakan untuk setiap gambar dalam input. Ditambahkan untuk kompatibilitas mundur, tetapi ini seharusnya diatur sebagai atribut prosesor pada model-model mendatang.

Argumen kata kunci untuk pemrosesan gambar. Untuk dokumentasi yang lebih lengkap, periksa metode dan docstring kelas ImageProcessor yang sesuai.

kelas transformers.VideosKwargs

< source >

( )

Parameter

do_convert_rgb (bool) — Apakah akan mengonversi video ke format RGB.
do_resize (bool) — Apakah akan mengubah ukuran video.
size (dict[str, int], opsional) — Ukurkan ulang sisi yang lebih pendek dari input menjadi size["shortest_edge"].
default_to_square (bool, opsional, defaultnya self.default_to_square) — Apakah akan menggunakan bentuk persegi secara default saat mengubah ukuran, jika size berupa int.
resample (PILImageResampling, opsional) — Filter resampling yang digunakan jika video di-resize.
do_rescale (bool, opsional) — Apakah video akan diskalakan ulang dengan skala rescale_factor yang ditentukan.
rescale_factor (int atau float, opsional) — Faktor skala yang digunakan jika melakukan penskalaan ulang video.
do_normalize (bool, opsional) — Apakah akan menormalisasi video.
image_mean (float or list[float] or tuple[float, float, float], optional) — Mean to use if normalizing the video.
image_std (float or list[float] or tuple[float, float, float], optional) — Standard deviation to use if normalizing the video.
do_center_crop (bool, opsional) — Apakah akan melakukan center crop pada video.
do_pad (bool, opsional) — Apakah akan melakukan padding pada gambar dalam batch.
do_sample_frames (bool, opsional) — Apakah akan mengambil sampel frame dari video sebelum diproses atau memproses seluruh video.
video_metadata (Union[VideoMetadata, dict], opsional) — Metadata dari video yang berisi informasi tentang durasi total, fps, dan jumlah total frame.
num_frames (int, opsional) — Jumlah maksimum frame yang akan disampelkan saat do_sample_frames=True.
fps (int atau float, opsional) — Target frame yang akan disampel per detik ketika do_sample_frames=True.
crop_size (dict[str, int], opsional) — Ukuran output yang diinginkan saat menerapkan center-cropping.
data_format (ChannelDimension atau str, opsional) — Format dimensi channel untuk video keluaran.
input_data_format (ChannelDimension atau str, opsional) — Format dimensi channel untuk video input.
device (Union[str, torch.Tensor], opsional) — Perangkat yang akan digunakan untuk pemrosesan (misalnya “cpu”, “cuda”), hanya relevan untuk pemrosesan gambar cepat.
return_metadata (bool, opsional) — Apakah akan mengembalikan metadata video atau tidak.
return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.

Argumen kata kunci untuk pemrosesan video.

kelas transformers.AudioKwargs

< source >

( )

Parameter

sampling_rate (int, opsional) — Laju sampling di mana input raw_speech disampelkan.
raw_speech (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — Sequens atau batch dari sequens yang akan di-pad. Setiap sequens dapat berupa array numpy, daftar nilai float, daftar array numpy, atau daftar dari daftar nilai float. Harus berupa audio mono channel, bukan stereo, yaitu satu float per timestep.
padding (bool, str atau PaddingStrategy, opsional) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
- True atau 'longest': Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
- 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
- False atau 'do_not_pad'
max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
truncation (bool, opsional) — Mengaktifkan pemotongan untuk memotong urutan input yang lebih panjang dari max_length menjadi max_length.
pad_to_multiple_of (int, opsional) — Jika diatur, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.
return_attention_mask (bool, opsional) — Apakah call() harus mengembalikan attention_mask atau tidak.
device (str atau torch.device, opsional) — Perangkat untuk menghitung fitur audio (misalnya “cpu”, “cuda”), hanya relevan untuk ekstraktor fitur yang menghitungnya dengan torch.
return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.
load_audio_backend (str, opsional) — Backend yang digunakan oleh load_audio() untuk mendekode/meresampel audio yang dirujuk oleh URL/path di apply_chat_template. Salah satu dari "auto", "torchcodec", "librosa", "torchaudio".

Argumen kata kunci untuk pemrosesan audio.

Update on GitHub

Transformers

Prosesor

Pemroses multi-modal

kelas transformers.ProcessorMixin

__call__

prepare_inputs_layout

validate_inputs

get_text_with_replacements

create_mm_token_type_ids

apply_chat_template

Memproses kwargs

kelas transformers.ProcessingKwargs

kelas transformers.TextKwargs

kelas transformers.ImagesKwargs

kelas transformers.VideosKwargs

kelas transformers.AudioKwargs

call