# GLoRA

广义低秩适应（[GLoRA](https://huggingface.co/papers/2306.07967)）是一种 PEFT 方法，它推广了 LoRA 及相关方法。GLoRA 将更新分解为可配置的路径（A、B、C、D、E），其中每条路径可根据其自身情况采用低秩、向量、常数或禁用参数化。

每条路径支持四种参数化模式之一。它们在**参数数量**与**表达能力**（更新可以有多丰富）之间进行权衡：

- `"lora"`：低秩分解（类似于标准 LoRA）。使用 `r * (out + in)` 个参数，可以表达秩为 `r` 的修正。表达能力最强，参数也最多。
- `"vector"`：单个向量（例如形状为 `(out, 1)`），在矩阵上进行广播。使用 `O(out)` 个参数；仅支持按通道的缩放或偏移。
- `"constant"`：在所有元素间共享的单个标量。使用 1 个参数；在可训练选项中表达能力最弱。
- `"none"`：零值且无可训练参数；完全禁用该路径。

并非每条路径都支持所有模式（例如，`config_D_E` 不支持 `"lora"`）。在更多路径上选择 `"lora"` 会增加容量和可训练参数；而 `"vector"`、`"constant"` 或 `"none"` 则会减少这两者。

GLoRA 特别适用于研究和高级应用，在这些场景中，您希望尝试结构化的更新模式，并在单个层中组合多种适配机制。

从高层次来看，GLoRA 通过以下方式修改冻结的线性层：

$$ W_{\mathrm{eff}} = W_0 + W_0 \odot A + B $$

$$ b_{\mathrm{eff}} = b_0 + b_0 \odot D + E + W_0 C $$

其中每条路径都是独立参数化的。

## GloraConfig[[peft.GloraConfig]]

#### peft.GloraConfig[[peft.GloraConfig]]

```python
peft.GloraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 8, target_modules: list[str] | str | None = None, bias: str = 'none', modules_to_save: list[str] | None = None, config_A_B: typing.Literal['lora', 'vector', 'constant', 'none'] = 'lora', config_C: typing.Literal['lora', 'vector', 'none'] = 'lora', config_D_E: typing.Literal['vector', 'constant', 'none'] = 'constant', init_weights: bool = True)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/glora/config.py#L23)

**参数：**

r (`int`) : 当配置设置为 `lora` 时，所使用的低秩分解的秩。

target_modules (`Optional[Union[List[str], str]]`) : 要应用 Glora 的模块名称。

config_A_B (`str`) : A 矩阵和 B 矩阵的参数化方式（权重乘性修正和加性修正）。有效值：`lora`、`vector`、`constant`、`none`。

config_C (`str`) : C 矩阵的参数化方式（权重到偏置的耦合：b += W0 @ C）。有效值：`lora`、`vector`、`none`。

config_D_E (`str`) : D 和 E 标量（偏置乘法和加法校正）的参数化方式。由于 D 和 E 是偏置大小的向量而非矩阵，因此不支持 `lora`。有效值：`vector`、`constant`、`none`。

init_weights (`bool`) : 如果为 True（默认值），则将 GLoRA 初始化为无操作（零值）。如果为 False，则使用 kaiming 初始化，使适配器不成为无操作。

这是用于存储 [GloraModel](/docs/peft/v0.22.0/zh/package_reference/glora#peft.GloraModel) 配置的类。

Glora 对冻结的线性层 W0 进行如下修改：`W_eff = W0 + W0 * A + B` 以及 `b_eff = b0 + b0 * D + E + W0 @ C`。

每个矩阵（A、B、C、D、E）都可以独立进行参数化。配置值控制使用多少参数以及它们可以表达的形状：

- `lora`：低秩分解 `Xd @ Xu`，形状为 `(out, r)` 和 `(r, in)`。使用 `r * (out + in)` 个参数，可以表示任意秩为 r 的修正。与标准 LoRA 类似。
- `vector`：形状为 `(out, 1)` 的单个列向量，在整个矩阵上进行广播。使用 `out` 个参数；仅支持按输出通道的缩放或偏移。
- `constant`：在所有元素间共享的单个标量。使用 1 个参数；约束最强。
- `none`：零，没有可训练参数。实际上禁用了此路径。

### 主要配置选项
- `r`：当路径配置为 `"lora"` 时使用的秩（默认值：`8`）。
- `target_modules`：要适配的模块名称列表或正则表达式（例如 `["q_proj", "v_proj"]`）。
- `config_A_B`：A 和 B 的路径类型（"lora"、"vector"、"constant"、"none"）。
- `config_C`：C 的路径类型（"lora"、"vector"、"none"）。
- `config_D_E`：D 和 E 的路径类型（"constant"、"vector"、"none"）。
- `bias`：偏差处理（`"none"`、`"all"` 或 `"glora_only"`）。
- `init_weights`：如果为 `True`（默认值），GLoRA 将初始化为无操作。如果为 `False`，则使用 kaiming 初始化。

注意事项：
- `config_D_E` 不支持 `"lora"`。
- 对于支持的模型类型，可以省略`target_modules`（将使用 PEFT 的默认映射）。

## GloraModel[[peft.GloraModel]]

#### peft.GloraModel[[peft.GloraModel]]

```python
peft.GloraModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/glora/model.py#L34)

从预训练的 transformers 模型创建广义低秩适配器（GLoRA）模型。

- 封装基础模型，并将 GLoRA 适配器注入到指定的模块中。
- 支持多个适配器、适配器切换、合并/取消合并以及混合批次推理。
- 使用 `set_adapter`、`merge_and_unload` 及相关方法进行适配器管理。

## GloraLayer 和 GloraLinear[[peft.tuners.glora.GloraLayer]]

#### peft.tuners.glora.GloraLayer[[peft.tuners.glora.GloraLayer]]

```python
peft.tuners.glora.GloraLayer(base_layer: nn.Module, **kwargs)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/glora/layer.py#L103)

#### peft.tuners.glora.GloraLinear[[peft.tuners.glora.GloraLinear]]

```python
peft.tuners.glora.GloraLinear(base_layer: nn.Module, adapter_name: str, config, **kwargs)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/glora/layer.py#L298)

包装稠密 `~torch.nn.Linear` `base_layer` 的 GLoRA 适配器。

- `GloraLayer` 是广义低秩适配的核心逻辑，支持多个适配器以及灵活的路径配置。
- `GloraLinear` 是 `nn.Linear` 的直接替代品，支持 GLoRA。
- GLoRA 目前支持普通的 `torch.nn.Linear` 基础层。

## 使用示例

```python
from transformers import AutoModelForCausalLM
from peft import GloraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("your-model-id")
glora_config = GloraConfig(
    r=8,
    target_modules=["q_proj", "v_proj"],
    config_A_B="lora",
    config_C="vector",
    config_D_E="constant",
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, glora_config)
model.print_healthcheck()

# Switch adapters, merge, etc.
model.set_adapter("default")
model.merge_and_unload()
```

## 备注
- GLoRA 是 LoRA 的超集：将所有路径设置为 "lora" 即可恢复标准的 LoRA。
- 您可以为 A/B/C/D/E 使用不同的路径类型，以尝试新的适配策略。
- GLoRA 支持所有标准的 PEFT 适配器管理功能（添加、删除、切换、合并等）。

## 另请参阅
- [LoRA 参考](./lora)
- [论文：https://huggingface.co/papers/2306.07967](https://huggingface.co/papers/2306.07967)

