图嵌入引擎

Cleora 通过一次矩阵乘法即可计算所有可能的随机游走。
无需负采样，无需 GPU，无噪声。只有快速、确定性、生产级的嵌入。

官网  ·  文档  ·  API 参考  ·  基准测试

pip install pycleora

---

#1 准确率。每个数据集。
在5 个经典的学术数据集上，与7 种竞争算法进行对比——Cleora 在每一个数据集上都取得了最高的准确率，
并且是唯一一种能够扩展到任意规模图而不崩溃的算法。

比 GraphSAGE 快240 倍  ·  内存占用比 NetMF 少50 倍  ·  安装包仅约5 MB  ·  不需要任何GPU

---

成就

在 SIGIR eCom Challenge 2020 中获得第1名

在 WSDM Booking.com Challenge 2021 中获得第2名及最佳论文奖

在 Twitter Recsys Challenge 2021 中获得第2名

在 KDD Cup 2021 中获得第3名

---

安装

pip install pycleora

可选扩展：

pip install pycleora[viz]       # matplotlib 用于可视化
pip install pycleora[full]      # matplotlib + networkx + tqdm

快速入门

from pycleora import SparseMatrix, embed, find_most_similar

edges = ["alice item_laptop", "alice item_mouse", "bob item_keyboard"]
graph = SparseMatrix.from_iterator(iter(edges), "complex::reflexive::product")

embeddings = embed(graph, feature_dim=256, num_iterations=40)

similar = find_most_similar(graph, embeddings, "alice", top_k=5)
for r in similar:
    print(f"{r['entity_id']}: {r['similarity']:.4f}")

embed() 的默认参数为 feature_dim=256、num_iterations=40，并在每一步传播后进行白化处理。

分步示例

高级别 embed() 函数封装了马尔可夫传播循环，方便使用。以下是完整的手动版本，可以让你完全控制整个过程：

from pycleora import SparseMatrix, whiten_embeddings
import numpy as np
import pandas as pd
import random

customers = [f"Customer_{i}" for i in range(1, 20)]
products = [f"Product_{j}" for j in range(1, 20)]

data = {
    "customer": random.choices(customers, k=100),
    "product": random.choices(products, k=100),
}

df = pd.DataFrame(data)
customer_products = df.groupby('customer')['product'].apply(list).values
cleora_input = map(lambda x: ' '.join(x), customer_products)

mat = SparseMatrix.from_iterator(cleora_input, columns='complex::reflexive::product')

print(mat.entity_ids)

embeddings = mat.initialize_deterministically(256)

NUM_ITERATIONS = 40

for i in range(NUM_ITERATIONS):
    embeddings = mat.left_markov_propagate(embeddings)
    embeddings /= np.linalg.norm(embeddings, ord=2, axis=-1, keepdims=True)
    embeddings = whiten_embeddings(embeddings)

for entity, embedding in zip(mat.entity_ids, embeddings):
    print(entity, embedding)

print(np.dot(embeddings[0], embeddings[1]))

命令行工具

pycleora embed --input graph.tsv --output embeddings.npz --dim 256 --iterations 40
pycleora info --input graph.tsv
pycleora similar --input graph.tsv --entity alice --top-k 10
pycleora benchmark --dataset karate_club

---

核心优势

无负采样

与 DeepWalk、Node2Vec 和 LINE 不同，Cleora 不使用负采样来近似随机游走。它通过矩阵乘法精确计算所有游走路径。噪声更少，准确更高，结果完全可复现。

比 GraphSAGE 快 240 倍

Zomato 报告称，使用 Cleora 在不到 5 分钟内即可生成嵌入，而使用 GraphSAGE 在相同数据集上则需要20 小时。基于 Rust 的核心实现了自适应并行化，充分利用每一颗 CPU 核心。

确定性嵌入

相同的输入始终产生相同的输出。没有随机种子，没有随机波动，无需“运行 5 次取平均”的流程。这对于可复现的研究和生产级机器学习流水线至关重要。

异构超图支持

原生支持多类型节点和边、二分图以及超图。只需提供带有类型列（如 complex::reflexive::product）的 TSV 文件即可，无需任何图预处理。

约 5 MB，零依赖

整个库的大小约为 5 MB。相比之下，PyTorch Geometric 超过 500 MB，DGL 则有 400 MB。Cleora 以单个编译好的 Rust 扩展形式发布，无需 CUDA、cuDNN 或 GPU 驱动程序带来的麻烦。

稳定且具备归纳性

嵌入在不同运行之间保持稳定，并支持归纳学习：新节点可以直接嵌入，而无需重新训练整个图。从第一天起即可投入生产使用。

---

支持的算法

算法	类型	描述
Cleora	谱方法 / 随机游走	迭代式马尔可夫传播，每步后进行白化——所有随机游走仅需一次矩阵乘法
ProNE	谱方法	使用切比雪夫多项式近似的快速谱传播
RandNE	随机投影	高斯随机投影，用于快速近似嵌入
NetMF	矩阵分解	网络矩阵分解——显式分解 DeepWalk 矩阵
DeepWalk	随机游走	经典的随机游走结合 skip-gram 方法
Node2Vec	随机游走	具有 BFS/DFS 探索权衡的偏置随机游走
HOPE	矩阵分解	保留高阶邻近关系的嵌入
GraRep	矩阵分解	包含全局结构信息的图表示
MLP	神经分类器	纯 NumPy/SciPy 实现的两层 MLP 分类器——无需 PyTorch

所有算法都统一在一个 API 下。只需更改一个参数即可切换方法：

pycleora embed --input graph.tsv --output out.npz --algorithm cleora
pycleora embed --input graph.tsv --output out.npz --algorithm prone
pycleora embed --input graph.tsv --output out.npz --algorithm node2vec

高级嵌入模式

除了标准算法之外，Cleora 还支持多种高级嵌入策略：

• 多尺度嵌入 — 将不同迭代深度的嵌入拼接在一起（例如尺度为 [10, 20, 30, 40]），以同时捕捉局部和全局图结构。
• 注意力加权传播 — 在传播过程中使用 softmax 归一化的点积注意力机制，动态调整邻居节点的贡献权重。
• 监督精调 — 利用正负实体对和三元组间隔损失来微调无监督嵌入。
• 有向图嵌入 — 处理边的方向性很重要的非对称关系。
• 加权图嵌入 — 在传播步骤中纳入边的权重。
• 节点特征集成 — 在传播之前，使用外部特征（文本、图像、数值）初始化嵌入。
• PCA 白化 — 默认在每次迭代后进行白化处理，以消除嵌入维度之间的相关性，并提升下游任务的表现。

---

一站式解决方案

pycleora 自带一套全面的内置模块：

模块	功能
pycleora.community	社区检测（Louvain 算法）
pycleora.classify	MLP 和标签传播分类器 — 无需 PyTorch
pycleora.sampling	6 种图采样方法
pycleora.tuning	网格搜索和随机搜索用于超参数调优
pycleora.compress	嵌入压缩（PQ、标量量化）
pycleora.io_utils	保存/加载嵌入（NPZ、CSV、TSV）、NetworkX 转换
pycleora.viz	嵌入可视化（UMAP、t-SNE 投影）
pycleora.metrics	嵌入评估指标
pycleora.benchmark	使用时间、内存和准确率指标比较算法
pycleora.ensemble	结合多个算法的嵌入结果
pycleora.align	图之间的嵌入对齐
pycleora.search	最近邻实体搜索
pycleora.stats	图统计与度分析
pycleora.preprocess	图预处理与过滤
pycleora.hetero	异质图工具
pycleora.generators	用于测试的合成图生成器
pycleora.datasets	现实世界基准数据集（Facebook、Cora、CiteSeer、PubMed、PPI、roadNet-CA 等）

有关每个函数和参数的详细信息，请参阅 完整 API 参考。

---

案例研究：Zomato

从 20 小时缩短至不到 5 分钟 — 为 500 多座城市的 8000 万+ 用户提供推荐服务。

Zomato 的机器学习团队需要图嵌入来驱动“像你一样的人”餐厅推荐功能。他们最初采用 GraphSAGE 方法，仅处理一个城市区域的顾客-餐厅交互数据就需要约 20 小时，这使得扩展到 500 多座城市变得不可能。

流程：

1. 顾客-餐厅图 — 顾客订单与餐厅互动的二分图
2. Cleora 嵌入（< 5 分钟）— 比 DeepWalk 快 197 倍，无需对正负样本进行采样
3. EMDE 密度估计 — 将顾客偏好建模为概率密度函数
4. 生产环境推荐 — 餐厅推荐、搜索排序、菜品建议以及“像你一样的人”相似用户查找

结果：

指标	数值
速度 vs DeepWalk	197 倍更快
嵌入生成	< 5 分钟
扩展城市数量	500+
所需 GPU 数量	0

阅读完整的 Zomato 博客文章 →

---

基准测试

我们在 5 个真实世界数据集（ego-Facebook、Cora、CiteSeer、PubMed、PPI）以及一个 200 万节点的大规模测试上，与 7 种竞争算法进行了对比。所有数据集均来自 SNAP、Planetoid 和 DGL 的权威学术基准。Cleora 在 每一个数据集上都取得了最高的准确率。

完整的交互式基准测试结果请访问 cleora.ai/benchmarks。

分类准确率

数据集	节点数	Cleora	NetMF	DeepWalk	Node2Vec	HOPE	GraRep	ProNE	RandNE
ego-Facebook	4K	0.990	0.957	0.958	0.958	0.890	T/O	0.075	0.212
Cora	2.7K	0.861	0.839	0.835	0.835	0.821	0.809	0.179	0.247
CiteSeer	3.3K	0.824	0.810	0.806	0.806	0.740	0.756	0.189	0.244
PubMed	19.7K	0.879	OOM	T/O	T/O	T/O	OOM	0.339	0.351
PPI	3.9K	1.000	OOM	T/O	T/O	T/O	OOM	0.023	0.073

在 19.7K 节点的数据集上，只有 3 种算法能够运行。 HOPE、NetMF、GraRep、DeepWalk 和 Node2Vec 全部崩溃或超时。而 Cleora 在 PPI 数据集上实现了完美的分类准确率（50 个类别）。

内存效率

数据集	Cleora	最佳竞争对手	差异倍数
ego-Facebook (4K)	22 MB	572 MB	少 26 倍
Cora (2.7K)	14 MB	227 MB	少 16 倍
CiteSeer (3.3K)	16 MB	294 MB	少 18 倍
PubMed (19.7K)	97 MB	175 MB	只有 3 种算法存活
roadNet-CA (2M)	4.1 GB	—	只有 Cleora 完成了计算

大规模测试：roadNet-CA（200 万个节点）

200 万个节点。31 秒。其他所有算法均因内存不足而崩溃。Cleora 是唯一一款能够在单核 CPU 上完成如此大规模计算的库。

---

库对比

特性	pycleora 3.2	PyG	KarateClub	DGL	Node2Vec	StellarGraph
仅 CPU 运行（无需 GPU）	是	可选	是	可选	是	可选
Rust 驱动的核心	是	否（C++）	否	否（C++）	否	否（TF）
无需负采样	是	否	否	否	否	否
确定性输出	是	否	否	否	否	否
Node2Vec / DeepWalk	内置	是	是	是	是	是
MLP 分类器（无需 PyTorch）	MLP	需要 PyTorch	否	需要 PyTorch	否	需要 TF
图采样	6 种方法	是	否	是	否	是
超参数调优	网格 + 随机	手动	否	手动	否	手动
安装大小	~5 MB	~500 MB+	~15 MB	~400 MB+	~2 MB	~600 MB+
积极维护	是	是	是	是	是	已归档

---

使用场景

• 推荐系统 — 商品、内容、餐厅、视频
• 知识图谱 — 实体和关系嵌入
• 客户相似画像 — 找到行为模式相似的用户
• 实体消歧 — 在不同数据源中匹配实体
• 欺诈检测 — 检测交易图中的异常模式
• 社交网络 — 社区发现和链接预测
• 药物发现 — 分子与蛋白质相互作用网络
• 供应链 — 供应商和物流图分析

更多包含代码示例的详细教程，请参阅 cleora.ai/use-cases。

---

工作原理

1. 输入数据 — 提供边列表、交互日志或知识三元组。Cleora 接受任何带有类型列的 TSV 文件。
2. 超图构建 — 构建一个异构超图，其中一条边可以连接多个不同类型实体。
3. 稀疏马尔可夫矩阵 — 构造一个稀疏转移矩阵（99%以上为零）。行已归一化，使得每行之和为 1。
4. 一次矩阵乘法 = 所有随机游走 — 通过一次稀疏矩阵乘法即可捕捉给定长度下的 所有可能的随机游走。无需采样，无噪声。
5. L2 归一化 + 白化传播 — 每次迭代都会用其邻居的 L2 归一化平均值替换每个节点的嵌入向量，并对嵌入空间进行白化处理。默认配置为 256 维下运行 40 次迭代。
6. 嵌入就绪 — 为每个实体生成稠密且确定性的嵌入向量。相同的输入始终产生相同的输出。

---

其他应用案例

Synerise — 一款每日处理数十亿电商事件的人工智能/机器学习平台。Cleora 支撑了核心的推荐与个性化功能：从数 TB 的交易数据中提取商品嵌入，识别替代品与互补品，进行客户细分，解决冷启动问题——所有这些操作均可在 CPU 上几分钟内完成。

Dailymotion — 一家月访问量超过 3.5 亿的视频平台。利用 Cleora 提供个性化视频推荐，显著提升了相关性和内容覆盖范围。

机器学习竞赛 — 基于 Cleora 的解决方案在 KDD Cup 2021、WSDM WebTour 2021 和 SIGIR eCom 2020 等比赛中名列前茅，在旅行、电商和网页推荐基准测试中击败了深度学习方法。

---

常见问题解答

问：我应该嵌入什么？

答：任何彼此交互、共同出现，或可在特定上下文中被认为同时存在的实体。例如：购物篮中的商品、同一人群在相近时间频繁光顾的地点、协同工作的员工、特定条件下共存的化学分子、由同种细菌产生的蛋白质、药物相互作用、撰写同一学术论文的作者、出现在同一 LinkedIn 个人资料中的公司等。

问：我该如何构造输入数据？

答：最佳做法是将处于相似上下文中的实体分组，并以空格分隔的形式逐行输入。使用 complex::reflexive 修饰符是个不错的选择。例如，若你有商品数据，可按购物篮或用户进行分组；若你有 URL 数据，则可按浏览器会话或 (用户, 时间窗口) 对进行分组。请参考上述使用示例。按客户分组只是众多可能性之一。

问：我可以同时嵌入用户和商品，然后用余弦相似度比较它们吗？

答：不可以。这种做法在方法论上是错误的，源于过时的矩阵分解方法。正确的做法是先获得高质量的商品嵌入，再基于这些嵌入生成用户嵌入。如果直接将两列数据（如“用户 商品”）输入 Cleora，将会得到一个二部图。相似的商品会彼此靠近，相似的用户也会彼此靠近，但用户和商品之间并不一定具有相似性。

问：应使用多少维的嵌入？

答：默认值为 256。对于大型生产系统，我们通常使用 1024 到 4096 维，但库提供的基础配置为 256 维。

问：我应该进行多少步的马尔可夫传播？

答：默认为 40 步增强白化的传播过程。若希望获得更局部、基于共现的行为特征，可手动减少迭代次数；较高的迭代次数则会更多地偏向于上下文相似性。

问：如何将外部信息，如实体元数据、图像、文本等融入嵌入中？

答：只需用来自 VIT、sentence-transformers 或数值特征随机投影的自定义向量初始化嵌入矩阵即可。在这种情况下，通常使用少于默认的 40 次马尔可夫迭代效果更好。

问：我的嵌入数据太大，无法放入内存，该怎么办？

答：Cleora 可以独立处理各个维度。先用较少的维度初始化嵌入，运行 Cleora，将其持久化到磁盘，然后再重复此过程。最后可以将结果嵌入向量拼接起来，但务必记得随后对其进行归一化！

问：是否存在实体出现次数的最低要求？

答：没有。即使实体 A 只与另一实体 B 共现 1 次，它也能获得合理的嵌入表示，即 B 将成为与 A 最相似的实体。反之亦然，A 会在 B 的最近邻中占据较高排名，但这是否符合需求取决于具体应用场景。您可以根据需要对输入数据进行过滤，去除低频项。

问：Cleora 是否存在某些特殊情况会导致失效？

答：Cleora 最适合处理相对稀疏的超图。如果您的所有超边都包含某个非常常见的实体，例如“购物袋”，那么这会通过退化随机游走中的最短路径来降低嵌入质量。因此，建议将此类实体从超图中移除。

问：Cleora 是如何做到既快速又准确的呢？

答：不采用负采样是一个巨大优势。通过构建稀疏的马尔可夫转移矩阵，Cleora 能够在一个大步骤中显式地执行超图中的所有可能的随机游走（即一次矩阵乘法）。这就是所谓的单次“迭代”。默认配置为 40 次迭代，且每一步之后都会进行白化处理。而负采样或随机选择随机游走往往会引入大量噪声——Cleora 则完全避免了这些问题。

---

资源

• 官网: cleora.ai
• API 文档: cleora.ai/api
• 基准测试: cleora.ai/benchmarks
• 白皮书: "Cleora: 一种简单、强大且可扩展的图嵌入方案"
• GitHub: github.com/BaseModelAI/cleora
• PyPI: pypi.org/project/pycleora

引用

如果您在自己的工作中使用此代码，请引用我们的论文（以及所用方法的相应论文）：

@article{DBLP:journals/corr/abs-2102-02302,
  author    = {Barbara Rychalska, Piotr Babel, Konrad Goluchowski, Andrzej Michalowski, Jacek Dabrowski},
  title     = {Cleora: {一个}简单、强大且可扩展的图嵌入方案},
  journal   = {CoRR},
  year      = {2021}
}

许可证

采用 MIT 许可证。详情请参阅 LICENSE。

贡献

欢迎提交 Pull 请求。对于重大更改，请先提出问题。联系方式：cleora@synerise.com

Cleora 快速上手指南

Cleora 是一款高性能的图嵌入引擎，无需 GPU、无需负采样，通过单次矩阵乘法即可计算所有可能的随机游走。它以确定性、高准确率和极低内存占用著称，适合生产环境部署。

环境准备

• 操作系统：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上版本。
• 硬件要求：无需 GPU。基于 Rust 核心构建，充分利用 CPU 多核并行计算，内存占用极低（比同类工具少 50 倍）。
• 前置依赖：无重型依赖（如 PyTorch 或 TensorFlow）。基础安装仅需 pip。若需可视化功能，可选安装 matplotlib。

国内加速提示：建议使用国内镜像源安装以提升下载速度。

pip install pycleora -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 基础安装

安装核心库（约 5 MB）：

pip install pycleora

2. 可选扩展

如需使用可视化功能或完整依赖包（包含 networkx, tqdm 等）：

# 仅安装可视化工具
pip install pycleora[viz]

# 安装完整功能包
pip install pycleora[full]

基本使用

方法一：Python API（推荐）

以下示例展示如何从边列表构建图、生成嵌入向量并查找相似节点。

from pycleora import SparseMatrix, embed, find_most_similar

# 1. 准备数据：格式为 "源节点 目标节点"
edges = ["alice item_laptop", "alice item_mouse", "bob item_keyboard"]

# 2. 构建稀疏矩阵
# columns 参数定义列类型，支持异构图谱 (complex::reflexive::product)
graph = SparseMatrix.from_iterator(iter(edges), "complex::reflexive::product")

# 3. 生成嵌入向量
# 默认特征维度 256，迭代 40 次，每步自动进行白化处理
embeddings = embed(graph, feature_dim=256, num_iterations=40)

# 4. 查找最相似的实体
similar = find_most_similar(graph, embeddings, "alice", top_k=5)
for r in similar:
    print(f"{r['entity_id']}: {r['similarity']:.4f}")

方法二：命令行工具 (CLI)

Cleora 提供了完整的命令行接口，适合处理大规模 TSV 文件。

生成嵌入：

pycleora embed --input graph.tsv --output embeddings.npz --dim 256 --iterations 40

查看图信息：

pycleora info --input graph.tsv

查找相似节点：

pycleora similar --input graph.tsv --entity alice --top-k 10

运行基准测试：

pycleora benchmark --dataset karate_club

进阶控制（手动模式）

如果需要完全控制传播过程（如自定义归一化方式），可以使用底层 API：

from pycleora import SparseMatrix, whiten_embeddings
import numpy as np

# ... (数据准备同上) ...
mat = SparseMatrix.from_iterator(cleora_input, columns='complex::reflexive::product')

# 确定性初始化
embeddings = mat.initialize_deterministically(256)

NUM_ITERATIONS = 40
for i in range(NUM_ITERATIONS):
    # 左马尔可夫传播
    embeddings = mat.left_markov_propagate(embeddings)
    # L2 归一化
    embeddings /= np.linalg.norm(embeddings, ord=2, axis=-1, keepdims=True)
    # 白化处理
    embeddings = whiten_embeddings(embeddings)

# 输出结果
for entity, embedding in zip(mat.entity_ids, embeddings):
    print(entity, embedding)