188 lines
15 KiB
Markdown
Executable File
188 lines
15 KiB
Markdown
Executable File
# superset-tools
|
||
|
||
[](LICENSE)
|
||
|
||
**Корпоративная платформа для управления Apache Superset, перевода данных с помощью LLM и безопасной доставки аналитики между окружениями.**
|
||
|
||
superset-tools помогает превратить набор разрозненных дашбордов, ручных переносов и служебных скриптов в управляемый процесс: с версиями, согласованиями, аудитом, фоновым выполнением и AI-ассистентом.
|
||
|
||
---
|
||
|
||
## Когда Superset уже вырос, а процессы вокруг него — ещё нет
|
||
|
||
На старте Apache Superset обычно прост: аналитик создаёт датасет, собирает дашборд и показывает его коллегам. Но по мере роста компании появляются новые окружения, подразделения, языки, требования безопасности и сотни связанных объектов.
|
||
|
||
В этот момент команда сталкивается с типичными вопросами:
|
||
|
||
- Как перенести дашборд из разработки в production и ничего не сломать?
|
||
- Как понять, кто изменил отчёт и можно ли вернуть предыдущую версию?
|
||
- Как перевести сотни тысяч наименований и описаний, сохранив отраслевую терминологию?
|
||
- Как контролировать длительные операции без постоянного просмотра логов?
|
||
- Как дать аналитикам свободу, не теряя управляемость и аудит?
|
||
- Как подключить LLM к внутренним данным, не превращая это в набор несвязанных экспериментов?
|
||
|
||
superset-tools объединяет эти задачи в одной платформе и делает работу с Superset воспроизводимой, наблюдаемой и безопасной.
|
||
|
||
## Что получает бизнес
|
||
|
||
| Результат | Как достигается |
|
||
|---|---|
|
||
| **Быстрый выпуск многоязычной отчётности** | Массовый LLM-перевод данных с корпоративными словарями и предварительной проверкой |
|
||
| **Меньше ошибок при релизах** | Dry-run перед миграцией показывает изменения и риски до применения |
|
||
| **Прозрачная история изменений** | Дашборды и связанные объекты версионируются через Git |
|
||
| **Снижение ручной работы** | Повторяемые операции запускаются из интерфейса, по расписанию или через API |
|
||
| **Контроль длительных процессов** | Прогресс, результаты и ошибки доступны в реальном времени |
|
||
| **Управляемое использование AI** | Единые LLM-провайдеры, словари, аудит и подтверждение критических действий |
|
||
| **Готовность к корпоративной среде** | Ролевая модель, ADFS SSO, аудит и поддержка закрытых контуров |
|
||
|
||
## Ключевые сценарии
|
||
|
||
### Перевод корпоративных данных без ручной обработки
|
||
|
||
Представьте каталог из 300 000 позиций: наименования продукции, технические характеристики, марки материалов и примечания. Отчётность нужно подготовить на английском, немецком и китайском языках, при этом терминология должна соответствовать внутренним стандартам компании.
|
||
|
||
В superset-tools команда выбирает источник, нужные поля и языки, подключает терминологический словарь и сначала получает небольшую выборку для проверки. После согласования система запускает полный перевод, сохраняет результат и формирует отчёт о выполнении.
|
||
|
||
При следующем запуске переводятся только новые и изменившиеся записи. Уже обработанные данные и подтверждённые формулировки используются повторно, поэтому процесс становится быстрее и экономичнее.
|
||
|
||
**Что поддерживается:**
|
||
|
||
- несколько целевых языков за один проход;
|
||
- OpenAI-совместимые модели и корпоративные LLM-шлюзы;
|
||
- отраслевые словари из CSV/TSV;
|
||
- предварительный просмотр результата;
|
||
- исправление переводов прямо в интерфейсе;
|
||
- инкрементальная обработка новых данных;
|
||
- плановые запуски по расписанию;
|
||
- статистика по строкам, ошибкам, кэшу и расходу токенов;
|
||
- массовая корректировка неконсистентных терминов.
|
||
|
||
### Безопасная миграция между dev, staging и production
|
||
|
||
Ручной export/import плохо масштабируется: идентификаторы отличаются, подключения к БД называются по-разному, а последствия становятся видны только после релиза.
|
||
|
||
superset-tools сначала выполняет dry-run и показывает, какие объекты будут созданы или изменены, какие зависимости найдены и где есть риски. Только после проверки команда запускает реальную миграцию.
|
||
|
||
Автоматический маппинг помогает сопоставить базы данных и ресурсы между окружениями, а единый отчёт сохраняет результат операции для последующего аудита.
|
||
|
||
**Бизнес-эффект:** меньше аварийных исправлений, быстрее выпуск изменений и понятная процедура согласования релиза.
|
||
|
||
### Дашборды как управляемые цифровые активы
|
||
|
||
Дашборд — это не просто экран с графиками. В нём зафиксированы бизнес-метрики, SQL-логика, фильтры и договорённости между подразделениями. Поэтому его изменения должны быть такими же прозрачными, как изменения программного кода.
|
||
|
||
Git-интеграция superset-tools позволяет:
|
||
|
||
- хранить историю версий;
|
||
- сравнивать изменения;
|
||
- возвращаться к стабильному состоянию;
|
||
- разделять экспериментальную и промышленную работу по веткам;
|
||
- доставлять согласованные изменения в целевое окружение;
|
||
- генерировать понятные сообщения коммитов с помощью LLM.
|
||
|
||
В результате команда получает единый процесс для аналитики и разработки, а ключевые отчёты перестают зависеть от памяти отдельных сотрудников.
|
||
|
||
### AI-ассистент для повседневных операций
|
||
|
||
Платформой можно управлять через чат на естественном языке. Пользователь формулирует задачу так, как привык обсуждать её с коллегами:
|
||
|
||
> «Проверь дашборд производства перед публикацией»
|
||
>
|
||
> «Покажи последние изменения в отчёте по качеству»
|
||
>
|
||
> «Подготовь перенос дашборда на staging и сначала покажи риски»
|
||
>
|
||
> «Проанализируй загруженную спецификацию и найди связанные датасеты»
|
||
|
||
AI-агент сохраняет контекст диалога, умеет работать с PDF и XLSX и запрашивает подтверждение перед критическими действиями. Это не отдельный демонстрационный чат, а дополнительный интерфейс к реальным операциям платформы.
|
||
|
||
### Единый центр контроля
|
||
|
||
Все длительные процессы — перевод, миграция, резервное копирование, анализ и Git-операции — выполняются как управляемые фоновые задачи.
|
||
|
||
Пользователь видит:
|
||
|
||
- текущий статус и прогресс;
|
||
- этап, на котором находится операция;
|
||
- предупреждения и ошибки;
|
||
- итоговый отчёт;
|
||
- историю запусков;
|
||
- автора и время действия.
|
||
|
||
Администратору не нужно подключаться к серверу и искать нужный фрагмент лога, а бизнес-пользователь не остаётся перед бесконечным индикатором загрузки.
|
||
|
||
## Кому подходит superset-tools
|
||
|
||
### BI-командам
|
||
|
||
Для управления большим количеством дашбордов и датасетов, выпуска изменений между окружениями и подготовки многоязычной отчётности.
|
||
|
||
### Аналитикам данных
|
||
|
||
Для запуска типовых операций из единого интерфейса, отслеживания результатов и работы с AI без необходимости писать служебные скрипты.
|
||
|
||
### DevOps и платформенным инженерам
|
||
|
||
Для воспроизводимых поставок, Git-процессов, интеграции с CI/CD, фоновых задач и развёртывания в закрытом контуре.
|
||
|
||
### Руководителям ИТ, BI и DWH
|
||
|
||
Для прозрачности процессов, разграничения доступа, истории изменений и снижения зависимости от ручных действий отдельных специалистов.
|
||
|
||
### Командам локализации и управления данными
|
||
|
||
Для массового перевода справочников и технического контента с контролем терминологии и качества результата.
|
||
|
||
## Чем платформа отличается от набора скриптов
|
||
|
||
Скрипт хорошо решает одну задачу один раз. Корпоративный процесс должен переживать рост объёмов, смену сотрудников, ошибки внешних систем и новые требования безопасности.
|
||
|
||
superset-tools добавляет вокруг операций необходимый управленческий контур:
|
||
|
||
- единый пользовательский интерфейс;
|
||
- роли и права доступа;
|
||
- предварительную проверку изменений;
|
||
- фоновые задачи и повторные попытки;
|
||
- историю и аудит;
|
||
- отчёты в едином формате;
|
||
- расписания и retention-политики;
|
||
- API для внешних систем;
|
||
- расширение через плагины.
|
||
|
||
## Корпоративное использование
|
||
|
||
Платформа рассчитана как на обычное Docker-развёртывание, так и на изолированные корпоративные сети.
|
||
|
||
Поддерживаются:
|
||
|
||
- локальная авторизация и ADFS SSO;
|
||
- роли `admin`, `analyst` и `viewer`;
|
||
- корпоративные CA-сертификаты;
|
||
- собственные LLM-шлюзы и OpenAI-совместимые API;
|
||
- развёртывание без доступа к внешним источникам;
|
||
- очищенные enterprise-дистрибутивы;
|
||
- журналирование действий и результатов операций.
|
||
|
||
## Как устроен продукт
|
||
|
||
Пользователь работает с единой веб-платформой, которая объединяет управление дашбордами, датасетами, миграциями, переводами, Git-репозиториями и фоновыми задачами. AI-агент предоставляет альтернативный диалоговый интерфейс, а API позволяет подключать CI/CD, Airflow, cron и внутренние корпоративные системы.
|
||
|
||
Архитектура модульная: стандартные возможности реализованы как плагины, поэтому платформу можно расширять под собственные источники данных и бизнес-процессы.
|
||
|
||
## Быстрый старт
|
||
|
||
Инструкции по Docker-развёртыванию, локальной разработке, настройке LLM, SSO, сертификатов и закрытого контура находятся в [INSTALL.md](INSTALL.md).
|
||
|
||
## Документация
|
||
|
||
- [Установка и настройка](INSTALL.md)
|
||
- [Архитектура системы](docs/architecture.md)
|
||
- [Архитектурные решения](docs/adr/README.md)
|
||
- [Enterprise Clean Deployment](docs/enterprise-clean.md)
|
||
- [API после запуска](http://localhost:8001/docs)
|
||
- [Руководство для контрибьюторов](CONTRIBUTING.md)
|
||
|
||
## Лицензия
|
||
|
||
Проект распространяется под лицензией [MIT](LICENSE).
|