# LLaMA-Factory

LLaMA-Factory — это самый полнофункциональный фреймворк с открытым исходным кодом для дообучения моделей, поддерживающий более 100 моделей, включая все варианты LLaMA, Qwen, Mistral, Phi, Falcon, ChatGLM и другие. Он предоставляет LoRA, QLoRA, полное дообучение, RLHF, DPO и PPO — всё через удобный веб-интерфейс (LLaMA Board) или CLI. Серверы CLORE.AI с GPU по требованию делают его идеальной платформой для запуска задач дообучения по цене намного ниже облачных провайдеров.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендуемых через [CLORE.AI Маркетплейс](https://clore.ai/marketplace).
{% endhint %}

## Требования к серверу

| Параметр | Минимум          | Рекомендуется  |
| -------- | ---------------- | -------------- |
| ОЗУ      | 16 ГБ            | 32 ГБ+         |
| VRAM     | 8 ГБ (QLoRA)     | 24 ГБ+         |
| Диск     | 50 ГБ            | 200 ГБ+        |
| GPU      | NVIDIA RTX 2080+ | A100, RTX 4090 |

{% hint style="info" %}
**Метод обучения определяет требования к GPU:**

* **QLoRA (4-бит)**: 8 ГБ VRAM для моделей 7B, 16 ГБ для 13B
* **LoRA (float16)**: 16 ГБ VRAM для моделей 7B, 40 ГБ для 13B
* **Полное дообучение**: \~14 ГБ VRAM на 7B параметров (+ состояния оптимизатора)
* Multi-GPU (DeepSpeed/FSDP) масштабируется на любое количество GPU
  {% endhint %}

## Быстрое развертывание на CLORE.AI

**Docker-образ:** `hiyouga/llamafactory:latest`

**Порты:** `22/tcp`, `7860/http`

**Переменные окружения:**

| Переменная             | Пример      | Описание                                        |
| ---------------------- | ----------- | ----------------------------------------------- |
| `HF_TOKEN`             | `hf_xxx...` | Токен HuggingFace для gated-моделей             |
| `WANDB_API_KEY`        | `xxx...`    | Weights & Biases для отслеживания экспериментов |
| `CUDA_VISIBLE_DEVICES` | `0,1`       | Какие GPU использовать                          |

## Пошаговая настройка

### 1. Арендуйте GPU-сервер на CLORE.AI

Перейдите на [CLORE.AI Маркетплейс](https://clore.ai/marketplace) и выбирайте в зависимости от вашей задачи:

| Задача     | VRAM        | Рекомендуемый GPU |
| ---------- | ----------- | ----------------- |
| QLoRA 7B   | 8 ГБ        | RTX 3070/2080     |
| QLoRA 13B  | 16 ГБ       | RTX 3090/A4000    |
| LoRA 7B    | 16 ГБ       | RTX 3090/A4000    |
| LoRA 13B   | 40 ГБ       | A6000/A100 40GB   |
| Full FT 7B | 80 ГБ       | A100 80GB         |
| Multi-GPU  | Различается | 2-8× любой GPU    |

### 2. Подключитесь по SSH к вашему серверу

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. Создайте рабочие каталоги

```bash
mkdir -p /root/llamafactory/{data,models,output,saves}
```

### 4. Скачайте Docker-образ

```bash
docker pull hiyouga/llamafactory:latest
```

### 5. Запустите LLaMA-Factory

**Запуск с веб-интерфейсом (LLaMA Board):**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**С отслеживанием Weights & Biases:**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  -e WANDB_API_KEY=your_wandb_key \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**Multi-GPU с DeepSpeed (4 GPU):**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  --shm-size 16g \
  --ipc host \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -e CUDA_VISIBLE_DEVICES=0,1,2,3 \
  hiyouga/llamafactory:latest \
  bash -c "llamafactory-cli webui"
```

### 6. Доступ к веб-интерфейсу

Просмотрите логи и получите URL:

```bash
docker logs -f llamafactory
```

Ваш CLORE.AI http\_pub URL для порта 7860:

```
https://<order-id>-7860.clore.ai/
```

***

## Примеры использования

### Пример 1: LoRA дообучение через веб-интерфейс (LLaMA Board)

1. Откройте LLaMA Board по вашему CLORE.AI URL
2. Перейдите в **Train** вкладку
3. Настройте:
   * **Название модели**: `LLaMA-3` → `Meta-Llama-3-8B-Instruct`
   * **Этап обучения**: `Supervised Fine-Tuning`
   * **Датасет**: Выберите ваш датасет (или загрузите свой)
   * **Метод дообучения**: `lora`
   * **LoRA rank**: `8` (больше = больше обучаемых параметров)
   * **Скорость обучения**: `1e-4`
   * **Эпохи**: `3`
   * **Каталог вывода**: `llama3-finetuned`
4. Нажмите **Начать** чтобы начать обучение
5. Отслеживайте кривые потерь в **Loss** диаграмме

### Пример 2: QLoRA дообучение через CLI

Подготовьте YAML конфиг для обучения:

```bash
docker exec -it llamafactory bash

cat > /app/LLaMA-Factory/configs/qlora_mistral.yaml << 'EOF'
### Model
model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3

### Method
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05

### Dataset
dataset: alpaca_en
template: mistral
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### Output
output_dir: saves/mistral-qlora
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

### Train
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
learning_rate: 0.0001
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
fp16: true

### Quantization
quantization_method: bitsandbytes
quantization_bit: 4
EOF

# Запуск обучения
llamafactory-cli train /app/LLaMA-Factory/configs/qlora_mistral.yaml
```

### Пример 3: Загрузка собственного датасета

Создайте пользовательский датасет в формате Alpaca:

```bash
# Создать файл датасета
cat > /root/llamafactory/data/my_dataset.json << 'EOF'
[
  {
    "instruction": "Вы агент службы поддержки в технологической компании. Отвечайте полезно.",
    "input": "Мой ноутбук не включается после обновления. Что мне делать?",
    "output": "Я понимаю, как это может раздражать. Давайте решать по шагам:\n\n1. **Удерживайте кнопку питания в течение 10 секунд**, чтобы принудительно завершить работу\n2. **Отключите питание** и извлеките аккумулятор, если он съемный, подождите 30 секунд\n3. **Подключите питание снова** и попробуйте включить\n4. Если все равно нет отклика, нажмите **F8/F11** при загрузке, чтобы войти в режим восстановления\n\nХотите, чтобы я подробно провёл вас через один из этих шагов?"
  },
  {
    "instruction": "Вы агент службы поддержки технологической компании.",
    "input": "Как мне сбросить пароль?",
    "output": "Сброс пароля — просто! Вот как:\n\n1. Перейдите на страницу входа и нажмите **'Забыли пароль'**\n2. Введите ваш **зарегистрированный адрес электронной почты**\n3. Проверьте почту на наличие ссылки для сброса (проверьте папку спам тоже)\n4. Нажмите ссылку и **создайте новый пароль**\n\nСсылка для сброса действует 24 часа. Если вы не получили письмо в течение 5 минут, свяжитесь со службой поддержки."
  }
]
EOF

# Зарегистрируйте датасет в dataset_info.json
docker exec -it llamafactory bash -c "
cat >> /app/LLaMA-Factory/data/dataset_info.json << 'EOF2'
,
\"my_dataset\": {
  \"file_name\": \"/root/llamafactory/data/my_dataset.json\"
}
EOF2
"
```

Затем выберите `my_dataset` в выпадающем списке датасетов LLaMA Board.

### Пример 4: DPO (Direct Preference Optimization)

```yaml
### configs/dpo_llama.yaml

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct

### Метод - DPO
stage: dpo
do_train: true
finetuning_type: lora
lora_rank: 8

### DPO-специфично
pref_beta: 0.1
pref_loss: sigmoid  # sigmoid, hinge, ipo

### Датасет (должен быть в формате предпочтений)
dataset: dpo_en_demo
template: llama3
cutoff_len: 2048

### Output
output_dir: saves/llama3-dpo
logging_steps: 10
save_steps: 100

### Train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 5e-5
num_train_epochs: 1.0
fp16: true
```

```bash
docker exec -it llamafactory bash -c "llamafactory-cli train /configs/dpo_llama.yaml"
```

### Пример 5: Инференс с дообученной моделью

После обучения протестируйте вашу модель:

```bash
docker exec -it llamafactory bash

# Интерактивный чат
llamafactory-cli chat \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora
```

Или экспортируйте объединённую модель:

```bash
llamafactory-cli export \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora \
  --export_dir /app/LLaMA-Factory/output/mistral-merged \
  --export_size 4 \
  --export_legacy_format false
```

***

## Конфигурация

### Ключевые параметры обучения

| Параметр                      | Типичное значение | Описание                                        |
| ----------------------------- | ----------------- | ----------------------------------------------- |
| `lora_rank`                   | 8–64              | LoRA rank (больше = более выразительная модель) |
| `lora_alpha`                  | 2× rank           | Масштабирование LoRA alpha                      |
| `lora_dropout`                | 0.0–0.1           | Dropout для LoRA-слоёв                          |
| `lora_target`                 | `all`             | На какие слои применять LoRA                    |
| `learning_rate`               | `1e-4`            | Начальная скорость обучения                     |
| `num_train_epochs`            | 1–5               | Эпохи обучения                                  |
| `per_device_train_batch_size` | 1–4               | Размер батча на GPU                             |
| `gradient_accumulation_steps` | 4–16              | Эффективный множитель батча                     |
| `cutoff_len`                  | 1024–4096         | Максимальная длина последовательности           |
| `quantization_bit`            | 4 или 8           | Биты квантования для QLoRA                      |
| `warmup_ratio`                | 0.05–0.1          | Доля разогрева LR                               |
| `lr_scheduler_type`           | `cosine`          | График изменения LR                             |

### Поддерживаемые методы дообучения

| Метод                | Использование памяти | Качество     | Когда использовать         |
| -------------------- | -------------------- | ------------ | -------------------------- |
| `full`               | Очень высокое        | Лучший выбор | Неограниченная видеопамять |
| `freeze`             | Средне               | Хорошо       | Заморозить базовые слои    |
| `lora`               | Низкое               | Очень хорошо | Выбор по умолчанию         |
| `qlora` (lora+quant) | Минимальное          | Хорошо       | Ограниченная видеопамять   |

### Multi-GPU DeepSpeed обучение

Для обучения на нескольких GPU запустите с помощью `torchrun`:

```bash
docker exec -it llamafactory bash -c "
FORCE_TORCHRUN=1 NNODES=1 RANK=0 MASTER_ADDR=127.0.0.1 MASTER_PORT=29500 \
llamafactory-cli train configs/qlora_mistral.yaml \
  --deepspeed examples/deepspeed/ds_z3_config.json
"
```

***

## Советы по производительности

### 1. Оптимальные настройки QLoRA по GPU

**8 ГБ VRAM (RTX 3070):**

```yaml
quantization_bit: 4
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
cutoff_len: 1024
```

**24 ГБ VRAM (RTX 3090/4090):**

```yaml
quantization_bit: 4  # По-прежнему используйте QLoRA для большего размера батча
per_device_train_batch_size: 4
gradient_accumulation_steps: 4
cutoff_len: 2048
```

**80 ГБ VRAM (A100):**

```yaml
# Квантование не требуется — используйте LoRA напрямую
finetuning_type: lora
per_device_train_batch_size: 8
gradient_accumulation_steps: 2
cutoff_len: 4096
fp16: true
```

### 2. Flash Attention 2 для более длинного контекста

```yaml
flash_attn: fa2  # Требуется GPU архитектуры Ampere и выше
```

Это позволяет обучать с последовательностями в 2× большей длины на той же видеопамяти.

### 3. Gradient Checkpointing

Экономит видеопамять за счёт примерно 20% более медленного обучения:

```yaml
gradient_checkpointing: true
```

### 4. Выберите правильную цель LoRA

```yaml
lora_target: all  # Все линейные слои (по умолчанию, лучшее качество)
# или
lora_target: q_proj,v_proj  # Минимально, быстрее, ниже качество
```

### 5. Заморозьте верхние слои для быстрой адаптации

```yaml
finetuning_type: freeze
freeze_trainable_layers: 2   # Обучать только верхние 2 слоя
freeze_trainable_modules: all
```

Гораздо быстрее, чем полный LoRA, для простой адаптации под задачу.

### 6. Мониторинг через TensorBoard

```bash
# В отдельном терминале
docker exec -it llamafactory bash -c "
tensorboard --logdir /app/LLaMA-Factory/saves --host 0.0.0.0 --port 6006
"
```

Добавьте порт 6006 в ваш заказ CLORE.AI, чтобы получить доступ к TensorBoard.

***

## Устранение неполадок

### Проблема: "CUDA out of memory" во время обучения

1. Уменьшите размер батча: `per_device_train_batch_size: 1`
2. Включите gradient checkpointing: `gradient_checkpointing: true`
3. Уменьшите длину контекста: `cutoff_len: 512`
4. Используйте QLoRA (4-бит): `quantization_bit: 4`
5. Уменьшите LoRA rank: `lora_rank: 4`

### Проблема: Потеря при обучении не уменьшается

* Проверьте скорость обучения — попробуйте `5e-5` или `2e-4`
* Убедитесь, что формат датасета соответствует шаблону
* Увеличьте `lora_rank` (8→16→32)
* Проверьте, что `lora_target: all` установлено

### Проблема: Медленная скорость обучения

```bash
# Проверьте загрузку GPU внутри контейнера
docker exec -it llamafactory bash -c "watch -n 1 nvidia-smi"
```

Если загрузка GPU < 80%:

* Увеличьте размер батча
* Используйте Flash Attention: `flash_attn: fa2`
* Удалите `gradient_checkpointing` если видеопамяти достаточно

### Проблема: Модель не найдена в веб-интерфейсе

```bash
# Предварительно скачайте в кэш том
docker exec -it llamafactory bash -c "
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3
"
```

Затем обновите список моделей в LLaMA Board.

### Проблема: Ошибки формата датасета

Все форматы датасетов должны соответствовать `dataset_info.json` спецификации:

```bash
# Проверить датасет
docker exec -it llamafactory python3 -c "
import json
with open('/app/LLaMA-Factory/data/my_dataset.json') as f:
    data = json.load(f)
print(f'В датасете {len(data)} примеров')
print('Ключи первого примера:', list(data[0].keys()))
"
```

### Проблема: Порт WebUI недоступен

Убедитесь, что LLaMA-Factory запустил Gradio сервер:

```bash
docker logs llamafactory 2>&1 | grep -E "Running on|Error|Traceback"
```

Добавьте `--share` флаг для публичного Gradio URL в качестве альтернативы.

***

## Ссылки

* [GitHub](https://github.com/hiyouga/LLaMA-Factory)
* [Документация](https://llamafactory.readthedocs.io)
* [Docker Hub (hiyouga)](https://hub.docker.com/r/hiyouga/llamafactory)
* [Поддерживаемые модели](https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#supported-models)
* [Формат датасета](https://github.com/hiyouga/LLaMA-Factory/blob/main/data/README.md)
* [CLORE.AI Маркетплейс](https://clore.ai/marketplace)

***

## Рекомендации Clore.ai по GPU

| Сценарий использования     | Рекомендуемый GPU | Примерная стоимость на Clore.ai |
| -------------------------- | ----------------- | ------------------------------- |
| Разработка/Тестирование    | RTX 3090 (24GB)   | \~$0.12/gpu/hr                  |
| Дообучение (7B–13B)        | RTX 4090 (24GB)   | \~$0.70/gpu/hr                  |
| Крупные модели (70B+)      | A100 80GB         | \~$1.20/gpu/hr                  |
| Обучение на нескольких GPU | 2-4x A100 80GB    | \~$2.40–$4.80/hr                |

> 💡 Все примеры в этом руководстве можно развернуть на [Clore.ai](https://clore.ai/marketplace) GPU-серверах. Просматривайте доступные GPU и арендуйте по часам — без обязательств, с полным root-доступом.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/obuchenie/llama-factory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.