PEFT documentation
AdaMSS
AdaMSS
AdaMSS (AdaMSS: Adaptive Multi-Subspace Approach for Parameter-Efficient Fine-Tuning) é um método de fine-tuning eficiente em parâmetros que decompõe matrizes de pesos usando SVD e agrupa o espaço decomposto em múltiplos subespaços treináveis. Cada subespaço aprende atualizações independentes de baixo rank, enquanto os pesos originais permanecem congelados. O AdaMSS também suporta a Alocação Adaptativa de Subespaços (ASA), que poda dinamicamente subespaços menos importantes durante o treinamento com base em informações de gradiente.
O resumo do artigo é:
Propomos o AdaMSS, uma abordagem adaptativa de múltiplos subespaços para ajuste fino eficiente em parâmetros de modelos grandes. Diferentemente dos métodos tradicionais de ajuste fino eficiente em parâmetros que operam dentro de um único subespaço grande dos pesos da rede, o AdaMSS utiliza a segmentação de subespaços para obter múltiplos subespaços menores e reduz adaptativamente o número de parâmetros treináveis durante o treinamento, atualizando, em última análise, apenas aqueles associados a um pequeno subconjunto de subespaços mais relevantes para a tarefa downstream de destino. Ao usar a representação de menor posto, o AdaMSS alcança uma expressividade mais compacta e um ajuste mais fino dos parâmetros do modelo. Análises teóricas demonstram que o AdaMSS possui uma garantia de generalização melhor do que LoRA, PiSSA e outros métodos baseados em baixo posto de subespaço único. Experimentos extensos em tarefas de classificação de imagens, compreensão de linguagem natural e geração de linguagem natural mostram que o AdaMSS alcança desempenho comparável ao ajuste fino completo e supera outros métodos de ajuste fino eficiente em parâmetros na maioria dos casos, tudo isso exigindo menos parâmetros treináveis. Notavelmente, no modelo ViT-Large, o AdaMSS alcança 4,7% de precisão média maior do que o LoRA em sete tarefas, usando apenas 15,4% dos parâmetros treináveis. No RoBERTa-Large, o AdaMSS supera o PiSSA em 7% de precisão média em seis tarefas, enquanto reduz o número de parâmetros treináveis em aproximadamente 94,4%. Esses resultados demonstram a eficácia do AdaMSS no ajuste fino eficiente em parâmetros. O código para o AdaMSS está disponível em https: //github.com/jzheng20/AdaMSS.
O AdaMSS possui atualmente as seguintes restrições:
- Apenas camadas
nn.Linearsão suportadas. - Exige o scikit-learn para a etapa de agrupamento KMeans.
Se essas restrições não funcionarem para o seu caso de uso, considere outros métodos.
Visão geral do benchmark
API
AdamssConfig
classe peft.AdamssConfig
< source >( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 100num_subspaces: int = 5subspace_rank: int = 1target_modules: Optional[Union[list[str], str]] = Noneinit_weights: Optional[Literal['orthogonal']] = 'orthogonal'modules_to_save: Optional[list[str]] = Nonelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Noneuse_asa: bool = Falseasa_target_subspaces: int = 50init_warmup: int = 50final_warmup: int = 1000mask_interval: int = 100asa_importance_beta: float = 0.85asa_uncertainty_beta: float = 0.85asa_schedule_exponent: float = 3.0use_dynamic_rank: bool = Falsesvd_threshold: float = 0.1random_seed: int = 0 )
Parâmetros
- r (
int) — Rank total para a decomposição SVD (denotado como R no artigo). Isso determina quantos vetores singulares são usados para representar a matriz de pesos antes do agrupamento. Valores mais altos capturam mais informações dos pesos originais, mas exigem mais computação e memória. Valores mais baixos fornecem regularização mais forte. Valores típicos variam de 50 a 500. O padrão é 100. - num_subspaces (
int) — Número de subespaços (K) para agrupar o espaço decomposto por SVD. Cada subespaço aprende atualizações de baixo posto independentes. Aumentar esse valor permite uma adaptação mais granular, mas aumenta o número de parâmetros treináveis proporcionalmente. Ao usar ASA (Adaptive Subspace Allocation), isso determina o número inicial de subespaços antes do pruning. Valores típicos variam de 3 a 10. O padrão é 5. - subspace_rank (
int) — O rank (r_i) para cada subespaço treinável. Isso controla a capacidade de cada subespaço para aprender adaptações. Valores maiores aumentam a expressividade, mas também aumentam os parâmetros treináveis. O total de parâmetros treináveis escala como O(num_subspaces subspace_rank (in_dim + out_dim) / num_subspaces). Para a maioria das tarefas, valores de 1 a 4 funcionam bem. O padrão é 1. - target_modules (
Optional[Union[list[str], str]]) — Os nomes dos módulos aos quais aplicar o AdaMSS. Se especificado, apenas esses módulos serão adaptados. Pode ser uma lista de nomes exatos de módulos ou uma expressão regular. Por exemplo,['q_proj', 'v_proj']para camadas de atenção, ou'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'para correspondência por expressão regular. - modules_to_save (
Optional[list[str]]) — Lista de módulos, além das camadas AdaMSS, que devem ser configurados como treináveis e salvos no checkpoint final. Esses módulos serão totalmente ajustados (não apenas de baixo-rank). Obrigatório para cabeças inicializadas aleatoriamente, comoclassifierouscore, em tarefas de classificação. - init_weights (
Literal["orthogonal"]) — Método de inicialização para os pesos treináveis do AdaMSS. Atualmente, apenas “orthogonal” é suportado, o que utiliza inicialização ortogonal para as matrizes B (projeção de saída). As matrizes A são inicializadas com zero para garantir que o modelo comece a partir dos pesos pré-treinados. Defina como None para pular a inicialização ao carregar de um checkpoint. O padrão é “orthogonal”. - layers_to_transform (
Optional[Union[list[int], int]]) — Índices específicos de camadas para aplicar o AdaMSS. Se especificado, apenas essas camadas serão adaptadas, o que é útil para experimentar quais camadas se beneficiam mais da adaptação. Pode ser um único inteiro ou uma lista de inteiros. - layers_pattern (
Optional[Union[list[str], str]]) — Padrão para corresponder a nomes de camadas quandolayers_to_transformé especificado. Usado para extrair índices de camadas de nomes de módulos que não seguem o padrão comum. - use_asa (
bool) — Se deve habilitar a Alocação Adaptativa de Subespaços (ASA). Quando habilitado, o ASA poda dinamicamente subespaços menos importantes durante o treinamento com base em informações de gradiente, reduzindo o número efetivo de parâmetros enquanto mantém o desempenho. Requer integração com um callback de treinamento. O padrão é False. - asa_target_subspaces (
int) — Número total de subespaços ativos em todas as camadas quando o ASA está habilitado. O ASA fará o pruning progressivo dos subespaços até que esse alvo seja atingido. Valores menores resultam em um pruning mais agressivo e em menos parâmetros treináveis. Deve ser menor quenum_subspaces * num_target_modules. Valores típicos variam de 20 a 100, dependendo do tamanho do modelo. O padrão é 50. Deve ser um inteiro positivo quandouse_asa=True. - init_warmup (
int) — Número de etapas de treinamento a aguardar antes de iniciar o poda ASA. Durante o aquecimento, todos os subespaços permanecem ativos para permitir que as pontuações de importância se estabilizem. Valores maiores dão mais tempo para uma estimativa precisa da importância, mas atrasam o poda. Valores típicos variam de 50 a 200. O padrão é 50. Deve ser menor quefinal_warmupquandouse_asa=True. - final_warmup (
int) — Etapa de treinamento na qual o ASA conclui o pruning e atingeasa_target_subspacessubespaços ativos. O pruning é distribuído entreinit_warmupefinal_warmup. Deve ser definido com base no total de etapas de treinamento; tipicamente, de 1/3 a 1/2 do total de etapas de treinamento. O valor padrão é 1000. Deve ser maior queinit_warmupquandouse_asa=True. - mask_interval (
int) — Número de etapas de treinamento entre atualizações da máscara ASA. Valores menores permitem adaptação mais frequente, mas aumentam a sobrecarga. Valores maiores fornecem estimativas de importância mais estáveis entre as atualizações. Os valores típicos variam de 50 a 200. O padrão é 100. Deve ser um inteiro positivo quandouse_asa=True. - asa_importance_beta (
float) — Coeficiente de média móvel exponencial (EMA) para suavizar as pontuações de importância dos subespaços. Valores mais altos (próximos de 1,0) dão mais peso à importância histórica, proporcionando estabilidade. Valores mais baixos tornam a importância mais responsiva aos gradientes recentes. Os valores típicos variam de 0,8 a 0,95. O padrão é 0,85. - asa_uncertainty_beta (
float) — Coeficiente de EMA para suavizar as estimativas de incerteza de importância. Controla a velocidade com que a incerteza se adapta à variância do gradiente. Assim como asa_importance_beta, valores mais altos fornecem estimativas mais estáveis. Valores típicos variam de 0,8 a 0,95. O padrão é 0,85. - asa_schedule_exponent (
float) — Expoente do agendamento que controla a taxa de decaimento deasa_target_subspacesa partir dos subespaços totais durante o aquecimento do ASA. Valores mais altos resultam em um poda inicial mais rápido (redução inicial mais agressiva), enquanto valores mais baixos fornecem um decaimento mais gradual, semelhante a um linear. A fórmula é: current_active_subspaces = asa_target_subspaces + (asa_total_subspaces - asa_target_subspaces) * (progress ** exponent). Valores típicos variam de 1.0 (linear) a 5.0 (agressivo). O padrão é 3.0. Deve ser um número positivo quandouse_asa=True(um expoente zero ou negativo degenera o agendamento para um no-op permanente ou, uma vez queprogressatinge exatamente 0.0, levanta umZeroDivisionError). - use_dynamic_rank (
bool) — Se deve determinar dinamicamente os ranks dos subespaços com base nas magnitudes dos valores singulares. Quando True, o rank de cada subespaço é determinado contando os valores singulares acima de um limiar, permitindo que diferentes subespaços tenham ranks efetivos diferentes. Quando False, todos os subespaços usam osubspace_rankfixo. O padrão é False. - svd_threshold (
float) — Proporção de limiar para seleção dinâmica de rank, usada apenas quandouse_dynamic_rank=True. Um valor singular é considerado significativo se excederthreshold * max_singular_value. Valores mais altos resultam em ranks efetivos menores (truncamento mais agressivo). Valores típicos variam de 0,05 a 0,2. O padrão é 0,1 (10% do máximo).
Classe de configuração para o método Adamss (Adaptive Multi-Subspaces).
AdaMSS é um método de ajuste fino eficiente em parâmetros que decompõe matrizes de pesos usando SVD e agrupa o espaço decomposto em múltiplos subespaços treináveis. Ele aprende atualizações de baixo rank nesses subespaços, mantendo os pesos originais congelados.
AdamssModel
classe peft.AdamssModel
< source >( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict] = None ) → torch.nn.Module
Cria um modelo Adamss (Adaptive Multi-Subspaces) a partir de um modelo pré-treinado.
O método decompõe as matrizes de pesos usando SVD e agrupa o espaço decomposto em múltiplos subespaços treináveis para ajuste fino eficiente em parâmetros.
Exemplo:
>>> from transformers import AutoModelForImageClassification
>>> from peft import AdamssConfig, get_peft_model
>>> config = AdamssConfig(
... r=500,
... num_subspaces=5,
... target_modules=["query", "value"],
... )
>>> model = AutoModelForImageClassification.from_pretrained("google/vit-base-patch16-224")
>>> adamss_model = get_peft_model(model, config)Atributos:
- model (
~torch.nn.Module) — O modelo a ser adaptado. - peft_config (AdamssConfig): A configuração do modelo Adamss.
update_and_allocate
< source >( global_step: int )
Atualize as pontuações de importância e aplique a máscara ASA (se habilitado).
Este método deve ser chamado em cada passo de treinamento após loss.backward() e antes de optimizer.zero_grad() quando o ASA está habilitado. Internamente, ele:
- Acumula as pontuações de importância via EMA a cada etapa durante o período de aquecimento.
- Em intervalos de máscara, aplica a máscara global top-K e redefine a importância.
Este é o único ponto de entrada para o ASA – usar o AdamssAsaCallback com o Trainer do HuggingFace simplesmente delega para este método. Para loops de treinamento personalizados, chame este método diretamente em vez do callback.