Transformers documentation

SAM-HQ

Transformers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Model ini dipublikasikan di HF papers pada 2023-06-02 dan disumbangkan ke Hugging Face Transformers pada 2025-04-28.

SAM-HQ

Ikhtisar

SAM-HQ (High-Quality Segment Anything Model) diusulkan dalam Segment Anything in High Quality oleh Lei Ke, Mingqiao Ye, Martin Danelljan, Yifan Liu, Yu-Wing Tai, Chi-Keung Tang, Fisher Yu.

Model ini merupakan peningkatan dari model SAM asli yang menghasilkan mask segmentasi dengan kualitas yang jauh lebih tinggi, sambil tetap mempertahankan desain promptable, efisiensi, dan kemampuan generalisasi zero-shot dari SAM.

example image

SAM-HQ memperkenalkan beberapa peningkatan utama dibandingkan model SAM asli:

Token Output Berkualitas Tinggi: Token yang dapat dipelajari (learnable) yang disuntikkan ke dalam mask decoder SAM untuk prediksi mask dengan kualitas yang lebih tinggi
Fusi Fitur Global-Lokal: Menggabungkan fitur dari berbagai tahap model untuk meningkatkan detail mask
Data Pelatihan: Menggunakan dataset yang dikurasi dengan cermat berisi 44K mask berkualitas tinggi, bukan SA-1B
Efisiensi: Hanya menambahkan 0,5% parameter tambahan sambil secara signifikan meningkatkan kualitas mask
Kemampuan Zero-shot: Mempertahankan kinerja zero-shot yang kuat dari SAM sambil meningkatkan akurasi

Abstrak dari makalah tersebut adalah sebagai berikut:

Segment Anything Model (SAM) yang baru-baru ini dirilis merupakan lompatan besar dalam memperluas skala model segmentasi, memungkinkan kemampuan zero-shot yang kuat dan prompting yang fleksibel. Meskipun dilatih dengan 1,1 miliar mask, kualitas prediksi mask SAM masih kurang memadai dalam banyak kasus, terutama ketika berurusan dengan objek yang memiliki struktur rumit. Kami mengusulkan HQ-SAM, yang melengkapi SAM dengan kemampuan untuk mensegmentasi objek apa pun secara akurat, sambil mempertahankan desain promptable, efisiensi, dan generalisasi zero-shot asli SAM. Desain cermat kami menggunakan ulang dan mempertahankan bobot model terlatih sebelumnya dari SAM, sambil hanya memperkenalkan parameter dan komputasi tambahan yang minimal. Kami merancang High-Quality Output Token yang dapat dipelajari, yang disuntikkan ke dalam mask decoder SAM dan bertanggung jawab untuk memprediksi mask berkualitas tinggi. Alih-alih hanya menerapkannya pada fitur mask-decoder, kami terlebih dahulu menggabungkannya dengan fitur ViT awal dan akhir untuk meningkatkan detail mask. Untuk melatih parameter yang dapat dipelajari yang kami perkenalkan, kami menyusun dataset berisi 44K mask bergranularitas halus dari beberapa sumber. HQ-SAM hanya dilatih pada dataset 44k mask yang diperkenalkan, yang hanya membutuhkan waktu 4 jam pada 8 GPU.

Tips:

SAM-HQ menghasilkan mask dengan kualitas yang lebih tinggi daripada model SAM asli, terutama untuk objek dengan struktur yang rumit dan detail yang halus
Model memprediksi masker biner dengan batas yang lebih akurat dan penanganan struktur tipis yang lebih baik
Seperti SAM, model ini memberikan hasil yang lebih baik dengan input titik 2D dan/atau kotak pembatas (bounding box) sebagai input.
Anda dapat memberikan prompt untuk beberapa titik pada gambar yang sama dan memprediksi satu mask berkualitas tinggi
Model ini mempertahankan kemampuan generalisasi zero-shot SAM
SAM-HQ hanya menambahkan sekitar 0,5% parameter tambahan dibandingkan SAM
Fine-tuning model belum didukung

Model ini disumbangkan oleh sushmanth. Kode aslinya dapat ditemukan di sini.

Berikut adalah contoh cara menjalankan pembuatan mask yang diberikan sebuah gambar dan titik 2D:

import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor


model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores

Anda juga dapat memproses mask Anda sendiri bersama dengan gambar input di dalam processor untuk diteruskan ke model:

import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor


model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
mask_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
segmentation_map = Image.open(requests.get(mask_url, stream=True).raw).convert("1")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, segmentation_maps=segmentation_map, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores

Sumber daya

Berikut adalah daftar sumber resmi Hugging Face dan komunitas (ditandai dengan 🌎) untuk membantu Anda memulai dengan SAM-HQ:

Notebook demo untuk menggunakan model (segera hadir)
Implementasi paper dan kode: Repositori GitHub SAM-HQ

SamHQConfig

kelas transformers.SamHQConfig

< 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 = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02tie_word_embeddings: bool = True )

Parameter

vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari vision backbone.
prompt_encoder_config (Union[dict, SamHQPromptEncoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi SamHQPromptEncoderConfig.
mask_decoder_config (Union[dict, SamHQMaskDecoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi SamHQMaskDecoderConfig.
initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
tie_word_embeddings (bool, opsional, default True) — Apakah akan mengikat bobot embedding sesuai dengan pemetaan tied_weights_keys model.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari SamHQModel. Kelas ini digunakan untuk membuat instans model Sam Hq berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari syscv-community/sam-hq-vit-base

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

SamHQVisionConfig

kelas transformers.SamHQVisionConfig

< 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 = Nonehidden_size: int = 768output_channels: int = 256num_hidden_layers: int = 12num_attention_heads: int = 12num_channels: int = 3image_size: int | list[int] | tuple[int, int] = 1024patch_size: int | list[int] | tuple[int, int] = 16hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06attention_dropout: float | int = 0.0initializer_range: float = 1e-10qkv_bias: bool = Truemlp_ratio: float = 4.0use_abs_pos: bool = Trueuse_rel_pos: bool = Truewindow_size: int = 14global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11)num_pos_feats: int = 128mlp_dim: int | None = None )

Parameter

hidden_size (int, opsional, default 768) — Dimensi dari representasi tersembunyi.
output_channels (int, opsional, default 256) — Dimensi dari saluran output di Patch Encoder.
num_hidden_layers (int, opsional, default 12) — Jumlah lapisan tersembunyi dalam decoder Transformer.
num_attention_heads (int, opsional, default 12) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
num_channels (int, opsional, defaultnya 3) — Jumlah saluran input.
image_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 1024) — Ukuran (resolusi) dari setiap gambar.
patch_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 16) — Ukuran (resolusi) dari setiap patch.
hidden_act (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
layer_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan.
attention_dropout (Union[float, int], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
initializer_range (float, opsional, defaultnya 1e-10) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
qkv_bias (bool, opsional, defaultnya True) — Apakah akan menambahkan bias ke queries, keys, dan values.
mlp_ratio (float, opsional, default 4.0) — Rasio dimensi tersembunyi MLP terhadap dimensi embedding.
use_abs_pos (bool, opsional, defaultnya True) — Apakah akan menggunakan embedding posisi absolut.
use_rel_pos (bool, opsional, default True) — Apakah akan menggunakan relative position embedding.
window_size (int, opsional, default 14) — Ukuran jendela untuk posisi relatif.
global_attn_indexes (list[int], opsional, default [2, 5, 8, 11]) — Indeks dari lapisan global attention.
num_pos_feats (int, opsional, default 128) — Dimensi dari position embedding.
mlp_dim (int, opsional) — Dimensi dari lapisan MLP dalam encoder Transformer. Jika None, defaultnya adalah mlp_ratio * hidden_size.

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

>>> from transformers import (
...     SamHQVisionConfig,
...     SamHQVisionModel,
... )

>>> # Initializing a SamHQVisionConfig with `"facebook/sam_hq-vit-huge"` style configuration
>>> configuration = SamHQVisionConfig()

>>> # Initializing a SamHQVisionModel (with random weights) from the `"facebook/sam_hq-vit-huge"` style configuration
>>> model = SamHQVisionModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

SamHQMaskDecoderConfig

kelas transformers.SamHQMaskDecoderConfig

< 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 = Nonehidden_size: int = 256hidden_act: str = 'relu'mlp_dim: int = 2048num_hidden_layers: int = 2num_attention_heads: int = 8attention_downsample_rate: int = 2num_multimask_outputs: int = 3iou_head_depth: int = 3iou_head_hidden_dim: int = 256layer_norm_eps: float = 1e-06vit_dim: int = 768 )

Parameter

hidden_size (int, opsional, default 256) — Dimensi dari representasi tersembunyi.
hidden_act (str, opsional, defaultnya relu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
mlp_dim (int, opsional, default 2048) — Dimensi dari lapisan “intermediate” (yaitu, feed-forward) dalam encoder Transformer.
num_hidden_layers (int, opsional, default 2) — Jumlah lapisan tersembunyi dalam decoder Transformer.
num_attention_heads (int, opsional, default 8) — Jumlah attention heads untuk setiap lapisan attention di decoder Transformer.
attention_downsample_rate (int, opsional, default 2) — Rasio downsampling dari lapisan attention.
num_multimask_outputs (int, opsional, default 3) — Jumlah output dari modul SamMaskDecoder. Dalam paper Segment Anything, nilai ini diatur ke 3.
iou_head_depth (int, opsional, default 3) — Jumlah lapisan dalam modul IoU head.
iou_head_hidden_dim (int, opsional, default 256) — Dimensi dari hidden states di dalam modul IoU head.
layer_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan.
vit_dim (int, opsional, default 768) — Dimensi dari Vision Transformer (ViT) yang digunakan dalam modul SamHQMaskDecoder.

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

SamHQPromptEncoderConfig

kelas transformers.SamHQPromptEncoderConfig

< source >

Parameter

hidden_size (int, opsional, default 256) — Dimensi dari representasi tersembunyi.
image_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 1024) — Ukuran (resolusi) dari setiap gambar.
patch_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 16) — Ukuran (resolusi) dari setiap patch.
mask_input_channels (int, opsional, default 16) — Jumlah channel yang akan diberikan ke modul MaskDecoder.
num_point_embeddings (int, opsional, defaultnya 4) — Jumlah point embeddings yang akan digunakan.
hidden_act (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
layer_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan.

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

SamHQProcessor

kelas transformers.SamHQProcessor

< source >

( image_processor )

Parameter

image_processor (SamImageProcessor) — Image processor adalah input yang wajib diisi.

Membangun SamHQProcessor yang membungkus image processor menjadi satu processor tunggal.

SamHQProcessor menyediakan semua fungsionalitas dari SamImageProcessor. Lihat ~SamImageProcessor untuk informasi lebih lanjut.

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] = None**kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'> ) → ~feature_extraction_utils.BatchFeature

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.
segmentation_maps (ImageInput, kwargs, opsional) — Peta segmentasi ground truth yang diproses bersama gambar input. Peta-peta ini digunakan untuk keperluan pelatihan atau evaluasi, dan di-resize serta dinormalisasi agar sesuai dengan dimensi gambar yang telah diproses.
input_points (NestedList, kwargs, opsional) — Titik input untuk segmentasi berbasis prompt. Harus berupa nested list dengan struktur [image_level, object_level, point_level, [x, y]] di mana setiap titik ditentukan sebagai koordinat [x, y] dalam ruang gambar asli. Titik-titik tersebut dinormalisasi ke ukuran gambar target sebelum diteruskan ke model.
input_labels (NestedList, kwargs, opsional) — Label untuk titik input, menunjukkan apakah setiap titik adalah foreground (1) atau background (0). Harus berupa nested list dengan struktur [image_level, object_level, point_level]. Harus memiliki struktur yang sama dengan input_points (kecuali dimensi koordinat).
input_boxes (NestedList, kwargs, opsional) — Bounding box untuk segmentasi berbasis prompt. Harus berupa nested list dengan struktur [image_level, box_level, [x1, y1, x2, y2]] di mana setiap box ditentukan sebagai koordinat [x1, y1, x2, y2] dalam ruang gambar asli. Box dinormalisasi ke ukuran gambar target sebelum diteruskan ke model.
point_pad_value (int, kwargs, opsional, default None) — Nilai yang digunakan untuk mengisi titik input saat melakukan batching pada urutan dengan panjang berbeda. Nilai ini menandai posisi yang di-*pad* dan dipertahankan selama normalisasi koordinat untuk membedakan titik asli dari *padding*. Jika None, nilai *pad* default dari konfigurasi prosesor akan digunakan.
mask_size (dict[str, *kwargs*, int], opsional) — Kamus yang menentukan ukuran target mask dengan kunci "height" dan "width". Hal ini menentukan resolusi dari mask segmentasi output yang dihasilkan oleh model.
mask_pad_size (dict[str, *kwargs*, int], opsional) — Kamus yang menentukan ukuran padding untuk mask dengan kunci "height" dan "width". Ini digunakan saat membatching mask dengan ukuran berbeda untuk memastikan dimensi yang konsisten.
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.

Mengembalikan

~feature_extraction_utils.BatchFeature

data (dict, opsional) — Kamus berisi daftar/array/tensor yang dikembalikan oleh metode call/pad (‘input_values’, ‘attention_mask’, dst.).
tensor_type (Union[None, str, TensorType], opsional) — Anda dapat memberikan tensor_type di sini untuk mengonversi daftar bilangan bulat menjadi Tensor PyTorch/Numpy saat inisialisasi.
skip_tensor_conversion (list[str] atau set[str], opsional) — Daftar atau himpunan kunci yang TIDAK boleh dikonversi menjadi tensor, bahkan ketika tensor_type ditentukan.

SamHQVisionModel

kelas transformers.SamHQVisionModel

< source >

( config: SamHQVisionConfig )

Parameter

config (SamHQVisionConfig) — 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 visi dari SamHQ tanpa head atau proyeksi 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] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → SamHQVisionEncoderOutput 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 SamImageProcessor. Lihat SamImageProcessor.call() untuk detailnya (SamHQProcessor menggunakan SamImageProcessor untuk memproses gambar).

Mengembalikan

SamHQVisionEncoderOutput atau tuple(torch.Tensor)

SamHQVisionEncoderOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (SamHQConfig) dan input.

Metode forward dari SamHQVisionModel 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.

image_embeds (torch.Tensor dengan bentuk (batch_size, output_dim) opsional dikembalikan saat model diinisialisasi dengan with_projection=True) — Embedding gambar yang diperoleh dengan menerapkan lapisan proyeksi ke pooler_output.
last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir model.
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 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.
attentions (tuple[torch.Tensor, ...], opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).
intermediate_embeddings (list(torch.Tensor), opsional) — Daftar embedding antara yang dikumpulkan dari blok-blok tertentu dalam model, biasanya blok yang tidak memiliki windowed attention. Setiap elemen dalam daftar ini memiliki bentuk (batch_size, sequence_length, hidden_size). Hal ini khusus untuk SAM-HQ dan tidak ada pada SAM dasar.

SamHQModel

kelas transformers.SamHQModel

< source >

( config: SamHQConfig )

Parameter

config (SamHQConfig) — 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.

Segment Anything Model HQ (SAM-HQ) untuk menghasilkan mask, berdasarkan gambar input dan lokasi 2D serta bounding box opsional.

forward

< source >

( pixel_values: typing.Optional[torch.Tensor] = Noneinput_points: typing.Optional[torch.Tensor] = Noneinput_labels: typing.Optional[torch.LongTensor] = Noneinput_boxes: typing.Optional[torch.Tensor] = Noneinput_masks: typing.Optional[torch.LongTensor] = Noneimage_embeddings: typing.Optional[torch.Tensor] = Nonemultimask_output: bool = Truehq_token_only: bool = Falseattention_similarity: typing.Optional[torch.Tensor] = Nonetarget_embedding: typing.Optional[torch.Tensor] = Noneintermediate_embeddings: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

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 SamImageProcessor. Lihat SamImageProcessor.call() untuk detailnya (SamHQProcessor menggunakan SamImageProcessor untuk memproses gambar).
input_points (torch.Tensor dengan bentuk (batch_size, num_points, 2)) — Titik spasial 2D sebagai input, yang digunakan oleh prompt encoder untuk mengkodekan prompt. Umumnya menghasilkan hasil yang jauh lebih baik. Titik-titik ini dapat diperoleh dengan meneruskan daftar dari daftar dari daftar ke processor yang akan membuat tensor torch yang sesuai dengan dimensi 4. Dimensi pertama adalah ukuran batch gambar, dimensi kedua adalah ukuran batch titik (yaitu berapa banyak mask segmentasi yang ingin diprediksi model per titik input), dimensi ketiga adalah jumlah titik per mask segmentasi (dimungkinkan untuk meneruskan beberapa titik untuk satu mask), dan dimensi terakhir adalah koordinat x (vertikal) dan y (horizontal) dari titik tersebut. Jika jumlah titik yang berbeda diteruskan baik untuk setiap gambar, maupun untuk setiap mask, processor akan membuat titik “PAD” yang akan sesuai dengan koordinat (0, 0), dan perhitungan embedding akan dilewati untuk titik-titik ini menggunakan label.
input_labels (torch.LongTensor dengan bentuk (batch_size, point_batch_size, num_points)) — Label input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Menurut implementasi resmi, terdapat 3 jenis label
- 1: titik tersebut adalah titik yang berisi objek yang diminati
- 0: titik tersebut adalah titik yang tidak mengandung objek yang diminati
- -1: titik tersebut sesuai dengan latar belakang
Kami menambahkan label:
- -10: titik tersebut adalah titik padding, sehingga harus diabaikan oleh prompt encoder
Label padding seharusnya dilakukan secara otomatis oleh processor.
input_boxes (torch.Tensor dengan bentuk (batch_size, num_boxes, 4)) — kotak input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Umumnya menghasilkan mask yang jauh lebih baik. Kotak-kotak ini dapat diperoleh dengan meneruskan list of list of list ke processor, yang akan menghasilkan torch tensor, dengan setiap dimensi yang masing-masing sesuai dengan ukuran batch gambar, jumlah kotak per gambar, dan koordinat titik kiri atas dan kanan bawah kotak. Dalam urutan (x1, y1, x2, y2):
- x1: koordinat x dari titik kiri atas kotak input
- y1: koordinat y dari titik kiri atas kotak input
- x2: koordinat x dari titik kanan bawah kotak input
- y2: koordinat y dari titik kanan bawah kotak input
input_masks (torch.Tensor dengan bentuk (batch_size, image_size, image_size)) — Model SAM_HQ juga menerima mask segmentasi sebagai input. Mask akan di-embed oleh prompt encoder untuk menghasilkan embedding yang sesuai, yang kemudian akan diberikan ke mask decoder. Mask ini perlu diberikan secara manual oleh pengguna, dan harus memiliki bentuk (batch_size, image_size, image_size).
image_embeddings (torch.Tensor dengan bentuk (batch_size, output_channels, window_size, window_size)) — Embedding gambar, yang digunakan oleh mask decoder untuk menghasilkan mask dan skor iou. Untuk komputasi yang lebih hemat memori, pengguna dapat terlebih dahulu mengambil embedding gambar menggunakan metode get_image_embeddings, lalu memasukkannya ke metode forward alih-alih memasukan pixel_values.
multimask_output (bool, opsional) — Pada implementasi dan paper aslinya, model selalu menghasilkan 3 mask per gambar (atau per titik / per bounding box jika relevan). Namun, dimungkinkan untuk hanya menghasilkan satu mask, yang sesuai dengan mask “terbaik”, dengan menentukan multimask_output=False.
hq_token_only (bool, opsional, default False) — Apakah hanya menggunakan jalur token HQ untuk pembuatan mask. Jika False, menggabungkan kedua jalur standar dan HQ. Ini spesifik untuk arsitektur SAM-HQ.
attention_similarity (torch.Tensor, opsional) — Tensor kesamaan perhatian, yang akan diberikan ke decoder mask untuk perhatian yang dipandu target dalam kasus model digunakan untuk personalisasi sebagaimana diperkenalkan dalam PerSAM.
target_embedding (torch.Tensor, opsional) — Embedding dari konsep target, yang harus diberikan ke mask decoder untuk target-semantic prompting dalam kasus model digunakan untuk personalisasi sebagaimana diperkenalkan dalam PerSAM.
intermediate_embeddings (List[torch.Tensor], opsional) — Embedding perantara dari blok non-windowed vision encoder, digunakan oleh SAM-HQ untuk meningkatkan kualitas mask. Wajib diisi saat menyediakan image_embeddings yang sudah dihitung sebelumnya, bukan pixel_values.

Metode forward dari SamHQModel 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.

Contoh:

>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("sushmanth/sam_hq_vit_b")
>>> processor = AutoProcessor.from_pretrained("sushmanth/sam_hq_vit_b")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=image, input_points=input_points, return_tensors="pt")

>>> # Get high-quality segmentation mask
>>> outputs = model(**inputs)

>>> # For high-quality mask only
>>> outputs = model(**inputs, hq_token_only=True)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"], inputs["reshaped_input_sizes"]
... )

Update on GitHub

←Segment Anything SuperGlue→