PEFT

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

DEFT: テキストから画像生成モデルのための分解型効率的ファインチューニング

DEFT（Decompositional Efficient Fine-Tuning）は、テキストから画像を生成するモデル向けのパラメータ効率の良いファインチューニング手法です。凍結された重み行列 W の更新を、2つの学習可能な要素に分解します。1つは W から低ランク部分空間を除去する射影、もう1つはその部分空間に新しい内容を注入する低ランク更新です。この定式化は、ターゲット分布への適合、少数の画像からの新概念の学習（パーソナライゼーション）、事前学習済みモデルの指示追従能力と編集可能性の維持のバランスを取るよう設計されています。

具体的には、DEFTは学習可能な低ランクの2つの要素を組み合わせます。(1)低ランク行列によって張られる低ランク部分空間の補空間への射影、および(2)低ランク更新です。最初の低ランク行列は部分空間を定義し、2つ目の行列はその部分空間内での柔軟なパラメータ適応を可能にします。

DEFTの使用場面: ベースモデルの指示追従能力を維持し、さらには向上させながら、既存の能力の忘却を最小限に抑えることを前提として、モデルを新しいデータや概念に適応させる場合に最も適しています。

ターゲットレイヤーごとに、DEFTは射影方向P(形状out_features x r)と注入行列R(形状r x in_features)を学習します。有効な重みは、残差射影です

W' = (I - P_proj) @ W + Q_P @ R

プロジェクターP_projは、decomposition_methodに従ってPから導出されます:

"relu" (デフォルト): Q_P = P、P_proj = P @ relu(P).T — 非直交射影です。
"qr": Q_P = qr(P)、P_proj = Q_P @ Q_P.T — 直交射影です。

(I - P_proj) @ W 項は事前学習済み重みの部分空間を除去し、Q_P @ R はそこに新しい内容を注入します。デフォルトでは (init_weights=True)、R は初期化時に更新が厳密な恒等変換 (W' == W) となるように初期化されるため、事前学習済み重みから学習を開始し、注入を学習します。この更新は、低ランクの加法的デルタ Q_P @ (R - right.T @ W) に相当し、out x out の射影行列を形成することなく計算でき、推論時のデプロイメントのためにベースの重みにマージできます。

para=True を設定すると、PaRa（Parameter Rank Reduction）バリアントが選択されます。これは、サブスペース除去の項のみを保持し、注入を除外する除去専用の更新 W' = (I - P_proj) @ W です。学習されるのは射影 P のみ（注入行列 R はありません）であり、そのためアダプタは初期化時に恒等変換ではありません。PaRa はテキストから画像への拡散モデルのパーソナライズのために導入され、ここでは DEFT の特殊ケースとして利用可能です。

DEFTは現在、torch.nn.LinearおよびConv1D（fan_in_fan_outを介したgpt-2など）のレイヤーに対して実装されています。論文（Stable Diffusionおよび統合モデルにおけるDreambooth、Dreambench Plus、InsDet、VisualCloze）の元の実装と実験は、github.com/MAXNORM8650/DEFTで利用できます。

DEFTを研究に使用する場合、以下の論文を引用してください。

@article{kumar2026deft,
  title={DEFT: Decompositional Efficient Fine-Tuning for Text-to-Image Models},
  author={Kumar, Komal and Anwer, Rao and Shahbaz Khan, Fahad and Khan, Salman and Laptev, Ivan and Cholakkal, Hisham},
  journal={Advances in Neural Information Processing Systems},
  volume={38},
  pages={102009--102035},
  year={2026}
}

PaRaバリアント（para=True）を使用する場合は、以下の論文も引用してください：

@inproceedings{chen2025personalizing,
  title={Para: Personalizing text-to-image diffusion via parameter rank reduction},
  author={Chen, Shangyu and Pan, Zizheng and Cai, Jianfei and Phung, Dinh},
  booktitle={International Conference on Learning Representations},
  year={2025}
}

DeftConfig

クラス peft.DeftConfig

< source >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 8target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonedecomposition_method: Literal['relu', 'qr'] = 'relu'init_scale: float = 1.0alpha: Optional[int] = Nonepara: bool = Falsefan_in_fan_out: bool = Falsedeft_dropout: float = 0.0init_weights: bool = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Nonebias: str = 'none'modules_to_save: Optional[list[str]] = None )

パラメータ

r (int) — DEFTの射影/注入のレイヤー間のランクです。
target_modules (Optional[Union[List[str], str]]) — アダプタを適用するモジュールの名前です。このパラメータが指定されている場合、指定された名前のモジュールのみが置き換えられます。文字列を渡す場合、正規表現によるマッチングが行われます。文字列のリストを渡す場合、完全一致が行われるか、モジュール名が渡された文字列のいずれかで終わるかがチェックされます。このパラメータが ‘all-linear’ として指定されている場合、出力層を除くすべての線形モジュールが選択されます。このパラメータが指定されていない場合、モデルのアーキテクチャに基づいてモジュールが選択されます。アーキテクチャが不明な場合はエラーが発生します。この場合、ターゲットモジュールを手動で指定する必要があります。
exclude_modules (Optional[Union[List[str], str]]) — アダプタを適用しないモジュールの名前。文字列を渡す場合、正規表現によるマッチングが行われます。文字列のリストを渡す場合、完全一致が行われるか、モジュール名が渡された文字列のいずれかで終わるかがチェックされます。
decomposition_method (str) — プロジェクター P_proj が P からどのように導出されるかを指定します。"relu"（デフォルト、非直交な P @ relu(P).T）または "qr"（直交な Q_P @ Q_P.T）のいずれかです。
init_scale (float) — 注入行列 R の初期化に用いられる標準偏差に適用されるスケーリング（init_weights=False の場合のみ使用されます）。値が小さいほど、初期化時に注入される更新がゼロに近づきます。デフォルト値は 1.0 です。
alpha (Optional[int]) — 注入項のスケーリング係数です。alpha / r によってスケーリングされます（LoRA の alpha に類似しています）。None の場合、スケーリングは適用されません（係数 1.0）。部分空間除去項には影響しません。
para (bool) — PaRa手法を使用するかどうか: 注入項なしの純粋な部分空間除去(delta = -P_proj @ W)。 Trueの場合、Rは作成されず、Pが唯一の学習可能な行列となり、アダプターは初期化時に恒等変換にはなりません。デフォルトはFalse(完全なDEFT)です。
fan_in_fan_out (bool) — 置き換えるレイヤーが重みを (fan_in, fan_out) の形式で保存している場合は、これを True に設定してください。例えば、gpt-2 は重みを (fan_in, fan_out) の形式で保存する Conv1D を使用しているため、これを True に設定する必要があります。
deft_dropout (float) — レイヤーの入力に適用されるドロップアウト確率です。デフォルト値は0.0です。
init_weights (bool) — アダプター重みに DEFT のデフォルト（恒等）初期化を使用するかどうか。これにより、学習開始時にアダプターが何もしない状態になります。この設定を変更しないでください。正確に意図している場合を除きます。デフォルトは True です。
layers_to_transform (Union[List[int], int]) — 変換対象のレイヤーのインデックスです。int のリストが渡された場合、このリストに指定されたレイヤーのインデックスにアダプターが適用されます。単一の整数が渡された場合、そのインデックスのレイヤーに変換が適用されます。
layers_pattern (Optional[Union[List[str], str]]) — layers_to_transform が None と異なる場合にのみ使用されるレイヤーパターン名です。これはモデルの nn.ModuleList を対象とすべきで、通常は 'layers' または 'h' と呼ばれます。
bias (str) — DEFT のバイアスタイプ。'none'、'all'、または 'deft_only' を指定できます。
modules_to_save (List[str]) — 最終チェックポイントに保存されるよう、学習可能に設定するアダプタ層以外のモジュールのリスト。

これはDeftModelの設定を保存するための設定クラスです。

DEFT (Decompositional Efficient Fine-Tuning) は、残差投影更新を通じて知識注入を実行します。凍結されたベース重み W に対して、低ランクの投影方向 P（形状 out_features x r）と注入行列 R（形状 r x in_features）が学習されます。適応後の重みは W' = (I - P_proj) @ W + Q_P @ R であり、プロジェクター P_proj は decomposition_method に従って P から導出されます。

"relu" (デフォルト): Q_P = P、P_proj = P @ relu(P).T (非直交射影)
"qr": Q_P = qr(P)、P_proj = Q_P @ Q_P.T（直交射影）

デフォルトでは (init_weights=True)、R は初期化時に更新が厳密な恒等変換となるように初期化されます (適応された重みが W に等しくなる)。これにより、学習は事前学習済み重みから開始され、インジェクションを学習します。

DeftModel

クラス peft.DeftModel

< source >

( 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

パラメータ

model (torch.nn.Module) — アダプタチューナー層が接続されるモデル。
config (DeftConfig) — DEFTモデルの設定。
adapter_name (str) — アダプターの名前。デフォルトは"default"です。
low_cpu_mem_usage (bool、optional、デフォルトはFalse) — メタデバイス上に空のアダプター重みを生成します。読み込みプロセスを高速化するために有用です。

戻り値

torch.nn.Module

DEFTモデル。

事前学習済みモデルからDEFT（Decompositional Efficient Fine-Tuning）モデルを作成します。

DEFTはベースの重みを凍結し、ターゲットモジュールごとに低ランクの射影方向Pと注入行列Rを学習します。有効な重みは(I - P_proj) @ W + Q_P @ Rとなり、Wの部分空間を新たに注入された内容で置き換えます（利用可能なdecomposition_methodのバリアントについては、DeftConfigを参照してください）。

属性:

model (~torch.nn.Module) — 適応させる対象のモデル。
peft_config (DeftConfig): DEFTモデルの設定。

Update on GitHub

←C3A DeLoRA→