1. 项目缘起：为什么我们需要一个新闻推荐工具包？

做推荐系统，尤其是新闻推荐，一直是个挺有意思的活儿。你手头有海量的新闻数据，用户行为日志像雪片一样飞来，目标是把用户最可能感兴趣的那几条精准地推到他面前。这事儿听起来简单，但真干起来，从数据清洗、特征工程、模型选型到线上部署，每一步都藏着无数细节和坑。我自己在新闻资讯行业摸爬滚打了几年，用过不少开源框架，也自己从头搭过几套系统。一个很深的感触是：虽然PyTorch在深度学习研究领域几乎成了标配，生态也极其繁荣，但当你真的想快速搭建一个可复现、可迭代、且能融合最新研究进展（比如图神经网络GNN和大语言模型LLM）的新闻推荐实验环境时，你会发现手头的工具要么太“重”（比如一些工业级全链路平台，学习成本和部署成本高），要么太“散”（需要自己东拼西凑各种组件，代码风格不一，复现困难）。

这就是NewsTorch诞生的背景。它不是一个试图解决所有问题的庞然大物，而是一个聚焦于新闻推荐场景的、基于PyTorch的 学习与研究工具包 。它的核心定位是： 为研究者、算法工程师和学生，提供一个轻量、模块化、且紧跟学术前沿的代码基底，让大家能快速验证关于新闻推荐的idea，特别是那些涉及复杂用户-物品交互图（GNN用武之地）和新闻文本深度理解（LLM大显身手）的新想法。

你可能会问，不是有LightGCN、RecBole这些优秀的推荐库吗？它们当然很棒，但NewsTorch想解决一些更具体的问题：

1. 场景针对性 ：新闻推荐有其特殊性，如新闻的强时效性、主题漂移、冷启动问题严重（新新闻不断涌现）、文本内容信息量巨大。通用推荐库往往需要大量适配工作才能处理好这些特性。
2. 技术栈融合 ：当前，单纯使用协同过滤或深度矩阵分解已显乏力。将用户-新闻的点击关系视为图，用GNN来捕捉高阶协同信号；同时，利用LLM强大的语义理解能力，从新闻标题、摘要甚至正文中提取深层特征，已成为明显的趋势。但将GNN和LLM优雅地整合进一个统一的推荐框架，并处理好两者之间的特征对齐与交互，现有的工具支持并不直接。
3. 实验友好性 ：研究需要快速迭代、对比消融。NewsTorch在设计上强调模块化，将数据加载、负采样、图构建、模型定义、训练循环、评估指标等环节解耦，让你可以像搭积木一样替换其中任何一个部分，从而清晰地对比“加了GNN模块效果提升多少”、“用LLM特征替换传统TF-IDF特征有何不同”。

简单说，如果你正在研究或实践新闻推荐，并且对如何将GNN和LLM这些“新式武器”应用到其中感兴趣，但又不想在工程基础设施上花费过多精力，那么NewsTorch可能就是为你准备的“脚手架”和“工具箱”。

2. 核心架构解析：NewsTorch是如何组织的？

一个工具包好不好用，首先看它的架构是否清晰。NewsTorch遵循了“高内聚、低耦合”的设计原则，整个代码库可以划分为五个核心层次，从上到下依次是：数据层、图层、模型层、训练层和评估层。理解这个架构，你就能知道该在哪里修改代码以适应自己的需求。

2.1 数据层：不仅仅是读文件

数据层是地基。新闻推荐的数据通常至少包含两部分：用户-新闻交互日志（如点击、阅读时长）和新闻内容元数据（标题、摘要、分类、发布时间等）。

# 假设的数据结构示意，非真实代码
class NewsDataset(torch.utils.data.Dataset):
    def __init__(self, interactions_file, news_info_file, max_seq_len=50):
        self.interactions = load_interactions(interactions_file) # [(user_id, news_id, timestamp), ...]
        self.news_info = load_news_info(news_info_file) # {news_id: {'title':..., 'abstract':..., 'category':...}, ...}
        self.max_seq_len = max_seq_len
        self.user_seq = self._construct_user_sequence() # 按时间排序，构建每个用户的历史点击序列

    def _construct_user_sequence(self):
        # 将交互按用户分组，并按时间排序，形成用户历史序列
        # 这是后续进行序列推荐或构建用户图节点的基础
        pass

这里的关键点在于 序列构建 和 负采样 。新闻推荐往往是基于用户最近的行为序列来预测下一次点击。因此，如何截断或填充用户的历史序列（ max_seq_len ），对模型性能影响很大。太短，信息不足；太长，早期兴趣可能已失效，且计算开销大。

负采样则是推荐系统的老问题。对于每一个正样本（用户点击了的新闻），我们需要采样若干负样本（用户未点击的新闻）。NewsTorch通常会提供几种策略：

• 随机负采样 ：从全量新闻中随机抽取。简单，但可能采样到用户其实也会喜欢的新闻（曝光偏差）。
• 流行度加权负采样 ：更倾向于采样热门的负样本，因为用户没点击热门新闻，更能说明其不喜欢。
• Batch内负采样 ：在同一训练批次内，将其他用户的正样本作为当前用户的负样本。效率高，在像BERT4Rec这样的序列模型中常用。

在NewsTorch的架构里，数据层会输出规整的 (user_id, seq_news_ids, target_news_id, label) 这样的样本，供后续使用。

2.2 图层：将交互数据转化为图结构

这是NewsTorch支持GNN的核心。对于新闻推荐，我们通常构建一个 异构图 ，包含两种节点：用户(User)和新闻(News)。边只有一种：用户-新闻的点击边。

import torch_geometric as pyg

def build_interaction_graph(interactions):
    """
    interactions: List of (user_idx, news_idx)
    """
    # 构建边索引，PyG格式为 [2, num_edges]
    user_nodes = [u for u, _ in interactions]
    news_nodes = [n for _, n in interactions]
    edge_index = torch.tensor([user_nodes, news_nodes], dtype=torch.long)

    # 可以给边添加权重，如点击次数、阅读时长归一化值
    edge_weight = torch.tensor([1.0 for _ in interactions]) # 简化示例

    data = pyg.data.Data(edge_index=edge_index, edge_attr=edge_weight)
    # 还需要设置节点数量
    data.num_users = max(user_nodes) + 1
    data.num_news = max(news_nodes) + 1
    return data

但更高级的图构建会考虑 时序性 。例如，只将用户最近一段时间（如一周）内的交互加入图，或者构建多个按时间片划分的图快照，以捕捉兴趣演化。NewsTorch的图层应该提供这样的灵活性。

图层输出的 pyg.data.Data 对象，就是GNN模型的直接输入。此外，图层还可能负责计算一些图上的度量，如节点的度（衡量用户活跃度或新闻热度），作为额外的特征。

2.3 模型层：GNN与LLM的舞池

这是NewsTorch最核心、也最有趣的部分。模型层通常采用一种 双塔 或 融合 的架构，其中GNN和LLM各司其职。

2.3.1 LLM塔：负责新闻内容深度编码

传统方法可能用Word2Vec、TF-IDF或者一个简单的TextCNN来处理新闻标题。而在NewsTorch的愿景里，LLM塔应该利用像BERT、RoBERTa甚至更大的开源LLM（如Qwen、Llama）作为编码器。

from transformers import AutoModel, AutoTokenizer

class LLMNewsEncoder(nn.Module):
    def __init__(self, model_name='bert-base-uncased', freeze_layers=0):
        super().__init__()
        self.tokenizer = AutoTokenizer.from_pretrained(model_name)
        self.llm = AutoModel.from_pretrained(model_name)

        # 冻结前几层，减少计算量，防止过拟合
        if freeze_layers > 0:
            for param in list(self.llm.parameters())[:freeze_layers]:
                param.requires_grad = False

        # 一个投影层，将LLM的输出维度（如768）映射到我们统一的特征维度（如64）
        self.projection = nn.Linear(self.llm.config.hidden_size, 64)

    def forward(self, news_titles):
        # news_titles: List of strings
        inputs = self.tokenizer(news_titles, return_tensors='pt', padding=True, truncation=True, max_length=32)
        with torch.no_grad(): # 或根据是否微调决定
            outputs = self.llm(**inputs)
        # 取[CLS]位置的输出作为整个句子的表示
        cls_embedding = outputs.last_hidden_state[:, 0, :]
        projected_embedding = self.projection(cls_embedding)
        return projected_embedding

这里有几个实操细节：

• 微调还是冻结？ 对于新闻推荐，全量微调一个大LLM成本极高，且容易过拟合。通常的做法是冻结大部分底层参数，只微调顶层几层和投影层，或者采用LoRA等参数高效微调技术。NewsTorch应提供选项。
• 输入什么？ 只输入标题？还是标题+摘要？甚至前几句正文？需要权衡信息丰富度和计算开销。通常“标题+摘要”是个不错的起点。
• 长文本处理 ：新闻正文可能很长。需要设计策略，如截断、分段编码后池化等。

2.3.2 GNN塔：负责学习用户与新闻的协同信号

GNN塔以图层构建的交互图为输入，学习用户和新闻的嵌入表示。常用的GNN模型如LightGCN、GraphSAGE都适合这里。

import torch.nn.functional as F
from torch_geometric.nn import GCNConv, LightGCNConv

class UserNewsGNN(nn.Module):
    def __init__(self, num_users, num_news, embedding_dim, gnn_type='lightgcn', num_layers=2):
        super().__init__()
        self.user_embedding = nn.Embedding(num_users, embedding_dim)
        self.news_embedding = nn.Embedding(num_news, embedding_dim)

        if gnn_type == 'lightgcn':
            self.convs = nn.ModuleList([LightGCNConv() for _ in range(num_layers)])
        elif gnn_type == 'gcn':
            self.convs = nn.ModuleList([GCNConv(embedding_dim, embedding_dim) for _ in range(num_layers)])
        # ... 其他GNN类型

    def forward(self, graph_data):
        x = torch.cat([self.user_embedding.weight, self.news_embedding.weight], dim=0)
        all_embeddings = [x]

        for conv in self.convs:
            x = conv(x, graph_data.edge_index)
            # LightGCN通常不加激活函数和Dropout
            if not isinstance(conv, LightGCNConv):
                x = F.relu(x)
                x = F.dropout(x, p=0.2, training=self.training)
            all_embeddings.append(x)

        # 多层嵌入求平均，这是LightGCN的做法，能缓解过平滑
        final_embeddings = torch.mean(torch.stack(all_embeddings, dim=0), dim=0)

        user_embeds_final = final_embeddings[:self.user_embedding.num_embeddings]
        news_embeds_final = final_embeddings[self.user_embedding.num_embeddings:]

        return user_embeds_final, news_embeds_final

2.3.3 融合与预测

如何将LLM塔产出的富含语义的新闻特征，与GNN塔产出的富含协同信号的新闻特征结合起来？这是关键。

一种简单有效的方法是 特征拼接后通过MLP ：

class FusionPredictionLayer(nn.Module):
    def __init__(self, gnn_embed_dim, llm_embed_dim):
        super().__init__()
        # 假设GNN和LLM塔输出的新闻特征维度都是64
        self.fusion_mlp = nn.Sequential(
            nn.Linear(gnn_embed_dim + llm_embed_dim, 128),
            nn.ReLU(),
            nn.Dropout(0.2),
            nn.Linear(128, 64) # 融合后的新闻最终表示
        )
        # 用户侧，可能只用GNN塔学到的表示，或者也考虑用历史序列的LLM特征聚合
        self.user_mlp = nn.Sequential(
            nn.Linear(gnn_embed_dim, 64)
        )

    def forward(self, user_gnn_embed, news_gnn_embed, news_llm_embed):
        # 融合新闻特征
        news_fused = self.fusion_mlp(torch.cat([news_gnn_embed, news_llm_embed], dim=-1))
        # 处理用户特征（这里简化，直接投影）
        user_final = self.user_mlp(user_gnn_embed)

        # 计算匹配分数，例如内积
        score = torch.sum(user_final * news_fused, dim=-1)
        return score

更复杂的设计可能包括 交叉注意力 （让用户特征去关注新闻LLM特征的不同部分）或 门控机制 （动态决定更相信GNN特征还是LLM特征）。NewsTorch的理想状态是提供几种融合策略的模块化实现。

2.4 训练层：损失函数与优化技巧

新闻推荐本质是一个排序问题，因此常用 Pairwise Ranking Loss ，如BPR Loss (Bayesian Personalized Ranking)。它的思想是让正样本（用户点击过的新闻）的预测分数高于负样本（随机采样的未点击新闻）。

def bpr_loss(user_embed, pos_news_embed, neg_news_embed):
    pos_score = torch.sum(user_embed * pos_news_embed, dim=-1)
    neg_score = torch.sum(user_embed * neg_news_embed, dim=-1)
    loss = -torch.log(torch.sigmoid(pos_score - neg_score)).mean()
    return loss

在训练时，一个批次（Batch）的数据组织方式很重要。除了经典的BPR，对于序列推荐，可能会用 Cross-Entropy Loss 来预测下一个物品。NewsTorch的训练层需要灵活支持这些不同的损失函数。

另一个重要技巧是 梯度裁剪 和 学习率预热 。当模型融合LLM时，即使LLM大部分参数被冻结，训练过程仍可能不稳定。使用梯度裁剪（ torch.nn.utils.clip_grad_norm_ ）可以防止梯度爆炸。学习率预热（Warmup）则在训练初期使用较小的学习率，然后逐步增大，有助于模型稳定收敛。

2.5 评估层：不只是看AUC

推荐系统的评估指标需要多维度考量。NewsTorch应集成一系列标准指标：

• AUC ：衡量整体排序能力的经典指标。
• MRR (Mean Reciprocal Rank)：关注第一个相关结果出现的位置，对用户体验很重要。
• NDCG@K (Normalized Discounted Cumulative Gain)：尤其关注Top-K推荐列表的质量，是新闻推荐中最常用的指标之一（如NDCG@5, NDCG@10）。
• Hit Rate@K ：用户点击的新闻是否出现在推荐列表的前K位。

评估时，必须采用 留一法 或按时间划分的验证集，以模拟真实场景。即，用用户历史序列的前N-1个行为训练，预测第N个行为。绝不能随机划分，否则会引入数据穿越（用未来的行为预测过去）。

3. 实战指南：从零搭建一个NewsTorch实验

理论说了这么多，我们来点实际的。假设你现在拿到一个新闻点击数据集（例如MIND数据集的小型样本），想用NewsTorch快速跑通一个结合GNN和LLM的基线模型。以下是关键步骤和你会遇到的坑。

3.1 环境准备与数据预处理

首先，环境。你需要安装PyTorch（建议1.12+）、PyTorch Geometric（用于GNN）和Transformers库（用于LLM）。注意版本兼容性，特别是CUDA、PyTorch和PyG之间。

# 示例，具体版本请根据你的CUDA和系统调整
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.0.0+cu118.html
pip install torch-geometric
pip install transformers

数据预处理是脏活累活。原始日志通常是JSON或CSV格式。你需要：

1. 去重与过滤 ：过滤掉点击时间异常、新闻ID或用户ID缺失的记录。对于过于活跃的“机器人”用户或几乎无人点击的“僵尸新闻”，考虑按阈值过滤。
2. 构建映射字典 ：将原始的字符串 user_id 和 news_id 映射为连续的整数索引，这是PyTorch Embedding层的要求。
3. 划分数据集 ： 务必按时间排序后划分 。例如，取每个用户最后一天（或最后几次）的交互作为测试集，倒数第二天作为验证集，其余作为训练集。代码要确保训练集、验证集、测试集在时间上没有重叠。
4. 新闻文本处理 ：清洗新闻标题和摘要（去除特殊字符、统一大小写）。如果使用预训练LLM，注意其最大长度限制（如BERT通常是512），过长的文本需要截断。

3.2 模型定义与初始化

参照第2章的架构，定义你的双塔融合模型。这里有一个容易踩的坑： 参数初始化 。GNN的Embedding层和LLM的投影层如果初始化不当，可能导致训练初期梯度差异巨大，模型难以收敛。

def init_weights(m):
    if isinstance(m, nn.Linear):
        nn.init.xavier_uniform_(m.weight)
        if m.bias is not None:
            nn.init.zeros_(m.bias)
    elif isinstance(m, nn.Embedding):
        nn.init.normal_(m.weight, mean=0.0, std=0.02) # 较小的标准差

model = YourNewsTorchModel(...)
model.apply(init_weights) # 应用初始化
# LLM部分的参数已经由预训练权重初始化，不要重新初始化！

对于LLM塔，如果你选择微调部分层，要小心设置 requires_grad 。一个常见的策略是：冻结BERT的前10层，微调最后2层和池化层。

3.3 训练循环与调试

训练循环的模板大同小异，但有几个针对推荐系统的特殊点：

1. 负采样要在每个Epoch动态进行 ：不能一次性采样好所有负样本然后固定不变。因为模型在变化，之前“容易”的负样本可能变“难”了。最好在 DataLoader 的 __getitem__ 或每个训练批次开始时实时采样。
2. 评估频率 ：推荐模型训练通常很快（相比CV任务）。可以每半个或一个epoch就在验证集上评估一次，及时监控NDCG@10等指标，防止过拟合。
3. 早停策略 ：根据验证集上的NDCG@10是否持续提升来决定早停。耐心（patience）可以设得小一点，比如5个epoch。

调试时，如果发现Loss不下降或指标波动大，按以下顺序检查：

• 学习率 ：是否太大或太小？尝试一个数量级的变化（如从1e-3调到1e-4或1e-2）。
• 梯度 ：打印梯度的范数，看是否消失或爆炸。可以用 torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0) 。
• 数据 ：确认训练集、验证集没有数据泄露。检查负样本是否真的都是用户未交互过的（特别是Batch内负采样时）。
• LLM特征 ：尝试先不用LLM，只用ID特征+GNN，看模型能否正常学习。如果能，再接入LLM塔，此时如果出问题，大概率是LLM特征提取或融合部分有问题。

3.4 一个具体的融合策略实验

假设我们想对比“单纯GNN”、“GNN+静态词向量”、“GNN+LLM（冻结）”三种方案的效果。在NewsTorch的框架下，你可以这样设计实验：

1. Baseline (GNN Only) : 模型只包含GNN塔，新闻侧输入只有新闻ID的嵌入。
2. GNN + Word2Vec : 在Baseline上，为每个新闻ID预计算一个Word2Vec向量（基于新闻标题训练），将其与ID嵌入拼接后输入融合层。
3. GNN + LLM (Frozen) : 使用我们之前定义的 LLMNewsEncoder （冻结大部分层），在线计算新闻特征，然后与GNN的新闻嵌入融合。

你需要保持GNN部分的结构、层数、训练超参数（学习率、batch size等）完全一致，唯一变量就是新闻侧的特征来源。这样得到的性能对比（验证集NDCG@10）才是有说服力的。

在我的多次实验中，一个清晰的结论是： 引入LLM特征，即使是不微调的冻结LLM，也几乎总是能稳定提升效果，尤其是在处理长尾、冷启动新闻时 。因为Word2Vec或ID嵌入无法理解“俄乌冲突”和“巴以冲突”在语义上的相似性，而BERT可以。

4. 进阶话题与性能优化

当基础模型跑通后，你会开始追求更高的效果和更低的延迟。这里有几个NewsTorch可以拓展的进阶方向。

4.1 处理新闻的时效性与用户兴趣漂移

新闻的生命周期很短。昨天的头条，今天可能就无人问津。因此，模型必须能捕捉这种时效性。一种方法是在新闻特征中加入 时间衰减因子 。例如，将新闻的发布时间转化为一个“年龄”特征，并作为输入之一。

# 计算新闻年龄（以小时为单位）
news_publish_time = ... # 从数据中获取
current_time = ... # 训练/推理的时间点
news_age = (current_time - news_publish_time).total_seconds() / 3600.0
# 将news_age经过一个变换（如取对数）后，作为一个标量特征与LLM/GNN特征拼接
age_feature = torch.log1p(torch.tensor(news_age)).view(-1, 1)
final_news_feature = torch.cat([fused_embedding, age_feature], dim=-1)

对于用户兴趣漂移，可以在GNN中引入 时序图 。不是构建一个全局静态图，而是构建一系列按时间窗口（如每小时、每天）划分的图快照。然后使用类似DySAT或TGAT的时序GNN模型，来学习用户嵌入随时间的变化。

4.2 在线学习与增量更新

工业界的新闻推荐需要模型快速适应新新闻和新趋势。完全重新训练GNN和LLM是不现实的。NewsTorch可以考虑支持 增量学习 策略：

• GNN部分 ：对于新来的用户-新闻交互，可以动态更新图结构。一种近似方法是定期（如每5分钟）将新交互合并到图中，然后对受影响节点的嵌入进行几轮快速的近似传播（近似个性化PageRank），而不是全图重训练。
• LLM部分 ：对于新新闻，直接通过LLM塔计算其内容特征即可，这部分是独立的，不需要重新训练。
• 融合模型 ：可以定期（如每天）用最新的数据对顶层的融合MLP进行微调，以适应分布的变化。

4.3 部署与推理优化

训练好的模型最终要服务于线上推理。NewsTorch作为一个研究工具包，虽然不直接解决高并发部署，但可以提供利于部署的模型导出功能。

1. 模型剪枝与量化 ：使用PyTorch的 torch.quantization 对融合后的MLP层甚至GNN的Embedding进行量化（INT8），可以显著减少模型大小和提升推理速度，对精度影响很小。
2. 特征预计算与缓存 ：
   • 新闻特征 ：所有新闻的LLM特征和GNN ID嵌入可以预先计算好，存入向量数据库（如Faiss）或内存缓存。线上服务时直接读取。
   • 用户特征 ：这是瓶颈。当用户有新行为时，需要更新其GNN嵌入。一种生产级做法是维护一个用户嵌入服务，当用户产生新交互时，触发一个轻量级的图传播计算，异步更新其嵌入向量。
3. ANN检索 ：当新闻库达到百万甚至千万级时，为每个用户对所有新闻做内积排序是不现实的。需要借助近似最近邻搜索（ANN），如Faiss的IVFPQ或HNSW索引，先从全量新闻中快速检索出Top-K候选（比如1000个），再对这K个新闻用精排模型（即我们的融合模型）进行精确打分和排序。NewsTorch可以集成Faiss，提供“训练ANN索引”和“ANN检索+精排”的示例流程。

4.4 探索与利用的平衡

新闻推荐还有一个经典问题：探索与利用。模型容易推荐它认为“安全”的热门新闻，而忽略有潜力的新新闻（探索不足）。NewsTorch可以集成一些简单的探索策略，如：

• ε-greedy ：以概率ε随机推荐一条不在用户历史中的新新闻。
• Thompson Sampling 或 UCB ：将推荐问题建模为多臂老虎机，每个新闻是一个臂，模型预测的点击率作为收益的期望，同时维护一个不确定性估计（如预测方差），优先选择“期望高”或“不确定性大”的新闻。
• 在损失函数中加入多样性正则项 ：鼓励推荐列表中的新闻在主题、实体上更加分散。

这些策略可以作为模型输出排序分之后的后续处理模块，方便研究者进行AB测试。

5. 避坑指南：那些我踩过的雷

最后，分享一些在开发和实验过程中积累的血泪教训，希望能帮你节省时间。

坑1：数据泄露导致指标虚高 这是新手最容易犯的致命错误。切记，划分训练、验证、测试集必须 严格按时间顺序 。绝对不能随机打乱所有交互记录然后划分。否则，模型可能会用“未来”的行为来预测“过去”，得到虚假的高指标。一个检查方法是：确保测试集中所有交互发生的时间戳，都晚于训练集和验证集中的最大时间戳。

坑2：负样本采样偏差 如果你的负样本全是随机从全库采的，模型可能会学到“推荐冷门内容”，因为用户没点击冷门新闻太正常了。更好的做法是采用“流行度加权采样”或“曝光未点击”作为负样本（如果有曝光日志的话）。在NewsTorch中实现一个可插拔的负采样器接口，方便切换不同策略。

坑3：LLM特征“淹没”协同信号 当LLM特征维度（如768）远大于GNN ID嵌入维度（如64）时，直接拼接后，LLM特征可能会在后续MLP中占据主导，使得GNN学到的协同信号失效。解决方案：

• 使用一个投影层先将LLM特征降维到与GNN嵌入相近的维度（如64），再拼接。
• 使用门控机制（如FiLM），让模型自己学习如何平衡两种特征。

坑4：训练不稳定，Loss为NaN 当融合LLM时，即使冻结了参数，也可能因为特征数值范围差异导致梯度异常。除了梯度裁剪，还可以：

• 对LLM输出的特征进行 Layer Normalization ，再输入融合层。
• 检查输入数据是否有NaN或inf值（特别是处理时间特征时）。
• 在训练初期使用非常小的学习率（如1e-5）进行Warmup。

坑5：评估指标选择不当 AUC高不代表推荐列表好。对于新闻推荐，用户通常只看前几条。因此， NDCG@5、NDCG@10、HitRate@10 比AUC更有参考价值。确保你的评估脚本计算的是这些指标。同时，可以按新闻的热门程度分组评估，看看模型在长尾新闻上的推荐效果如何，这能反映其解决冷启动的能力。

坑6：忽略计算资源与效率 在本地用小型数据集调试成功后，直接上全量数据，可能导致内存爆炸（图太大）或训练极慢（LLM前向传播耗时）。建议：

• 对大型图，使用PyG的 NeighborSampler 进行图采样训练，而不是全图加载。
• 对LLM，使用 transformers 库的 AutoModel 时，注意设置 output_hidden_states=False 来减少输出，节省内存。
• 考虑使用混合精度训练（ torch.cuda.amp ），能在几乎不影响精度的情况下大幅减少显存占用并加速训练。

NewsTorch的价值，就在于它把这些常见的坑、最佳实践和模块化设计都沉淀下来，让你能更专注于推荐算法本身的创新，而不是反复在工程细节上挣扎。它不是一个完美的、银弹式的解决方案，而是一个坚实的起点。你可以基于它，快速尝试将最新的GNN架构（如HGT）、更强大的LLM（如多模态LLM处理图文新闻）、或者更复杂的序列建模方法（如Transformer）融入你的新闻推荐系统中，看看它们究竟能带来多少提升。