简介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-prototypes2.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_clusters2, initHuang, n_init2, verbose1) 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_init10或更大让多次随机初始化的最好结果生效。默认n_init1会很不稳同一份数据两次运行结果可能差别很大。项目在初始化时会调用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, axis1)这是核心的距离函数输入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, axis1) def mixed_dissim(a, b, categorical_features, gamma0.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的位置表示分类字段。gamma0.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(dropTrue) 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_clusters5, initCao, n_init5, verbose2, random_state42 ) clusters kproto.fit_predict(df[cat_cols num_cols].values, categoricalcat_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_newNone): 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, dtypeobject) 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项目都强制走一遍这个流程——先做字段预检再调初始化和簇数最终输出画像解读报告。希望这些踩坑记录和改造思路帮到你少走几趟弯路。本文还有配套的精品资源点击获取