先聊个有意思的事。你在技术社区里看到“caveman”这个词，别急着把它理解成“山顶洞人”“原始人”。至少在复杂网络和图计算这个圈子里，它指的是一个特别经典的图结构模型——caveman graph，穴居人图。我第一次接触它是在做社交网络社区发现算法评估的时候，当时需要一个“真实社区划分完全已知”的测试图，用来验证Louvain算法对社区边界的识别能力。真实数据集要么没标签，要么有隐私问题，手动标注又太费劲，后来我才发现，caveman图正是这种场景下的标准答案：结构简单、语义清晰、可精确控制，还能直接导出带标签的图数据。这篇文章的思路是，先讲清楚caveman图的数学定义和设计逻辑，再给出基于NetworkX的完整生成代码和参数调优方法，然后带你把社区发现和GNN数据构造两个典型场景跑通，最后把我踩过的坑一次性抖出来。不管你是做图算法研究、复杂网络分析，还是想给图神经网络造一批有强社区结构的合成数据，这篇应该都能帮上忙。

1. 理解caveman图的原始设计：一个小部落自成一个世界

1.1 为什么叫“穴居人”图

把名字拆开看就很好理解了。想象一下史前时代，一个部落的人住在同一个洞穴里，部落内部天天打照面、一起狩猎，互相之间熟得不能再熟；但不同洞穴之间呢，可能隔着几座山、几条河，一年也碰不上几回面，部落与部落之间的联系少得可怜。这种“内部紧密、外部稀疏”的结构，恰恰是现实中社交网络、协作网络、蛋白质网络里最常见的社区形态。caveman图就是把这种部落关系抽象成了图：每个洞穴是一个社区，洞穴里的成员是节点，成员之间的熟人关系是边；而洞穴之间仅保留极少数的“串门通道”，用来维持整个网络的连通性。

名词的趣味性只是它受欢迎的原因之一。更核心的是，这可能是所有合成图里社区结构最干净、最容易量化分析的一种。社区发现算法好不好，总得有个对照基准；对比基准需要“标准答案”，而caveman图的标准答案就是它构造时写死的——每一个洞穴就是一个社区，没有任何歧义。

1.2 三句话定义caveman图

严谨起见，给出构造式定义：

1. 一共 n 个大组（洞穴），每组有 k 个节点，总节点数 N = n × k。
2. 组内节点两两相连，也就是说，每一组都构成一个大小为 k 的完全图，数学上也叫 k-团。
3. 组与组之间只保留极少量的桥接边，把这些团串联成一个环。

举个例子，n=4、k=5，那就是4个洞穴，每个洞穴5个人，洞穴内部5个人互相全认识；然后第1个洞穴的某个代表和第2个洞穴的某个代表之间有1条边，第2连第3，第3连第4，第4再连回第1，整体像一串被串起来的珠子。

在NetworkX里，这个过程只需要一行代码：

import networkx as nx G = nx.caveman_graph(n=4, k=5) print("节点数:", G.number_of_nodes()) print("边数:", G.number_of_edges())

这里 n=4、k=5，所以节点数是20。如果按标准构造，每组内部是 C(5,2)=10 条边，4组共40条，组间桥接边4条，总边数44。程序输出会和这个完全对得上。

1.3 caveman图在复杂网络模型坐标系里的位置

新手容易把各种合成图模型搞混，我直接给一张对比表，看的时候可以按“社区结构是否可控”来理解。

caveman图在“社区结构的清晰度”上几乎是满分，代价就是度分布过于整齐，和真实网络的幂律特征相差较远。所以它最适合当正基准：如果算法在这个图上都找不出社区，那大概率是算法实现有问题；但如果算法在LFR图上效果好，那才是真正接近实战。

2. 从零生成caveman图：关键参数与实现细节

2.1 快速搭环境：只用两个库

做这件事不需要重型依赖，Python 3.8以上，装上NetworkX和Matplotlib就够。NetworkX负责图结构，Matplotlib负责可视化。装起来也简单：

pip install networkx matplotlib

如果你后面要做社区发现指标评估，建议顺手装一个python-louvain，或者直接用NetworkX自带的louvain_communities。再想算NMI、ARI之类的指标，可以装scikit-learn。这些都是成熟稳定的库，用的人多，坑少。

2.2 最小可用代码：生成、统计、可视化一条龙

直接放一段完整的脚本，照抄就能跑：

import networkx as nx import matplotlib.pyplot as plt n = 6 # 洞穴数量 k = 4 # 每个洞穴的成员数 G = nx.caveman_graph(n=n, k=k) print(nx.info(G)) print("平均聚类系数:", round(nx.average_clustering(G), 4)) print("直径:", nx.diameter(G)) # 按洞穴生成社区划分标签，作为“真实答案” partition = [set(range(i*k, (i+1)*k)) for i in range(n)] # 可视化：用环状布局，能比较清楚看到社区链 plt.figure(figsize=(8, 6)) pos = nx.circular_layout(G) nx.draw(G, pos=pos, with_labels=True, node_color='lightblue', edge_color='gray', node_size=500) plt.show()

跑完后注意两点。第一，partition是按节点下标构造的，因为NetworkX默认给节点编号0到n*k-1，前k个是一个团，后k个是另一个团，逐块切片就行。第二，circular_layout在观察caveman图时特别好用，因为图的环状结构正好可以被展示出来；如果用默认的spring布局，大概率会拉成一团乱麻，什么都看不出来。

2.3 参数n和k的真实含义：调参前先算一笔账

这两个参数看似简单，但直接影响图的几何规模。先看总节点数公式：

N = n × k

总边数也可以精确推导。每个洞穴内部是一个k-团，产生 k(k-1)/2 条边；n个洞穴就是 n × k(k-1)/2；再加上洞穴之间的n条桥接边，所以标准构造下的总边数：

E = n × k(k-1)/2 + n

拿n=5、k=4来说，N=20，E=5×6+5=35，平均度 = 2E/N = 2×35/20 = 3.5。这组数据是不是很眼熟？一个社区内部的成员几乎和另外3个人紧密相连，外带0.5条“跨社区通道”。平均度不高，但每个社区内部密度已经很高了。

实际调参建议：

• n决定社区数量。如果你后面要做多分类GNN数据，n就是类别数，别设太小，否则类别不平衡问题会很难看。
• k决定社区规模。k越大，每个社区内部越稠密，聚类系数越接近1，但总节点数也线性膨胀。想做小规模快速实验，k取4~6；想测试算法在大型图上的表现，再考虑k取10以上。
• 别把k设成2以下。k=1时每组只有一个孤立节点，caveman图直接退化成一个大环，社区结构荡然无存；k=2时每组只有一条边，勉强算有“社区”但边界太脆弱，社区发现算法基本都要翻车。

我建议可以写个循环，批量生成不同n和k的组合，观察指标变化趋势：

for n in [4, 8, 12]: for k in [3, 5, 8]: G = nx.caveman_graph(n=n, k=k) Q = nx.community.modularity( G, [set(range(i*k, (i+1)*k)) for i in range(n)] ) print(f"n={n}, k={k}, 节点数={G.number_of_nodes():3d}, " f"边数={G.number_of_edges():4d}, 模块度={Q:.4f}")

模块度Q是社区划分质量的传统指标，取值越接近1越说明社区边界清晰。caveman图在这个指标上的表现通常非常亮眼，范围大概在0.7到0.9之间。如果算出来的Q特别低，先检查一下partition有没有漏节点或者重叠节点。

2.4 connected_caveman_graph和基础版到底差在哪

NetworkX里还提供了一个变体接口，叫connected_caveman_graph(n, k)。我一开始以为它和基础版没区别，因为基础版本身由n个团串成环，整体就是连通的。后来对比边列表才看出门道：基础版的桥接边非常稀疏，每个团里基本只有“代表节点”出去认识一下其他洞穴；而connected版本相当于把洞穴之间的连接变得更系统、更稳固，相当于给每个洞穴都开了更多的“对外通道”。

从使用场景来区分：

• 用caveman_graph，你得到的是一个桥接关系极其稀疏的环状社区图，适合做“极端社区结构”的测试，也适合观察一条跨社区连接对整个网络带来的影响。
• 用connected_caveman_graph，跨社区连接更丰富，整体鲁棒性更高，更接近真实世界中“哪怕这个社区内部再封闭，也总有几个成员会认识外面的人”的情形。

我在实际项目里，做社区发现算法效果评估时两种都会用：先用基础版跑，验证算法对“理想社区”的还原度；再用connected版本，看看社区间弱连接增多之后，算法是否还能保持稳定。你可以把这两个图同时打印出来对比一下，这个差异胜过读十遍文档。

2.5 再加一个变体：relaxed_caveman_graph

如果觉得基础版太“完美”，社区之间太过泾渭分明，NetworkX还提供了relaxed_caveman_graph(n, k, p, seed)。它的作用是在保持社区骨架不变的前提下，引入随机性，让边重连变得不那么绝对，从而生成“带噪声的社区结构”。参数p控制扰动强度，p=0时近似基础版，p越大，社区边界越模糊。

我不建议一上来就纠结p的精确定义，重点是理解这个变体背后的意义：真实网络没有哪个社区像“教科书”一样干净，总会有人际连接跨来跨去。先用基础版验证算法，再用relaxed版本测鲁棒性，这才是一套完整的评估思路。

3. 实战场景：社区发现与图神经网络数据构造

3.1 用caveman图给Louvain算法做“体检”

社区发现算法鱼龙混杂，表面看都把图分成了几块，但分块质量天差地别。caveman图最大的价值就是能当试金石：真实划分你手里有，算法跑完直接和真实划分对比，算法行不行一眼就清楚。

完整代码示例：

import networkx as nx import numpy as np from sklearn.metrics import normalized_mutual_info_score, adjusted_rand_score from networkx.algorithms.community import louvain_communities n, k = 8, 6 G = nx.caveman_graph(n=n, k=k) true_partition = [set(range(i*k, (i+1)*k)) for i in range(n)] def partition_to_labels(nodes, partition): label = {} for comm_id, comm in enumerate(partition): for node in comm: label[node] = comm_id return [label[node] for node in nodes] y_true = partition_to_labels(G.nodes(), true_partition) # 跑Louvain，固定随机种子保证可复现 communities = louvain_communities(G, seed=42) y_pred = partition_to_labels(G.nodes(), communities) nmi = normalized_mutual_info_score(y_true, y_pred) ari = adjusted_rand_score(y_true, y_pred) print("真实社区数:", len(true_partition)) print("Louvain识别社区数:", len(communities)) print("NMI:", round(nmi, 4)) print("ARI:", round(ari, 4))

按我的经验，n、k选得不极端的情况下，NMI和ARI基本都在0.9以上，经常是1.0。这里的逻辑很清楚：caveman图结构这么干净，如果某个社区发现算法跑在上面还分得七零八落、NMI低于0.5，那问题大概率不在图数据，而在算法本身或实现细节。这时候就该回头检查代码，别急着换数据集。

3.2 给GNN造一批自带标准答案的节点分类数据

图神经网络做节点分类时，经常需要带标签的图数据。真实数据集获取成本高、标签噪声大，caveman图反而是个廉价的替代：标签就是洞穴编号，天然符合“同一社区的节点同属一个类别”的假设，而且社区数量、社区规模、连边密度都能按需调整。

用PyG构造Data对象的示例：

import torch from torch_geometric.data import Data import networkx as nx n, k = 10, 8 G = nx.caveman_graph(n=n, k=k) # 邻接矩阵转edge_index，注意是无向图，需要对称化 adj = nx.to_scipy_sparse_array(G, nodelist=list(G.nodes())) coo = adj.tocoo() edge_index = torch.tensor( [coo.row, coo.col], dtype=torch.long ) # 节点特征：直接用随机特征或者结合度数特征 x = torch.cat([ torch.randn(n*k, 16), torch.tensor([deg for _, deg in G.degree()]).unsqueeze(1) ], dim=1) # 标签：前k个属于类0，后k个属于类1，以此类推 y = torch.tensor([i // k for i in range(n*k)], dtype=torch.long) data = Data(x=x, edge_index=edge_index, y=y)

这里有两个实用建议。第一，度数特征很有用，因为caveman图的节点度数和社区位置强相关：基础版里大多数节点度数是k-1，只有少量跨社区节点的度数是k，模型很容易学到这种模式；如果你只想测图结构编码器的能力，可以不加度数特征。第二，PyG的Data对象自带train_mask、val_mask、test_mask字段，生成后按节点比例划分就行，记得让每个社区的节点都均匀出现在三个集合里，否则类别缺失会让评估失真。

不用PyG的话也没关系，导成edge_list.csv加labels.csv，任何框架都能消费。核心价值不在框架，而在于这个数据天生带“正确分组答案”，做模型对比时可信度高。

3.3 从标准caveman走向贴近现实的变体组合

真实的社区不会全都是固定的大小，也不会全都有“铁板一块”的内部密度。如果只靠标准的caveman图做评估，很容易产生一种错觉：只要算法能把完全图分开，就算合格。实际上还需要测试更复杂的情况。

我常用的一种组合策略是：先把n个团的大小改成随机分布，比如定义size_list = [4, 6, 5, 9, 7]，每个团的k不一样，然后手动构造图。这样社区数量、整体节点数不变，但社区大小分布不再均匀，更接近真实网络。实现也不复杂，循环构造团，再按顺序把相邻团用一条桥接边连起来，几十行代码就能搞定。

另一种策略是用relaxed_caveman_graph加噪声。先跑一遍基础版得到上界指标，再逐步增大p值，观察社区发现算法的性能曲线。如果某个算法在p很小的时候就开始掉点，说明它对社区边界极其敏感，在真实数据上大概率也不稳定。

3.4 带权图的小技巧：给“串门通道”打个折

还有一个容易被忽略的扩展：把跨社区边的权重调低，把社区内部边的权重调高。做法很简单，遍历图边，判断两个端点是否属于同一社区，属于则权重设为1.0，跨社区则设为0.1。

加权之后，社区结构依然清晰，但算法能利用的信息更丰富。很多社区发现算法、图神经网络都支持edge_weight，这种设置可以让你在“结构清晰”的基础上继续考察算法对边权重的敏感度。这个思路在做推荐系统中用户社群划分的时候尤其有用，因为用户间的弱交互通常权重很低，直接丢掉会损失信息。

4. 避坑指南：这些坑我全都踩过

4.1 不要拿随机布局看社区结构

最早我用Matplotlib画caveman图，直接用默认的spring布局，结果图上一团浆糊，根本看不出“洞穴套洞穴”的结构，我当时差点怀疑数据生成错了。后来换了circular_layout，效果立竿见影：几个团沿着环排列，团内边密密麻麻，团间只有稀疏几条，社区边界一目了然。

经验是：画caveman图千万要用环状布局或按社区着色之后再用带力导向的布局，否则视觉反馈会严重误导判断。如果节点数超过几百个，spring_layout还会慢得让人怀疑人生，这时候circular_layout几乎是不二选择。

按社区着色示例：

colors = [i // k for i in G.nodes()] nx.draw(G, pos=nx.circular_layout(G), node_color=colors, cmap=plt.cm.tab20, node_size=300, with_labels=False)

不过注意，默认的tab20色图最多支持20个社区，社区数超过20时建议换成gist_rainbow这类连续色图，或者自己造颜色列表。

4.2 别把聚类系数想当然地当成1

很多人直觉上觉得caveman图每组内部都是完全图，聚类系数肯定等于1。实际去算，基础版caveman图的平均聚类系数可能只有0.8左右。原因就出在跨社区连接上：拥有跨社区边的节点，它的邻居集合里多了一个“外来户”，这个外来户和它周围的其他邻居之间没有边，所以该节点的局部聚类系数不再是1，被拉低了。

这个细节在对比实验里很关键。如果你拿聚类系数当特征，却不理解它为什么不是1，后面分析会绕很多弯路。我用过一个取巧的办法：先算平均聚类系数，再分别统计“有跨社区边的节点”和“没有跨社区边的节点”的聚类系数，两者的差值恰好能反映桥接边带来的局部结构扰动。

4.3 基础版和connected版本别混用，结论会打架

之前有次实验，同事A用caveman_graph生成数据集，同事B用connected_caveman_graph声称复现，结果两个人跑出来的模块度、NMI差了一大截，还以为是算法实现有bug。其实纯粹是数据集生成接口用差了。

建议固定使用同一版本，并在实验记录里写清楚函数名和参数。另外，relaxed_caveman_graph带随机逻辑，生成时必须传入seed固定随机种子，否则每次生成的结构都不一样，实验结果无法复现。

4.4 社区发现结果异常时的排查顺序

如果跑Louvain或者其他社区发现算法时，结果和预期差太多，我建议按以下顺序排查：

4.5 别把caveman图的“度分布整齐”当缺陷乱加噪声

caveman图确实不像真实社交网络那样有幂律度分布，很多刚接触图生成模型的人会强行往上加一堆随机边，想让它“更像真的”。想法可以，但要搞清楚目的：合成图的价值在于可控，而不是单纯模拟真实。想要真实感，请直接用LFR基准图，它同时支持幂律度分布和社区结构调节；想要可控的社区属性，caveman才是对的选择。硬在caveman图上叠加随机边，最后只会得到一个既不像真实网络、也失去理论边界的四不像。正确操作是：caveman图负责验证算法上限，LFR图负责验证算法在真实度更高场景下的表现，两者互补，不冲突。

5. 最后再分享一点个人体会

我自己做社区发现算法评测时，已经把caveman图当成一个压舱石工具，每次要验证新的聚类思路，第一件事就是跑一遍不同n、k参数组合的caveman图。这个过程看起来简单，但真能帮大忙：它逼你把核心逻辑先跑通，排除数据本身的干扰。如果你刚开始接触图算法，我强烈建议先把caveman图生成、可视化、模块度计算这三步走顺，再去碰真实数据集。踩坑踩多了之后你会发现，很多复杂问题最后都归结为“你的基准图到底是不是真的可控”这一件事。希望这篇内容能帮你少走点弯路。