HTGformer

HTGformer（Heterogeneous Temporal Graph Transformer）复现/实验代码：将异质图按时间快照组织，并使用 本地 LLM（LLaMA3/Qwen 等） 生成“节点类型语义嵌入”，用于节点级预测任务（节点分类/链路预测）。

说明

• 本仓库是自己读到一篇论文《HTGformer: Heterogeneous Temporal Graph Transformer》发现没有源码，根据自己对论文的理解复现了代码，只在OGBN-MAG数据上进行了测试，原文链接附上：https://doi.org/10.1145/3726302.3730209

目录结构

• scripts/preprocess.py：将原始数据转换为时间快照（snapshot_{t}.pt）
• scripts/train.py：基础训练脚本（单次训练）
• scripts/experiment.py：完整实验脚本（多次运行、早停、节点分类/链路预测等）
• scripts/evaluate.py：评估脚本（当前包含 dummy label 的占位逻辑，更多用于检查流程）
• data/：快照格式与数据加载
• models/、trainer/、utils/：模型与训练/评估逻辑

环境准备

建议使用 Conda / venv（Python 3.9+）。

1. 安装基础依赖

pip install -r requirements.txt

2. 安装 PyTorch（按你的 CUDA 版本选择）

# 示例：CUDA 11.8
pip install --index-url https://download.pytorch.org/whl/cu118 torch torchvision torchaudio

3. 可选：安装 PyG 相关扩展（如你使用 OGBN-MAG/torch_geometric）

注意：torch-scatter/torch-sparse/torch-cluster 必须与 torch/CUDA 匹配，否则会出现 undefined symbol。

快速开始（以 OGBN-MAG 为例）

1) 预处理：生成时间快照

python scripts/preprocess.py --dataset ogbn-mag --num_snapshots 10

生成目录（示例）：

• data/processed/ogbn-mag/metadata.pt
• data/processed/ogbn-mag/snapshots/snapshot_0.pt ... snapshot_9.pt

2) 训练（单次）

python scripts/train.py \
  --config configs/ogbn_mag.yaml \
  --epochs 100 \
  --gpu 0 \
  --llm_model /path/to/your/local_llm \
  --force_regenerate

说明：

• --llm_model：本地 LLM 路径或 HuggingFace 兼容模型名（默认见 llm/llm_encoder.py）
• 类型嵌入会缓存到 llm/cache/，重复训练可复用（除非 --force_regenerate）

3) 完整实验（推荐）

scripts/experiment.py 集成了多次运行/早停/输出日志等，适合复现实验与做消融。

python scripts/experiment.py --config configs/ogbn_mag.yaml --gpu 0 --epochs 500

（如需后台运行）

nohup python scripts/experiment.py --config configs/ogbn_mag.yaml --gpu 0 --epochs 500 \
  > log_$(date +%Y%m%d_%H%M%S).log 2>&1 &
disown

支持的数据集

见 DATASETS.md，当前内置：

• ogbn-mag（原论文数据集，带年份，可按 2010–2019 生成快照）

快照数据格式

每个 snapshot_{t}.pt（字典）包含：

• node_features: {node_type: FloatTensor[num_nodes, feature_dim]}
• adjacency: {relation: LongTensor[2, num_edges]}
• labels（可选）：{target_node_type: LongTensor[num_nodes]}

更多细节见 DATASETS.md / NEW_DATASET_GUIDE.md。

新数据集接入

按 NEW_DATASET_GUIDE.md 的步骤：

1. 在 scripts/preprocess.py 添加 preprocess_your_dataset()
2. 在 data/dataset_loader.py:get_dataset_config() 注册元信息
3. 新建 configs/your_dataset.yaml

W&B 日志上传（可选）

如你有文本日志并希望同步到 W&B，可用：

python scripts/upload_log_to_wandb.py \
  --logfile path/to/your.log \
  --project your_project \
  --entity your_entity

常见问题

• 导入 PyG 扩展报 undefined symbol：通常是 torch 与 torch-scatter/torch-sparse/torch-cluster 版本不匹配；请按你的 torch==...+cuXXX 重新安装匹配 wheel。