# Stable Diffusion 3.5

Stable Diffusion 3.5 от Stability AI — это мультимодальный диффузионный трансформер (MMDiT), который устанавливает новый стандарт для генерации изображений с открытыми весами. Он доступен в трех вариантах: **Large** (8B параметров), **Средне** (2.5B параметров), и **Large Turbo** (8B, дистиллированный для вывода в 4 шага). Главная особенность — точное отображение текста: SD 3.5 надежно помещает читаемый текст в сгенерированные изображения, с чем многим предыдущим моделям было сложно справиться.

На [Clore.ai](https://clore.ai/) вы можете арендовать GPU для SD 3.5 всего за $0.30/день и генерировать сотни изображений в час.

## Ключевые особенности

* **Три варианта** — Large (8B, наивысшее качество), Medium (2.5B, быстро и легковесно), Large Turbo (8B, дистилляция для 4 шагов).
* **Точное отображение текста** — генерирует читаемый текст, вывески, надписи и типографику внутри изображений.
* **Архитектура MMDiT** — совместное внимание к изображению и тексту для лучшего соответствия промпту.
* **Нативное разрешение 1024×1024** — чистый вывод без хитростей с апскейлом.
* **Гибкие соотношения сторон** — обрабатывает не-квадратные выходы (768×1344, 1344×768 и т.д.) без потери качества.
* **Нативная поддержка diffusers** — `StableDiffusion3Pipeline` в `diffusers >= 0.30`.
* **Открытые веса** — Лицензия сообщества Stability AI; бесплатно для большинства коммерческих применений.

## Требования

| Компонент            | Минимум        | Рекомендуется         |
| -------------------- | -------------- | --------------------- |
| VRAM GPU             | 12 GB (Medium) | 24 GB (Large / Turbo) |
| ОЗУ системы          | 16 ГБ          | 32 ГБ                 |
| Диск                 | 20 ГБ          | 40 ГБ                 |
| Python               | 3.10+          | 3.11                  |
| CUDA                 | 12.1+          | 12.4                  |
| поддержкой diffusers | 0.30+          | latest                |

**Рекомендация Clore.ai по GPU:** Один **RTX 4090** (24 GB, \~$0.5–2/день) обеспечивает запуск всех трех вариантов на полной скорости. Для модели Medium **RTX 3090** (24 GB, \~$0.3–1/день) или даже карта на 16 GB достаточна и дешевле.

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

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece protobuf

python -c "import torch; print(torch.cuda.get_device_name(0))"
```

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

### SD 3.5 Large — Максимальное качество

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")

image = pipe(
    prompt=(
        "Потертая деревянная вывеска с надписью 'OPEN 24 HOURS', свисающая с "
        "ржавой цепи перед неоновой закусочной, дождливая ночь, отражения "
        "на мокром асфальте, кинематографичная фотография"
    ),
    negative_prompt="размытый, деформированный текст, низкое качество",
    guidance_scale=3.5,
    num_inference_steps=28,
    width=1024,
    height=1024,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("diner_sign.png")
print("Сохранено diner_sign.png")
```

### SD 3.5 Large Turbo — Быстрая генерация в 4 шага

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large-turbo",
    torch_dtype=torch.bfloat16,
).to("cuda")

# Вариант Turbo: требуется лишь 4 шага, guidance_scale=0 (дистиллированный)
image = pipe(
    prompt="Макрофото механизма часов, сложные шестерни, золотой свет",
    guidance_scale=0.0,
    num_inference_steps=4,
    width=1024,
    height=1024,
).images[0]

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

### SD 3.5 Medium — Легковесный вариант

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-medium",
    torch_dtype=torch.float16,
).to("cuda")

image = pipe(
    prompt="Изометрический вид уютного интерьера кофейни, стиль пиксель-арт, теплое освещение",
    guidance_scale=4.0,
    num_inference_steps=28,
    width=1024,
    height=1024,
).images[0]

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

### Пакетная генерация с разными соотношениями сторон

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    torch_dtype=torch.bfloat16,
).to("cuda")

jobs = [
    {"prompt": "Портрет астронавта в поле подсолнухов", "w": 768, "h": 1344},
    {"prompt": "Панорамный пейзаж высокогорий Исландии, мрачное небо", "w": 1344, "h": 768},
    {"prompt": "Товарное фото флакона духов на мраморной поверхности", "w": 1024, "h": 1024},
]

for i, job in enumerate(jobs):
    img = pipe(
        prompt=job["prompt"],
        guidance_scale=3.5,
        num_inference_steps=28,
        width=job["w"],
        height=job["h"],
    ).images[0]
    img.save(f"batch_{i:03d}.png")
    print(f"[{i+1}/{len(jobs)}] {job['w']}x{job['h']} выполнено")
```

## Советы для пользователей Clore.ai

1. **Turbo для итераций, Large для финалов** — используйте 4-шаговый Turbo для быстрого исследования идей промптов, затем переключайтесь на Large (28 шагов) для финального рендера.
2. **guidance\_scale=3.5** — SD 3.5 Large лучше работает при более низком CFG, чем старые модели Stable Diffusion. Значения выше 5.0 часто приводят к перенасыщению.
3. **Turbo требует guidance\_scale=0** — дистиллированная модель уже содержит руководство внутри; добавление большего ухудшает качество.
4. **Текст в изображениях** — отображение текста в SD 3.5 сильное, но не идеальное. Используйте кавычки вокруг точного текста, который хотите получить: `'OPEN 24 HOURS'`. Держите текст коротким (макс. 3–5 слов).
5. **Кеширование весов** — установите `HF_HOME=/workspace/hf_cache` на постоянном хранилище. Large занимает \~16 GB на диске.
6. **bf16 для Large, fp16 для Medium** — модели 8B обучались в bf16; 2.5B Medium хорошо работает в fp16.
7. **Эффективная пакетная обработка** — SD 3.5 Large генерирует одно изображение 1024×1024 примерно за 3 секунды на RTX 4090. Пакетируйте на ночь для массовой генерации.
8. **Принять лицензию HF** — вы должны принять лицензию модели на странице HuggingFace перед загрузкой. Выполните вход с `huggingface-cli login`.

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

| Проблема                         | Исправить                                                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `OutOfMemoryError` с Large       | Используйте `pipe.enable_model_cpu_offload()`; или переключитесь на вариант Medium                                       |
| Искаженный текст на изображении  | Держите текст коротким (3–5 слов); помещайте его в кавычки в промпте; увеличьте `num_inference_steps` до 35              |
| Перенасыщенные цвета             | Понизьте `guidance_scale` — попробуйте 2.5–3.5 для Large; используйте 0.0 для Turbo                                      |
| Ошибка 403 при скачивании модели | Примите лицензию на `https://huggingface.co/stabilityai/stable-diffusion-3.5-large` и выполните `huggingface-cli login`  |
| Медленный первый запуск          | Первичная загрузка для Large занимает \~16 GB; последующие запуски используют кеш                                        |
| `KeyError: 'text_encoder_3'`     | Обновите diffusers: `pip install -U diffusers transformers`                                                              |
| Черный вывод изображения         | Убедитесь, что `torch_dtype=torch.bfloat16` для Large/Turbo; fp32 может вызывать скрытые ошибки на некоторых видеокартах |