让大模型看懂关系网：GraphGPT 图数据分析与智能问答上手实战

让大模型看懂关系网：GraphGPT 图数据分析与智能问答上手实战

【免费下载链接】GraphGPT[SIGIR'2024] "GraphGPT: Graph Instruction Tuning for Large Language Models"项目地址: https://gitcode.com/gh_mirrors/gra/GraphGPT

假设你手里握着一张论文引用关系表、一份社交好友列表，或者一串电商用户-商品购买记录。你想让 AI 帮你回答"哪些节点最像同一类""这两个节点之间会不会有联系"，但你把表格丢给 ChatGPT，它只会回你一句"我看不懂这种结构"。这并不奇怪——常规大模型只认识文字，而你的数据藏在点与点之间的连线里。

GraphGPT 就是为解决这个尴尬而来的。它把图结构数据的编码与大型语言模型的自然语言理解拼到了一起：你问它问题，它真的"看"过你的图，然后像聊天一样把答案讲给你听。这是 SIGIR'2024 收录的研究成果（Graph Instruction Tuning for Large Language Models），而好消息是，它的代码仓库里已经备好了示例数据、训练脚本和完整的服务端代码，你完全可以照着这篇教程把它跑起来。

先搞懂它到底做了什么

一句话：GraphGPT 教会了大模型"读图"。

它没有把图变成一堆数字表格喂给模型，而是走了一条更巧的路——文本-图对齐（text-graph grounding）。你可以把它想象成给每个节点配了一张"身份证"，上面写着它的邻居是谁、它和谁相连、它的特征长什么样，然后让图编码器和语言模型在同一个"语义空间"里对表。图结构先被一个图 Transformer 编码，再通过投影层转成语言模型能读懂的 token，这样你的提问和图的"视觉"就在同一个对话里流通了。

仓库里的目录把这条链路分得很清楚：

• text-graph-grounding/：训练图编码器的实验场，自带 Cora 示例数据；
• graphgpt/train/：两阶段指令微调的训练代码（对应scripts/tune_script/下的 shell 脚本）；
• graphgpt/serve/：把训练好的模型包装成可对话的服务，Web 界面和命令行都有；
• graphgpt/eval/：批量评测模型在节点分类、链路预测任务上的表现。

装进你的环境：从零到能跑的三步

装这个项目不像装普通 pip 包，它依赖 PyTorch、图神经网络库 PyG 和 FastChat，所以建议按下面的顺序一气呵成。

第一步，建一个干净的环境并装好底层计算库。推荐用 conda 隔离一个独立环境，避免污染你现有的 Python：

conda create -n graphgpt python=3.8 conda activate graphgpt

接着装带 CUDA 的 PyTorch（官方推荐 1.13 + CUDA 11.7 的搭配）：

pip install torch==1.13.0+cu117 torchvision==0.14.0+cu117 torchaudio==0.13.0 --extra-index-url https://download.pytorch.org/whl/cu117

第二步，把图神经网络三件套补齐。模型要用 PyG 来操作图数据，这一步别偷懒，版本要和 PyTorch 严格对应：

pip install torch_geometric pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-1.13.0+cu117.html

第三步，拉代码、装剩余依赖。仓库地址在这里，直接克隆到本地：

git clone https://gitcode.com/gh_mirrors/gra/GraphGPT cd GraphGPT pip install -r requirements.txt

装完后用pip check快速验一下依赖有没有冲突。如果哪一步报错，多半是版本不对齐，回到对应命令重新装即可。到这里，环境就绪，接下来我们跑点真东西。

第一个能出结果的任务：让图编码器学会"看图说话"

先从仓库里自带的最小数据集 Cora 开始。Cora 是图学习界的"hello world"——2700 多篇论文按引用关系连成一张网，每篇论文有文本和类别标签。它的数据文件就放在text-graph-grounding/data/Cora/下：

• Cora_edge.npy：节点之间的边（谁引用了谁）；
• Cora_f_bert.npy：每个节点的 BERT 特征向量；
• Cora_text.json：每篇论文的标题摘要文本；
• Cora_id_labels.json：节点对应的类别标签。

我们要做的第一件事，是运行text-graph-grounding下的预训练脚本，让图编码器学会把"图的邻居结构"和"节点文字"对齐到同一个向量空间。这个过程就是论文里说的文本-图对齐，也是整个 GraphGPT 能看懂图的基础。

直接敲下面这行命令即可：

cd text-graph-grounding python main_train.py --data_name Cora --epoch_num 2

程序会加载 Cora 的边和文本，每一轮训练都打印 loss。你会看到 loss 从初始值一路往下掉——这就是编码器正在把"图视角"和"文本视角"逐渐拧到一块儿。训练结束后，模型权重会保存为res/Cora/目录下的.pkl文件。

跑通这一步你就拥有了 GraphGPT 的"眼睛"。它本身是小规模实验，一张普通 GPU 甚至 CPU 都能撑住，非常适合用来验证你的环境是否真的装对了。

让它开口说话：把训练好的模型变成聊天机器人

有了图编码器还不够，真正和你对话的是背后那个大语言模型。GraphGPT 的完整链路是：用 Vicuna 作为底座大模型，先做两阶段指令微调，再部署成服务。仓库里已经把这些步骤打包成了脚本：

sh ./scripts/tune_script/graphgpt_stage1.sh # 第一阶段：图匹配自监督微调 sh ./scripts/tune_script/graphgpt_stage2.sh # 第二阶段：针对节点分类/链路预测做任务微调

两个脚本开头都是一串待填的空变量（模型路径、指令数据、图数据路径等），照着脚本注释填完就能跑。需要注意的是，这一步需要真实的 GPU 资源——官方在两张 24GB 的 3090 上就能完成两阶段微调，如果资源有限，也可以直接下载论文发布页提供的训练好的 checkpoint 跳过这一步。

模型就绪后，部署一个能对话的服务。GraphGPT 采用了经典的"控制器 + 工作节点"架构：controller_graph.py负责调度，model_worker_graph.py负责真正跑模型，gradio_web_server_graph.py是给你用的聊天界面。按顺序开三个终端：

python graphgpt/serve/controller_graph.py # 终端1：调度中心 python graphgpt/serve/model_worker_graph.py --model-path 你的模型目录 # 终端2：加载模型 python graphgpt/serve/gradio_web_server_graph.py --port 7860 # 终端3：Web界面

浏览器打开本地 7860 端口，一个聊天界面就在眼前了：

在这个界面里，你可以直接问模型类似"分析一下这个节点的类别"或"预测这两个节点之间是否存在连边"的问题——它会结合你指定的图数据，像普通助手一样流式回答。如果你不喜欢图形界面，cli.py提供了一个更轻量的命令行对话方式，适合快速测试和脚本集成：

想验证效果？批量评测来兜底

闲聊式的验证还不够严谨。仓库里准备了完整的评测流水线：graphgpt/eval/目录下有评测代码，scripts/eval_script/graphgpt_eval.sh是一个现成的评测脚本。你只需要填上模型路径、评测指令数据路径和图数据路径，它就会在测试集上逐条提问并把模型回答保存为 JSON 文件，之后你可以拿这些回答跟标准答案比对，计算分类准确率或链路预测的命中率。评测脚本支持多 GPU 并行，评测数据量大的时候能省不少时间。

你可能遇到的坎，先帮你趟一遍

• 模型加载报No module named 'graphgpt'？这是没把仓库根目录加进 Python 路径。在GraphGPT根目录下运行脚本，或者把根目录加入PYTHONPATH就能解决。
• flash-attention 报错？训练脚本里默认启用了 flash attention 优化。如果你用的 GPU 或环境不兼容，把graphgpt/train/train_mem.py里调用replace_llama_attn_with_flash_attn()的那一行注释掉即可。
• PyG 相关包装不上？检查 PyTorch 版本，torch_geometric及其配套的 scatter/sparse 库必须与你的 CUDA 和 PyTorch 版本严格对应，去 PyG 官网按版本挑对应 wheel 是最稳妥的做法。
• 想用轻量训练方案？官方更新了基于 PyTorch 2.1 + Lightning 的轻量训练脚本（scripts/tune_script_light/目录下），两张 3090 就能跑，条件允许的话优先用它。
• 跑服务时界面里没有模型可选？大概率是模型 worker 没注册成功，检查 worker 终端里的报错日志，确认--controller-address指向的端口和 controller 一致。

接下来，往哪走

到现在，你应该已经跑通了"图编码器预训练 → 模型微调 → 对话服务 → 批量评测"这条完整链路。GraphGPT 的源码并不复杂，几个模块职责很清晰：图结构相关的核心实现在graphgpt/model/graph_layers/，训练逻辑在graphgpt/train/，服务部署在graphgpt/serve/。想深入的话，可以先看看graphgpt/model/graph_layers/graph_transformer.py里图编码是怎么实现的，再对照论文把两阶段微调的数据流捋一遍。

把图结构数据和自然语言对齐这件事，GraphGPT 只是起点。你可以试着把自己的数据换成和 Cora 相同的格式，喂给微调脚本，做出一个真正懂你业务数据的图分析助手。动手跑一次，比读十遍论文都管用。

【免费下载链接】GraphGPT[SIGIR'2024] "GraphGPT: Graph Instruction Tuning for Large Language Models"项目地址: https://gitcode.com/gh_mirrors/gra/GraphGPT