README.md

---
license: apache-2.0
language:
- ru
- en
pipeline_tag: text-to-image
library_name: diffusers
tags:
- text-to-image
- diffusion
- russian
- fine-tuned
- preview
base_model: Tongyi-MAI/Z-Image
---

<h1 align="center">🌞 Helio-Image-Preview<br><sub><sup>Русскоязычная модель генерации изображений — предварительная версия</sup></sub></h1>

<div align="center">

<img src="https://huggingface.co/HelioAI/Helio-Image-Preview/resolve/main/teaser.png" alt="Helio-Image-Preview Examples" width="800">

**Helio-Image-Preview** — первый публичный выпуск семейства Helio-Image.
Это предварительная версия модели, демонстрирующая возможности архитектуры перед полноценным релизом.

</div>

---

## � О проекте

**Helio-Image** — семейство моделей генерации изображений на базе архитектуры S3-DiT (~6B параметров), ориентированное на качественную работу с русским языком: генерация надписей на кириллице, понимание русскоязычных описаний сцен и стилей.

**Preview-версия** — это ранний доступ к модели, который показывает текущее направление разработки и уже сейчас демонстрирует впечатляющие результаты на широком спектре задач.

### 🔮 Что впереди

Полноценная модель **Helio-Image** находится в активной разработке и будет обучена на **500–800K изображений** с расширенным покрытием стилей, жанров и сценариев. Preview-версия обучена на ~110K изображений за одну эпоху и уже покрывает большинство популярных направлений генерации — от фотореализма до аниме, от игровых сцен до киберпанка.

## ✨ Возможности Preview-версии

- **Русский текст в изображениях** — генерация надписей, вывесок, логотипов на кириллице
- **Широкий спектр стилей** — фотореализм, аниме, пиксельарт, киберпанк, фэнтези, Minecraft и многое другое
- **Эталонное разрешение** — 1024×1024 (1:1), оптимизировано под квадратный формат
- **Полная совместимость** — работает через `diffusers`, поддерживает CFG, negative prompts
- **Готова к использованию** — скачал, загрузил, генерируй

### ⚡ Preview vs Полная версия

| | Helio-Image-Preview | Helio-Image (в разработке) |
|---|---|---|
| Датасет | ~110K изображений | 500–800K изображений |
| Эпохи обучения | 1 | Несколько |
| Покрытие стилей | Основные направления | Полное покрытие |
| Разрешение | 1024×1024 (1:1) | Мульти-разрешение |
| Качество русского текста | Хорошее | Улучшенное |
| Статус | ✅ Доступна | 🔧 В разработке |

> 💡 **Примечание:** Preview-версия может иногда давать неожиданные результаты в редких стилях или сложных композициях — это нормально для ранней версии с одной эпохой обучения. На популярных запросах (портреты, пейзажи, игровые сцены, аниме, текст) модель работает стабильно и выдаёт качественные результаты.

## 🚀 Быстрый старт

### Установка

```bash
pip install git+https://github.com/huggingface/diffusers
pip install torch transformers accelerate safetensors
```

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

```python
import torch
from diffusers import ZImagePipeline

# Загрузка модели
pipe = ZImagePipeline.from_pretrained(
    "./Helio-Image-Preview",  # или путь к скачанной модели
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")

# Генерация изображения
image = pipe(
    prompt="Красивый закат над Москвой с надписью РОССИЯ",
    negative_prompt="",
    height=1024,
    width=1024,
    num_inference_steps=50,
    guidance_scale=7.5,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

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

### Рекомендуемые параметры

| Параметр | Рекомендация |
|---|---|
| Разрешение | **1024×1024** (1:1, эталонное) |
| Guidance Scale | 7.5 — 9.0 |
| Inference Steps | 50 — 100 (больше = качественнее) |
| Precision | `torch.bfloat16` |

## 📝 Примеры промптов

```
Котёнок играет с клубком ниток на ковре
Киберпанк город будущего с неоновыми вывесками на русском
Minecraft деревня с табличкой ДОБРО ПОЖАЛОВАТЬ
Логотип с надписью ГЕЛИОС золотыми буквами на чёрном фоне
Космонавт на Луне с флагом и надписью КОСМОС
Фэнтези замок на вершине горы в тумане
Star Wars штурмовики маршируют с надписью ИМПЕРИЯ
Аниме школьница с зонтиком под дождём в Токио
Деревенский дом зимой с дымом из трубы
Портрет девушки в русском народном костюме
```

## 📊 Детали обучения

| Параметр | Значение |
|---|---|
| Базовая модель | Z-Image S3-DiT (~6B параметров) |
| Датасет | ~110K изображений 1024×1024 |
| GPU | 4× RTX PRO 6000 96GB |
| DeepSpeed | ZeRO-2 |
| Precision | bf16 + TF32 |
| Optimizer | 8-bit AdamW |
| Learning Rate | 1e-5 (cosine decay) |
| Effective Batch | 128 (16 × 4 GPU × 2 accum) |
| Эпохи | 1 |

## 🏗️ Структура модели

```
Helio-Image-Preview/
├── transformer/          # Файнтюнутый S3-DiT трансформер (~6B)
│   ├── config.json
│   └── diffusion_pytorch_model.safetensors
├── vae/                  # VAE декодер
├── text_encoder/         # Текстовый энкодер
├── tokenizer/            # Токенизатор
├── scheduler/            # Scheduler
├── model_index.json      # Конфигурация пайплайна
└── README.md
```

## 📜 Лицензия

Apache 2.0. Базовая архитектура: [Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) от Tongyi-MAI.

## 🙏 Благодарности

- [Tongyi-MAI](https://github.com/Tongyi-MAI) — архитектура S3-DiT и базовая модель Z-Image
- [Hugging Face Diffusers](https://github.com/huggingface/diffusers) — инфраструктура и инференс

---

<div align="center">

*Helio-Image-Preview — это только начало. Следите за обновлениями!* ☀️

</div>