andrew/selectel-ml-tui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add README.md

Browse Source
This commit is contained in:
andrew
2026-09-02 16:40:56 +03:00
parent 1e3b638710
commit 6dc6b51b94
1 changed files with 282 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+282
View File
@@ -0,0 +1,282 @@
# selectel-ml-tui
TUI-приложение (Python 3.10+) для отображения потребления **ИИ-роутера Selectel**
прямо в терминале. Работает на Ubuntu (22.04+/24.04) и macOS (12+).
## Возможности
- Дашборд потребления за месяц (сумма, запросы, input/output/cache токены)
- Метрики за 24 часа (доступность, TTFT, задержка) — общие и по моделям
- Бюджет роутера (лимит/расход/остаток) и лимиты по API-ключам
- История потребления по дням с Unicode-бар-графиком (локальный SQLite-кэш)
- Детализация метрик конкретной модели (Enter в таблице моделей)
- Офлайн-режим: при недоступности API показывает последние данные из кэша
- Автообновление по интервалу из конфигурации (по умолчанию 60 с)
- Экспорт истории в CSV/JSON, диагностика окружения (`doctor`)
## Интерфейс
```
┌─ Selectel ML Tokens ──────────────── online · 1 186,73 ₽ ───────┐
│ ┌─ Потребление за месяц ─┐ ┌─ Метрики за 24 часа ──────────────┐ │
│ │ Сумма: 1 186,73 ₽ │ │ Доступность: 100,0% │ │
│ │ Запросы: 1 096 │ │ TTFT: 3 670,0 мс │ │
│ │ Токены: 482 749 246 │ │ Запросы: 1 097 │ │
│ │ Input: 244 004 716 │ │ Input/Output/Cache: … │ │
│ │ Output/Cache: … │ └───────────────────────────────────┘ │
│ │ Бюджет: 2 000 ₽ │ │
│ └────────────────────────┘ │
│ По моделям │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Модель │ Запросы │ Доступность │ TTFT, мс │ Задержка, мс │ │
│ │ deepseek-v4-pro │ 1028 │ 100,0% │ 3,69 │ 12,29 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ r — обновить h — история k — ключи s — настройки q — выход │
└──────────────────────────────────────────────────────────────────┘
```
Экран **История** (**h**): бар-график стоимости по дням + таблица
(период 7/30/90 дней — кнопками). Экран **Ключи** (**k**): лимиты и расход по
API-ключам. Экран **Настройки** (**s**): интервал обновления, «Очистить кэш»,
пути и маскированный токен. **Esc** — назад.
## Горячие клавиши
| Клавиша | Действие |
|---|---|
| `r` | Обновить данные |
| `h` | История потребления |
| `k` | API-ключи и лимиты |
| `s` | Настройки |
| `q` | Выход |
| `Esc` | Назад (с экрана истории/настроек/модели) |
| `Enter` / клик | Детализация метрик модели (в таблице «По моделям») |
На macOS горячие клавиши — обычные символьные (`r/h/s/q`); Option/Command
зарезервированы системой и не используются.
## Требования
- Python 3.10+
- Ubuntu 22.04+/24.04, macOS 12+
- Терминал с поддержкой цвета и UTF-8 (GNOME Terminal, Konsole, tmux,
Terminal.app, iTerm2)
## Источники данных
- **Billing Statistics API** (`https://api.selectel.ru`, заголовок `X-Token`):
стоимость потребления ИИ-роутера (провайдер `aig`) по дням/часам. Параметры
`start`/`end` принимаются в полном ISO-формате (`YYYY-MM-DDTHH:MM:SS.000`),
короткие даты дополняются клиентом автоматически. Значение `value` в копейках.
- **Gateway API ИИ-роутера** (`/aig/gateway/v1/*`, IAM-токен проекта + `X-Project-Id`):
токены, метрики, каталог моделей.
- **IAM-авторизация**: `POST https://cloud.api.selcloud.ru/identity/v3/auth/tokens`
(логин/пароль сервисного пользователя, scope project, TTL 24 ч, кэш с
автообновлением за 5 минут до истечения).
## Получение токенов (панель Selectel)
- **Статический токен** (billing-метрики): панель `my.selectel.ru` → профиль →
**Доступ** → **API-ключи**. Вставьте токен в мастер настройки.
- **IAM-токен** (gateway: сумма/токены/модели/ключи): нужен **сервисный
пользователь**. Создайте его в `my.selectel.ru` → **IAM** → **Сервисные
пользователи** (имя без email, например `ml-monitor`), назначьте роль на
нужный ML-проект. Затем в `selectel-ml-tui config` укажите имя сервисного
пользователя, его пароль, `project_id` и `domain_id` (номер аккаунта).
Без сервисного пользователя доступна только стоимость из billing.
Подробнее об API: [Selectel ML / управление роутером](https://selectel.ru/services/ml/) —
внутренние API панели и документация по биллингу.
## Установка
```bash
make install # Ubuntu/macOS
# или
./scripts/install_ubuntu.sh # Ubuntu
./scripts/install_macos.sh # macOS
# или make install-ubuntu / make install-macos
```
Всё сводится к двум командам на каждой ОС:
```bash
# Ubuntu
sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip
pip install --user . # или ./scripts/install_ubuntu.sh
```
```bash
# macOS
brew install python@3.11 # или ./scripts/install_macos.sh
pip install --user .
```
## Запуск
```bash
make run
# или
.venv/bin/selectel-ml-tui run
# или (с корректным TERM/LANG, подходит для tmux/ssh)
./scripts/run.sh run
```
CLI-точка входа: `selectel-ml-tui` (console_scripts), а также `python -m selectel_ml_tui`.
При первом запуске без настроенных учётных данных выводится подсказка
(`selectel-ml-tui config`); `selectel-ml-tui doctor` предупреждает, что токен
не настроен.
TUI-дашборд:
- **Dashboard**: потребление за месяц (сумма, токены), метрики за 24 часа,
таблица «По моделям»; статус в заголовке — `online`/`offline`
- **r** — обновить, **h** — история, **s** — настройки, **q** — выход
- Автообновление по интервалу из конфигурации (по умолчанию 60 с)
- При недоступности API показывает последние данные из кэша (офлайн)
- **История** (**h**): таблица по дням из кэша + Unicode-бар-график стоимости,
выбор периода 7/30/90 дней (кнопки)
- **Модель** (Enter/клик в таблице моделей): детализация метрик конкретной модели
- **Настройки** (**s**): изменение интервала обновления (сохранение в конфиг),
«Очистить кэш», пути к конфигу/БД, маскированный токен
- Навигация: **Esc** — назад
## Конфигурация
```bash
selectel-ml-tui config # интерактивный мастер настройки
selectel-ml-tui config --path # показать пути конфигурации
selectel-ml-tui config --show # показать текущие настройки (секреты маскируются)
```
Настройки хранятся в `config.toml`, учётные данные (пароль сервисного
пользователя, статический токен) — в `credentials.json` в каталоге конфигурации
(права 0600). Каталог: Linux — `~/.config/selectel-ml-tui`, macOS —
`~/Library/Application Support/selectel-ml-tui`.
Переменные окружения имеют приоритет над файлом конфигурации:
- `SELCTEL_API_URL` — базовый URL API (вместо `api_base_url`)
- `SELCTEL_TOKEN` — статический токен (вместо `static_token`)
- `SELCTEL_SERVICE_USER`, `SELCTEL_PASSWORD` — сервисный пользователь
- `SELCTEL_PROJECT_ID`, `SELCTEL_DOMAIN_ID` — проект и аккаунт
- остальные поля: `SELCTEL_API_BASE_URL`, `SELCTEL_REFRESH_INTERVAL`, `SELCTEL_ROUTER_ID`, …
## Локальный кэш и история
Данные сохраняются в SQLite-базу (`cache.db`) в каталоге данных платформы
(Linux: `~/.local/share/selectel-ml-tui`, macOS:
`~/Library/Application Support/selectel-ml-tui`) при каждом успешном обновлении:
- `consumption_snapshots` — снимки потребления (сумма, токены)
- `metrics_snapshots` — снимки общих метрик
- `model_metrics` — метрики по моделям
- `history` — точки истории по периодам (upsert, без дублей)
При недоступности API TUI показывает «офлайн» и последние данные из кэша.
Старые записи удаляются автоматически (TTL 180 дней).
Экспорт истории: `selectel-ml-tui export --format json|csv -o <файл>`.
## Платформы (Ubuntu и macOS)
Диагностика окружения: `selectel-ml-tui doctor` — проверяет Python (>=3.10),
`TERM`, `LANG`, кодировку UTF-8, выводит пути к конфигурации и данным.
Отличия платформ:
| | Ubuntu 22.04+/24.04 | macOS 12+ |
|---|---|---|
| Python | python3.10+ (apt: `python3 python3-venv python3-pip`) | Homebrew `python@3.11`+ |
| Каталог конфигурации | `~/.config/selectel-ml-tui` | `~/Library/Application Support/selectel-ml-tui` |
| Каталог данных | `~/.local/share/selectel-ml-tui` | `~/Library/Application Support/selectel-ml-tui` |
| Права доступа | 0700/0600 (по умолчанию) | то же; доступ на чтение к `Application Support` |
| Терминалы | GNOME Terminal, Konsole, tmux | Terminal.app, iTerm2 |
| Клавиши | — | hotkeys через Ctrl/символы (r/h/s/q); Option/Command зарезервированы системой |
Требования к окружению терминала:
- `TERM` должен указывать на цветной терминал (`xterm-256color`, `tmux-256color`).
В `tmux`/`screen` задаётся автоматически; `scripts/run.sh` подставляет
`xterm-256color`, если переменная не задана.
- `LANG`/`locale` должны быть UTF-8 (`ru_RU.UTF-8`, `en_US.UTF-8`), иначе
возможны сбои отображения русского текста и граничных символов (▌▀█).
CI: GitHub Actions (`ubuntu-latest` + `macos-latest`, Python 3.11/3.12) — ruff,
mypy, pytest+coverage, doctor.
## Упаковка (однофайловый исполняемый файл)
Опционально: сборка автономного бинарника через PyInstaller.
```bash
make build # или ./scripts/build_ubuntu.sh / build_macos.sh
./dist/selectel-ml-tui doctor # проверка
```
Артефакт не зависит от установленного Python и venv (собирается на целевой ОС).
История версий: [CHANGELOG.md](CHANGELOG.md). Финальный чек-лист тестирования:
[docs/FINAL_CHECKLIST.md](docs/FINAL_CHECKLIST.md).
## Разработка
```bash
make test # pytest + coverage (порог 80%)
make lint # ruff (flake8/isort/format)
make typecheck # mypy (strict)
make format # ruff format
```
- Unit-тесты: config (приоритет env), storage, models (парсинг/форматирование),
API-клиент (httpx.MockTransport: успех, 401, 429, 500, timeout, сетевые ошибки)
- Интеграционный smoke-тест TUI: headless-запуск приложения через `App.run_test()`
- Статический анализ настроен в `pyproject.toml` (`[tool.ruff]`, `[tool.mypy]`,
`fail_under = 80`).
## FAQ и troubleshooting
**«Учётные данные не настроены» при запуске**
Выполните `selectel-ml-tui config` — мастер настройки запросит токен
(и опционально сервисного пользователя для метрик моделей). Проверка:
`selectel-ml-tui doctor` → `[OK] token`.
**Ошибки авторизации (401 / 403)**
- Статический токен истёк или неверен — получите новый в панели Selectel
(профиль → API-токены) и обновите через `selectel-ml-tui config`.
- IAM-доступ: сервисный пользователь должен иметь роль *reader* на нужном
ML-проекте; проверьте `project_id` и `domain_id` (аккаунт). У IAM-токена
TTL 24 ч — приложение обновляет его автоматически (за 5 минут до истечения).
**В дашборде нет метрик по моделям (Input/Output/Cache отсутствуют)**
Gateway-данные (токены по моделям, каталог моделей) требуют IAM-токена
сервисного пользователя. Если сервисный пользователь не создан, доступна
только стоимость (billing) — на дашборде выводится пояснение
«Токены и модели — только через IAM». Создать сервисного пользователя:
my.selectel.ru → IAM → Сервисные пользователи (с областью доступа на нужный
проект), затем `selectel-ml-tui config`.
**PermissionError при запуске (`credentials.json` не читается)**
Файлы конфигурации должны принадлежать текущему пользователю (права 0600).
Если запускать приложение от `root`/`sudo`, файлы создаются с владельцем root,
и обычный запуск падает. Исправление (macOS/Linux):
`sudo chown -R $USER ~/Library/Application\ Support/selectel-ml-tui`
(на Linux путь `~/.config/selectel-ml-tui`). Не запускайте приложение от root.
**Ошибка 422 при запросе данных**
API принимает только полные ISO-таймстампы (`YYYY-MM-DDTHH:MM:SS.000`).
Приложение формирует их самостоятельно; если ошибка повторяется — проверьте
часовой пояс (`doctor` → `LANG`/`locale`).
**«Краказябры»/битые символы в терминале**
`LANG`/`locale` должны быть UTF-8 (`ru_RU.UTF-8`, `en_US.UTF-8`), `TERM` —
цветной (`xterm-256color`). Запуск через `./scripts/run.sh run` подставит
значения автоматически (полезно в tmux/ssh).
**Офлайн-режим**
При недоступности API в заголовке появляется `offline`, а дашборд показывает
последние снимки из SQLite-кэша. Данные обновятся автоматически при
восстановлении сети (клавиша `r` — вручную).
**«Нет данных для графика» в истории**
Кэш пуст — данные появляются после первого успешного обновления (каждая
загрузка сохраняет точку за день). Очистить кэш можно в экране «Настройки»
или через `export` (не очищает).