Transformers documentation
FocalNet
Model ini dipublikasikan di HF papers pada 2022-03-22 dan disumbangkan ke Hugging Face Transformers pada 2023-04-23.
FocalNet
Ikhtisar
Model FocalNet diusulkan dalam Focal Modulation Networks oleh Jianwei Yang, Chunyuan Li, Xiyang Dai, Lu Yuan, Jianfeng Gao. FocalNets sepenuhnya menggantikan self-attention (yang digunakan dalam model seperti ViT dan Swin) dengan mekanisme focal modulation untuk pemodelan interaksi token dalam visi. Para penulis mengklaim bahwa FocalNets melampaui model berbasis self-attention dengan biaya komputasi serupa pada tugas klasifikasi gambar, deteksi objek, dan segmentasi.
Abstrak dari makalah tersebut adalah sebagai berikut:
Kami mengusulkan focal modulation networks (disingkat FocalNets), di mana self-attention (SA) sepenuhnya digantikan oleh mekanisme focal modulation untuk memodelkan interaksi token dalam visi. Focal modulation terdiri dari tiga komponen: (i) hierarkis kontekstualisasi, diimplementasikan menggunakan tumpukan lapisan konvolusi depth-wise, untuk mengkodekan konteks visual dari rentang pendek hingga panjang, (ii) agregasi bergerbang untuk mengumpulkan konteks secara selektif untuk setiap token kueri berdasarkan isinya, dan (iii) modulasi element-wise atau transformasi afine untuk menyuntikkan konteks yang telah diagregasi ke dalam kueri. Eksperimen ekstensif menunjukkan FocalNets melampaui padanan SA state-of-the-art (misalnya, Swin dan Focal Transformers) dengan biaya komputasi yang serupa pada tugas klasifikasi gambar, deteksi objek, dan segmentasi. Secara spesifik, FocalNets dengan ukuran tiny dan base mencapai akurasi top-1 sebesar 82,3% dan 83,9% pada ImageNet-1K. Setelah dipretrain pada ImageNet-22K dengan resolusi 224, model ini mencapai akurasi top-1 sebesar 86,5% dan 87,3% saat difinetune dengan resolusi 224 dan 384, masing-masing. Saat ditransfer ke tugas downstream, FocalNets menunjukkan keunggulan yang jelas. Untuk deteksi objek dengan Mask R-CNN, FocalNet base yang dilatih dengan 1\times melampaui padanan Swin sebesar 2,1 poin dan sudah melampaui Swin yang dilatih dengan jadwal 3\times (49,0 v.s. 48,5). Untuk segmentasi semantik dengan UPerNet, FocalNet base pada skala tunggal melampaui Swin sebesar 2,4, dan mengalahkan Swin pada multi-skala (50,5 v.s. 49,7). Menggunakan FocalNet besar dan Mask2former, kami mencapai 58,5 mIoU untuk segmentasi semantik ADE20K, dan 57,9 PQ untuk COCO Panoptic Segmentation. Menggunakan FocalNet huge dan DINO, kami mencapai 64,3 dan 64,4 mAP pada COCO minival dan test-dev, masing-masing, menetapkan SoTA baru di atas model berbasis perhatian yang jauh lebih besar seperti Swinv2-G dan BEIT-3.
Model ini disumbangkan oleh nielsr. Kode aslinya dapat ditemukan di sini.
FocalNetConfig
kelas transformers.FocalNetConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneimage_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 4num_channels: int = 3embed_dim: int = 96use_conv_embed: bool = Falsehidden_sizes: list[int] | tuple[int, ...] = (192, 384, 768, 768)depths: list[int] | tuple[int, ...] = (2, 2, 6, 2)focal_levels: list[int] | tuple[int, ...] = (2, 2, 2, 2)focal_windows: list[int] | tuple[int, ...] = (3, 3, 3, 3)hidden_act: str = 'gelu'mlp_ratio: float = 4.0hidden_dropout_prob: float | int = 0.0drop_path_rate: float | int = 0.1use_layerscale: bool = Falselayerscale_value: float = 0.0001use_post_layernorm: bool = Falseuse_post_layernorm_in_modulation: bool = Falsenormalize_modulator: bool = Falseinitializer_range: float = 0.02layer_norm_eps: float = 1e-05encoder_stride: int = 32_out_features: list[str] | None = None_out_indices: list[int] | None = None )
Parameter
- image_size (
Union[int, list[int], tuple[int, int]], opsional, defaultnya224) — Ukuran (resolusi) dari setiap gambar. - patch_size (
Union[int, list[int], tuple[int, int]], opsional, defaultnya4) — Ukuran (resolusi) dari setiap patch. - num_channels (
int, opsional, defaultnya3) — Jumlah saluran input. - embed_dim (
int, opsional, default96) — Dimensi dari embeddings dan hidden states. - use_conv_embed (
bool, opsional, defaultFalse) — Apakah akan menggunakan convolutional embedding. Para penulis mencatat bahwa penggunaan convolutional embedding biasanya meningkatkan performa, tetapi tidak digunakan secara default. - hidden_sizes (
Union[list[int], tuple[int, ...]], opsional, default(192, 384, 768, 768)) — Dimensi (hidden size) pada setiap tahap model. - depths (
Union[list[int], tuple[int, ...]], opsional, default(2, 2, 6, 2)) — Kedalaman setiap layer dalam Transformer. - focal_levels (
list(int), opsional, default[2, 2, 2, 2]) — Jumlah focal levels di setiap layer dari tahap yang bersangkutan dalam encoder. - focal_windows (
list(int), opsional, default[3, 3, 3, 3]) — Ukuran jendela focal pada setiap layer dari tahap yang bersangkutan di encoder. - hidden_act (
str, opsional, defaultnyagelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya,"gelu","relu","silu", dan sebagainya. - mlp_ratio (
float, opsional, default4.0) — Rasio dimensi tersembunyi MLP terhadap dimensi embedding. - hidden_dropout_prob (
float, opsional, default 0.0) — Probabilitas dropout untuk semua lapisan fully connected di embeddings dan encoder. - drop_path_rate (
Union[float, int], opsional, defaultnya0.1) — Tingkat drop path untuk fusi patch. - use_layerscale (
bool, opsional, defaultFalse) — Apakah akan menggunakan layer scale di encoder. - layerscale_value (
float, opsional, default 0.0001) — Nilai awal dari skala layer. - use_post_layernorm (
bool, opsional, defaultFalse) — Apakah akan menggunakan normalisasi lapisan pasca (post layer normalization) pada encoder. - use_post_layernorm_in_modulation (
bool, opsional, defaultFalse) — Apakah akan menggunakan normalisasi lapisan pasca (post layer normalization) pada lapisan modulasi. - normalize_modulator (
bool, opsional, defaultFalse) — Apakah akan menormalisasi modulator. - initializer_range (
float, opsional, defaultnya0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot. - layer_norm_eps (
float, opsional, defaultnya1e-05) — Epsilon yang digunakan oleh lapisan normalisasi lapisan. - encoder_stride (
int, opsional, default 32) — Faktor untuk meningkatkan resolusi spasial pada decoder head untuk pemodelan gambar ber-masker.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari FocalNetModel. Kelas ini digunakan untuk membuat instans model Focalnet berdasarkan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari microsoft/focalnet-tiny
Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.
Contoh:
>>> from transformers import FocalNetConfig, FocalNetModel
>>> # Initializing a FocalNet microsoft/focalnet-tiny style configuration
>>> configuration = FocalNetConfig()
>>> # Initializing a model (with random weights) from the microsoft/focalnet-tiny style configuration
>>> model = FocalNetModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configFocalNetModel
kelas transformers.FocalNetModel
< source >( config: FocalNetConfigadd_pooling_layer = Trueuse_mask_token = False )
Parameter
- config (FocalNetConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
- add_pooling_layer (
bool, opsional, defaultTrue) — Apakah akan menambahkan lapisan pooling - use_mask_token (
bool, opsional, defaultFalse) — Apakah akan menggunakan token mask untuk pemodelan gambar ter-mask.
Model Focalnet polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.
Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)
Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetModelOutput or tuple(torch.Tensor)
Parameter
- pixel_values (
torch.Tensordengan bentuk(batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan BitImageProcessor. Lihat BitImageProcessor.call() untuk detailnya (processor_classmenggunakan BitImageProcessor untuk memproses gambar). - bool_masked_pos (
torch.BoolTensordengan bentuk(batch_size, num_patches)) — Posisi yang dimasker secara boolean. Menunjukkan patch mana yang dimasker (1) dan mana yang tidak (0). - output_hidden_states (
bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihathidden_statesdi bawah tensor yang dikembalikan untuk detail lebih lanjut. - return_dict (
bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
Mengembalikan
FocalNetModelOutput atau tuple(torch.Tensor)
FocalNetModelOutput atau tuple dari
torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (FocalNetConfig) dan input.
Metode forward dari FocalNetModel menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.
last_hidden_state (
torch.Tensordengan bentuk(batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir model.pooler_output (
torch.Tensordengan bentuk(batch_size, hidden_size), opsional, dikembalikan ketikaadd_pooling_layer=Truediberikan) — Average pooling dari hidden-state lapisan terakhir.hidden_states (
tuple[torch.Tensor], opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk(batch_size, sequence_length, hidden_size).Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
reshaped_hidden_states (
tuple(torch.Tensor), opsional, dikembalikan ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output embeddings + satu untuk output setiap tahap) dengan bentuk(batch_size, hidden_size, height, width).Hidden-states model pada output setiap lapisan ditambah output embedding awal yang di-reshape untuk mencakup dimensi spasial.
FocalNetForMaskedImageModeling
kelas transformers.FocalNetForMaskedImageModeling
< source >( config: FocalNetConfig )
Parameter
- config (FocalNetConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
Model FocalNet dengan decoder di atasnya untuk pemodelan gambar ber-masker.
Ini mengikuti implementasi yang sama seperti di SimMIM.
Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)
Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetMaskedImageModelingOutput or tuple(torch.Tensor)
Parameter
- pixel_values (
torch.Tensordengan bentuk(batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan BitImageProcessor. Lihat BitImageProcessor.call() untuk detailnya (processor_classmenggunakan BitImageProcessor untuk memproses gambar). - bool_masked_pos (
torch.BoolTensordengan bentuk(batch_size, num_patches)) — Posisi yang dimasker secara boolean. Menunjukkan patch mana yang dimasker (1) dan mana yang tidak (0). - output_hidden_states (
bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihathidden_statesdi bawah tensor yang dikembalikan untuk detail lebih lanjut. - return_dict (
bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
Mengembalikan
FocalNetMaskedImageModelingOutput atau tuple(torch.Tensor)
A FocalNetMaskedImageModelingOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (FocalNetConfig) dan input.
Metode forward dari FocalNetForMaskedImageModeling menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.
loss (
torch.Tensordengan bentuk(1,), opsional, dikembalikan ketikabool_masked_posdisediakan) — Loss untuk masked image modeling (MLM).rekonstruksi (
torch.Tensordengan bentuk(batch_size, num_channels, height, width)) — Nilai piksel yang direkonstruksi.hidden_states (
tuple[torch.Tensor], opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk(batch_size, sequence_length, hidden_size).Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
reshaped_hidden_states (
tuple(torch.Tensor), opsional, dikembalikan ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output embeddings + satu untuk output setiap tahap) dengan bentuk(batch_size, hidden_size, height, width).Hidden-states model pada output setiap lapisan ditambah output embedding awal yang di-reshape untuk mencakup dimensi spasial.
Contoh:
>>> from transformers import AutoImageProcessor, FocalNetConfig, FocalNetForMaskedImageModeling
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read()))
>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/focalnet-base-simmim-window6-192")
>>> config = FocalNetConfig()
>>> model = FocalNetForMaskedImageModeling(config)
>>> num_patches = (model.config.image_size // model.config.patch_size) ** 2
>>> pixel_values = image_processor(images=image, return_tensors="pt").pixel_values
>>> # create random boolean mask of shape (batch_size, num_patches)
>>> bool_masked_pos = torch.randint(low=0, high=2, size=(1, num_patches)).bool()
>>> outputs = model(pixel_values, bool_masked_pos=bool_masked_pos)
>>> loss, reconstructed_pixel_values = outputs.loss, outputs.logits
>>> list(reconstructed_pixel_values.shape)
[1, 3, 192, 192]FocalNetForImageClassification
kelas transformers.FocalNetForImageClassification
< source >( config: FocalNetConfig )
Parameter
- config (FocalNetConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
Model FocalNet dengan kepala klasifikasi gambar di atasnya (lapisan linear di atas output yang dipooling) misalnya untuk ImageNet.
Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)
Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetImageClassifierOutput or tuple(torch.Tensor)
Parameter
- pixel_values (
torch.Tensordengan bentuk(batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan BitImageProcessor. Lihat BitImageProcessor.call() untuk detailnya (processor_classmenggunakan BitImageProcessor untuk memproses gambar). - labels (
torch.LongTensordengan bentuk(batch_size,), opsional) — Label untuk menghitung loss klasifikasi/regresi gambar. Indeks harus berada dalam[0, ..., config.num_labels - 1]. Jikaconfig.num_labels == 1, loss regresi dihitung (Mean-Square loss). Jikaconfig.num_labels > 1, loss klasifikasi dihitung (Cross-Entropy). - output_hidden_states (
bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihathidden_statesdi bawah tensor yang dikembalikan untuk detail lebih lanjut. - return_dict (
bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
Mengembalikan
FocalNetImageClassifierOutput atau tuple(torch.Tensor)
FocalNetImageClassifierOutput atau tuple dari
torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (FocalNetConfig) dan input.
Metode forward dari FocalNetForImageClassification menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.
loss (
torch.Tensordengan bentuk(1,), opsional, dikembalikan saatlabelsdisediakan) — Loss klasifikasi (atau regresi jika config.num_labels==1).logits (
torch.Tensordengan bentuk(batch_size, config.num_labels)) — Skor klasifikasi (atau regresi jika config.num_labels==1) (sebelum SoftMax).hidden_states (
tuple[torch.Tensor], opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk(batch_size, sequence_length, hidden_size).Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
reshaped_hidden_states (
tuple(torch.Tensor), opsional, dikembalikan ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output embeddings + satu untuk output setiap tahap) dengan bentuk(batch_size, hidden_size, height, width).Hidden-states model pada output setiap lapisan ditambah output embedding awal yang di-reshape untuk mencakup dimensi spasial.
Contoh:
>>> from transformers import AutoImageProcessor, FocalNetForImageClassification
>>> import torch
>>> from datasets import load_dataset
>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]
>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/focalnet-tiny")
>>> model = FocalNetForImageClassification.from_pretrained("microsoft/focalnet-tiny")
>>> inputs = image_processor(image, return_tensors="pt")
>>> with torch.no_grad():
... logits = model(**inputs).logits
>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...