Implementation:Recommenders team Recommenders SVD NNI Training

Knowledge Sources	Recommenders
Domains	Hyperparameter Tuning, Matrix Factorization, NNI
Last Updated	2026-02-10 00:00 GMT

Overview

NNI trial script that trains and evaluates a Surprise SVD (Singular Value Decomposition) recommendation model with hyperparameters provided by the NNI automated tuning framework.

Description

This module serves as the NNI trial entry point for hyperparameter tuning of the Surprise SVD recommendation model. When executed as a main script, it retrieves hyperparameters from NNI via nni.get_next_parameter(), merges them with extensive command-line arguments covering all SVD parameters, and supports Hyperband's STEPS parameter for dynamic epoch allocation.

The svd_training function loads pickled train/validation DataFrames, creates a Surprise SVD model with the full set of tunable parameters including n_factors, individual learning rates (lr_all, lr_bu, lr_bi, lr_pu, lr_qi), and regularization parameters (reg_all, reg_bu, reg_bi, reg_pu, reg_qi). Training is performed on the full training set using Surprise's build_full_trainset(). Evaluation uses rating metrics (via the predict utility) and ranking metrics (via compute_ranking_predictions). Results are reported to NNI via nni.report_final_result() and saved as JSON.

The main function additionally saves the trained SVD model to disk via surprise.dump.dump for later retrieval.

Usage

Use this module as the trial code file in an NNI experiment configuration for tuning SVD hyperparameters. It is designed to be launched by NNI's trial scheduler. The extensive parameter set (14+ tunable hyperparameters) makes it well-suited for automated search strategies like TPE, random search, or Hyperband.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/tuning/nni/svd_training.py
• Lines: 1-185

Signature

def svd_training(params)

def get_params()

def main(params)

Import

from recommenders.tuning.nni.svd_training import svd_training, get_params, main

I/O Contract

Inputs

svd_training

Name	Type	Required	Description
params	dict	Yes	Dictionary containing all training configuration including: "datastore" (str), "train_datapath" (str), "validation_datapath" (str), "surprise_reader" (str), "usercol" (str), "itemcol" (str), "rating_metrics" (list), "ranking_metrics" (list), "k" (int), "primary_metric" (str), "remove_seen" (bool), plus SVD hyperparameters

get_params (command-line arguments)

Name	Type	Required	Description
--datastore	str	Yes	Path to the data directory
--train-datapath	str	Yes	Relative path to the pickled training data
--validation-datapath	str	Yes	Relative path to the pickled validation data
--surprise-reader	str	Yes	Surprise Reader rating scale specification
--usercol	str	No	User column name (default: "userID")
--itemcol	str	No	Item column name (default: "itemID")
--rating-metrics	str (nargs)	No	List of rating metric names
--ranking-metrics	str (nargs)	No	List of ranking metric names
--k	int	No	Top-K for ranking metrics
--epochs	int	No	Number of training epochs (default: 30)
--n_factors	int	No	Number of latent factors (default: 100)
--lr_all	float	No	Global learning rate (default: 0.005)
--reg_all	float	No	Global regularization term (default: 0.02)
--primary-metric	str	No	Primary metric name for NNI (default: "rmse")

Outputs

Name	Type	Description
return (svd_training)	surprise.SVD	The trained Surprise SVD model object
NNI report	dict	Metrics dictionary reported to NNI via nni.report_final_result()
metrics.json	file	JSON file with evaluation metrics written to NNI_OUTPUT_DIR
model.dump	file	Serialized SVD model saved to NNI_OUTPUT_DIR (from main function)

Usage Examples

Basic Usage

# This module is typically executed by NNI as a trial script.
# In an NNI config YAML:
# trial:
#   command: python svd_training.py --datastore /data --train-datapath train.pkl --validation-datapath val.pkl --surprise-reader "ml-100k" --rating-metrics rmse mae --primary-metric rmse
#   codeDir: .

# Programmatic usage (for testing):
from recommenders.tuning.nni.svd_training import svd_training

params = {
    "datastore": "/path/to/data",
    "train_datapath": "train.pkl",
    "validation_datapath": "val.pkl",
    "surprise_reader": "ml-100k",
    "usercol": "userID",
    "itemcol": "itemID",
    "n_factors": 100,
    "n_epochs": 30,
    "random_state": 42,
    "verbose": False,
    "biased": True,
    "init_mean": 0.0,
    "init_std_dev": 0.1,
    "lr_all": 0.005,
    "reg_all": 0.02,
    "lr_bu": None, "lr_bi": None, "lr_pu": None, "lr_qi": None,
    "reg_bu": None, "reg_bi": None, "reg_pu": None, "reg_qi": None,
    "rating_metrics": ["rmse", "mae"],
    "ranking_metrics": [],
    "k": 10,
    "primary_metric": "rmse",
    "remove_seen": True,
}

svd_model = svd_training(params)