mrleo1nid/gpu-rent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update extensions and documentation for LLM integration and CLI enhancements

Browse Source 
- 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.
This commit is contained in:
Leonid Pershin
2026-08-21 05:49:34 +03:00
parent dc1fde9e3e
commit 71f4e4c2e3
19 changed files with 713 additions and 394 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli.md
+135 -113
View File
@@ -1,144 +1,153 @@
# CLI и конфигурация
Имя команды: `gpu-rent`. Windows и Linux. Лицензия MIT, в репозитории нет секретов и имён личных чекпоинтов.
Имя команды: `gpu-rent`. Лаунчеры: `gpu-rent.bat` / `.\gpu-rent.ps1` / `./gpu-rent.sh` (создают `.venv` и вызывают `python -m gpu_rent`).
Без аргументов CLI показывает **help**. Поднять GPU с двойного клика: в `gpu-rent.vars` → `GPU_RENT_DEFAULT_ARGS=up --yes`.
---
## Типичные сценарии
### Первый раз
```text
gpu-rent doctor
gpu-rent up --yes
# … работа …
gpu-rent stop
```
Подготовка ключей: [setup.md](setup.md).
### Обычная сессия
```text
gpu-rent up --yes
# Ctrl+C → туннель off, GPU жив
gpu-rent tunnel --open
gpu-rent hold
gpu-rent stop
```
### Только облако (туннель позже)
```text
gpu-rent up --yes --no-tunnel
gpu-rent tunnel --open
```
### LLM рядом со SwarmUI
```text
gpu-rent setup # или
gpu-rent up --yes --ollama
```
Подробности: [llm.md](llm.md).
---
## Команды
| Команда | Поведение |
| --- | --- |
| `gpu-rent flavors` | Скан `SCAN_POOLS` (ru-6 multizone…) × `FLAVOR_PREFERENCE`, затем список в текущем `OS_REGION_NAME` |
| `gpu-rent doctor` | Preflight **без** create: Keystone, квота GPU, flavor в AZ, диски, Civitai token+`.red`, манифесты, SSH-ключ. Код выхода ≠ 0, если сессию нельзя начать |
| `gpu-rent setup` | Wizard: `.env`/манифесты, `LLM_RUNTIME`, пресет ollama-models, опционально local-watchdog |
| `gpu-rent up` / `up --yes` | Preflight → create/unshelve → bootstrap → git update → optional LLM → **туннель** `localhost:17801`; Ctrl+C закрывает туннель |
| `gpu-rent up --ollama` / `--llamacpp` / `--llm …` | Поднять LLM рядом со SwarmUI (см. [llm.md](llm.md)) |
| `gpu-rent up --no-update` | Без `git pull` SwarmUI и extensions (только недостающие clone) |
| `gpu-rent up --no-tunnel` | Только облако + bootstrap, без локального проброса |
| `gpu-rent up --no-spot` | Обычный (не preemptible) сервер |
| `gpu-rent up --flavor … --yes` | Без вопросов. `--flavor` бьёт список фоллбека. `--yes` без `--flavor` берёт первый доступный из `FLAVOR_PREFERENCE` |
| `gpu-rent tunnel` | Повторный SSH-проброс, если `up --no-tunnel` или туннель уже закрыли. Ctrl+C = закрыть туннель, GPU **оставить** |
| `gpu-rent tunnel --open` | Туннель + сразу открыть браузер на 17801 |
| `gpu-rent open` | Открыть браузер на `http://127.0.0.1:17801`. Туннель уже должен слушать порт |
| `gpu-rent status` | State + Nova + диск used/free + ₽/час + сколько до 24 ч preempt + killer/hold. Туннель не обязателен |
| `gpu-rent hold` | Отложить idle-killer на `IDLE_MINUTES` от сейчас |
| `gpu-rent hold --minutes 90` | Hold до now+90 мин (заменяет предыдущий, не складывает) |
| `gpu-rent hold --until <ISO>` | Hold до абсолютного времени |
| `gpu-rent hold --clear` | Снять hold |
| `gpu-rent stop` | Optional pull Output → удалить compute и FIP, диски оставить. С любой машины с `.env` |
| `gpu-rent stop --no-pull` | Не тянуть Output, даже если `PULL_OUTPUT=true` |
| `gpu-rent destroy` | `stop` + диски, только `--i-understand-data-loss` |
| `gpu-rent logs` | journalctl swarmui / cloud-init по SSH |
| `gpu-rent ssh` | Оболочка на VM |
| `gpu-rent seed-models` | Докачать новые строки манифеста Civitai на уже существующий диск |
| `gpu-rent push` | Инкремент `Models/` + `Wildcards/` + `CustomWorkflows/` (пустые skip) |
| `gpu-rent push-models` | Только `./Models` |
| `gpu-rent pull-output` | Забрать новые файлы с VM `Output/` в `./Output` (сервер не чистим) |
| `gpu-rent seed-extensions` | Доклонировать/обновить git-репы; если VM жива — `systemctl restart swarmui` |
| `gpu-rent resize-data --gb 400` | Увеличить data volume вверх (Selectel online resize). Вниз нельзя |
| `gpu-rent watchdog install` | Локальный тик (Task Scheduler / systemd user / launchd): аварийное закрытие туннеля → `stop` после grace |
| `gpu-rent watchdog uninstall` | Снять локальный сервис |
| `gpu-rent watchdog status` | Установлен ли сервис + local lease |
| `gpu-rent watchdog tick` | Один тик (для планировщика; `--dry-run` без delete) |
| `gpu-rent setup` | Wizard: манифесты, `LLM_RUNTIME`, пресет ollama-models, опционально local-watchdog |
| `gpu-rent doctor` | Preflight **без** create. Exit ≠ 0 → сессию начинать нельзя |
| `gpu-rent flavors` | Скан `SCAN_POOLS` × `FLAVOR_PREFERENCE`, список в текущем регионе |
| `gpu-rent dry-run` | План без mutating-вызовов |
| `gpu-rent up` / `up --yes` | Create/unshelve → bootstrap → optional LLM → **туннель** `:17801`. Ctrl+C = туннель off |
| `gpu-rent up -v` / `--verbose` | Полная таблица doctor на `up` (по умолчанию кратко) |
| `gpu-rent up --ollama` / `--llamacpp` / `--llm …` | LLM рядом со SwarmUI |
| `gpu-rent up --no-update` | Без `git pull` SwarmUI/extensions (только недостающие clone) |
| `gpu-rent up --no-tunnel` | Только облако |
| `gpu-rent up --no-spot` | Не preemptible |
| `gpu-rent up --flavor ID --yes` | Явный flavor; без `--flavor` + `--yes` — первый доступный из `FLAVOR_PREFERENCE` |
| `gpu-rent tunnel` / `tunnel --open` | Повторный проброс; `--open` сразу браузер. Ctrl+C GPU **не** гасит |
| `gpu-rent open` / `open --llm` | Браузер на SwarmUI / LLM-порт (туннель уже должен слушать) |
| `gpu-rent status` | State, Nova, диск, killer/hold, LLM, local-watchdog |
| `gpu-rent hold` / `--minutes N` / `--until ISO` / `--clear` | Пауза idle-killer (нужны живая VM + SSH) |
| `gpu-rent stop` / `stop --no-pull` | Удалить compute (+ FIP), диски оставить; optional pull Output |
| `gpu-rent destroy --i-understand-data-loss` | `stop` + диски |
| `gpu-rent logs` | journalctl swarmui / cloud-init |
| `gpu-rent ssh` | Оболочка на VM |
| `gpu-rent seed-models` | Докачать новые строки Civitai-манифеста на живой диск |
| `gpu-rent seed-extensions` | Доклонировать/обновить git-репы; restart swarmui |
| `gpu-rent push` / `push-models` | Локальные деревья → VM |
| `gpu-rent pull-output` | VM `Output/` → `./Output` |
| `gpu-rent resize-data --gb 400` | Data volume **только вверх** |
| `gpu-rent watchdog install` / `uninstall` / `status` / `tick` | Локальный safety-net (см. ниже) |
Второй `up` при живой VM: не создавать второй GPU; сделать autocomplete-check и **push** локальных папок; если `PULL_OUTPUT` — подтянуть Output; напомнить про `tunnel` / `stop`. `--adopt` если нашли тег без state.
Второй `up` при живой VM: не создаёт второй GPU; autocomplete-check + push локальных папок; при `PULL_OUTPUT` — подтянуть Output. `--adopt` — подхватить тег без state.
Нет команды `generate`. Нет зеркала каталога локального SwarmUI — только папки приложения, см. [local-folders.md](local-folders.md).
Нет команды `generate`. Локальный SwarmUI целиком не зеркалируем — только папки приложения ([local-folders.md](local-folders.md)).
Сейчас в коде: после seed/`start swarmui` — idle-killer, Idle backend, boot snapshot, toast/MCP-сниппет, `resize-data`. `tunnel` с Nova-watchdog: EXPIRED → unshelve + reconnect. Опционально `watchdog install` — локальный safety net. UX-полировка flavors/цен ещё впереди.
## Local watchdog
Опционально. **Idle-killer на VM** остаётся основным: ноут можно закрыть, GPU живёт до простоя. Local watchdog — если хочешь гасить GPU при «убили окно / ребут» без `stop`.
1. `gpu-rent watchdog install` (раз на машине, в корне репо).
2. Пока крутится `up`/`tunnel`, пишется heartbeat в `.gpu-rent/local-lease.json`.
3. **Ctrl+C** → detach, GPU **не** трогаем (как раньше).
4. Процесс умер / ребут → через `LOCAL_WATCHDOG_GRACE_MINUTES` (дефолт 10) тик вызывает `stop` (диски остаются).
5. `gpu-rent stop` чистит lease сам.
Без `install` поведение прежнее. Без открытого туннеля (`up --no-tunnel`) lease не вооружается — работает только VM idle-killer.
---
## `doctor`
Не создаёт сервер, не тратит GPU. Нужен до первого `up` и когда «вчера работало».
Не создаёт сервер и не тратит GPU. Нужен до первого `up` и когда «вчера работало».
Проверки по порядку, все печатаются (не падать на первой, собрать отчёт):
Проверки (все печатаются в отчёт):
1. Читается `.env`, обязательные `OS_*`.
2. Keystone: токен выдаётся.
3. Квота GPU > 0; иначе текст «напишите в поддержку Selectel».
4. В сегменте есть хотя бы один flavor из `FLAVOR_PREFERENCE` (не `disabled`).
5. Volume type сегмента существует; data 100 GB влезает в квоту дисков.
6. SSH-ключ: есть `<repo>/.gpu-rent/id_ed25519` или CLI сможет его создать.
7. Если задан `CIVITAI_API_TOKEN` — HEAD/лёгкий запрос к `CIVITAI_API_HOST` (дефолт `.red`); манифест парсится.
8. `extensions.yaml` парсится, если файл есть.
9. Локальные папки: предупреждение, если `Models/` огромный относительно свободного места на будущем диске.
1. Читается `.env`, обязательные `OS_*`
2. Keystone выдаёт токен
3. Квота GPU > 0 (иначе текст про поддержку Selectel)
4. В сегменте есть flavor из `FLAVOR_PREFERENCE`
5. Volume type / место под data ~100 GB
6. SSH-ключ есть или будет создан в `.gpu-rent/`
7. Если есть `CIVITAI_API_TOKEN` — доступ к API-хосту; манифест парсится
8. `extensions.yaml` парсится, если есть
9. Предупреждения по огромным локальным `Models/`
Exit 0 — можно `up`. Exit 1 — нельзя, причина в отчёте.
Exit 0 → можно `up`. Exit 1 → причина в таблице / кратком списке на `up`.
## `status`
---
Без туннеля. Если SSH есть — ещё диск и killer; если нет — только OpenStack.
## `status` и `hold`
| Поле | Откуда |
| --- | --- |
| Фаза state / Nova status | `state.json` + compute |
| Flavor, ₽/час | extra specs / оценка с spike; нет цены в API — «см. панель», не выдумывать |
| Preempt window | create/unshelve timestamp + 24 ч; «осталось Hh Mm» или «не preemptible» |
| Data disk used/free | SSH `df` на `/mnt/swarm_data` |
| Idle-killer | armed / grace до … / hold до … / busy (очередь или качалка) / слеп (нет кредов) |
| Туннель | слушает ли локальный 17801 |
| Snapshot boot | есть ли `gpu-rent-boot-ok` |
**status** — без туннеля. При SSH: ещё `df` диска и состояние killer; иначе только OpenStack + локальный state.
## `hold`
**hold** пишет на VM `/mnt/swarm_data/.gpu-rent-hold-until`. Killer не удаляет compute, пока `now < ts`. Без живой VM — ошибка (не «запомню на потом»). После unshelve hold на диске сохраняется.
Пишет на VM `/mnt/swarm_data/.gpu-rent-hold-until` (unix ts). Killer не удаляет compute, пока `now < ts`. Нужен SSH и живой сервер.
---
Без VM — ошибка, не «запомню на потом». После `unshelve` hold-файл на диске сохраняется.
## Local watchdog (опционально)
## Что печатать при `up`
Основной авто-stop — **idle-killer на VM** (ноут можно закрыть). Local watchdog — если хочешь гасить GPU при «убили окно / ребут» без `stop`.
1. Preflight (тот же набор, что `doctor`, можно вызвать его внутри).
2. Если квота 0 — стоп с текстом «напишите в поддержку Selectel», не traceback.
3. Выбранный flavor (или фоллбек) + оценка: GPU ₽/час, диск ₽/мес, preemptible 24 ч, idle-killer через N мин.
4. Фазы: provisioning → bootstrap → clone extensions → autocomplete → seed Civitai → push локальных папок → waiting UI → backend Idle.
5. Если `NOTIFY_READY` — Windows toast + звук (и строка в лог).
6. Готово:
1. `gpu-rent watchdog install` (раз на машине, из корня репо)
2. Пока крутится `up`/`tunnel`, пишется heartbeat `.gpu-rent/local-lease.json`
3. **Ctrl+C** → detach, GPU **не** трогаем
4. Процесс умер / ребут → через `LOCAL_WATCHDOG_GRACE_MINUTES` (дефолт 10) → `stop`
5. `gpu-rent stop` чистит lease сам
```text
SwarmUI на VM: 127.0.0.1:7801 (только через туннель)
Локально: gpu-rent tunnel
Браузер: gpu-rent open → http://127.0.0.1:17801
API: http://127.0.0.1:17801/API/
MCP: http://127.0.0.1:17801/mcp
Hold killer: gpu-rent hold
Стоп GPU: gpu-rent stop
```
Без `install` поведение прежнее. При `up --no-tunnel` lease не вооружается.
Сниппет MCP для Cursor — в stdout, `mcp.json` не редактировать.
---
## Конфигурация
| Файл | Назначение |
| --- | --- |
| `.env` | Секреты и OpenStack (`OS_*`, токены). Не в git |
| `gpu-rent.vars` | Параметры запуска / несекретные дефолты. Читают `gpu-rent.ps1` / `.sh` / `.bat` и CLI. Пример: `gpu-rent.vars.example` |
| `models.yaml` / `extensions.yaml` | Манифесты |
| `gpu-rent.vars` | Несекретные дефолты; читают лаунчеры и CLI. Пример: `gpu-rent.vars.example` |
| `models.yaml` / `extensions.yaml` / `ollama-models.yaml` | Манифесты |
`.env` в корне репозитория (рядом с `env.example`).
В `gpu-rent.vars` (создаётся из example при первом запуске):
### Лаунчер (`gpu-rent.vars`)
```env
# Двойной клик / запуск лаунчера без аргументов (CLI сам по себе показывает help):
# Двойной клик / запуск без аргументов у .ps1/.bat/.sh:
GPU_RENT_DEFAULT_ARGS=up --yes
# Дописать ко всем вызовам:
# GPU_RENT_EXTRA_ARGS=--no-update
UPDATE_GIT=true
LLM_RUNTIME=none
```
### Основные переменные (`.env` / vars)
```env
OS_AUTH_URL=https://cloud.api.selcloud.ru/identity/v3
OS_USER_DOMAIN_NAME=
@@ -150,6 +159,8 @@ GPU_RENT_AZ=ru-7a
SSH_PRIVATE_KEY_PATH=
SSH_USER=ubuntu
# Пусто = авто /32 твоего IP. Для spike/WARP иногда 0.0.0.0/0:
GPU_RENT_SSH_CIDR=
BOOT_VOLUME_ID=
DATA_VOLUME_ID=
@@ -167,46 +178,57 @@ EXTENSIONS_MANIFEST=
GIT_TOKEN=
AUTOCOMPLETE_ENABLED=true
AUTOCOMPLETE_GITHUB_REPO=DominikDoom/a1111-sd-webui-tagcomplete
AUTOCOMPLETE_GITHUB_PATH=tags/danbooru.csv
AUTOCOMPLETE_GITHUB_REF=main
AUTOCOMPLETE_FILENAME=danbooru.csv
SWARMUI_LOCAL_PORT=17801
LLM_RUNTIME=none
OLLAMA_LOCAL_PORT=17811
LLAMACPP_LOCAL_PORT=17812
UPDATE_GIT=true
DEFAULT_FLAVOR_ID=
FLAVOR_PREFERENCE=4090-24,4090-48,a5000,a100-40
FLAVOR_FALLBACK=true
SCAN_POOLS=ru-6,ru-7
DEFAULT_SPOT=true
KEEP_FLOATING_IP=false
IDLE_MINUTES=30
IDLE_GRACE_MINUTES=45
# LOCAL_WATCHDOG_GRACE_MINUTES=10
PULL_OUTPUT=false
NOTIFY_READY=true
```
Flavor id в git не хардкодить. `FLAVOR_PREFERENCE` — ярлыки; реальные uuid резолвятся в сегменте. `FLAVOR_FALLBACK=false` — только `DEFAULT_FLAVOR_ID` / `--flavor`, без следующего в списке.
Flavor uuid в git не хардкодить. `FLAVOR_FALLBACK=false` — только `DEFAULT_FLAVOR_ID` / `--flavor`.
Application credential для idle-killer CLI создаёт при bootstrap и кладёт на VM; в `.env` ноутбука его можно не дублировать.
Application credential для idle-killer CLI создаёт на `up` (узко: DELETE/GET **этого** server) и отзывает на `stop`. В `.env` ноутбука дублировать не нужно.
Пути локальных папок по умолчанию — каталоги в корне приложения: `Models/`, `Wildcards/`, `CustomWorkflows/`, `Output/`.
Пути локальных папок по умолчанию: `Models/`, `Wildcards/`, `CustomWorkflows/`, `Output/` в корне репо.
Полный шаблон: [`env.example`](../env.example).
---
## State
`<repo>/.gpu-rent/state.json` — ids, фаза (`idle` / `ready_cloud` / `ready_tunneled` / …), flavor, timestamps create/unshelve (для окна 24 ч). Без паролей. Lockfile там же, чтобы два `up` не создали два сервера.
`<repo>/.gpu-rent/state.json` — ids, фаза, timestamps (окно preempt 24 ч). Без паролей. Lockfile рядом — два `up` не создадут два сервера.
---
## Ожидание готовности
Потолок ~20–40 мин на первый bootstrap, ~5–10 мин на unshelve:
Ориентир: **~20–40 мин** первый bootstrap, **~5–10 мин** unshelve.
Порядок готовности:
1. Nova `ACTIVE`
2. TCP 22
3. SSH: cloud-init или `systemctl is-active swarmui`
4. HTTP `http://127.0.0.1:7801` **на VM** (через SSH), не путать с локальным 7801
5. Для MCP/API / toast — дождаться Idle backend.
2. TCP 22 / SSH
3. HTTP `http://127.0.0.1:7801` **на VM** (через SSH)
4. Backend Idle → toast (если `NOTIFY_READY`) + access-card
## Windows
Локальный порт UI: **17801** (на VM по-прежнему 7801 на loopback).
Лаунчеры в корне: `gpu-rent.bat` (cmd / двойной клик), `.\gpu-rent.ps1` (PowerShell). На Unix — `./gpu-rent.sh`. Они создают `.venv` в репозитории и вызывают `python -m gpu_rent`. Ключ генерирует CLI: `<repo>/.gpu-rent/id_ed25519`.
---
`NOTIFY_READY`: toast через WinRT / `win10toast` (что заработает на 10/11 без админ-прав) + системный звук. Если toast недоступен — только звук и лог, не падать.
## Windows / notify
`NOTIFY_READY`: toast + системный звук, когда backend Idle. Если toast недоступен — только звук и лог, без падения CLI.