简介：kmodes是一个专注于分类数据聚类的Python库，提供k-Modes与k-Prototypes两种算法，弥补传统k-means无法直接处理类别型或混合型特征的不足。整个压缩包共30个文件，以20个Python源码文件为主，涵盖kmodes.py、kprototypes.py核心实现、测试用例、iris/soybean/stocks等示例脚本及配套CSV数据集，另有README文档和项目配置文件，包体仅36KB，轻巧易用。该资源已有2008人学习下载，适合算法学习者和数据挖掘工程师快速上手。通过阅读源码与运行示例，读者能直观理解汉明距离在分类变量聚类中的应用，掌握k-Prototypes如何结合欧氏距离与汉明距离处理混合数据，并熟悉类似scikit-learn的API调用、参数初始化与聚类评估方法。项目目录结构清晰，便于按模块研读，是实践分类数据聚类任务的优质参考资料。
1. 这个聚类库解决什么问题：当均值失效时，分类数据该怎么做分群
做用户画像或者问卷分析时，都会遇到一个尴尬场景：手里数据全是性别、职业、地区、偏好这类分类变量，根本没法直接算均值。拿传统k-means硬套，欧氏距离算出来毫无意义，聚类结果自然成了玄学。kmodes这个项目就是专门解决这个问题的——它实现了k-modes和k-prototypes两种聚类算法，前者处理纯分类数据，后者能同时混合数值型和分类型字段。我在某电商公司做过一次用户分群，几万条订单数据里全是品类、渠道、支付方式，当时就是靠这个库跑出的分群结果，直接支撑了后续的差异化运营策略。如果你手里的数据是“能分组但不能排名”的类型，比如品牌偏好、设备型号、居住城市，这个项目比scikit-learn自带的聚类模块更对症。
2. 核心思路拆解：从k-means到k-modes，再到混合类型通吃的k-prototypes
2.1 为什么k-means在分类数据上失效
要理解k-modes的巧妙，得先看清k-means的局限。k-means的核心是计算簇内均值，然后把每个样本归到距离最近的簇中心。这里的“均值”只对数值型变量有意义：年龄、收入、消费金额可以取平均值，但职业、颜色、地区这些分类变量取均值毫无意义——“程序员”和“设计师”的平均是什么？所以说k-means在处理分类数据时，本质是在用一个错误的数据模型做推理。
k-modes的做法是三个替换。第一，用众数（mode）替换均值作为簇中心，每个簇中心由每个字段上出现频率最高的类别构成。第二，用汉明距离替换欧氏距离：两个样本在每个维度上相同记0、不同记1，加起来就是距离。第三，更新簇中心时，每个字段选择出现次数最多的类别作为新的众数。这三步替换以后，整个迭代框架跟k-means完全一致，只是换了一套适合离散数据的度量方式。
k-prototypes则是为了解决更实际的混合数据场景：比如一个客群数据里既有年龄这种数值字段，又有消费偏好这种分类字段。它把距离函数拆成两段，数值部分用欧氏距离，分类部分用汉明距离，然后通过一个权重系数γ把两者拼在一起。这个γ参数需要人工调节，控制分类字段对整体距离的贡献占比。
2.2 项目整体模块结构
这个项目的代码组织很清晰，核心是三个模块文件：kmodes/kmodes.py存放KMode类的实现，kmodes/kprototypes.py存放KPrototypes类，kmodes/util.py存放公共工具函数比如欧氏距离、汉明距离的计算和随机初始化逻辑。整个项目大概就这么几个文件，没有复杂的依赖树，跑起来非常省心。
接口设计仿照scikit-learn的规范，所以如果用过k-means，上手几乎零成本。标准流程是：先初始化聚类器对象，然后调用fit方法训练，最后从labels_属性拿聚类标签。k-prototypes因为要处理数值和分类混合，训练前得用categorical_features参数指明哪些列是分类字段。
from kmodes.kmodes import KModes import numpy as np data = np.array([ ['A', 'X', 1], ['A', 'Y', 0], ['B', 'X', 1], ['B', 'Y', 0], ['C', 'Z', 2], ]) km = KModes(n_clusters=2, init='Huang', n_init=2, verbose=1) clusters = km.fit_predict(data) print(km.cluster_centroids_) print(clusters)这段代码演示了最基础的使用方式：导入KModes，准备一个全是字符串的二维数组，然后指定聚类数量、初始化方式、运行轮数，直接调用fit_predict。km.cluster_centroids_保存每个簇的众数中心，clusters是每个样本的簇标签。后端实际执行的是先随机初始化簇中心，再迭代分配样本、更新中心，直到收敛或达到最大迭代次数。
2.3 初始化方法的差异和选择逻辑
k-modes对初始化比k-means更敏感，因为众数中心比均值中心更容易陷入局部最优。这个项目实现了两种经典初始化策略：Huang方法和Cao方法。Huang方法是先随机选第一个簇中心，然后计算每个样本到已有中心的距离，按距离平方加权的概率（即距离越大被选中的概率越高）选下一个中心，本质是k-means++思路的变体。Cao方法专门考虑到了离群点问题：它是根据频率加权密度来选择初始中心，更偏好那些“能代表大量样本”的点。
实际用下来我的血泪经验是：数据量不大（几万条）时，直接设n_init=10或更大，让多次随机初始化的最好结果生效。默认n_init=1会很不稳，同一份数据两次运行结果可能差别很大。项目在初始化时会调用compute_dissimilarity_matrix去计算样本间距离矩阵，这个矩阵的规模是n_samples乘以n_clusters，如果样本量上了百万，内存开销就很感人。
cost = 0.0 for i in range(n_clusters): idx = np.where(labels == i)[0] if len(idx) == 0: continue dist = dissimilarity_func(X[idx], centroids[i], diss_matrix) cost += np.sum(dist)上面这段是核心迭代里计算cost的片段，每次分配完样本后会统计每个簇内所有样本到中心的距离总和，用来衡量当前聚类的紧凑程度。dissimilarity_func是传入的距离函数，在KModes里是汉明距离，在KPrototypes里就是混合距离。如果某个簇没有分配到样本（执行中常见），会直接跳过，避免除零错误，然后在后续步骤里重新初始化这个空簇。
3. 核心模块逐个突破：距离计算、中心更新和批量分配的内部实现
3.1 汉明距离和众数更新的实现细节
汉明距离的实现很直接，但有几个工程化细节值得注意。第一是向量化：不能用双重循环逐行逐列比较，要利用NumPy的广播机制做批量计算。具体做法是将测试样本复制成跟数据集相同的形状，然后用不等式比较得到布尔矩阵，最后按行求和。第二是字符串数组的处理：分类数据往往是object类型的NumPy数组，比较起来比纯数值要慢不少，预处理阶段最好把字符串映射成整数编码，能省掉不少不必要的开销。
def categorical_dissim(a, b): return np.sum(a != b, axis=1)这是核心的距离函数：输入a是某个簇中心的单行向量，b是二维数组（跟a比较的样本集合）。a != b利用广播逐元素比较，得到布尔矩阵，然后按行求和。返回的是一个一维数组，每个元素代表该样本与中心的汉明距离，数值越小越相似。这段代码因为用了NumPy底层实现，速度远快于Python层逐行循环。
众数更新的逻辑更微妙。在某次迭代中，拿到一个簇的所有样本后，要逐个字段统计频次，取出现最多的类别作为新中心。工程上常用做法是逐列做np.bincount或pd.Series.mode，但bincount只对非负整数有效，所以必须提前把所有分类转换成整数编码。这也是为什么项目内部建议输入数值编码而不是原始字符串。
3.2 k-prototypes的混合距离函数和γ参数
k-prototypes把样本距离拆成两个分量：数值部分的欧氏距离平方和，加上分类部分的汉明距离乘以权重γ。这个分割思路对应了一个很实在的需求：很多业务数据是数值和分类混杂的，比如ID、年龄、账单金额、设备品牌、用户等级，没法只用k-modes丢掉数值信息，也没法只用k-means凭空处理字符串。
def euclidean_dissim(a, b): return np.sum((a - b) ** 2, axis=1) def mixed_dissim(a, b, categorical_features, gamma=0.5): num_a = a[categorical_features == False] num_b = b[:, categorical_features == False] cat_a = a[categorical_features == True] cat_b = b[:, categorical_features == True] return euclidean_dissim(num_a, num_b) + gamma * categorical_dissim(cat_a, cat_b)这段代码用布尔索引同时分离两类字段，然后分别计算距离再相加。categorical_features是一个布尔数组，True的位置表示分类字段。gamma=0.5是默认权重，代表分类部分贡献的距离占总距离的一半。如果数据里分类字段很多或很重要的业务含义，建议把gamma调大；反之调小。调试gamma是个体力活，没有特别通用的万能值，多数靠领域经验结合聚类质量的肘部法则去试。
这里有一个容易翻车的细节：数值字段和分类字段分开后，两个子矩阵的列数会发生变化。如果不小心把布尔索引用错，报错信息通常是检查行列数不一致，接着就是距离矩阵里面一堆NaN。建议在预处理阶段先对categorical_feature这个参数打log验证，把True/False对应的字段名打印出来，确认没有把数值列标记成分类列。
3.3 执行流程：从初始化到收敛的完整链路
一个典型的训练过程长这样。第一步，解析输入，按categorical_features将数据拆成数值和分类两部分存好。第二步，调用用户指定或默认的初始化方法得到n_clusters个簇中心。第三步，进入主循环：每次迭代对所有样本计算它们跟每个簇中心的距离矩阵，把样本分配到距离最小的簇；然后重新计算每个簇的众数（或混合中心）；再用新的中心重新计算cost，对比上次cost的下降幅度是否小于阈值。
这里还有一个内部优化：所有簇中心会被整理成一个三维数组，第一维是簇序号，第二维是样本字段数，第三维是常数1。这样能避免反复做广播复制时的内存碎片。具体来说，当你要计算全部样本跟全部中心的距离矩阵时，最省内存的方式是保持中心矩阵扁平化，然后在距离函数内部解包成多个临时变量，总内存占用从O(n_samples × n_features × n_clusters)降到了O(n_samples × n_clusters)。
for i in range(n_clusters): index = np.where(labels == i)[0] if len(index) == 0: continue diss = self.dissim(centroids[i], self.X[index], diss_matrix) cost += np.sum(diss)这是主循环里cost统计部分的骨架。self.dissim是绑定好的距离函数，在这里根据算法类型被替换成汉明距离、欧氏距离或者混合距离。每一轮迭代结束后，cost用于判断是否收敛。如果某轮cost下降不明显，或者跟上一轮完全一样，就提前终止循环。多数情况下迭代次数在5到20之间就能稳定下来，但如果init选得太差，有概率在局部最优里来回跳动，cost曲线会反复震荡。
4. 从源码到运行：安装、数据准备和实际跑通的三种方式
4.1 安装环境与依赖检查
这个项目依赖numpy、scipy和scikit-learn。安装方式很简单，直接通过pip安装。如果你没有科学计算环境，强烈建议先从Anaconda装好Python 3.x基础环境，然后一个pip命令装齐依赖：
pip install numpy scipy scikit-learn kmodes装完之后验证一下导入是否正常，避免后面跑代码时才发现版本冲突：
import kmodes from kmodes.kmodes import KModes from kmodes.kprototypes import KPrototypes print(kmodes.__version__)如果看到版本号输出了，说明安装成功。常见的问题集中在依赖库版本不匹配，比如老版本scikit-learn接口变化可能导致兼容性警告，不过对这两个聚类类来说影响不大。真遇到报错就升级相关依赖，或者在干净的虚拟环境里重装一遍。
4.2 真实场景数据跑通：用户行为画像分群
理论讲再多不如直接跑一遍。我拿一套某电商的用户行为数据做示范，共5000条，包含3个分类字段（用户等级、活跃时段、支付习惯）和2个数值字段（月均消费、近30天登录次数）。目标是把这些用户分成5个运营客群。
import pandas as pd import numpy as np from kmodes.kprototypes import KPrototypes df = pd.read_csv('user_behavior.csv') print(df.head()) print(df.dtypes)第一步先加载并检查数据。这里要注意的是pandas读进来之后，分类字段是object类型，数值字段是int或float。做聚类之前一定要确认没有缺失值，因为缺失值会让距离计算直接出错或者得到NaN标签：
df = df.dropna().reset_index(drop=True) cat_cols = ['user_level', 'active_time', 'pay_habit'] num_cols = ['monthly_spend', 'login_count'] cat_idx = [df.columns.get_loc(c) for c in cat_cols] kproto = KPrototypes( n_clusters=5, init='Cao', n_init=5, verbose=2, random_state=42 ) clusters = kproto.fit_predict(df[cat_cols + num_cols].values, categorical=cat_idx) df['cluster'] = clusters print(df.groupby('cluster').size()) print(kproto.cluster_centroids_)这段代码里有几个必须注意的细节。首先categorical参数接受的是列索引列表，不是列名，所以用get_loc把列名转成位置。其次输入给fit_predict的必须是二维数组，不能用DataFrame，需要.values转换。再次init选'Cao'会比'Huang'稳定一些，特别是分类字段较多时。最后random_state固定以后，多次运行结果完全一致，方便复现和调试。
运行完会输出每个簇的样本数量，一般会出现5个明显不等的分群，其中某些小群可能是异常用户或特殊偏好群体。cluster_centroids_里能直接看到每个簇的众数中心，比如某个簇的“活跃时段”集中在“夜间”，“支付习惯”是“货到付款”，这个画像直接能转化成运营策略。实际分析中，我们拿这套参数跑完，五个客群的业务特征非常清晰，包括高价值忠诚用户、夜间冲动型、价格敏感型等，直接支撑了后续优惠券策略的差异化配置。
4.3 调参手段：n_clusters、n_init和verbose的实际影响
n_clusters是聚类的核心参数，常见做法是用肘部法则辅助判断：跑多个候选簇数，画出cost随簇数变化的曲线，找拐点。n_init指初始化的随机次数，每次从不同起点跑完整收敛，最后取cost最小的结果。官方默认n_init是1，但分类数据的局部最优问题严重，所以翻车风险大。我一般是设5到10，样本量大时用5省时间，小样本用10求稳。
verbose这个参数被很多人忽略，至少设成1能让你看到每次初始化的cost曲线，方便确认迭代是否收敛。如果verbose输出里cost反复横跳，多半是初始化选得不好或者簇数不对。反之，如果cost下降很平滑且快速稳定，说明参数基本合理。还有一个经验：数据量在10万级以上时，把init设成'Huang'比'Cao'省时间，因为Huang的初始化计算更轻量。
5. 避坑指南：分类数据聚类最常见的五个翻车现场
5.1 字符串列没做编码转换导致距离计算失效
现象：聚类结果全是NaN标签，或者每次运行结果不稳定。 原因：距离函数内部用了np.bincount等只接受整数的操作，字符串数组直接传入会报错或产生不可预期的结果。 解决：预处理阶段把所有分类字段映射成整数编码，比如用pandas的factorize或sklearn的OrdinalEncoder。映射后的整数仍然代表分类，不参与数值运算，但底层存储和处理效率会大大提升。数据量大时这一步能显著降内存。
5.2 分类字段没有标记，被当成数值处理
现象：聚类结果跟业务直觉完全不符，比如“支付习惯”这个字段的数值差异主导了整个距离。 原因：fit时忘了传categorical参数，或者传的索引位置与列顺序不匹配。 解决：拿到数据后先打印列名和类型，用get_loc逐个确认索引，再打印categorical_true对应的列名做二次校验。有一次我就是因为列顺序在中间加工时变了，用了旧的索引列表，结果聚类全乱了。
5.3 缺失值未清理导致训练失败
现象：fit时直接抛异常，或者labels_里出现负数。 原因：样本里有NaN值时，距离计算会传染整个距离矩阵，导致分配不到任何簇。 解决：在进入fit_predict之前用dropna清理整行，或者用fillna填充业务含义明确的占位值。对于分类字段，可以填充“UNKNOWN”作为独立类别；对于数值字段，用中位数填充比均值更不怕离群点。
5.4 过度依赖默认初始化得到垃圾簇
现象：同一份数据跑两次结果完全不一样，而且差异大到业务无法采纳。 原因：n_init默认是1，随机初始化碰到局部最优的概率很高，尤其在分类字段较多、数据分布不均衡时。 解决：把n_init设成5到10，同时固定random_state。这样最终cost会明显低于单次随机初始化的结果，忠于多起点择优的原则。固定随机种子后，同一份代码能稳定复现结果，这是做数据分析的基本素养。
5.5 将纯距离值当成相似度百分比解读
现象：业务同事问“这两个用户相似度是80%吗”，而实际汉明距离值是3，无法直接换算。 原因：汉明距离只是在统计“有几个字段不一致”，没有归一化到0到1的相似度概念。 解决：如果非要解读，可以用“1 - 平均汉明距离/字段数”做近似处理，但这只适用于同样字段长度的数据，跨数据集对比毫无意义。我一般直接拿距离排序做定性比较：距离小代表更接近某个簇中心，而不是用百分比交流。
6. 二次开发思路：给kmodes加上业务友好的增量聚类能力
如果你用这个库做了一段时间后开始嫌它“笨重”——每次全量数据都要重新训练，新增几千条样本得重跑全部数据，这在大数据场景里确实不方便。我当时的做法是给KMode类加了一个增量式的update方法，让旧模型学到的新样本能快速回归，并且在每个簇中心不变的前提下更新众数计数。
def incremental_update(self, new_X, labels_new=None): from scipy.stats import mode if labels_new is None: labels_new = self.predict(new_X) for i in range(self.n_clusters): idx = np.where(labels_new == i)[0] if len(idx) == 0: continue cluster_data = np.vstack([self.X[self.labels_ == i], new_X[idx]]) new_centroid = np.empty(self.n_features, dtype=object) for f in range(self.n_features): new_centroid[f] = mode(cluster_data[:, f])[0][0] self.cluster_centroids_[i] = new_centroid self.X = np.vstack([self.X, new_X]) self.labels_ = np.concatenate([self.labels_, labels_new]) return self这个方法的核心是直接把新样本归到最近的旧簇中心，然后利用众数性质增量更新中心。它没有做全局重算，但胜在速度快，适合流式场景的初步聚类。验证方法也很简单：拿一批新数据分别跑这个增量方法和全量fit，比对两个结果里样本标签分布的变化情况，看中心偏移是否在可接受范围内。
另一个常用的改造方向是把距离计算替换成其他离散度量，比如带权重的汉明距离。当前实现里每个字段的权重是均等的，但实际业务中“用户等级”和“支付习惯”的区分力度显然不同。你可以复制一个dissimilarity函数，让不同字段乘以不同权重，然后作为参数传入KModes。这种局部改动不会触碰内部迭代的逻辑，比自己重写一个聚类器划算得多。
还有一点值得留意：分类数据聚类之后，别急着把结果直接当“客户分群”，建议每个簇都做一个“画像报告”。我这边一直维护着一套可视化脚本，每跑完一次聚簇就把cluster_centroids_导成表格，按频次高低标注每个字段的代表类别，再配上业务同事能看懂的说明文案。从那以后，我每次做KMode项目都强制走一遍这个流程——先做字段预检，再调初始化和簇数，最终输出画像解读报告。希望这些踩坑记录和改造思路帮到你，少走几趟弯路。
本文还有配套的精品资源，点击获取
