LoRA

LoRAは最も人気のあるPEFT手法の一つであり、PEFTを始めたばかりの方にとっての良い出発点です。当初は大型言語モデル向けに開発されましたが、その効率性と効果の高さから、拡散モデルの学習手法としても非常に人気があります。

低ランク適応（LoRA）は、大きな行列を2つの小さな低ランク行列に分解するPEFT手法です。これにより、ファインチューニングが必要なパラメータ数が大幅に削減されます。

論文の抄録は以下の通りです:

自然言語処理における重要なパラダイムは、汎用ドメインデータを用いた大規模事前学習と、特定のタスクやドメインへの適応です。より大きなモデルを事前学習するにつれて、モデルの全パラメータを再学習するフルファインチューニングは、実行可能性が低くなります。GPT-3 175Bを例にとると、175Bパラメータを持つファインチューニング済みモデルの独立したインスタンスをデプロイすることは、コスト的に現実的ではありません。そこで、我々はLow-Rank Adaptation（LoRA）を提案します。LoRAは、事前学習済みモデルの重みを凍結し、Transformerアーキテクチャの各層に学習可能なランク分解行列を注入することで、下流タスクにおける学習可能なパラメータ数を大幅に削減します。Adamを用いたGPT-3 175Bのファインチューニングと比較して、LoRAは学習可能なパラメータ数を10,000分の1、GPUメモリ要件を3分の1に削減できます。LoRAは、学習可能なパラメータ数が少なく、学習スループットが高く、アダプタとは異なり追加の推論レイテンシがないにもかかわらず、RoBERTa、DeBERTa、GPT-2、GPT-3においてモデル品質の面でファインチューニングと同等以上の性能を発揮します。また、言語モデル適応におけるランク不足に関する実証的な調査を行い、LoRAの有効性について考察しました。PyTorchモデルへのLoRA統合を容易にするパッケージを公開し、RoBERTa、DeBERTa、GPT-2の実装とモデルチェックポイントをこのURLで提供しています。

LoRA は重みの更新 $\Delta W$ を、2 つのより小さい行列（ 更新行列) ）で低ランク分解を用いて表します。これらの新しい行列は、全体のパラメータ数を低く保ちながら新しいデータに適応するように学習できます。元の重み行列は凍結されたまま、これ以上の更新を受け取りません。最終的な結果を生成するには、元の重みと追加の適応済み重みを結合します。また、推論のレイテンシーを排除するために、アダプタの重みをベースモデルにマージすることもできます。

このアプローチには、いくつかの利点があります：

• LoRAは、学習可能なパラメータの数を大幅に削減することで、ファインチューニングをより効率的にします。
• 元の事前学習済み重みは凍結されたまま保持されるため、それらを基盤として、さまざまな下流タスクに対応する軽量かつポータブルな複数のLoRAモデルを構築できます。
• LoRAは他のパラメータ効率手法と直交しており、それらの多くと組み合わせることができます。
• LoRAを使用してファインチューニングされたモデルの性能は、完全にファインチューニングされたモデルの性能と同等です。

原理的には、LoRAはニューラルネットワーク内の重み行列の任意の部分集合に適用でき、学習可能なパラメータ数を削減できます。ただし、簡便さとさらなるパラメータ効率を考慮して、LoRAは通常、Transformerモデルのattentionブロックにのみ適用されます。他のレイヤーも対象にすることを検討する価値があるかもしれません。LoRAモデルにおける学習可能なパラメータの最終的な数は、更新行列のサイズに依存します。このサイズは主に、ランクrと元の重み行列の形状によって決定されます。

低ランク行列の初期化は、タスク認識（CorDA、EVA、Astra）、収束の高速化（PiSSA）、量子化の緩和（LoftQ）など、さまざまなユースケースを念頭に置いて行うことができます。ここではほんの一例を挙げました。異なる初期化方法については、以下を参照してください。デフォルトの初期化では、LoRAが何もしない（no-op）状態となり、既存のモデルに大きく干渉することなく、徐々に新しい動作を学習するように設計されています。

使用方法

低ランク更新行列のサイズは、rank（またはr）によって決定されます。ランクが高いほど、モデルには学習させるためのパラメータが増えますが、同時にモデルの学習能力も高まります。次の例では、アテンションブロックのquery行列とvalue行列を対象とします。設定する他の重要なパラメータとしては、lora_alpha（スケーリング係数）、bias（none、all、またはLoRAバイアスパラメータのみを学習するか）、そしてmodules_to_save（LoRA層以外で学習および保存するモジュール）があります。これらのパラメータ（およびそれ以外）はすべて、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()

ベンチマーク概要

初期化

LoRA重みの初期化は、LoraConfigのパラメータinit_lora_weightsによって制御されます。デフォルトでは、PEFTは重みAにKaiming-uniform、重みBにゼロでLoRA重みを初期化し、恒等変換（参照実装と同じ）になります。

transformers.Conv1Dレイヤー（GPT-2の投影など）では、重みがnn.Linearのレイアウトではなく(in_features, out_features)として保存されているため、fan_in_fan_out=Trueを使用してください。サポートされている重みベースのイニシャライザーは、分解にはLinearレイアウトを使用し、ベースの重みを更新する際に保存されたレイアウトを復元します。LoRA-GAの"stable"スケーリングも、保存レイアウトに関係なく出力次元を使用します。

init_lora_weights="gaussian" を渡すことも可能です。名前の通り、重み A をガウス分布で、重み B をゼロで初期化します（Diffusers が LoRA の重みを初期化する方式です）。

from peft import LoraConfig

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

デバッグやテストに有用なinit_lora_weights=Falseというオプションも用意されています。このオプションを使用するのは、この場合のみとすべきです。このオプションを選択すると、LoRAの重みは、恒等変換を引き起こさないように初期化されます。

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

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

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

トレーニング

このセクションでは、モデルに低ランクアダプタを適用してデータを供給するだけでなく、より複雑なトレーニングシナリオをどのように処理するかを示します。

QLoRAスタイルの学習

PEFTのデフォルトのLoRA設定では、各アテンションブロックのクエリ層とバリュー層に学習可能な重みが追加されます。しかし、Transformerモデルのすべての線形層に学習可能な重みを追加するQLoRAは、完全なファインチューニングモデルと同等のパフォーマンスを提供できます。QLoRAと同様にすべての線形層にLoRAを適用するには、target_modules="all-linear"を設定します（アーキテクチャによって異なる可能性がある個別のモジュール名を指定するよりも簡単です）。

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

PEFTアダプターに量子化を適用する方法の詳細については、量子化ガイドを参照してください。

LoRAによるメモリ効率の良いレイヤー複製

モデルの性能を向上させるためのアプローチとして、与えられたサイズの事前学習済みモデルから、モデル内のレイヤーを複製してモデルを拡張し、より大きなモデルを構築する方法があります。例えば、SOLAR論文で説明されているように、7Bモデルを10Bモデルに拡張します。PEFT LoRAは、レイヤーの複製後にそのレイヤーに接続されたLoRAアダプターを用いたさらなるファインチューニングをサポートする、メモリ効率の高い方法でこの種の拡張をサポートしています。複製されたレイヤーは基盤となる重みを共有するため、追加のメモリを消費せず、必要な追加メモリはアダプターの重みのメモリのみです。この機能を使用するには、layer_replication引数を含む設定を作成します。

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

元のモデルが5層[0, 1, 2 ,3, 4]であったと仮定すると、この操作により[0, 1, 2, 3, 2, 3, 4]のように配置された7層のモデルが作成されます。これはmergekitのパススルーマージ規約に従っており、開始位置を含む・終了位置を含まないタプルで指定された層のシーケンスを積み重ねて最終モデルを構築します。最終モデルの各層には、それぞれ固有のLoRAアダプターセットが割り当てられます。

Fewshot-Metamath-OrcaVicuna-Mistral-10B は、この手法を用いて Mistral-7B を 10B に拡張して学習させたモデルの例です。adapter_config.json には、この手法をファインチューニングに適用する LoRA アダプターの設定のサンプルが示されています。

ランクとアルファ（スケーリング）の細かい制御

デフォルトでは、LoraConfig で指定された内容に基づき、LoRA の対象となるすべてのレイヤーに同じランク r と同じ lora_alpha（LoRA のスケーリングを決定する）が適用されます。ただし、レイヤーごとに異なる値を指定したい場合があります。これは、LoraConfig に rank_pattern と alpha_pattern 引数を渡すことで可能です。これらの引数は、キーがレイヤー名、値がランク/アルファ値である辞書である必要があります。キーには正規表現（regex）を指定できます。rank_pattern と alpha_pattern に明示的に記載されていないすべての LoRA レイヤーには、デフォルトの r と lora_alpha の値が適用されます。

例として、次のような構造を持つモデルがあると仮定します。

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42} は、すべての foo レイヤーに一致します。foobar も barfoo も一致しません。
• rank_pattern={"^foo": 42} はモデルの foo レイヤーのみを一致させ、module.foo や module.module.foo には一致しません。これは、正規表現において ^ が「文字列の先頭」を意味するため、foo のみが "foo" で始まる一方、他のレイヤー名にはプレフィックスが付いているためです。
• rank_pattern={"^module.foo": 42} は、同じ理由により、module.foo にはマッチしますが、module.module.foo にはマッチしません。
• rank_pattern={"module.foo": 42} は module.foo と module.module.foo の両方にマッチしますが、foo にはマッチしません。
• rank_pattern={"^foo": 42, "^module.module.foo": 55} は、それぞれ foo と module.module.foo にマッチしますが、module.foo にはマッチしません。
• PEFTが自動的に追加するため、マッチの終わりを示すために$を指定する必要はありません。

同じロジックがalpha_patternにも適用されます。迷ったら、正規表現で凝ったことをせず、異なるランク/アルファを持つ各モジュールの完全な名前を^プレフィックス付きで渡すだけで問題ありません。

実行可能なターゲットモジュールを自動的に検出する

peft.helpers.KappaTuneSelector は、KappaTune論文で提案された条件数に基づくターゲット選択戦略を実装しています。すべてのnn.Linearモジュールをスキャンし、MoEエキスパートの重みが融合された3次元のnn.Parameterテンソルとして保存されているモデル（例: Llama-4、Qwen3-MoE）ではそれらのパラメータも対象とし、それぞれについて行列の条件数 κ = σ_max / σ_min を計算します。その後、最も各向同性なレイヤー（κが最小のレイヤー）を選択します。これらの各向同性レイヤーは、高エントロピーの性質により新しい情報をより容易に吸収できるため、ファインチューニングの理想的な候補となります。これにより、特化された各向異性レイヤーはそのまま維持され、継続的学習におけるカタストロフィック・フォーゲッティングを軽減できます。

LoraConfigの最適なtarget_modulesを取得するワンライナーとして、peft.helpers.find_kappa_target_modules()を使用します:

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)

完全な例はこちらを参照してください。

nn.Parameterを直接ターゲットにする

一般的には、モジュール（例: nn.Linear）を対象にするために target_modules を使用します。ただし、状況によってはこれができない場合があります。例えば、HF Transformers の多くの mixture of expert (MoE) レイヤーでは、nn.Linear の代わりに nn.Parameter が使用されています。PEFT は通常、LoRA に対して forward メソッドを上書きしますが、nn.Parameter にはこれが存在しません。したがって、そのパラメータに LoRA を適用するには、target_parameters で対象に指定する必要があります。例えば、Llama4 の場合は、以下を渡すことができます: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj]。

エキスパートパラメータを対象とする場合、PEFTは実行時にかなりのオーバーヘッドを追加する可能性があります。その理由は、必要とされるエキスパートが少量であっても、PEFTは常に各エキスパートのLoRA寄与を実体化するためです。学習中は、シーケンスの経過に伴い、通常、エキスパートの大部分が少なくとも一度は活性化されるため、この影響は小さくなります。しかし、推論時には通常KVキャッシュが使用され、最後のトークンのみ計算すればよいため、活性化されるエキスパートは少量にとどまります。したがって、MoE層にLoRAを使用すると、推論時に大幅なスローダウンが発生する可能性があります。そのため、重みをマージすること（model.merge_adapter()またはmodel = model.merge_and_unload()）を推奨します。これにより、PEFTのオーバーヘッドを除去できます。

この問題に関するより詳細な調査は、MoE最適化に関するプルリクエストで確認できます。

注意事項

• 現在、この引数は2次元または3次元のnn.Parameterを対象とできます。3次元のパラメータの場合、0次元目がエキスパート次元であると仮定されます。
• target_parameters を使用する複数の LoRA アダプター（model.add_adapter または model.load_adapter を介して追加されたもの）はサポートされていますが、すべてが同じパラメータセットを対象とする必要があります。

MoEエキスパートパラメータとvLLM

Transformers の一部の MoE モデルでは、エキスパートの重みが nn.Linear モジュールではなく、nn.Parameter テンソル（多くの場合は 3 次元）として保存されています。 これらのエキスパートに LoRA を適用するには、target_parameters を使用し、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,
    },
)

これにより、LoRAのパラメータ総量はdense層とほぼ同じ予算に保たれます（Schulman et. al. の LoRA Without Regret を参照）。エキスパート以外のモジュールには、デフォルトのランク r が使用されます。

ファインチューニング済みのモデルによる高速推論は、例えば、v0.11.2 以降で融合された MoE エキスパート層をサポートする vLLM を使用することで可能です。

LoRAとトークンを効率的に同時に学習

PEFT LoRA アダプターは、trainable_token_indices パラメーターを使用して新しいトークンの追加をサポートしています。これにより、特定の層のファインチューニングと並行して、他のトークンのチューニングを行うことができます。指定されたトークンのみが学習され、他のすべてのトークンは変更されません。埋め込み行列全体を学習させる場合と異なり、既存のトークン埋め込みから得られた学習済みコンテキストを失うことなく、メモリを節約できます。この手法は、内部で 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, ...]}, ...)

以下のスニペットでは、モデルに新しいトークンを追加し、モデルの他のレイヤーと並行して学習する方法を示しています。

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
[...]

トークン重みは、LoRA 重みとともにアダプタの state dict の一部として保存されます。フルファインチューニングや埋め込み行列の保存を行う場合、はるかに大きなファイルが保存されることになります。

VRAMをどの程度節約できるかを示すために、上記の例について、埋め込み行列を完全に学習させる場合（modules_to_save=["embed_tokens"]）、埋め込み行列にLoRAを使用する場合（target_modules=[..., "embed_tokens"]、ランク32）、および学習可能なトークンを使用する場合（trainable_token_indices=[...]、6トークン）の簡易的な比較を行いました。

重みの共有

多くの因果言語モデルは、2つ以上の重みが同じ基礎パラメータを共有する重みタイイングを使用しています。最も一般的なケースでは、入力埋め込み重み（embed_tokens）と出力投影重み（lm_head）が同じテンソルを共有します。これは、パラメータ数を削減しつつ、通常はモデルの品質を維持できるためです。

PEFTがこれらのタイドウェイトをファインチューニングの対象とした際にどのように扱うかは、必ずしも自明ではありません。LoRAの場合、LoraConfigのensure_weight_tyingが、PEFTがこれらのレイヤーに対してアダプター側の更新を明示的にタイド状態に保つべきかを制御します。実際には、これはmodules_to_save、target_modules、およびtrainable_token_indicesに影響を与える可能性があります。なお、このロジックはレイヤーの命名（"embed_tokens"、"lm_head"）に関して慣習に部分的に依存しており、これらの慣習が使用されない場合、正常な動作は保証されません。

以下の表は、期待される動作を要約しています。

modules_to_save

target_modules

trainable_token_indices

学習可能なトークンについては、LM headとembeddingが結合されている場合でも、ユーザーとしてこれらに対して異なるトークンをファインチューニングしたい場合があります。そのため、以下の例の表では、同じトークンのファインチューニングと異なるトークンのファインチューニングを区別しています。

ユーザーにとって、これは次のことを意味します:

• 一般的に、タイドされている重みをファインチューニングしつつ、そのタイド状態を維持したい場合は、ensure_weight_tying=True を渡してください。
• ベースモデルの重みが未結合の場合、ensure_weight_tying=Trueでは結合を強制できず、警告のみが表示されます。
• trainable_token_indices については、ensure_weight_tying=True の場合、結合されたレイヤーは同じトークンインデックスを使用する必要があります。

オプティマイザー

LoRAの学習には、オプションとして特殊なオプティマイザーを含めることができます。現在、PEFTはLoRA-FA、LoRA+、およびRiemannian-preconditioned LoRAをサポートしています。

LoRA-FA Optimizer

LoRA-FA に記載されているように、LoRA-FA を使用することで、LoRA トレーニングはより効果的かつ効率的になります。LoRA-FA は、行列 A を固定し、行列 B のみチューニングすることで、アクティベーションのメモリ消費量を削減します。トレーニング中は、B の勾配が最適化され、フルパラメータファインチューニングの勾配を近似するようにします。さらに、LoRA-FA のメモリ消費量はランクに敏感ではありません（$A$ のアクティベーションを消去するため）、そのため、メモリ消費量を増やすことなく lora rank を拡大してパフォーマンスを向上させることができます。

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+で最適化されたLoRA

LoRAの学習は、LoRA+を使用して最適化できます。これはアダプター行列AとBに異なる学習率を使用し、ファインチューニングの速度を最大2倍、パフォーマンスを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),
)

Riemannian-preconditioned LoRA

LoRA の学習は、 Riemannian Preconditioned LoRA. すべてのオプティマイザーステップで、LoRA 行列 $A$ および $B$ の勾配は、 $r \times r$ のプリコンディショナーで乗算されます。このプリコンディショナーは、低ランク行列多様体上で、ユークリッド勾配をリーマン（スケーリングされた勾配）方向へ再スケーリングします。これにより更新の条件付けが改善され、収束が向上する可能性があります。プリコンディショナーは $r \times r$ であるため、LoRA ランクに対するメモリおよび実行時間のオーバーヘッドは小さくなります。 create_riemannian_optimizer は、任意のベースオプティマイザークラス（例： torch.optim.AdamW または torch.optim.SGD): ）をラップします。LoRA 以外のパラメータはベースオプティマイザによって変更なしで更新され、 nn.Linear-形状の LoRA レイヤー（lora_A / lora_B) にプリコンディショニングが適用されます。

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 は、 $r \times r$ 行列の対角成分に逆行列を計算する前に加えられる減衰項であり、LoRA 係数が（ほぼ）ランク不足の場合にプリコンディショナーを安定化させます。

Post-Training

このセクションでは、学習済みアダプターに対する潜在的な後処理手法を示します。

LoRAの重みをベースモデルにマージする

While LoRA is significantly smaller and faster to train, you may encounter latency issues during inference due to separately loading the base model and the LoRA adapter. To eliminate latency, use the merge_and_unload() function to merge the adapter weights with the base model. This allows you to use the newly merged model as a standalone model. The merge_and_unload() function doesn’t keep the adapter weights in memory.

以下は、LoRAアダプターのマージの直観を説明する図です：

以下のスニペットでは、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()

返されたモデルを变数に代入して使用することが重要です。merge_and_unload() はインプレース操作ではありません。後でアダプタをアンマージしたり、削除して別のものをロードできるように、重みのコピーを保持する必要がある場合は、代わりに merge_adapter() 関数を使用してください。これで、unmerge_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)
model.merge_adapter()

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

量子化モデルでは、アンマージングは厳密ではありません。マージングはベースの重みを再量子化するため、マージングとアンマージングのサイクルを繰り返すと丸め誤差が蓄積する可能性があります。量子化された重みへのアダプタのマージングを参照してください。

複数のアダプターがアクティブな状態で、そのうち一部のみがマージされている場合、マージされていないアダプターは静かに適用されません。この動作はPEFT v1.0で変更されます。アクティブなアダプターの一部のみをマージするを参照してください。

weights パラメータでユーザーが指定した重み付けスキームに基づいて、複数の LoRA を新しいアダプターにマージするには、add_weighted_adapter() 関数が便利です。以下にエンドツーエンドの例を示します。

まずベースモデルを読み込みます:

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

次に、最初のアダプターを読み込みます:

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

次に、別のアダプターを読み込み、最初のものとマージします:

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)

combination_typeにはいくつかサポートされているメソッドがあります。詳細については、ドキュメントを参照してください。なお、データ型としてtorch.float16またはtorch.bfloat16を使用する場合、combination_typeに“svd”を指定することはサポートされていません。

次に、推論を実行します:

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)

侵入次元削減によるベースモデルの性能回復

論文 LoRA vs Full Fine-tuning: An Illusion of Equivalence は、LoRA 学習が、すでに学習された重みとはほとんど共通点のない追加の次元を重みに導入し、学習済みの情報の忘却を引き起こすことを主張しています。PEFT は、peft.tuners.lora.intruders.reduce_intruder_dimension() で提案された緩和策を実装しています。

この緩和策では、読み込まれたLoRAを持つPEFTモデルを取得し、既存のアダプターと並んで読み込まれる新しい修正済みアダプターを作成します。この新しいアダプターがアクティブなアダプターとなります。

使用例:

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

ミティゲーションの効果を調整するために使用できるハイパーパラメータはいくつか存在しますが、論文の図8に示されているように、アダプタが学習したタスクの精度と、ベースモデルの知識の忘却の間には常にトレードオフの関係があります。ミティゲーションは、過去の知識の忘却への影響を軽減するためにアダプタから情報を削除しますが、その結果、アダプタが学習したタスクに関する一部の情報も失われることになります。

デフォルト値は2つの要素のバランスを良好に保つように設定されていますが、お使いのアダプター、モデル、データに対してデフォルト値が最適であることは保証されていません。そのため、その影響を測定するためのベンチマークを用意しておくことが賢明です。

アダプターを読み込む

アダプターは、load_adapter() を使用して事前学習済みモデルに読み込むことができます。これは、重みがマージされていない異なるアダプターを試す際に便利です。アクティブなアダプターの重みは、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")

ベースモデルを返すには、すべてのLoRAモジュールをアンロードするためにunload()を使用するか、アダプタを完全に削除するためにdelete_adapter()を使用できます。unload()はインプレース操作ではないため、返されたモデルを变数に代入して使用することを忘れないでください。

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

テンソル並列

LoRAは、Transformersが提供するテンソル並列性（TP）をサポートしています。ベースモデルがtp_plan付きで読み込まれると、PEFTは各ターゲットモジュールのTP設定を自動的に検出し、LoRAアダプター重みに適切なフックを追加することで、テンソル並列計算に正しく参加できるようにします。

LoRA での Tensor Parallelism のサポートには、transformers >= 5.4.0 が必要です。 DTensor ベースの Tensor Parallelism API には、peft >= 0.21.1 および transformers >= 5.17.0 が必要です。

使用法は標準的なLoRAワークフローと同一です。PEFTでラップする前に、ベースモデルをtp_plan付きで読み込むだけです。

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)

save_pretrained / from_pretrained を通じた保存と読み込みは、通常どおり動作します。PEFT は保存前に、シャーディングされたアダプター重みをフルテンソルに集約するため、チェックポイントは移植可能であり、学習時に使用したデバイス数に依存しません。

TP プランなしでテンソル並列性を適用する場合（例: PyTorch の parallelize_module を使用する場合）、PEFT は、重みのデバイスメッシュに "tp" という名前の次元がある場合、シャードされた nn.Linear の LoRA 重みをそのローカルシャードのサイズに設定し、それ以外の場合は（FSDP2 と同様に）レイヤー全体の形状に設定します。PEFT は、これらの LoRA 重みに TP フックを追加したり、保存時にそれらをガザリングしたりしません。TP メッシュの次元名が異なる場合は、PEFT モデルを作成する前に追加してください:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

推論

このセクションでは、LoRAを用いた推論時に実行できる処理、例えばアダプターのカップリング解除などを紹介します。

アクティベーション LoRA (aLoRA)

Activated LoRA (aLoRA) は、因果言語モデル向けの低ランクアダプターアーキテクチャであり、既存のベースモデルの KV キャッシュを再利用することで、より効率的な推論を実現します。このアプローチは、ほとんどのタスクや生成においてベースモデルに依存する推論パイプラインに最も適しています。ただし、チェーン内の特定のタスクを実行するために aLoRA アダプターを使用します。例えば、ベースモデルの生成出力を確認したり修正したりする場合です。このような設定では、推論時間が1桁以上高速化される可能性があります。aLoRA に関する詳細や多くの使用例については、aLoRA の 論文を参照してください。

この手法は、各入力内で呼び出しシーケンス（alora_invocation_tokens）の最後の出現箇所をスキャンします（これは1トークンだけの場合もあります）。呼び出しシーケンスの開始位置から始まるトークンから、アダプター重みが有効化されます。呼び出しシーケンス以降の入力も適応され、生成されるすべてのトークンに適応された重みが使用されます。それ以前のトークンの重みは適応されず、因果的言語モデルにおける因果的アテンションマスクにより、それらのトークンのキャッシュはベースモデルのキャッシュと互換性があります。使用法は標準的なLoRAと非常に似ています。主な違いは、アダプターを作成する際に呼び出しシーケンスを指定する必要がある点です：

from peft import LoraConfig

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

alora_invocation_tokens は整数トークン ID のリストです。所望の呼び出し文字列が与えられた場合、以下のように取得できます。

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

トークナイザーはベースモデルのトークナイザーです。検索文字列にSOS/EOSトークンが追加されて検索が失敗するのを防ぐために、add_special_tokens=Falseを使用してください。

注記

• aLoRAは、キャッシュの再利用に焦点を当てているため、task_type=CAUSAL_LMタスクのみサポートされています。
• 重みがより少ないトークンで適応されるため、aLoRAはLoRAよりも高いランク（r）を必要とすることがよくあります（常にではありません）。r=32は良い出発点となり得ます。
• aLoRAの重みは定義上、ベースモデルにマージできません。アダプタの重みはトークンの部分集合に選択的に適用されるためです。マージを試みるとエラーが発生します。
• Beam searchは現在サポートされていません。
• ベースモデルに存在しない新しいトークンをトークナイザーに追加することは、一般的には推奨されません。これにより、ベースモデルとアダプターモデルが重複するコンテキストで動作するという、両方のターゲットユースケースが複雑になる可能性があります。この問題を回避するには、アダプターを学習する前に、ベースモデルに学習可能なトークンを追加してください。

呼び出しシーケンスの選択とSFTの設計

alora_invocation_tokensシーケンスは自動的に追加されないため、手動で追加する必要があります。モデルの性能を最大化しつつキャッシュの再利用を損なわないよう、アダプター重みの有効化は、長い入力の後、かつアダプター固有のプロンプティングの開始時に行うことを推奨します。他のモデルと同様に、フォーマットは学習時とテスト時で一致させる必要があります。

ベースモデルにチャットテンプレートがあり、アダプターをトレーニングして所望の出力を生成することを目的とする、次の例を考慮してください。

• オプション 1: タスク固有のプロンプトがない場合、つまり入力がassistantプロンプト付きのチャット履歴である場合、呼び出し文字列には、チャットテンプレートのassistantプロンプト（例: <|start_of_role|>assistant<|end_of_role|>）が自然な選択です。モデルのプロンプトを確認するには、モデルのチャットテンプレートをご覧ください。
• オプション 2: アダプタに、そのアダプタが学習しているタスクを説明するタスク固有のプロンプトがあり、そのプロンプトが生成の直前にuserターンとして配置される場合、チャットテンプレートのuserプロンプト（例: <|start_of_role|>user<|end_of_role|>）が呼び出し文字列の自然な選択となります。

呼び出し文字列を決定した後、モデルのトークナイザーを取得し、alora_invocation_tokens を以下のように取得します。

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

推論セットアップの例は、alora finetuningにあります。

呼び出し文字列にカスタム文字列を使用する場合は、境界でのトークナイゼーションの問題を避けるため、文字列の先頭と末尾が特殊トークンであることを確認してください。

その理由を理解するために、トークナイザーにおいて ‘a’、‘b’、‘c’、および ‘ab’ がトークン（それぞれ番号 1、2、3、4）であると想像してください。alora_invocation_tokens = [2, 3] であると仮定します。次に、入力文字列が “abc” であるとします。“ab” がトークンであるため、これは [4,3] としてトークン化されます。したがって、文字列内に “bc” が含まれているにもかかわらず、alora_invocation_tokens は検出されません。しかし、呼び出し文字列の開始と終了が特殊トークンであれば、特殊トークンは他の文字と同一のトークンにトークン化されることはないため、この失敗ケースは決して発生しません。

生成におけるキャッシュの使用（および再利用）

aLoRAの主な目的は、ベースモデルとaLoRAアダプターモデル間でKVキャッシュを相互に利用可能にすることです。ベースモデルとアダプターモデルのKV値は互換性がなく、呼び出しシーケンスの前にこの相互利用を実現する必要があります。具体的には、あるモデルの生成時に保存されたキーと値を、その後の生成に再利用することで、コンテキストトークンに対するコストの高いプリフィル操作を回避できます。ベースモデルとaLoRAアダプター間でキャッシュを共有する際、主に2つのパターンがあります。

1. ベースモデルが何かを生成し、その後、aLoRAアダプターが呼び出されてフォローアップの生成を行います。例えば、ベースモデルが質問に回答し、ハルシネーション検出用に訓練されたaLoRAがベースモデルの応答を確認します。
2. aLoRA アダプターが何かを生成し、ベースモデルまたは別の aLoRA アダプターが、元の aLoRA と部分的にコンテキストが重複するフォローアップ生成を呼び出される場合です。例えば、ユーザーがクエリを提供し、aLoRA がクエリをより自己完結型に書き換えて RAG システムでの検索を改善します。その後、ドキュメントが検索されコンテキストに読み込まれ、aLoRA がこれらのドキュメントが質問に関連しているかを確認し、最後にベースモデルが回答を生成します。

上記の動作をデモストレーションするために、transformersのDynamicCacheを使用します。適応されたキャッシュの値とベースのキャッシュの値が混在しないよう注意してください。特に、コンテキストが部分的に重複している場合（パターン2）には、キャッシュを共有するために追加の手順が必要です。

パターン1: ベースモデルの後にaLoRAここでは、ベースモデルからの入力全体と生成結果が、呼び出しシーケンスとともにaLoRAアダプターに入力されます。

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!

パターン2: aLoRAによる生成の後に、ベースモデル（または別のaLoRA）による部分コンテキスト重複を伴う処理ここでは、ベースモデルを使用して共有コンテキストをプリフィルし、その後生成を行います。

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

同一バッチ内で異なるLoRAアダプターを使用して推論を行う

通常、PEFTでは各推論バッチが同じアダプタを使用する必要があります。これは時に煩わしくなる場合があります。異なるLoRAアダプタで使用するサンプルを含むバッチが存在する可能性があるためです。例えば、英語で良好に動作するベースモデルと、フランス語用とドイツ語用の2つのLoRAアダプタがある場合を想定します。通常、各バッチが1つの言語のサンプルのみを含むようにバッチを分割する必要があり、異なる言語を同じバッチに組み合わせることはできません。

幸いなことに、adapter_name 引数を使用することで、異なる LoRA アダプターを同じバッチに混在させることができます。以下では、その具体的な動作例を示します。まず、ベースモデル、英語、そしてフランス語とドイツ語の2つのアダプターを、次のように読み込みます。

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

次に、英語、フランス語、ドイツ語の3言語すべてを含むサンプルでテキストを生成します。最初の3つのサンプルは英語、次の3つはフランス語、最後の3つはドイツ語です。adapter_names引数を使用して、各サンプルに使用するアダプターを指定できます。ベースモデルが英語に使用されるため、これらのサンプルには特別な文字列"__base__"を使用します。次の3つのサンプルには、フランス語のLoRAファインチューニングのアダプター名、ここでは"adapter_fr"を指定します。最後の3つのサンプルには、ドイツ語のLoRAファインチューニングのアダプター名、ここでは"adapter_de"を指定します。これにより、ベースモデルと2つのアダプターを単一のバッチで使用できます。

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)

ここでは順序は重要ではなく、上記の例のようにバッチ内のサンプルをアダプターごとにグループ化する必要はありません。adapter_names引数がサンプルと正しく対応していることを確認するだけです。

さらに、modules_to_save 機能でも同じアプローチが機能します。この機能により、分類タスク用のカスタムヘッドなどの特定のニューラルネットワーク層を保存し、異なる LoRA アダプター間で再利用できます。

注意事項

この機能にはいくつかのデメリットがあります。具体的には以下の通りです。

• 推論でのみ動作し、トレーニングには対応していません。
• with model.disable_adapter() コンテキストによるアダプターの無効化は、adapter_names より優先されます。
• merge_adapter メソッドを使用して一部のアダプター重みがベース重みにマージされている場合、adapter_names を渡すことはできません。まず、model.unmerge_adapter() を呼び出してすべてのアダプターをアンマージしてください。なお、adapter_names 以外でも、アクティブなアダプターのうち一部のみをマージする場合は、同様の注意点 があります。
• 明白な理由により、merge_and_unload()を呼び出した後ではこれを使用できません。この場合、すべてのLoRAアダプターがベースの重みにマージされるためです。
• この機能は現在DoRAと互換性がありません。使用する場合は、LoraConfigでuse_dora=Falseを設定してください。
• modules_to_save 機能は、現在 Linear、Embedding、Conv2d および Conv1d 型のレイヤーのみサポートされています。
• 推論には、 adapter_names, 特にバッチ内の異なるアダプタの数が多い場合、想定されるオーバーヘッドがあります。これは、バッチサイズが実質的にアダプタごとのサンプル数に削減されるためです。ランタイムのパフォーマンスが最優先であれば、以下のことを試してください。
  • バッチサイズを大きくします。
  • 同じバッチに多数の異なるアダプターが含まれることを避け、均質なバッチを優先してください。これは、同じアダプターを持つサンプルをバッファリングし、少数の異なるアダプターでのみ推論を実行することで実現できます。
  • 多数の異なるアダプターでの動作に特化したLoRAX、punica、S-LoRAなどの代替実装をご覧ください。

LoRAアダプターの構成と再利用

Arrow

Arrowは、Polytroponと同様に与えられたタスクを解決するために複数の事前学習済みタスク固有のLoRAアダプターを組み合わせることを目的としたモジュール型ルーティングアルゴリズムですが、ファインチューニングは不要です。すべてのアダプターを単純にマージするのではなく、Arrowは勾配なしのトークン単位のMixture-of-Experts (MoE) ルーティング機構を導入します。推論時、まず各LoRAのSVD分解から上位の右特異ベクトルを抽出してプロトタイプを計算します。次に、各トークン表現をこれらのプロトタイプと比較し、コサイン類似度を用いてルーティング係数を取得します。トークンは上位k個の最も関連性の高いLoRAアダプターに割り当てられ、係数はsoftmaxで正規化された後、その出力が線形に結合されます。これにより、既存のLoRAモジュールを新しいタスクに効果的に再利用でき、より強力なゼロショット汎化が実現されます。

In PEFT, Arrow is enabled through [`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.

さらに、create_arrow_modelを呼び出した後でも、アダプターを追加または削除できます。例えば、新しいアダプターをファインチューニングしたり、不要なアダプターを破棄したりする場合です。アダプターが配置されたら、推論でArrowを使用するために"arrow_router"をアクティブにできます。なお、create_arrow_modelの後に新しいLoRAアダプターを追加してファインチューニングしたい場合は、create_arrow_modelでは"arrow_router"がデフォルトでアクティブ化されるため、新しいアダプターを明示的にアクティブに設定する必要があります。

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は、ルーティングの前にタスク固有のLoRAアダプターを精製することで、Arrowを拡張します。その核心となるアイデアは、否定による忘却の原理に基づき、LoRA空間にエンコードされた一般知識を減算することです。これにより、タスクアダプターはより分離され、タスクに関連するシグナルに集中するようになります。具体的には、GenKnowSubは一般（タスク固有でない）LoRAアダプターのセットから低次元の「一般」部分空間を推定し、Arrowのトークン単位のルーティングに先立って、各タスクアダプターのLoRA更新からこの成分を除去します。これにより、多くのタスクアダプターを組み合わせる際の合成性（compositionality）が向上し、干渉が軽減されるのが一般的です。

PEFTでは、ArrowConfigでuse_gks=Trueを設定し、create_arrow_modelにgeneral_adapter_pathsを指定することで、GenKnowSubを有効にします:

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.

一般的な知識をエンコードするために、GenKnowSub はルーティングが開始される前に、提供された一般的なアダプタの平均を、各タスク固有のアダプタから一度だけ引き算します。さらに、create_arrow_model の呼び出し後にアダプタを追加または削除する機能（Arrow セクションで説明されている通り）も、この場合引き続きサポートされています。

Arrow + GenKnowSub を使用する際に注意すべき点:

• すべての LoRA アダプタ（タスク固有および汎用）は、同じ rank と target_modules を共有する必要があります。

• これらの設定に不一致がある場合、create_arrow_modelでエラーが発生します。

• タスクアダプター間で異なるスケーリング係数（lora_alpha）を持つことはサポートされており、Arrow が自動的に処理します。

• 動的ルーティング動作のため、"arrow_router"のマージはサポートされていません。

• create_arrow_model において、タスクアダプターはtask_iとして、汎用アダプターはgks_jとして読み込まれます（ここでiとjはインデックスです）。この関数は、target_modules、rank、およびアダプターがLinearレイヤーかLinear4bitレイヤーに適用されるかの整合性を保証します。その後、"arrow_router"モジュールを追加して有効化します。このプロセスのカスタマイズには、create_arrow_modelをオーバーライドする必要があります。

• この実装は、4ビット量子化（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

LoraModel

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

ユーティリティ

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

ユーティリティ

侵入次元削減