使用 PyTorch 的 K 均值聚类

基于 PyTorch 的 K 均值聚类实现，可利用 GPU 加速

快速入门

import torch
import numpy as np
from kmeans_pytorch import kmeans

# 数据
data_size, dims, num_clusters = 1000, 2, 3
x = np.random.randn(data_size, dims) / 6
x = torch.from_numpy(x)

# K 均值聚类
cluster_ids_x, cluster_centers = kmeans(
    X=x, num_clusters=num_clusters, distance='euclidean', device=torch.device('cuda:0')
)

更多详细示例请参阅 example.ipynb

系统要求

• PyTorch 版本 ≥ 1.0.0
• Python 版本 ≥ 3.6

安装

使用 pip 安装：

pip install kmeans-pytorch

从源码安装

若需从源码安装并进行本地开发：

git clone https://github.com/subhadarship/kmeans_pytorch
cd kmeans_pytorch
pip install --editable .

CPU 与 GPU 对比

CPU 和 GPU 的性能对比请参阅 cpu_vs_gpu.ipynb

注意事项

• 在对大量样本进行聚类时非常有用
• 利用 GPU 加速矩阵运算，提升计算速度
• 目前支持欧氏距离和余弦距离

致谢

• 本实现严格遵循 此项目 的风格
• 文档采用优秀的主题 jekyllbook

许可证

MIT

kmeans_pytorch 快速上手指南

环境准备

在开始使用前，请确保您的开发环境满足以下要求：

• Python 版本：>= 3.6
• PyTorch 版本：>= 1.0.0
• 硬件加速（可选）：支持 NVIDIA GPU 以利用 CUDA 加速大规模矩阵计算；若无 GPU，也可在 CPU 上运行。

安装步骤

您可以通过 pip 直接安装稳定版，或从源码安装以进行本地开发。

方式一：使用 pip 安装（推荐）

pip install kmeans-pytorch

国内加速提示：如果您在中国大陆地区，建议使用清华或阿里镜像源以提升下载速度：

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

方式二：从源码安装

git clone https://github.com/subhadarship/kmeans_pytorch
cd kmeans_pytorch
pip install --editable .

基本使用

以下是最简单的使用示例，展示如何生成随机数据并执行 K-Means 聚类。该库支持自动调用 GPU 进行加速。

import torch
import numpy as np
from kmeans_pytorch import kmeans

# 1. 准备数据
data_size, dims, num_clusters = 1000, 2, 3
x = np.random.randn(data_size, dims) / 6
x = torch.from_numpy(x)

# 2. 执行 K-Means
# device 可设置为 'cuda:0' 启用 GPU，或 'cpu' 使用 CPU
cluster_ids_x, cluster_centers = kmeans(
    X=x, 
    num_clusters=num_clusters, 
    distance='euclidean', 
    device=torch.device('cuda:0')
)

# cluster_ids_x: 每个样本所属的簇 ID
# cluster_centers: 各个簇的中心点坐标

参数说明：

• X: 输入数据张量 (Tensor)。
• num_clusters: 需要划分的簇数量 (K 值)。
• distance: 距离度量方式，支持 'euclidean' (欧氏距离) 和 'cosine' (余弦距离)。
• device: 指定运行设备，推荐使用 torch.device('cuda:0') 以获得最佳性能。