This is the original theano implementation of the algorithm of the paper "Session-based Recommendations With Recurrent Neural Networks", with the extensions introduced in the paper "Recurrent Neural Networks with Top-k Gains for Session-based Recommendations".
Make sure to always use the latest version as baseline and cite both papers when you do so!
The code was optimized for fast execution on the GPU (up to 1500 mini-batch per second on a GTX 1080Ti). According to the Theano profiler, training spends 97.5% of the time on the GPU (0.5% on CPU and 2% moving data between the two). Running on the CPU is not supported, but it is possible with some modificatons to the code.
Parameters of the experiments on the Recsys Challenge 2015 (RSC15) dataset - that is reported in the paper - can be found in
examples/rsc15/run_rsc15.py and in
You can train and evaluate the model on your own session data easily using
run.py. Usage information below.
LICENSE: See license.txt for details. Main guidelines: for research and education purposes the code is and always will be free to use. Using the code or parts of it in commercial systems requires a licence. If you've been using the code or any of its derivates in a commercial system, contact me!
Execute experiments using
Using GRU4Rec in code or the interpreter
Notes on sequence-aware vs. session-based models
Reproducing experiments on RSC15
Speed of training
Executing on CPU
- python --> Use python
3.6.3or newer. The code was mostly tested on
3.7.6, but was briefly tested on other versions. Python 2 is NOT supported.
- numpy -->
- pandas -->
- CUDA --> Needed for the GPU support of Theano. The latest CUDA version Theano was tested with (to the best of my knowledge) is
9.2. Might work with more recent ones, but I advise to use
- libgpuarray --> Required for the GPU support of Theano, use the latest version.
- theano -->
1.0.4(last stable release) or newer (occassionally it is still updated with minor stuff). GPU support should be installed.
Note on cuDNN --> More recent versions produce a warning, but
7.6.4 still works for me. GRU4Rec doesn't rely heavily on the part of Theano that utilizes cuDNN. With cuDNN
v7, some of the operators are SLOWER when the cuDNN version is used (e.g. see here). Therefore some related optimizations should be excluded in the configuration (see below).
This code was optimized for GPU execution. This means that beside execution on the CPU might be slower than what is achievable, execution will fail if you try to directly run it on CPU (if you really want to mess with it, check out the relevant section of this readme). Therefore Theano configuration must be set in a way to use the GPU. If you use
run.py for runnning experiments, the code sets this configuration for you. You might want to change some of the preset configuration (e.g. execute on a specified GPU instead of the one with the lowest Id). You can do this in the
THEANO_FLAGS environment variable or edit
If you don't use
run.py, it is possible that the preset config won't have any effect (this happens if theano is imported before
gru4rec either directly or by another module). In this case, you must set your own config by either editing your
.theanorc or setting up the
THEANO_FLAGS environment variable. Please refer to the documentation of Theano.
Important config parameters
device--> must always be a CUDA capable GPU (e.g.
floatX--> must always be
mode--> should be
FAST_RUNfor fast execution
optimizer_excluding--> should be
local_dnn_reduction:local_cudnn_maxandargmax:local_dnn_argmaxto tell Theano not to use the relevant cuDNN optimizations that are slow if you have cuDNN
Execute experiments using
run.py is an easy way to train, evaluate and save/load GRU4Rec models.
Execute with the
-h argument to take a look at the parameters.
$ python run.py -h
usage: run.py [-h] [-ps PARAM_STRING] [-pf PARAM_PATH] [-l] [-s MODEL_PATH] [-t TEST_PATH [TEST_PATH ...]] [-m AT [AT ...]] [-e EVAL_TYPE] [-ss SS] [--sample_store_on_cpu] [--test_against_items N_TEST_ITEMS] PATH Train or load a GRU4Rec model & measure recall and MRR on the specified test set(s). positional arguments: PATH Path to the training data (TAB separated file (.tsv or .txt) or pickled pandas.DataFrame object (.pickle)) (if the --load_model parameter is NOT provided) or to the serialized model (if the --load_model parameter is provided). optional arguments: -h, --help show this help message and exit -ps PARAM_STRING, --parameter_string PARAM_STRING Training parameters provided as a single parameter string. The format of the string is `param_name1=param_value1,param_name2=param_value2...`, e.g.: `loss=bpr-max,layers=100,constrained_embedding=True`. Boolean training parameters should be either True or False; parameters that can take a list should use / as the separator (e.g. layers=200/200). Mutually exclusive with the -pf (--parameter_file) and the -l (--load_model) arguments and one of the three must be provided. -pf PARAM_PATH, --parameter_file PARAM_PATH Alternatively, training parameters can be set using a config file specified in this argument. The config file must contain a single OrderedDict named `gru4rec_params`. The parameters must have the appropriate type (e.g. layers = ). Mutually exclusive with the -ps (--parameter_string) and the -l (--load model) arguments and one of the three must be provided. -l, --load_model Load an already trained model instead of training a model. Mutually exclusive with the -ps (--parameter_string) and the -pf (--parameter_file) arguments and one of the three must be provided. -s MODEL_PATH, --save_model MODEL_PATH Save the trained model to the MODEL_PATH. (Default: don't save model) -t TEST_PATH [TEST_PATH ...], --test TEST_PATH [TEST_PATH ...] Path to the test data set(s) located at TEST_PATH. Multiple test sets can be provided (separate with spaces). (Default: don't evaluate the model) -m AT [AT ...], --measure AT [AT ...] Measure recall & MRR at the defined recommendation list length(s). Multiple values can be provided. (Default: 20) -e EVAL_TYPE, --eval_type EVAL_TYPE Sets how to handle if multiple items in the ranked list have the same prediction score (which is usually due to saturation or an error). See the documentation of evaluate_gpu() in evaluation.py for further details. (Default: standard) -ss SS, --sample_store_size SS GRU4Rec uses a buffer for negative samples during training to maximize GPU utilization. This parameter sets the buffer length. Lower values require more frequent recomputation, higher values use more (GPU) memory. Unless you know what you are doing, you shouldn't mess with this parameter. (Default: 10000000) --sample_store_on_cpu If provided, the sample store will be stored in the RAM instead of the GPU memory. This is not advised in most cases, because it significantly lowers the GPU utilization. This option is provided if for some reason you want to train the model on the CPU (NOT advised). --test_against_items N_TEST_ITEMS It is NOT advised to evaluate recommender algorithms by ranking a single positive item against a set of sampled negatives. It overestimates recommendation performance and also skewes comparisons, as it affects algorithms differently (and if a different sequence of random samples is used, the results are downright uncomparable). If testing takes too much time, it is advised to sample test sessions to create a smaller test set. However, if the number of items is very high (i.e. ABOVE FEW MILLIONS), it might be impossible to evaluate the model within a reasonable time, even on a smaller (but still representative) test set. In this case, and this case only, one can sample items to evaluate against. This option allows to rank the positive item against the N_TEST_ITEMS most popular items. This has a lesser effect on comparison and it is a much stronger criteria than ranking against randomly sampled items. Keep in mind that the real performcance of the algorithm will still be overestimated by the results, but comparison will be mostly fair. If used, you should NEVER SET THIS PARAMETER BELOW 50000 and try to set it as high as possible (for your required evaluation time). (Default: all items are used as negatives for evaluation)
Train and evaluate a model measuring recall and MRR at 1, 5, 10 and 20 using model parameters from a parameter string.
$ python run.py /path/to/training_data_file -t /path/to/test_data_file -m 1 5 10 20 -ps loss=bpr-max,final_act=elu-0.5,hidden_act=tanh,layers=100,adapt=adagrad,n_epochs=10,batch_size=32,dropout_p_embed=0.0,dropout_p_hidden=0.0,learning_rate=0.2,momentum=0.3,n_sample=2048,sample_alpha=0.0,bpreg=1.0,constrained_embedding=False
Output (using the RSC15 data). The value of the loss, the time of the computations and the speed of data processing (mini-batch/second & event/second) are printed on the output in each epoch.
Using cuDNN version 7604 on context None Mapped name None to device cuda0: GeForce GTX 1080 Ti (0000:02:00.0) SET loss TO bpr-max (type: <class 'str'>) SET final_act TO elu-0.5 (type: <class 'str'>) SET hidden_act TO tanh (type: <class 'str'>) SET layers TO  (type: <class 'list'>) SET adapt TO adagrad (type: <class 'str'>) SET n_epochs TO 10 (type: <class 'int'>) SET batch_size TO 32 (type: <class 'int'>) SET dropout_p_embed TO 0.0 (type: <class 'float'>) SET dropout_p_hidden TO 0.0 (type: <class 'float'>) SET learning_rate TO 0.2 (type: <class 'float'>) SET momentum TO 0.3 (type: <class 'float'>) SET n_sample TO 2048 (type: <class 'int'>) SET sample_alpha TO 0.0 (type: <class 'float'>) SET bpreg TO 1.0 (type: <class 'float'>) SET constrained_embedding TO False (type: <class 'bool'>) Loading training data... Loading data from TAB separated file: /path/to/training_data_file Started training The dataframe is already sorted by SessionId, Time Created sample store with 4882 batches of samples (type=GPU) Epoch1 --> loss: 0.257018 (624.72s) [1184.16 mb/s | 37890 e/s] Epoch2 --> loss: 0.244611 (650.60s) [1137.06 mb/s | 36383 e/s] Epoch3 --> loss: 0.242729 (646.23s) [1144.74 mb/s | 36629 e/s] Epoch4 --> loss: 0.241872 (652.75s) [1133.31 mb/s | 36263 e/s] Epoch5 --> loss: 0.241344 (646.70s) [1143.92 mb/s | 36603 e/s] Epoch6 --> loss: 0.240963 (658.08s) [1124.13 mb/s | 35970 e/s] Epoch7 --> loss: 0.240663 (629.93s) [1174.37 mb/s | 37577 e/s] Epoch8 --> loss: 0.240424 (630.64s) [1173.04 mb/s | 37535 e/s] Epoch9 --> loss: 0.240225 (655.66s) [1128.28 mb/s | 36102 e/s] Epoch10 --> loss: 0.240039 (632.79s) [1169.06 mb/s | 37407 e/s] Total training time: 6453.16s Loading test data... Loading data from TAB separated file: /path/to/test_data_file Starting evaluation (cut-off=1, using standard mode for tiebreaking) Measuring Recall@1 and MRR@1 Evaluation took 3.99s Recall@1: 0.178593 MRR@1: 0.178593 Starting evaluation (cut-off=5, using standard mode for tiebreaking) Measuring Recall@5 and MRR@5 Evaluation took 2.24s Recall@5: 0.481448 MRR@5: 0.288218 Starting evaluation (cut-off=10, using standard mode for tiebreaking) Measuring Recall@10 and MRR@10 Evaluation took 2.21s Recall@10: 0.613027 MRR@10: 0.305961 Starting evaluation (cut-off=20, using standard mode for tiebreaking) Measuring Recall@20 and MRR@20 Evaluation took 2.24s Recall@20: 0.720044 MRR@20: 0.313504
Train and save using model parameters from a parameter file (using different parameters than in the previous example).
$ python run.py /path/to/training_data_file -pf /path/to/parameter_file.py -s /path/to/save_model.pickle
Output (using the RSC15 data). Notice that the speed is similar in terms of mini-batch/second, but it is almost twice as fast in terms of event/second (and training time is almost halved). This is due to using larger mini-batches (
batch_size=64). Mini-batch processing degrades very slowly as
batch_size is increased, which means that event processing is much faster when larger mini-batches are used. Unfortunately, the results are usually better with smaller mini-batches (depens on the dataset and sometimes also on the loss).
Using cuDNN version 7604 on context None Mapped name None to device cuda0: GeForce GTX 1080 Ti (0000:02:00.0) Loaded parameters from file: /path/to/parameter_file.py SET layers TO  (type: <class 'list'>) SET loss TO cross-entropy (type: <class 'str'>) SET final_act TO softmax (type: <class 'str'>) SET hidden_act TO tanh (type: <class 'str'>) SET adapt TO adagrad (type: <class 'str'>) SET n_epochs TO 10 (type: <class 'int'>) SET batch_size TO 64 (type: <class 'int'>) SET dropout_p_embed TO 0.0 (type: <class 'float'>) SET dropout_p_hidden TO 0.4 (type: <class 'float'>) SET learning_rate TO 0.2 (type: <class 'float'>) SET momentum TO 0.2 (type: <class 'float'>) SET sample_alpha TO 0.5 (type: <class 'float'>) SET n_sample TO 2048 (type: <class 'int'>) SET logq TO 1.0 (type: <class 'float'>) SET constrained_embedding TO True (type: <class 'bool'>) Loading training data... Loading data from TAB separated file: /path/to/training_data_file Started training The dataframe is already sorted by SessionId, Time Created sample store with 4882 batches of samples (type=GPU) Epoch1 --> loss: 7.180416 (334.48s) [1105.96 mb/s | 70769 e/s] Epoch2 --> loss: 6.916848 (348.47s) [1061.56 mb/s | 67928 e/s] Epoch3 --> loss: 6.889819 (341.80s) [1082.29 mb/s | 69254 e/s] Epoch4 --> loss: 6.876406 (353.20s) [1047.35 mb/s | 67018 e/s] Epoch5 --> loss: 6.868563 (353.45s) [1046.60 mb/s | 66971 e/s] Epoch6 --> loss: 6.864311 (380.97s) [971.01 mb/s | 62133 e/s] Epoch7 --> loss: 6.866572 (362.07s) [1021.68 mb/s | 65376 e/s] Epoch8 --> loss: 6.883779 (341.96s) [1081.78 mb/s | 69222 e/s] Epoch9 --> loss: 6.906769 (342.22s) [1080.96 mb/s | 69169 e/s] Epoch10 --> loss: 6.919822 (366.92s) [1008.20 mb/s | 64513 e/s] Total training time: 3568.13s Saving trained model to: /path/to/save_model.pickle
Load a previously trained model and evaluate it measuring recall and MRR at 1, 5, 10 and 20 using the conservative method for tiebreaking.
$ python run.py /path/to/previously_saved_model.pickle -l -t /path/to/test_data_file -m 1 5 10 20 -e conservative
Output (using the RSC15 data)
Using cuDNN version 7604 on context None Mapped name None to device cuda0: GeForce GTX 1080 Ti (0000:02:00.0) Loading trained model from file: /path/to/previously_saved_model.pickle Loading test data... Loading data from TAB separated file: /path/to/test_data_file Starting evaluation (cut-off=1, using conservative mode for tiebreaking) Measuring Recall@1 and MRR@1 Evaluation took 11.40s Recall@1: 0.166035 MRR@1: 0.166035 Starting evaluation (cut-off=5, using conservative mode for tiebreaking) Measuring Recall@5 and MRR@5 Evaluation took 2.55s Recall@5: 0.476976 MRR@5: 0.279910 Starting evaluation (cut-off=10, using conservative mode for tiebreaking) Measuring Recall@10 and MRR@10 Evaluation took 2.54s Recall@10: 0.609664 MRR@10: 0.297743 Starting evaluation (cut-off=20, using conservative mode for tiebreaking) Measuring Recall@20 and MRR@20 Evaluation took 2.55s Recall@20: 0.718756 MRR@20: 0.305424
Using GRU4Rec in code or the interpreter
You can simply import the
gru4rec module in your code or in an interpreter and use the
GRU4Rec class to create and train models. The trained models can be evaluated by importing the
evaluation module and using either the
evaluate_gpu or the
evaluate_session_batch method. The latter is deprecated and doesn't fully utilize the GPU and is therefore significantly slower. The public version of this code is mainly for running experiments (training and evaluating the algorithm on different datasets), therefore retrieving the actual predictions can be cumbersome and ineffective.
IMPORTANT! For the sake of convenience, the
gru4rec module sets some important Theano parameters so that you don't have to worry about them if you are not familiar with Theano. But this only has any effect if
gru4rec is imported BEFORE Theano (or any module that imports Theano) is imported. (Because once Theano is initialized, most of its configuration can't be changed. And even if Theano is reimported, the GPU is not reinitialized.) If you do it the other way around, you should set your default
.theanorc or provide the
THEANO_FLAGS environment variable with the appropriate configuration.
Notes on sequence-aware vs. session-based models
GRU4Rec is originally for session-based recommendations, where the generally short sessions are considered independent. Every time a user comes to the site, they are considered to be unknown, i.e. nothing of their history is used, even if it is known. (This setup is great for many real-life applications.) This means that when the model is evaluated, the hidden state starts from zero for each test session.
However, RNN (CNN, Transformer, etc.) based models are also a great fit for the practically less important sequance-aware personalized recommendation setup (i.e. the whole user history is used as a sequence to predict future items in the sequence). There are two main differences:
- (1) The sequences are significantly longer in sequence-aware recommendations. This also means that BPTT (backpropagation through time) is useful in this scenario. For session-based recommendations, experiments suggest that BPTT doesn't improve the model.
- (2) Evaluation in the sequence-aware setup should be started from the last value of the hidden state (i.e. the value computed on the training portion of the user history).
Currently, neither of these are supported in the public code. These functionalities might be added later (they exist in some of my internal research repos). At the moment, you have to extend the code yourself to do this.
Reproducing experiments on RSC15
- Download the dataset (
yoochoose-clicks.dat) of the RecSys Challenge 2015 from the competitions's website.
- Preprocess it with
examples/rsc15/preprocess.pyto get two train/test splits: the
train_validsplit can be used for hyperparameter optimization; final results are measured on the
- Use either
run.pywith parameters stored in
param_samplesOR check out
examples/rsc15/run_rsc15.pyand run the appropriate code section.
Speed of training
The training time mostly depends on the number of events and the model parameters. The following parameters affect the processing speed of events (event/s):
batch_size--> The processing speed of batches (mb/s) decreases much slower than the size increase of the batch, therefore event processing speeds up as
batch_sizealso affects model accuracy and smaller batches are usually better for most datasets.
n_sample--> The number of negative samples up to 500-1000 doesn't affect processing speed (depending on the hardware). The default is
n_sample=2048, but if the number of items is low, it might be lowered without loss of accuracy.
cross-entropyis somewhat faster than
momentum--> setting these to other than 0, training will be a little bit slower
Training speeds measured executing on a GTX 1080Ti (
*Compared to the previously published public version
Executing on CPU
Some optimizations for speeding up GPU execution (e.g. custom Theano operators) prevent running the code on CPU. Since CPU execution of neural networks is already slow, I decided to abandon CPU support to speed up execution on GPU. If - for some reason - you still want to run GRU4Rec on the CPU, you need to modify the code to disable the custom GPU optimizations. You will be able to run the code on CPU, just don't expect it to be quick.
Steps of disabling the custom GPU optimizations:
disable_custom_op = True. This makes the functions in
gpu_opsto return stnadard operators or operators assembled from standard operators, instead of the custom ones when the computational graph is computed.
gru4rec.pycomment out line
import custom_opt. One of the custom operators is integrated deeper into Theano through
custom_opt, which adds it to the optimizer that replaces operators in the computational graph. By removing this import, this operator won't be used.
- Significant speed-up of the training by increasing GPU utilization.
- logQ normalization added (improves results when cross-entropy loss is used)
run.pyfor easy experimentation.
- Extended this README.
- Refactor and cleaning.
- Speeding up execution.
- Ease of life improvements.
- Code for evaluating on GPU.
- Upgraded to the v2.0 version
- Added BPR-max and TOP1-max losses for cutting edge performance (coupled with additional sampling +30% in recall & MRR over the base results)
- Sacrificed some speed on CPU for faster GPU execution
- Fixed cross-entropy unstability. Very small predicted scores were rounded to 0 and thus their logarithm became NaN. Added a small epsilon (1e-24) to all scores before computing the logarithm. I got better results with this stabilized cross-entropy than with the TOP1 loss on networks with 100 hidden units.
- Added the option of using additional negative samples (besides the default, which is the other examples in the minibatch). The number of additional samples is given by the n_sample parameter. The probability of an item choosen as a sample is supp^sample_alpha, i.e. setting sample_alpha to 1 results in popularity based sampling, setting it to 0 results in uniform sampling. Using additional samples can slow down training, but depending on your config, the slowdown might not be noticable on GPU, up to 1000-2000 additional samples.
- Added an option to training to precompute a large batch of negative samples in advance. The number of int values (IDs) to be stored is determined by the sample_store parameter of the train function (default: 10M). This option is for the additional negative samples only, so only takes effect when n_sample > 0. Computing negative samples in each step results in very inefficient GPU utilization as computations are often interrupted by sample generation (which runs on the CPU). Precomputing samples for several steps in advance makes the process more efficient. However one should avoid setting the sample store too big as generating too many samples takes a long time, resulting in the GPU waiting for its completion for a long time. It also increases the memory footprint.
- Optimized code for GPU execution. Training is ~2x faster now.
- Added retrain functionality.