# MiSS

[MiSS (Matrix Shard Sharing)](https://arxiv.org/abs/2409.15371) é um método PEFT que alcança um bom equilíbrio entre o desempenho do modelo e a eficiência computacional. Ele requer apenas uma única matriz treinável e introduz um mecanismo de compartilhamento de shards distinto do LoRA.

O resumo do artigo é:

*Métodos de Fine-Tuning Eficiente em Parâmetros (PEFT), em particular a Low-Rank Adaptation (LoRA), reduzem eficazmente o número de parâmetros treináveis em Large Language Models (LLMs). No entanto, à medida que a escala dos modelos continua a crescer, a demanda por recursos computacionais permanece um desafio significativo. Variantes existentes de LoRA frequentemente têm dificuldade em atingir um equilíbrio ótimo entre adaptabilidade (desempenho do modelo e velocidade de convergência) e eficiência (sobrecarga computacional, uso de memória e tempo de inicialização). Este artigo introduz o MiSS (Matrix Shard Sharing), uma nova abordagem de PEFT que aborda esse trade-off por meio de um mecanismo simples de compartilhamento de shards. O MiSS aproveita o insight de que uma adaptação de baixo rank pode ser alcançada decompondo a matriz de pesos em múltiplas matrizes fragmentadas e utilizando um fragmento comum compartilhado e treinável. Este método constrói a matriz de atualização de baixo rank por meio da replicação desses shards compartilhados e particionados. Também propomos uma implementação eficiente em hardware e amplamente aplicável para o MiSS. Experimentos extensos conduzidos em uma variedade de tarefas, juntamente com uma análise sistemática do desempenho computacional, demonstram a superioridade do MiSS. Os resultados mostram que o MiSS supera significativamente o LoRA padrão e suas variantes proeminentes tanto nas métricas de desempenho do modelo quanto na eficiência computacional, incluindo a velocidade de inicialização e o throughput de treinamento. Ao equilibrar eficazmente o poder expressivo e a utilização de recursos, o MiSS oferece uma solução convincente para a adaptação eficiente de modelos em larga escala.*

## Visão geral do benchmark

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=MISS" frameborder="0" width="850" height="1000"
>

## Quando usar o MiSS

MiSS é uma boa escolha quando:

- Você deseja uma inicialização mais rápida e um maior rendimento de treinamento do que os esquemas avançados de inicialização de LoRA que usam configurações caras (como PiSSA, LoRA-GA ou OLoRA).
- Você quer uma alternativa drop-in para o LoRA com mudanças mínimas de configuração.

Se você precisar de uma expressividade maior, mesmo que custe alguma eficiência, considere a variante de inicialização `bat` (veja abaixo).

## modos de init_weights

O MiSS suporta três modos de inicialização por meio do parâmetro `init_weights`:

- `True` (padrão): inicialização padrão do MiSS. Ponto de partida ideal para a maioria dos casos de uso.
- `"bat"`: Habilita atualizações não lineares entre diferentes shards. Produz melhores resultados que o MiSS padrão, mas usa mais memória e é aproximadamente duas vezes mais lento. Use esta opção quando o desempenho for prioridade em relação à eficiência.
- `"mini"`: Usa um rank menor ao longo da dimensão `out_features`, controlado por `mini_r`. Isso reduz ainda mais os parâmetros treináveis. Ao usar este modo, `mini_r` deve ser definido e `out_features` deve ser divisível por `mini_r`.

## Início rápido

```python
import torch
from peft import MissConfig, get_peft_model
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")
tokenizer.pad_token_id = tokenizer.eos_token_id

# Standard MiSS
config = MissConfig(
    r=64,
    miss_dropout=0.01,
    task_type="CAUSAL_LM"
)

# BAT variant — better performance, more memory
# config = MissConfig(
#     r=64,
#     init_weights="bat",
#     task_type="CAUSAL_LM"
# )

# Mini variant — fewer trainable parameters
# config = MissConfig(
#     r=64,
#     init_weights="mini",
#     mini_r=8,
#     task_type="CAUSAL_LM"
# )

model = get_peft_model(model, config)
model.print_healthcheck()
```

Para um exemplo completo de fine-tuning, incluindo treinamento e inferência, consulte o [exemplo de fine-tuning do MiSS](https://github.com/huggingface/peft/tree/main/examples/miss_finetuning).

# API

## MissConfig[[peft.MissConfig]]

#### peft.MissConfig[[peft.MissConfig]]

```python
peft.MissConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 64, miss_dropout: float = 0.0, mini_r: int = 1, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, init_weights: bool | Literal['bat', 'mini'] = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[str] = None, bias: str = 'none', modules_to_save: Optional[list[str]] = None)
```

[Fonte](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/miss/config.py#L25)

**Parâmetros:**

r (`int`) : O rank do MiSS entre as diferentes camadas. É recomendável definir 'r' como um número par; caso contrário, o método de inicialização padrão não funcionará. O rank do MiSS corresponde a uma decomposição de baixo rank ao longo da dimensão in_features.

miss_dropout (`float`) : A probabilidade de dropout para as camadas MiSS.

mini_r (`int`) : O rank do MiSS corresponde a uma decomposição de baixo rank ao longo da dimensão out_features. Quando você define `init_weights=mini`, é necessário definir `mini_r`. Certifique-se de que `out_features` seja divisível por `mini_r`.

target_modules (`Optional[Union[List[str], str]]`) : Os nomes dos módulos aos quais o adaptador será aplicado. Se especificado, apenas os módulos com os nomes indicados serão substituídos. Ao passar uma string, será realizada uma correspondência por expressão regular. Ao passar uma lista de strings, será realizada uma correspondência exata ou será verificado se o nome do módulo termina com qualquer uma das strings passadas. Se especificado como 'all-linear', todos os módulos lineares serão selecionados, excluindo a camada de saída. Se não for especificado, os módulos serão escolhidos de acordo com a arquitetura do modelo. Se a arquitetura não for conhecida, um erro será lançado — nesse caso, você deve especificar os módulos de destino manualmente.

exclude_modules (`Optional[Union[List[str], str]]`) : Os nomes dos módulos aos quais o adaptador não deve ser aplicado. Ao passar uma string, será realizada uma correspondência por regex. Ao passar uma lista de strings, será realizada uma correspondência exata ou será verificado se o nome do módulo termina com qualquer uma das strings passadas.

init_weights (bool | Literal["bat", "mini"]) : Inicializações diferentes correspondem a diferentes variantes de MiSS. Por padrão (balance), o método mais eficiente e geral do MiSS será utilizado. 'bat': Neste modo, você pode habilitar atualizações não lineares entre diferentes shards. 'mini': Neste modo, você pode definir um rank menor para usar menos parâmetros treináveis, mas é recomendado manter `out_features % mini_r == 0`.

layers_to_transform (`Union[List[int], int]`) : Os índices das camadas a serem transformadas. Se uma lista de inteiros for passada, o adaptador será aplicado aos índices das camadas especificados nesta lista. Se um único inteiro for passado, as transformações serão aplicadas à camada neste índice.

layers_pattern (`str`) : O nome do padrão da camada, usado apenas se `layers_to_transform` for diferente de `None`.

bias (`str`) : Tipo de viés para MiSS. Pode ser `'none'`, `'all'` ou `'MiSS_only'`.

modules_to_save (`List[str]`) : Lista de módulos, exceto as camadas de adaptador, que devem ser configurados como treináveis e salvos no checkpoint final.

Esta é a classe de configuração para armazenar a configuração de um [MissModel](/docs/peft/v0.22.0/pt/package_reference/miss#peft.MissModel).

## MissModel[[peft.MissModel]]

#### peft.MissModel[[peft.MissModel]]

```python
peft.MissModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Fonte](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/miss/model.py#L38)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo ao qual as camadas do adaptador tuner serão anexadas.

config ([MissConfig](/docs/peft/v0.22.0/pt/package_reference/miss#peft.MissConfig)) : A configuração do modelo MiSS.

adapter_name (`str`) : O nome do adaptador, padrão é `"default"`.

low_cpu_mem_usage (`bool`, `optional`, padrão `False`) : Cria pesos de adaptador vazios no dispositivo meta. Útil para acelerar o processo de carregamento.

**Retorna:** `torch.nn.Module`

O modelo MiSS.

Cria um modelo de Compartilhamento de Fragmentos de Matriz (MiSS) a partir de um modelo pré-treinado. O método é descrito em https://huggingface.co/papers/2409.15371

Exemplo:
```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import MissConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = MissConfig(r=64)
>>> model = get_peft_model(base_model, config)
```

**Atributos**:
- **model** (`~torch.nn.Module`) -- O modelo a ser adaptado.
- **peft_config** ([MissConfig](/docs/peft/v0.22.0/pt/package_reference/miss#peft.MissConfig)): A configuração do modelo MiSS.

