Skip to content

Machine Learning Models Chord Recognition Models BTC Model Training and Distillation

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

BTC Model Training and Distillation

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 explains the BTC (Bi-Directional Transformer Chord) model training methodologies, focusing on self-label (SL) and pseudo-label (PL) variants within the ChordMini ecosystem. It covers the teacher-student distillation process, knowledge transfer mechanisms, and model compression techniques. The guide details the training pipeline for both SL and PL variants, including data preparation, pseudo-label generation, and fine-tuning procedures. It also documents curriculum learning approaches, cross-validation strategies, hyperparameter optimization, model configuration files, training schedules, and evaluation metrics. Practical examples demonstrate training execution, checkpoint management, and performance monitoring, along with trade-offs among model size, accuracy, and computational efficiency. Finally, it explains integration with the broader ChordMini ecosystem and deployment considerations for production environments.

Project Structure

The BTC training implementation resides under the ChordMini module within the Python backend. Key components include:

  • Training entry points for BTC and fine-tuning
  • BTC model architecture
  • Configuration files for model and experiment parameters
  • Kubernetes job configurations for training automation
  • Inference module for API usage
graph TB
subgraph "ChordMini BTC Training"
A["train_btc.py"]
B["btc_model.py"]
C["btc_config.yaml"]
D["train_btc.yaml"]
E["btc_chord_recognition.py"]
F["finetune_labeled.yaml"]
G["train_finetune.py"]
end
A --> B
A --> C
D --> A
F --> G
G --> B
E --> B
Loading

Diagram sources

Section sources

Core Components

  • BTC Model: Implements bi-directional self-attention layers with a softmax output layer. It accepts spectrogram features and produces per-frame chord logits.
  • Training Pipeline: Supports supervised learning (SL) and pseudo-label (PL) scenarios. It integrates knowledge distillation (KD) with optional focal loss and curriculum-style warmup.
  • Configuration: btc_config.yaml defines model architecture, feature dimensions, and training parameters.
  • Inference: btc_chord_recognition.py provides API-friendly inference using SL or PL checkpoints and standardized chord labeling.

Key implementation references:

Section sources

Architecture Overview

The BTC training architecture supports:

  • Supervised Learning (SL): Uses ground-truth labels from synthetic datasets.
  • Pseudo-Label (PL): Incorporates teacher logits for distillation when available.
  • Knowledge Distillation: Combines cross-entropy with a KL divergence term using a temperature-scaled softmax.
  • Curriculum Learning: Optional warmup scheduling to stabilize early training.
  • Model Compression: Large vocabulary (170 chords) with configurable dropout and attention layers.
sequenceDiagram
participant User as "User/Operator"
participant K8s as "Kubernetes Job (train_btc.yaml)"
participant Script as "train_btc.py"
participant Model as "BTC_model"
participant Data as "SynthDataset"
participant Eval as "Tester"
User->>K8s : Submit training job
K8s->>Script : Launch with env args
Script->>Data : Initialize dataset (SL/PL/KD)
Script->>Model : Build BTC model with config
loop Training Epochs
Script->>Data : Fetch batch (features, labels, logits if KD)
Script->>Model : Forward pass
Script->>Script : Compute loss (CE/KL/Focal)
Script->>Model : Backward pass and optimizer step
end
Script->>Eval : Evaluate on validation/test splits
Eval-->>Script : Metrics (accuracy, MIR scores)
Script-->>K8s : Save checkpoints and artifacts
Loading

Diagram sources

Detailed Component Analysis

BTC Model Architecture

The BTC model comprises bi-directional self-attention layers with position-wise feed-forward networks and residual connections. It normalizes inputs and projects them into a hidden space before applying multi-head attention and feed-forward blocks. The output layer produces per-frame logits for chord classification.

classDiagram
class BTC_model {
+int timestep
+bi_directional_self_attention_layers self_attn_layers
+SoftmaxOutputLayer output_layer
+forward(x) Tensor
+predict(x) Tensor
}
class bi_directional_self_attention_layers {
+int max_length
+Sequential self_attn_layers
+LayerNorm layer_norm
+forward(inputs) Tensor
}
class self_attention_block {
+MultiHeadAttention multi_head_attention
+PositionwiseFeedForward positionwise_convolution
+LayerNorm layer_norm_mha
+LayerNorm layer_norm_ffn
+forward(inputs) Tensor
}
BTC_model --> bi_directional_self_attention_layers : "uses"
bi_directional_self_attention_layers --> self_attention_block : "stacks"
Loading

Diagram sources

Section sources

Training Pipeline for SL and PL Variants

The training pipeline supports:

  • SL Training: Standard supervised cross-entropy loss on ground-truth labels.
  • PL Training: Uses teacher logits for distillation when available; falls back to CE when logits are absent.
  • KD Integration: Combines CE and KL divergence with configurable alpha and temperature.
  • Focal Loss: Optional to handle class imbalance.
  • Curriculum Learning: Warmup scheduling for learning rate.
flowchart TD
Start(["Start Training"]) --> ParseArgs["Parse CLI and Env Args"]
ParseArgs --> Config["Load btc_config.yaml<br/>Merge overrides"]
Config --> KDCheck{"KD Enabled?"}
KDCheck --> |Yes| UseLogits["Require teacher logits"]
KDCheck --> |No| UseLabels["Use ground-truth labels"]
UseLogits --> LossSel["Select Loss:<br/>CE + α*KL(T/τ)"]
UseLabels --> LossSel2["Select Loss:<br/>CE or Focal Loss"]
LossSel --> TrainLoop["Training Loop"]
LossSel2 --> TrainLoop
TrainLoop --> Eval["Evaluate on Val/Test"]
Eval --> Save["Save Checkpoints"]
Save --> End(["End"])
Loading

Diagram sources

Section sources

Knowledge Transfer and Distillation Mechanisms

  • Teacher-Student Setup: BTC student model trained with teacher logits for improved generalization.
  • Loss Composition: Final loss combines CE and KL divergence with a mixing coefficient alpha and temperature τ.
  • Normalization Alignment: Uses mean/std from a teacher checkpoint to align feature distributions.
sequenceDiagram
participant T as "Teacher Model"
participant D as "Dataset Loader"
participant S as "Student (BTC)"
participant L as "Loss Fn"
D->>D : Load spectrograms + labels/logits
D-->>S : Batch (x, y_true, y_soft)
S->>S : Forward pass (logits)
alt KD Enabled
L->>L : Compute CE + α*KL_div(Softmax(logits/τ) || Softmax(y_soft/τ))
else SL Only
L->>L : Compute CE(logits, y_true)
end
L-->>S : Loss value
Loading

Diagram sources

Section sources

Data Preparation and Pseudo-Label Generation

  • Dataset Types: Supports FMA, Maestro, and DALI synthetic datasets. Combined datasets supported.
  • Pseudo-Label Availability: When logits are provided, PL training leverages them; otherwise, SL training proceeds with labels.
  • Normalization: Loads mean/std from a teacher checkpoint to align features across datasets.

Practical guidance:

  • Use logits_dir for PL training when available.
  • Ensure label directories contain .lab files aligned to spectrogram frames.
  • For SL, ensure label directories contain ground-truth labels.

Section sources

Fine-Tuning Procedures (Cross-Validation and Production)

  • Fine-tuning Workflow: Uses pre-computed spectrograms/logits with real labels. Supports freezing feature extractor and curriculum-style warmup.
  • Cross-Validation: The fine-tuning script creates train/val/test splits via SynthSegmentSubset and evaluates on test.
  • Production Deployment: Inference module loads model checkpoints and performs standardized chord labeling for API usage.
flowchart TD
FTStart(["Fine-tune Entry"]) --> LoadCfg["Load student_config.yaml + ENV overrides"]
LoadCfg --> LoadData["Initialize SynthDataset (logits + labels)"]
LoadData --> Split["Create train/val/test subsets"]
Split --> Freeze{"Freeze Feature Extractor?"}
Freeze --> |Yes| TrainFT["Train with frozen extractor"]
Freeze --> |No| TrainFT2["Train with full fine-tuning"]
TrainFT --> EvalFT["Evaluate on test"]
TrainFT2 --> EvalFT
EvalFT --> SaveFT["Save checkpoints"]
SaveFT --> FTEnd(["Fine-tune Complete"])
Loading

Diagram sources

Section sources

Hyperparameter Optimization and Schedules

  • Learning Rate Schedules: Cosine, linear decay, one-cycle, cosine restarts, validation-based, or none.
  • Warmup: Optional warmup with configurable start/end LR and epochs.
  • Focal Loss: Gamma and Alpha parameters for handling class imbalance.
  • KD Parameters: Alpha (mixing weight) and Temperature (softening) for distillation.

Section sources

Model Configuration Files and Training Schedules

  • btc_config.yaml: Defines model architecture (hidden size, layers, heads, dropout), feature dimensions, and training parameters.
  • train_btc.yaml: Kubernetes job specification for BTC training with environment-driven overrides for LR, KD, focal loss, and dataset selection.

Section sources

Evaluation Metrics and Monitoring

  • MIR Evaluation: Uses large vocabulary scoring functions and standardized chord label processing.
  • Logging: Verbosity controlled via config/env; detailed logs for mapping analysis and batch verification.
  • Metrics: Accuracy, MIR scores computed during evaluation; individual chord accuracy available.

Section sources

Dependency Analysis

The BTC training pipeline depends on:

  • PyTorch for model definition and training loops
  • NumPy/Pandas for data handling
  • mir_eval for chord evaluation
  • Kubernetes Jobs for orchestration
graph TB
BTC["BTC_model"] --> Torch["PyTorch"]
Train["train_btc.py"] --> BTC
Train --> Torch
Train --> Numpy["NumPy/Pandas"]
Train --> MirEval["mir_eval"]
K8s["train_btc.yaml"] --> Train
Loading

Diagram sources

Section sources

Performance Considerations

  • GPU Memory Optimization: Batch GPU caching, prefetch factors, and lazy initialization reduce memory pressure.
  • Dataset Caching: Metadata-only or full caching reduces I/O overhead; cache fractions can be tuned.
  • Dropout and Model Depth: Configurable dropout and attention layers balance capacity and generalization.
  • Curriculum Warmup: Stabilizes early training and improves convergence speed.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Missing teacher logits: When KD is enabled but logits are absent, the pipeline falls back to CE; verify logits_dir paths.
  • Data loader empty: Ensure spectrogram and label directories contain matching files; verify dataset_type and paths.
  • GPU memory errors: Reduce batch size, enable metadata cache, or disable cache to lower memory footprint.
  • Checkpoint loading: Use load_checkpoint with reset_epoch/reset_scheduler flags to control state restoration.

Section sources

Conclusion

The BTC training methodology integrates supervised and pseudo-label paradigms with knowledge distillation and curriculum learning. The modular design enables flexible configurations, robust data handling, and scalable training via Kubernetes. The inference module ensures seamless deployment for production environments, while evaluation utilities support continuous monitoring and improvement.

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

Appendices

Practical Training Execution Examples

  • Single-GPU BTC Training (SL/PL/KD): Use train_btc.yaml to launch a Kubernetes job with environment overrides for dataset type, LR schedule, KD, and focal loss.
  • Fine-tuning with Real Labels: Use finetune_labeled.yaml to run fine-tuning with pre-computed logits and real labels, enabling cross-validation and evaluation.

Section sources

Checkpoint Management and Monitoring

  • Centralized Checkpoints: Use save_dir to specify checkpoint locations; subdirectories can organize runs.
  • Best Model Selection: Jobs save best checkpoints; loading supports reset_epoch and reset_scheduler flags.
  • Monitoring: Logging verbosity and evaluation metrics provide insights into training progress.

Section sources

Trade-offs: Size, Accuracy, Efficiency

  • Model Size: Hidden size, number of layers, and heads influence accuracy and latency.
  • Accuracy: Large vocabulary (170 chords) improves expressiveness; KD with teacher logits enhances generalization.
  • Computational Efficiency: Dropout, attention heads, and caching strategies balance speed and memory usage.

[No sources needed since this section provides general guidance]

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