torchrec 不是开箱即用的推荐模型库，而是面向大规模稀疏特征训练的底层分布式 embedding 框架，需自行拼装模型结构、实现 loss/metric/训练循环，并严格处理数据格式（keyedjaggedtensor）、设备一致性、分布式初始化及特征对齐等细节。
PyTorch 的 TorchRec 并不适合直接构建端到端工业级推荐系统模型——它本身是面向大规模稀疏特征训练的底层分布式 embedding 框架，不是开箱即用的推荐模型库。
为什么不能直接用 TorchRec 写一个“推荐模型”？
TorchRec 不提供 RankingModel、TwoTower 或 DLRM 这类高层模型定义；它只负责：多机多卡下的 embedding 表分片、异步更新、梯度合并、UVM（Unified Virtual Memory）支持。你得自己组合 EmbeddingBagCollection、DenseArch、InteractionArch 等模块拼出模型结构。
- 没有内置 loss、metric 或训练 loop —— 你要自己写
torch.nn.BCEWithLogitsLoss+torch.optim.Adam+torch.utils.data.DataLoader - 不处理样本采样（如负采样逻辑）、特征工程（ID 映射、统计归一化）、线上 serving（ONNX 导出需额外适配）
- 依赖
torchrec.distributed的分布式训练必须配合torch.distributed.launch或torchrun，且要求 NCCL 后端和一致的 GPU 数量配置
怎样用 TorchRec 正确接入已有推荐流程？
典型做法是：用 TorchRec 替换原模型中 embedding 层部分，其余 dense tower 和 loss 保持不变。适用于已有 PyTorch 推荐模型但遇到 embedding 内存爆炸或训练慢的问题。
- 把原始
nn.Embedding换成EmbeddingBagCollection，按表名组织 sparse features（如"user_id","item_id","category"） - 确保输入数据格式为
KeyedJaggedTensor：每个 feature key 对应一个变长 ID 列表（如用户历史点击 item_ids），不能直接喂torch.Tensor - 调用
ShardedEmbeddingBagCollection前必须初始化TableBatchedEmbeddingBag，并指定embedding_dim、num_embeddings、pooling（"sum"or"mean"） - 单机调试时用
EmbeddingBagCollection；多机部署必须用ShardedEmbeddingBagCollection+torch.distributed.init_process_group
TorchRec 训练时最常见的三个报错及修复
错误往往不出现在模型定义，而在数据流或分布式初始化环节：
-
RuntimeError: Expected all tensors to be on the same device→ 检查KeyedJaggedTensor中所有values和lengths是否都 .to(device)，EmbeddingBagCollection必须显式.to(device) -
ValueError: EmbeddingBagCollection: missing keys in input→ 输入的KeyedJaggedTensorkeys 和模型声明的tables名称不完全一致（大小写、下划线、顺序） -
torch.distributed.DistBackendError: NCCL operation failed→ 多卡训练时未设置CUDA_VISIBLE_DEVICES，或torchrun启动参数中--nproc-per-node与实际 GPU 数不匹配
真正难的是 embedding 表冷启动、feature schema 动态扩缩容、以及和线上特征平台（如 Flink + Redis）对齐 ID 映射——这些 TorchRec 一概不管，得你自己在 data loader 里补全逻辑。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
