Update extensions and documentation for LLM integration and CLI enhancements

- 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.
2026-08-21 05:49:34 +03:00
parent dc1fde9e3e
commit 71f4e4c2e3
19 changed files with 713 additions and 394 deletions
@@ -1,20 +1,38 @@
-# Что сделать до первого `gpu-rent up`
+# Подготовка до первого `up`

-Код **не создаёт GPU**, пока не пройден `gpu-rent doctor`. Сначала доступ в облако, квота GPU и ключи. Статический ключ панели **`X-Token` для этого CLI не подходит** — им нельзя управлять серверами и дисками.
+Цель: зелёный `doctor` → первый `up --yes` → UI на `http://127.0.0.1:17801` → `stop`.

-Панель: [my.selectel.ru](https://my.selectel.ru).
+Панель Selectel: [my.selectel.ru](https://my.selectel.ru).
+
+**Важно:** ключ панели **`X-Token` не подходит**. Нужен сервисный пользователь + пароль (OpenStack Keystone). CLI сам получает токен на ~24 ч; в `.env` токен хранить не надо.

 ---

-## 1. Python
+## Карта шагов
+
+| # | Что сделать | Готово, когда |
+| --- | --- | --- |
+| 1 | Python 3.11+ и лаунчер | `.\gpu-rent.ps1 --help` печатает help |
+| 2 | Проект + квота GPU > 0 | в панели лимит GPU ≥ 1 |
+| 3 | Сервисный пользователь + `.env` | заполнены `OS_*` и `GPU_RENT_AZ` |
+| 4 | (Опц.) Civitai + `models.yaml` | токен в `.env`, манифест с `modelVersionId` |
+| 5 | (Опц.) `extensions.yaml` / Git | публичные репы без токена |
+| 6 | `doctor` | exit 0 |
+| 7 | Первый `up --yes` | браузер / :17801 |
+| 8 | `stop` | compute удалён, диски на месте |
+
+SSH-ключ руками не нужен — CLI создаст `.gpu-rent/id_ed25519` при первом `up`.
+
+---
+
+## 1. Python и лаунчер

 Нужен **Python 3.11+**. На Windows при установке включи «Add python.exe to PATH».

-В корне репозитория достаточно лаунчера — venv и `pip install` он сделает сам:
+В корне репозитория:

 ```powershell
 .\gpu-rent.ps1 --help
-.\gpu-rent.ps1 doctor
 ```

 ```bat
@@ -26,11 +44,24 @@ chmod +x gpu-rent.sh
 ./gpu-rent.sh --help
 ```

-Первый запуск копирует `env.example` → `.env`, `models.example.yaml` → `models.yaml`, `extensions.example.yaml` → `extensions.yaml` в **корне репозитория**, если файлов ещё нет. Заполни `OS_*` в `.env` (шаги ниже). После `git pull`, если изменился `pyproject.toml`, лаунчер переустановит пакет.
+Лаунчер сам создаёт `.venv` и ставит пакет. Первый запуск копирует шаблоны **в корень репо**, если файлов нет:

-Секреты и runtime не уезжают в `%USERPROFILE%`: только `<repo>/.env` и `<repo>/.gpu-rent/` (state, SSH-ключ). Оба в `.gitignore`. Если раньше лежало в `~\.gpu-rent\`, CLI один раз перенесёт в проект.
+- `env.example` → `.env`
+- `models.example.yaml` → `models.yaml`
+- `extensions.example.yaml` → `extensions.yaml`
+- `gpu-rent.vars.example` → `gpu-rent.vars`

-Ручной венв по желанию (для разработки / pytest):
+Секреты только в `<repo>/.env` и runtime в `<repo>/.gpu-rent/` (оба в `.gitignore`).
+
+Опционально wizard (после того как `.env` хотя бы частично заполнен):
+
+```powershell
+.\gpu-rent.ps1 setup
+```
+
+Спросит LLM (none/ollama/llamacpp) и local-watchdog. Можно пропустить и настроить позже.
+
+Для разработки / pytest:

 ```powershell
 python -m venv .venv
@@ -44,171 +75,194 @@ python -m gpu_rent --help

 ## 2. Selectel: проект и квота GPU

-На новых аккаунтах лимит GPU почти всегда **0**. Без тикета в поддержку `up` создать карту не сможет — это норма, не баг CLI.
+На новых аккаунтах лимит GPU часто **0**. Без поднятия лимита `up` не создаст сервер — это нормально, не баг CLI.

 ### 2.1. Проект

-1. Панель → сверху **IAM** → **Projects** (Проекты).
-2. Отдельный проект, например `gpu-rent`. Не клади GPU в общий «мусорный» проект.
-3. Скопируй **ID проекта** (uuid). Он же `OS_PROJECT_ID`.
-4. **Номер аккаунта** — в правом верхнем углу панели. Он же `OS_USER_DOMAIN_NAME` (domain в Keystone).
+1. Панель → **IAM** → **Projects** (Проекты).
+2. Отдельный проект, например `gpu-rent` (не общий «мусорный»).
+3. Скопируй **ID проекта** (uuid) → это `OS_PROJECT_ID`.
+4. **Номер аккаунта** (правый верхний угол) → это `OS_USER_DOMAIN_NAME`.

 ### 2.2. Есть ли GPU в квоте

-1. **IAM** → **Projects** → твой проект → вкладка **Quotas and limits** / **Квоты и лимиты** → **Cloud platform**.
-2. Выбери пул и сегмент, где есть GPU (матрица: [GPU availability](https://docs.selectel.ru/en/cloud-servers/create/gpus/)). Для Москвы смотри **мультизональный `ru-6`** (`ru-6a`/`ru-6b`/`ru-6c`) и `ru-7`. CLI сам сканит `SCAN_POOLS` в `gpu-rent flavors` и подскажет `OS_REGION_NAME` / `GPU_RENT_AZ`.
-3. Строка **GPU** (и при необходимости vCPU/RAM/network volumes). Если лимит 0 — дальше тикет.
+1. **IAM** → **Projects** → твой проект → **Quotas and limits** / **Квоты** → **Cloud platform**.
+2. Пул и сегмент с GPU: матрица [GPU availability](https://docs.selectel.ru/en/cloud-servers/create/gpus/). Часто смотрят мультизональный `ru-6` и `ru-7`.
+3. Строка **GPU**. Если лимит 0 — тикет (ниже).

-Квоту внутри уже выданного лимита можно крутить в панели. **Сам лимит GPU поднимает только поддержка.**
+Лимит GPU поднимает **только поддержка**. Внутри уже выданного лимита квоту можно крутить в панели.
+
+Подсказка по пулу после появления ключей: `.\gpu-rent.ps1 flavors` (скан `SCAN_POOLS`).

 ### 2.3. Тикет в поддержку

-**Тикеты** в панели (не email вслепую). Лимит увеличивают **на один конкретный проект**.
-
-Текст можно почти копировать:
+**Тикеты** в панели. Лимит увеличивают **на один конкретный проект**.

 ```text
 Прошу увеличить лимит GPU в облачной платформе.

 Проект: <имя> (ID: <uuid проекта>)
 Пул / сегмент: ru-7 / ru-7a   ← подставь свой из матрицы GPU
-Нужно: 1× NVIDIA RTX 4090 24 GB (если нет — ближайший аналог в этом сегменте: 4090 48 GB или A5000).
-Цель: один прерываемый (preemptible) облачный сервер для персональных сессий генерации, диски сетевые.
+Нужно: 1× NVIDIA RTX 4090 24 GB (если нет — ближайший аналог: 4090 48 GB или A5000).
+Цель: один прерываемый (preemptible) облачный сервер для персональных сессий, диски сетевые.

 Сейчас квота/лимит GPU = 0, создать сервер с GPU нельзя.
 ```

-Пока тикет не закрыт, ставишь CLI и гоняешь `doctor` — он как раз покажет «квота 0, напишите в поддержку».
+Пока тикет открыт, можно уже заполнять `.env` и гонять `doctor` — он покажет «квота 0».

 ---

-## 3. Ключи OpenStack (это и есть «API key» для gpu-rent)
+## 3. Ключи OpenStack

-Нужен **сервисный пользователь** + пароль. CLI сам получает IAM-токен на 24 часа (`X-Auth-Token`). В `.env` токен хранить не надо.
-
-**Не используй:** Профиль → Access → API Keys → `X-Token`. Это статический ключ панели, OpenStack (серверы/диски/сети) он **не** двигает.
+Нужен **сервисный пользователь** + пароль. Не используй: Профиль → Access → API Keys → `X-Token`.

 ### 3.1. Сервисный пользователь

-Только владелец аккаунта или роль `iam.admin`. На балансе для роли `member` должно быть хотя бы **100 ₽**.
+Только владелец аккаунта или `iam.admin`. На балансе для роли `member` обычно нужно хотя бы **~100 ₽**.

-1. Сверху **IAM** → **Service users** / **Сервисные пользователи**.
-2. **Add service user**.
-3. Имя, например `gpu-rent-api`.
-4. Пароль: **минимум 20 символов**, сохрани в менеджер паролей. После создания пароль **больше не показывают** — только сброс.
-5. Права:
-   - **Scope: Projects** (не весь аккаунт);
-   - проект `gpu-rent`;
-   - роль **`member`** (создание серверов/дисков/сетей). Роль `reader` для `up` не хватит.
-6. **Add user**.
+1. **IAM** → **Service users** / **Сервисные пользователи** → **Add**.
+2. Имя, например `gpu-rent-api`.
+3. Пароль: **≥ 20 символов**, сохрани сразу — потом только сброс.
+4. Scope: **Projects** → проект `gpu-rent` → роль **`member`** (`reader` для `up` мало).
+5. **Add user**.

-Официально: [Add user](https://docs.selectel.ru/en/access-control/manage/add-user/), [авторизация API](https://docs.selectel.ru/en/api/authorization/).
+Официально: [Add user](https://docs.selectel.ru/en/access-control/manage/add-user/), [API auth](https://docs.selectel.ru/en/api/authorization/).

-### 3.2. Скачать RC-файл (готовые `OS_*`)
+### 3.2. RC-файл

-1. **IAM** → **Service users** → твой пользователь → вкладка **Access**.
-2. Блок **RC files**:
-   - проект `gpu-rent`;
-   - локация = **пул**, например `ru-7` (это `OS_REGION_NAME`, не сегмент `ru-7a`);
-   - **Download**.
-3. Открой файл (`rc.sh`). Из него в `.env` переносятся:
+1. **IAM** → **Service users** → пользователь → **Access**.
+2. **RC files**: проект `gpu-rent`, локация = **пул** (например `ru-7`, не сегмент `ru-7a`) → **Download**.
+3. Из `rc.sh` перенеси в `.env`:

 | Переменная | Откуда |
 | --- | --- |
 | `OS_AUTH_URL` | обычно `https://cloud.api.selcloud.ru/identity/v3` |
 | `OS_USER_DOMAIN_NAME` | номер аккаунта |
-| `OS_PROJECT_DOMAIN_NAME` | тот же номер (можно не дублировать в нашем `.env`) |
 | `OS_PROJECT_ID` | uuid проекта |
 | `OS_USERNAME` | имя сервисного пользователя |
-| `OS_PASSWORD` | пароль, который ты сохранил (в RC его часто нет — дописываешь сам) |
-| `OS_REGION_NAME` | пул, `ru-7` |
-| `GPU_RENT_AZ` | **сегмент** пула, `ru-7a` — в RC его может не быть, смотри матрицу GPU |
+| `OS_PASSWORD` | пароль (в RC часто нет — допиши сам) |
+| `OS_REGION_NAME` | пул, например `ru-7` |
+| `GPU_RENT_AZ` | **сегмент**, например `ru-7a` (в RC может не быть) |

 Официально: [Configure OpenStack CLI](https://docs.selectel.ru/en/cloud-servers/tools/openstack-cli/configure-openstack-cli/).

-### 3.3. Куда класть
-
-Создай каталог и файл **вне git**:
+### 3.3. Заполнить `.env`

 ```powershell
 copy env.example .env
 notepad .env
 ```

-Вставь значения из RC + пароль + `GPU_RENT_AZ`. Никогда не коммить `.env`.
+Вставь значения из RC + пароль + `GPU_RENT_AZ`. **Не коммить** `.env`.

-Проверка без нашего CLI (необязательно):
-
-```powershell
-# после pip install python-openstackclient, если хочешь
-openstack token issue
-openstack flavor list
-```
-
-Наш способ: `gpu-rent doctor`.
+Проверка: `.\gpu-rent.ps1 doctor` (не обязательно ставить `openstack` CLI).

 ---

 ## 4. Civitai API token (модели)

-Нужен, если хочешь seed с Civitai по `models.yaml`. Без токена SwarmUI поставит свою дефолтную модель — это допустимо.
+Нужен, если хочешь seed по `models.yaml`. Без токена SwarmUI поставит свою дефолтную модель — это нормально.

-1. Войди на [civitai.com](https://civitai.com) (тот же аккаунт, что и для `.red`).
-2. [Account settings](https://civitai.com/user/account) → блок **API Keys** → **Add API key**.
-3. Имя, например `gpu-rent`. Токен показывают **один раз**.
-4. В `.env`: `CIVITAI_API_TOKEN=...`
-5. Хост API по умолчанию **`civitai.red`** (полный каталог). `.com` — SFW-витрина, NSFW с неё часто 404. Один токен на оба домена.
-
-Не клади токен в query-string в скриптах «на память» — в логах светится. CLI шлёт `Authorization: Bearer …` только на `civitai.com` / `civitai.red` / `civitai.green`, не на CDN.
-
-Манифест (не в git со своими id, если не хочешь светить вкусы):
+1. Войди на [civitai.com](https://civitai.com) (тот же аккаунт, что для `.red`).
+2. [Account settings](https://civitai.com/user/account) → **API Keys** → **Add**.
+3. Токен показывают **один раз** → в `.env`: `CIVITAI_API_TOKEN=...`
+4. Хост по умолчанию **`civitai.red`** (полный каталог). С `.com` NSFW часто 404.
+5. Манифест:

 ```powershell
 copy models.example.yaml models.yaml
 ```

-`version_id: 0` — заглушка, doctor её игнорирует. Нужен **modelVersionId** из URL, не id карточки модели.
+В URL нужен **`modelVersionId=`**, не id карточки модели. Подробности: [models.md](models.md).

 ---

-## 5. Git-токен (только приватные репы расширений)
+## 5. Git-токен (только приватные репы)

-Публичные GitHub-репы в `extensions.yaml` клонируются без токена.
+Публичные репы в `extensions.yaml` клонируются без токена.

-Если репа приватная:
-
-1. GitHub → Settings → Developer settings → Personal access tokens.
-2. Fine-grained: доступ только к нужным репам, **Contents: Read**.
-3. `GIT_TOKEN` в `.env`.
-
-Скопируй шаблон: `extensions.example.yaml` → `extensions.yaml` в корне репо. Пустой файл = стоковый SwarmUI.
+Приватные: GitHub fine-grained PAT, **Contents: Read** → `GIT_TOKEN` в `.env`.  
+Шаблон: `extensions.example.yaml` → `extensions.yaml`. Пустой файл = стоковый SwarmUI. См. [extensions.md](extensions.md).

 ---

-## 6. SSH
+## 6. Чеклист перед `doctor`

-Ключ **не надо** делать руками. CLI создаст `<repo>\.gpu-rent\id_ed25519` без passphrase и зарегистрирует keypair в OpenStack при первом `up`. `doctor` только проверяет, что это получится.
-
---
-
-## 7. Чеклист перед `doctor`
-
- [ ] Python 3.11+, `pip install -e .`
- [ ] Проект Selectel, скопирован uuid
- [ ] Тикет на лимит **1× GPU** в нужном сегменте (или квота уже > 0)
- [ ] Сервисный пользователь `member` на этот проект, пароль сохранён
- [ ] RC скачан на **тот же пул**, где GPU
- [ ] `.env` в корне репо заполнен (`OS_*` + `GPU_RENT_AZ`)
- [ ] Нет `X-Token` вместо пароля сервисного пользователя
- [ ] (опционально) Civitai token + `models.yaml`
- [ ] На балансе хватает на диск 100 GB **даже когда GPU выключен**
-
-Дальше:
+- [ ] Python 3.11+, лаунчер отвечает на `--help`
+- [ ] Проект Selectel, uuid скопирован
+- [ ] Лимит GPU ≥ 1 (или тикет в работе — тогда `doctor` честно скажет «0»)
+- [ ] Сервисный пользователь `member`, пароль сохранён
+- [ ] RC с того же **пула**, где GPU
+- [ ] `.env`: `OS_*` + `GPU_RENT_AZ`, не `X-Token`
+- [ ] (опц.) Civitai + `models.yaml`
+- [ ] На балансе хватает на **диск ~100 GB 24/7**, даже когда GPU выключен

 ```powershell
-gpu-rent doctor
+.\gpu-rent.ps1 doctor
+.\gpu-rent.ps1 flavors
+.\gpu-rent.ps1 dry-run
 ```

-Exit 0 — облако отвечает, можно идти к spike / `up`, когда команда появится. Exit 1 — в отчёте причина (часто квота GPU = 0).
+| Результат | Что делать |
+| --- | --- |
+| exit 0 | можно `up` |
+| exit 1 | читай отчёт: чаще всего квота GPU = 0 или неверный пароль / пул |

-`gpu-rent dry-run` печатает план без создания сервера.
+---
+
+## 7. Первый `up`
+
+Первый прогон долгий (образ, SwarmUI, Comfy, seed): ориентир **20–40 минут**. Не закрывай терминал посередине bootstrap.
+
+```powershell
+.\gpu-rent.ps1 up --yes
+```
+
+Что произойдёт:
+
+1. Снова короткий doctor (кратко; полный — `up -v`).
+2. Create/unshelve preemptible GPU + диски.
+3. Bootstrap SwarmUI, extensions, autocomplete, Civitai-seed, push локальных папок.
+4. Туннель на `localhost:17801`, access-card с URL / MCP.
+5. Процесс ждёт: **Ctrl+C** закрывает только туннель, GPU остаётся.
+
+Полезные флаги:
+
+| Флаг | Зачем |
+| --- | --- |
+| `--no-tunnel` | только облако; UI потом: `tunnel --open` |
+| `--no-update` | не `git pull` SwarmUI/extensions |
+| `--ollama` | поднять Ollama рядом ([llm.md](llm.md)) |
+| `--no-spot` | обычный (не preemptible) тариф |
+| `--flavor ID` | явный flavor, без фоллбека |
+
+Двойной клик без аргументов: в `gpu-rent.vars` задай `GPU_RENT_DEFAULT_ARGS=up --yes`. Сам `gpu-rent` без args показывает **help**, не поднимает GPU.
+
+---
+
+## 8. Закончить сессию
+
+```powershell
+.\gpu-rent.ps1 stop
+```
+
+Удаляет compute (+ FIP по умолчанию), **диски оставляет**. Модели на месте для следующего `up`.
+
+| Команда | Эффект |
+| --- | --- |
+| `hold` / `hold --minutes 90` | отложить idle-killer |
+| `status` | Nova, диск, killer, LLM |
+| `destroy --i-understand-data-loss` | stop + удалить диски |
+
+---
+
+## Деньги и риски (кратко)
+
+- **GPU** — пока жив compute.
+- **Data-диск** — тарифицируется **всегда** после создания.
+- Preemptible ~**24 ч** → `EXPIRED`; `tunnel` или `up` восстановят.
+- Idle-killer: после льготы (~45 мин) + ~30 мин пустой очереди → delete compute.
+- Цены в OpenStack API нет — смотри панель Selectel.
+
+Дальше: чеклист живого прогона [spike-notes.md](spike-notes.md), справочник команд [cli.md](cli.md).