Transformers documentation
PEFT
PEFT
O PeftAdapterMixin fornece funções da biblioteca PEFT 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.
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 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_dictdo adaptador ativo.
load_adapter
< source >( peft_model_id: str | None = Noneadapter_name: str | None = Nonepeft_config: dict[str, typing.Any] | None = Noneadapter_state_dict: dict[str, 'torch.Tensor'] | None = Nonelow_cpu_mem_usage: bool = Falseis_trainable: bool = Falsehotswap: typing.Union[bool, typing.Literal['auto']] = 'auto'local_files_only: bool = Falseadapter_kwargs: dict[str, typing.Any] | None = Noneload_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None**kwargs )
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 salvo e os pesos do adaptador. - adapter_name (
str, opcional) — O nome do adaptador a ser usado. Se não for definido, será usado o nome “default”. - load_config (
LoadStateDictConfig, opcional) — Uma configuração de carregamento para reutilizar ao obter os pesos do adaptador, normalmente a partir defrom_pretrained. - kwargs (
dict[str, Any], opcional) — Campos adicionais deLoadStateDictConfigpassados 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 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ãoFalse) — 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ãoFalse) — Indica se o adaptador deve ser treinável ou não. SeFalse, o adaptador será congelado e poderá ser usado apenas para inferência. - hotswap — (
"auto"oubool, 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, os pesos do adaptador existente serão substituídos 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, oadapter_namedeve ser o nome de um adaptador já carregado.Se o novo adaptador e o adaptador antigo tiverem ranks e/ou alphas LoRA (ou seja, escalonamento) diferentes, você precisa chamar um método adicional antes de carregar o adaptador:
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
< source >( adapter_configadapter_name: str | None = None )
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
< source >( adapter_name: list[str] | str )
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.
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.
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
< source >( target_rank: int = 128check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error' )
Parâmetros
- target_rank (
int, opcional, padrão128) — 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): lança um erro
- “warn”: emitir um aviso
- “ignore”: não fazer nada
Permite a troca dinâmica de adaptadores PEFT com ranks diferentes ou, se o modelo estiver compilado, sem disparar 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 se o modelo estiver compilado ou se os ranks dos adaptadores carregados forem diferentes. 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.
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
< source >( adapter_name: str | None = Nonestate_dict: dict | None = None )
Parâmetros
- adapter_name (
str, opcional) — O nome do adaptador do qual obter o state dict. Se nenhum nome for passado, o adaptador ativo será usado. - state_dict (dicionário aninhado de
torch.Tensor, opcional) — O dicionário de estado do modelo. O valor padrão seráself.state_dict(), mas pode ser utilizado 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
< source >( adapter_names: list[str] | str )
Exclua um adaptador PEFT do modelo subjacente.