PEFT documentation

X-LoRA

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

X-LoRA

Mixture of LoRA Experts (X-LoRA) es un método de PEFT que permite una mezcla dispersa o densa de expertos LoRA basada en una matriz de escalado de alta granularidad (token, capa, secuencia). Esto aprovecha adaptadores LoRA congelados y un modelo base congelado para reducir drásticamente el número de parámetros que deben ajustarse.

Un aspecto único de X-LoRA es su versatilidad: puede aplicarse a cualquier modelo base de transformers con adaptadores LoRA. Esto significa que, a pesar de la estrategia de mezcla de expertos, no es necesario realizar cambios en el código del modelo.

El gráfico siguiente muestra cómo cambian las escalas para diferentes indicaciones en cada token. Esto resalta la activación de diferentes adaptadores a medida que avanza la generación y la secuencia crea un nuevo contexto.

Token-by-token scalings

En cada paso, X-LoRA requiere ejecutar el modelo base dos veces: primero, para obtener los estados ocultos sin ningún adaptador LoRA, y en segundo lugar, se utilizan esos estados ocultos para calcular los escalados que se aplican a los adaptadores LoRA, y el modelo se ejecuta una segunda vez. La salida de la segunda ejecución es el resultado del paso del modelo.

En última instancia, X-LoRA permite que el modelo reflexione sobre su conocimiento gracias al esquema de doble pasada hacia adelante, y reconfigure dinámicamente la arquitectura.

El resumen del artículo es:

Informamos sobre una estrategia de mezcla de expertos para crear modelos de lenguaje grandes ajustados finamente mediante un enfoque profundo a nivel de capa y de token basado en adaptación de bajo rango (LoRA). Partiendo de un conjunto de adaptadores LoRA preentrenados, nuestra estrategia de enrutamiento utiliza los estados ocultos para mezclar dinámicamente las capas adaptadas, lo que permite que el modelo X-LoRA resultante aproveche diferentes capacidades y cree combinaciones profundas a nivel de capa nunca antes utilizadas para resolver tareas. El diseño se inspira en los principios biológicos de universalidad y diversidad, donde los bloques de construcción de las redes neuronales se reutilizan en diferentes manifestaciones jerárquicas. Por lo tanto, el modelo X-LoRA puede implementarse fácilmente para cualquier modelo de lenguaje grande (LLM) existente sin necesidad de modificar la estructura subyacente. Desarrollamos un modelo X-LoRA a medida que ofrece capacidades científicas, incluidas tareas de análisis directo/inverso y una capacidad de razonamiento mejorada, centradas en el análisis de biomateriales, la mecánica y el diseño de proteínas. El impacto de este trabajo incluye el acceso a modelos fácilmente expandibles y adaptables con un sólido conocimiento de dominio y la capacidad de integrarse en diferentes áreas del conocimiento. Al contar con expertos en biología, matemáticas, razonamiento, materiales bioinspirados, mecánica y materiales, química, biofísica de proteínas, mecánica y propiedades moleculares basadas en mecánica cuántica, realizamos una serie de estudios de caso centrados en la física. Examinamos la recuperación de conocimiento, tareas directas/inversas de mecánica de proteínas, diseño de proteínas, modelado agéntico adversarial que incluye la construcción de grafos de conocimiento ontológicos, así como el diseño molecular. El modelo es capaz no solo de realizar predicciones cuantitativas de las propiedades nanomecánicas de las proteínas o de las propiedades moleculares de la mecánica cuántica, sino también de razonar sobre los resultados y predecir correctamente los mecanismos probables que explican los distintos comportamientos 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

clase peft.XLoraConfig

< >

( 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) — Tamaño oculto del modelo base.
  • adapters (dict) — Mapeo de nombres de adaptadores al id del adaptador LoRA, según PeftModel.load_adapter. Se cargarán automáticamente para usarlos como expertos LoRA. Al usar from_pretrained, pasa el nuevo diccionario de adaptadores como argumento de palabra clave.
  • enable_softmax (bool, opcional, valor predeterminado True) — Habilita la aplicación de softmax para el clasificador X-LoRA.
  • enable_softmax_topk (bool, opcional, valor predeterminado False) — Habilita la aplicación de softmax para los adaptadores LoRA top-k. Es mutuamente excluyente con enable_softmax y solo debe establecerse si se establece top_k_lora.
  • softmax_temperature (float, opcional, valor predeterminado 1.0) — Temperatura de softmax; un valor más bajo produce predicciones más nítidas
  • layerwise_scalings (bool, opcional, valor predeterminado False) — Si es True, genera escalas para cada adaptador LoRA (cada capa). Si es False, las escalas se difundirán, de forma idéntica, a cada capa.
  • top_k_lora (int, opcional, valor predeterminado None) — Selecciona de forma dispersa los top_k expertos LoRA en lugar del método denso predeterminado.
  • xlora_depth (int, opcional, valor predeterminado 1) — Profundidad del clasificador X-LoRA.
  • xlora_size (int, opcional, valor predeterminado 2048) — Tamaño oculto del clasificador X-LoRA, irrelevante si xlora_depth=1.
  • xlora_dropout_p (float, opcional, valor predeterminado 0.2) — Probabilidad de dropout del clasificador X-LoRA, irrelevante si xlora_depth=1.
  • use_trainable_adapters (bool, opcional, predeterminado en False) — Hace que los adaptadores sean entrenables.
  • scaling_pass_value (float, opcional, valor predeterminado 0) — Valor de paso de escalado.
  • global_scaling_weight (float, opcional, valor predeterminado 1) — Peso para multiplicar la salida de cada adaptador LoRA.

Esta es la clase de configuración para almacenar la configuración de un XLoraModel. Cuando la configuración se recarga, las rutas del campo adapters se ignoran en favor de los adaptadores guardados. Por lo tanto, solo las claves importan durante la carga.

XLoraModel

clase peft.XLoraModel

< >

( 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) — El modelo que se va a adaptar.
  • config (XLoraConfig) — La configuración del modelo Lora.
  • adapter_name (str) — El nombre del adaptador, no afecta a los nombres de los adaptadores LoRA.

Devuelve

torch.nn.Module

El modelo X-LoRA.

Crea un modelo X-LoRA (Mixture of LoRA experts) a partir de un modelo de transformers preentrenado. Actualmente, esta implementación de X-LoRA solo funciona con modelos con una arquitectura transformer.

El método se describe en detalle en https://huggingface.co/papers/2402.07148.

Ejemplo:

>>> 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)

clear_scalings_log

< >

( )

Borrar el registro de escalados.

disable_scalings_logging

< >

( )

Desactivar el registro de escalados, sin borrar el registro.

enable_scalings_logging

< >

( )

Habilitar el registro de escalados.

get_bucketed_scalings_log

< >

( )

Devuelve escalados agrupados, agrupados por seq_len. Cada valor consiste en las posiciones (las primeras) y los tensores asociados. Las posiciones se emparejan con los tensores asociados y dan la posición en el registro de escalado.

get_global_scaling_weight

< >

( )

Obtenga el peso global de LoRA.

get_latest_scalings

< >

( )

Devuelve la predicción de escalado más reciente, o None si no se han predicho escalados. El tensor tiene forma (batch_size, seq_len, n_layers, n_classes).

get_scalings_log

< >

( )

Devuelve una copia superficial (solo copia la lista en sí, no los tensores) de la lista que contiene el registro de escalados. Editar la lista no modifica el registro subyacente. Los tensores tienen forma (batch_size, seq_len, n_layers, n_classes). La dimensión seq_len puede variar según la dimensión de entrada.

set_global_scaling_weight

< >

( weight: float )

Establece el peso global de LoRA, un escalar para multiplicar la salida de cada adaptador LoRA. Por defecto, este valor es 1. Esto se refleja en la configuración.

set_scaling_pass_value

< >

( value: float | None )

Establezca el valor de la pasada de escalado, el valor al que se establecerán los escalados durante la pasada de escalado. Si el valor es None, el valor de la pasada de escalado será 1/n, donde n es el número de adaptadores.

set_topk_lora

< >

( value: Optional[int] )

Seleccione de forma dispersa los expertos LoRA especificados en top_k en lugar del método denso predeterminado. Establezca None para usar denso. Esto se refleja en la configuración.

Update on GitHub