PEFT documentation

LoRA

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LoRA

LoRA es uno de los métodos PEFT más populares y un buen punto de partida si apenas estás comenzando con PEFT. Originalmente se desarrolló para modelos de lenguaje de gran escala, pero es un método de entrenamiento enormemente popular para modelos de difusión debido a su eficiencia y eficacia.

La adaptación de bajo rango (LoRA) es un método PEFT que descompone una matriz grande en dos matrices de bajo rango más pequeñas. Esto reduce drásticamente el número de parámetros que deben ajustarse.

El resumen del artículo es:

Un paradigma importante del procesamiento del lenguaje natural consiste en el preentrenamiento a gran escala en datos de dominio general y la adaptación a tareas o dominios particulares. A medida que preentrenamos modelos más grandes, el ajuste fino completo, que reentrena todos los parámetros del modelo, se vuelve menos viable. Tomando GPT-3 175B como ejemplo, desplegar instancias independientes de modelos ajustados, cada una con 175B parámetros, resulta prohibitivamente costoso. Proponemos la Adaptación de Bajo Rango, o LoRA, que congela los pesos del modelo preentrenado e inyecta matrices de descomposición de rango entrenables en cada capa de la arquitectura Transformer, reduciendo en gran medida el número de parámetros entrenables para tareas posteriores. En comparación con GPT-3 175B ajustado con Adam, LoRA puede reducir el número de parámetros entrenables en 10.000 veces y el requisito de memoria GPU en 3 veces. LoRA rinde igual o mejor que el ajuste fino en la calidad del modelo en RoBERTa, DeBERTa, GPT-2 y GPT-3, a pesar de tener menos parámetros entrenables, un mayor rendimiento de entrenamiento y, a diferencia de los adaptadores, no introduce latencia adicional de inferencia. También proporcionamos una investigación empírica sobre la deficiencia de rango en la adaptación de modelos de lenguaje, que arroja luz sobre la eficacia de LoRA. Publicamos un paquete que facilita la integración de LoRA con modelos de PyTorch y proporcionamos nuestras implementaciones y puntos de control de modelos para RoBERTa, DeBERTa y GPT-2 en esta URL de https.

LoRA representa las actualizaciones de pesos ΔW\Delta W con dos matrices más pequeñas (llamadas matrices de actualización) mediante descomposición de bajo rango. Estas nuevas matrices se pueden entrenar para adaptarse a los nuevos datos manteniendo bajo el número total de parámetros. La matriz de pesos original permanece congelada y no recibe más actualizaciones. Para producir los resultados finales, se combinan los pesos originales y los pesos adicionales adaptados. También es posible fusionar los pesos del adaptador con el modelo base para eliminar la latencia de inferencia.

Este enfoque tiene una serie de ventajas:

  • LoRA hace que el ajuste fino sea más eficiente al reducir drásticamente el número de parámetros entrenables.
  • Los pesos preentrenados originales se mantienen congelados, lo que significa que puedes tener múltiples modelos LoRA ligeros y portátiles para diversas tareas de nivel inferior construidos sobre ellos.
  • LoRA es ortogonal a otros métodos de eficiencia de parámetros y puede combinarse con muchos de ellos.
  • El rendimiento de los modelos ajustados con LoRA es comparable al de los modelos ajustados por completo.

En principio, LoRA puede aplicarse a cualquier subconjunto de matrices de pesos en una red neuronal para reducir el número de parámetros entrenables. Sin embargo, por simplicidad y mayor eficiencia de parámetros, LoRA se aplica típicamente solo a los bloques de atención en los modelos Transformer, aunque puede ser útil apuntar también a otras capas. El número resultante de parámetros entrenables en un modelo LoRA depende del tamaño de las matrices de actualización, que está determinado principalmente por el rango r y la forma de la matriz de pesos original.

Puedes inicializar las matrices de bajo rango con diferentes casos de uso en mente: conciencia de la tarea (CorDA, EVA, Astra), convergencia más rápida (PiSSA), mitigación de la cuantización (LoftQ), solo por mencionar algunos. Lee sobre las diferentes inicializaciones a continuación. La inicialización predeterminada es que LoRA sea una operación sin efecto (no-op), para aprender gradualmente un nuevo comportamiento sin interferir demasiado con el modelo existente.

Uso

El tamaño de las matrices de actualización de bajo rango está determinado por el rank o r. Un rango más alto significa que el modelo tiene más parámetros para entrenar, pero también que tiene mayor capacidad de aprendizaje. En el siguiente ejemplo, se apuntará a las matrices query y value de los bloques de atención. Otros parámetros importantes a configurar son lora_alpha (factor de escalado), bias (si se deben entrenar none, all o solo los parámetros de sesgo de LoRA) y modules_to_save (los módulos, aparte de las capas LoRA, que se deben entrenar y guardar). Todos estos parámetros, y más, se encuentran en LoraConfig.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

Resumen de las pruebas de rendimiento

Inicialización

La inicialización de los pesos de LoRA se controla mediante el parámetro init_lora_weights en LoraConfig. De forma predeterminada, PEFT inicializa los pesos de LoRA con Kaiming-uniform para el peso A y ceros para el peso B, lo que resulta en una transformación de identidad (igual que la implementación de referencia).

Para las capas transformers.Conv1D, como las proyecciones de GPT-2, use fan_in_fan_out=True porque sus pesos se almacenan como (in_features, out_features) en lugar del formato de nn.Linear. Los inicializadores basados en pesos admitidos usan el formato Linear para la descomposición y restauran el formato de almacenamiento al actualizar los pesos base. La escalado "stable" de LoRA-GA también usa la dimensión de salida independientemente del formato de almacenamiento.

También es posible pasar init_lora_weights="gaussian". Como sugiere el nombre, esto inicializa el peso A con una distribución gaussiana y ceros para el peso B (así es como Diffusers inicializa los pesos de LoRA).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

También existe la opción de establecer init_lora_weights=False, que es útil para depurar y probar. Este debe ser el único momento en que se utilice esta opción. Al elegir esta opción, los pesos de LoRA se inicializan de tal manera que no resulten en una transformación de identidad.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)
NoRA
PiSSA
MiCA
CorDA
Astra
OLoRA
EVA
LoftQ
rsLoRA
LoRA-GA

Normalized Low-Rank Adaptation (NoRA) normaliza las matrices de proyección descendente de LoRA. PEFT aplica esta normalización solo durante la inicialización mediante init_lora_weights="nora" en LoraConfig: normaliza las columnas del peso A de LoRA inicializado aleatoriamente e inicializa el peso B de LoRA a cero. Ambas matrices siguen siendo entrenables y los pesos base se mantienen sin cambios.

Para una capa lineal, la actualización de pesos del adaptador es $\Delta W = sBA$, donde AA tiene forma (r, in_features), BB tiene forma (out_features, r), y ss es el factor de escalado de LoRA. NoRA parte del peso aleatorio A creado por la capa lineal de LoRA y normaliza cada columna a lo largo de la dimensión de rango: A:,j←A:,jmax⁡(∥A:,j∥2,10−6),B←0. A_{:,j} \leftarrow \frac{A_{:,j}}{\max(\lVert A_{:,j} \rVert_2, 10^{-6})}, \qquad B \leftarrow 0.

Dado que B es cero, la actualización de los pesos del adaptador es cero antes del entrenamiento. Con bias="none" y lora_bias=False, el adaptador preserva inicialmente la salida del modelo base. NoRA no requiere un conjunto de datos de calibración ni una descomposición de pesos.

Para NoRA, la configuración recomendada es lora_alpha igual a r (una proporción alpha/rango de 1:1), por ejemplo, r=8, lora_alpha=8. Con el valor predeterminado use_rslora=False, esto mantiene un factor de escala de 1; habilitar LoRA estabilizado por rango lo cambia a lora_alpha / sqrt(r).

El siguiente ejemplo aplica NoRA a dos capas lineales en un pequeño modelo de PyTorch:

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

Para un modelo de Transformers, establece target_modules con los nombres de las capas lineales que deseas adaptar, como ["q_proj", "v_proj"] cuando esos nombres están presentes en el modelo.

NoRA utiliza las API existentes de configuración, entrenamiento, guardado y carga de LoRA, por lo que no existe una clase NoraConfig o NoraModel separada. Para las API de configuración y modelo compartidas, consulte LoraConfig y LoraModel.

NoRA admite módulos objetivo torch.nn.Linear o nn.Parameters pasados directamente con target_parameters. No se admite para embeddings, capas conv, etc.

Entrenamiento

Esta sección muestra cómo manejar escenarios de entrenamiento más complejos, en lugar de solo aplicar un adaptador de bajo rango al modelo y alimentar datos.

Entrenamiento de estilo QLoRA

La configuración predeterminada de LoRA en PEFT añade pesos entrenables a las capas de consulta y valor de cada bloque de atención. Sin embargo, QLoRA, que añade pesos entrenables a todas las capas lineales de un modelo transformer, puede ofrecer un rendimiento igual al de un modelo totalmente afinado. Para aplicar LoRA a todas las capas lineales, como en QLoRA, establece target_modules="all-linear" (es más sencillo que especificar módulos individuales por nombre, ya que estos pueden variar según la arquitectura).

config = LoraConfig(target_modules="all-linear", ...)

Para obtener más información sobre cómo aplicar la cuantización a los adaptadores de PEFT, consulte la guía de cuantización.

Replicación de capas eficiente en memoria con LoRA

Un enfoque utilizado para mejorar el rendimiento de los modelos consiste en expandir un modelo duplicando capas para construir un modelo más grande a partir de un modelo preentrenado de un tamaño dado. Por ejemplo, aumentar un modelo de 7B a un modelo de 10B, tal como se describe en el artículo SOLAR. PEFT LoRA admite este tipo de expansión de manera eficiente en memoria, lo que permite un ajuste fino posterior mediante adaptadores LoRA unidos a las capas después de su replicación. Las capas replicadas no consumen memoria adicional, ya que comparten los pesos subyacentes, por lo que la única memoria adicional requerida es la de los pesos del adaptador. Para utilizar esta función, debe crear una configuración con el argumento layer_replication.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

Suponiendo que el modelo original tenía 5 capas [0, 1, 2 ,3, 4], esto crearía un modelo con 7 capas dispuestas como [0, 1, 2, 3, 2, 3, 4]. Esto sigue la convención de fusión de paso a través de mergekit, donde las secuencias de capas especificadas como tuplas con inicio incluido y final excluido se apilan para construir el modelo final. Cada capa del modelo final obtiene su propio conjunto de adaptadores LoRA.

Fewshot-Metamath-OrcaVicuna-Mistral-10B es un ejemplo de un modelo entrenado usando este método en Mistral-7B expandido a 10B. El adapter_config.json muestra una configuración de adaptador LoRA de ejemplo que aplica este método para el ajuste fino.

Control fino sobre los rangos y alfa (escalado)

Por defecto, todas las capas objetivo de LoRA tendrán el mismo rango r y el mismo lora_alpha (que determina la escalada de LoRA), según lo especificado en LoraConfig. Sin embargo, en algunos casos puede que desee indicar valores diferentes para distintas capas. Esto es posible pasando los argumentos rank_pattern y alpha_pattern a LoraConfig. Estos argumentos deben ser diccionarios donde la clave es el nombre de la capa y el valor es el valor de rango/alpha. Las claves pueden ser expresiones regulares (regex). Todas las capas de LoRA que no se mencionen explícitamente en rank_pattern y alpha_pattern tomarán los valores predeterminados de r y lora_alpha.

A modo de ejemplo, supongamos que tenemos un modelo con la siguiente estructura:

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)
  • rank_pattern={"foo": 42} coincidirá con las 3 capas foo. Ni foobar ni barfoo coinciden.
  • rank_pattern={"^foo": 42} solo coincidirá con la capa foo del modelo, pero ni con module.foo ni con module.module.foo. Esto se debe a que ^ significa “inicio de cadena” al usar expresiones regulares, y solo foo comienza con "foo"; los nombres de las otras capas tienen prefijos.
  • rank_pattern={"^module.foo": 42} solo coincide con module.foo, pero no con module.module.foo, por la misma razón.
  • rank_pattern={"module.foo": 42} coincide con module.foo y module.module.foo, pero no con foo.
  • rank_pattern={"^foo": 42, "^module.module.foo": 55} coincide con foo y module.module.foo, respectivamente, pero no con module.foo.
  • No es necesario indicar $ para marcar el final de la coincidencia, ya que PEFT lo añade automáticamente.

La misma lógica se aplica a alpha_pattern. Si tienes dudas, no intentes complicarte con expresiones regulares: simplemente pasa el nombre completo de cada módulo con un rank/alpha diferente, precedido por el prefijo ^, y estará bien.

Detectar automáticamente los módulos objetivo viables

peft.helpers.KappaTuneSelector implementa la estrategia de selección de objetivos basada en el número de condición del artículo de KappaTune. Recorre cada módulo nn.Linear y, para los modelos en los que los pesos de los expertos MoE se almacenan como tensores nn.Parameter 3D fusionados (p. ej., Llama-4, Qwen3-MoE), también esos parámetros, calcula el número de condición de la matriz κ = σ_max / σ_min para cada uno y selecciona las capas más isotrópicas (con κ más bajo). Estas capas isotrópicas son candidatas ideales para el ajuste fino, ya que su naturaleza de alta entropía les permite absorber nueva información con mayor facilidad, dejando intactas las capas especializadas y anisotrópicas para mitigar el olvido catastrófico durante el aprendizaje continuo.

Use peft.helpers.find_kappa_target_modules() como una línea de código para obtener los target_modules óptimos para LoraConfig:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

Vea un ejemplo completo aquí.

Dirigirse a nn.Parameter directamente

En general, debe usar target_modules para apuntar al módulo (p. ej. nn.Linear). Sin embargo, en algunas circunstancias, esto no es posible. Por ejemplo, en muchas capas de mezcla de expertos (MoE) de HF Transformers, en lugar de usar nn.Linear, se utiliza un nn.Parameter. PEFT normalmente sobrescribe el método forward para LoRA, pero para nn.Parameter, no existe. Por lo tanto, para aplicar LoRA a ese parámetro, debe apuntarse con target_parameters. Como ejemplo, para Llama4, puede pasar: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

Tenga en cuenta que, al apuntar a los parámetros de expertos, PEFT puede añadir una sobrecarga de tiempo de ejecución considerable. La razón es que PEFT siempre materializa la contribución de LoRA para cada experto, incluso si solo se requiere una pequeña cantidad de expertos. Durante el entrenamiento, esto es menos relevante, ya que, a lo largo de la secuencia, normalmente se activa al menos una vez una gran proporción de expertos. Sin embargo, durante la inferencia, normalmente se utiliza una caché KV y, por lo tanto, solo necesitamos calcular el último token, lo que significa que solo se activa una pequeña cantidad de expertos. Por lo tanto, el uso de LoRA en capas MoE puede provocar una ralentización considerable en el tiempo de inferencia. La recomendación, por tanto, es fusionar los pesos (model.merge_adapter() o model = model.merge_and_unload()). Esto elimina la sobrecarga de PEFT.

Se puede encontrar una investigación más detallada de este problema en esta solicitud de extracción (pull request) sobre la optimización de MoE.

Precauciones

  • En este momento, este argumento permite apuntar a nn.Parameter de 2 o 3 dimensiones. Se asume que, en el caso de un parámetro de 3 dimensiones, la dimensión 0 es la dimensión de experto.
  • Se admiten varios adaptadores LoRA (añadidos mediante model.add_adapter o model.load_adapter) que utilizan target_parameters, pero todos deben apuntar al mismo conjunto de parámetros.

Parámetros de expertos MoE y vLLM

Algunos modelos MoE en Transformers almacenan los pesos de los expertos como tensores nn.Parameter (a menudo 3D), no como módulos nn.Linear. Para aplicar LoRA a esos expertos, usa target_parameters y establece un rango por capa con rank_pattern:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

Esto mantiene el presupuesto total de parámetros de LoRA similar al de las capas densas (véase LoRA Without Regret de Schulman et. al.). Los módulos no expertos utilizan el rango predeterminado r.

La inferencia acelerada con el modelo afinado es posible, por ejemplo, con vLLM, que admite capas de expertos MoE fusionadas desde la v0.11.2.

Entrenar de manera eficiente tokens junto con LoRA

Los adaptadores LoRA de PEFT admiten la adición de nuevos tokens mediante el parámetro trainable_token_indices. Esto permite ajustar otros tokens junto con el ajuste fino de capas específicas. Solo se entrenan los tokens especificados y todos los demás permanecen intactos. Esto ahorra memoria y no descarta el contexto aprendido de las incorporaciones de tokens existentes, a diferencia de entrenar toda la matriz de incorporaciones. Internamente, este método utiliza la capa de TrainableTokensModel.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

En el fragmento de código a continuación, mostramos cómo agregar nuevos tokens al modelo y cómo entrenarlo junto con las demás capas del modelo.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

Los pesos de los tokens se guardan como parte del estado del adaptador, junto con los pesos de LoRA. El ajuste fino completo y el guardado de la matriz de incrustaciones habrían almacenado un archivo mucho más grande.

Para dar una idea de la cantidad de VRAM que se puede ahorrar, se realizó una comparación rudimentaria del ejemplo anterior entre entrenar la matriz de embeddings por completo (modules_to_save=["embed_tokens"]), usar un LoRA para la matriz de embeddings (target_modules=[..., "embed_tokens"], rango 32) y tokens entrenables (trainable_token_indices=[...], 6 tokens):

Tokens entrenablesLoRAAjuste fino completo
VRAM15,562 MB15,581MB~16.500 MB
Influencia6 tokenstodos los tokenstodos los tokens

Vinculación de pesos

Muchos LM causales utilizan weight tying, donde dos o más pesos comparten los mismos parámetros subyacentes. En el caso más común, los pesos de la incrustación de entrada (embed_tokens) y los pesos de la proyección de salida (lm_head) comparten el mismo tensor. Esto se debe a que reduce los parámetros y generalmente preserva la calidad del modelo.

No siempre es evidente cómo PEFT maneja estos pesos vinculados cuando son objetivo del ajuste fino. Para LoRA, el parámetro ensure_weight_tying en LoraConfig controla si PEFT debe mantener explícitamente vinculadas las actualizaciones del lado del adaptador para esas capas. En la práctica, esto puede afectar a modules_to_save, target_modules y trainable_token_indices. Tenga en cuenta que esta lógica depende en parte de convenciones a la hora de nombrar las capas ("embed_tokens", "lm_head") y no se puede garantizar un funcionamiento correcto si no se utilizan dichas convenciones.

Las tablas siguientes resumen el comportamiento esperado.

modules_to_save

Pesos del modelo base vinculadosensure_weight_tyingForma de LoraConfigComportamiento
NoFalsemodules_to_save=["embed_tokens"] o ["lm_head"]Agregue ModulesToSaveWrapper solo en la capa seleccionada
NoTruemodules_to_save=["embed_tokens"] o ["lm_head"]Avisar y luego añadir ModulesToSaveWrapper solo en la capa seleccionada
SíFalsemodules_to_save=["embed_tokens"] o ["lm_head"]Tratar como separado
SíTruemodules_to_save=["embed_tokens"] o ["lm_head"]Envolver capas vinculadas y mantener los envoltorios vinculados
NoFalsemodules_to_save=["embed_tokens", "lm_head"]Tratar como separado
NoTruemodules_to_save=["embed_tokens", "lm_head"]Avisar y luego tratar como separados
SíFalsemodules_to_save=["embed_tokens", "lm_head"]Avisar y luego tratar como separados
SíTruemodules_to_save=["embed_tokens", "lm_head"]Mantener los ModulesToSaveWrapper vinculados

target_modules

Pesos del modelo base vinculadosensure_weight_tyingForma de LoraConfigComportamiento
NoFalsetarget_modules=["embed_tokens"] o ["lm_head"]Añadir LoRA solo en la capa seleccionada
NoTruetarget_modules=["embed_tokens"] o ["lm_head"]Avisar y luego añadir LoRA solo en la capa seleccionada
SíFalsetarget_modules=["embed_tokens"] o ["lm_head"]Tratar como separado
SíTruetarget_modules=["embed_tokens"] o ["lm_head"]Mantener los adaptadores LoRA vinculados
NoFalsetarget_modules=["embed_tokens", "lm_head"]Tratar como separado
NoTruetarget_modules=["embed_tokens", "lm_head"]Avisar y luego tratar como separados
SíFalsetarget_modules=["embed_tokens", "lm_head"]Avisar y luego tratar como separados
SíTruetarget_modules=["embed_tokens", "lm_head"]Mantener los adaptadores LoRA vinculados

trainable_token_indices

Para los tokens entrenables, existe la complicación adicional de que, incluso si la cabeza del LM y los embeddings están vinculados, como usuario puedo querer afinar tokens diferentes en ellos. En la tabla de ejemplo a continuación, distinguimos entre afinar los mismos tokens y afinar tokens diferentes.

Pesos del modelo base vinculadosensure_weight_tyingForma de LoraConfigComportamiento
NoFalsetrainable_token_indices=[1, 2, 3]Tokens entrenables solo en embeddings
NoTruetrainable_token_indices=[1, 2, 3]Avisar, luego tokens entrenables solo en embeddings
SíFalsetrainable_token_indices=[1, 2, 3]Tokens entrenables vinculados
SíTruetrainable_token_indices=[1, 2, 3]Tokens entrenables vinculados
NoFalsetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [1, 2]}Tratar como separado
NoTruetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [1, 2]}Avisar y luego tratar como separados
SíFalsetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [1, 2]}Tokens entrenables vinculados
SíTruetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [1, 2]}Tokens entrenables vinculados
NoFalsetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [3, 4]}Tratar como separado
NoTruetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [3, 4]}Avisar y luego tratar como separados
SíFalsetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [3, 4]}Tratar como separado
SíTruetrainable_token_indices={"lm_head": [1, 2], "embed_tokens": [3, 4]}Error

Para los usuarios, esto significa:

  • En general, si desea ajustar los pesos que están vinculados y quiere mantenerlos vinculados, pase ensure_weight_tying=True.
  • Si los pesos del modelo base no están vinculados, ensure_weight_tying=True no puede forzar la vinculación y solo emite una advertencia.
  • Para trainable_token_indices, las capas vinculadas deben usar los mismos índices de tokens cuando ensure_weight_tying=True.

Optimizers

El entrenamiento con LoRA puede incluir opcionalmente optimizadores de propósito especial. Actualmente, PEFT admite LoRA-FA, LoRA+ y LoRA con precondicionamiento riemanniano.

Optimizador LoRA-FA

El entrenamiento con LoRA puede ser más efectivo y eficiente al utilizar LoRA-FA, tal como se describe en LoRA-FA. LoRA-FA reduce el consumo de memoria de activaciones al fijar la matriz A y ajustar únicamente la matriz B. Durante el entrenamiento, el gradiente de B se optimiza para aproximar el gradiente del ajuste fino de parámetros completo. Además, el consumo de memoria de LoRA-FA no es sensible al rango (ya que elimina la activación de $A$), por lo que puede mejorar el rendimiento aumentando el rango de LoRA sin incrementar el consumo de memoria.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ optimizado

El entrenamiento de LoRA se puede optimizar mediante LoRA+, que utiliza tasas de aprendizaje diferentes para las matrices de adaptador A y B, lo que ha demostrado aumentar la velocidad de ajuste fino hasta 2 veces y el rendimiento en un 1-2 %.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA con precondicionamiento riemanniano

El entrenamiento de LoRA puede mejorarse con un precondicionador riemanniano, como se describe en Riemannian Preconditioned LoRA. En cada paso del optimizador, los gradientes de las matrices LoRA AA y BB se multiplican por un r×rr \times r precondicionador que reescala el gradiente euclidiano hacia la dirección riemanniana (gradiente escalado) en la variedad de matrices de bajo rango, lo que mejora la condición de la actualización y puede mejorar la convergencia. Dado que el precondicionador es $r \times r$, su sobrecarga de memoria y tiempo de ejecución es pequeña en el rango de LoRA. create_riemannian_optimizer envuelve cualquier clase de optimizador base (p. ej. torch.optim.AdamW o torch.optim.SGD): los parámetros que no son de LoRA se actualizan sin cambios por el optimizador base, y solo nn.Linear-capas LoRA con forma delora_A / lora_B) se precondicionan.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg es un término de amortiguación que se añade a la r×rr \times r diagonal de la matriz antes de la inversión; estabiliza el precondicionador cuando un factor de LoRA es (casi) de rango deficiente.

Entrenamiento posterior

Esta sección muestra posibles métodos de posprocesamiento para adaptadores entrenados.

Fusionar los pesos de LoRA en el modelo base

Aunque LoRA es significativamente más pequeño y rápido de entrenar, es posible que encuentres problemas de latencia durante la inferencia debido a la carga separada del modelo base y del adaptador LoRA. Para eliminar la latencia, usa la función merge_and_unload() para fusionar los pesos del adaptador con el modelo base. Esto te permite utilizar el modelo recién fusionado como un modelo independiente. La función merge_and_unload() no mantiene los pesos del adaptador en memoria.

A continuación se muestra un diagrama que explica la intuición detrás de la fusión de adaptadores LoRA:

A continuación, mostramos en los fragmentos de código cómo ejecutarlo usando PEFT.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

Es importante asignar el modelo devuelto a una variable y usarlo, merge_and_unload() no es una operación in situ. Si necesitas conservar una copia de los pesos para poder desintegrar el adaptador más adelante o eliminar y cargar otros diferentes, debes usar la función merge_adapter() en su lugar. Ahora tienes la opción de usar unmerge_adapter() para devolver el modelo base.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

En un modelo cuantizado, la desintegración no es exacta: la integración recuantiza el peso base, y los ciclos repetidos de integración y desintegración pueden acumular error de redondeo. Consulte Integración de adaptadores en pesos cuantizados.

Si varios adaptadores están activos y solo algunos se fusionan, los adaptadores que no se fusionan no se aplican de forma silenciosa. Este comportamiento cambiará en PEFT v1.0. Consulte Fusionar solo algunos de los adaptadores activos.

La función add_weighted_adapter() resulta útil para fusionar varios LoRA en un nuevo adaptador según un esquema de ponderación proporcionado por el usuario en el parámetro weights. A continuación se muestra un ejemplo de principio a fin.

Primero, carga el modelo base:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

Luego, cargamos el primer adaptador:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

Luego, cargue un adaptador diferente y combínelo con el primero:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

Existen varios métodos admitidos para combination_type. Consulte la documentación para obtener más detalles. Tenga en cuenta que “svd” como combination_type no se admite al utilizar torch.float16 o torch.bfloat16 como tipo de datos.

Ahora, realiza la inferencia:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

Recuperar el rendimiento del modelo base mediante la reducción de la dimensión del intruso

El artículo LoRA vs Full Fine-tuning: An Illusion of Equivalence sostiene que el entrenamiento con LoRA introduce dimensiones adicionales en los pesos que tienen muy poco en común con los pesos ya aprendidos y provocan el olvido de información previamente adquirida. PEFT implementa la mitigación sugerida en peft.tuners.lora.intruders.reduce_intruder_dimension().

La mitigación tomará un modelo PEFT con un LoRA cargado y creará un nuevo adaptador modificado que se cargará junto con el adaptador existente y será el adaptador activo.

Ejemplo de uso:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

Hay algunos hiperparámetros que se pueden utilizar para ajustar la eficacia de la mitigación, pero, como se evidencia en la Figura 8 del artículo, siempre habrá un compromiso entre la precisión de la tarea aprendida por el adaptador y el olvido del conocimiento del modelo base. La mitigación eliminará información del adaptador para reducir el impacto en el olvido del conocimiento previo, pero esto también significa que se pierde cierta información sobre la tarea aprendida por el adaptador.

Aunque los valores predeterminados están configurados para ofrecer un buen equilibrio entre los dos factores, no está garantizado que se mantengan para su adaptador, su modelo y sus datos, por lo que es recomendable tener un benchmark preparado para medir el efecto.

Cargar adaptadores

Los adaptadores se pueden cargar en un modelo preentrenado con load_adapter(), lo cual es útil para probar diferentes adaptadores cuyos pesos no están fusionados. Establece los pesos del adaptador activo con la función set_adapter().

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

Para devolver el modelo base, puedes usar unload() para descargar todos los módulos de LoRA o delete_adapter() para eliminar el adaptador por completo. unload() no es una operación in situ; recuerda asignar el modelo devuelto a una variable y usarlo.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Paralelismo de tensores

LoRA admite Tensor Parallelism (TP) tal como lo proporciona Transformers. Cuando se carga un modelo base con un tp_plan, PEFT detecta automáticamente la configuración de TP de cada módulo objetivo y añade los hooks apropiados a los pesos del adaptador LoRA para que participen correctamente en el cálculo tensor-parallel.

El soporte de Tensor Parallelism para LoRA requiere transformers >= 5.4.0. La API de Tensor Parallelism basada en DTensor requiere peft >= 0.21.1 y transformers >= 5.17.0.

El uso es idéntico al flujo de trabajo estándar de LoRA: simplemente cargue el modelo base con un tp_plan antes de envolverlo con PEFT:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

Guardar y cargar funcionan como de costumbre mediante save_pretrained / from_pretrained. PEFT reúne los pesos del adaptador fragmentados en tensores completos antes de guardar, por lo que los puntos de control son portátiles e independientes del número de dispositivos utilizados durante el entrenamiento.

Si aplica paralelismo de tensores sin un plan de TP, por ejemplo con parallelize_module de PyTorch, PEFT dimensiona los pesos LoRA de un nn.Linear fragmentado al tamaño de su fragmento local si la malla de dispositivos del peso tiene una dimensión llamada "tp", y a la forma completa de la capa en caso contrario (como con FSDP2). PEFT no añade ganchos de TP a estos pesos LoRA ni los reúne al guardar. Si la dimensión de su malla de TP tiene un nombre diferente, añádala antes de crear el modelo PEFT:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

Inferencia

Esta sección muestra lo que puedes hacer durante el tiempo de inferencia con LoRA, como desacoplar el adaptador.

LoRA activado (aLoRA)

Activated LoRA (aLoRA) es una arquitectura de adaptadores de bajo rango para LMs causales que reutiliza la caché KV del modelo base existente para una inferencia más eficiente. Este enfoque es más adecuado para pipelines de inferencia que dependen del modelo base para la mayoría de las tareas/generaciones, pero utilizan adaptador(es) aLoRA para realizar tarea(s) especializada(s) dentro de la cadena. Por ejemplo, verificar o corregir las salidas generadas por el modelo base. En estos escenarios, los tiempos de inferencia pueden acelerarse en un orden de magnitud o más. Para obtener más información sobre aLoRA y muchos casos de uso de ejemplo, consulte el paper de aLoRA.

Esta técnica busca la última aparición de una secuencia de invocación (alora_invocation_tokens) en cada entrada (que puede ser tan corta como 1 token). Activa los pesos del adaptador en los tokens que comienzan desde el inicio de la secuencia de invocación. Las entradas posteriores a la secuencia de invocación también se adaptan, y todos los tokens generados utilizarán los pesos adaptados. Los pesos de los tokens anteriores se dejan sin adaptar, lo que hace que la caché de esos tokens sea intercambiable con la caché del modelo base debido a la máscara de atención causal en los LM causales. El uso es muy similar al de LoRA estándar. La diferencia clave es que la secuencia de invocación debe especificarse al crear el adaptador:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

`alora_invocation_tokens` es una lista de ids de tokens enteros. Dada una cadena de invocación deseada, esto se puede obtener como:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

El tokenizador es el tokenizador del modelo base. Use add_special_tokens=False para evitar añadir los tokens SOS/EOS en nuestra cadena de búsqueda (lo cual probablemente hará que la búsqueda falle).

Notas

  • aLoRA solo se admite para tareas de task_type=CAUSAL_LM debido a su enfoque en la reutilización de caché.
  • Dado que los pesos se adaptan con menos tokens, a menudo (no siempre) aLoRA requiere un rango (r) más alto que LoRA. r=32 puede ser un buen punto de partida.
  • Los pesos de aLoRA no pueden fusionarse en el modelo base por definición, ya que los pesos del adaptador se aplican selectivamente a un subconjunto de tokens. Los intentos de fusión lanzarán errores.
  • La búsqueda por haz (beam search) aún no está admitida.
  • En general, no se recomienda añadir nuevos tokens al tokenizador que no estén presentes en el modelo base. Esto puede complicar el caso de uso objetivo de que tanto el modelo base como el modelo adaptador operen sobre un contexto superpuesto. Puede evitarlo añadiendo tokens entrenables al modelo base antes de entrenar el adaptador.
  • aLoRA a veces puede usarse como sustituto de Gated LoRA (popular en algunas implementaciones de predicción de múltiples tokens), ya que se pueden usar tokens personalizados para dirigir la activación del adaptador (es decir, el gating) o proporcionar los offsets de aLoRA uno mismo. La única diferencia es que, una vez que el adaptador está activo, no hay forma de desactivarlo hasta que la secuencia termina.

Elección de la secuencia de invocación y diseño del SFT

Debes añadir la secuencia alora_invocation_tokens porque no se añade automáticamente. Recomendamos activar los pesos del adaptador de forma temprana (al inicio de cualquier indicación específica del adaptador), pero después de cualquier entrada larga, para maximizar el rendimiento del modelo sin comprometer la reutilización de la caché. Como con cualquier modelo, el formato debe ser coherente entre el entrenamiento y la prueba.

Considere el siguiente ejemplo, en el que el modelo base tiene una plantilla de chat y el objetivo es entrenar el adaptador para generar una salida deseada.

  • Opción 1: Si no hay un prompt específico para la tarea, es decir, si la entrada es un historial de chat con el prompt de assistant, entonces el prompt de assistant de la plantilla de chat (por ejemplo, <|start_of_role|>assistant<|end_of_role|>) es una elección natural para la cadena de invocación. Consulte la plantilla de chat del modelo para encontrar el prompt del modelo.
  • Opción 2: Si existe un prompt específico de la tarea para el adaptador que describe la tarea que el adaptador está aprendiendo, y ese prompt se coloca como un turno de user inmediatamente antes de la generación, entonces el prompt de user de la plantilla de chat (p. ej. <|start_of_role|>user<|end_of_role|>) es una opción natural para la cadena de invocación.

Después de decidir la cadena de invocación, obtenga el tokenizador del modelo y obtenga alora_invocation_tokens como

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Un ejemplo de configuración de inferencia se encuentra en alora finetuning.

Si se usan cadenas personalizadas para la cadena de invocación, asegúrese de que el inicio y el final de la cadena sean tokens especiales para evitar problemas con la tokenización en los límites.

Para entender por qué, imagina que ‘a’, ‘b’, ‘c’ y ‘ab’ son tokens en tu tokenizer (los números 1, 2, 3 y 4, respectivamente). Supongamos que tu alora_invocation_tokens = [2, 3]. Ahora imagina que tu cadena de entrada es “abc”. Dado que “ab” es un token, esto se tokenizará como [4,3]. Por lo tanto, alora_invocation_tokens no se encontrará, a pesar de que la cadena “bc” esté presente. Sin embargo, si el inicio y el final de la cadena de invocación son tokens especiales, este caso de fallo nunca ocurrirá, ya que los tokens especiales nunca se tokenizan en el mismo token junto con otros caracteres.

Uso (y reutilización) de la caché para la generación

El propósito principal de aLoRA es hacer que la caché KV sea intercambiable entre el modelo base y los modelos de adaptador aLoRA antes de la secuencia de invocación, ya que los valores KV base y adaptados no son compatibles. Específicamente, las claves y los valores almacenados durante una generación de un modelo pueden utilizarse en generaciones posteriores para evitar costosas operaciones de prefill para los tokens de contexto. Al compartir la caché entre el modelo base y los adaptadores aLoRA, existen 2 patrones principales:

  1. El modelo base ha generado algo y luego se llama a un adaptador aLoRA para realizar una generación de seguimiento. Por ejemplo, el modelo base responde a una pregunta y un aLoRA entrenado para detectar alucinaciones comprueba la respuesta del modelo base.
  2. Un adaptador aLoRA ha generado algo y se invoca al modelo base o a un adaptador aLoRA diferente para realizar una generación de seguimiento que presenta una superposición parcial de contexto con el aLoRA original. Por ejemplo, el usuario proporciona una consulta y un aLoRA reescribe la consulta para que sea más autosuficiente y mejore la recuperación en un sistema RAG. A continuación, se recuperan y cargan en el contexto los documentos, el aLoRA comprueba si estos documentos son relevantes para la pregunta y luego el modelo base genera una respuesta.

Para demostrar los comportamientos anteriores al usar caché, utilizamos DynamicCache de transformers. Asegúrese de que los valores de caché adaptados no se mezclen con los valores de caché base. En particular, se requiere un paso adicional para compartir la caché cuando hay una superposición parcial del contexto (patrón 2).

Patrón 1: modelo base seguido de aLoRA Aquí, la entrada completa y la generación del modelo base se introducen en el adaptador aLoRA, junto con la secuencia de invocación:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

Patrón 2: generación con aLoRA seguida del modelo base (o de otro aLoRA) con solapamiento parcial del contexto Aquí, prellenamos el contexto compartido usando el modelo base y luego generamos.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

Inferencia con diferentes adaptadores LoRA en el mismo lote

Normalmente, cada lote de inferencia debe usar el mismo adaptador o adaptadores en PEFT. Esto puede resultar molesto a veces, ya que es posible que tengamos lotes que contengan muestras destinadas a usarse con diferentes adaptadores LoRA. Por ejemplo, podríamos tener un modelo base que funciona bien en inglés y dos adaptadores LoRA más, uno para francés y otro para alemán. Normalmente, tendríamos que dividir nuestros lotes de modo que cada lote solo contenga muestras de uno de los idiomas; no podemos combinar diferentes idiomas en el mismo lote.

Afortunadamente, es posible mezclar diferentes adaptadores LoRA en el mismo lote utilizando el argumento adapter_name. A continuación, mostramos un ejemplo de cómo funciona esto en la práctica. Primero, cargamos el modelo base, el inglés y los dos adaptadores, el francés y el alemán, de la siguiente manera:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

model_id = ...
tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

Ahora, queremos generar texto en una muestra que contiene los tres idiomas: las tres primeras muestras están en inglés, las siguientes tres en francés y las tres últimas en alemán. Podemos usar el argumento adapter_names para especificar qué adaptador usar para cada muestra. Dado que nuestro modelo base se usa para el inglés, usamos la cadena especial "__base__" para estas muestras. Para las siguientes tres muestras, indicamos el nombre del adaptador del ajuste fino de LoRA en francés, en este caso "adapter_fr". Para las tres últimas muestras, indicamos el nombre del adaptador del ajuste fino de LoRA en alemán, en este caso "adapter_de". De esta manera, podemos usar el modelo base y los dos adaptadores en un solo lote.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

Tenga en cuenta que el orden no importa aquí, es decir, las muestras del lote no necesitan agruparse por adaptador como en el ejemplo anterior. Solo necesitamos asegurarnos de que el argumento adapter_names esté alineado correctamente con las muestras.

Además, el mismo enfoque también funciona con la función modules_to_save, que permite guardar y reutilizar capas específicas de la red neuronal, como cabezas personalizadas para tareas de clasificación, entre diferentes adaptadores LoRA.

Precauciones

El uso de esta función tiene algunas desventajas, a saber:

  • Solo funciona para inferencia, no para entrenamiento.
  • Desactivar adaptadores mediante el contexto with model.disable_adapter() tiene prioridad sobre adapter_names.
  • No se puede pasar adapter_names cuando algunos pesos de adaptador se han fusionado con los pesos base mediante el método merge_adapter. Primero, desfusiona todos los adaptadores llamando a model.unmerge_adapter(). Ten en cuenta que fusionar solo algunos de los adaptadores activos tiene una advertencia similar fuera de adapter_names.
  • Por razones obvias, esto no se puede usar después de llamar a merge_and_unload(), ya que en ese caso todos los adaptadores LoRA se fusionarán en los pesos base.
  • Esta función no funciona actualmente con DoRA, por lo que debe establecer use_dora=False en su LoraConfig si desea utilizarla.
  • La función modules_to_save actualmente solo se admite para las capas de los tipos Linear, Embedding, Conv2d y Conv1d.
  • Se espera un sobrecoste para la inferencia con adapter_names, especialmente si la cantidad de adaptadores diferentes en el lote es alta. Esto se debe a que el tamaño del lote se reduce efectivamente al número de muestras por adaptador. Si el rendimiento en tiempo de ejecución es tu prioridad principal, prueba lo siguiente:
    • Aumenta el tamaño del lote.
    • Intente evitar tener un gran número de adaptadores diferentes en el mismo lote; prefiera lotes homogéneos. Esto se puede lograr almacenando en un búfer muestras con el mismo adaptador y solo realizar inferencia con un pequeño número de adaptadores diferentes.
    • Echa un vistazo a implementaciones alternativas como LoRAX, punica o S-LoRA, que están especializadas para trabajar con un gran número de adaptadores diferentes.

Componer y reutilizar adaptadores LoRA

Arrow

Arrow es un algoritmo de enrutamiento modular diseñado para combinar múltiples adaptadores LoRA preentrenados y específicos de una tarea para resolver una tarea dada, de manera similar a Polytropon pero sin necesidad de ajuste fino. En lugar de fusionar todos los adaptadores de forma ingenua, Arrow introduce un mecanismo de enrutamiento de mezcla de expertos (MoE) sin gradiente y a nivel de token. En el momento de la inferencia, primero calcula un prototipo para cada LoRA extrayendo el vector singular derecho principal de su descomposición SVD. Luego, cada representación de token se compara con estos prototipos mediante similitud coseno para obtener coeficientes de enrutamiento. Los tokens se asignan a los k adaptadores LoRA más relevantes, con los coeficientes normalizados a través de softmax, y sus salidas se combinan linealmente. Esto permite reutilizar de manera efectiva los módulos LoRA existentes para nuevas tareas y conduce a una generalización cero-shot más robusta.

En PEFT, Arrow se habilita mediante [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Además, puedes añadir o eliminar adaptadores después de llamar a create_arrow_model, por ejemplo, para ajustar un nuevo adaptador o descartar uno innecesario. Una vez que los adaptadores estén en su lugar, puedes activar el "arrow_router" para la inferencia y usar Arrow. Ten en cuenta que si añades un nuevo adaptador LoRA después de create_arrow_model y quieres ajustarlo, debes establecer explícitamente el nuevo adaptador como activo, ya que "arrow_router" se activa de forma predeterminada en create_arrow_model.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub mejora Arrow purificando los adaptadores LoRA específicos de cada tarea antes de enrutarlas. La idea clave es restar el conocimiento general codificado en el espacio LoRA, basado en el principio de olvido mediante negación, para que los adaptadores de tarea queden más aislados y enfocados en las señales relevantes para la tarea. Concretamente, GenKnowSub estima un subespacio “general” de baja dimensión a partir de un conjunto de adaptadores LoRA generales (no específicos de la tarea) y elimina este componente de la actualización LoRA de cada adaptador de tarea antes del enrutamiento por token de Arrow. Esto suele mejorar la composicionalidad y reduce la interferencia al combinar muchos adaptadores de tarea.

En PEFT, active GenKnowSub estableciendo use_gks=True en ArrowConfig y proporcionando general_adapter_paths en create_arrow_model:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Para codificar el conocimiento general, GenKnowSub resta la media de los adaptadores generales proporcionados de cada adaptador específico de la tarea una sola vez, antes de que comience el enrutamiento. Además, en este caso se sigue admitiendo la posibilidad de añadir o eliminar adaptadores después de llamar a create_arrow_model (como se describe en la sección Arrow).

Aspectos a tener en cuenta al usar Arrow + GenKnowSub:

  • Todos los adaptadores LoRA (específicos de la tarea y generales) deben compartir el mismo rank y target_modules.

  • Cualquier inconsistencia en estas configuraciones generará un error en create_arrow_model.

  • Se admiten diferentes factores de escala (lora_alpha) entre adaptadores de tareas: Arrow los gestiona automáticamente.

  • La fusión de "arrow_router" no está admitida debido a su comportamiento de enrutamiento dinámico.

  • En create_arrow_model, los adaptadores de tarea se cargan como task_i y los adaptadores generales como gks_j (donde i y j son índices). La función garantiza la coherencia de target_modules, rank y si los adaptadores se aplican a capas Linear o Linear4bit. A continuación, añade el módulo "arrow_router" y lo activa. Cualquier personalización de este proceso requiere sobrescribir create_arrow_model.

  • Esta implementación es compatible con la cuantización de 4 bits (a través de bitsandbytes):

    from transformers import AutoModelForCausalLM, BitsAndBytesConfig
    import torch
    
    # Quantisation config
    bnb_config = BitsAndBytesConfig(
            load_in_4bit=True,
            bnb_4bit_quant_type="nf4",
            bnb_4bit_compute_dtype=torch.bfloat16,
            bnb_4bit_use_double_quant=False,
        )
    
    # Loading the model
    base_model = AutoModelForCausalLM.from_pretrained(
        "microsoft/Phi-3-mini-4k-instruct",
        dtype=torch.bfloat16,
        device_map="auto",
        quantization_config=bnb_config,
    )
    
    # Now call create_arrow_model() as we explained before.

API

LoraConfig

clase peft.LoraConfig

< >

( 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 = 8target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonelora_alpha: int = 8lora_dropout: float = 0.0fan_in_fan_out: bool = Falsebias: Literal['none', 'all', 'lora_only'] = 'none'use_rslora: bool = Falsemodules_to_save: Optional[list[str]] = Noneinit_lora_weights: bool | Literal['gaussian', 'eva', 'olora', 'pissa', 'pissa_niter_[number of iters]', 'corda', 'astra', 'loftq', 'orthogonal', 'mica', 'nora'] = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Nonerank_pattern: Optional[dict] = <factory>alpha_pattern: Optional[dict] = <factory>megatron_config: Optional[dict] = Nonemegatron_core: Optional[str] = 'megatron.core'trainable_token_indices: Optional[Union[list[int], dict[str, list[int]]]] = Noneloftq_config: Union[LoftQConfig, dict] = <factory>eva_config: Optional[EvaConfig] = Nonecorda_config: Optional[CordaConfig] = Noneastra_config: Optional[AstraConfig] = Nonelora_ga_config: Optional[LoraGAConfig] = Noneuse_dora: bool = Falsevelora_config: Optional[Union[VeloraConfig, dict]] = Nonealora_invocation_tokens: Optional[list[int]] = Noneuse_qalora: bool = Falseqalora_group_size: int = 16monteclora_config: Optional[MontecloraConfig] = Nonelayer_replication: Optional[list[tuple[int, int]]] = Noneruntime_config: LoraRuntimeConfig = <factory>lora_bias: bool = Falsetarget_parameters: Optional[list[str]] = Noneuse_bdlora: Optional[BdLoraConfig] = Nonearrow_config: Optional[ArrowConfig] = Nonekasa_config: Optional[KasaConfig] = Noneensure_weight_tying: bool = False )

Parámetros

  • r (int) — Dimensión de atención Lora (el “rango”).
  • target_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que se aplicará el adaptador. Si se especifica, solo se reemplazarán los módulos con los nombres indicados. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se verificará si el nombre del módulo termina con alguna de las cadenas pasadas. Si se especifica como ‘all-linear’, se seleccionarán todos los módulos lineales/Conv1D (si el modelo es un PreTrainedModel, excluyendo la capa de salida). Si no se especifica, los módulos se elegirán según la arquitectura del modelo. Si la arquitectura no es conocida, se generará un error; en este caso, debe especificar los módulos objetivo manualmente. Para evitar apuntar a ningún módulo (porque desea aplicar target_parameters), establezca target_modules=[].
  • exclude_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que no se aplicará el adaptador. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se comprobará si el nombre del módulo termina con alguna de las cadenas de caracteres pasadas.
  • lora_alpha (int) — El parámetro alpha para la escalado de Lora.
  • lora_dropout (float) — La probabilidad de dropout para las capas Lora.
  • fan_in_fan_out (bool) — Establezca este valor en True si la capa que se va a reemplazar almacena los pesos como (fan_in, fan_out). Por ejemplo, gpt-2 utiliza Conv1D, que almacena los pesos como (fan_in, fan_out), por lo que este valor debe establecerse en True.
  • bias (str) — Tipo de sesgo para LoRA. Puede ser ‘none’, ‘all’ o ‘lora_only’. Si se establece en ‘all’ o ‘lora_only’, los sesgos correspondientes se actualizarán durante el entrenamiento. Tenga en cuenta que esto significa que, incluso al desactivar los adaptadores, el modelo no producirá la misma salida que habría producido el modelo base sin adaptación.
  • use_rslora (bool) — Cuando se establece en True, utiliza Rank-Stabilized LoRA, que fija el factor de escalado del adaptador en lora_alpha/math.sqrt(r), ya que se ha demostrado que funciona mejor. En caso contrario, se utilizará el valor predeterminado original de lora_alpha/r.
  • modules_to_save (List[str]) — Lista de módulos, aparte de las capas de adaptador, que se configurarán como entrenables y se guardarán en el punto de control final.
  • init_lora_weights (bool | Literal["gaussian", "eva", "olora", "pissa", "pissa_niter_[number of iters]", "corda", "astra", "loftq", "orthogonal", "mica", "nora"]) — Cómo inicializar los pesos de las capas del adaptador. Pasar True (predeterminado) resulta en la inicialización predeterminada de la implementación de referencia de Microsoft, con el peso LoRA B establecido en 0. Esto significa que, sin entrenamiento adicional, el adaptador LoRA será una operación sin efecto (no-op). Establecer la inicialización en False lleva a una inicialización aleatoria de LoRA A y B, lo que significa que LoRA no es un no-op antes del entrenamiento; esta configuración está destinada a fines de depuración. Pasar 'gaussian' resulta en una inicialización gaussiana escalada por el rango de LoRA para capas lineales y de incrustación. Pasar 'loftq' para usar la inicialización de LoftQ. Pasar 'eva' resulta en una inicialización basada en datos de Adaptación de Varianza Explicada. EVA inicializa LoRA basándose en la SVD de las activaciones de entrada de la capa y logra un rendimiento SOTA debido a su capacidad para adaptarse a los datos de ajuste fino. Pasar 'olora' para usar la inicialización de OLoRA. Pasar 'pissa' resulta en la inicialización de Adaptación de Valores Singulares Principales y Vectores Singulares (PiSSA), que converge más rápidamente que LoRA y logra un rendimiento superior en última instancia. Además, PiSSA reduce el error de cuantización en comparación con QLoRA, lo que conduce a mejoras adicionales. Pasar 'pissa_niter_[número de iteraciones]' inicia la inicialización de PiSSA basada en Fast-SVD, donde [número de iteraciones] indica el número de iteraciones de subespacio para realizar FSVD, y debe ser un entero no negativo. Cuando [número de iteraciones] se establece en 16, puede completar la inicialización de un modelo de 7B en segundos, y el efecto del entrenamiento es aproximadamente equivalente al uso de SVD. Pasar 'corda' resulta en la inicialización de Adaptación de Descomposición Orientada al Contexto, que converge aún más rápidamente que PiSSA en Modo de Vista Previa de Instrucciones y preserva mejor el conocimiento del mundo en Modo de Preservación de Conocimiento. Pasar 'astra' resulta en la inicialización de Adaptación de Bajo Rango de Autovectores de Cola en el Espacio de Activaciones, que proyecta el peso base en el espacio propio de las activaciones de salida estimadas a partir de un pequeño conjunto de datos de calibración. Pasar "orthogonal" resulta en que LoRA A y B se inicialicen ortogonalmente; en esto, se parece a "olora", pero los pesos base se dejan intactos (requiere que r sea par, actualmente solo se admite para capas lineales). Pasar "mica" resulta en la inicialización de Adaptación de Componentes Menores (MiCA), que inicializa B desde los r vectores singulares izquierdos del peso base asociados con los valores singulares más pequeños, establece A en cero y congela B durante el entrenamiento; solo A se actualiza. Actualmente se admite para capas lineales y de incrustación. Pasar "nora" resulta en la inicialización de Adaptación de Bajo Rango Normalizada (NoRA), que normaliza cada columna del peso LoRA A inicializado aleatoriamente a una norma L2 unitaria y establece el peso LoRA B en cero. La normalización se aplica solo en la inicialización; los pesos base no cambian y tanto A como B siguen siendo entrenables. La configuración recomendada es lora_alpha igual a r con use_rslora=False, lo que mantiene una proporción de 1:1 y un factor de escala de 1. Actualmente se admite para capas lineales y para nn.Parameters objetivo con target_parameters.

    Valores singulares principales y vectores singulares Adaptation (PiSSA), que converge más rápidamente que LoRA y finalmente logra un rendimiento superior. Además, PiSSA reduce el error de cuantización en comparación con QLoRA, lo que conduce a mejoras adicionales. Al pasar 'pissa_niter_[number of iters]' se inicia la inicialización de PiSSA basada en Fast-SVD, donde [number of iters] indica el número de iteraciones de subespacio para realizar FSVD, y debe ser un entero no negativo. Cuando [number of iters] se establece en 16, puede completar la inicialización de un modelo de 7B en segundos, y el efecto del entrenamiento es aproximadamente equivalente al de usar SVD. Al pasar 'corda' se produce la inicialización de Context-Oriented Decomposition Adaptation, que converge aún más rápidamente que PiSSA en el modo Instruction-Previewed Mode, y preserva mejor el conocimiento del mundo que LoRA en el modo Knowledge-Preserved Mode. Al pasar 'astra' se produce la inicialización de Activation-Space Tail-Eigenvector Low-Rank Adaptation, que proyecta el peso base en el espacio propio de las activaciones de salida estimadas a partir de un pequeño conjunto de datos de calibración. Al pasar "orthogonal" se produce que LoRA A y B se inicialicen de forma ortogonal; en esto, se parece a "olora", pero los pesos base se dejan intactos (requiere que r sea par, solo soportado actualmente para capas lineales). Al pasar "mica" se produce la inicialización de Minor Component Adaptation (MiCA), que inicializa B a partir de los r vectores singulares izquierdos del peso base asociados con los valores singulares más pequeños, establece A en cero y congela B durante el entrenamiento; solo A se actualiza. Actualmente soportado para capas lineales y de incrustación. Al pasar "nora" se produce la inicialización de Normalized Low-Rank Adaptation (NoRA), que normaliza cada columna del peso LoRA A inicializado aleatoriamente a una norma L2 unitaria y establece el peso LoRA B en cero. La normalización se aplica solo en la inicialización; los pesos base no cambian y tanto A como B permanecen entrenables. La configuración recomendada es lora_alpha igual a r con use_rslora=False, lo que mantiene una proporción de 1:1 y un factor de escala de 1. Actualmente soportado para capas lineales y para nn.Parameters dirigidos con target_parameters.

  • layers_to_transform (Union[List[int], int]) — Los índices de las capas a transformar. Si se pasa una lista de enteros, se aplicará el adaptador a los índices de capa especificados en esta lista. Si se pasa un solo entero, se aplicarán las transformaciones a la capa en este índice.
  • layers_pattern (Optional[Union[List[str], str]]) — El nombre del patrón de capas, utilizado solo si layers_to_transform es diferente de None. Esto debe apuntar al nn.ModuleList del modelo, que a menudo se llama 'layers' o 'h'.
  • rank_pattern (dict) — El mapeo de nombres de capas o expresiones regulares a los rangos que difieren del rango predeterminado especificado por r. Por ejemplo, {'^model.decoder.layers.0.encoder_attn.k_proj': 16}.
  • alpha_pattern (dict) — El mapeo de nombres de capas o expresiones regulares a alfas que difieren del alfa predeterminado especificado por lora_alpha. Por ejemplo, {'^model.decoder.layers.0.encoder_attn.k_proj': 16}.
  • megatron_config (Optional[dict]) — Los argumentos de TransformerConfig para Megatron. Se utiliza para crear la capa lineal paralela de LoRA. Puedes obtenerlo de esta manera, core_transformer_config_from_args(get_args()), donde estas dos funciones provienen de Megatron. Los argumentos se usarán para inicializar el TransformerConfig de Megatron. Debes especificar este parámetro cuando quieras aplicar LoRA a las capas ColumnParallelLinear y RowParallelLinear de megatron.
  • megatron_core (Optional[str]) — El módulo principal de Megatron a utilizar, por defecto es "megatron.core".
  • trainable_token_indices (Optional[Union[List[int], dict[str, List[int]]]]) — Permite especificar qué índices de tokens se deben ajustar de forma selectiva, sin necesidad de volver a entrenar toda la matriz de embeddings, utilizando el método peft.TrainableTokensModel. Puedes especificar los índices de tokens de dos maneras. O bien especificas una lista de índices, que apuntará a la capa de embeddings de entrada del modelo (o, si no se encuentra, a embed_tokens). Alternativamente, puedes especificar un diccionario donde la clave es el nombre del módulo de embeddings y los valores son la lista de índices de tokens, por ejemplo {'embed_tokens': [0, 1, ...]}. Ten en cuenta que el entrenamiento con FSDP requiere use_orig_params=True para evitar problemas con requires_grad no uniforme.
  • loftq_config (Optional[LoftQConfig]) — La configuración de LoftQ. Si este valor no es None, se utilizará LoftQ para cuantizar los pesos del backbone e inicializar las capas Lora. También pase init_lora_weights='loftq'. Tenga en cuenta que no debe pasar un modelo cuantizado en este caso, ya que LoftQ cuantizará el modelo por sí mismo. LoftQ solo se aplica a capas lineales, incluidas aquellas dirigidas mediante target_parameters. Las capas de embedding y convolucionales no son compatibles y utilizan la inicialización predeterminada de LoRA en su lugar. Las capas nn.MultiheadAttention no son compatibles y provocan un error.
  • eva_config (Optional[EvaConfig]) — La configuración de EVA. Como mínimo, se debe establecer el argumento de dataset (use el mismo dataset que para el finetuning).
  • corda_config (Optional[CordaConfig]) — La configuración de CorDA. Si este valor no es None, se utilizará CorDA para construir las capas del adaptador. También pase init_lora_weights='corda'.
  • astra_config (Optional[AstraConfig]) — La configuración de Astra. Si este valor no es None, Astra se utilizará para construir las capas del adaptador. En este caso, también pase init_lora_weights='astra' y llame a preprocess_astra antes de get_peft_model.
  • lora_ga_config (Optional[LoraGAConfig]) — La configuración de LoRA-GA. Si se pasa este parámetro, se utilizará LoRA-GA para inicializar las capas del adaptador. En este caso, también se debe establecer init_lora_weights='lora_ga'.
  • use_dora (bool) — Activa ‘Weight-Decomposed Low-Rank Adaptation’ (DoRA). Esta técnica descompone las actualizaciones de los pesos en dos partes, magnitud y dirección. La dirección se maneja con LoRA normal, mientras que la magnitud se maneja mediante un parámetro de aprendizaje separado. Esto puede mejorar el rendimiento de LoRA, especialmente en rangos bajos. Por ahora, DoRA solo admite capas lineales y Conv2D. DoRA introduce una sobrecarga mayor que la de LoRA puro, por lo que se recomienda fusionar los pesos para la inferencia. Para obtener más información, consulte https://huggingface.co/papers/2402.09353.
  • velora_config (Optional[VeloraConfig]) — Habilita VeLoRA proporcionando un VeloraConfig. VeLoRA sustituye la pasada de retropropagación (backward pass) personalizada para la proyección A de LoRA, que almacena activaciones comprimidas en lugar de las activaciones de entrada completas.
  • kasa_config (Optional[KasaConfig]) — Habilita KaSA (Knowledge-aware Singular-value Adaptation) proporcionando un KasaConfig. KaSA trunca los r componentes singulares más pequeños del peso base congelado mediante una SVD de una sola vez e inserta una diagonal aprendible de valores singulares entre los factores A y B de LoRA. Actualmente solo se admiten capas lineales.
  • alora_invocation_tokens (List[int]) — Si no es None, habilita ‘Activated LoRA’ (aLoRA), donde alora_invocation_tokens es la cadena de invocación tokenizada para el adaptador (debe estar presente en todas las cadenas de entrada del modelo). Esta técnica activa selectivamente los pesos del adaptador solo en los tokens durante y después de alora_invocation_tokens. Cuando se usa en un CausalLM, esto significa que la caché KV previa a la invocación es intercambiable con la del modelo base (y con otros adaptadores aLoRA que operen de esta manera). Como resultado, en pipelines de inferencia que implican alternar entre la inferencia del modelo base y la inferencia del adaptador (p. ej. pipelines agénticos, ver el paper para ejemplos), se logran ahorros significativos (en comparación con LoRA) al guardar las operaciones de prefill. Las aceleraciones generales de la inferencia del adaptador pueden ser de un orden de magnitud o más en vLLM, dependiendo de la longitud del contexto compartido. Tenga en cuenta que la fusión no es posible debido a la aplicación selectiva de los pesos.
  • use_qalora (bool) — Por ahora solo está implementado en GPTQ. Habilita Quantization-Aware Low-Rank Adaptation (QALoRA). Esta técnica combina el entrenamiento consciente de la cuantización con LoRA para mejorar el rendimiento de los modelos cuantizados. Esto puede mejorar el rendimiento de LoRA, especialmente en rangos bajos. Por ahora, QALoRA solo admite capas lineales.
  • qalora_group_size (int) — Parámetro de tamaño de grupo para el pooling de QALoRA, que controla el factor de reducción de dimensión. Las dimensiones de entrada se agrupan en grupos de este tamaño, reduciendo el coste computacional. Valores más altos proporcionan más compresión, pero pueden reducir la calidad del modelo. Este parámetro determina cuántas características originales se promedian para crear una característica agrupada. Solo se utiliza cuando use_qalora=True.
  • monteclora_config (Optional[MontecloraConfig]) — La configuración de Monteclora (Monte Carlo Low-Rank Adaptation). Si se pasa, Monteclora se usará para añadir muestreo variacional de Monte Carlo sobre los adaptadores LoRA. Consulte MontecloraConfig para obtener detalles sobre los hiperparámetros individuales.
  • layer_replication (List[Tuple[int, int]]) — Construye una nueva pila de capas apilando las capas del modelo original según los rangos especificados. Esto permite expandir (o reducir) el modelo sin duplicar los pesos del modelo base. A las nuevas capas se les adjuntarán adaptadores LoRA separados.
  • runtime_config (LoraRuntimeConfig) — Configuraciones de tiempo de ejecución (que no se guardan ni se restauran).
  • lora_bias (bool) — Por defecto, False. Indica si se debe habilitar el término de sesgo para el parámetro B de LoRA. Por lo general, esto debe desactivarse. El caso de uso principal es cuando los pesos de LoRA se extrajeron de parámetros totalmente ajustados, de modo que se pueda tener en cuenta el sesgo de dichos parámetros.
  • target_parameters (List[str], opcional) — Lista de nombres de parámetros a reemplazar con LoRA. Este argumento se comporta de manera similar a target_modules, con la excepción de que debe pasarse el nombre del parámetro. Generalmente, se debe usar target_modules para apuntar al módulo (p. ej. nn.Linear). Sin embargo, en algunas circunstancias, esto no es posible. Por ejemplo, en muchas capas de mezcla de expertos (MoE) de HF Transformers, en lugar de usar nn.Linear, se utiliza un nn.Parameter. PEFT normalmente sobrescribe el método forward para LoRA, pero para nn.Parameter, no existe ninguno. Por lo tanto, para aplicar LoRA a ese parámetro, es necesario apuntar a él con target_parameters. Como ejemplo, para Llama4, se puede pasar: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj]. El paso de una cadena para coincidencia con expresiones regulares aún no está implementado. Tenga en cuenta que cuando el modelo está compilado y usa target_parameters, se espera una recompilación y/o rupturas de grafo. Se recomienda no usar ambos al mismo tiempo.
  • use_bdlora (Optional[BdLoraConfig]) — Habilita BD-LoRA (Block-Diagonal LoRA) proporcionando una BdLoraConfig. Esta técnica utiliza matrices bloque-diagonales para los factores LoRA-A o LoRA-B para permitir un servicio multi-LoRA más rápido al eliminar las sobrecargas de comunicación en entornos distribuidos.
  • arrow_config (Optional[ArrowConfig]) — La configuración necesaria para aplicar el enrutamiento de arrow en el modelo.
  • ensure_weight_tying (bool, opcional) — Si se deben vincular los pesos o no después de la inicialización de peft. Esto asegurará que los adaptadores añadidos a las capas vinculadas también queden vinculados. Esto solo es aplicable a las capas pasadas a través de modules_to_save y target_modules.

Esta es la clase de configuración para almacenar la configuración de un LoraModel.

to_dict

< >

( )

Devuelve la configuración de tu modelo de adaptador como un diccionario. Elimina las configuraciones de tiempo de ejecución.

LoraModel

clase peft.LoraModel

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None ) → torch.nn.Module

Parámetros

  • model (torch.nn.Module) — El modelo que se va a adaptar.
  • config (LoraConfig) — La configuración del modelo Lora.
  • adapter_name (str) — El nombre del adaptador, por defecto es "default".
  • low_cpu_mem_usage (bool, optional, defaults to False) — Crea pesos de adaptador vacíos en el dispositivo meta. Útil para acelerar el proceso de carga.

Devuelve

torch.nn.Module

El modelo Lora.

Crea un modelo Low Rank Adapter (LoRA) a partir de un modelo de transformers preentrenado.

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

Ejemplo:

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)
>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

Atributos:

add_weighted_adapter

< >

( adapters: list[str]weights: list[float]adapter_name: strcombination_type: Literal['svd', 'linear', 'cat', 'ties', 'ties_svd', 'dare_ties', 'dare_linear', 'dare_ties_svd', 'dare_linear_svd', 'magnitude_prune', 'magnitude_prune_svd'] = 'svd'svd_rank: int | None = Nonesvd_clamp: int | None = Nonesvd_full_matrices: bool = Truesvd_driver: str | None = Nonedensity: float | None = Nonemajority_sign_method: Literal['total', 'frequency'] = 'total' )

Parámetros

  • adapters (list) — Lista de nombres de adaptadores que se van a fusionar.
  • weights (list) — Lista de pesos para cada adaptador. Los pesos pueden ser positivos o negativos, lo que permite tanto la adición como la sustracción de los efectos de los adaptadores.
  • adapter_name (str) — Nombre del nuevo adaptador.
  • combination_type (str) — El tipo de fusión puede ser uno de [svd, linear, cat, ties, ties_svd, dare_ties, dare_linear, dare_ties_svd, dare_linear_svd, magnitude_prune, magnitude_prune_svd]. Al usar el cat como combination_type, el rango del adaptador resultante es igual a la suma de los rangos de todos los adaptadores (el adaptador mixto puede ser demasiado grande y provocar errores de OOM). Tenga en cuenta que cat y svd son métodos precisos y le darán una buena precisión, mientras que linear es eficiente pero una aproximación muy burda y debe evitarse si puede permitírselo.
  • svd_rank (int, opcional) — Rango del adaptador de salida para svd. Si se proporciona None, se usará el rango máximo de los adaptadores fusionados.
  • svd_clamp (float, opcional) — Umbral de cuantil para limitar la salida de la descomposición SVD. Si se proporciona None, no se realiza la limitación. El valor predeterminado es None.
  • svd_full_matrices (bool, opcional) — Controla si se calcula la SVD completa o reducida y, en consecuencia, la forma de los tensores U y Vh devueltos. El valor predeterminado es True.
  • svd_driver (str, opcional) — Nombre del método de cuSOLVER que se utilizará. Este argumento de palabra clave solo funciona al fusionar en CUDA. Puede ser uno de [None, gesvd, gesvdj, gesvda]. Para más información, consulte la documentación de torch.linalg.svd. El valor predeterminado es None.
  • density (float, opcional) — Valor entre 0 y 1. 0 significa que todos los valores se podan y 1 significa que no se podan valores. Debe usarse con [ties, ties_svd, dare_ties, dare_linear, dare_ties_svd, dare_linear_svd, magnintude_prune, magnitude_prune_svd]
  • majority_sign_method (str) — El método, que debe ser uno de [“total”, “frequency”], para obtener la magnitud de los valores de signo. Debe usarse con [ties, ties_svd, dare_ties, dare_ties_svd]

Este método añade un nuevo adaptador fusionando los adaptadores dados con los pesos dados.

Al usar el combination_type cat, debe tener en cuenta que el rango del adaptador resultante será igual a la suma de los rangos de todos los adaptadores. Por lo tanto, es posible que el adaptador mixto se vuelva demasiado grande y provoque errores de OOM.

subtract_mutated_init

< >

( output_state_dict: dict[str, torch.Tensor]adapter_name: strkwargs = None )

Esta función puede calcular las actualizaciones de PiSSA/CorDA/OLoRA comparando los parámetros del adaptador PiSSA/CorDA/OLoRA en output_state_dict con los valores iniciales de PiSSA/CorDA/OLoRA en adapter_name, convirtiendo así PiSSA/CorDA/OLoRA en LoRA.

Métodos como PiSSA eliminan una parte de los pesos base del modelo para el entrenamiento y, por lo tanto, no se pueden intercambiar fácilmente. Pero si conoces tanto los pesos de preentrenamiento inicial como los de posentrenamiento, puedes calcular el \Delta W y usarlo como un adaptador LoRA.

Pasos de cálculo:

  • W=Wres+A0B0W = W_{res} + A_0 B_0 (inicialización de PiSSA)
  • W+ΔW=Wres+ABW + \Delta W = W_{res} + A B (PiSSA después del entrenamiento)
  • ΔW=Wres+AB−W=Wres+AB−Wres−A0B0\Delta W = W_{res} + AB - W = W_{res} + AB - W_{res} - A_0 B_0 (Derivación de dW para LoRA)
  • ΔW=AB−A0B0\Delta W = AB - A_0 B_0

Utilidad

ArrowConfig

clase peft.ArrowConfig

< >

( top_k: int = 3router_temperature: float = 1.0use_gks: bool = Falserng_seed: Optional[int] = None )

Esta es la clase de subconfiguración para almacenar la configuración del algoritmo Arrow y GenKnowSub. Arrow es un algoritmo de enrutamiento para combinar los módulos LoRA entrenados con el fin de resolver nuevas tareas, propuesto en ’https://huggingface.co/papers/2405.11157’. GenKnowSub es un refinamiento de los módulos entrenados antes de ser combinados vía Arrow, introducido en ’https://aclanthology.org/2025.acl-short.54/’

LoftQ

replace_lora_weights_loftq

peft.replace_lora_weights_loftq

< >

( peft_modelmodel_path: Optional[str] = Noneadapter_name: str = 'default'callback: Optional[Callable[[torch.nn.Module, str], bool]] = None )

Parámetros

  • peft_model (PeftModel) — El modelo cuyos pesos se van a reemplazar. Debe ser un modelo PEFT cuantizado con capas LoRA.
  • model_path (Optional[str]) — La ruta al archivo safetensors del modelo. Si el modelo es un modelo de Hugging Face, esta se inferirá a partir de la configuración del modelo. En caso contrario, debe proporcionarse.
  • adapter_name (str) — El nombre del adaptador para reemplazar los pesos. El nombre de adaptador predeterminado es “default”.
  • callback (Optional[Callable[[PeftModel, str], bool]]) — Una función de callback que se llamará después de que cada módulo sea reemplazado. La función de callback debe tomar el modelo y el nombre del módulo actual como entrada y devolver un booleano que indique si el reemplazo debe conservarse. Si el callback devuelve False, el reemplazo se revertirá. Esto puede ser muy útil para confirmar que la inicialización de LoftQ realmente reduce el error de cuantización del modelo. Como ejemplo, este callback podría generar logits para una entrada dada y compararlos con los logits del modelo original, no cuantizado, con la misma entrada, y solo devolver True si hay una mejora. Dado que se trata de una optimización codiciosa, es posible que llamar a esta función varias veces produzca mejoras incrementales.

Reemplaza los pesos LoRA de un modelo cuantizado con bitsandbytes, utilizando la técnica LoftQ.

La sustitución se realiza sobre la marcha cargando los pesos no cuantizados desde un archivo de modelo safetensors almacenado localmente e inicializando los pesos de LoRA de manera que se minimice el error de cuantización entre los pesos originales y los cuantizados.

Los pesos se cargan de forma perezosa, lo que requiere que el modelo esté almacenado en el formato safetensors.

Según el tamaño del modelo, la llamada a esta función puede tardar algún tiempo en completarse.

LoftQConfig

clase peft.LoftQConfig

< >

( loftq_bits: int = 4loftq_iter: int = 1 )

Parámetros

  • loftq_bits (int) — Bits de cuantización para LoftQ.
  • loftq_iter (int) — Iteraciones alternas para LoftQ.

Esta es la clase de subconfiguración para almacenar la configuración de un LoraModel.

PiSSA

replace_lora_weights_pissa

peft.replace_lora_weights_pissa

< >

( peft_modelmodel_path: Optional[str] = Noneadapter_name: str = 'default'init_lora_weights: str = 'pissa' )

Parámetros

  • peft_model (PeftModel) — El modelo cuyos pesos se van a reemplazar. Debe ser un modelo PEFT con capas LoRA, cuantizado con bitsandbytes 4-bit.
  • model_path (Optional[str]) — La ruta al archivo safetensors del modelo. Si el modelo es un modelo de Hugging Face, esta se inferirá a partir de la configuración del modelo. En caso contrario, debe proporcionarse.
  • adapter_name (str) — El nombre del adaptador para reemplazar los pesos. El nombre de adaptador predeterminado es “default”.
  • init_lora_weights (str) — O bien "pissa" o "pissa_niter_[number of iters]", consulte LoraConfig. Para modelos grandes, la segunda opción es mucho más rápida.

Reemplaza los pesos de LoRA y los pesos base de un modelo cuantizado con bitsandbytes, usando PiSSA.

Solo se admite la cuantización de 4 bits de bitsandbytes.

PiSSA no puede aplicarse directamente a pesos cuantizados, por lo que normalmente requiere cargar el modelo de precisión completa, guardar el residual y cargar ese residual con cuantización. Esta función obtiene el mismo resultado partiendo del modelo cuantizado: los pesos no cuantizados se cargan al vuelo desde un archivo de modelo safetensors almacenado localmente, una capa a la vez, de modo que el modelo de precisión completa nunca tenga que mantenerse en memoria.

Cada peso base se reemplaza por el residual PiSSA re-cuantizado. Al igual que con cualquier inicialización de PiSSA, el adaptador por sí solo no es suficiente para restaurar el modelo, consulte el argumento path_initial_model_for_weight_conversion de save_pretrained().

Los pesos se cargan de forma perezosa, lo que requiere que el modelo esté almacenado en el formato safetensors.

Según el tamaño del modelo, la llamada a esta función puede tardar algún tiempo en completarse.

Eva

EvaConfig

clase peft.EvaConfig

< >

( rho: float = 2.0tau: float = 0.99use_label_mask: bool = Truelabel_mask_value: int = -100whiten: bool = Falseadjust_scaling_factors: bool = True )

Parámetros

  • rho (float) — Valor de Rho para la redistribución de EVA (>= 1.0). El rango máximo para una capa es lora_r * rho. El valor predeterminado es 2.0, lo que significa que el rango máximo permitido para una capa es 2r. Aumentar rho permitirá un mayor grado de redistribución de rangos entre capas. Algunos modelos preentrenados pueden ser más sensibles a la redistribución de rangos. Por lo tanto, puede ser beneficioso probar rho=1.0 (sin redistribución) si el rendimiento es inferior al esperado.
  • tau (float) — Umbral de similitud coseno para el detención temprana. Compara la similitud coseno de los vectores singulares derechos entre dos pasos consecutivos de SVD. Si la similitud coseno supera este umbral, la iteración de SVD se detiene. El valor predeterminado es 0.99.
  • use_label_mask (bool) — Usa una máscara de etiquetas para la inicialización de EVA. Esto significa que las posiciones donde labels=label_mask_value se ignoran para el cálculo de SVD. Se prefiere establecer use_label_mask=True en la mayoría de los casos y puede ser especialmente beneficioso para conversaciones de varios turnos. El valor predeterminado es True. Filtrar elementos basándose en la máscara de etiquetas a veces puede dar lugar a un tamaño de lote pequeño y, como resultado, a inestabilidades en el cálculo de SVD. Para los casos en los que se filtraría una gran proporción de elementos del lote, establezca use_label_mask=False.
  • label_mask_value (int) — Si use_label_mask=True, el valor que se busca para enmascarar los tokens ignorados. El valor predeterminado es -100.
  • whiten (bool) — Aplica el blanqueado a los vectores singulares. El valor predeterminado es False. Se ha demostrado que el blanqueado es beneficioso para EVA en el dominio de la visión.
  • adjust_scaling_factors (bool) — Ajusta los factores de escalado de LoRA después de la redistribución de rangos. Establecer esto en True significa que los factores de escalado se ajustan para que todos los gradientes de LoRA tengan la misma escala, independientemente de su rango. El valor predeterminado es True.

Esta es la clase de subconfiguración para almacenar la configuración de una inicialización basada en datos a través de EVA. EVA fue introducido en Explained Variance Adaptation.

initialize_lora_eva_weights

peft.initialize_lora_eva_weights

< >

( model: Moduledataloader: collections.abc.Iterable | None = Noneeva_state_dict: dict | None = Noneforward_fn: collections.abc.Callable | None = <function forward_fn_dict at 0x7eff9b83b270>prepare_model_inputs_fn: collections.abc.Callable | None = <function prepare_model_inputs_fn_language_modeling at 0x7eff9b83b060>prepare_layer_inputs_fn: collections.abc.Callable | dict[str, collections.abc.Callable] | None = <function prepare_layer_inputs_fn_language_modeling at 0x7eff9b83b1c0>adapter_name: str = 'default'gather_distributed_inputs: bool = Trueshow_progress_bar: bool = True ) → model (torch.nn.Module)

Parámetros

  • model (PeftModel) — El modelo peft para el que se debe calcular la SVD.
  • dataloader (Optional[Iterable]) — El dataloader a utilizar para la pasada hacia adelante. Si es None, se debe proporcionar eva_state_dict.
  • eva_state_dict (Optional[dict]) — El state_dict que se cargará en el modelo. Si es None, se debe proporcionar un dataloader y el state_dict se calculará usando get_eva_state_dict.
  • forward_fn (Callable) — La función de forward a utilizar para el paso de forward. Toma dos argumentos: model y inputs. El comportamiento predeterminado es return model(**inputs)
  • prepare_model_inputs_fn (Optional[Callable]) — Esta función recibe las entradas del modelo y el peft_config y pasa la salida a prepare_layer_inputs_fn. Puede usarse para modificar la entrada del cálculo SVD en función de las entradas originales del modelo. Por ejemplo, en el modelado de lenguaje, la máscara de atención se utiliza para determinar qué índices corresponden a tokens de relleno y no deben usarse para SVD. Cualquier función definida aquí espera dos argumentos: model_input y peft_config. peft.tuners.lora.eva.prepare_model_inputs_fn_language_modeling se utiliza de forma predeterminada.
  • prepare_layer_inputs_fn (Union[Callable, Dict[str, Callable], None]) — Esta función recibe las entradas de la capa, las entradas del modelo (posiblemente modificadas por prepare_model_inputs_fn) y el nombre de la capa, y devuelve las entradas que deben usarse para SVD para esa capa en particular. Cualquier función personalizada definida aquí espera tres argumentos: layer_input, model_input y layer_name, y debe devolver un tensor 2d. La lógica predeterminada se encuentra en peft.tuners.lora.eva.prepare_layer_inputs_fn_language_modeling y funciona para modelado de lenguaje. En este caso, model_inputs es la máscara utilizada para determinar qué índices deben usarse para SVD (creada por prepare_model_inputs_fn_language_modeling).
  • adapter_name (str) — El nombre del adaptador para el que se inicializarán los pesos.
  • gather_distributed_inputs (bool) — Si se deben recopilar las entradas de la capa de todos los ranks. El valor predeterminado es True, lo que significa que, en un entorno distribuido, las entradas de la capa se recopilarán de todos los ranks para el cálculo de SVD. En entornos no distribuidos, este argumento se ignora. Establezca False si está utilizando un dataloader no distribuido en un entorno distribuido.
  • show_progress_bar (bool) — Si se muestra una barra de progreso. El valor predeterminado es True.

Devuelve

model (torch.nn.Module)

El modelo con los pesos de LoRA inicializados.

Inicialice los pesos de las capas de LoRA utilizando el método EVA.

Esta función inicializa los pesos de las capas de LoRA utilizando el método EVA. Calcula la SVD para cada capa de adaptador y actualiza los pesos en consecuencia.

get_eva_state_dict

peft.get_eva_state_dict

< >

( model: Moduledataloader: Iterablepeft_config: peft.tuners.lora.config.LoraConfig | None = Noneforward_fn: collections.abc.Callable | None = <function forward_fn_dict at 0x7eff9b83b270>prepare_model_inputs_fn: collections.abc.Callable | None = <function prepare_model_inputs_fn_language_modeling at 0x7eff9b83b060>prepare_layer_inputs_fn: collections.abc.Callable | dict[str, collections.abc.Callable] | None = <function prepare_layer_inputs_fn_language_modeling at 0x7eff9b83b1c0>adapter_name: str = 'default'gather_distributed_inputs: bool = Trueshow_progress_bar: bool = True ) → eva_state_dict (dict)

Parámetros

  • model (torch.nn.Module) — El modelo para el que se debe calcular la SVD. No es necesario que sea un PeftModel.
  • dataloader (Iterable) — El dataloader que se utilizará para la pasada hacia adelante.
  • peft_config (Optional[LoraConfig]) — La configuración de las capas LoRA. Solo es necesaria si model no es un PeftModel.
  • forward_fn (Callable) — La función de forward a utilizar para el paso de forward. Toma dos argumentos: model y inputs. El comportamiento predeterminado es return model(**inputs)
  • prepare_model_inputs_fn (Optional[Callable]) — Esta función recibe las entradas del modelo y el peft_config y pasa la salida a prepare_layer_inputs_fn. Puede usarse para modificar la entrada del cálculo SVD en función de las entradas originales del modelo. Por ejemplo, en el modelado de lenguaje, la máscara de atención se utiliza para determinar qué índices corresponden a tokens de relleno y no deben usarse para SVD. Cualquier función definida aquí espera dos argumentos: model_input y peft_config. peft.tuners.lora.eva.prepare_model_inputs_fn_language_modeling se utiliza de forma predeterminada.
  • prepare_layer_inputs_fn (Union[Callable, Dict[str, Callable], None]) — Esta función recibe las entradas de la capa, las entradas del modelo (posiblemente modificadas por prepare_model_inputs_fn) y el nombre de la capa, y devuelve las entradas que deben usarse para SVD para esa capa en particular. Cualquier función personalizada definida aquí espera tres argumentos: layer_input, model_input y layer_name, y debe devolver un tensor 2d. La lógica predeterminada se encuentra en peft.tuners.lora.eva.prepare_layer_inputs_fn_language_modeling y funciona para modelado de lenguaje. En este caso, model_inputs es la máscara utilizada para determinar qué índices deben usarse para SVD (creada por prepare_model_inputs_fn_language_modeling).
  • adapter_name (str) — El nombre del adaptador para el que se calculará la SVD.
  • gather_distributed_inputs (bool) — Si se deben recopilar las entradas de la capa de todos los ranks. El valor predeterminado es True, lo que significa que, en un entorno distribuido, las entradas de la capa se recopilarán de todos los ranks para el cálculo de SVD. En entornos no distribuidos, este argumento se ignora. Establezca False si está utilizando un dataloader no distribuido en un entorno distribuido.
  • show_progress_bar (bool) — Si se muestra una barra de progreso. El valor predeterminado es True.

Devuelve

eva_state_dict (dict)

El diccionario de estado que contiene los componentes SVD para cada capa.

Calcule la SVD para cada capa del modelo.

Esta función calcula la Descomposición en Valores Singulares (SVD) para cada capa del modelo. Utiliza el método de PCA incremental para calcular los componentes de la SVD. La función también verifica la convergencia de los componentes calculados mediante la similitud coseno. La distribución de rangos para cada capa se determina en función de la proporción de varianza explicada.

LoraGAConfig

clase peft.LoraGAConfig

< >

( direction: Literal['ArBr', 'A2rBr', 'ArB2r', 'random'] = 'ArB2r'scale: Literal['stable', 'weight_svd', 'gd_scale', 'unit'] = 'stable'stable_gamma: int = 16 )

Parámetros

  • direction (Literal["ArBr", "A2rBr", "ArB2r", "random"]) — Estrategia para distribuir los componentes SVD del gradiente en las matrices lora_A y lora_B.
    • “ArBr”: Índices alternos (A toma los impares, B toma los pares)
    • “A2rBr”: A toma los índices [r:2r], B toma los índices [:r]
    • “ArB2r”: A toma los índices [:r], B toma los índices [r:2r] (recomendado)
    • “random”: Selección aleatoria de índices Valor predeterminado: “ArB2r”
  • scale (Literal["stable", "weight_svd", "gd_scale", "unit"]) — Estrategia de escalado para la inicialización del adaptador.
    • “stable”: Escalado estable con parámetro gamma
    • “weight_svd”: Escala basada en los valores singulares de la matriz de pesos
    • “gd_scale”: Escalado basado en descenso de gradiente
    • “unit”: Sin escalado adicional Valor predeterminado: “stable”
  • stable_gamma (int) — Parámetro gamma para el método de escalado estable. Valor predeterminado: 16

Esta es la clase de subconfiguración para almacenar la configuración de la inicialización de LoRA-GA.

LoRA-GA (Low-Rank Adaptation with Gradient Approximation) utiliza información de gradientes durante la inicialización para lograr una convergencia más rápida (aceleración de 2 a 4 veces) alineando los pesos iniciales del adaptador con la dirección de los gradientes de la afinación completa.

Referencia: https://arxiv.org/abs/2407.05000

Utilidades

peft.tuners.lora.loraga.estimate_gradients

< >

( model: Modulelora_config: LoraConfigtrain_step: Callable )

Estimar los gradientes para la inicialización de LoRA-GA.

Esta función habilita el cálculo de gradientos SOLO en los pesos del módulo objetivo y ejecuta el callback train_step. Esto es más eficiente en memoria que habilitar los gradientos de forma global.

peft.preprocess_loraga

< >

( model: Modulelora_config: LoraConfigtrain_step: Callablecache_file: str | None = None )

Parámetros

  • model (nn.Module) — Modelo a preprocesar.
  • lora_config (LoraConfig) — Configuración de Lora del modelo. lora_config.lora_ga_config debe estar configurado.
  • train_step (Callable[[], None]) — Callback para ejecutar la estimación de gradientes. Normalmente, debe ejecutar las pasadas hacia adelante y hacia atrás del modelo en este callback. Los gradientes se acumularán en todas las llamadas dentro de este callback.
  • cache_file (Optional[str]) — Ruta opcional del archivo de caché para guardar/cargar gradientes. Si se proporciona y el archivo existe, los gradientes se cargarán desde la caché. De lo contrario, los gradientes se estimarán y se guardarán en esta ruta.

Construya los campos LoRA-GA necesarios para un modelo estimando los gradientes.

Para cada capa lineal, los gradientes se estimarán ejecutando el callback train_step proporcionado. A continuación, estos gradientes se adjuntan a los módulos y se utilizan durante la inicialización.

Al completarse, se establecen los siguientes campos para cada módulo objetivo: _peft_loraga_grad (torch.Tensor): Gradiente acumulado para la matriz de pesos.

Reducción de la dimensión del intruso

peft.tuners.lora.intruders.reduce_intruder_dimension

< >

( peft_modelold_adapter_name = 'default'new_adapter_name = 'intruder_reduced'top_k = 10threshold_epsilon = 0.5mitigation_lambda = 0.75logging_sink = <built-in function print>use_lowrank = Falseniter = None )

Parámetros

  • peft_model — El modelo PEFT con un adaptador LoRA cargado con el nombre proporcionado en old_adapter_name. Actualmente, los modelos mixtos no son compatibles.
  • top_k (predeterminado — 10) Considera las dimensiones top-k para la detección de intrusos. A mayor valor, más dimensiones se considerarán para el análisis de detección de intrusos (y más falsos positivos puede haber). Opera sobre la similitud coseno entre los pesos base y los pesos del adaptador, ordenados aproximadamente por la influencia de la dimensión (determinada por la descomposición en valores singulares), por lo que un top-k de 10 examinará las 10 dimensiones más «importantes».
  • threshold_epsilon (predeterminado — 0.5) Valor umbral para considerar una similitud coseno entre el peso base y el peso del adaptador como intruso. Según el artículo, las dimensiones intrusas muestran una similitud coseno absoluta cercana a cero con los vectores singulares preentrenados. Cuanto menor sea este valor, menos dimensiones intrusas potenciales se identificarán. Cuanto mayor sea el valor, más falsos positivos potenciales se considerarán como intrusos.
  • mitigation_lambda (predeterminado — 0.75) La porción relativa de las dimensiones del intruso que se resta del peso delta del adaptador. A mayor valor, más dimensiones del intruso se restan, pero se pierde más información. Consulte la Figura 8 del artículo para un análisis de compensación.
  • logging_sink (predeterminado — print) Función que imprime información sobre el proceso de mitigación. Establezca None si no desea ninguna salida.
  • use_lowrank (predeterminado — False) Para acelerar el proceso: usa un SVD de bajo rango aleatorizado para prefiltrar la detección de intrusos, ejecutando el SVD completo solo en las capas marcadas. Cuantas menos capas contengan intrusos, mayor será la ganancia. Está muy sesgado hacia falsos positivos. (en pruebas: hasta 3 veces más rápido con pocos intrusos, punto de equilibrio alrededor del 73 % de las capas, hasta ~20 % más lento cuando cada capa tiene uno).
  • niter (predeterminado — 320) Solo se utiliza cuando use_lowrank=True para ajustar la tasa de detección. Un valor más alto es más preciso (menos falsos positivos) pero más lento por capa. Un valor demasiado bajo genera demasiadas detecciones erróneas.

Mitigación de la dimensión del intruso basada en https://huggingface.co/papers/2410.21228 (“LoRA vs Full Fine-tuning: An Illusion of Equivalence”).

Este método puede recuperar conocimientos previos (es decir, mitigar el olvido) mediante el postprocesamiento de adaptadores de bajo rango ya entrenados. Esto conlleva un coste en la precisión de la tarea: el ajuste del valor de migration_lambda permite equilibrar estos dos factores.

Una vez completada la mitigación, habrá un nuevo adaptador con el nombre establecido en new_adapter_name, que también se configurará como el adaptador activo actualmente. Por lo tanto, la inferencia en el modelo mitigado utilizará el adaptador modificado. Para volver al adaptador original, puede usar peft_model.set_adapter(<old_adapter_name>).

Actualmente solo se admite LoRA, ya que no está claro si este método se generaliza a otros métodos de pesos delta.

Update on GitHub