Sync remaining docs with CLI surface, Assistent, and Civitai dataset.

Align architecture/cli/decisions with modules and Debug API; cross-link seed overlays and scrape→FTS so user docs match 0.2.0. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-23 08:18:08 +03:00
parent 6dfbf4e702
commit b24c1b5d4b
14 changed files with 101 additions and 20 deletions
@@ -1,6 +1,6 @@
 # Локальные модели (не коммитить веса)
-Положи сюда чекпоинт (и рядом `.json` / `.civitai.json` / `.swarm.json`, если есть).
+Положи сюда чекпоинт (и рядом `.json` / `.civitai.json` / `.swarm.json` / `.assistent.json`, если есть).
 - Папка пустая — на сервер ничего не едет.
 - Появилась модель с метадатой — на `gpu-rent up` уедет эта пара (веса + sidecar).
@@ -9,3 +9,5 @@
 Раскладка как у SwarmUI: `Stable-Diffusion/`, `Lora/`, `VAE/`, `Embeddings/`, `controlnet/`, `upscale_models/`, `clip/`.
 Веса в git не попадают.
 Civitai-seed по манифесту (не эта папка): [docs/models.md](../docs/models.md). Scraped galleries (без весов): [datasets/README.md](../datasets/README.md).
@@ -2,3 +2,5 @@
 По умолчанию CLI их сам не скачивает. Включи `PULL_OUTPUT=true` или вызови `gpu-rent pull-output`.
 Новые файлы с VM появятся здесь. С сервера ничего не удаляется.
 `gpu-rent stop --no-pull` — пропустить pull на этот раз. Не тащи гигабайты видео без нужды.
@@ -10,4 +10,7 @@ ship with the swarm-assistent extension — you do not need to duplicate them he
 - `personas/<id>/*.json` — sparse identity shelves (bio, voice, humor, …)
 - Overlay personas created in the Assistent UI are **not** deleted by seed
 This is a **seed overlay**, not `gpu-rent push` (see [docs/local-folders.md](../docs/local-folders.md)).
 Debug overlay vs laptop: `GET http://127.0.0.1:17821/assistent/overlay`.
 See swarm-assistent `Config/personas/README.md` for the shelf schema.
@@ -41,22 +41,27 @@
 | `config` / `varsfile` | `.env` + `gpu-rent.vars`, пути |
 | `state` | JSON сессии: ids, фаза, timestamps |
 | `os_client` / `cloud` / `pools` | openstacksdk, ресурсы, скан пулов |
-| `inventory` / `ux` | Flavors, квоты; preview / ServerPlan (flavor/disk/spot) |
+| `inventory` / `ux` / `placement` / `flavor_presets` | Flavors, квоты, AZ; preview / ServerPlan |
 | `session` | `cmd_up` / `cmd_stop` / adopt |
 | `bootstrap` + `remote/bootstrap.sh` | Идемпотентный first-boot; light без apt |
-| `provision` | extensions, autocomplete, civitai seed, LLM, push, idle-killer arm, start SwarmUI |
+| `provision` | extensions, autocomplete, civitai seed, LLM, push, idle-killer arm, start SwarmUI; seed `search.jsonl` → `Assistent/civitai-examples.jsonl` |
 | `civitai` / `civitai_dataset` | Civitai HTTP API; локальный scrape Krea2 → train/search jsonl (отдельный CLI) |
 | `huggingface` | HF probe / метадата / URL для seed и capture |
 | `capture` | Инвентарь VM → merge ссылок в локальные манифесты |
 | `doctor` | Preflight без mutating compute |
-| `sync_files` | SFTP `Models` / Wildcards / workflows / Output |
+| `sync_files` / `payload` | SFTP Models / Wildcards / workflows / Output; локальные деревья приложения |
-| `notify` | Toast/звук при backend Idle |
+| `notify` / `balance` | Toast/звук при ready; баланс ₽ через X-Token + watchdog |
 | `tunnel` | sshtunnel + Nova EXPIRED watchdog |
-| `debug_api` / `debug_checks` / `debug_assistent` | localhost read-only HTTP sidecar (`:17821`); deep Assistent probes |
+| `debug_api` / `debug_checks` / `debug_assistent` / `debug_assistent_session` | localhost read-only HTTP sidecar (`:17821`); deep Assistent + multi-turn sessions |
 | `vm_logs` | journalctl helpers; алиасы `swarm`/`ollama`/`killer`/`cloud-init` |
 | `local_watchdog` | Опциональный локальный тик → stop при unclean exit |
-| `llm_runtime` / `setup_wizard` | Opt-in Ollama + `ollama-models.yaml` |
+| `llm_runtime` / `setup_wizard` / `perf_tiers` | Opt-in Ollama + `ollama-models.yaml`; GPU tier для Swarm/Ollama |
 | `idle_killer` / `hold` | systemd на VM + hold-файл |
-| `ready` / `snapshot` | Idle backend + boot snapshot |
+| `ready` / `snapshot` | Backend ready + boot snapshot |
 | `access_card` | URL / MCP panel после ready |
 На `up` leftover-юнит `gpu-rent-llamacpp` (если остался с прошлых версий) стопается; рантайма llama.cpp в продукте больше нет (`LLM_RUNTIME` = `none` \| `ollama`).
 Каталог сервисов — из Keystone, не из выдуманного `api.selectel.ru/v3/`.
 ## Два диска
@@ -51,6 +51,7 @@ gpu-rent up --yes --ollama
 | Команда | Поведение |
 | --- | --- |
 | `gpu-rent version` | Версия пакета (`0.2.0`) |
 | `gpu-rent setup` | Wizard: манифесты (в т.ч. ollama-models), `LLM_RUNTIME` (нумерованное меню), пресет, опционально local-watchdog |
 | `gpu-rent doctor` | Preflight **без** create. Exit ≠ 0 → сессию начинать нельзя |
 | `gpu-rent flavors` | Скан `SCAN_POOLS` по сегментам a/b/c × `FLAVOR_PREFERENCE` × `FLAVOR_SIZE_PRESET`, список в текущем регионе |
@@ -62,6 +63,7 @@ gpu-rent up --yes --ollama
 | `gpu-rent up --ollama` / `--llm ollama` | Ollama рядом со SwarmUI |
 | `gpu-rent up --no-swarm` / `--llm-only` | Только Ollama (нужен `--ollama` / `LLM_RUNTIME=ollama`); без clone SwarmUI |
 | `gpu-rent up --no-update` | Без `git pull` SwarmUI/extensions (только недостающие clone) |
 | `gpu-rent up --update` | Форс `git pull` SwarmUI + extensions (перекрывает `UPDATE_GIT=false`) |
 | `gpu-rent up --no-tunnel` | Только облако |
 | `gpu-rent up --no-spot` | Не preemptible |
 | `gpu-rent up --flavor ID --yes` | Явный flavor; без `--flavor` + `--yes` — первый доступный из `FLAVOR_PREFERENCE` |
@@ -73,11 +75,11 @@ gpu-rent up --yes --ollama
 | `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 (полный дамп; после `up` хвост уже печатается сам) |
+| `gpu-rent logs` / `logs -u UNIT` | journalctl на VM; `-u swarm\|ollama\|killer\|cloud-init` (алиас `ollama` → юнит `gpu-rent-ollama`) |
 | `gpu-rent ssh` | Оболочка на VM |
 | `gpu-rent seed-models` | Докачать новые строки Civitai-манифеста на живой диск |
 | `gpu-rent seed-extensions` | Доклонировать/обновить git-репы; restart swarmui |
-| `gpu-rent seed-personas` | Пуш `assistent-personas/` → overlay на VM (без полного up) |
+| `gpu-rent seed-personas` | Пуш `assistent-personas/` → overlay на VM (без полного up); также `search.jsonl` → FTS, если есть |
 | `gpu-rent push` / `push-models` | Локальные деревья → VM |
 | `gpu-rent pull-output` | VM `Output/` → `./Output` |
 | `gpu-rent capture` / `capture all` | Инвентарь VM → merge **ссылок** в `models.yaml` + `extensions.yaml` (веса не качать) |
@@ -92,6 +94,19 @@ gpu-rent up --yes --ollama
 Нет команды `generate`. Локальный SwarmUI целиком не зеркалируем — только папки приложения ([local-folders.md](local-folders.md)).
 ### Отдельный CLI: `civitai-dataset` (не Typer)
 Лаунчеры `civitai-dataset.bat` / `.ps1` / `.sh` → `python -m gpu_rent.civitai_dataset`. По умолчанию `all`. Подробности и пути: [datasets/README.md](../datasets/README.md).
 | Команда | Поведение |
 | --- | --- |
 | `discover` | Топ Krea2 checkpoints/LoRAs → `catalog/models.json` |
 | `scrape` | Галереи (метаданные, **без** картинок); `--target`, `--per-version`, `--min-score` |
 | `split` | `by_kind/` / `by_rating/` / `train.jsonl` / `search.jsonl` |
 | `all` | discover + scrape + split |
 Нужен `CIVITAI_API_TOKEN` (лучше `CIVITAI_API_HOST=civitai.red`). На `up` / `seed-personas` файл `datasets/civitai/search.jsonl` пушится на VM как `Assistent/civitai-examples.jsonl` (если есть).
 ---
 ## `doctor`
@@ -103,12 +118,13 @@ gpu-rent up --yes --ollama
 1. Читается `.env`, обязательные `OS_*`
 2. Keystone выдаёт токен
 3. Квота GPU > 0 (иначе текст про поддержку Selectel)
-4. В сегменте есть flavor из `FLAVOR_PREFERENCE`
+4. В сегменте есть flavor из `FLAVOR_PREFERENCE` / `DEFAULT_FLAVOR_ID`
 5. Volume type / место под data ~100 GB
 6. SSH-ключ есть или будет создан в `.gpu-rent/`
-7. Если есть `CIVITAI_API_TOKEN` — доступ к API-хосту; манифест парсится
+7. Живой сервер с тегом `gpu-rent` (info) и boot snapshot `gpu-rent-boot-ok` (info)
-8. `extensions.yaml` парсится, если есть
+8. Если есть `CIVITAI_API_TOKEN` — доступ к API-хосту; манифест парсится
-9. Предупреждения по огромным локальным `Models/`
+9. `extensions.yaml` парсится, если есть; при `LLM_RUNTIME=ollama` — `ollama-models.yaml` + строка Assistent ext
 10. Предупреждения по огромным локальным `Models/`
 Exit 0 → можно `up`. Exit 1 → причина в таблице / кратком списке на `up`.
@@ -140,6 +156,7 @@ Exit 0 → можно `up`. Exit 1 → причина в таблице / кра
 | `/assistent/memory` | `assistent.sqlite` + counts |
 | `/assistent/api` | `AssistentListPersonas/Models/Memory/Chats` через туннель (или SSH) |
 | `/assistent/api?chat_smoke=1` | + 1-token Ollama `/api/chat` (кратко грузит модель) |
 | `/assistent/wanted` | **GET** — очередь wanted-моделей на data volume |
 | `/assistent/logs` | journalctl swarmui: build/load/Sqlite |
 | `/assistent?logs=1` | Сводка + journal |
 | `/assistent/session` | **POST** — multi-turn debug chat (in-memory, TTL ~45m) |
@@ -258,6 +275,9 @@ BOOT_SNAPSHOT_NAME=gpu-rent-boot-ok
 CIVITAI_API_TOKEN=
 CIVITAI_API_HOST=civitai.red
 # HF для download/capture (любой из двух):
 # HF_TOKEN=
 # HUGGING_FACE_HUB_TOKEN=
 MODELS_MANIFEST=
 LOCAL_MODELS_DIR=
 LOCAL_WILDCARDS_DIR=
@@ -272,6 +292,7 @@ SWARMUI_LOCAL_PORT=17801
 LLM_RUNTIME=none
 OLLAMA_LOCAL_PORT=17811
 DEBUG_LOCAL_PORT=17821
 # ENABLE_SWARMUI=false / WORKLOAD=llm — только LLM (см. llm.md)
 UPDATE_GIT=true
 DEFAULT_FLAVOR_ID=
@@ -286,6 +307,11 @@ IDLE_GRACE_MINUTES=45
 # LOCAL_WATCHDOG_GRACE_MINUTES=10
 PULL_OUTPUT=false
 NOTIFY_READY=true
 # Баланс ₽ (X-Token панели, не OS_*). Нужен watchdog install:
 # SELECTEL_API_TOKEN=
 # BALANCE_NOTIFY_STEP_RUB=200
 # BALANCE_NOTIFY_LOW_RUB=
 ```
 Flavor uuid в git не хардкодить. `FLAVOR_FALLBACK=false` — только `DEFAULT_FLAVOR_ID` / `--flavor`.
@@ -52,3 +52,14 @@
 3. **`Ctrl+C` и `Ctrl+D` на туннеле вызывают `stop`** (диски на месте). Убийство процесса/ребут без stop → idle-killer на VM; при **local-watchdog** — ещё и локальный stop после grace.
 4. Idle-killer на VM **не может** быть `shutdown -h`: у Selectel остановленная изнутри VM часто продолжает тарифицировать ресурсы. Нужен вызов OpenStack: удалить **этот** compute, диски оставить.
 5. Для этого на VM — OpenStack **application credential** с правом DELETE/GET **только этого** compute (не `/servers/*`, не unrestricted fallback). На `stop`/`destroy` cred отзывается. Компрометация SwarmUI в худшем случае сносит текущую GPU-сессию, а не произвольные машины проекта.
 ## Дополнения (23 августа 2026)
 Таблица выше от 21.08 не переписывалась. Ниже — принятые уточнения после v1:
 | Тема | Решение |
 | --- | --- |
 | LLM runtime | Только `none` \| `ollama`. **llama.cpp снят** из продукта; leftover unit `gpu-rent-llamacpp` на `up` стопается |
 | Debug API | Принятая поверхность: localhost `:17821` на `up`/`tunnel` / `gpu-rent debug`; Assistent diagnose, session, chat-eval |
 | Assistent | First-class поверх SwarmUI + Ollama (чат, Cards, personas), не только «prompt-help» |
 | Civitai dataset | Локальный scrape метаданных Krea2 (без картинок) → `train.jsonl` / `search.jsonl`; на `up`/`seed-personas` `search.jsonl` → `Assistent/civitai-examples.jsonl` (FTS) |
@@ -51,10 +51,12 @@ comfy:
 | --- | --- |
 | `none` (или поле отсутствует) | всегда |
 | `ollama` | только при `LLM_RUNTIME=ollama` |
-| `any-llm` | при `LLM_RUNTIME=ollama` |
+| `any-llm` | при `LLM_RUNTIME=ollama` (сейчас единственный LLM-рантайм; llama.cpp снят) |
 Строки с несовпавшим `requires` пропускаются (лог), остальные ставятся как обычно. В `extensions.example.yaml` по умолчанию — **swarm-assistent** с `requires: ollama` (чат + доска Generate/Ref + persona/Cards, ветка `main`). После `seed-extensions` + рестарта SwarmUI подтягивается текущий `main` (с **0.13.1+**: `CopyLocalLockFileAssemblies` копирует `Microsoft.Data.Sqlite` + `SQLitePCLRaw*` рядом с extension DLL — иначе ListMemory/ListChats/SaveChat падают; с **0.10.11**: default chat = `default_chat` / старший тег, warm той же моделью). На `up` (и `gpu-rent seed-personas`) сидится папка `assistent-personas/` → overlay `/mnt/swarm_data/Assistent/personas/<id>/*.json`, плюс `_base/assistant.json` (`default_persona`, опционально `num_ctx` с GPU tier). Seed **не** удаляет overlay-личности, созданные в UI. Legacy `personas.json` / yaml-prompt больше не пишутся.
 Если есть `datasets/civitai/search.jsonl`, на том же шаге пушится FTS-индекс → `/mnt/swarm_data/Assistent/civitai-examples.jsonl` ([datasets/README](../datasets/README.md)). Диагностика Assistent: Debug API `/assistent/*` ([cli.md](cli.md)).
 В git репозитория gpu-rent не коммитить рабочий список с лишними приватными URL сверх примера.
 ## Когда в жизненном цикле
@@ -1,6 +1,6 @@
 # LLM рядом со SwarmUI (opt-in)
-По умолчанию поднимается **только SwarmUI**. Ollama — отдельно (помощь с промптами и т.п.).
+По умолчанию поднимается **только SwarmUI**. Ollama — отдельно (помощь с промптами, Assistent chat и т.п.). **llama.cpp снят** из продукта: `LLM_RUNTIME` только `none` \| `ollama` (leftover unit `gpu-rent-llamacpp` на `up` стопается).
 Интерактивные вопросы — **нумерованные меню** (Enter = вариант со ←). Ключ словом (`recommended`, `keep`) тоже принимается.
@@ -44,7 +44,7 @@ LLM_RUNTIME=ollama
 Потом `gpu-rent up --yes`.
-Выключить: `LLM_RUNTIME=none` (на `up` старые LLM unit’ы на VM останавливаются).
+Выключить: `LLM_RUNTIME=none` (на `up` старые LLM unit’ы на VM останавливаются). Journal: `gpu-rent logs -u ollama` (алиас → systemd `gpu-rent-ollama`).
 Голый `gpu-rent` без args — **help**. Двойной клик: `GPU_RENT_DEFAULT_ARGS=up --yes`. Полный doctor на up: `up -v`.
@@ -113,7 +113,7 @@ Unit `gpu-rent-ollama` читает `/mnt/swarm_data/.gpu-rent-gpu.json`:
 \*Flash на Ampere+ (compute ≥ 8.0). `NUM_PARALLEL=2`, `MAX_LOADED_MODELS=2` (chat VL + memory embed). Memory models use `use: memory` and a CPU Modelfile (`num_gpu 0`) so embed does not steal VRAM from the chat model. Ollama default `num_ctx` is 4096; we set `OLLAMA_CONTEXT_LENGTH` so Assistent + vision fits. Mid/high keep-alive is **5m** because Assistent parks the chat model before Generate (`AssistentParkLlm`) and warms after. Env: `/mnt/swarm_data/.gpu-rent-ollama.env`.
-Personas: laptop `assistent-personas/` → on `up` / `seed-personas` overlay folders under `/mnt/swarm_data/Assistent/personas/<id>/` (+ `_base/assistant.json` with `default_persona` / `num_ctx`). Shelves are short JSON files (not a long prompt). See [extensions.md](extensions.md).
+Personas: laptop `assistent-personas/` → on `up` / `seed-personas` overlay folders under `/mnt/swarm_data/Assistent/personas/<id>/` (+ `_base/assistant.json` with `default_persona` / `num_ctx`). Shelves are short JSON files (not a long prompt). See [extensions.md](extensions.md). Optional FTS examples: [datasets/README](../datasets/README.md) (`search.jsonl` → `Assistent/civitai-examples.jsonl`). Journal: `gpu-rent logs -u ollama`.
 `ollama-models.yaml` entries:
@@ -15,10 +15,19 @@
 | `Models/` | `/mnt/swarm_data/Models/` | push | да, если не пусто; см. [models.md](models.md) |
 | `Wildcards/` | `/mnt/swarm_data/Data/Wildcards/` | push | да, если не пусто |
 | `CustomWorkflows/` | `/mnt/swarm_data/CustomWorkflows/` → bind в ComfyUI CustomWorkflows | push | да, если не пусто |
-| `Output/` | `/mnt/swarm_data/Output/` | **pull**, опционально | нет; флаг `PULL_OUTPUT` |
+| `Output/` | `/mnt/swarm_data/Output/` | **pull**, опционально | нет; флаг `PULL_OUTPUT`; `stop --no-pull` отключает на этот раз |
 Веса, картинки, воркфлоу в git не коммитить (`.gitignore` + `.gitkeep`).
 ## Seed overlay (не `gpu-rent push`)
 Другой механизм — не SHA256-синк четырёх деревьев выше:
 | Локально | На VM | Когда |
 | --- | --- | --- |
 | `assistent-personas/` | `/mnt/swarm_data/Assistent/personas/<id>/` | `up` / `seed-personas`; см. [extensions.md](extensions.md) |
 | `datasets/civitai/search.jsonl` | `Assistent/civitai-examples.jsonl` | `up` / `seed-personas`, если файл есть; см. [datasets/README](../datasets/README.md) |
 ## Push (Models / Wildcards / CustomWorkflows)
 Как у моделей: нет содержимого кроме README/`.gitkeep` — skip. Новый или изменённый файл — SFTP. Метадата рядом с весами едет парой. Команда на все три дерева: `gpu-rent push`.
@@ -5,6 +5,8 @@
 1. **Civitai-seed** (ниже) — на пустой диск при bootstrap, если есть API-токен и манифест.
 2. **Папка `Models/` в корне gpu-rent** — на каждом `up` выгрузить только изменившееся. `Wildcards/` и `CustomWorkflows/` — то же, см. [local-folders.md](local-folders.md).
 Отдельно (не веса): локальный scrape галерей Krea2 → jsonl для Assistent FTS / обучения — [datasets/README.md](../datasets/README.md). Это не `models.yaml` и не `gpu-rent push`.
 ## Быстрый старт моделей
 ```powershell
@@ -11,3 +11,10 @@
 - Snapshot attached boot после Idle: время; create from snapshot ок.
 Если 45 мин льготы мало на первый Comfy — подними `IDLE_GRACE_MINUTES`, не отключай killer.
 ## Живые caveat’ы (код есть, прод-зелёный не обещаем)
 - **Качалка в UI SwarmUI** — без надёжного busy-сигнала → пользователь жмёт `hold`.
 - **Assistent Sqlite / Exact / nomic-embed** на живой GPU ещё не «зелёный прод»: смотри Debug `/assistent/diagnose` и [cli.md](cli.md); offline-фиксы могут опережать live.
 - **Qwen3-VL** требует **Ollama ≥ 0.12.7** (пин в vars / [llm.md](llm.md)).
 - Датасет scrape: rate limits Civitai — подбирать `--target` / паузы на живом токене.
@@ -178,6 +178,12 @@ copy models.example.yaml models.yaml
 В URL нужен **`modelVersionId=`**, не id карточки модели. Подробности: [models.md](models.md).
 Опционально позже (не нужно для первой картинки):
 - `SELECTEL_API_TOKEN` (X-Token панели) + `gpu-rent watchdog install` — toast по балансу ₽; см. [cli.md](cli.md) / [decisions.md](decisions.md).
 - `copy assistent-personas.example assistent-personas` — overlay personas; см. [extensions.md](extensions.md).
 - `.\civitai-dataset.bat` — scrape метаданных Krea2 → Assistent FTS; см. [datasets/README](../datasets/README.md).
 ---
 ## 5. Git-токен (только приватные репы)
@@ -113,8 +113,12 @@
 | Ollama :17811 через туннель | |
 | pull / GGUF из манифеста | |
 | `LLM_RUNTIME=none` гасит unit на следующем up | |
 | Debug `:17821` → `GET /assistent/diagnose` | |
 | Assistent chat / Sqlite (UI или session) | |
 | `seed-personas` / overlay | |
 | (опц.) `datasets/civitai/search.jsonl` → FTS на VM | |
-См. [llm.md](llm.md).
+См. [llm.md](llm.md), [cli.md](cli.md) (Debug), [datasets/README](../datasets/README.md).
 ---
@@ -58,6 +58,8 @@
 Без туннеля API с ноутбука недоступен: 7801 на VM не опубликован в интернет.
 **Assistent** (если `requires: ollama` и runtime включён) грузится как SwarmUI extension с data volume. Глубокая отладка — не через публичный 7801, а через Debug sidecar `:17821` / `gpu-rent debug` ([cli.md](cli.md)). Personas / FTS: [extensions.md](extensions.md), [datasets/README](../datasets/README.md).
 ## Чего не делать
 - `chmod -R 777` на Models.