Skip to content

Backend Services Machine Learning Services Model Management

Jump to bottom
github-actions[bot] edited this page May 2, 2026 · 4 revisions

Model Management

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document describes the model management system for the ChordMiniApp backend. It covers model loading and initialization, configuration file management, parameter validation, availability checking, fallback strategies, error handling, versioning and update procedures, compatibility checks, deployment and monitoring workflows, performance optimization, and integration with different model architectures. The focus is on the chord recognition pipeline and the BTC (Beat-Transformer-Chord) family of models, while also touching on SongFormer integration and Spleeter audio separation.

Project Structure

The model management system spans several layers:

  • Application bootstrap and configuration
  • Model availability and path utilities
  • Detector services for different architectures
  • Centralized service orchestrating model selection and fallback
  • Blueprints exposing endpoints for model testing and inference
  • Configuration files for BTC and student training
  • Container orchestration for deployment
graph TB
subgraph "Application"
APP["Flask App<br/>app.py"]
CFG["Config<br/>config.py"]
PATHS["Paths & Checkpoints<br/>utils/paths.py"]
end
subgraph "Model Availability"
AVAIL["Availability Utils<br/>utils/model_utils.py"]
end
subgraph "Detectors"
BTC_SL["BTC-SL Detector<br/>services/detectors/btc_sl_detector.py"]
BTC_PL["BTC-PL Detector<br/>services/detectors/btc_pl_detector.py"]
CNNLSTM["Chord-CNN-LSTM Detector<br/>services/detectors/chord_cnn_lstm_detector.py"]
end
subgraph "Orchestration"
SVC["Chord Recognition Service<br/>services/audio/chord_recognition_service.py"]
ROUTES["Chord Routes<br/>blueprints/chords/routes.py"]
end
subgraph "Audio Processing"
SPLEETER["Spleeter Service<br/>services/audio/spleeter_service.py"]
end
subgraph "External Integrations"
SONGFOR["SongFormer Service<br/>services/audio/songformer_service.py"]
end
subgraph "Configs"
BTC_CFG["btc_config.yaml"]
STUDENT_CFG["student_config.yaml"]
end
APP --> CFG
APP --> PATHS
APP --> AVAIL
APP --> SVC
SVC --> BTC_SL
SVC --> BTC_PL
SVC --> CNNLSTM
SVC --> SPLEETER
SVC --> ROUTES
SONGFOR --> SVC
PATHS --> BTC_SL
PATHS --> BTC_PL
PATHS --> CNNLSTM
BTC_CFG --> BTC_SL
BTC_CFG --> BTC_PL
STUDENT_CFG --> SVC
Loading

Diagram sources

Section sources

Core Components

  • Application bootstrap and configuration: Initializes environment, loads .env, applies compatibility patches, sets up model paths, and performs deferred availability checks.
  • Model availability utilities: Provide checks for Spleeter, Beat-Transformer, Chord-CNN-LSTM, Genius, BTC, PyTorch, and TensorFlow without loading models.
  • Detector services: Encapsulate BTC-SL, BTC-PL, and Chord-CNN-LSTM with normalized interfaces, availability checks, and result parsing.
  • Centralized service: Orchestrates model selection, file-size-aware fallback, chord dictionary validation, and optional Spleeter separation.
  • Routes: Expose endpoints for model testing, model info, and chord recognition with validation and error handling.
  • Configuration files: btc_config.yaml defines BTC model parameters and paths; student_config.yaml defines training and runtime parameters for the student model.

Section sources

Architecture Overview

The system follows a layered architecture:

  • Presentation: Flask blueprints expose endpoints for model testing and inference.
  • Orchestration: A centralized service selects the appropriate detector based on availability, file size, and user preferences.
  • Detection: Each detector validates its own availability and executes inference, returning normalized results.
  • Utilities: Availability checks, path resolution, and logging support the orchestration and detection layers.
  • External integrations: SongFormer service wraps an external runtime; Spleeter provides audio separation.
sequenceDiagram
participant Client as "Client"
participant Routes as "Chord Routes"
participant Service as "ChordRecognitionService"
participant Detector as "Detector (BTC/Chord-CNN-LSTM)"
participant Spleeter as "SpleeterService"
Client->>Routes : POST /api/recognize-chords
Routes->>Service : recognize_chords(file_path, detector, chord_dict, force, use_spleeter)
Service->>Service : validate audio file and size
Service->>Service : select_detector(...)
Service->>Detector : is_available()
alt Detector available
Service->>Detector : recognize_chords(file_path, chord_dict)
Detector-->>Service : normalized results
else Use Spleeter
Service->>Spleeter : extract_vocals(file_path)
Spleeter-->>Service : vocals_path
Service->>Detector : recognize_chords(vocals_path, chord_dict)
Detector-->>Service : normalized results
end
Service-->>Routes : result
Routes-->>Client : JSON result
Loading

Diagram sources

Detailed Component Analysis

Model Loading and Initialization

  • Application bootstrap adds model directories to the Python path and defers heavy imports. It performs a global BTC availability check at startup and sets feature flags accordingly.
  • Detector services encapsulate initialization and import-time checks. They validate directories, required files, and runtime dependencies before enabling inference.
  • SongFormer service dynamically loads the external runtime module and initializes models lazily within a thread-safe context manager.
flowchart TD
Start(["App Startup"]) --> Paths["Add model dirs to sys.path"]
Paths --> Env["Load .env and compat patches"]
Env --> GlobalAvail["Global BTC availability check"]
GlobalAvail --> Detectors["Initialize detector services"]
Detectors --> BTCInit["BTC detectors import checks"]
Detectors --> CNNInit["Chord-CNN-LSTM import checks"]
Detectors --> SpleeterInit["Spleeter availability"]
BTCInit --> Ready(["Ready"])
CNNInit --> Ready
SpleeterInit --> Ready
Loading

Diagram sources

Section sources

Configuration Management: btc_config.yaml and student_config.yaml

  • btc_config.yaml defines audio processing parameters, experiment hyperparameters, model architecture parameters for BTC, and model paths for BTC-SL and BTC-PL.
  • student_config.yaml defines training hyperparameters, model scaling factors, feature parameters aligned with teacher models, data paths, caching, and miscellaneous settings.
flowchart TD
A["btc_config.yaml"] --> B["Audio/Feature Params"]
A --> C["Experiment Params"]
A --> D["Model Params (Transformer)"]
A --> E["Model Paths"]
F["student_config.yaml"] --> G["Training Hyperparameters"]
F --> H["Model Scaling & Heads/Layers"]
F --> I["Feature Params (aligned)"]
F --> J["Data Paths & Cache"]
F --> K["Miscellaneous"]
Loading

Diagram sources

Section sources

Model Availability Checking and Fallback Strategies

  • Availability utilities check filesystem presence of models, required Python packages, and runtime devices (PyTorch CUDA/MPS).
  • Detector services implement availability checks per model, including directory validation and import-time verification.
  • The centralized service selects detectors based on availability and file size, with explicit fallback logic preferring larger-capacity models for large files and smaller models for speed/efficiency.
flowchart TD
Req["Request Detector"] --> Avail["Check Availability"]
Avail --> |Unavailable| Fallback["Select Fallback Detector"]
Avail --> |Available| SizeCheck["Check File Size Limits"]
SizeCheck --> |Too Large| Fallback
SizeCheck --> |OK| Use["Use Requested Detector"]
Fallback --> Use
Loading

Diagram sources

Section sources

Error Handling for Missing or Corrupted Models

  • Detector services catch exceptions during import and inference, returning structured error messages and ensuring cleanup of temporary artifacts.
  • Routes wrap service calls with try/catch, logging stack traces in non-production environments and returning standardized JSON responses.
  • Availability utilities return safe defaults and log detailed errors for debugging.

Section sources

Model Versioning, Update Procedures, and Compatibility Checking

  • Model paths and checkpoints are centralized in path utilities, enabling consistent updates and migrations.
  • Configuration files define model parameters and feature alignment, supporting controlled updates.
  • Device availability checks (CUDA/MPS) ensure compatibility with the runtime environment.

Section sources

Practical Examples: Deployment, Monitoring, and Maintenance

  • Local development with Docker Compose exposes the backend on port 8080 and supports mounting model caches.
  • Endpoints for testing models and retrieving model info enable monitoring and maintenance workflows.
  • SongFormer service integrates an external runtime with environment-driven configuration.

Section sources

Integration with Different Model Architectures

  • BTC-SL and BTC-PL: Transformer-based models with large vocabulary; integrated via a unified wrapper and normalized output.
  • Chord-CNN-LSTM: CNN-LSTM architecture with multiple chord dictionaries; includes mock data generation for testing.
  • Spleeter: Optional audio separation service for vocal/accompaniment extraction prior to inference.
  • SongFormer: External runtime integration with lazy initialization and environment-driven configuration.

Section sources

Dependency Analysis

The system exhibits clear separation of concerns:

  • Centralized configuration and path utilities decouple model specifics from orchestration logic.
  • Detector services isolate model-specific logic and error handling.
  • Routes depend on the centralized service and validators.
  • External integrations (SongFormer, Spleeter) are optional and isolated behind availability checks.
graph LR
CFG["config.py"] --> APP["app.py"]
PATHS["utils/paths.py"] --> BTC_SL["btc_sl_detector.py"]
PATHS --> BTC_PL["btc_pl_detector.py"]
PATHS --> CNNLSTM["chord_cnn_lstm_detector.py"]
AVAIL["utils/model_utils.py"] --> SVC["chord_recognition_service.py"]
SVC --> BTC_SL
SVC --> BTC_PL
SVC --> CNNLSTM
SVC --> ROUTES["blueprints/chords/routes.py"]
SPLEETER["spleeter_service.py"] --> SVC
SONGFOR["songformer_service.py"] --> SVC
Loading

Diagram sources

Section sources

Performance Considerations

  • Detector selection favors smaller models for small files and larger models for large files to balance latency and accuracy.
  • Spleeter separation introduces overhead; it is optional and only used when requested and available.
  • Availability checks and lazy initialization reduce cold-start latency.
  • Device availability checks (CUDA/MPS) ensure optimal hardware utilization.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and remedies:

  • Missing models or dependencies: Use availability endpoints and logs to confirm filesystem paths and imports.
  • File size limitations: Reduce file size or choose a detector with a higher size limit.
  • Spleeter failures: Verify Spleeter availability and disk space; ensure temporary directories are writable.
  • SongFormer runtime errors: Confirm SONGFORMER_ROOT points to a valid runtime directory and required files exist.
  • Configuration mismatches: Align feature parameters (hop length, sample rate) between models and configurations.

Section sources

Conclusion

The model management system provides a robust, modular framework for deploying and operating multiple chord recognition models. It emphasizes availability-first design, explicit fallback strategies, and clear separation between configuration, orchestration, and detection. With comprehensive availability checks, structured error handling, and optional integrations (Spleeter, SongFormer), the system supports scalable deployment and maintenance across diverse environments.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Configuration Options Summary

  • btc_config.yaml: Audio/feature parameters, experiment settings, model architecture, and model paths for BTC variants.
  • student_config.yaml: Training hyperparameters, model scaling, feature alignment, data paths, caching, and miscellaneous settings.

Section sources

Environment and Deployment Notes

  • Docker Compose defines service exposure, environment variables, and optional volume mounts for model caches.
  • Requirements pin compatible versions for NumPy, SciPy, TensorFlow, PyTorch, and other dependencies.

Section sources

ChordMiniApp Wiki

General

API Reference

Architecture and Design

Audio Processing and Analysis

Backend Services

Database and Storage

Deployment and Operations

Experimental Features

Frontend Application

Lyrics and Text Processing

Machine Learning Models

Project Overview

Visualization and User Interface

Clone this wiki locally