USAGE.md

# Helio-Ray-LoRA (v0.1 Experimental) — Руководство

Этот документ описывает, как использовать экспериментальный LoRA-адаптер Helio-Ray поверх базовой модели Z-Image.

## Установка зависимостей

```bash
pip install torch>=2.0.0
pip install diffusers>=0.30.0
pip install peft>=0.13.0
pip install transformers>=4.45.0
pip install accelerate safetensors
```

## Базовая генерация

Скрипт автоматически скачает базовую модель (Z-Image-Turbo), если она не установлена, и применит к ней наш адаптер.

```python
import torch
from diffusers import DiffusionPipeline
from peft import PeftModel

# 1. Загрузка базовой модели (Z-Image)
# При первом запуске скачается ~10 ГБ
pipe = DiffusionPipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.float16, # Используйте float16 для экономии памяти
    trust_remote_code=True
)
pipe.to("cuda")

# 2. Применение адаптера Helio-Ray
# Загружается с Hugging Face (всего ~300 МБ)
pipe.transformer = PeftModel.from_pretrained(
    pipe.transformer,
    "HelioAI/Helio-Ray-LoRA-v0.1", # Убедитесь, что имя репозитория совпадает
    is_trainable=False
)

# 3. Функция установки силы влияния (Scale)
def set_lora_scale(scale):
    for module in pipe.transformer.modules():
        if hasattr(module, "scaling"):
            for key in module.scaling:
                module.scaling[key] = scale

# Рекомендуемое значение: 0.5 - 0.7
set_lora_scale(0.5)

# 4. Генерация (Строго 1024x1024)
image = pipe(
    prompt="Реалистичное фото, вывеска магазина с надписью 'ПРОДУКТЫ', вечер, 8k",
    height=1024,
    width=1024,
    num_inference_steps=8, # Turbo-режим (быстро)
    guidance_scale=0.0
).images[0]

image.save("output.png")
```

## Адаптивный scale (Умная настройка)

Адаптер лучше всего работает с реализмом. Для пиксель-арта или стилизации рекомендуется снижать влияние адаптера.

```python
def get_optimal_scale(prompt):
    """Автоматический выбор scale в зависимости от промпта"""
    stylized_keywords = ['майнкрафт', 'пиксел', 'anime', 'мультфильм', '8-bit']
    
    prompt_lower = prompt.lower()
    for keyword in stylized_keywords:
        if keyword in prompt_lower:
            return 0.3 # Слабое влияние для стилизации
    
    return 0.5 # Стандартное влияние для фотореализма и текста

# Использование
prompt = "Картинка в стиле майнкрафта"
scale = get_optimal_scale(prompt)
set_lora_scale(scale)
```

## Batch генерация (Пакетная)

```python
prompts = [
    "Кружка с надписью 'КОФЕ' на столе",
    "Вывеска 'АПТЕКА' на здании",
    "Книга с заголовком 'ИСТОРИЯ' крупным планом"
]

for i, prompt in enumerate(prompts):
    image = pipe(
        prompt, 
        height=1024, 
        width=1024, 
        num_inference_steps=8, 
        guidance_scale=0.0
    ).images[0]
    
    image.save(f"output_{i}.png")
```

## Настройка качества

Если результат кажется "мыльным", можно увеличить количество шагов, но это замедлит генерацию.

```python
# Больше шагов = выше детализация
image = pipe(
    prompt="...",
    num_inference_steps=12,  # Стандарт: 8. Максимум: 15-20.
    height=1024,
    width=1024
).images[0]
```

## Системные требования

Хотя сам адаптер весит мало, для запуска всей цепочки (Base + Adapter) требуется GPU.

- **VRAM:** Минимум 12-16 GB (для комфортной работы).
- **RAM:** 16 GB+.
- **Python:** 3.10+.

## Troubleshooting (Решение проблем)

### OOM (Ошибка нехватки памяти)
Если видеокарта слабая (менее 12 ГБ VRAM), включите выгрузку слоев на процессор:
```python
pipe.enable_model_cpu_offload()
```

### Артефакты на изображении
- Попробуйте уменьшить scale до **0.3-0.4**.
- Увеличьте `num_inference_steps` до **10-12**.

### Текст генерируется с ошибками
- Убедитесь, что scale установлен на **0.5** или **0.6**.
- Пишите желаемый текст в промпте **в одинарных кавычках** (например: `'МАГАЗИН'`).
- Добавьте описание стиля текста (например: "крупный шрифт, четкие буквы").
```