Implementation:Recommenders team Recommenders NextItNet Iterator

Knowledge Sources	Recommenders
Domains	Recommendation Systems, Sequential Modeling, Data Loading
Last Updated	2026-02-10 00:00 GMT

Overview

NextItNetIterator is a specialized data iterator for the NextItNet model that generates training targets for every position in a sequence rather than only the last item.

Description

The NextItNetIterator class extends SequentialIterator and overrides the __init__ and _convert_data methods to support NextItNet's unique generative training paradigm. Unlike standard sequential recommendation models that only predict the next item after the final position, NextItNet predicts every item in the sequence, requiring a fundamentally different data preparation approach.

During training (when batch_num_ngs > 0), the _convert_data method creates target labels and items for the entire sequence. For each positive instance, the positive items are constructed as the shifted history sequence (positions 1 through end) plus the actual next item. Negative items are randomly sampled from other instances in the batch, ensuring they differ from the corresponding positive item at each position. This produces (sequence_length * train_num_ngs) target items per instance, enabling the model to learn predictions at every sequence position.

During evaluation (when batch_num_ngs = 0), the iterator uses right-aligned padding (items placed at the end of the fixed-length array) instead of the base SequentialIterator's left-aligned approach. This distinction is important for NextItNet's convolutional architecture which processes sequences from left to right.

The iterator also handles temporal features including time_diff, time_from_first_action, and time_to_now, consistent with the parent SequentialIterator.

Usage

Use NextItNetIterator when training or evaluating the NextItNet model. It is the required data component for NextItNet's generative training approach, where the model learns to predict items at every position in the user behavior sequence.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/models/deeprec/io/nextitnet_iterator.py
• Lines: 1-268

Signature

class NextItNetIterator(SequentialIterator):
    def __init__(self, hparams, graph, col_spliter="\t"):

    def _convert_data(
        self,
        label_list,
        user_list,
        item_list,
        item_cate_list,
        item_history_batch,
        item_cate_history_batch,
        time_list,
        time_diff_list,
        time_from_first_action_list,
        time_to_now_list,
        batch_num_ngs,
    ):
        # Returns: dict

Import

from recommenders.models.deeprec.io.nextitnet_iterator import NextItNetIterator

I/O Contract

Inputs

Name	Type	Required	Description
hparams	object	Yes	Global hyper-parameters with user_vocab, item_vocab, cate_vocab, max_seq_length, and batch_size
graph	tf.Graph	Yes	The TensorFlow graph to which all created placeholders will be added
col_spliter	str	No	Column separator in one line (default: "\t")

Outputs

Name	Type	Description
_convert_data() (training)	dict	Dictionary with keys: labels (shape [batch*(1+ngs), seq_len]), users, items (shape [batch*(1+ngs), seq_len]), cates, item_history, item_cate_history, mask, time, time_diff, time_from_first_action, time_to_now
_convert_data() (evaluation)	dict	Dictionary with keys: labels (shape [-1, 1]), users, items (shape [-1, 1]), cates, item_history, item_cate_history, mask, time, time_diff, time_from_first_action, time_to_now

TensorFlow Placeholders

Placeholder	Shape	Type	Description
labels	[None, None]	tf.float32	Ground-truth labels; shape varies between training and evaluation
users	[None]	tf.int32	User indices
items	[None, None]	tf.int32	Item indices; multiple items per instance during training
cates	[None, None]	tf.int32	Category indices
item_history	[None, max_seq_length]	tf.int32	Item history sequence
item_cate_history	[None, max_seq_length]	tf.int32	Category history sequence
mask	[None, max_seq_length]	tf.int32	Mask for valid history positions
time	[None]	tf.float32	Current timestamp
time_diff	[None, max_seq_length]	tf.float32	Time differences between consecutive actions
time_from_first_action	[None, max_seq_length]	tf.float32	Time from first action in sequence
time_to_now	[None, max_seq_length]	tf.float32	Time from each action to current time

Key Differences from SequentialIterator

Aspect	SequentialIterator	NextItNetIterator
Prediction targets	Last item only	Every item in the sequence
Labels shape (training)	[-1, 1] scalar per instance	[batch, seq_len] per instance
Items shape (training)	Single item per instance	seq_len items per instance
Positive item construction	The next item from data	Shifted history + next item
Negative sampling	One negative per positive	seq_len negatives per positive
Padding alignment (eval)	Left-aligned (front)	Right-aligned (end)

Usage Examples

Basic Usage

import tensorflow as tf
from recommenders.models.deeprec.io.nextitnet_iterator import NextItNetIterator

# hparams must include:
#   hparams.user_vocab = "user_vocab.pkl"
#   hparams.item_vocab = "item_vocab.pkl"
#   hparams.cate_vocab = "cate_vocab.pkl"
#   hparams.max_seq_length = 50
#   hparams.batch_size = 32

graph = tf.Graph()
iterator = NextItNetIterator(hparams, graph)

# Load training data with negative sampling
train_file = "train_data.tsv"
for batch_input in iterator.load_data_from_file(train_file, batch_num_ngs=4):
    if batch_input is not None:
        # batch_input is a feed_dict with sequence-level labels and items
        # Labels shape: [batch_size * (1 + ngs), max_seq_length]
        pass

# Load evaluation data without negative sampling
test_file = "test_data.tsv"
for batch_input in iterator.load_data_from_file(test_file, batch_num_ngs=0):
    if batch_input is not None:
        # batch_input uses right-aligned padding
        pass