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

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

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

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), если она не установлена, и применит к ней наш адаптер.

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 (Умная настройка)

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

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 генерация (Пакетная)

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")

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

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

# Больше шагов = выше детализация
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), включите выгрузку слоев на процессор:

pipe.enable_model_cpu_offload()

Артефакты на изображении

Попробуйте уменьшить scale до 0.3-0.4.
Увеличьте num_inference_steps до 10-12.

Текст генерируется с ошибками

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