Установка для локального анализа

Для кого: Для тех, кто готовит проект к сканированию, работе в интерфейсе и необязательному анализу. Задача: Установить только нужные компоненты и понимать требования каждого инструмента. Тип: Учебная инструкция

Проект состоит из пакета Python с дополнительными наборами зависимостей, интерфейса React и документации VitePress. В примерах предполагается, что окружение уже активировано.

Требования

• Python >=3.10.
• FFmpeg в PATH либо полный путь к исполняемому файлу в DJ_TRACK_SIMILARITY_FFMPEG.
• Node.js и npm для сборки frontend/dist или сайта документации.
• Локальная папка с аудио. Для обычной работы облачное хранилище не требуется.

При запуске сервер вызывает require_ffmpeg(). Если FFmpeg не найден, сервер останавливается с понятным сообщением об установке, а не переходит незаметно на неполное декодирование.

Создайте и активируйте окружение

Пример для PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

После активации используйте в командах обычные python и dj-sim.

Базовый пакет

python -m pip install -e ".[dev]"

Базовый пакет устанавливает основные зависимости: NumPy, Mutagen, Pydantic, Typer, FastAPI, Uvicorn, Joblib и инструменты тестирования. Этого достаточно для сканирования в v7, CLI, серверного API, экспорта и выбора базы. Перенос интерфейса React выполняется отдельно.

Дополнительные компоненты

Устанавливайте только те наборы, которые нужны:

python -m pip install -e ".[sonara,ml,dev]"

Набор sonara устанавливает закреплённую версию SONARA v0.2.9. На Windows x64 pip собирает закреплённый исходный пакет, если готового wheel-пакета нет. На других платформах устанавливается та же версия.

Перед анализом новой фонотеки или подготовкой нового релиза SONARA проверьте среду:

python -c "import sonara; print(sonara.__version__)"

Команда должна вывести 0.2.9. Приложение создаёт новый набор схемы v7 из Core и обязательной базы Artifacts, а старые схемы отклоняет: команды миграции нет. Следуйте сценарию подготовки и повторного анализа релиза SONARA.

Набор ml закрепляет версии загрузчиков, включая transformers==5.13.0 и huggingface-hub==1.22.0. Предварительная проверка адаптера модели блокирует запуск, если установленные пакеты не соответствуют закреплённому контракту анализа.

• sonara: извлечение признаков SONARA.
• ml: пакеты для инференса PyTorch, Torchaudio, Torchvision, TorchCodec, nnaudio, Transformers, Hugging Face Hub, LAION CLAP, MAEST и MuQ.
• ann: необязательный HNSW-бэкенд для постоянных вспомогательных индексов ANN.
• rhythm-lab: scikit-learn для обучения классификаторов.

Для необязательной поддержки ANN:

python -m pip install -e ".[ann,dev]"

Для обучения в Rhythm Lab:

python -m pip install -e ".[rhythm-lab,dev]"

Соберите интерфейс

Клиент React ещё не перенесён на API v7. Команды ниже собирают текущий исходный код, но результат не считается проверенным интерфейсом v7.

Бэкенд раздаёт frontend/dist, если каталог существует. Создайте сборку:

npm --prefix .\frontend install
npm --prefix .\frontend run build

Для разработки интерфейса с автоматическим обновлением:

npm --prefix .\frontend run dev

Сервер разработки по умолчанию слушает 127.0.0.1.

Соберите сайт документации

Бэкенд раздаёт статическую документацию из docs/dj-track-similarity/site, если каталог существует. Установите зависимости, синхронизируйте Vale и запустите проверку со сборкой:

npm --prefix .\docs\dj-track-similarity install --no-package-lock
npm --prefix .\docs\dj-track-similarity run vale:sync
npm --prefix .\docs\dj-track-similarity run check

npm run check выполняет строгую проверку стиля Vale перед сборкой VitePress. Созданный каталог site/ исключён из Git.

Запустите сервер

dj-sim serve --host 127.0.0.1 --port 8765 --db .\data\library.sqlite

Фиксированные порты по умолчанию:

Инструмент	Порт	Комментарий
Основной бэкенд	8765	dj-sim serve
Сервер разработки Vite	5173	npm run dev в frontend/
Rhythm Lab	8777	отдельный интерфейс разметки и обучения

На каждом фиксированном порту запускайте только один экземпляр.