torch-rechub 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

torch_rechub/trainers/match_trainer.py

@@ -1,170 +1,336 @@
-import os
-import torch
-import tqdm
-from sklearn.metrics import roc_auc_score
-from ..basic.callback import EarlyStopper
-from ..basic.loss_func import BPRLoss
-
-
-class MatchTrainer(object):
-    """A general trainer for Matching/Retrieval
-
-    Args:
-        model (nn.Module): any matching model.
-        mode (int, optional): the training mode, `{0:point-wise, 1:pair-wise, 2:list-wise}`. Defaults to 0.
-        optimizer_fn (torch.optim): optimizer function of pytorch (default = `torch.optim.Adam`).
-        optimizer_params (dict): parameters of optimizer_fn.
-        scheduler_fn (torch.optim.lr_scheduler) : torch scheduling class, eg. `torch.optim.lr_scheduler.StepLR`.
-        scheduler_params (dict): parameters of optimizer scheduler_fn.
-        n_epoch (int): epoch number of training.
-        earlystop_patience (int): how long to wait after last time validation auc improved (default=10).
-        device (str): `"cpu"` or `"cuda:0"`
-        gpus (list): id of multi gpu (default=[]). If the length >=1, then the model will wrapped by nn.DataParallel.
-        model_path (str): the path you want to save the model (default="./"). Note only save the best weight in the validation data.
-    """
-
-    def __init__(
-        self,
-        model,
-        mode=0,
-        optimizer_fn=torch.optim.Adam,
-            optimizer_params=None,
-        scheduler_fn=None,
-        scheduler_params=None,
-        n_epoch=10,
-        earlystop_patience=10,
-        device="cpu",
-            gpus=None,
-        model_path="./",
-    ):
-        self.model = model  # for uniform weights save method in one gpu or multi gpu
-        if gpus is None:
-            gpus = []
-        self.gpus = gpus
-        if len(gpus) > 1:
-            print('parallel running on these gpus:', gpus)
-            self.model = torch.nn.DataParallel(self.model, device_ids=gpus)
-        self.device = torch.device(device)  #torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
-        self.model.to(self.device)
-        if optimizer_params is None:
-            optimizer_params = {
-                "lr": 1e-3,
-                "weight_decay": 1e-5
-            }
-        self.mode = mode
-        if mode == 0:  #point-wise loss, binary cross_entropy
-            self.criterion = torch.nn.BCELoss()  #default loss binary cross_entropy
-        elif mode == 1:  #pair-wise loss
-            self.criterion = BPRLoss()
-        elif mode == 2:  #list-wise loss, softmax
-            self.criterion = torch.nn.CrossEntropyLoss()
-        else:
-            raise ValueError("mode only contain value in %s, but got %s" % ([0, 1, 2], mode))
-        self.optimizer = optimizer_fn(self.model.parameters(), **optimizer_params)  #default optimizer
-        self.scheduler = None
-        if scheduler_fn is not None:
-            self.scheduler = scheduler_fn(self.optimizer, **scheduler_params)
-        self.evaluate_fn = roc_auc_score  #default evaluate function
-        self.n_epoch = n_epoch
-        self.early_stopper = EarlyStopper(patience=earlystop_patience)
-        self.model_path = model_path
-
-    def train_one_epoch(self, data_loader, log_interval=10):
-        self.model.train()
-        total_loss = 0
-        tk0 = tqdm.tqdm(data_loader, desc="train", smoothing=0, mininterval=1.0)
-        for i, (x_dict, y) in enumerate(tk0):
-            x_dict = {k: v.to(self.device) for k, v in x_dict.items()}  #tensor to GPU
-            y = y.to(self.device)
-            if self.mode == 0:
-                y = y.float()  #torch._C._nn.binary_cross_entropy expected Float
-            else:
-                y = y.long()  #
-            if self.mode == 1:  #pair_wise
-                pos_score, neg_score = self.model(x_dict)
-                loss = self.criterion(pos_score, neg_score)
-            else:
-                y_pred = self.model(x_dict)
-                loss = self.criterion(y_pred, y)
-            # used for debug
-            # if i == 0:
-            #     print()
-            #     if self.mode == 0:
-            #         print('pred: ', [f'{float(each):5.2g}' for each in y_pred.detach().cpu().tolist()])
-            #         print('truth:', [f'{float(each):5.2g}' for each in y.detach().cpu().tolist()])
-            #     elif self.mode == 2:
-            #         pred = y_pred.detach().cpu().mean(0)
-            #         pred = torch.softmax(pred, dim=0).tolist()
-            #         print('pred: ', [f'{float(each):4.2g}' for each in pred])
-            #     elif self.mode == 1:
-            #         print('pos:', [f'{float(each):5.2g}' for each in pos_score.detach().cpu().tolist()])
-            #         print('neg: ', [f'{float(each):5.2g}' for each in neg_score.detach().cpu().tolist()])
-
-            self.model.zero_grad()
-            loss.backward()
-            self.optimizer.step()
-            total_loss += loss.item()
-            if (i + 1) % log_interval == 0:
-                tk0.set_postfix(loss=total_loss / log_interval)
-                total_loss = 0
-
-    def fit(self, train_dataloader, val_dataloader=None):
-        for epoch_i in range(self.n_epoch):
-            print('epoch:', epoch_i)
-            self.train_one_epoch(train_dataloader)
-            if self.scheduler is not None:
-                if epoch_i % self.scheduler.step_size == 0:
-                    print("Current lr : {}".format(self.optimizer.state_dict()['param_groups'][0]['lr']))
-                self.scheduler.step()  #update lr in epoch level by scheduler
-
-            if val_dataloader:
-                auc = self.evaluate(self.model, val_dataloader)
-                print('epoch:', epoch_i, 'validation: auc:', auc)
-                if self.early_stopper.stop_training(auc, self.model.state_dict()):
-                    print(f'validation: best auc: {self.early_stopper.best_auc}')
-                    self.model.load_state_dict(self.early_stopper.best_weights)
-                    break
-        torch.save(self.model.state_dict(), os.path.join(self.model_path,
-                                                            "model.pth"))  #save best auc model
-
-
-    def evaluate(self, model, data_loader):
-        model.eval()
-        targets, predicts = list(), list()
-        with torch.no_grad():
-            tk0 = tqdm.tqdm(data_loader, desc="validation", smoothing=0, mininterval=1.0)
-            for i, (x_dict, y) in enumerate(tk0):
-                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
-                y = y.to(self.device)
-                y_pred = model(x_dict)
-                targets.extend(y.tolist())
-                predicts.extend(y_pred.tolist())
-        return self.evaluate_fn(targets, predicts)
-
-    def predict(self, model, data_loader):
-        model.eval()
-        predicts = list()
-        with torch.no_grad():
-            tk0 = tqdm.tqdm(data_loader, desc="predict", smoothing=0, mininterval=1.0)
-            for i, (x_dict, y) in enumerate(tk0):
-                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
-                y = y.to(self.device)
-                y_pred = model(x_dict)
-                predicts.extend(y_pred.tolist())
-        return predicts
-
-    def inference_embedding(self, model, mode, data_loader, model_path):
-        #inference
-        assert mode in ["user", "item"], "Invalid mode={}.".format(mode)
-        model.mode = mode
-        model.load_state_dict(torch.load(os.path.join(model_path, "model.pth")))
-        model = model.to(self.device)
-        model.eval()
-        predicts = []
-        with torch.no_grad():
-            tk0 = tqdm.tqdm(data_loader, desc="%s inference" % (mode), smoothing=0, mininterval=1.0)
-            for i, x_dict in enumerate(tk0):
-                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
-                y_pred = model(x_dict)
-                predicts.append(y_pred.data)
-        return torch.cat(predicts, dim=0)
+import os
+
+import torch
+import tqdm
+from sklearn.metrics import roc_auc_score
+
+from ..basic.callback import EarlyStopper
+from ..basic.loss_func import BPRLoss, RegularizationLoss
+
+
+class MatchTrainer(object):
+    """A general trainer for Matching/Retrieval
+
+    Args:
+        model (nn.Module): any matching model.
+        mode (int, optional): the training mode, `{0:point-wise, 1:pair-wise, 2:list-wise}`. Defaults to 0.
+        optimizer_fn (torch.optim): optimizer function of pytorch (default = `torch.optim.Adam`).
+        optimizer_params (dict): parameters of optimizer_fn.
+        scheduler_fn (torch.optim.lr_scheduler) : torch scheduling class, eg. `torch.optim.lr_scheduler.StepLR`.
+        scheduler_params (dict): parameters of optimizer scheduler_fn.
+        n_epoch (int): epoch number of training.
+        earlystop_patience (int): how long to wait after last time validation auc improved (default=10).
+        device (str): `"cpu"` or `"cuda:0"`
+        gpus (list): id of multi gpu (default=[]). If the length >=1, then the model will wrapped by nn.DataParallel.
+        model_path (str): the path you want to save the model (default="./"). Note only save the best weight in the validation data.
+    """
+
+    def __init__(
+        self,
+        model,
+        mode=0,
+        optimizer_fn=torch.optim.Adam,
+        optimizer_params=None,
+        regularization_params=None,
+        scheduler_fn=None,
+        scheduler_params=None,
+        n_epoch=10,
+        earlystop_patience=10,
+        device="cpu",
+        gpus=None,
+        model_path="./",
+    ):
+        self.model = model  # for uniform weights save method in one gpu or multi gpu
+        if gpus is None:
+            gpus = []
+        self.gpus = gpus
+        if len(gpus) > 1:
+            print('parallel running on these gpus:', gpus)
+            self.model = torch.nn.DataParallel(self.model, device_ids=gpus)
+        # torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
+        self.device = torch.device(device)
+        self.model.to(self.device)
+        if optimizer_params is None:
+            optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5}
+        if regularization_params is None:
+            regularization_params = {"embedding_l1": 0.0, "embedding_l2": 0.0, "dense_l1": 0.0, "dense_l2": 0.0}
+        self.mode = mode
+        if mode == 0:  # point-wise loss, binary cross_entropy
+            self.criterion = torch.nn.BCELoss()  # default loss binary cross_entropy
+        elif mode == 1:  # pair-wise loss
+            self.criterion = BPRLoss()
+        elif mode == 2:  # list-wise loss, softmax
+            self.criterion = torch.nn.CrossEntropyLoss()
+        else:
+            raise ValueError("mode only contain value in %s, but got %s" % ([0, 1, 2], mode))
+        self.optimizer = optimizer_fn(self.model.parameters(), **optimizer_params)  # default optimizer
+        self.scheduler = None
+        if scheduler_fn is not None:
+            self.scheduler = scheduler_fn(self.optimizer, **scheduler_params)
+        self.evaluate_fn = roc_auc_score  # default evaluate function
+        self.n_epoch = n_epoch
+        self.early_stopper = EarlyStopper(patience=earlystop_patience)
+        self.model_path = model_path
+        # Initialize regularization loss
+        self.reg_loss_fn = RegularizationLoss(**regularization_params)
+
+    def train_one_epoch(self, data_loader, log_interval=10):
+        self.model.train()
+        total_loss = 0
+        tk0 = tqdm.tqdm(data_loader, desc="train", smoothing=0, mininterval=1.0)
+        for i, (x_dict, y) in enumerate(tk0):
+            x_dict = {k: v.to(self.device) for k, v in x_dict.items()}  # tensor to GPU
+            y = y.to(self.device)
+            if self.mode == 0:
+                y = y.float()  # torch._C._nn.binary_cross_entropy expected Float
+            else:
+                y = y.long()  #
+            if self.mode == 1:  # pair_wise
+                pos_score, neg_score = self.model(x_dict)
+                loss = self.criterion(pos_score, neg_score)
+            else:
+                y_pred = self.model(x_dict)
+                loss = self.criterion(y_pred, y)
+
+            # Add regularization loss
+            reg_loss = self.reg_loss_fn(self.model)
+            loss = loss + reg_loss
+
+            # used for debug
+            # if i == 0:
+            #     print()
+            #     if self.mode == 0:
+            #         print('pred: ', [f'{float(each):5.2g}' for each in y_pred.detach().cpu().tolist()])
+            #         print('truth:', [f'{float(each):5.2g}' for each in y.detach().cpu().tolist()])
+            #     elif self.mode == 2:
+            #         pred = y_pred.detach().cpu().mean(0)
+            #         pred = torch.softmax(pred, dim=0).tolist()
+            #         print('pred: ', [f'{float(each):4.2g}' for each in pred])
+            #     elif self.mode == 1:
+            #         print('pos:', [f'{float(each):5.2g}' for each in pos_score.detach().cpu().tolist()])
+            #         print('neg: ', [f'{float(each):5.2g}' for each in neg_score.detach().cpu().tolist()])
+
+            self.model.zero_grad()
+            loss.backward()
+            self.optimizer.step()
+            total_loss += loss.item()
+            if (i + 1) % log_interval == 0:
+                tk0.set_postfix(loss=total_loss / log_interval)
+                total_loss = 0
+
+    def fit(self, train_dataloader, val_dataloader=None):
+        for epoch_i in range(self.n_epoch):
+            print('epoch:', epoch_i)
+            self.train_one_epoch(train_dataloader)
+            if self.scheduler is not None:
+                if epoch_i % self.scheduler.step_size == 0:
+                    print("Current lr : {}".format(self.optimizer.state_dict()['param_groups'][0]['lr']))
+                self.scheduler.step()  # update lr in epoch level by scheduler
+
+            if val_dataloader:
+                auc = self.evaluate(self.model, val_dataloader)
+                print('epoch:', epoch_i, 'validation: auc:', auc)
+                if self.early_stopper.stop_training(auc, self.model.state_dict()):
+                    print(f'validation: best auc: {self.early_stopper.best_auc}')
+                    self.model.load_state_dict(self.early_stopper.best_weights)
+                    break
+        torch.save(self.model.state_dict(), os.path.join(self.model_path, "model.pth"))  # save best auc model
+
+    def evaluate(self, model, data_loader):
+        model.eval()
+        targets, predicts = list(), list()
+        with torch.no_grad():
+            tk0 = tqdm.tqdm(data_loader, desc="validation", smoothing=0, mininterval=1.0)
+            for i, (x_dict, y) in enumerate(tk0):
+                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
+                y = y.to(self.device)
+                y_pred = model(x_dict)
+                targets.extend(y.tolist())
+                predicts.extend(y_pred.tolist())
+        return self.evaluate_fn(targets, predicts)
+
+    def predict(self, model, data_loader):
+        model.eval()
+        predicts = list()
+        with torch.no_grad():
+            tk0 = tqdm.tqdm(data_loader, desc="predict", smoothing=0, mininterval=1.0)
+            for i, (x_dict, y) in enumerate(tk0):
+                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
+                y = y.to(self.device)
+                y_pred = model(x_dict)
+                predicts.extend(y_pred.tolist())
+        return predicts
+
+    def inference_embedding(self, model, mode, data_loader, model_path):
+        # inference
+        assert mode in ["user", "item"], "Invalid mode={}.".format(mode)
+        model.mode = mode
+        model.load_state_dict(torch.load(os.path.join(model_path, "model.pth"), map_location=self.device, weights_only=True))
+        model = model.to(self.device)
+        model.eval()
+        predicts = []
+        with torch.no_grad():
+            tk0 = tqdm.tqdm(data_loader, desc="%s inference" % (mode), smoothing=0, mininterval=1.0)
+            for i, x_dict in enumerate(tk0):
+                x_dict = {k: v.to(self.device) for k, v in x_dict.items()}
+                y_pred = model(x_dict)
+                predicts.append(y_pred.data)
+        return torch.cat(predicts, dim=0)
+
+    def export_onnx(self, output_path, mode=None, dummy_input=None, batch_size=2, seq_length=10, opset_version=14, dynamic_batch=True, device=None, verbose=False):
+        """Export the trained matching model to ONNX format.
+
+        This method exports matching/retrieval models (e.g., DSSM, YoutubeDNN, MIND)
+        to ONNX format. For dual-tower models, you can export user tower and item
+        tower separately for efficient online serving.
+
+        Args:
+            output_path (str): Path to save the ONNX model file.
+            mode (str, optional): Export mode for dual-tower models:
+                - "user": Export only the user tower (for user embedding inference)
+                - "item": Export only the item tower (for item embedding inference)
+                - None: Export the full model (default)
+            dummy_input (dict, optional): Example input dict {feature_name: tensor}.
+                If not provided, dummy inputs will be generated automatically.
+            batch_size (int): Batch size for auto-generated dummy input (default: 2).
+            seq_length (int): Sequence length for SequenceFeature (default: 10).
+            opset_version (int): ONNX opset version (default: 14).
+            dynamic_batch (bool): Enable dynamic batch size (default: True).
+            device (str, optional): Device for export ('cpu', 'cuda', etc.).
+                If None, defaults to 'cpu' for maximum compatibility.
+            verbose (bool): Print export details (default: False).
+
+        Returns:
+            bool: True if export succeeded, False otherwise.
+
+        Example:
+            >>> trainer = MatchTrainer(dssm_model, mode=0, ...)
+            >>> trainer.fit(train_dl)
+
+            >>> # Export user tower for user embedding inference
+            >>> trainer.export_onnx("user_tower.onnx", mode="user")
+
+            >>> # Export item tower for item embedding inference
+            >>> trainer.export_onnx("item_tower.onnx", mode="item")
+
+            >>> # Export full model (for online similarity computation)
+            >>> trainer.export_onnx("full_model.onnx")
+
+            >>> # Export on specific device
+            >>> trainer.export_onnx("user_tower.onnx", mode="user", device="cpu")
+        """
+        from ..utils.onnx_export import ONNXExporter
+
+        # Handle DataParallel wrapped model
+        model = self.model.module if hasattr(self.model, 'module') else self.model
+
+        # Store original mode
+        original_mode = getattr(model, 'mode', None)
+
+        # Use provided device or default to 'cpu'
+        export_device = device if device is not None else 'cpu'
+
+        try:
+            exporter = ONNXExporter(model, device=export_device)
+            return exporter.export(output_path=output_path, mode=mode, dummy_input=dummy_input, batch_size=batch_size, seq_length=seq_length, opset_version=opset_version, dynamic_batch=dynamic_batch, verbose=verbose)
+        finally:
+            # Restore original mode
+            if hasattr(model, 'mode'):
+                model.mode = original_mode
+
+    def visualization(self, input_data=None, batch_size=2, seq_length=10, depth=3, show_shapes=True, expand_nested=True, save_path=None, graph_name="model", device=None, dpi=300, **kwargs):
+        """Visualize the model's computation graph.
+
+        This method generates a visual representation of the model architecture,
+        showing layer connections, tensor shapes, and nested module structures.
+        It automatically extracts feature information from the model.
+
+        Parameters
+        ----------
+        input_data : dict, optional
+            Example input dict {feature_name: tensor}.
+            If not provided, dummy inputs will be generated automatically.
+        batch_size : int, default=2
+            Batch size for auto-generated dummy input.
+        seq_length : int, default=10
+            Sequence length for SequenceFeature.
+        depth : int, default=3
+            Visualization depth, higher values show more detail.
+            Set to -1 to show all layers.
+        show_shapes : bool, default=True
+            Whether to display tensor shapes.
+        expand_nested : bool, default=True
+            Whether to expand nested modules.
+        save_path : str, optional
+            Path to save the graph image (.pdf, .svg, .png).
+            If None, displays in Jupyter or opens system viewer.
+        graph_name : str, default="model"
+            Name for the graph.
+        device : str, optional
+            Device for model execution. If None, defaults to 'cpu'.
+        dpi : int, default=300
+            Resolution in dots per inch for output image.
+            Higher values produce sharper images suitable for papers.
+        **kwargs : dict
+            Additional arguments passed to torchview.draw_graph().
+
+        Returns
+        -------
+        ComputationGraph
+            A torchview ComputationGraph object.
+
+        Raises
+        ------
+        ImportError
+            If torchview or graphviz is not installed.
+
+        Notes
+        -----
+        Default Display Behavior:
+            When `save_path` is None (default):
+            - In Jupyter/IPython: automatically displays the graph inline
+            - In Python script: opens the graph with system default viewer
+
+        Examples
+        --------
+        >>> trainer = MatchTrainer(model, ...)
+        >>> trainer.fit(train_dl)
+        >>>
+        >>> # Auto-display in Jupyter (no save_path needed)
+        >>> trainer.visualization(depth=4)
+        >>>
+        >>> # Save to high-DPI PNG for papers
+        >>> trainer.visualization(save_path="model.png", dpi=300)
+        """
+        from ..utils.visualization import TORCHVIEW_AVAILABLE, visualize_model
+
+        if not TORCHVIEW_AVAILABLE:
+            raise ImportError(
+                "Visualization requires torchview. "
+                "Install with: pip install torch-rechub[visualization]\n"
+                "Also ensure graphviz is installed on your system:\n"
+                "  - Ubuntu/Debian: sudo apt-get install graphviz\n"
+                "  - macOS: brew install graphviz\n"
+                "  - Windows: choco install graphviz"
+            )
+
+        # Handle DataParallel wrapped model
+        model = self.model.module if hasattr(self.model, 'module') else self.model
+
+        # Use provided device or default to 'cpu'
+        viz_device = device if device is not None else 'cpu'
+
+        return visualize_model(
+            model,
+            input_data=input_data,
+            batch_size=batch_size,
+            seq_length=seq_length,
+            depth=depth,
+            show_shapes=show_shapes,
+            expand_nested=expand_nested,
+            save_path=save_path,
+            graph_name=graph_name,
+            device=viz_device,
+            dpi=dpi,
+            **kwargs
+        )

torch_rechub/trainers/matching.md

@@ -0,0 +1,3 @@
+# Matching
+
+召回使用文档