TorchEasyRec 支持在你自己的工程里编写自定义模型,无需修改 TorchEasyRec 仓库中的任何文件。 模型代码、模型配置 proto 和 pipeline config 都放在你的工程中,升级 TorchEasyRec 时不会产生代码冲突。
pipeline config 通过 custom_model.class_path 指定模型类的完整 python 路径,通过
custom_model.config(google.protobuf.Any)携带你自己定义的强类型模型配置。
TorchEasyRec 在解析 pipeline config 前会先导入 class_path 所在的模块,因此模型模块中
import 的 *_pb2 会自动完成 protobuf descriptor 注册。
推荐的工程结构如下,包名和目录名可以自由选择:
my-rec-project/
├── my_models/
│ ├── __init__.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── custom_rank_model.py
│ └── protos/
│ ├── __init__.py
│ └── custom_rank_model.proto
├── configs/
│ └── custom_rank_model.config
└── .vscode/
└── settings.json
TorchEasyRec 可以通过 pip 安装,也可以作为 git submodule 引入,两种方式后续步骤完全一致。
pip install tzrec[cu130]==${TZREC_NIGHTLY_VERSION} -f http://tzrec.oss-accelerate.aliyuncs.com/release/nightly/repo.html --trusted-host tzrec.oss-accelerate.aliyuncs.com注:[cu130] 按环境替换为 cpu、cu126、cu130 或 ppu,它决定安装的 torch、fbgemm-gpu、torchrec 版本;不带该后缀时不会安装这三者,仅适用于官方镜像等已预装它们的环境。
运行命令时用 PYTHONPATH=. 让 python 可以导入你的包即可:
PYTHONPATH=. python -m tzrec.train_eval --pipeline_config_path configs/custom_rank_model.config ...适合需要固定 TorchEasyRec 版本、或需要同时修改调试 TorchEasyRec 源码的场景。
git submodule add https://github.com/alibaba/TorchEasyRec.git third_party/TorchEasyRec
pip install -r third_party/TorchEasyRec/requirements.txtsubmodule 中不包含生成的 *_pb2.py,拉取和更新 submodule 后需要在 submodule 目录内生成:
cd third_party/TorchEasyRec && bash scripts/gen_proto.sh && cd -运行命令时把 submodule 加入 PYTHONPATH:
PYTHONPATH=.:third_party/TorchEasyRec python -m tzrec.train_eval \
--pipeline_config_path configs/custom_rank_model.config ...注意:PYTHONPATH 中的源码版本会覆盖 pip 安装的 tzrec,请不要同时使用两种方式。
TorchEasyRec 使用 Protocol Buffer
定义配置文件格式。在你自己的包里定义模型配置,可以直接复用 TorchEasyRec 的公共 message,
例如 tzrec.protos.MLP:
// my_models/protos/custom_rank_model.proto
syntax = "proto2";
package my_models.protos;
import "tzrec/protos/module.proto";
message CustomRankModelConfig {
required tzrec.protos.MLP mlp = 1;
}在工程根目录用 protoc 编译自己的 proto:
python -m grpc_tools.protoc -I . my_models/protos/*.proto --python_out=. --pyi_out=.如果自定义 proto import 了 TorchEasyRec 的 proto(例如上面复用 tzrec.protos.MLP),
还需要把 TorchEasyRec 的目录加到 -I 中。protoc 读取的是 .proto 源文件,
所以这里要填 tzrec/protos/ 的上一级目录:
# submodule 方式
TZREC_PATH=third_party/TorchEasyRec
# pip 安装方式
TZREC_PATH=$(python -c "import importlib.metadata as m; print(m.distribution('tzrec').locate_file(''))")
python -m grpc_tools.protoc -I . -I "${TZREC_PATH}" \
my_models/protos/*.proto --python_out=. --pyi_out=.继承 tzrec.models.model.BaseModel 来实现自定义模型,需重载以下函数。
自定义模型的 __init__ 签名与内置模型完全一致,框架会把 custom_model.config 解包成
强类型 message 后赋值给 self._model_config。
- 根据模型配置
model_config和特征配置features构建子模块
- 根据输入的
batch数据,进行前向推理,得到predictionsbatch为tzrec.datasets.utils.Batch的数据结构,包含dense_features(稠密特征)、sparse_features(稀疏特征)、sequence_dense_features(序列稠密特征)- 一般可以将
batch传给EmbeddingGroup模块tzrec.modules.embedding.EmbeddingGroup得到分组的Embedding结果后,再进行进一步前向推理
init_loss函数用于根据模型损失函数配置初始化loss模块,写入到self._loss_modules中loss函数用于根据输入的predictions和batch中的label,实际计算每个step的loss,返回一个loss_dict
init_metric函数用于根据模型初始化metric模块,写入到self._metric_modules中update_metric函数用于根据输入的predictions和batch中的label,更新metric模块的状态
在排序、多目标排序、召回的场景下,可以直接继承以下子模型,可以只用重置前向推理函数
- 排序模型可直接继承
tzrec.models.rank_model.RankModel - 多目标模型可直接继承
tzrec.models.multi_task_rank.MultiTaskRank - 召回模型可直接继承
tzrec.models.match_model.MatchModel
模型模块必须在顶层 import 自己的 *_pb2。
读取 label 时使用 self.get_label(batch, label_name),不要直接用 batch.labels[label_name],
否则数组类型的 label 会取不到。
以排序模型为例
# my_models/models/custom_rank_model.py
from typing import Any, Dict, List, Optional
import torch
from torch import nn
from tzrec.datasets.utils import Batch
from tzrec.features.feature import BaseFeature
from tzrec.models.rank_model import RankModel
from tzrec.modules.mlp import MLP
from tzrec.protos.model_pb2 import ModelConfig
from tzrec.utils.config_util import config_to_kwargs
from my_models.protos.custom_rank_model_pb2 import CustomRankModelConfig # NOQA
class CustomRankModel(RankModel):
"""CustomRankModel.
Args:
model_config (ModelConfig): an instance of ModelConfig.
features (list): list of features.
labels (list): list of label names.
"""
def __init__(
self,
model_config: ModelConfig,
features: List[BaseFeature],
labels: List[str],
sample_weights: Optional[List[str]] = None,
**kwargs: Any,
) -> None:
super().__init__(model_config, features, labels, sample_weights, **kwargs)
# self._model_config 即解包后的 CustomRankModelConfig
self.init_input()
self.mlp = MLP(
self.embedding_group.group_total_dim("deep"),
**config_to_kwargs(self._model_config.mlp),
)
self.output_mlp = nn.Linear(self.mlp.output_dim(), self._num_class)
def predict(self, batch: Batch) -> Dict[str, torch.Tensor]:
"""Forward the model.
Args:
batch (Batch): input batch data.
Return:
predictions (dict): a dict of predicted result.
"""
grouped_features = self.build_input(batch)
y = self.output_mlp(self.mlp(grouped_features["deep"]))
return self._output_to_prediction(y)model_config {
feature_groups {
group_name: "deep"
feature_names: "f1"
feature_names: "f2"
group_type: DEEP
}
custom_model {
class_path: "my_models.models.custom_rank_model.CustomRankModel"
config {
[type.googleapis.com/my_models.protos.CustomRankModelConfig] {
mlp {
hidden_units: [128, 64]
dropout_ratio: [0.1, 0.1]
}
}
}
}
losses {
binary_cross_entropy {}
}
metrics {
auc {}
}
}class_path是模型类的完整 python 路径,运行时该路径必须可以被 python 导入。- 方括号中的
my_models.protos.CustomRankModelConfig是 proto 文件里声明的package加 message 名,不是 python 模块路径。 custom_model.config可以省略,此时self._model_config为None。
以 pip 安装方式为例,submodule 方式只需把 PYTHONPATH 换成 .:third_party/TorchEasyRec。
训练
PYTHONPATH=. torchrun --master_addr=localhost --master_port=32555 \
--nnodes=1 --nproc-per-node=2 --node_rank=0 \
-m tzrec.train_eval \
--pipeline_config_path configs/custom_rank_model.config \
--train_input_path ${TRAIN_INPUT_PATH} \
--eval_input_path ${EVAL_INPUT_PATH} \
--model_dir ${MODEL_DIR}评估、导出和预测与内置模型完全一致,class_path 会随 pipeline config 一起保存到
${MODEL_DIR}/pipeline.config,因此后续命令无需任何额外配置:
PYTHONPATH=. torchrun --master_addr=localhost --master_port=32555 \
--nnodes=1 --nproc-per-node=2 --node_rank=0 \
-m tzrec.eval --pipeline_config_path ${MODEL_DIR}/pipeline.config
PYTHONPATH=. torchrun --master_addr=localhost --master_port=32555 \
--nnodes=1 --nproc-per-node=2 --node_rank=0 \
-m tzrec.export --pipeline_config_path ${MODEL_DIR}/pipeline.config \
--export_dir ${EXPORT_DIR}shell 中设置的 PYTHONPATH 不会传递给 VSCode 的 Pylance,需要在工程里增加
.vscode/settings.json,否则无法跳转到 tzrec 的定义:
{
"python.analysis.extraPaths": [".", "third_party/TorchEasyRec"],
"python.autoComplete.extraPaths": [".", "third_party/TorchEasyRec"]
}pip 安装方式下 extraPaths 只需要 ["."],tzrec 由解释器的 site-packages 解析;
submodule 方式下跳转会进入 submodule 源码,可以直接修改和打断点调试 TorchEasyRec。
protoc 的 --pyi_out 生成的 *_pb2.pyi 让自定义 proto 的类型也可以正常跳转和补全。
调试模型代码时使用单进程启动,可以正常使用 pdb / debugpy:
PYTHONPATH=. torchrun --master_addr=localhost --master_port=32555 \
--nnodes=1 --nproc-per-node=1 --node_rank=0 \
-m tzrec.train_eval --pipeline_config_path configs/custom_rank_model.config ...config type [xxx] is not registered:class_path指向的模型模块没有在顶层import对应的*_pb2,descriptor 未注册。ModuleNotFoundError/class xxx is not found in module xxx:class_path写错, 或者运行时PYTHONPATH中没有包含你的工程目录。duplicate file name tzrec/protos/xxx.proto或couldn't resolve name:自定义 proto 编译时-I指向的 TorchEasyRec 和运行时使用的不一致,用实际运行的那一份重新编译。confilict class xxx is already register:自定义模型的类名和 TorchEasyRec 内置模型 重名,换一个类名即可。
自定义包可以打成 wheel 发布,安装后运行时不再需要设置 PYTHONPATH。
setup.py:
from setuptools import find_packages, setup
setup(
name="my_models",
version="0.1.0",
packages=find_packages(),
package_data={"my_models.protos": ["*.proto", "*.pyi"]},
)先生成 binding 再打包,顺序和 TorchEasyRec 的 scripts/build_wheel.sh 一致:
python -m grpc_tools.protoc -I . -I "${TZREC_PATH}" \
my_models/protos/*.proto --python_out=. --pyi_out=.
python setup.py bdist_wheel
pip install dist/my_models-0.1.0-py3-none-any.whl*_pb2.py 是普通的 python 文件,find_packages() 会自动打包进 wheel;*_pb2.pyi
和 .proto 需要用 package_data 指定。如果 .gitignore 中忽略了 *_pb2.py,
打包前必须先执行上面的 protoc 命令。