Leonid Pershin
71f4e4c2e3
- Added support for a new extension, `swarm-assistent`, in `extensions.example.yaml` with a requirement for `ollama`. - Enhanced the README.md to clarify the setup process and provide a quick start guide for using extensions. - Updated documentation in `llm.md` to reflect the opt-in nature of LLM support and provide clearer instructions for enabling it. - Improved the `autocomplete.md` to detail the automatic setup of word lists during the initial launch. - Revised `cli.md` to include new commands and options related to LLM runtime handling and extension management. - Enhanced the `spike-notes.md` to guide users through the first live run with a focus on LLM integration.
180 lines
13 KiB
Markdown
180 lines
13 KiB
Markdown
# Модели
|
||
|
||
Два источника на data volume, они **складываются**, не заменяют друг друга:
|
||
|
||
1. **Civitai-seed** (ниже) — на пустой диск при bootstrap, если есть API-токен и манифест.
|
||
2. **Папка `Models/` в корне gpu-rent** — на каждом `up` выгрузить только изменившееся. `Wildcards/` и `CustomWorkflows/` — то же, см. [local-folders.md](local-folders.md).
|
||
|
||
## Быстрый старт моделей
|
||
|
||
```powershell
|
||
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`.
|
||
|
||
Локальный SwarmUI на `7801` не зеркалируем. Только дерево `./Models` приложения.
|
||
|
||
## Локальная папка → сервер
|
||
|
||
Каталог: `<корень приложения>/Models/` (или `LOCAL_MODELS_DIR`). Раскладка как у SwarmUI: `Stable-Diffusion/`, `Lora/`, `VAE/`, … Описание: [`Models/README.md`](../Models/README.md). Веса в git не коммитятся.
|
||
|
||
Правило одно:
|
||
|
||
| Локально | На `up` |
|
||
| --- | --- |
|
||
| Папки нет, или только `.gitkeep` / README | **Ничего не выгружаем**, тихий лог |
|
||
| Появился файл весов (`.safetensors` / `.ckpt` / …) | Залить его **вместе с соседней метадатой** |
|
||
| Веса уже на VM с тем же SHA256 | Пропуск (нет «обновления») |
|
||
| Веса изменились | Залить веса заново и актуальную метадату |
|
||
|
||
Метадата — файлы рядом с тем же stem: `.json`, `.civitai.json`, `.swarm.json`, превью (`.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 default, не «пустой диск без моделей».
|
||
|
||
ComfyUI в `dlbackend` качается всегда. Речь только о **модели весов** установщика SwarmUI, не о backend.
|
||
|
||
## Когда в жизненном цикле
|
||
|
||
Пока idle-killer ещё **не вооружён**:
|
||
|
||
1. Создать/примонтировать data volume, маркер FS.
|
||
2. Clone расширений из `extensions.yaml` ([extensions.md](extensions.md)).
|
||
3. Autocomplete word-list ([autocomplete.md](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.example.yaml). Рабочая копия: `models.yaml` в корне репо (или путь `MODELS_MANIFEST`).
|
||
|
||
Идентификатор — **Civitai model version id**, не имя файла и не «последняя версия модели» (она плывёт).
|
||
|
||
```yaml
|
||
# 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 два входа в **одну** базу ([анонс](https://civitai.com/articles/28369/two-front-doors-civitaicom-civitaired-and-whats-next)):
|
||
|
||
| Домен | Что видно |
|
||
| --- | --- |
|
||
| `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.
|
||
|
||
## Конфиг
|
||
|
||
```env
|
||
CIVITAI_API_TOKEN=
|
||
CIVITAI_API_HOST=civitai.red # полный каталог; civitai.com = только SFW
|
||
MODELS_MANIFEST= # пусто = <repo>/models.yaml
|
||
LOCAL_MODELS_DIR= # пусто = <корень приложения>/Models
|
||
```
|