gpu-rent/docs/models.md

Модели

Два источника на data volume, они складываются, не заменяют друг друга:

1. Civitai-seed (ниже) — на пустой диск при bootstrap, если есть API-токен и манифест.
2. Папка Models/ в корне gpu-rent — на каждом up выгрузить только изменившееся. Wildcards/ и CustomWorkflows/ — то же, см. local-folders.md.

Быстрый старт моделей

copy models.example.yaml models.yaml
# правь URL с modelVersionId=…
# в .env: CIVITAI_API_TOKEN=…
.\gpu-rent.ps1 up --yes

Или положи веса в Models/Stable-Diffusion/ (и т.п.) — уедут на up / gpu-rent push-models.

Capture с VM (ссылки only)

Если на облачном диске уже есть модели (seed, UI Civitai, ручная заливка) — записать их обратно в локальный манифест без скачивания весов:

.\gpu-rent.ps1 capture models          # merge Civitai url → models.yaml
.\gpu-rent.ps1 capture models --kind lora
.\gpu-rent.ps1 capture wanted          # только очередь Assistent Cards → models.yaml
.\gpu-rent.ps1 capture --dry-run       # models + extensions, без записи
.\gpu-rent.ps1 capture all

Берёт {stem}.civitai.json или SHA256 → Civitai by-hash. Также мержит очередь Assistent /mnt/swarm_data/.gpu-rent-wanted-models.yaml (модели, добавленные из вкладки Cards / Enqueue wanted) — на capture models|wanted|all и перед seed-models / up. Дубли modelVersionId не дублируются. Перед записью — models.yaml.bak. Неизвестные файлы (нет в Civitai) — только в отчёте.

Локальный SwarmUI на 7801 не зеркалируем. Только дерево ./Models приложения.

Локальная папка → сервер

Каталог: <корень приложения>/Models/ (или LOCAL_MODELS_DIR). Раскладка как у SwarmUI: Stable-Diffusion/, Lora/, VAE/, … Описание: Models/README.md. Веса в git не коммитятся.

Правило одно:

Локально	На up
Папки нет, или только .gitkeep / README	Ничего не выгружаем, тихий лог
Появился файл весов (.safetensors / .ckpt / …)	Залить его вместе с соседней метадатой
Веса уже на VM с тем же SHA256	Пропуск (нет «обновления»)
Веса изменились	Залить веса заново и актуальную метадату

Метадата — файлы рядом с тем же stem: .json, .civitai.json, .swarm.json, .assistent.json (карточки рекомендаций Assistent), превью (.preview.png / .png / .webp), если лежат в той же папке. Веса без sidecar тоже можно залить (предупреждение в лог: «метадаты нет»). Метадату без весов не шлём отдельно.

С диска в облаке ничего не удаляем. Civitai-seed и то, чего нет в ./Models, остаётся.

Технически: SHA256 локального файла vs тот же относительный путь под /mnt/swarm_data/Models/. SFTP/paramiko, resume .partial. Preflight свободного места. Если залили и SwarmUI уже жив — refresh списка моделей.

Повторный up при живой VM тоже смотрит папку (положил новую LoRA дома → следующий up её увезёт). Явно: gpu-rent push-models или gpu-rent push (все локальные деревья).

Пока идёт аплоад, idle-killer на паузе.

---

Civitai: первый seed

Срабатывает один раз: пустой data-диск + первый инстанс. Повторный up к уже засеянному диску строки манифеста с совпавшим SHA256 пропускает.

Две ветки

Условие	Что происходит
В .env есть CIVITAI_API_TOKEN и в манифесте есть хотя бы одна запись	Скачать перечисленные модели с Civitai на VM (не через ноут). Рядом положить метаданные. Не качать дефолтный чекпоинт установщика SwarmUI
Токена нет, или манифест пуст/отсутствует	Обычный первый запуск SwarmUI: пусть ставит свою стандартную модель. В лог — почему Civitai-seed пропущен

После старта SwarmUI тот же CIVITAI_API_TOKEN прокидывается в UI через /API/SetAPIKey (civitai_api) — Model Downloader и gated-модели в браузере. При наличии HF_TOKEN / HUGGING_FACE_HUB_TOKEN — ещё huggingface_api.

Токен без манифеста = предупреждение и ветка SwarmUI default, не «пустой диск без моделей».

ComfyUI в dlbackend качается всегда. Речь только о модели весов установщика SwarmUI, не о backend.

Когда в жизненном цикле

Пока idle-killer ещё не вооружён:

1. Создать/примонтировать data volume, маркер FS.
2. Clone расширений из extensions.yaml (extensions.md).
3. Autocomplete word-list (autocomplete.md): скачать, если нет; иначе проверить GitHub sha.
4. Если ветка Civitai: залить на VM манифест (scp, не cloud-init — токен не должен светиться в Nova user_data).
5. Скачать файлы в /mnt/swarm_data/Models/…, проверить SHA256, записать sidecar.
6. Маркер /mnt/swarm_data/.gpu-rent-models-seeded.
7. Push из корневой Models/ приложения (новые/изменённые, см. выше).
8. Первый старт SwarmUI (папки чекпоинтов уже не пустые → установщик не предлагает свой SD; Extensions и Autocompletions уже на месте).
9. Ждать backend Idle, затем вооружить idle-killer.

Качание нескольких GB легко длиннее льготы 45 минут. Поэтому killer не живёт, пока не закончился seed.

Позже тот же код: gpu-rent seed-models — докачать новые строки манифеста на уже живой диск (идемпотентно).

Манифест

Пример в репозитории: models.example.yaml. Рабочая копия: models.yaml в корне репо (или путь MODELS_MANIFEST).

Идентификатор — Civitai model version id, не имя файла и не «последняя версия модели» (она плывёт).

# models.yaml — пример: Krea 2 + LoRA (см. models.example.yaml)
checkpoint:
  - url: https://civitai.red/models/2786499/realism-by-stable-yogi-krea2?modelVersionId=3231611
lora:
  - url: https://civitai.red/models/2268008/realistic-snapshot-z-image-turbo-krea-2?modelVersionId=3084537
  - url: https://civitai.red/models/2187487/cutifyier?modelVersionId=3107521
  - url: https://civitai.red/models/1134895/2000s-analog-core?modelVersionId=3103914

Допустимо вместо url поле version_id (число из modelVersionId=). Хосты civitai.com, civitai.red, civitai.green равнозначны (зелёный редиректит на .com). Несколько файлов у версии: берём files[] с "primary": true, иначе SafeTensor / fp16.

Типы манифеста → каталоги SwarmUI (ModelRoot = Models):

Ключ yaml	Civitai model.type (ориентир)	Каталог на диске
checkpoint	Checkpoint	Models/Stable-Diffusion
lora	LORA, LoCon, DoRA	Models/Lora
vae	VAE	Models/VAE
embedding	TextualInversion	Models/Embeddings
controlnet	Controlnet	Models/controlnet
upscaler	Upscaler	Models/upscale_models
clip	—	Models/clip

Тип в yaml задаёт куда класть, даже если Civitai назвал иначе. Если API-тип совсем другой — предупреждение, кладём по yaml.

В git не коммитить рабочий манифест с личными чекпоинтами. В models.example.yaml — стартовый набор Krea 2 (чекпоинт + три LoRA); скопируй и дополни под себя.

Civitai API (.com / .red)

С апреля 2026 у Civitai два входа в одну базу (анонс):

Домен	Что видно
civitai.com	SFW / PG (бывший green). NSFW-карточки с этого хоста часто не находятся (404) или без files[]
civitai.red	Полный каталог, включая NSFW
civitai.green	301 на .com

REST не раздвоился: те же /api/v1/... на обоих хостах, один аккаунт, один API-токен. Официальная дока по-прежнему пишет base https://civitai.com/api/v1/, но там же: ответы с «зелёного» домена и из части регионов молча режутся до SFW. Нам нужны любые version_id из манифеста → дефолтный API-хост civitai.red.

Клиент:

1. Доверять только civitai.com, civitai.red и их поддоменам. Токен на чужой хост (CDN после редиректа) не отправлять.
2. URL из yaml нормализовать: вытащить modelVersionId / /models/{id}?modelVersionId= с любого из трёх доменов.
3. Метаданные: GET https://{CIVITAI_API_HOST}/api/v1/model-versions/{id} с Authorization: Bearer.
4. Если 404, пустой files[] или нет downloadUrl — один повтор на второй хост (.red ↔ .com). Не крутить бесконечно.
5. Качать: GET https://{хост_успешного_GET}/api/download/models/{id} с Bearer, следовать редиректам на presigned S3. Имя — Content-Disposition. downloadUrl в JSON часто указывает на .com — для NSFW его переписать на хост, который отдал файлы.
6. Поле nsfwLevel / model.nsfw в sidecar сохранить как есть, фильтром не пользоваться.

Без токена скачивание часто 401 даже на публичные веса. requireAuth: true в mini-endpoint — токен обязателен.

После ответа version:

1. Primary file, hashes.SHA256, sizeKB.
2. Preflight места: сумма sizeKB × 1.2 < свободно на data volume.
3. Качать на VM. Прогресс в логах.
4. Сверить SHA256. Несовпадение — удалить файл, fail строки.

Рядом с весами:

Файл	Содержимое
{name}.safetensors	веса
{name}.civitai.json	сырой JSON version (+ при желании GET /models/{modelId} для автора/тегов)
{name}.swarm.json	маппинг под SwarmUI: name, title, description, trigger_phrase из trainedWords, author, license, tags

Превью-картинки в base64 не обязательны в v1 (раздувают json). SwarmUI подтянет превью сам, если умеет по civitai id.

Не класть API-токен в sidecar и не в Output.

Пропуск дефолта SwarmUI

Когда seed успешен (есть хотя бы один checkpoint или пользователь явно согласен на «только LoRA»):

• первый старт SwarmUI — после появления файлов в Models/;
• на spike проверить: установщик не качает Z-Image / SDXL Base, если Stable-Diffusion не пуст;
• если всё же качает — выключить автозагрузку настройкой/LaunchArg (имя ключа зафиксировать на spike, не выдумывать сейчас).

Если в манифесте нет ни одного checkpoint — предупреждение «без базовой модели генерация может не стартовать», не жёсткий fail.

Сбой

• 401 → «токен неверный или скачивание требует логина».
• 404 на обоих хостах → версии нет / снята / не published.
• Early access / 403 → строка fail, остальные можно продолжить; маркер seeded не ставить.
• Обрыв сети — resume по .partial + повтор SHA256.

Конфиг

CIVITAI_API_TOKEN=
CIVITAI_API_HOST=civitai.red   # полный каталог; civitai.com = только SFW
HF_TOKEN=                      # или HUGGING_FACE_HUB_TOKEN — HF GGUF / gated / capture fallback
MODELS_MANIFEST=   # пусто = <repo>/models.yaml
LOCAL_MODELS_DIR=  # пусто = <корень приложения>/Models

Hugging Face (резерв)

• Скачивание: HF_TOKEN в .env → строки models.yaml с huggingface.co/…/resolve/….
• Capture: если Civitai by-hash не нашёл файл → поиск на Hub по имени + LFS sha256 → URL в манифест.
• SwarmUI: тот же токен прокидывается как huggingface_api (Model Downloader).
• Abliterated / gated репозитории без токена почти всегда дают 401.