Transformers documentation

FocalNet

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

and get access to the augmented documentation experience

to get started

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

< >

( 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, defaultnya 224) — Ukuran (resolusi) dari setiap gambar.
  • patch_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 4) — Ukuran (resolusi) dari setiap patch.
  • num_channels (int, opsional, defaultnya 3) — Jumlah saluran input.
  • embed_dim (int, opsional, default 96) — Dimensi dari embeddings dan hidden states.
  • use_conv_embed (bool, opsional, default False) — 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, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
  • mlp_ratio (float, opsional, default 4.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, defaultnya 0.1) — Tingkat drop path untuk fusi patch.
  • use_layerscale (bool, opsional, default False) — Apakah akan menggunakan layer scale di encoder.
  • layerscale_value (float, opsional, default 0.0001) — Nilai awal dari skala layer.
  • use_post_layernorm (bool, opsional, default False) — Apakah akan menggunakan normalisasi lapisan pasca (post layer normalization) pada encoder.
  • use_post_layernorm_in_modulation (bool, opsional, default False) — Apakah akan menggunakan normalisasi lapisan pasca (post layer normalization) pada lapisan modulasi.
  • normalize_modulator (bool, opsional, default False) — Apakah akan menormalisasi modulator.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
  • layer_norm_eps (float, opsional, defaultnya 1e-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.config

FocalNetModel

kelas transformers.FocalNetModel

< >

( 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, default True) — Apakah akan menambahkan lapisan pooling
  • use_mask_token (bool, opsional, default False) — 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

< >

( 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.Tensor dengan 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_class menggunakan BitImageProcessor untuk memproses gambar).
  • bool_masked_pos (torch.BoolTensor dengan 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. Lihat hidden_states di 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 Module setelahnya 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.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir model.

  • pooler_output (torch.Tensor dengan bentuk (batch_size, hidden_size), opsional, dikembalikan ketika add_pooling_layer=True diberikan) — Average pooling dari hidden-state lapisan terakhir.

  • hidden_states (tuple[torch.Tensor], opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.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 ketika output_hidden_states=True dilewatkan atau ketika config.output_hidden_states=True) — Tuple dari torch.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:

FocalNetForMaskedImageModeling

kelas transformers.FocalNetForMaskedImageModeling

< >

( 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

< >

( 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.Tensor dengan 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_class menggunakan BitImageProcessor untuk memproses gambar).
  • bool_masked_pos (torch.BoolTensor dengan 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. Lihat hidden_states di 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 Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan ketika bool_masked_pos disediakan) — Loss untuk masked image modeling (MLM).

  • rekonstruksi (torch.Tensor dengan bentuk (batch_size, num_channels, height, width)) — Nilai piksel yang direkonstruksi.

  • hidden_states (tuple[torch.Tensor], opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.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 ketika output_hidden_states=True dilewatkan atau ketika config.output_hidden_states=True) — Tuple dari torch.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

< >

( 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

< >

( 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.Tensor dengan 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_class menggunakan BitImageProcessor untuk memproses gambar).
  • labels (torch.LongTensor dengan bentuk (batch_size,), opsional) — Label untuk menghitung loss klasifikasi/regresi gambar. Indeks harus berada dalam [0, ..., config.num_labels - 1]. Jika config.num_labels == 1, loss regresi dihitung (Mean-Square loss). Jika config.num_labels > 1, loss klasifikasi dihitung (Cross-Entropy).
  • output_hidden_states (bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihat hidden_states di 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 Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan saat labels disediakan) — Loss klasifikasi (atau regresi jika config.num_labels==1).

  • logits (torch.Tensor dengan bentuk (batch_size, config.num_labels)) — Skor klasifikasi (atau regresi jika config.num_labels==1) (sebelum SoftMax).

  • hidden_states (tuple[torch.Tensor], opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.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 ketika output_hidden_states=True dilewatkan atau ketika config.output_hidden_states=True) — Tuple dari torch.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])
...
Update on GitHub