PEFT documentation
X-LoRA
X-LoRA
Mixture of LoRA Experts (X-LoRA) é um método PEFT que permite uma mistura esparsa ou densa de especialistas LoRA com base em uma matriz de escalonamento de alta granularidade (token, camada, sequência). Isso aproveita adaptadores LoRA congelados e um modelo base congelado para reduzir drasticamente o número de parâmetros que precisam ser ajustados finamente.
Um aspecto único do X-LoRA é sua versatilidade: ele pode ser aplicado a qualquer modelo base do transformers com adaptadores LoRA. Isso significa que, apesar da estratégia de mistura de especialistas, nenhuma alteração no código do modelo precisa ser feita.
O gráfico abaixo demonstra como as escalas mudam para diferentes prompts em cada token. Isso destaca a ativação de diferentes adaptadores à medida que a geração avança e a sequência cria um novo contexto.

Para cada etapa, o X-LoRA exige que o modelo base seja executado duas vezes: primeiro, para obter os estados ocultos sem nenhum adaptador LoRA, e, em seguida, os estados ocultos são usados para calcular escalonamentos que são aplicados aos adaptadores LoRA, e o modelo é executado uma segunda vez. A saída da segunda execução é o resultado da etapa do modelo.
Em última análise, o X-LoRA permite que o modelo reflita sobre seu conhecimento devido ao esquema de dupla passagem de frente e reconfigure dinamicamente a arquitetura.
O resumo do artigo é:
Relatamos uma estratégia de mistura de especialistas para criar modelos de linguagem de grande escala ajustados finamente, utilizando uma abordagem profunda, camada a camada e token a token, baseada em adaptação de baixo rank (LoRA). Partindo de um conjunto de adaptadores LoRA pré-treinados, nossa estratégia de roteamento usa os estados ocultos para misturar dinamicamente as camadas adaptadas, permitindo que o modelo X-LoRA resultante aproveite diferentes capacidades e crie combinações profundas, camada a camada, nunca antes utilizadas para resolver tarefas. O design é inspirado nos princípios biológicos de universalidade e diversidade, nos quais os blocos de construção de redes neurais são reutilizados em diferentes manifestações hierárquicas. Portanto, o modelo X-LoRA pode ser implementado facilmente para qualquer modelo de linguagem de grande escala (LLM) existente, sem necessidade de modificações na estrutura subjacente. Desenvolvemos um modelo X-LoRA personalizado que oferece capacidades científicas, incluindo tarefas de análise direta/inversa e capacidade de raciocínio aprimorada, com foco em análise de biomateriais, mecânica e design de proteínas. O impacto deste trabalho inclui o acesso a modelos prontamente expansíveis e adaptáveis, com forte conhecimento de domínio e a capacidade de integrar diferentes áreas do conhecimento. Com especialistas em biologia, matemática, raciocínio, materiais bioinspirados, mecânica e materiais, química, biofísica de proteínas, mecânica e propriedades moleculares baseadas em mecânica quântica, conduzimos uma série de estudos de caso focados em física. Examinamos a recuperação de conhecimento, tarefas diretas/inversas de mecânica de proteínas, design de proteínas, modelagem agêntica adversarial, incluindo a construção de grafos de conhecimento ontológicos, bem como o design molecular. O modelo é capaz não apenas de fazer previsões quantitativas das propriedades nanomecânicas de proteínas ou das propriedades moleculares da mecânica quântica, mas também de raciocinar sobre os resultados e prever corretamente os mecanismos prováveis que explicam os distintos comportamentos moleculares..
Cite X-LoRA como:
@article{10.1063/5.0203126,
author = {Buehler, Eric L. and Buehler, Markus J.},
title = "{X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design}",
journal = {APL Machine Learning},
volume = {2},
number = {2},
pages = {026119},
year = {2024},
month = {05},
abstract = "{We report a mixture of expert strategy to create fine-tuned large language models using a deep layer-wise token-level approach based on low-rank adaptation (LoRA). Starting with a set of pre-trained LoRA adapters, our gating strategy uses the hidden states to dynamically mix adapted layers, allowing the resulting X-LoRA model to draw upon different capabilities and create never-before-used deep layer-wise combinations to solve tasks. The design is inspired by the biological principles of universality and diversity, where neural network building blocks are reused in different hierarchical manifestations. Hence, the X-LoRA model can be easily implemented for any existing large language model without a need for modifications of the underlying structure. We develop a tailored X-LoRA model that offers scientific capabilities, including forward/inverse analysis tasks and enhanced reasoning capability, focused on biomaterial analysis, protein mechanics, and design. The impact of this work includes access to readily expandable and adaptable models with strong domain knowledge and the capability to integrate across areas of knowledge. Featuring experts in biology, mathematics, reasoning, bio-inspired materials, mechanics and materials, chemistry, protein biophysics, mechanics, and quantum-mechanics based molecular properties, we conduct a series of physics-focused case studies. We examine knowledge recall, protein mechanics forward/inverse tasks, protein design, adversarial agentic modeling including ontological knowledge graph construction, and molecular design. The model is capable not only of making quantitative predictions of nanomechanical properties of proteins or quantum mechanical molecular properties but also reasoning over the results and correctly predicting likely mechanisms that explain distinct molecular behaviors.}",
issn = {2770-9019},
doi = {10.1063/5.0203126},
url = {https://doi.org/10.1063/5.0203126},
eprint = {https://pubs.aip.org/aip/aml/article-pdf/doi/10.1063/5.0203126/19964043/026119\_1\_5.0203126.pdf},
}API
XLoraConfig
classe peft.XLoraConfig
< 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 = Falsehidden_size: int = Noneadapters: dict[str, str] = Noneenable_softmax: bool = Trueenable_softmax_topk: bool = Falselayerwise_scalings: bool = Falsexlora_depth: int = 1xlora_size: int = 2048xlora_dropout_p: float = 0.2use_trainable_adapters: bool = Falsesoftmax_temperature: float = 1.0top_k_lora: Optional[int] = Nonescaling_pass_value: float = 0.0global_scaling_weight: float = 1.0 )
Parâmetros
- hidden_size (
int) — Tamanho oculto do modelo base. - adapters (
dict) — Mapeamento de nomes de adaptadores para o id do adaptador LoRA, conforme PeftModel.load_adapter. Eles serão carregados automaticamente para uso como especialistas LoRA. Ao usar from_pretrained, passe o novo dicionário de adaptadores como argumento de palavra-chave. - enable_softmax (
bool, opcional, padrãoTrue) — Ativa a aplicação de softmax para o classificador X-LoRA. - enable_softmax_topk (
bool, opcional, padrãoFalse) — Ativa a aplicação de softmax para os adaptadores LoRA top-k. É mutuamente exclusivo comenable_softmaxe deve ser definido apenas setop_k_loraestiver definido. - softmax_temperature (
float, opcional, padrão 1.0) — Temperatura do softmax; valores menores geram previsões mais nítidas - layerwise_scalings (
bool, opcional, padrãoFalse) — Se True, gera escalas para cada adaptador LoRA (cada camada). Se False, as escalas serão transmitidas, da mesma forma, para cada camada. - top_k_lora (
int, opcional, padrão None) — Seleciona esparsamente os top_k especialistas LoRA em vez do método denso padrão. - xlora_depth (
int, opcional, padrão 1) — Profundidade do classificador X-LoRA. - xlora_size (
int, opcional, padrão 2048) — Tamanho oculto do classificador X-LoRA, irrelevante sexlora_depth=1. - xlora_dropout_p (
float, opcional, padrão 0.2) — Probabilidade de dropout do classificador X-LoRA, irrelevante sexlora_depth=1. - use_trainable_adapters (
bool, opcional, padrão é False) — Torna os adaptadores treináveis. - scaling_pass_value (
float, opcional, padrão 0) — Valor de passagem de escala. - global_scaling_weight (
float, opcional, padrão 1) — Peso para multiplicar a saída de cada adaptador LoRA.
Esta é a classe de configuração para armazenar a configuração de um XLoraModel. Quando a configuração é recarregada, os caminhos do campo adapters são ignorados em favor dos adaptadores salvos. Dessa forma, apenas as chaves importam durante o carregamento.
XLoraModel
classe peft.XLoraModel
< source >( model: nn.Moduleconfig: Union[dict[str, XLoraConfig], XLoraConfig]adapter_name: strtorch_device: Optional[str] = Noneephemeral_gpu_offload: bool = Falseautocast_adapter_dtype: bool = True**kwargs ) → torch.nn.Module
Parâmetros
- model (
torch.nn.Module) — O modelo a ser adaptado. - config (XLoraConfig) — A configuração do modelo Lora.
- adapter_name (
str) — O nome do adaptador, não afeta os nomes dos adaptadores LoRA.
Retorna
torch.nn.Module
O modelo X-LoRA.
Cria um modelo X-LoRA (Mixture of LoRA experts) a partir de um modelo transformers pré-treinado. Atualmente, esta implementação de X-LoRA funciona apenas com modelos que possuem uma arquitetura transformer.
O método é descrito em detalhes em https://huggingface.co/papers/2402.07148.
Exemplo:
>>> import torch
>>> from transformers import AutoModelForCausalLM, AutoConfig, BitsAndBytesConfig
>>> from peft import XLoraConfig, get_peft_model, prepare_model_for_kbit_training
>>> model_config = AutoConfig.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
>>> config = XLoraConfig(
... task_type="CAUSAL_LM",
... hidden_size=model_config.hidden_size,
... xlora_depth=4,
... adapters={
... "adapter_1": "./path/to/the/checkpoint/",
... "adapter_2": "./path/to/the/checkpoint/",
... "adapter_n": "./path/to/the/checkpoint/",
... },
... )
>>> int8_config = BitsAndBytesConfig(load_in_8bit=True)
>>> model = AutoModelForCausalLM.from_pretrained(
... "mistralai/Mistral-7B-Instruct-v0.1",
... trust_remote_code=True,
... attn_implementation="flash_attention_2",
... device_map="cuda:0",
... torch_dtype=torch.bfloat16,
... quantization_config=int8_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> xlora_model = get_peft_model(model, config)Limpar o log de escalonamentos.
Desative o registro de escalonamentos, sem limpar o log.
Ativar o registro de escalonamentos.
Retorna escalonamentos agrupados, agrupados por seq_len. Cada valor consiste nas posições (as primeiras) e nos tensors associados. As posições são pareadas com os tensors associados e indicam a posição no log de escalonamento.
Obtenha o peso global do LoRA.
Retorna a previsão mais recente de escalonamentos, ou None se nenhum escalonamento tiver sido previsto. O tensor tem a forma (batch_size, seq_len, n_layers, n_classes).
Retorna uma cópia rasa (copiando apenas a lista em si, não os tensores) da lista contendo o log de escalonamentos. A edição da lista não altera o log subjacente. Os tensores têm a forma (batch_size, seq_len, n_layers, n_classes). A dimensão seq_len pode variar com a dimensão de entrada.
Defina o peso global do LoRA, um escalar para multiplicar a saída de cada adaptador LoRA. Por padrão, esse valor é 1. Isso é refletido na configuração.
Defina o valor da passagem de escalonamento, o valor para definir os escalonamentos durante a passagem de escalonamento. Se o valor for None, o valor da passagem de escalonamento será 1/n, onde n é o número de adaptadores.
Selecione esparsamente os especialistas LoRA especificados em top_k em vez do método denso padrão. Defina como None para usar denso. Isso é refletido na configuração.