# IA3

> [!TIP]
> IA3 — отличный выбор, когда требуется минимально возможный размер адаптера: он использует обучаемые векторы вместо матриц низкого ранга, что делает его одним из самых параметрически эффективных доступных методов. Если ваш приоритет — минимальный размер на диске/в памяти и быстрая тренировка, IA3 является сильным кандидатом.

    

IA3 вводит три вектора, lv, lk и lff, для масштабирования активаций value, key и feed-forward (источник изображения).

Infused Adapter by Inhibiting and Amplifying Inner Activations, or [IA3](https://hf.co/papers/2205.05638), is a method that adds three learned vectors to rescale the keys and values of the self-attention and encoder-decoder attention layers, and the intermediate activation of the position-wise feed-forward network.

Аннотация из статьи:

*Обучение с несколькими примерами в контексте (Few-shot in-context learning, ICL) позволяет предобученным языковым моделям выполнять ранее не встречавшуюся задачу без обучения на основе градиентов, передавая небольшое количество обучающих примеров в качестве части входных данных. ICL требует значительных вычислительных, энергетических и затрат на хранение, поскольку предполагает обработку всех обучающих примеров при каждом выполнении предсказания. Эффективное по параметрам дообучение (Parameter-efficient fine-tuning, PEFT) (например, адаптерные модули, prompt tuning, методы разреженного обновления и т. д.) предлагает альтернативный подход, при котором обучается небольшой набор параметров, чтобы модель могла выполнять новую задачу. В данной статье мы строго сравниваем few-shot ICL и PEFT и показываем, что второй вариант обеспечивает более высокую точность, а также значительно меньшие вычислительные затраты. По ходу работы мы представляем новый метод PEFT, названный (IA)^3, который масштабирует активации с помощью обучаемых векторов, достигая более высоких результатов при введении относительно небольшого количества новых параметров. Мы также предлагаем простой рецепт на основе модели T0, названный T-Few, который можно применять к новым задачам без настройки или модификаций, специфичных для конкретной задачи. Мы подтверждаем эффективность T-Few на полностью новых задачах, применив его к бенчмарку RAFT, впервые достигнув сверхчеловеческих результатов и превзойдя текущий уровень (state-of-the-art) на 6% в абсолютном выражении. Весь код, использованный в наших экспериментах, доступен публично*.

To make fine-tuning more efficient, IA3 (Infused Adapter by Inhibiting and Amplifying Inner Activations) rescales inner activations with learned vectors. These learned vectors are injected in the attention and feedforward modules in a typical transformer-based architecture. These learned vectors are the only trainable parameters during fine-tuning, and thus the original weights remain frozen. Dealing with learned vectors (as opposed to learned low-rank updates to a weight matrix like LoRA) keeps the number of trainable parameters much smaller.

Похоже на [LoRA](./lora), IA3 обладает многими преимуществами:

* IA3 делает дообучение более эффективным, значительно сокращая количество обучаемых параметров. (Для T0 модель IA3 содержит лишь около 0,01% обучаемых параметров, тогда как даже у LoRA их больше 0,1%)
* Исходные предобученные веса остаются замороженными, что позволяет создавать множество лёгких и переносимых моделей IA3 для различных задач, построенных на их основе.
* Производительность моделей, дообученных с использованием IA3, сопоставима с производительностью полностью дообученных моделей.
* IA3 не увеличивает задержку вывода, так как веса адаптера можно объединить с базовой моделью.

В принципе, IA3 можно применять к любому подмножеству матриц весов в нейронной сети для уменьшения количества обучаемых параметров. В соответствии с реализацией авторов, веса IA3 добавляются к слоям key, value и feedforward в модели Transformer. Конкретнее, для моделей Transformer веса IA3 добавляются к выходам слоёв key и value, а также ко входу второго feedforward-слоя в каждом блоке Transformer.

Зная целевые слои для внедрения параметров IA3, количество обучаемых параметров можно определить на основе размеров матриц весов.

## Использование

> [!TIP]
> Для авторегрессионных моделей нацельтесь на `k_proj`, `v_proj` и `down_proj` — это слои, которые авторы признали наиболее эффективными. Установите `feedforward_modules=["down_proj"]`, чтобы IA3 понимал, какие модули являются слоями прямой передачи, и мог применять правильное масштабирование.

Для задачи классификации последовательности конфигурацию IA3 для модели Llama можно инициализировать следующим образом:

```py
from peft import IA3Config, TaskType, get_peft_model
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("HuggingFaceTB/SmolLM-135M")
peft_config = IA3Config(
    task_type=TaskType.CAUSAL_LM,
    target_modules=["k_proj", "v_proj", "down_proj"],
    feedforward_modules=["down_proj"],
)
model = get_peft_model(model, peft_config)
model.print_healthcheck()
```

### Когда использовать IA3, а когда LoRA

IA3 особенно эффективна, когда вам нужны адаптеры минимального размера для развёртывания с ограниченным хранилищем или когда требуется быстрая сходимость при меньшем количестве обучаемых параметров. LoRA может быть предпочтительнее, если вам нужен более широкий набор вариантов LoRA (DoRA, QLoRA и т. д.) или если вы хотите использовать наиболее протестированный подход с обширной поддержкой сообщества.

## Обзор бенчмарков

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=IA3" frameborder="0" width="850" height="1000"
>

# API

## IA3Config[[peft.IA3Config]]

#### peft.IA3Config[[peft.IA3Config]]

```python
peft.IA3Config(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, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, feedforward_modules: Optional[Union[list[str], str]] = None, fan_in_fan_out: bool = False, modules_to_save: Optional[list[str]] = None, init_ia3_weights: bool = True)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/config.py#L25)

**Параметры:**

target_modules (`Optional[Union[List[str], str]]`) : Имена модулей, к которым следует применить адаптер. Если это значение указано, будут заменены только модули с указанными именами. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк. Если это значение указано как 'all-linear', выбираются все линейные/Conv1D модули, за исключением выходного слоя. Если это значение не указано, модули выбираются в соответствии с архитектурой модели. Если архитектура неизвестна, будет выброшена ошибка — в этом случае следует указать целевые модули вручную.

exclude_modules (`Optional[Union[List[str], str]]`) : Имена модулей, к которым не следует применять адаптер. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк.

feedforward_modules (`Optional[Union[List[str], str]]`) : Имена модулей, которые следует обрабатывать как модули прямого распространения (feedforward), как в оригинальной статье. Для этих модулей векторы (IA)³ будут умножаться на вход, а не на выход. `feedforward_modules` должно быть именем или подмножеством имён, присутствующих в `target_modules`.

fan_in_fan_out (`bool`) : Установите это значение в True, если заменяемый слой хранит веса в формате (fan_in, fan_out). Например, gpt-2 использует `Conv1D`, который хранит веса в формате (fan_in, fan_out), поэтому это значение должно быть установлено в `True`.

modules_to_save (`Optional[List[str]]`) : Список модулей, кроме слоёв (IA)³, которые нужно сделать обучаемыми и сохранить в итоговой контрольной точке.

init_ia3_weights (`bool`) : Флаг, определяющий, следует ли инициализировать векторы в слоях (IA)³. По умолчанию установлено значение `True`. Установка значения `False` не рекомендуется.

Это класс конфигурации для хранения конфигурации модели [IA3Model](/docs/peft/main/ru/package_reference/ia3#peft.IA3Model).

## IA3Model[[peft.IA3Model]]

#### peft.IA3Model[[peft.IA3Model]]

```python
peft.IA3Model(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/main/src/peft/tuners/ia3/model.py#L36)

**Параметры:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)): модель, подлежащая адаптации.

config ([IA3Config](/docs/peft/main/ru/package_reference/ia3#peft.IA3Config)) : конфигурация модели (IA)^3.

adapter_name (`str`) : Имя адаптера, по умолчанию `"default"`.

low_cpu_mem_usage (`bool`, `optional`, по умолчанию `False`) : Создать пустые веса адаптера на мета-устройстве. Полезно для ускорения процесса загрузки.

**Возвращает:** `torch.nn.Module`

The модель (IA)^3.

Создаёт модель Infused Adapter by Inhibiting and Amplifying Inner Activations ((IA)^3) на основе предобученной модели transformers. Метод подробно описан в https://huggingface.co/papers/2205.05638

Пример:

```py
>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import IA3Config, get_peft_model

>>> config = IA3Config(
...     peft_type="IA3",
...     task_type="SEQ_2_SEQ_LM",
...     target_modules=["k", "v", "w0"],
...     feedforward_modules=["w0"],
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> ia3_model = get_peft_model(model, config)
```

**Атрибуты**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- Модель, подлежащая адаптации.
- **peft_config** ([IA3Config](/docs/peft/main/ru/package_reference/ia3#peft.IA3Config)): конфигурация модели (IA)^3.

#### add_weighted_adapter[[peft.IA3Model.add_weighted_adapter]]

```python
add_weighted_adapter(adapters: list[str], weights: list[float], adapter_name: str)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/ia3/model.py#L273)

**Параметры:**

adapters (`list`) : список имён адаптеров, которые будут объединены.

weights (`list`) : список весов для каждого адаптера.

adapter_name (`str`) : Имя нового адаптера.

Этот метод добавляет новый адаптер, объединяя указанные адаптеры с заданными весами.

