# PEFT[[transformers.integrations.PeftAdapterMixin]] O [PeftAdapterMixin](/docs/transformers/main/pt/main_classes/peft#transformers.integrations.PeftAdapterMixin) fornece funções da biblioteca [PEFT](https://huggingface.co/docs/peft/index) para gerenciar adaptadores com o Transformers. Este mixin suporta todos os métodos PEFT que não envolvem aprendizado de prompt (LoRA, IA3, AdaLoRA, entre outros). Os métodos de prefix tuning (prompt tuning, prompt learning) não são suportados, pois não podem ser injetados em um módulo torch. #### transformers.integrations.PeftAdapterMixin[[transformers.integrations.PeftAdapterMixin]] ```python transformers.integrations.PeftAdapterMixin() ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L57) Uma classe que contém todas as funções para carregar e usar pesos de adaptadores suportados na biblioteca PEFT. Para mais detalhes sobre adaptadores e sua injeção em um modelo baseado em transformer, consulte a documentação da biblioteca PEFT: https://huggingface.co/docs/peft/index Os métodos PEFT atualmente suportados são todos métodos de aprendizado não baseados em prompts (LoRA, IA³, etc.). Outros modelos PEFT, como prompt tuning e prompt learning, estão fora do escopo, pois esses adaptadores não são "injetáveis" em um módulo do torch. Para usar esses métodos, consulte o guia de uso da biblioteca PEFT. Com este mixin, se a versão correta do PEFT estiver instalada (>= 0.20.0), é possível: - Carregue um adaptador armazenado em um caminho local ou em um repositório remoto do Hub e injete-o no modelo - Anexe novos adaptadores ao modelo e treine-os com o Trainer ou por conta própria. - Anexe vários adaptadores e ative/desative-os iterativamente - Ative / desative todos os adaptadores do modelo. - Obtenha o `state_dict` do adaptador ativo. #### load_adapter[[transformers.integrations.PeftAdapterMixin.load_adapter]] ```python load_adapter(peft_model_id: str | None = None, adapter_name: str | None = None, peft_config: dict[str, typing.Any] | None = None, adapter_state_dict: dict[str, 'torch.Tensor'] | None = None, low_cpu_mem_usage: bool = False, is_trainable: bool = False, hotswap: typing.Union[bool, typing.Literal['auto']] = 'auto', local_files_only: bool = False, adapter_kwargs: dict[str, typing.Any] | None = None, load_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L80) **Parâmetros:** peft_model_id (`str`, *opcional*) : O identificador do modelo a ser procurado no Hub, ou um caminho local para o arquivo de configuração do adaptador e os pesos do adaptador salvos. adapter_name (`str`, *opcional*) : O nome do adaptador a ser usado. Se não for definido, o nome "default" será utilizado. load_config (`LoadStateDictConfig`, *opcional*) : Uma configuração de carregamento para reutilizar ao obter os pesos do adaptador, normalmente de `from_pretrained`. kwargs (`dict[str, Any]`, *opcional*) : Campos adicionais de `LoadStateDictConfig` passados como argumentos de palavra-chave. peft_config (`dict[str, Any]`, *opcional*) : A configuração do adaptador a ser adicionado; os adaptadores suportados são todas as configurações de aprendizado não baseado em prompt (LoRA, IA³, etc). Este argumento é utilizado quando os usuários passam diretamente os dicionários de estado do PEFT. adapter_state_dict (`dict[str, torch.Tensor]`, *opcional*) : O state dict do adaptador a ser carregado. Este argumento é utilizado quando os usuários passam diretamente state dicts do PEFT. low_cpu_mem_usage (`bool`, *opcional*, padrão `False`) : Reduz o uso de memória ao carregar o adaptador PEFT. Isso também deve acelerar o processo de carregamento. is_trainable (`bool`, *opcional*, padrão `False`) : Se o adaptador deve ser treinável ou não. Se `False`, o adaptador será congelado e poderá ser usado apenas para inferência. hotswap : (`"auto"` ou `bool`, *opcional*, padrão `"auto"`) Se deve substituir um adaptador (LoRA) existente pelo adaptador recém-carregado no local. Isso significa que, em vez de carregar um adaptador adicional, isso pegará os pesos do adaptador existente e os substituirá pelos pesos do novo adaptador. Isso pode ser mais rápido e eficiente em termos de memória. No entanto, a principal vantagem do hotswap é que, quando o modelo é compilado com torch.compile, o carregamento do novo adaptador não requer a recompilação do modelo. Ao usar hotswap, o `adapter_name` passado deve ser o nome de um adaptador já carregado. Se o novo adaptador e o antigo tiverem ranks e/ou alfas LoRA (ou seja, escalonamento) diferentes, você precisa chamar um método adicional antes de carregar o adaptador: ```py model = AutoModel.from_pretrained(...) max_rank = ... # the highest rank among all LoRAs that you want to load # call *before* compiling and loading the LoRA adapter model.enable_peft_hotswap(target_rank=max_rank) model.load_adapter(file_name_1, adapter_name="default") # optionally compile the model now model = torch.compile(model, ...) output_1 = model(...) # now you can hotswap the 2nd adapter, use the same name as for the 1st # hotswap is activated by default since enable_peft_hotswap was called model.load_adapter(file_name_2, adapter_name="default") output_2 = model(...) ``` Por padrão, o hotswap está desativado e requer a passagem de `hotswap=True`. Se você chamou `enable_peft_hotswap` primeiro, ele está ativado. Você ainda pode desativá-lo manualmente nesse caso passando `hotswap=False`. Observe que o hotswap vem com algumas limitações documentadas aqui: https://huggingface.co/docs/peft/main/en/package_reference/hotswap adapter_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palavra-chave adicionais passados para o método `from_pretrained` da configuração do adaptador e para o método `find_adapter_config_file`. Carrega os pesos do adaptador de um arquivo ou de uma pasta remota no Hub. Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Exige que o PEFT esteja instalado como backend para carregar os pesos do adaptador. #### add_adapter[[transformers.integrations.PeftAdapterMixin.add_adapter]] ```python add_adapter(adapter_config, adapter_name: str | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L390) **Parâmetros:** adapter_config (`~peft.PeftConfig`) : A configuração do adaptador a ser adicionado; os adaptadores suportados são métodos de aprendizado sem prompt (LoRA, IA³, etc.). adapter_name (`str`, *opcional*, padrão `"default"`) : O nome do adaptador a ser adicionado. Se nenhum nome for fornecido, um nome padrão será atribuído ao adaptador. Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Adiciona um novo adaptador ao modelo atual para fins de treinamento. Se nenhum nome de adaptador for fornecido, um nome padrão será atribuído ao adaptador, seguindo a convenção da biblioteca PEFT (no PEFT, usamos "default" como nome padrão do adaptador). Observe que o adaptador recém-adicionado não é ativado automaticamente. Para ativá-lo, use `model.set_adapter`. #### set_adapter[[transformers.integrations.PeftAdapterMixin.set_adapter]] ```python set_adapter(adapter_name: list[str] | str) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L430) **Parâmetros:** adapter_name (`Union[list[str], str]`) : O nome do adaptador a ser definido. Também pode ser uma lista de strings para definir vários adaptadores. Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Define um adaptador específico, forçando o modelo a usar esse adaptador e desativando os outros adaptadores. #### disable_adapters[[transformers.integrations.PeftAdapterMixin.disable_adapters]] ```python disable_adapters() ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L471) Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Desative todos os adaptadores anexados ao modelo. Isso resulta na inferência usando apenas o modelo base. #### enable_adapters[[transformers.integrations.PeftAdapterMixin.enable_adapters]] ```python enable_adapters() ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L490) Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Ative os adaptadores que estão acoplados ao modelo. #### enable_peft_hotswap[[transformers.integrations.PeftAdapterMixin.enable_peft_hotswap]] ```python enable_peft_hotswap(target_rank: int = 128, check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error') ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L353) **Parâmetros:** target_rank (`int`, *opcional*, padrão `128`) : O maior rank entre todos os adaptadores que serão carregados. check_compiled (`str`, *opcional*, padrão `"error"`) : Como lidar com o caso em que o modelo já está compilado, o que geralmente deve ser evitado. As opções são: - "error" (padrão): levantar um erro - "warn": emitir um aviso - "ignore": não fazer nada Permite a possibilidade de trocar dinamicamente adaptadores PEFT com diferentes ranks ou, se o modelo estiver compilado, sem acionar a recompilação. No momento, o hotswapping é suportado apenas para LoRA. A chamada deste método é necessária apenas ao trocar adaptadores dinamicamente (hotswap) e quando o modelo está compilado ou quando os ranks dos adaptadores carregados diferem. Se os ranks forem todos idênticos e o modelo não estiver compilado, a troca dinâmica de adaptadores funciona sem a necessidade de chamar este método primeiro. #### active_adapters[[transformers.integrations.PeftAdapterMixin.active_adapters]] ```python active_adapters() ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L508) Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Obtém os adaptadores ativos atuais do modelo. No caso de inferência com múltiplos adaptadores (combinação de vários adaptadores para inferência), retorna a lista de todos os adaptadores ativos para que os usuários possam tratá-los de forma adequada. Para versões anteriores do PEFT (que não suportam inferência multi-adapter), `module.active_adapter` retornará uma única string. #### get_adapter_state_dict[[transformers.integrations.PeftAdapterMixin.get_adapter_state_dict]] ```python get_adapter_state_dict(adapter_name: str | None = None, state_dict: dict | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L537) **Parâmetros:** adapter_name (`str`, *opcional*) : O nome do adaptador do qual obter o state dict. Se nenhum nome for fornecido, o adaptador ativo será utilizado. state_dict (dicionário aninhado de `torch.Tensor`, *opcional*) : O dicionário de estado do modelo. O padrão será `self.state_dict()`, mas pode ser usado quando forem necessárias precauções especiais ao recuperar o dicionário de estado de um modelo (como ao usar paralelismo de modelo). Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na documentação oficial do PEFT: https://huggingface.co/docs/peft Obtém o dicionário de estado do adaptador, que deve conter apenas os tensores de pesos do adaptador especificado por adapter_name. Se nenhum adapter_name for fornecido, o adaptador ativo será utilizado. #### delete_adapter[[transformers.integrations.PeftAdapterMixin.delete_adapter]] ```python delete_adapter(adapter_names: list[str] | str) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L622) **Parâmetros:** adapter_names (`Union[list[str], str]`) : O(s) nome(s) do(s) adaptador(es) a ser(em) excluído(s). Exclua um adaptador PEFT do modelo subjacente.