karateclub，一个强大的 Python 库！

用户关系已经拉成边表了，结果下一步卡住了。

SQL 能查出 user_a、user_b、score，NetworkX 也能画图，但你真要做“相似用户召回”“异常团伙识别”“社区划分”，就会发现光有图没用。图得变成向量，或者直接变成社群标签。

这时候可以看一眼 karateclub。

它不是那个经典的空手道俱乐部数据集，而是一个 Python 图挖掘库。官方定位很直接：基于 NetworkX 的无监督机器学习扩展库，主要干图嵌入、社区发现、图挖掘这些活。API 也比较统一，基本就是 fit() 进去，get_embedding() 或 get_memberships() 出来。

我对这种库一般不先看论文，先看能不能接住业务里的边表。

比如用户之间有过共同下单、共同设备、共同地址，前面规则已经过滤过一轮，现在想把关系近的用户找出来。边表大概就是这种东西：

raw_edges = [
    ("u_1001", "u_1002", 3),
    ("u_1001", "u_1088", 1),
    ("u_1002", "u_1090", 2),
    ("u_2001", "u_2003", 4),
    ("u_2003", "u_2011", 2),
]

这里我第一眼不会直接喂给 karateclub。它对 NetworkX 图有个要求：节点最好是从 0 开始的连续整数。这个地方很容易坑，业务里的用户 ID 基本都是字符串，直接塞进去，后面 embedding 的行号就不好对了。官方文档也明确提到节点索引要从 0 开始且连续。

我一般先写一个很薄的转换层：

import networkx as nx
def build_graph(edge_rows):
    user_ids = set()
    for left, right, _ in edge_rows:
        if left != right:
            user_ids.add(left)
            user_ids.add(right)
    user_to_idx = {u: i for i, u in enumerate(sorted(user_ids))}
    idx_to_user = {i: u for u, i in user_to_idx.items()}
    graph = nx.Graph()
    graph.add_nodes_from(idx_to_user.keys())
    for left, right, score in edge_rows:
        if left == right:
            continue
        graph.add_edge(user_to_idx[left], user_to_idx[right], weight=score)
    return graph, user_to_idx, idx_to_user

注意，我这里保留了 weight，但不要指望所有算法都认真吃这个权重。图挖掘库最怕的就是“我以为它用了”。真上线前，要么看源码，要么拿几条边做对照实验，别凭感觉。

先跑一个 DeepWalk。它适合做节点向量，后面接相似度、聚类、分类器都行：

from karateclub import DeepWalk
from sklearn.metrics.pairwise import cosine_similarity
graph, user_to_idx, idx_to_user = build_graph(raw_edges)
model = DeepWalk(
    dimensions=32,
    walk_number=20,
    walk_length=40,
    workers=1,
    seed=2026
)
model.fit(graph)
vectors = model.get_embedding()
def similar_users(user_id, topn=5):
    idx = user_to_idx[user_id]
    scores = cosine_similarity(vectors[idx:idx + 1], vectors)[0]
    candidates = []
    for other_idx, score in enumerate(scores):
        if other_idx == idx:
            continue
        candidates.append((idx_to_user[other_idx], float(score)))
    return sorted(candidates, key=lambda x: x[1], reverse=True)[:topn]
print(similar_users("u_1001", topn=3))

这段代码真正有用的地方，不是 DeepWalk 多高级，而是它把“图上的邻近关系”变成了可以排序的向量分数。

以前写推荐召回，很多人会先做一堆规则：

共同设备 +10
共同地址 +8
共同收货人 +5
共同 IP +2

这种规则不是不能用，但问题是越写越像祖传 if-else。加一个新关系，要调一堆权重。图嵌入的好处是，它能把多跳关系一起揉进去。A 和 B 没直接连边，但它们周围邻居很像，向量距离也可能很近。

当然，别把它当神仙。

我一般会先看三件事：

第一，孤立节点多不多。孤立节点没有上下文，算出来的向量价值很低。

第二，最大连通分量占比。如果图被切成一堆小碎片，embedding 的效果通常不会太漂亮。

第三，节点编号有没有对错。这个问题低级，但真容易发生，尤其是结果写回数据库时。

排查代码可以这么写：

def inspect_graph(graph):
    components = sorted(nx.connected_components(graph), key=len, reverse=True)
    largest = len(components[0]) if components else 0
    print({
        "nodes": graph.number_of_nodes(),
        "edges": graph.number_of_edges(),
        "components": len(components),
        "largest_component": largest,
        "isolated_nodes": len(list(nx.isolates(graph)))
    })
inspect_graph(graph)

如果你不是想找相似节点，而是想直接把用户分成几个圈子，可以换社区发现算法。

from karateclub import LabelPropagation
cluster = LabelPropagation(seed=2026)
cluster.fit(graph)
memberships = cluster.get_memberships()
user_groups = {}
for idx, group_id in memberships.items():
    user_groups.setdefault(group_id, []).append(idx_to_user[idx])
for group_id, users in user_groups.items():
    print(group_id, users)

这个结果更适合给运营、风控、审核系统看。

比如某一组用户都共用过设备、地址、支付环境，规则系统只命中了其中两个，社区发现可能把整团拖出来。这里我会很谨慎，不会直接拿它做封禁依据，最多先做线索召回。图算法算出来的是“关系可疑”，不是“事实成立”。

安装也简单：

pip install karateclub

不过这个库不是那种天天更新的新玩具。PyPI 上 karateclub 当前展示的最新版本是 1.3.3，发布时间是 2022 年 10 月 22 日。

所以环境别太激进。Python、NetworkX、NumPy 版本太新时，遇到安装或兼容问题不要先怀疑业务代码。先单独建个虚拟环境，把依赖锁住。

python -m venv .venv_graph
source .venv_graph/bin/activate
pip install karateclub scikit-learn pandas

我更愿意把 karateclub 放在离线任务里用。

比如每天凌晨从订单库、设备库、登录日志里抽边表，构图，跑 embedding，然后把相似用户 TopN 或社区编号写回一张结果表。线上接口只查结果，不在请求链路里现场跑图算法。

这才是比较稳的用法。

它强的地方，是用很少的代码把图挖掘算法接进 Python 工程；它别扭的地方，也很明显：输入图格式要规整，节点编号要处理好，大图性能要自己压测，结果也不能不解释就直接进风控决策。

但如果你手里已经有一堆关系数据，还在用 SQL 一层层 join 去找“谁和谁像”，那 karateclub 值得试一下。

先别上来就搞复杂模型。

先把边表洗干净，把节点映射做对，跑一个 DeepWalk，看相似结果是不是像人话。能过这一关，再谈后面的优化。

上就是“karateclub，一个强大的 Python 库！”的详细内容，想要了解更多Python教程欢迎持续关注编程学习网。