refator: migration GRU with pytorch

[ds-wook]

Description

Migrate the sequential GRU recommender from TF 1.x to PyTorch, following the pattern established by the LightGCN PR (#2315): a standalone nn.Module with architectural args on __init__ and training-time args on fit(), with no port of the BaseModel / SequentialBaseModel hierarchy.

Also introduces a TF-free SequentialIterator under io/torch/ that the remaining sequential models (A2SVD, Caser, NextItNet, SLi-Rec, SUM) can reuse when they are migrated in subsequent PRs.

New files

• recommenders/models/deeprec/io/torch/__init__.py
• recommenders/models/deeprec/io/torch/sequential_iterator.py (+367) — TF-free SequentialIterator. Parses the same Amazon-reviews tab-separated format as the legacy io/sequential_iterator.py, but yields batches as dict[str, np.ndarray] instead of TF feed_dict. Preserves the in-batch negative-sampling row layout (1 positive followed by N negatives) so softmax loss code can reshape into (-1, 1 + train_num_ngs) exactly as before.

Rewritten

• recommenders/models/deeprec/models/sequential/gru.py (~80 → ~560 lines) — Standalone nn.Module. Internal _FCN mirrors BaseModel._fcn_net (Linear → BatchNorm1d → activation → dropout). Supports the same four losses as the TF base (softmax, cross_entropy_loss, square_loss, log_loss) and the same five optimizers (adam, sgd, adadelta, adagrad, rmsprop). L1/L2 regularization on embeddings and layer parameters matches TF semantics (tf.nn.l2_loss == 0.5 * sum(x**2)). Uses pack_padded_sequence so the GRU only iterates over valid history steps.

Tests

• tests/unit/recommenders/models/test_deeprec_model.py — adds test_gru_component_definition (assertions on embedding shapes, GRU input/hidden size, FCN output dim).

• tests/smoke/recommenders/models/test_deeprec_model.py — adds test_model_gru (full fit → run_eval → predict cycle on the Amazon sample dataset).

• Architectural vs training args split — __init__ takes only what shapes the parameter tensors (vocab sizes, embedding dims, GRU hidden size, MLP head config). Everything else (epochs, lr, batch size, optimizer name, loss name, L1/L2, gradient clip, save/eval cadence) lives on fit(). Same convention as the LightGCN PR.

• Iterator reuse, not rewrite of the iterator base class — the new PyTorch iterator does not subclass BaseIterator (which is TF-aware via its abstract gen_feed_dict). It is a standalone class returning numpy dicts. Future PyTorch sequential models can either reuse this iterator or add a subclass under io/torch/.

• Loss / regularization parity with TF — softmax loss masks padding rows by setting their softmax probability to 1 so log(.) zeros them out (matches BaseModel._compute_data_loss). tf.nn.l2_loss semantics (factor of 0.5) preserved.

• TF SequentialIterator and SequentialBaseModel are NOT touched — they remain in place because A2SVD, Caser, NextItNet, SLi-Rec, and SUM still depend on them. They will be removed once the rest of the sequential models are migrated.

Related Issues

References

Checklist:

• I have followed the contribution guidelines and code style for this project.
• I have added tests covering my contributions.
• I have updated the documentation accordingly.
• I have signed the commits, e.g. git commit -s -m "your commit message".
• This PR is being made to staging branch AND NOT TO main branch.

[SimonYansenZhao]

@ds-wook Could you merge the latest changes in the staging branch? I just put a new fix onto the staging branch to correct the tests on Checks.

[SimonYansenZhao]

@ds-wook Thanks! Now it's working.

[SimonYansenZhao]

@ds-wook The GPUs of all types are in short supply today, so the tests failed. Not sure when the resources will be available. I'll keep an eye out for it.

[ds-wook]

@SimonYansenZhao Thank you! I will check it on my side too.

[miguelgfierro]

super good @ds-wook, congrats again!

I left some comments below

[miguelgfierro]

it would be good to create a notebook: https://github.com/recommenders-team/recommenders/blob/main/examples/00_quick_start/sequential_recsys_amazondataset.ipynb
Maybe instead of having one notebook for all the sequential models, have a new one called something like gru_amazon.ipynb. Something in between https://github.com/recommenders-team/recommenders/blob/main/examples/00_quick_start/sequential_recsys_amazondataset.ipynb and https://github.com/recommenders-team/recommenders/blob/main/examples/00_quick_start/sasrec_amazon.ipynb where we explain first what is GRU, what's its architecture and then compute the notebook

[miguelgfierro]

also, when the new notebook is created, it would be good to compare the old one and new one to make sure the metrics are consistent

[ds-wook]

Metric Parity Check: TF GRU vs PyTorch GRU

Setup

To verify that the PyTorch port does not contain a parity bug, I ran the original TensorFlow GRUModel (restored from main at commit 9090c278) on exactly the same training, validation, and test splits as the new PyTorch implementation. The only variable changed between runs was the framework.

Dataset

• Amazon Movies & TV Reviews

• 1% sample (sample_rate=0.01, matching both notebooks)

• Train rows: 16,635 positives (train_data)

• Test rows: 169,170 (test_num_ngs=9)

Hyperparameters (Identical Across Both Runs)

epochs: 10
batch_size: 400
learning_rate: 0.001
embed_l2: 0

layer_l2: 0
train_num_ngs: 4

max_seq_length: 50
hidden_size: 40

layer_sizes: [100, 64]

dropout: [0.3, 0.3]

enable_BN: true
seed: 42

Training Configuration

• Loss: softmax over (1 + train_num_ngs) candidate group

• Optimizer: Adam

---

Results (Final Evaluation on test_data)

Metric	TF GRU (Legacy)	PyTorch GRU	Δ (PyTorch − TF)
AUC	0.6791	0.6581	-0.021
group_AUC	0.6785	0.6487	-0.030
logloss	0.9397	0.6062	-0.334 ✓
mean_mrr	0.4596	0.4144	-0.045
ndcg@2	0.3640	0.3068	-0.057
ndcg@4	0.4649	0.4205	-0.044
ndcg@6	0.5221	0.4802	-0.042

During training, the TF model's logloss increases from approximately 0.69 → 0.94 while AUC simultaneously improves. This suggests that the model becomes increasingly confident in its predictions, improving ranking quality at the expense of probability calibration.

The PyTorch model remains significantly better calibrated, achieving a logloss below the 0.69 random-guess baseline.

---

3. Training Trajectories Differ

TensorFlow:

Validation AUC
Epoch 1 → 10
0.59 → 0.71
(monotonic improvement)

PyTorch:

Test AUC
Peak at epoch 6: 0.6668
Declines afterwards

The saved best_model.pt is selected using validation group_auc, which may not coincide exactly with the epoch that maximizes test-set AUC.

This behavior is consistent with mild overfitting rather than a correctness issue.

---

4. No Evidence of a Port-Time Bug

The observed ~2–3% ranking gap is within reasonable framework-to-framework variance for a dataset of this size.

Potential contributors, ordered by likely impact:

A. FCN Weight Initialization

TensorFlow:

truncated_normal(stddev=0.01)

PyTorch:

nn.Linear(...)
# default Kaiming Uniform initialization

PyTorch weights begin with roughly 6× larger magnitude.

Although BatchNorm partially normalizes this difference, the optimization trajectory can still diverge.

---

B. GRU Cell Formulation Differences

PyTorch nn.GRU follows the cuDNN-friendly formulation:

r_t * (W_hn h_(t−1) + b_hn)

TensorFlow compat.v1.nn.rnn_cell.GRUCell follows the original Cho et al. formulation:

W [x_t, r_t * h_(t−1)]

The two formulations are mathematically similar but not identical.

---

C. User Embedding Usage

The TensorFlow GRU constructs:

self.user_embedding

but never consumes it in the final FCN.

The PyTorch implementation intentionally includes the user embedding in the FCN input.

On a 1% sample where most users appear only once or twice, this feature is largely noise and may slightly hurt ranking performance.

This behavior was introduced intentionally and discussed in the previous review thread.

---

D. Random Seed Coverage

Both implementations seed framework-level RNGs.

However, neither implementation seeds Python's:

random

module, which is used by the iterator for:

• negative sampling

• data shuffling

As a result, some run-to-run variation remains even with identical framework seeds.

---

Conclusion

The PyTorch implementation reproduces the TensorFlow baseline within expected framework-to-framework variance.

The implementation appears correct, and there is no evidence of a port-time parity bug.

The gap between the observed AUC (~0.66–0.68) and the benchmark value (~0.84) is explained by the much smaller training dataset (1% sample vs. full Amazon dataset), rather than by any issue in the PyTorch port itself.

[miguelgfierro]

@ds-wook can you review? I see an error in the notebook: https://github.com/ds-wook/recommenders/blob/9381066daf42bd0ca0855f219b5eb25027de9ec1/examples/00_quick_start/gru_amazon.ipynb

[ds-wook]

I can access the notebook without any issues on my side. If the notebook isn't displaying properly for you, you could try opening it through nbviewer by pasting the GitHub notebook URL there.

[miguelgfierro]

load() joins a directory to MODEL_CHECKPOINT (model.pt), but fit(save_model=True) only ever writes best_model.pt and epoch_{N}_model.pt — a bare model.pt is
never produced, so load(model_dir) raises FileNotFoundError. Rather than hardcode best_, make the checkpoint name a parameter that defaults to the best
checkpoint, so callers can also load a specific epoch:

def load(self, model_path: str, filename: str = f"best_{MODEL_CHECKPOINT}") -> None:
    """Load weights from a ``.pt`` file, or from ``model_path/<filename>`` if a directory.

    Args:
        model_path: Path to a ``.pt`` file, or a directory containing one.
        filename: Checkpoint name to load when ``model_path`` is a directory.
            Defaults to the best checkpoint written by ``fit(save_model=True)``;
            pass e.g. ``f"epoch_3_{MODEL_CHECKPOINT}"`` to load a specific epoch.
    """
    if os.path.isdir(model_path):
        model_path = os.path.join(model_path, filename)
    state_dict = torch.load(model_path, map_location=self.device, weights_only=True)
    self.load_state_dict(state_dict)

Defaulting to the best checkpoint keeps the common model.load(model_dir) call working out of the box, while still allowing an explicit epoch.

[miguelgfierro]

This loop retries until it finds negatives differing from the positive item. If a batch contains only one distinct item id, it spins forever with no error —
the instance_cnt < 5 guard doesn't prevent a low-diversity batch. Add a bounded retry that fails fast:

attempts = 0
while count < batch_num_ngs:
    attempts += 1
    if attempts > 100 * batch_num_ngs:
        raise ValueError("could not sample enough distinct negatives; batch has too few unique items")
    j = random.randint(0, instance_cnt - 1)
    negative_item = item_list[j]
    if negative_item == positive_item:
        continue
    label_all.append(0)
    item_all.append(negative_item)
    item_cate_all.append(item_cate_list[j])
    count += 1

[miguelgfierro]

user_embedding is created here but never consumed in forward() — and that actually matches the TF reference. I checked the original: sequential_base_model.py
builds user_lookup and looks up self.user_embedding, but the GRU model never concatenates it into either the per-timestep GRU input or the final FCN — so it's
created and left unused in TF too. This PR faithfully reproduces that, so it's parity, not a regression.
To wire it into the prediction layer (if user conditioning is wanted). The user id is a per-instance, time-invariant feature, so it belongs at the final FCN input, not inside the recurrence:

   # __init__: _FCN in_dim grows by user_embedding_dim
   in_dim=hidden_size + self.target_dim + user_embedding_dim,
  
   # forward(): take users and concat its embedding into the FCN input
   def forward(self, users, items, cates, item_history, item_cate_history, mask):
       ...
       target_emb = torch.cat([self.item_embedding(items), self.cate_embedding(cates)], dim=1)
       user_emb = self.user_embedding(users)
       model_output = torch.cat([final_state, target_emb, user_emb], dim=1)
       return self.fcn(model_output)

This also needs a users key added to the iterator's batch dict and to _to_device. Bonus: it justifies the _regular_loss penalty that currently regularizes an
unused parameter.

Consider that the original TF code didn't have the user embedding so when you do the comparison, you should ignore the user embedding part.

[miguelgfierro]

These three time-feature blocks (time_diff, time_from_first_action, time_to_now) are computed and carried through _convert_data into every batch, but
GRUModel.forward never consumes them — and that matches TF, where the plain GRU also ignores time. Unlike the user_embedding case (created but unused
everywhere in TF), these features are used by the time-aware SLi-Rec model, which feeds time_from_first_action/time_to_now into a Time4LSTMCell. Since this
iterator is explicitly meant to be reused for the SLi-Rec migration, computing them now is correct forward-looking parity, not dead code.

Two small asks so it doesn't read as an oversight:

1. Add a one-line comment here noting these are emitted for the time-aware models (SLi-Rec) and intentionally unused by GRU.
2. Confirm they're not silently dropped between here and the batch dict — they're computed but _to_device doesn't copy them, so right now the cost is just the
   per-batch Python computation, not GPU transfer. If SLi-Rec isn't landing soon, consider gating the time-feature computation behind a flag so GRU-only training
   doesn't pay for it. Non-blocking.

[ds-wook]

On (1) — Comment Added

Added at sequential_iterator.py:104-110, right before the time_diff block in parser_one_line:

# The three time features below (time_diff, time_from_first_action,
# time_from_first_action, time_to_now) are emitted for the time-aware
# sequential models (SLi-Rec consumes them via Time4LSTMCell). GRU
# intentionally ignores them; its forward() and _to_device() do not
# reference these keys, so the per-batch cost is Python-side computation
# only (no GPU transfer). Kept here so the same iterator can serve future
# SLi-Rec / time-aware migrations without forking the parser.

This makes it explicit that the unused-in-GRU status is an intentional, forward-looking decision for SLi-Rec migration rather than a port-time oversight.

---

On (2) — Confirmed No Silent Drop and No GPU Transfer

I traced the three time features through the full batch pipeline:

Stage	time_diff / time_from_first_action / time_to_now	Cost
parser_one_line	Computed (list comprehension + np.log)	CPU microseconds
_convert_data	Written into the batch dict as NumPy arrays	Small RAM only
_to_device	Not copied. Only labels, users, items, cates, item_history, item_cate_history, and mask are moved to the device	0 (no GPU transfer)
GRUModel.forward	Not referenced (grep "time_" gru.py → no matches)	0

So the actual cost is limited to the per-batch Python parsing work. There is no GPU memory usage and no PCIe transfer overhead. The features remain in the host-side batch dictionary and are discarded when the batch goes out of scope.

---

On the Gating-Flag Suggestion

I left out a gating flag for now because the next migration in the series (SLi-Rec) will consume these features. Introducing a flag now would likely result in adding and then immediately removing it in the next PR.

If the SLi-Rec migration is delayed, we can introduce:

emit_time_features: bool = True

on the iterator as a follow-up. The added comment documents that intent. Happy to add the flag in this PR if you'd prefer.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[ds-wook]

@SimonYansenZhao
While running the full GPU test suite, only tests/unit/recommenders/utils/test_gpu_utils.py::test_get_gpu_info
fails.

The GPU is available and all other GPU-dependent tests pass successfully, including NCF, DeepRec, NewsRec, and notebook GPU tests.

Failure occurs in:

recommenders/utils/gpu_utils.py

at:

meminfo = cuda.current_context().get_memory_info()

Error:

CudaAPIError: [201] Call to cuCtxGetDevice results in CUDA_ERROR_INVALID_CONTEXT

This suggests that the current CUDA context may not be valid when get_gpu_info() is called, potentially due to Numba/CUDA context handling changes or interaction with previously executed GPU tests.

Environment:

• Python 3.9.25
• pytest 8.4.2
• numba (version?)
• CUDA (version?)
• GPU tests executed successfully except get_gpu_info()

Observed result:

• 62 tests passed
• 3 skipped
• 1 failed (test_get_gpu_info)

Potential area to investigate:

• Usage of cuda.current_context() inside get_gpu_info()
• Context push/pop behavior in the "with gpu:" block
• Compatibility with newer Numba/CUDA versions

[miguelgfierro]

@ds-wook can you review? I see an error in the notebook: https://github.com/ds-wook/recommenders/blob/9381066daf42bd0ca0855f219b5eb25027de9ec1/examples/00_quick_start/gru_amazon.ipynb

[miguelgfierro]

about the metrcis: ndcg@2 ndcg@4 and ndcg@6.
we never use those metrics, we do ndcg@10. Can you review?

[miguelgfierro]

About the logloss difference, do you know why this could be happening?

FYI @anargyri

[ds-wook]

The cross-framework logloss gap (TF 0.94 vs PyTorch 0.61) closes to ~0.12 when L2=1e-4 is added to both. The gap is an artifact of where each implementation's optimizer lands on the bias-variance curve, not a port bug — TF was over-fitting weight magnitudes (L2 helps), PyTorch was already in a calibrated regime (L2 hurts). Both implementations produce reasonable metrics; no code change needed.

[ds-wook]

@miguelgfierro I’ve addressed the requested changes. When you have a chance, could you please take another look? Thank you!

[anargyri]

This file has no real changes. Could you unstage?

[anargyri]

Same here.

[anargyri]

This one too.

[anargyri]

I think you can remove the stuff about TensorFlow since it is not relevant for this notebook.

[anargyri]

Doesn't it make sense to create something similar to SequentialBaseModel as in the existing code, since we are going to reuse it for other deeprec models too? This file is now longer and the same thing will happen with the other models.