Transformers documentation
FocalNet
Este modelo foi publicado no HF papers em 2022-03-22 e contribuído para o Hugging Face Transformers em 2023-04-23.
FocalNet
Visão geral
O modelo FocalNet foi proposto em Focal Modulation Networks por Jianwei Yang, Chunyuan Li, Xiyang Dai, Lu Yuan e Jianfeng Gao. Os FocalNets substituem completamente a autoatenção (usada em modelos como ViT e Swin) por um mecanismo de modulação focal para modelar as interações entre tokens em visão. Os autores afirmam que os FocalNets superam modelos baseados em autoatenção com custos computacionais semelhantes nas tarefas de classificação de imagem, detecção de objetos e segmentação.
O resumo do artigo é o seguinte:
Propomos as redes de modulação focal (FocalNets, em breve), nas quais a autoatenção (SA) é completamente substituída por um mecanismo de modulação focal para modelar as interações entre tokens em visão. A modulação focal compreende três componentes: (i) contextualização hierárquica, implementada usando uma pilha de camadas de convolução em profundidade, para codificar contextos visuais de curto a longo alcance, (ii) agregação com gate para coletar seletivamente contextos para cada token de consulta com base em seu conteúdo, e (iii) modulação elemento a elemento ou transformação afim para injetar o contexto agregado na consulta. Experimentos extensivos mostram que os FocalNets superam os equivalentes de SA do estado da arte (por exemplo, Swin e Focal Transformers) com custos computacionais semelhantes nas tarefas de classificação de imagem, detecção de objetos e segmentação. Especificamente, FocalNets com tamanho tiny e base alcançam 82,3% e 83,9% de precisão top-1 no ImageNet-1K. Após o pré-treinamento no ImageNet-22K em resolução 224, ele atinge 86,5% e 87,3% de precisão top-1 quando ajustado com resolução 224 e 384, respectivamente. Quando transferidos para tarefas de baixo nível, os FocalNets exibem superioridade clara. Para detecção de objetos com Mask R-CNN, o FocalNet base treinado com 1\times supera o equivalente Swin em 2,1 pontos e já supera o Swin treinado com agendamento 3\times (49,0 v.s. 48,5). Para segmentação semântica com UPerNet, o FocalNet base em escala única supera o Swin em 2,4 e vence o Swin em multi-escala (50,5 v.s. 49,7). Usando o FocalNet grande e o Mask2former, alcançamos 58,5 mIoU para segmentação semântica ADE20K e 57,9 PQ para Segmentação Panóptica COCO. Usando o FocalNet enorme e o DINO, alcançamos 64,3 e 64,4 mAP no COCO minival e test-dev, respectivamente, estabelecendo novo SoTA em cima de modelos baseados em atenção muito maiores, como Swinv2-G e BEIT-3.
Este modelo foi contribuído por nielsr. O código original pode ser encontrado aqui.
FocalNetConfig
classe 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 )
Parâmetros
- image_size (
Union[int, list[int], tuple[int, int]], opcional, padrão224) — O tamanho (resolução) de cada imagem. - patch_size (
Union[int, list[int], tuple[int, int]], opcional, padrão4) — O tamanho (resolução) de cada patch. - num_channels (
int, opcional, padrão3) — O número de canais de entrada. - embed_dim (
int, opcional, padrão96) — Dimensão dos embeddings e dos estados ocultos. - use_conv_embed (
bool, opcional, padrãoFalse) — Se deve usar incorporação convolucional. Os autores observaram que o uso de incorporação convolucional geralmente melhora o desempenho, mas não é usado por padrão. - hidden_sizes (
Union[list[int], tuple[int, ...]], opcional, padrão(192, 384, 768, 768)) — Dimensão (tamanho oculto) em cada etapa do modelo. - depths (
Union[list[int], tuple[int, ...]], opcional, padrão(2, 2, 6, 2)) — Profundidade de cada camada no Transformer. - focal_levels (
list(int), opcional, padrão[2, 2, 2, 2]) — Número de níveis focais em cada camada dos respectivos estágios no codificador. - focal_windows (
list(int), opcional, padrão[3, 3, 3, 3]) — Tamanho da janela focal em cada camada dos respectivos estágios no codificador. - hidden_act (
str, opcional, padrãogelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo,"gelu","relu","silu", etc. - mlp_ratio (
float, opcional, padrão4.0) — Proporção entre a dimensão oculta do MLP e a dimensão de incorporação. - hidden_dropout_prob (
float, opcional, padrão 0.0) — A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings e no codificador. - drop_path_rate (
Union[float, int], opcional, padrão0.1) — Taxa de drop path para a fusão de patches. - use_layerscale (
bool, opcional, padrãoFalse) — Se deve usar layer scale no encoder. - layerscale_value (
float, opcional, padrão 0.0001) — O valor inicial da escala da camada. - use_post_layernorm (
bool, opcional, padrãoFalse) — Se deve usar normalização de camada pós-encoder. - use_post_layernorm_in_modulation (
bool, opcional, padrãoFalse) — Se deve usar normalização de camada posterior na camada de modulação. - normalize_modulator (
bool, opcional, padrãoFalse) — Se deve normalizar o modulator. - initializer_range (
float, opcional, padrão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - layer_norm_eps (
float, opcional, padrão1e-05) — O epsilon usado pelas camadas de normalização de camada. - encoder_stride (
int, opcional, padrão 32) — Fator pelo qual a resolução espacial é aumentada na cabeça do decodificador para modelagem de imagens mascaradas.
Esta é a classe de configuração para armazenar a configuração de um FocalNetModel. Ela é usada para instanciar um modelo Focalnet de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do microsoft/focalnet-tiny
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplo:
>>> 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
classe transformers.FocalNetModel
< source >( config: FocalNetConfigadd_pooling_layer = Trueuse_mask_token = False )
Parâmetros
- config (FocalNetConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
- add_pooling_layer (
bool, opcional, padrãoTrue) — Se deve adicionar uma camada de pooling - use_mask_token (
bool, opcional, padrãoFalse) — Se deve usar um token de máscara para modelagem de imagem mascarada.
O modelo Focalnet puro, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( pixel_values: typing.Optional[torch.FloatTensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetModelOutput or tuple(torch.FloatTensor)
Parâmetros
- pixel_values (
torch.FloatTensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando BitImageProcessor. Consulte BitImageProcessor.call() para detalhes (processor_classusa BitImageProcessor para processar imagens). - bool_masked_pos (
torch.BoolTensorde forma(batch_size, num_patches)) — Posições mascaradas booleanas. Indica quais patches estão mascarados (1) e quais não estão (0). - output_hidden_states (
bool, opcional) — Indica se as hidden states de todas as camadas devem ser retornadas. Consultehidden_statesem tensors retornados para mais detalhes. - return_dict (
bool, opcional) — Indica se deve retornar um ModelOutput em vez de uma tupla simples.
Retorna
FocalNetModelOutput ou tuple(torch.FloatTensor)
Um FocalNetModelOutput ou uma tupla de
torch.FloatTensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (FocalNetConfig) e das entradas.
O método forward do FocalNetModel substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
last_hidden_state (
torch.FloatTensorde forma(batch_size, sequence_length, hidden_size), opcional) — Sequência de hidden-states na saída da última camada do modelo.pooler_output (
torch.FloatTensorde forma(batch_size, hidden_size), opcional, retornado quandoadd_pooling_layer=Trueé passado) — Average pooling do hidden-state da última camada.hidden_states (
tuple[torch.FloatTensor], opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
reshaped_hidden_states (
tuple(torch.FloatTensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings + uma para a saída de cada estágio) de forma(batch_size, hidden_size, height, width).Estados ocultos do modelo na saída de cada camada, mais as saídas do embedding inicial, redimensionados para incluir as dimensões espaciais.
FocalNetForMaskedImageModeling
classe transformers.FocalNetForMaskedImageModeling
< source >( config: FocalNetConfig )
Parâmetros
- config (FocalNetConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
Modelo FocalNet com um decodificador no topo para modelagem de imagem mascarada.
Isso segue a mesma implementação do SimMIM.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( pixel_values: typing.Optional[torch.FloatTensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetMaskedImageModelingOutput or tuple(torch.FloatTensor)
Parâmetros
- pixel_values (
torch.FloatTensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando BitImageProcessor. Consulte BitImageProcessor.call() para detalhes (processor_classusa BitImageProcessor para processar imagens). - bool_masked_pos (
torch.BoolTensorde forma(batch_size, num_patches)) — Posições mascaradas booleanas. Indica quais patches estão mascarados (1) e quais não estão (0). - output_hidden_states (
bool, opcional) — Indica se as hidden states de todas as camadas devem ser retornadas. Consultehidden_statesem tensors retornados para mais detalhes. - return_dict (
bool, opcional) — Indica se deve retornar um ModelOutput em vez de uma tupla simples.
Retorna
FocalNetMaskedImageModelingOutput ou tuple(torch.FloatTensor)
Um FocalNetMaskedImageModelingOutput ou uma tupla de
torch.FloatTensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (FocalNetConfig) e das entradas.
O método forward de FocalNetForMaskedImageModeling substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
loss (
torch.FloatTensorde forma(1,), opcional, retornado quandobool_masked_posé fornecido) — Perda de modelagem de imagem mascarada (MLM).reconstrução (
torch.FloatTensorde forma(batch_size, num_channels, height, width)) — Valores de pixels reconstruídos.hidden_states (
tuple[torch.FloatTensor], opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
reshaped_hidden_states (
tuple(torch.FloatTensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings + uma para a saída de cada estágio) de forma(batch_size, hidden_size, height, width).Estados ocultos do modelo na saída de cada camada, mais as saídas do embedding inicial, redimensionados para incluir as dimensões espaciais.
Exemplos:
>>> 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
classe transformers.FocalNetForImageClassification
< source >( config: FocalNetConfig )
Parâmetros
- config (FocalNetConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
Modelo FocalNet com uma cabeça de classificação de imagem no topo (uma camada linear sobre a saída agregada), por exemplo, para o ImageNet.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( pixel_values: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetImageClassifierOutput or tuple(torch.FloatTensor)
Parâmetros
- pixel_values (
torch.FloatTensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando BitImageProcessor. Consulte BitImageProcessor.call() para detalhes (processor_classusa BitImageProcessor para processar imagens). - labels (
torch.LongTensorde forma(batch_size,), opcional) — Rótulos para o cálculo da perda de classificação/regressão de imagem. Os índices devem estar em[0, ..., config.num_labels - 1]. Seconfig.num_labels == 1, uma perda de regressão é calculada (perda de erro quadrático médio); seconfig.num_labels > 1, uma perda de classificação é calculada (entropia cruzada). - output_hidden_states (
bool, opcional) — Indica se as hidden states de todas as camadas devem ser retornadas. Consultehidden_statesem tensors retornados para mais detalhes. - return_dict (
bool, opcional) — Indica se deve retornar um ModelOutput em vez de uma tupla simples.
Retorna
FocalNetImageClassifierOutput ou tuple(torch.FloatTensor)
Um FocalNetImageClassifierOutput ou uma tupla de
torch.FloatTensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (FocalNetConfig) e das entradas.
O método forward de FocalNetForImageClassification sobrescreve o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
loss (
torch.FloatTensorde forma(1,), opcional, retornado quandolabelsé fornecido) — Perda de classificação (ou de regressão se config.num_labels==1).logits (
torch.FloatTensorde forma(batch_size, config.num_labels)) — Pontuações de classificação (ou regressão, se config.num_labels==1) (antes do SoftMax).hidden_states (
tuple[torch.FloatTensor], opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
reshaped_hidden_states (
tuple(torch.FloatTensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.FloatTensor(uma para a saída dos embeddings + uma para a saída de cada estágio) de forma(batch_size, hidden_size, height, width).Estados ocultos do modelo na saída de cada camada, mais as saídas do embedding inicial, redimensionados para incluir as dimensões espaciais.
Exemplo:
>>> 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])
...