> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-ru/obuchenie/llama-factory.md).

# LLaMA-Factory

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

{% 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-bit)**: 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 для моделей с ограниченным доступом |
| `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 80 ГБ        |
| Несколько 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

**Запуск с Web UI (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-дообучение через Web UI (LLaMA Board)

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

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

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

```bash
docker exec -it llamafactory bash

cat > /app/LLaMA-Factory/configs/qlora_mistral.yaml << 'EOF'
### Модель
model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3

### Метод
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05

### Набор данных
dataset: alpaca_en
template: mistral
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### Вывод
output_dir: saves/mistral-qlora
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

### Обучение
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_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_dir: saves/llama3-dpo
logging_steps: 10
save_steps: 100

### Обучение
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 (больше = более выразительная модель) |
| `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 or 8            | Биты квантования QLoRA                          |
| `warmup_ratio`                | 0.05–0.1          | Доля разогрева LR                               |
| `lr_scheduler_type`           | `cosine`          | Планировщик LR                                  |

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

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

### Обучение DeepSpeed на нескольких GPU

Для обучения на нескольких 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× длиннее при том же объёме VRAM.

### 3. Gradient Checkpointing

Экономит VRAM ценой примерно на 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-bit): `quantization_bit: 4`
5. Уменьшите ранг LoRA: `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` если позволяет VRAM

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

```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'Dataset has {len(data)} samples')
print('First sample keys:', 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)

***

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

{% hint style="warning" %}
**Многопроцессорные конфигурации с GPU класса 80GB не представлены на маркетплейсе Clore.ai.** Самые крупные доступные сейчас машины — это 4× RTX PRO 6000 Blackwell (по 96GB, всего 380GB) и 8–11× RTX 5090 (по 32GB). Ёмкость A100 / H200 / B200 продаётся как [голое железо](https://clore.ai/bare-metal) по запросу. Проверьте [Цены и доступность GPU](/guides/guides_v2-ru/nachalo-raboty/pricing.md) перед выбором размера развёртывания.
{% endhint %}

| Сценарий использования                       | Рекомендуемый GPU | Оценочная стоимость на Clore.ai             |
| -------------------------------------------- | ----------------- | ------------------------------------------- |
| Разработка/тестирование                      | RTX 3090 (24 ГБ)  | $0.07–0.21/гпу/ч                            |
| Дообучение (7B–13B)                          | RTX 4090 (24 ГБ)  | $0.14–0.42/гпу/ч                            |
| Крупные модели (70B+)                        | A100 80 ГБ        | [голое железо](https://clore.ai/bare-metal) |
| Многопроцессорное обучение на нескольких GPU | 2-4x A100 80GB    | [голое железо](https://clore.ai/bare-metal) |

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.