自定义GNN层最可控：需用tf.keras.layers.Layer手动实现消息传递，邻接矩阵必须用tf.SparseTensor表示，聚合用tf.gather+tf.reduce_mean等，避免Python循环和错误掩码应用。
用 tf.keras.layers.Layer 自定义 GNN 层最可控
TensorFlow 原生不提供开箱即用的 GraphConv 或 GATLayer，硬套 tf.keras.Sequential 会卡在邻接矩阵处理上。必须自己实现消息传递逻辑，核心是把邻居聚合写进 call() 方法里。
常见错误：直接把节点特征和邻接矩阵拼成张量喂给 Dense 层——这完全没体现图结构，等价于丢掉图信息跑 MLP。
- 邻接矩阵要用稀疏张量
tf.SparseTensor表示，否则内存爆炸（尤其千级节点以上） - 聚合操作别用 Python 循环，改用
tf.gather+tf.reduce_mean或tf.math.unsorted_segment_sum - 如果用边特征，记得在
call()里传入并参与消息计算，不是只靠节点特征
tensorflow-gnn 库比手写更省事，但得绕过版本陷阱
Google 官方的 tensorflow-gnn 是目前最贴近标准 GNN 实现的封装，但它不兼容 TF 2.15+ 的 eager mode 默认行为，装完常报 AttributeError: 'NoneType' object has no attribute 'op'。
使用场景：需要快速验证 GCN、GAT、GraphSAGE 在 citation 数据集上的 baseline，且能接受额外依赖。
立即学习“Python免费学习笔记（深入）”；
- 必须用
pip install tensorflow-gnn==0.7.0（对应 TF 2.13～2.14） - 数据要转成
tfgnn.GraphTensor，不能直接用 numpy 数组；节点/边特征得挂载在context、node_sets、edge_sets字典里 -
tfgnn.keras.layers.MapFeatures和tfgnn.keras.layers.GraphUpdate是构建块，别试图用Model.fit()直接喂原始图数据
训练时图结构固定，但动态图得手动重构建 SparseTensor
多数教程默认图结构不变，所以邻接矩阵只初始化一次。但如果你做时序图（如社交网络每小时快照）、或 mini-batch 图采样（如 ClusterGCN），每次前向传播的邻接关系都不同——这时 SparseTensor 必须在 call() 内实时构造。
性能影响明显：频繁调用 tf.sparse.SparseTensor 构造函数比复用静态张量慢 3～5 倍，尤其 batch size > 32 时。
- 用
tf.py_function包裹图采样逻辑（如torch-geometric的ClusterData），再转成稀疏索引 - 避免在
@tf.function装饰的函数里做图结构判断（如if len(edges) > 0），会导致 retracing - 动态图建议用
tf.Variable缓存稀疏索引三元组（indices,values,dense_shape），只更新values
评估指标容易错在掩码应用顺序
图节点分类任务中，训练/验证/测试节点是按掩码划分的（如 train_mask 是 bool 张量），但很多人把掩码用在 loss 计算后——导致梯度回传到所有节点，模型其实“偷看”了测试节点。
正确做法是：loss 输入前就用掩码截断 logits 和 labels，而不是对整个 batch 算完 loss 再乘掩码。
- 错误写法：
loss = tf.keras.losses.categorical_crossentropy(y_true, y_pred); loss = tf.reduce_mean(loss * train_mask) - 正确写法：
y_true_masked = tf.boolean_mask(y_true, train_mask); y_pred_masked = tf.boolean_mask(y_pred, train_mask); loss = tf.keras.losses.categorical_crossentropy(y_true_masked, y_pred_masked) - 注意
tf.boolean_mask会改变 batch 维度，后续 metrics（如accuracy）也要同步 mask，否则值失真
图神经网络在 TensorFlow 里没有“一键启动”路径，关键不在会不会调库，而在是否理解消息传递的张量形状怎么对齐——邻接矩阵的稀疏索引、节点特征的 batch 维、mask 的布尔广播，三者错一个，结果就全偏。动手前先拿 3 个节点的小图手推一遍 tf.gather 的输出 shape。
