doc(ai): sync hugegraph-ml with main - #482
Conversation
Rebuild the Implemented Models table from src/hugegraph_ml/models/ so it lists every module, its entry class and its paper, including GIN and MLPClassifier. Correct the BGNN row: the bundled example runs regression over tabular node features, not fraud detection. Add sections for the HugeGraph2DGL conversion methods, the dataset importers and the datasets each accepts, the task classes and their entry points, and the runnable example scripts. Record the ML dependency pins from the root constraint-dependencies block, and add troubleshooting entries for the missing node attributes error, the unsupported dataset error, the bgrl_example MLP_Predictor import mismatch and the missing CARE-GNN dataset importer.
imbajin
left a comment
imbajin
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: The page adds useful coverage but currently contains several user-facing contracts that contradict the pinned HugeGraph-AI implementation, including server-version, task-device, attribute, importer, and destructive-clear behavior. Evidence: exact-head source cross-checks against apache/hugegraph-ai@5ee21cc and the HugeGraph GraphsAPI; exact-head site CI is green.
| - HugeGraph Server 1.0 or later; 1.5 or later is recommended | ||
| - `uv` 0.7 or later | ||
|
|
||
| All server access goes through `hugegraph-python-client` (the `pyhugegraph` package) from the same repository. `HugeGraph2DGL` pulls vertices and edges over the Gremlin endpoint with `g.V().hasLabel(...)` and `g.E().hasLabel(...)`, and the dataset importers write through the schema and batch vertex/edge APIs in batches of 500. |
There was a problem hiding this comment.
| | `numpy` | `~=1.24.4` | | ||
| | `pandas` | `~=2.2.3` | | ||
|
|
||
| Those pins install CPU builds. Every task accepts a `gpu` argument that defaults to `-1`, meaning CPU; pass a device index only after installing CUDA builds of `torch` and `dgl` yourself. |
There was a problem hiding this comment.
| | `convert_graph_ogb(vertex_label, edge_label, split_label)` | `(dgl.DGLGraph, split_edge)` | Used by SEAL | | ||
| | `convert_hetero_graph_bgnn(vertex_labels, edge_labels, feat_key="feat", label_key="class", cat_key="cat_features", mask_keys=None)` | DGL heterograph | Used by BGNN | | ||
|
|
||
| Node features land in `ndata["feat"]`, labels in `ndata["label"]` and each mask in `ndata[<mask key>]`. `NodeEmbed` requires `feat` only; `NodeClassify`, `NodeClassifyWithEdge` and `NodeClassifyWithSample` require `feat`, `label`, `train_mask`, `val_mask` and `test_mask` and raise `ValueError` when one is missing. |
There was a problem hiding this comment.
| | `import_graph_from_ogb` | `ogbl-collab`, matched without upper-casing | `<NAME>_vertex`, `<NAME>_edge` | | ||
| | `import_split_edge_from_ogb` | `ogbl-collab`, matched without upper-casing | `<NAME>_split_edge` | | ||
|
|
||
| Any other name raises `ValueError("dataset not supported")`. `import_split_edge_from_ogb` additionally requires the `idx_to_vertex_id` mapping and a `max_nodes` cap returned by the vertex import. |
There was a problem hiding this comment.
|
|
||
| Any other name raises `ValueError("dataset not supported")`. `import_split_edge_from_ogb` additionally requires the `idx_to_vertex_id` mapping and a `max_nodes` cap returned by the vertex import. | ||
|
|
||
| `clear_all_data()` drops every vertex and edge in the target graph. The test fixture calls it, loads `CORA`, `MUTAG` and `ACM`, and calls it again on teardown. |
There was a problem hiding this comment.
| | `NodeClassifyWithEdge` | `node_classify_with_edge.py` | Same shape, for models that also read `edata["feat"]` | | ||
| | `NodeClassifyWithSample` | `node_classify_with_sample.py` | Cluster-GCN style training on `ClusterGCNSampler` partitions; runs on CPU and takes no `gpu` argument | | ||
| | `GraphClassify` | `graph_classify.py` | `train(batch_size=20, lr, weight_decay, n_epochs, patience, early_stopping_monitor, clip=2.0, gpu)` over a `HugeGraphDataset`, split 70/20/10 | | ||
| | `DetectorCaregnn` | `fraud_detector_caregnn.py` | CARE-GNN training; `evaluate()` reports recall and ROC AUC and reads `ndata["feature"]` rather than `ndata["feat"]` | |
There was a problem hiding this comment.
| ``` | ||
|
|
||
| The source also includes `GIN` for graph classification and `MLPClassifier` for downstream classification. The model count changes between versions; use `src/hugegraph_ml/models/` as the authoritative list. | ||
| Each script also exposes a function of the same name, so it can be imported and called with a smaller epoch count. |
There was a problem hiding this comment.
🧹 bgnn_example is the only listed example function without an epoch parameter—it hard-codes num_epochs=100 (apache/hugegraph-ai@5ee21cc, hugegraph-ml/src/hugegraph_ml/examples/bgnn_example.py:30,49-58). Calling each example with a smaller epoch count as this sentence suggests raises TypeError; qualify the sentence or update that example's signature.
2 participants
Syncs the HugeGraph-ML quick start (en and cn) with
apache/hugegraph-ai@mainat version 1.7.0. Every change below traces to a file onmain.hugegraph-ml/src/hugegraph_ml/tasks/link_prediction_seal.py:32,.../fraud_detector_caregnn.py:27pyhugegraph; importers use schema and batch APIs in batches of 500hugegraph-ml/src/hugegraph_ml/data/hugegraph2dgl.py:41,54,.../utils/dgl2hugegraph_utils.py:45torch==2.2.0,dgl~=2.1.0,ogb~=1.3.6,torchdata~=0.7.0,catboost~=1.2.3,category-encoders~=2.6.3,numpy~=1.24.4,pandas~=2.2.3pyproject.toml:109,110,136-140,143gpudefaulting to-1hugegraph-ml/src/hugegraph_ml/tasks/node_embed.py:49,.../node_classify.py:61hugegraph-ml/src/hugegraph_ml/models/agnn.py:33,appnp.py:32,arma.py:122,bgnn.py:60,bgrl.py:93,care_gnn.py:127,cluster_gcn.py:34,correct_and_smooth.py:160,dagnn.py:100,deepergcn.py:38,dgi.py:35,diffpool.py:36,gatne.py:66,grace.py:36,grand.py:35,jknet.py:33,pgnn.py:79,seal.py:175task="regression"hugegraph-ml/src/hugegraph_ml/examples/bgnn_example.py:40hugegraph-ml/src/hugegraph_ml/models/gin_global_pool.py:26,.../mlp.py:22models/__init__.pyre-exports nothing; import from the module filehugegraph-ml/src/hugegraph_ml/models/__init__.py:1sum(default),mean,max,global_attention,set2sethugegraph-ml/src/hugegraph_ml/models/gin_global_pool.py:41convert_graphappeared, inside an examplehugegraph-ml/src/hugegraph_ml/data/hugegraph2dgl.py:33,44,60,114,148,158,177,185ndatakeys each task requiresNodeEmbedneedsfeat; the three node classification tasks needfeat,label,train_mask,val_mask,test_maskhugegraph-ml/src/hugegraph_ml/tasks/node_embed.py:36,.../node_classify.py:38import_graph_from_dgl("cora")appearedhugegraph-ml/src/hugegraph_ml/utils/dgl2hugegraph_utils.py:59,130,211,295,366,424,513,613,749clear_all_dataand the test fixture flowCORA,MUTAG,ACM, then calls it againhugegraph-ml/src/hugegraph_ml/utils/dgl2hugegraph_utils.py:48,hugegraph-ml/src/tests/conftest.py:29AMAZONGATNEandAVAZUare not auto-downloadedhugegraph-ml/src/hugegraph_ml/utils/dgl2hugegraph_utils.py:303,757NodeEmbedandNodeClassifyappeared in examplesGraphClassify70/20/10 split,NodeClassifyWithSamplebeing CPU only,LinkPredictionSealcallingdata_prepare()in its constructor, andDetectorCaregnnreadingndata["feature"]hugegraph-ml/src/hugegraph_ml/tasks/node_embed.py:42,node_classify.py:54,node_classify_with_edge.py:58,node_classify_with_sample.py:65,graph_classify.py:59,73,fraud_detector_caregnn.py:81,hetero_sample_embed_gatne.py:40,link_prediction_pgnn.py:36,link_prediction_seal.py:43EarlyStoppingbehaviourpatiencedefaults tofloat("inf"), monitorslossoraccuracy, restores best weightshugegraph-ml/src/hugegraph_ml/utils/early_stopping.py:42hugegraph-ml/srcand a 19-row table of script, model, task and graph labels readhugegraph-ml/src/hugegraph_ml/examples/agnn_example.py:23,bgnn_example.py:32,care_gnn_example.py:27,cluster_gcn_example.py:25,deepergcn_example.py:25,diffpool_example.py:25,gatne_example.py:26,gin_example.py:25,pgnn_example.py:26,seal_example.py:28evaluate()returnshugegraph-ml/src/hugegraph_ml/tasks/node_classify.py:44,hugegraph-ml/README.md:137import_graph_from_dgl("cora")gave no hint why the labels areCORA_*hugegraph-ml/src/hugegraph_ml/utils/dgl2hugegraph_utils.py:67NodeClassifymasks each elementhugegraph-ml/src/hugegraph_ml/tasks/node_classify.py:87ValueError: Graph is missing required node attribute ...with the fixhugegraph-ml/src/hugegraph_ml/tasks/node_classify.py:41ValueError: dataset not supported, and thatimport_graph_from_ogbmatchesogbl-collabwithout upper-casinghugegraph-ml/src/hugegraph_ml/utils/dgl2hugegraph_utils.py:75,521bgrl_example.pyfails on importMLP_Predictor, but the class isMLPPredictorhugegraph-ml/src/hugegraph_ml/examples/bgrl_example.py:19,.../models/bgrl.py:43care_gnn_example.pyhas no matching importerAMAZON_user_vand threeAMAZON_net_*_elabels that no bundled importer createshugegraph-ml/src/hugegraph_ml/examples/care_gnn_example.py:28,.../utils/dgl2hugegraph_utils.py:306Upstream defects found while reading the code
Not fixed here, they belong in
apache/hugegraph-ai:hugegraph-ml/README.md:35says "python 3.9+", buthugegraph-ml/pyproject.toml:32setsrequires-python = ">=3.10".README.md:105,107advertises DeepWalk, Node2Vec, GAT, GCN and GraphSAGE.models/contains no DeepWalk, Node2Vec or GAT; GraphSAGE exists only asSAGEinsidecluster_gcn.py:34, and GCN only as encoder classes insidebgrl.py:71,grace.py:196andseal.py:51.hugegraph-ml/src/hugegraph_ml/examples/bgrl_example.py:19importsMLP_Predictor, which does not exist;models/bgrl.py:43definesMLPPredictor.src/tests/test_examples/test_examples.py:24imports this example, so the whole example test module fails to collect.