Leonid Pershin
615cf81493
- Added package data configuration for the 'gpu_rent' package in pyproject.toml. - Updated README.md to include usage instructions for Windows and Unix launchers. - Enhanced CLI documentation in cli.md to reflect new commands and their functionalities. - Revised setup.md to clarify installation steps and environment setup. - Improved error handling and command descriptions in the CLI implementation. - Added new functions for model version handling and flavor resolution in the codebase. - Updated state management to include additional properties for better tracking.
214 lines
11 KiB
Markdown
214 lines
11 KiB
Markdown
# Что сделать до первого `gpu-rent up`
|
||
|
||
Код **не создаёт GPU**, пока не пройден `gpu-rent doctor`. Сначала доступ в облако, квота GPU и ключи. Статический ключ панели **`X-Token` для этого CLI не подходит** — им нельзя управлять серверами и дисками.
|
||
|
||
Панель: [my.selectel.ru](https://my.selectel.ru).
|
||
|
||
---
|
||
|
||
## 1. Python
|
||
|
||
Нужен **Python 3.11+**. На Windows при установке включи «Add python.exe to PATH».
|
||
|
||
В корне репозитория достаточно лаунчера — venv и `pip install` он сделает сам:
|
||
|
||
```powershell
|
||
.\gpu-rent.ps1 --help
|
||
.\gpu-rent.ps1 doctor
|
||
```
|
||
|
||
```bat
|
||
gpu-rent.bat --help
|
||
```
|
||
|
||
```bash
|
||
chmod +x gpu-rent.sh
|
||
./gpu-rent.sh --help
|
||
```
|
||
|
||
Первый запуск копирует `env.example` в `%USERPROFILE%\.gpu-rent\.env` / `~/.gpu-rent/.env`, если файла ещё нет. Заполни `OS_*` (шаги ниже). После `git pull`, если изменился `pyproject.toml`, лаунчер переустановит пакет.
|
||
|
||
Ручной венв по желанию (для разработки / pytest):
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\activate
|
||
python -m pip install -U pip
|
||
python -m pip install -e ".[dev]"
|
||
python -m gpu_rent --help
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Selectel: проект и квота GPU
|
||
|
||
На новых аккаунтах лимит 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).
|
||
|
||
### 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-7` / `ru-7a` — **проверь матрицу**, GPU есть не везде.
|
||
3. Строка **GPU** (и при необходимости vCPU/RAM/network volumes). Если лимит 0 — дальше тикет.
|
||
|
||
Квоту внутри уже выданного лимита можно крутить в панели. **Сам лимит GPU поднимает только поддержка.**
|
||
|
||
### 2.3. Тикет в поддержку
|
||
|
||
**Тикеты** в панели (не email вслепую). Лимит увеличивают **на один конкретный проект**.
|
||
|
||
Текст можно почти копировать:
|
||
|
||
```text
|
||
Прошу увеличить лимит GPU в облачной платформе.
|
||
|
||
Проект: <имя> (ID: <uuid проекта>)
|
||
Пул / сегмент: ru-7 / ru-7a ← подставь свой из матрицы GPU
|
||
Нужно: 1× NVIDIA RTX 4090 24 GB (если нет — ближайший аналог в этом сегменте: 4090 48 GB или A5000).
|
||
Цель: один прерываемый (preemptible) облачный сервер для персональных сессий генерации, диски сетевые.
|
||
|
||
Сейчас квота/лимит GPU = 0, создать сервер с GPU нельзя.
|
||
```
|
||
|
||
Пока тикет не закрыт, ставишь CLI и гоняешь `doctor` — он как раз покажет «квота 0, напишите в поддержку».
|
||
|
||
---
|
||
|
||
## 3. Ключи OpenStack (это и есть «API key» для gpu-rent)
|
||
|
||
Нужен **сервисный пользователь** + пароль. CLI сам получает IAM-токен на 24 часа (`X-Auth-Token`). В `.env` токен хранить не надо.
|
||
|
||
**Не используй:** Профиль → Access → API Keys → `X-Token`. Это статический ключ панели, OpenStack (серверы/диски/сети) он **не** двигает.
|
||
|
||
### 3.1. Сервисный пользователь
|
||
|
||
Только владелец аккаунта или роль `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**.
|
||
|
||
Официально: [Add user](https://docs.selectel.ru/en/access-control/manage/add-user/), [авторизация API](https://docs.selectel.ru/en/api/authorization/).
|
||
|
||
### 3.2. Скачать RC-файл (готовые `OS_*`)
|
||
|
||
1. **IAM** → **Service users** → твой пользователь → вкладка **Access**.
|
||
2. Блок **RC files**:
|
||
- проект `gpu-rent`;
|
||
- локация = **пул**, например `ru-7` (это `OS_REGION_NAME`, не сегмент `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 |
|
||
|
||
Официально: [Configure OpenStack CLI](https://docs.selectel.ru/en/cloud-servers/tools/openstack-cli/configure-openstack-cli/).
|
||
|
||
### 3.3. Куда класть
|
||
|
||
Создай каталог и файл **вне git**:
|
||
|
||
```powershell
|
||
mkdir $env:USERPROFILE\.gpu-rent
|
||
copy env.example $env:USERPROFILE\.gpu-rent\.env
|
||
notepad $env:USERPROFILE\.gpu-rent\.env
|
||
```
|
||
|
||
Вставь значения из RC + пароль + `GPU_RENT_AZ`. Никогда не коммить `.env`.
|
||
|
||
Проверка без нашего CLI (необязательно):
|
||
|
||
```powershell
|
||
# после pip install python-openstackclient, если хочешь
|
||
openstack token issue
|
||
openstack flavor list
|
||
```
|
||
|
||
Наш способ: `gpu-rent doctor`.
|
||
|
||
---
|
||
|
||
## 4. Civitai API token (модели)
|
||
|
||
Нужен, если хочешь seed с Civitai по `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, если не хочешь светить вкусы):
|
||
|
||
```powershell
|
||
copy models.example.yaml $env:USERPROFILE\.gpu-rent\models.yaml
|
||
```
|
||
|
||
`version_id: 0` — заглушка, doctor её игнорирует. Нужен **modelVersionId** из URL, не id карточки модели.
|
||
|
||
---
|
||
|
||
## 5. Git-токен (только приватные репы расширений)
|
||
|
||
Публичные GitHub-репы в `extensions.yaml` клонируются без токена.
|
||
|
||
Если репа приватная:
|
||
|
||
1. GitHub → Settings → Developer settings → Personal access tokens.
|
||
2. Fine-grained: доступ только к нужным репам, **Contents: Read**.
|
||
3. `GIT_TOKEN` в `.env`.
|
||
|
||
Скопируй шаблон: `extensions.example.yaml` → `~\.gpu-rent\extensions.yaml`. Пустой файл = стоковый SwarmUI.
|
||
|
||
---
|
||
|
||
## 6. SSH
|
||
|
||
Ключ **не надо** делать руками. CLI создаст `~\.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
|
||
- [ ] `~\.gpu-rent\.env` заполнен (`OS_*` + `GPU_RENT_AZ`)
|
||
- [ ] Нет `X-Token` вместо пароля сервисного пользователя
|
||
- [ ] (опционально) Civitai token + `models.yaml`
|
||
- [ ] На балансе хватает на диск 100 GB **даже когда GPU выключен**
|
||
|
||
Дальше:
|
||
|
||
```powershell
|
||
gpu-rent doctor
|
||
```
|
||
|
||
Exit 0 — облако отвечает, можно идти к spike / `up`, когда команда появится. Exit 1 — в отчёте причина (часто квота GPU = 0).
|
||
|
||
`gpu-rent dry-run` печатает план без создания сервера.
|