ogb 完整教學

Repository: https://github.com/snap-stanford/ogb Stars: 2090 | Forks: 409 | Language: Python | License: MIT Homepage: https://ogb.stanford.edu Topics: graph-machine-learning, graph-neural-networks, deep-learning, datasets

1. 專案概覽 (Project Overview)

1.1 專案背景與研究團隊

OGB（Open Graph Benchmark; 開放圖形基準)是由 Stanford SNAP (Stanford Network Analysis Project; 史丹佛網路分析專案) 實驗室——由 Jure Leskovec 教授領導——所發起的圖機器學習 (graph machine learning; GML) 基準資料集集合。核心作者群包含 Weihua Hu、Matthias Fey（同時也是 PyTorch Geometric 的創建者)、Marinka Zitnik、Yuxiao Dong、Hongyu Ren、Bowen Liu、Michele Catasta 與 Jure Leskovec，論文〈Open Graph Benchmark: Datasets for Machine Learning on Graphs〉發表於 NeurIPS 2020。

在 OGB 出現之前，圖神經網路 (graph neural network; GNN) 研究社群長期依賴一批「玩具級」資料集：Cora、Citeseer、PubMed 這類引用網路，節點數僅數千、邊數僅數萬。這些資料集規模過小，導致：

1. 模型天花板效應：幾乎所有新方法在這些小資料集上都能宣稱「達到 SOTA (state-of-the-art; 最先進水準)」，因為資料集小到很容易 overfitting (過擬合)，難以區分方法的真實有效性。
2. 評估協定不統一：不同論文用不同的 train/valid/test split（甚至隨機切分)，導致跨論文比較毫無意義。
3. 缺乏真實世界規模：真實世界的圖（例如分子資料庫、知識圖譜、學術引用網、蛋白質交互網路)動輒百萬到十億級別的節點與邊，小資料集無法反映方法在此規模下的表現與可擴展性 (scalability)。

OGB 正是為了解決這三個問題而生：提供大規模、跨領域、標準化切分、統一評估協定的基準資料集，讓 GNN 研究能像電腦視覺領域的 ImageNet 一樣，有一個公認的競賽場。

1.2 解決的問題與重要性

OGB 的核心價值主張可以歸納為三個層面：

• 資料集層面：提供從小型 (可單 GPU 訓練) 到超大型 (需要多 GPU / 圖切分技術) 的資料集光譜，涵蓋節點預測 (node prediction)、連結預測 (link prediction)、圖預測 (graph prediction) 三大任務類型。
• 工程層面：提供與 PyTorch Geometric (PyG) 與 Deep Graph Library (DGL) 完全相容的 dataloader，自動下載、自動處理、標準切分，開發者只需 3-4 行程式碼即可拿到可訓練的資料。
• 評估層面：提供 Evaluator 類別，把「用什麼指標評估」這件事從研究者手中收回，統一為官方定義的 metric（如 ROC-AUC、Accuracy、MRR 等)，確保論文之間可以公平比較，並支撐 OGB 官方排行榜 (Leaderboard)。

這對整個領域的重要性在於：它把 GNN 研究從「各自為政的小資料集實驗」轉變為「可累積、可比較、可信任」的科學基準測試典範，類似 ImageNet 之於電腦視覺、GLUE 之於 NLP。

1.3 在 snap-stanford 生態系中的定位

SNAP 實驗室維護一系列圖分析相關開源專案，OGB 在其中扮演「基準與評估層」的角色：

• SNAP.PY / SNAP C++：底層大規模圖分析函式庫，處理圖的載入、演算法計算。
• PyTorch Geometric (PyG，非 SNAP 自家但深度整合)：GNN 模型層，負責模型架構與訓練迴圈。
• OGB：資料與評估層，站在模型與資料之間，是連接「有新想法的研究者」與「值得信賴的評測結果」的橋樑。
• OGB-LSC (Large-Scale Challenge)：OGB 的超大規模擴充版本 (MAG240M、PCQM4M、WikiKG90M)，用於 KDD Cup 競賽，推動十億級圖規模的方法研究。

換言之，OGB 不是一個模型框架，而是標準化的度量衡系統——它定義了「怎麼切資料」「怎麼算分數」，讓生態系其他工具（PyG、DGL）有共同的評測基礎。

1.4 相關論文引用

 1@article{hu2020ogb,
 2  title={Open Graph Benchmark: Datasets for Machine Learning on Graphs},
 3  author={Hu, Weihua and Fey, Matthias and Zitnik, Marinka and Dong, Yuxiao and Ren, Hongyu and Liu, Bowen and Catasta, Michele and Leskovec, Jure},
 4  journal={arXiv preprint arXiv:2005.00687},
 5  year={2020}
 6}
 7
 8@article{hu2021ogblsc,
 9  title={OGB-LSC: A Large-Scale Challenge for Machine Learning on Graphs},
10  author={Hu, Weihua and Fey, Matthias and Ren, Hongyu and Nakata, Maho and Dong, Yuxiao and Leskovec, Jure},
11  journal={arXiv preprint arXiv:2103.09430},
12  year={2021}
13}

2. 核心架構 (Core Architecture)

2.1 系統架構圖

OGB 的程式碼庫依照三大任務類型 (node / link / graph) 切分為三個子套件，並共用底層的 I/O 與工具模組。

flowchart TB
    subgraph pkg["ogb 套件根目錄"]
        subgraph node["ogb.nodeproppred（節點屬性預測）"]
            n1["dataset.py
NodePropPredDataset"]
            n2["dataset_pyg.py
PygNodePropPredDataset"]
            n3["dataset_dgl.py
DglNodePropPredDataset"]
            n4["evaluate.py
Evaluator"]
            n5["master.csv
資料集中繼資料"]
        end

        subgraph link["ogb.linkproppred（連結預測）"]
            l1["dataset.py"]
            l2["dataset_pyg.py"]
            l3["dataset_dgl.py"]
            l4["evaluate.py"]
            l5["master.csv"]
        end

        subgraph graph["ogb.graphproppred（圖屬性預測）"]
            g1["dataset.py"]
            g2["dataset_pyg.py"]
            g3["dataset_dgl.py"]
            g4["evaluate.py"]
            g5["mol_encoder.py
AtomEncoder / BondEncoder"]
            g6["master.csv"]
        end

        subgraph io["ogb.io（共用 I/O 層）"]
            io1["read_graph_raw.py"]
            io2["read_graph_pyg.py"]
            io3["read_graph_dgl.py"]
            io4["save_dataset.py"]
        end

        subgraph utils["ogb.utils（共用工具）"]
            u1["url.py
自動下載"]
            u2["mol.py
SMILES→圖轉換"]
            u3["features.py
原子/鍵特徵表"]
            u4["torch_util.py"]
        end

        subgraph lsc["ogb.lsc（超大規模挑戰賽）"]
            lsc1["mag240m.py"]
            lsc2["pcqm4mv2.py"]
            lsc3["wikikg90mv2.py"]
        end
    end

    node --> io
    link --> io
    graph --> io
    node --> utils
    link --> utils
    graph --> utils
    lsc --> io
    lsc --> utils

    external["外部框架"] -.相容.-> node
    external -.相容.-> link
    external -.相容.-> graph
    ext2["PyTorch Geometric / DGL"] --> external

2.2 關鍵模組、類別與資料流說明

OGB 每個任務子套件都遵循相同的三件式設計模式 (design pattern)：

master.csv 是每個子套件的「中繼資料表 (metadata table)」，記錄了每個資料集的下載網址、任務數量 (num tasks)、評估指標 (eval metric)、切分方式等。這個設計讓新增資料集時只需要在 CSV 增加一列，而不需要改動核心程式碼——這是典型的資料驅動設計 (data-driven design)，把「哪些資料集存在」與「資料集怎麼被處理」解耦。

資料流可以用下圖表示：

sequenceDiagram
    participant U as 使用者程式碼
    participant D as PygXxxPropPredDataset
    participant M as master.csv
    participant Net as 遠端伺服器（Stanford）
    participant Cache as 本地 dataset/ 快取
    participant E as Evaluator

    U->>D: dataset = PygGraphPropPredDataset(name)
    D->>M: 查詢 name 對應的 url / 任務資訊
    D->>Cache: 檢查本地是否已有快取
    alt 快取不存在
        D->>Net: 下載壓縮檔（zip）
        Net-->>D: 回傳原始資料
        D->>D: 解析並轉換為 PyG Data 物件
        D->>Cache: 寫入快取（processed/）
    else 快取存在
        Cache-->>D: 直接讀取
    end
    D-->>U: 回傳 dataset 物件
    U->>D: split_idx = dataset.get_idx_split()
    D-->>U: {"train":…, "valid":…, "test":…}
    U->>U: 模型訓練與推論產生 y_pred
    U->>E: evaluator = Evaluator(name)
    U->>E: evaluator.eval({"y_true":…, "y_pred":…})
    E->>M: 查詢官方 eval metric
    E-->>U: {"rocauc": 0.7321} 等標準化結果

2.3 設計哲學與技術選擇分析

1. 框架中立 + 框架特化並存：核心 dataset.py 完全不依賴 PyTorch 或 DGL，只用 numpy/pandas 處理資料；dataset_pyg.py 與 dataset_dgl.py 是薄包裝層 (thin wrapper)。這種設計讓核心邏輯可測試、可重用，也讓使用者能自由選擇深度學習框架而不被綁架——這是一個值得學習的關注點分離 (separation of concerns) 範例。

2. CSV 驅動的中繼資料：不把資料集資訊寫死在 Python 程式碼裡，而是外部化到 master.csv。這消除了「新增資料集需要改程式碼」的特殊情況，是一種簡化資料流的做法。

3. 標準化 split 而非隨機 split：OGB 刻意採用「結構化切分 (structural split)」，例如分子資料集用 scaffold split（依化學骨架切分，而非隨機切分），刻意製造 train/test 之間的分布差異 (distribution shift)，這樣才能真實反映模型的泛化能力 (generalization) 而非死記硬背。

4. Evaluator 與 Dataset 解耦：評估邏輯獨立於資料載入邏輯，即使使用者自建模型完全不使用 OGB dataloader，也能單獨使用 Evaluator 驗證自己的預測格式與分數。

3. 安裝與設定 (Installation & Setup)

3.1 環境需求

根據官方 README，OGB 對環境的要求如下：

GPU 需求：OGB 本身（資料下載、切分、評估）不需要 GPU。GPU 需求來自訓練 GNN 模型時使用的 PyTorch/DGL，依資料集規模而異——小型資料集（如 ogbn-arxiv）單張消費級 GPU（8GB 顯存）即可訓練；大型資料集（如 ogbn-papers100M，1.1 億節點）建議使用多 GPU 或子圖抽樣 (subgraph sampling) 技巧；OGB-LSC 系列（如 MAG240M）則接近或超過單機記憶體上限，需分散式或圖切分方案。

3.2 完整安裝步驟

依照 CLAUDE.md 全域鐵律，Python 套件管理一律使用 uv，避免直接用 pip 當主要安裝方式：

 1# 1. 建立獨立虛擬環境（以 uv 取代裸 python -m venv + pip）
 2uv venv ogb-env --python 3.10
 3source ogb-env/bin/activate
 4
 5# 2. 先安裝 PyTorch（依你的 CUDA 版本，以官方指令為準）
 6uv pip install torch --index-url https://download.pytorch.org/whl/cu121
 7
 8# 3. 安裝 PyTorch Geometric（若走 PyG 路線）
 9uv pip install torch_geometric
10
11# 4. 安裝 OGB 本體
12uv pip install ogb
13
14# 5. 驗證安裝版本
15python -c "import ogb; print(ogb.__version__)"
16# 應輸出如 1.3.6；若過舊執行 uv pip install -U ogb

若需要從原始碼安裝（例如要修改或貢獻程式碼)：

1git clone https://github.com/snap-stanford/ogb
2cd ogb
3uv pip install -e .

⚠️ 官方 README 特別提醒：若先前已安裝過舊版 OGB，務必更新到 1.3.6 以上，因為早期版本的資料集切分或欄位定義可能與新版不相容，混用版本會導致下載到的資料格式與程式碼不匹配。

3.3 資料集下載與準備

OGB 採用惰性下載 (lazy download) 模式：資料集不會隨套件安裝，而是第一次呼叫 Dataset 建構子時才自動從 Stanford 伺服器下載並快取到本地資料夾。

1from ogb.nodeproppred import PygNodePropPredDataset
2
3# 第一次執行會自動下載、解壓、處理，並快取到 ./dataset/ogbn_arxiv/
4dataset = PygNodePropPredDataset(name='ogbn-arxiv', root='dataset/')
5
6# 之後再次執行同一行程式碼，會直接讀取本地快取，不再重新下載

下載後的目錄結構大致如下：

1dataset/
2└── ogbn_arxiv/
3    ├── raw/            # 原始下載檔案（edge.csv.gz、node-feat.csv.gz 等）
4    ├── processed/       # 處理過的 .pt（PyG）或其他框架格式快取
5    └── split/           # 官方標準 train/valid/test 索引

若要手動控制下載位置（例如公司內網無法連外，需離線放置資料），可以將資料夾結構依照上述格式手動建立，並將 root 參數指向該目錄，OGB 會偵測到 processed/ 已存在而跳過下載。

3.4 常見問題排解

4. 核心概念詳解 (Key Concepts)

4.0 資料集規模光譜完整速查

在深入任務類型之前，先建立「OGB 資料集橫跨多大規模」的直觀感受。下表列出各任務類型下具代表性的資料集規模（節點數/邊數為概略量級）：

可以觀察到一個重要規律：圖層級任務（ogbg）的「圖」本身很小（通常幾十個原子），但「圖的數量」很多（數萬到數十萬張獨立小圖）；而節點/連結層級任務（ogbn/ogbl）通常只有一張巨大的圖。這個規模結構上的差異，直接決定了訓練時的 batch 策略——圖層級任務用「多張小圖組成 batch」（類似圖片分類的 mini-batch），節點/連結層級任務則需要「在單一大圖上做子圖抽樣」組成 batch。

flowchart TB
    subgraph small["圖層級任務資料形態"]
        direction LR
        s1["圖 1
(小分子)"] 
        s2["圖 2
(小分子)"]
        s3["圖 3
(小分子)"]
        sdots["... 數萬張"]
    end
    subgraph big["節點/連結層級任務資料形態"]
        direction LR
        b1["單一巨型圖
(百萬~億級節點)"]
    end
    small -->|"batch = 多張獨立小圖"| batch1["DataLoader mini-batch"]
    big -->|"batch = 子圖抽樣(neighbor sampling)"| batch2["NeighborLoader mini-batch"]

4.1 三大任務類型：用「班級」來類比

想像一個班級（圖），學生是節點 (node)，同學之間的互動關係是邊 (edge)：

• 節點屬性預測 (node property prediction; ogbn)：預測「每個學生的興趣分類」——已知全班的互動關係，猜每個學生屬於哪個社團。例如 ogbn-arxiv 預測論文的研究領域分類。
• 連結預測 (link property prediction; ogbl)：預測「兩個學生之間未來會不會變成好友」——已知現有的互動網路，猜哪些「邊」會出現或消失。例如 ogbl-collab 預測學者未來是否會合作發表論文。
• 圖屬性預測 (graph property prediction; ogbg)：把「整個班級」視為一個單位來預測屬性——例如給定一整個分子（化學鍵結構的圖），預測這個分子的某項化學性質（如是否有毒性）。ogbg-molhiv 就是預測整個分子圖是否能抑制 HIV 病毒複製。

flowchart LR
    subgraph node_task["節點層級任務（ogbn）"]
        direction TB
        n_ex["輸入：整張圖
輸出：每個節點的類別
例：ogbn-arxiv 論文分類"]
    end

    subgraph link_task["連結層級任務（ogbl）"]
        direction TB
        l_ex["輸入：整張圖（部分邊被遮蔽）
輸出：某兩節點間是否存在邊
例：ogbl-collab 合作預測"]
    end

    subgraph graph_task["圖層級任務（ogbg）"]
        direction TB
        g_ex["輸入：大量獨立的小圖
輸出：每張圖的整體屬性
例：ogbg-molhiv 分子毒性"]
    end

    node_task -->|規模逐漸縮小
但數量增加| graph_task

4.2 標準化 Split 的直觀理解

一般機器學習的隨機切分，就像「隨機把全班學生分成訓練組和測驗組」——但如果測驗組跟訓練組的學生本來就很相似（比如都住同一條街），模型很容易靠死記硬背就拿高分，這不代表模型真的學會了「規律」。

OGB 的許多資料集刻意使用結構化切分，製造 distribution shift（分布位移），確保模型必須學到「可泛化的規律」才能表現好：

• ogbn-arxiv：依論文發表年份切分——用較早年份的論文訓練，較晚年份的論文測試，模擬真實世界「用歷史資料預測未來」的情境。
• ogbg-molhiv：依分子的 **scaffold（化學骨架）**切分——結構相似的分子會被分到同一組，避免模型只是記住「看起來像的分子往往有類似性質」這種捷徑。
• ogbl-collab：依合作發生的時間切分——用早期合作紀錄預測晚期是否會產生新合作。

4.3 Evaluator 抽象化：為什麼不讓研究者自己算分數？

如果每個人都自己寫 ROC-AUC 或 Accuracy 計算程式碼，很容易因為小小的實作差異（比如處理 NaN 的方式、多任務時是否取平均、二分類 threshold 設定）導致同一個模型在不同論文報出不同分數。OGB 的 Evaluator 把這件事「收斂到單一真相來源 (single source of truth)」：

flowchart TB
    A["使用者的 y_true / y_pred"] --> B{"Evaluator 依
master.csv 判斷
官方 eval metric"}
    B -->|"rocauc"| C["_eval_rocauc()
sklearn.roc_auc_score"]
    B -->|"acc"| D["_eval_acc()"]
    B -->|"mrr / hits@K"| E["連結預測專用指標"]
    C --> F["回傳標準化 dict
如 {'rocauc': 0.7321}"]
    D --> F
    E --> F

這個「格式檢查 + 指標計算」二階段設計（見 _parse_and_check_input 再 eval）也是一種防禦性程式設計 (defensive programming)：提早在輸入階段抓出形狀 (shape) 不符、任務數不符、型別不符等錯誤，避免計算到一半才崩潰或算出無意義的分數。

4.4 分子圖的特徵編碼：AtomEncoder / BondEncoder

在圖屬性預測中，分子資料集（如 ogbg-molhiv、ogbg-molpcba）把每個原子和化學鍵表示為類別型特徵向量（例如原子序、電荷、是否為芳香環的一部分等），而不是連續數值。AtomEncoder 和 BondEncoder（在 ogb/graphproppred/mol_encoder.py）的作用，就像是把「一串類別代碼」轉換成「稠密向量表示 (dense embedding)」，這與 NLP 中把「詞彙 ID」轉成「word embedding」的概念完全類似：

• 每個原子特徵維度（如原子序、手性、電荷數）各自對應一個獨立的 nn.Embedding 查找表。
• 多個特徵維度的 embedding 向量相加合併成單一原子表示（而非拼接 concat），這是一種簡化融合方式，讓輸出維度固定，方便後續 GNN 層直接使用。

5. 使用方式與程式碼範例 (Usage & Code Examples)

5.1 基礎用法：節點分類任務（PyTorch Geometric）

以下範例展示 ogbn-arxiv 資料集的完整端到端流程，從載入資料到訓練一個簡易 GCN (Graph Convolutional Network) 並用官方 Evaluator 評估。

 1"""
 2基礎範例：ogbn-arxiv 節點分類
 3需求：pip install ogb torch torch_geometric
 4"""
 5import torch
 6import torch.nn.functional as F
 7from torch_geometric.nn import GCNConv
 8from ogb.nodeproppred import PygNodePropPredDataset, Evaluator
 9
10# 1. 載入資料集（自動下載至 ./dataset/）
11dataset = PygNodePropPredDataset(name='ogbn-arxiv', root='dataset/')
12data = dataset[0]  # 單一大圖：包含 data.x, data.edge_index, data.y
13
14# 2. 取得官方標準切分（依論文發表年份切分，非隨機）
15split_idx = dataset.get_idx_split()
16train_idx, valid_idx, test_idx = split_idx['train'], split_idx['valid'], split_idx['test']
17
18# 3. 定義一個兩層 GCN 模型
19class GCN(torch.nn.Module):
20    def __init__(self, in_channels, hidden_channels, out_channels):
21        super().__init__()
22        self.conv1 = GCNConv(in_channels, hidden_channels)
23        self.conv2 = GCNConv(hidden_channels, out_channels)
24
25    def forward(self, x, edge_index):
26        x = self.conv1(x, edge_index).relu()
27        x = F.dropout(x, p=0.5, training=self.training)
28        x = self.conv2(x, edge_index)
29        return x.log_softmax(dim=-1)
30
31device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
32model = GCN(dataset.num_features, 256, dataset.num_classes).to(device)
33data = data.to(device)
34optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
35
36# 4. 訓練迴圈
37model.train()
38for epoch in range(1, 101):
39    optimizer.zero_grad()
40    out = model(data.x, data.edge_index)
41    loss = F.nll_loss(out[train_idx], data.y[train_idx].squeeze(1))
42    loss.backward()
43    optimizer.step()
44    if epoch % 20 == 0:
45        print(f'Epoch {epoch:03d}, Loss: {loss.item():.4f}')
46
47# 5. 用官方 Evaluator 評估（非自行計算 Accuracy）
48evaluator = Evaluator(name='ogbn-arxiv')
49model.eval()
50with torch.no_grad():
51    out = model(data.x, data.edge_index)
52    y_pred = out.argmax(dim=-1, keepdim=True)
53
54train_acc = evaluator.eval({
55    'y_true': data.y[train_idx],
56    'y_pred': y_pred[train_idx],
57})['acc']
58test_acc = evaluator.eval({
59    'y_true': data.y[test_idx],
60    'y_pred': y_pred[test_idx],
61})['acc']
62
63print(f'Train Acc: {train_acc:.4f}, Test Acc: {test_acc:.4f}')

5.2 進階用法：圖屬性預測（分子性質預測 + AtomEncoder）

此範例展示如何使用 ogbg-molhiv（HIV 抑制活性分類）搭配 AtomEncoder/BondEncoder 處理分子節點與邊特徵，並用 mini-batch DataLoader 訓練圖層級任務。

 1"""
 2進階範例：ogbg-molhiv 圖層級分類 + mol_encoder
 3"""
 4import torch
 5import torch.nn.functional as F
 6from torch_geometric.loader import DataLoader
 7from torch_geometric.nn import global_mean_pool, GINConv
 8from ogb.graphproppred import PygGraphPropPredDataset, Evaluator
 9from ogb.graphproppred.mol_encoder import AtomEncoder, BondEncoder
10
11dataset = PygGraphPropPredDataset(name='ogbg-molhiv', root='dataset/')
12split_idx = dataset.get_idx_split()
13
14train_loader = DataLoader(dataset[split_idx['train']], batch_size=32, shuffle=True)
15valid_loader = DataLoader(dataset[split_idx['valid']], batch_size=32, shuffle=False)
16test_loader  = DataLoader(dataset[split_idx['test']],  batch_size=32, shuffle=False)
17
18class GINGraphClassifier(torch.nn.Module):
19    def __init__(self, emb_dim=100, num_tasks=1):
20        super().__init__()
21        self.atom_encoder = AtomEncoder(emb_dim)   # 類別特徵 → 稠密向量
22        self.bond_encoder = BondEncoder(emb_dim)
23        mlp = torch.nn.Sequential(
24            torch.nn.Linear(emb_dim, emb_dim),
25            torch.nn.ReLU(),
26            torch.nn.Linear(emb_dim, emb_dim),
27        )
28        self.conv = GINConv(mlp)
29        self.out_lin = torch.nn.Linear(emb_dim, num_tasks)
30
31    def forward(self, batch):
32        x = self.atom_encoder(batch.x)          # 原子特徵嵌入
33        x = self.conv(x, batch.edge_index)      # 圖卷積（此簡例未使用 bond_encoder 輸出）
34        x = global_mean_pool(x, batch.batch)     # 節點層級 → 整張圖表示
35        return self.out_lin(x)
36
37device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
38model = GINGraphClassifier(num_tasks=dataset.num_tasks).to(device)
39optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
40evaluator = Evaluator(name='ogbg-molhiv')
41
42def run_epoch(loader, train=True):
43    model.train() if train else model.eval()
44    y_true_all, y_pred_all = [], []
45    for batch in loader:
46        batch = batch.to(device)
47        if train:
48            optimizer.zero_grad()
49        pred = model(batch)
50        is_labeled = batch.y == batch.y  # 過濾遺漏標籤（NaN mask）
51        loss = F.binary_cross_entropy_with_logits(
52            pred[is_labeled].float(), batch.y[is_labeled].float()
53        )
54        if train:
55            loss.backward()
56            optimizer.step()
57        y_true_all.append(batch.y.detach().cpu())
58        y_pred_all.append(pred.detach().cpu())
59    y_true = torch.cat(y_true_all, dim=0)
60    y_pred = torch.cat(y_pred_all, dim=0)
61    return evaluator.eval({'y_true': y_true, 'y_pred': y_pred})
62
63for epoch in range(1, 11):
64    run_epoch(train_loader, train=True)
65    valid_result = run_epoch(valid_loader, train=False)
66    print(f'Epoch {epoch}: Valid ROC-AUC = {valid_result["rocauc"]:.4f}')
67
68test_result = run_epoch(test_loader, train=False)
69print(f'Final Test ROC-AUC: {test_result["rocauc"]:.4f}')

5.3 實際應用場景：連結預測（推薦系統情境）

ogbl-collab 模擬「學者合作推薦」情境，展示連結預測任務的資料結構與負採樣 (negative sampling) 概念：

 1"""
 2連結預測範例：ogbl-collab 學者合作預測
 3"""
 4from ogb.linkproppred import PygLinkPropPredDataset, Evaluator
 5import torch
 6
 7dataset = PygLinkPropPredDataset(name='ogbl-collab', root='dataset/')
 8data = dataset[0]
 9split_edge = dataset.get_edge_split()
10
11train_edge = split_edge['train']['edge']      # 已知的正樣本合作關係
12valid_edge = split_edge['valid']['edge']       # 驗證用正樣本
13valid_edge_neg = split_edge['valid']['edge_neg']  # 官方提供的負樣本（未合作的學者對）
14
15print(f'訓練集正樣本邊數: {train_edge.shape[0]}')
16print(f'驗證集正/負樣本: {valid_edge.shape[0]} / {valid_edge_neg.shape[0]}')
17
18# 官方 Evaluator 對連結預測任務常用 Hits@K 指標
19evaluator = Evaluator(name='ogbl-collab')
20print('本資料集評估設定:', evaluator.expected_input_format)

這裡的重點在於：負樣本並非隨機生成，而是 OGB 官方預先切分好、固定不變的負樣本集合。這確保所有論文使用「完全相同」的負樣本進行評估，避免因負採樣策略不同而造成分數不可比較——這正是 OGB「標準化評估協定」設計哲學的具體展現。

5.4 使用 DGL 框架的等效範例

OGB 的框架中立設計意味著同一個資料集，可以用幾乎相同的介面透過 DGL 讀取，只是資料型別從 PyG 的 Data 換成 DGL 的 DGLGraph：

 1"""
 2DGL 版本：ogbn-arxiv 節點分類資料載入
 3"""
 4import torch
 5import dgl
 6from ogb.nodeproppred import DglNodePropPredDataset, Evaluator
 7
 8dataset = DglNodePropPredDataset(name='ogbn-arxiv', root='dataset/')
 9graph, label = dataset[0]        # graph 為 DGLGraph，label 為節點標籤張量
10split_idx = dataset.get_idx_split()
11train_idx, valid_idx, test_idx = split_idx['train'], split_idx['valid'], split_idx['test']
12
13# DGL 圖預設是有向邊，節點分類任務常需加上反向邊使訊息可雙向傳遞
14graph = dgl.add_reverse_edges(graph)
15graph = dgl.add_self_loop(graph)  # 常見技巧：加自環讓節點也能「看到自己」
16
17print(f'節點數: {graph.num_nodes()}, 邊數: {graph.num_edges()}')
18print(f'節點特徵維度: {graph.ndata["feat"].shape}')
19
20evaluator = Evaluator(name='ogbn-arxiv')
21# 後續训练迴圈與 PyG 版本邏輯相同：模型輸出 logits → argmax → evaluator.eval(...)

可以看到，無論底層使用 PyG 或 DGL，get_idx_split() 與 Evaluator 的介面完全一致——這正是第 2.3 節提到的「框架中立 + 框架特化並存」設計哲學在實務上的體現：研究者可以自由切換深度學習框架，而不需要重新學習資料處理與評估的介面。

5.5 自訂資料集：使用 ogb.io.save_dataset

若團隊需要把「自己的圖資料」包裝成 OGB 相容格式（例如內部的分子資料庫或生物網路），可以使用 ogb.io 提供的工具函式，讓自建資料集也能享有 OGB 標準化的 dataloader 與 split 介面：

 1"""
 2自訂資料集範例：把內部分子資料包裝成 OGB 相容格式（概念示意）
 3"""
 4import numpy as np
 5from ogb.io import DatasetSaver
 6
 7# 假設已有：graph_list（每個元素是一張分子圖的 dict：edge_index/node_feat/edge_feat）
 8#           labels（每張圖對應的性質標籤，如是否有毒性）
 9saver = DatasetSaver(
10    dataset_name='ogbg-my-internal-toxicity',
11    is_hetero=False,
12    version=1,
13)
14
15saver.save_graph_list(graph_list)
16saver.save_target_labels(np.array(labels))
17
18# 定義官方標準 train/valid/test split（建議依化學骨架切分，避免資訊洩漏）
19split_idx = {'train': train_indices, 'valid': valid_indices, 'test': test_indices}
20saver.save_split(split_idx, split_name='scaffold')
21
22saver.save_task_info(
23    task_type='binary classification',
24    eval_metric='rocauc',
25    num_classes=2,
26)
27saver.zip()
28saver.cleanup()

包裝完成後，內部團隊即可用與官方資料集完全相同的 PygGraphPropPredDataset(name='ogbg-my-internal-toxicity') 呼叫方式使用，享有一致的 API 與評估流程——這對需要在內部建立「私有基準測試集」的藥物開發團隊尤其實用。

6. 進階應用場景 (Advanced Use Cases)

6.1 真實世界應用案例

• 藥物發現 (drug discovery)：ogbg-molhiv、ogbg-molpcba 這類分子性質預測資料集，直接對應真實製藥流程中的虛擬篩選 (virtual screening)——在合成化合物之前，先用 GNN 預測其生物活性或毒性，大幅降低濕實驗室 (wet-lab) 成本。
• 學術推薦系統：ogbl-collab（合作預測）、ogbl-citation2（引用預測）可直接遷移到論文推薦、合作者推薦等產品情境。
• 知識圖譜補全 (knowledge graph completion)：ogbl-biokg、ogbl-wikikg2 用於補全生物醫學或百科知識圖譜中缺失的三元組關係，是知識圖譜嵌入 (knowledge graph embedding) 研究的標準測試場。
• 超大規模學術圖網路：ogbn-papers100M（1.11 億節點、16 億邊）用於測試 GNN 在工業級規模下的可擴展性，是許多分散式 GNN 訓練框架（如 DistDGL、PyG 的 GraphSAGE NeighborLoader）的標準壓力測試資料集。

6.2 與其他 snap-stanford 工具的整合

flowchart LR
    ogb["OGB
資料 + 評估標準"] --> pyg["PyTorch Geometric
模型訓練"]
    ogb --> dgl["DGL
模型訓練"]
    ogb --> lsc["OGB-LSC
KDD Cup 競賽"]
    pyg --> leaderboard["OGB 官方 Leaderboard
ogbn/ogbl/ogbg 排行榜"]
    dgl --> leaderboard
    leaderboard --> paper["發表論文
可信任的跨方法比較"]

OGB-LSC (Large-Scale Challenge) 是 OGB 的超大規模衍生分支，資料集規模達到十億級（如 WikiKG90M 有 9000 萬實體），主要用於 KDD Cup 競賽，推動業界對分散式圖計算、圖切分 (graph partitioning)、記憶體高效訓練等工程問題的研究——這也是為什麼 ogb/lsc/ 目錄獨立於三大任務子套件之外。

6.3 效能調校與最佳實踐

1. 大圖用子圖抽樣，不要整圖塞進顯存：ogbn-products、ogbn-papers100M 等大型資料集應搭配 PyG 的 NeighborLoader 或 DGL 的 NeighborSampler，做 mini-batch 式的鄰居抽樣訓練，而非一次性把整張圖塞進 GPU。
2. 善用官方 Evaluator 而非自行實作指標：即使你自己寫的 Accuracy/ROC-AUC 邏輯理論上等價，仍建議用官方 Evaluator，避免因為多任務平均方式、NaN 處理等細節不同而導致與 Leaderboard 分數不可比。
3. 注意資料集切分背後的 distribution shift 語意：調參與模型選擇時，應在官方 valid 集上做 early stopping，而非直接看 test 分數決定超參數，否則會產生 test set 洩漏 (leakage) 的問題，這在結構化切分（非隨機切分）資料集上尤其容易被忽略。
4. 分子任務善用 mol_encoder，不要自建原子/鍵嵌入表：AtomEncoder/BondEncoder 已針對 OGB 分子特徵編碼定義做好維度對齊，重造輪子容易在特徵維度定義上出錯。
5. 多任務資料集要正確處理 NaN 標籤：ogbg-molpcba 這類多任務分子資料集，許多分子在某些任務上缺乏標籤（以 NaN 表示），訓練時務必用 is_labeled = y == y（NaN 不等於自身的技巧）過濾遺漏值再計算 loss，否則反傳播會直接輸出 NaN 梯度，整個訓練崩潰。
6. 超大規模任務優先評估硬體可行性再選模型：面對 ogbn-papers100M 這類億級節點資料集，應先確認可用記憶體/顯存與是否有分散式訓練框架（如 DistDGL、PyG 的 ClusterGCN/GraphSAINT 抽樣策略），再決定模型架構複雜度，避免選了記憶體需求過高的模型架構後才發現無法訓練。

6.4 效能對照：官方 Leaderboard 呈現的方法演進速覽

OGB 官方 Leaderboard（https://ogb.stanford.edu/docs/leader_overview/）持續收錄各方法在標準測試集上的表現，形成了可觀察「方法論演進」的活歷史紀錄。以 ogbn-arxiv（節點分類）為例，可以觀察到隨時間推進的典型技術演進路徑：

flowchart LR
    A["基線方法
MLP（不使用圖結構）"] --> B["GCN / GraphSAGE
（基礎訊息傳遞 GNN）"]
    B --> C["加入正規化技巧
（Label Propagation、
C&S Correct-and-Smooth）"]
    C --> D["更深層架構 +
殘差連接（如 RevGNN）"]
    D --> E["結合預訓練節點嵌入
（如語言模型嵌入論文標題摘要）"]
    E --> F["當前 SOTA：
混合圖結構+文本語意特徵的方法"]

這種演進脈絡對研究者的實務意義在於：在為新研究選擇 baseline 時，應優先參考 Leaderboard 上「有公開程式碼」的方法，而非憑印象假設某方法仍是當前最強——OGB Leaderboard 的存在正是為了消除這種「記憶過時 SOTA」的資訊落差問題，這也呼應了 AIKT 系統「查證優先於記憶」的核心原則（見 CLAUDE.md §8 查證與文件使用規範）。

7. 與 AIKT 的關聯分析 (AIKT Integration Analysis)

7.1 OGB 可作為 AIKT 的資料來源或分析工具嗎？

嚴格來說，OGB 本身是圖機器學習領域的基準資料集套件，與 AIKT（一個 CLI 知識管理/研究自動化系統）的應用領域（知識擷取、文件生成、教學編排)並不直接重疊——OGB 不產出「知識文件」，而是產出「訓練用的圖資料 + 評估分數」。因此 OGB 對 AIKT 而言，價值不在於被 AIKT 當作資料來源，而在於被 AIKT 當作「教學/研究對象」來處理：

• 作為研究對象：透過 L2 (ai-gh-save) 收錄 OGB repo 本身（如本教學所做的事），或透過 L9 (paper-search) 收錄 OGB 論文 (arXiv:2005.00687、arXiv:2103.09430)，建立起「GNN benchmark 領域知識」的知識庫節點。
• 作為程式碼分析對象：若使用者的研究專案內部呼叫了 OGB API（例如某個 GNN 研究 repo 用 ogb.nodeproppred），L6 (gitnexus) 可以建立該研究 repo 的符號圖，分析程式碼如何呼叫 OGB 的 Dataset/Evaluator，輔助程式碼理解與 impact analysis（影響範圍分析）。

7.2 AIKT 哪些 Layer 可以包裝或編排此專案

flowchart TB
    subgraph L2["L2 ai-gh-save"]
        a1["收錄 OGB repo README/架構
→ inbox/ md"]
    end

    subgraph L9["L9 paper-search"]
        a2["收錄 OGB / OGB-LSC 論文
NeurIPS 2020 + arXiv 2103.09430"]
    end

    subgraph L12["L12 gh-tutorial-qd"]
        a3["生成本教學文件
（正是目前這份輸出）"]
    end

    subgraph L18["L18 research-pipeline-v2"]
        a4["若研究主題涉及 GNN 藥物發現
可將 OGB 分子資料集
納入多輪研究迭代的資料基準"]
    end

    subgraph L19["L19 tu-plan-generator"]
        a5["藥物開發計畫若涉及
GNN-based 化合物性質預測
可引用 ogbg-molhiv/molpcba
作為模型驗證基準"]
    end

    subgraph L4["L4 graphify"]
        a6["若使用者專案內大量呼叫 OGB API
graphify 可建立
「研究 repo ↔ OGB 依賴」知識圖譜"]
    end

    a1 --> a3
    a2 --> a3
    a3 --> know["AIKT 知識庫
docs/ + inbox/"]
    a4 --> know
    a5 --> know
    a6 --> know

具體場景：

• L2 + L9 組合：先用 ai-gh-save 收錄 OGB repo 架構性資訊，再用 paper-search 收錄其論文全文與後續引用它的方法論文，建立「基準資料集 + 方法演進」的知識脈絡。
• L12 gh-tutorial-qd：正是本次任務的執行 Layer——把 OGB 這類研究基礎設施 repo，轉換成繁中雙語教學文件，降低團隊成員（尤其非 ML 背景的生資分析師）理解圖機器學習基準測試生態的門檻。
• L19 tu-plan-generator：若 Apotek 的藥物開發專案未來涉及使用 GNN 做 ADMET (Absorption, Distribution, Metabolism, Excretion, Toxicity; 吸收/分布/代謝/排除/毒性) 性質預測，ogbg-molhiv/ogbg-molpcba 可作為模型選型時的公開基準參照——用來驗證「這個 GNN 架構在公開資料集上排名如何」，作為內部模型可信度的佐證資料。

7.3 潛在整合場景與價值

7.4 小結

OGB 與 AIKT 的關係本質是「研究對象 vs 知識管理系統」，而非「資料源 vs 消費端」。AIKT 適合扮演「把 OGB 這類研究基礎設施轉譯為團隊可消化知識」的角色，尤其在生資/藥物開發團隊需要評估「是否該用 GNN 做某項預測任務」時，AIKT 可以快速產出決策支援文件。

8. 優缺點與生態系定位 (Strengths, Limitations & Ecosystem Position)

8.1 核心優勢與創新點

1. 標準化評估協定的公信力：OGB 的 Leaderboard 機制要求投稿者提供程式碼與可重現的實驗設定，這種「可驗證性」是 OGB 能在學術社群建立公信力的關鍵。
2. 結構化切分制度：刻意設計 distribution shift（依時間、依 scaffold 切分)，避免傳統隨機切分造成的樂觀偏差 (optimistic bias)，逼迫方法論真正解決泛化問題而非過擬合基準。
3. 框架中立的資料層設計：核心 Dataset 類別不綁定特定深度學習框架，_pyg/_dgl 包裝層讓使用者能自由選型，降低採用門檻。
4. 跨規模、跨領域的資料集光譜：從單 GPU 可訓練的小型資料集，到需要分散式運算的十億級資料集（OGB-LSC），完整覆蓋了 GNN 研究從入門到工業級可擴展性驗證的需求。
5. 與主流框架（PyG、DGL）深度整合：3-4 行程式碼即可拿到可訓練資料，大幅降低研究者的資料工程負擔，讓研究精力集中在模型設計本身。

8.2 目前限制與改進空間

1. 資料集覆蓋領域仍以化學/引用網路/知識圖譜為主：對於某些新興領域（例如時序動態圖 (temporal dynamic graph)、異質圖神經網路的複雜場景）覆蓋相對有限，社群仍需依賴其他基準（如 Temporal Graph Benchmark）補充。
2. 超大規模資料集的硬體門檻高：OGB-LSC 系列資料集（MAG240M、WikiKG90M）動輒需要數百 GB 記憶體或多卡叢集，對學術界中小型實驗室或個人研究者不友善，形成一定程度的「資源不平等」問題。
3. 版本相容性維護負擔：README 明確警告需要更新到 1.3.6 版本，暗示過去版本間曾有資料格式或 API 的破壞性變更，對於長期維護的研究專案而言，需要額外注意版本鎖定 (pinning)。
4. Evaluator 目前僅支援固定的指標集合：eval_metric 由 master.csv 固定為 rocauc/acc/mrr 等既定字串，若研究者需要自訂或混合指標，仍需繞出 OGB Evaluator 自行實作，擴充彈性有限。

8.3 與同領域工具的比較

8.4 適用場景建議

• 適合使用 OGB 的情境：需要對新提出的 GNN 方法做嚴謹、可信、可與已發表論文比較的效能驗證；需要跨規模（小型驗證想法、大型驗證可擴展性）测試同一方法；藥物發現/分子性質預測相關研究需要公開基準佐證模型可信度。
• 不建議單獨依賴 OGB 的情境：若研究聚焦於時序動態圖、圖生成 (graph generation)、或高度領域特化的圖結構（如特定產業的知識圖譜），應搭配其他專門基準或自建資料集，OGB 僅作為輔助驗證之一。
• 對 Apotek/生資團隊的建議：若未來 pre-IND 或藥物研發流程中考慮導入 GNN 做分子性質/毒性預測，建議先在 ogbg-molhiv/ogbg-molpcba 等公開基準上驗證候選模型架構的相對表現，再投入內部真實資料的訓練與驗證，降低盲目選型的風險。

附錄：資料集命名慣例速查

OGB 資料集名稱遵循 ogb{n|l|g}-{領域縮寫} 的命名規則：

完整資料集列表與最新統計數據，建議查閱 OGB 官方文件 https://ogb.stanford.edu/docs/dataset_overview/ 以及套件內對應子模組的 master.csv（該檔案是版本內建的權威來源，會隨套件版本更新)。

附錄：常用術語雙語對照表

教學文件產出資訊：本文件由 AIKT L12 (gh-tutorial-qd) 依據 OGB repository 官方 README、原始碼結構（ogb/nodeproppred、ogb/linkproppred、ogb/graphproppred、ogb/io、ogb/utils、ogb/lsc）與核心模組原始碼（evaluate.py、mol_encoder.py）分析生成，程式碼範例基於官方 API 設計撰寫，實際執行前請對照當前套件版本（pip show ogb 或 python -c "import ogb; print(ogb.__version__)"）核實 API 是否有變動。