简介：一套基于Python的机器学习算法设计源码包，面向机器学习初学者与算法研究者，集中实现了逻辑回归、支持向量机、K均值、岭回归、反向传播神经网络、均值漂移、密度聚类和矩阵分解等经典算法，覆盖分类、回归、聚类与降维等常见建模任务。这些代码按章节分目录组织，每个算法均配有训练与测试脚本以及对应的数据文件，方便读者对照理解算法内部的工作原理。压缩包共包含五十四个文件，其中三十一个为Python源代码文件，十九个为文本数据说明文件，另有测试数据集、实验数据等，整体体积约三百二十三KB，轻量易用。目前已有三百六十一位学习者学习使用，适合用作课程设计、算法实践或自学入门的参考资料。除了核心算法实现外，还附带结构化的文档说明和多种标准测试数据，能够帮助用户快速验证模型效果，并深入体会不同算法的适用场景与性能特点。无论是想做算法对比实验，还是需要一套可直接运行的代码模板，都能从中受益。
1. 为什么还要自己手写算法？——基于Python的机器学习算法设计源码到底解决什么问题
用Python手写一套机器学习算法设计源码，看似重复造轮子，却是机器学习入门后最值得补的一课。调scikit-learn时你面对的是封装好的fit和predict，一旦换成自定义损失函数，或数据集分布一变，模型输出莫名其妙，你根本不知道断点该打在哪一行。自己设计源码的价值不是“不用sklearn”，而是把线性回归、逻辑回归、决策树的数据流、梯度流向和停止条件全都暴露出来，排查问题时能直接看到最底层在算什么。
这个方向适合三类人：准备算法面试或做课题的，手写一遍后损失函数推导、梯度落地才不发慌；要交付课程设计、毕业设计源码的学生，最看重完整性和可复现性；以及被业务模型异常预测困扰的工程师，降级到源码层做实验往往更快定位问题。全套方案不需要GPU和大数据集，一个Python 3.8+环境加NumPy就能从头跑到尾。
2. 先把算法底座搭好：数据契约、数值梯度与训练循环
2.1 用NumPy把数据契约定下来：标签形状与验证集切分
机器学习算法设计的第一步往往不是写模型，而是定数据格式。这也是很多人项目一开始就翻车的地方：X顺手写成(n_samples, n_features)没问题，y有时候是列向量(n_samples, 1)，有时候是一维(n_samples,)，两种形状在NumPy广播里的语义完全不同，一旦混用，梯度算出来就是错的。
我一般在一开始就定死两条契约：X永远是二维矩阵，行是样本、列是特征；y永远压成一维数组。所有数据预处理、损失函数、梯度计算都基于这个约定写。这样无论是回归还是分类，模型内部不用再散落各种reshape和squeeze。
配套工具函数也要提前写好。常见的做法是自写切分和标准化工具，同时把验证集和测试集的职责分开：调参只用验证集，测试集只能最后碰一次。下面这份是我常用的最小实现，直接复用即可：
import numpy as np def train_test_split(X, y, test_size=0.2, val_size=0.0, seed=42): rng = np.random.default_rng(seed) n = X.shape[0] idx = rng.permutation(n) test_n = int(n * test_size) val_n = int(n * val_size) test_idx = idx[:test_n] val_idx = idx[test_n:test_n + val_n] train_idx = idx[test_n + val_n:] return (X[train_idx], X[val_idx], X[test_idx], y[train_idx], y[val_idx], y[test_idx]) class StandardScaler: """只允许用训练集调用fit，验证集和测试集只调用transform""" def __init__(self): self.mean_ = None self.std_ = None def fit(self, X): self.mean_ = X.mean(axis=0) self.std_ = X.std(axis=0) + 1e-8 return self def transform(self, X): if self.mean_ is None: raise RuntimeError("必须先调用fit") return (X - self.mean_) / self.std_逻辑说明：train_test_split使用default_rng而不是全局np.random.seed，因为构造独立随机数生成器可以避免污染后面梯度下降、K-Means初始化里可能用到的随机状态。切分顺序是先切出测试集，再切验证集，剩下的才是训练集，三个子集的索引完全不重叠。StandardScaler里对std_加了1e-8，是防止某个特征方差为0时除零，属于标准化流程里很值得保留的一个防呆设计。
参数说明：test_size=0.2是小数据集的经验起点，数据集只有几百条时建议提高到0.25到0.3，否则测试集太小，评估方差会大得没法看；seed=42固定是为了让实验可复现，和不同机器学习模型对比时务必锁同一个种子。这里要重点强调一个使用习惯：fit必须只在训练集上调用，验证集和测试集只能transform，均值和标准差不能提前看到后续数据的分布。这一点在后面 4.3 节会作为数据泄露的典型现场再检查一遍。
2.2 损失函数与梯度检查：数值梯度先当唯一裁判
损失函数是算法设计里的第一个核心决定。你选择哪个损失，直接决定了梯度的数学表达式。但解析梯度推导太容易出错：少一项、错一个符号、维度没对齐，损失可能还在下降，模型却已经在学错误的东西。所以我写任何新算法源码的第一步，永远是先用数值梯度当裁判，校验解析梯度是否正确，这是算法设计与分析里最容易被跳过的测试环节。
数值梯度的原理就是导数的定义。为了精度，我一般不写单侧差分，而是用中心差分。它把theta的每个维度分别加减一个eps，计算两点处损失的差除以2 * eps，误差量级是O(eps^2)，比单侧差分的O(eps)高一个量级。
def numerical_gradient(fun, theta, eps=1e-6): grad = np.zeros_like(theta) it = np.nditer(theta, flags=['multi_index']) while not it.finished: idx = it.multi_index t1 = theta.copy() t2 = theta.copy() t1[idx] += eps t2[idx] -= eps grad[idx] = (fun(t1) - fun(t2)) / (2 * eps) it.iternext() return grad def check_gradient(fun, grad_fun, theta, eps=1e-6): ng = numerical_gradient(fun, theta, eps) ag = grad_fun(theta) denom = max(np.linalg.norm(ng) + np.linalg.norm(ag), 1e-12) rel = np.linalg.norm(ng - ag) / denom return rel逻辑说明：numerical_gradient接受一个返回标量损失的函数fun和参数向量theta，逐个维度做中心差分。np.nditer负责遍历参数的所有下标，兼容一维和多维参数。check_gradient用相对误差而不是绝对误差判断，因为绝对误差会随参数取值量级变化，denom加1e-12防止除零。
参数说明：eps取1e-6是精度和浮点舍入的折中，再小到1e-8时中心差分结果会被浮点噪声干扰，反而不准。check_gradient返回值小于1e-6可以认为解析梯度正确；在1e-4到1e-6之间，重点怀疑维度广播有没有对齐；超过1e-4基本就是公式错了，直接重推。注意：如果损失函数里带了正则项，传给fun和grad_fun的必须是同一个含正则项的损失与梯度，否则这一关永远过不了。后面第 3 章里线性回归和逻辑回归的梯度，我都建议先用这套函数测一遍再继续。
2.3 优化器底座：从批量梯度下降到Mini-batch的切换
把优化循环从模型里解耦出来，是让一套源码能复用到多个算法的关键。我习惯的做法是：模型只负责两件事——计算损失和计算梯度；优化器只负责一件事——拿梯度更新参数。这样换算法时不用重写训练循环，也能直接复用学习率衰减、打乱样本这些通用逻辑。
下面是一个最小可用的Mini-batch训练骨架，也可以直接退化成批量梯度下降或随机梯度下降：
def train(model, X, y, lr=0.01, epochs=500, batch_size=32, seed=0, lr_decay=0.995): rng = np.random.default_rng(seed) n = X.shape[0] history = [] for epoch in range(epochs): idx = rng.permutation(n) X_shuf, y_shuf = X[idx], y[idx] for i in range(0, n, batch_size): Xb = X_shuf[i:i + batch_size] yb = y_shuf[i:i + batch_size] grad = model.grad(Xb, yb) model.params -= lr * grad history.append(model.loss(X, y)) lr *= lr_decay return np.array(history)逻辑说明：每个epoch开始先把样本索引打乱，再按batch_size切小批量。为什么必须打乱？因为原始数据很可能按标签或时间排序，不打乱会让连续几个batch过于同质，梯度方向偏斜，收敛变慢。打乱后记录每个epoch结束时的全量损失，便于后面画损失曲线观察训练状态。
参数说明：batch_size=32是一个经验起点，小数据集直接设成n就退化为批量梯度下降，损失曲线平滑但每次更新慢；设成1就是随机梯度下降，每一步噪声大，损失曲线毛刺明显；32是收敛速度和梯度稳定性的折中。lr在0.01附近起步，配合lr_decay=0.995做指数衰减，适合小规模源码项目。如果发现损失曲线先降后剧烈震荡，优先把lr调小一个量级，而不是加epochs。
判断训练是否正常，我习惯看loss曲线最后一段是否平滑下降并趋于平台。锯齿状但整体下行，是batch噪声，正常；曲线中间突然冲高再掉下来，多半是学习率太大冲过了头，或者数据里有离群点把梯度带偏了。这两种曲线形态区分清楚，能省掉大量排错时间。
3. 线性回归到逻辑回归：一份源码模板怎么复用到两类算法
3.1 手写线性回归：闭式解与梯度下降两条路径的取舍
线性回归是最温和的起点，但它在源码层面同时提供两条求解路径，值得都保留。一条是解析的闭式解，直接解最小二乘；另一条是梯度下降，与后面所有算法共用同一套训练循环。两者对同一份数据应该得到基本一致的参数，这就是第一层天然交叉验证。
闭式解版本里有一个大多数人都踩过的细节：不要用np.linalg.inv去求逆，而是用np.linalg.solve解线性方程组。求逆在数值上是不可靠的，尤其当特征间存在多重共线性时，XᵀX接近奇异，inv的结果会剧烈跳动，solve的稳定性好得多。
class LinearRegression: def __init__(self, fit_intercept=True): self.fit_intercept = fit_intercept self.coef_ = None self.intercept_ = 0.0 def _add_bias(self, X): return np.c_[np.ones(X.shape[0]), X] def fit_solve(self, X, y): Xb = self._add_bias(X) w = np.linalg.solve(Xb.T @ Xb, Xb.T @ y) if self.fit_intercept: self.intercept_ = w[0] self.coef_ = w[1:] else: self.coef_ = w return self def fit_gd(self, X, y, lr=0.01, epochs=500): Xb = self._add_bias(X) self.w_ = np.zeros(Xb.shape[1]) n = Xb.shape[0] for _ in range(epochs): grad = 2 * Xb.T @ (Xb @ self.w_ - y) / n self.w_ -= lr * grad if self.fit_intercept: self.intercept_ = self.w_[0] self.coef_ = self.w_[1:] return self def predict(self, X): return X @ self.coef_ + self.intercept_逻辑说明：fit_solve把截距项拼进权重向量，一次性解出全部参数，适合特征维度几千以内的中小规模数据。fit_gd里梯度的来源是MSE对w求导，表达式为2 * Xᵀ(Xw - y) / n，那个除以n是把损失平均到样本上，否则batch一大梯度就成倍放大。两份实现如果结果差异超过0.01，基本可以断定某个环节有问题，先回去查标准化和形状。
参数说明：fit_gd的lr和epochs与2.3节骨架一致。闭式解的复杂度大约是O(nd^2)，特征数超过1万、样本量又大时，矩阵乘法和求逆的代价明显上升，此时梯度下降是更务实的路线。另一个注意点：如果关闭fit_intercept，输入X的第一列不能是常数1，源码里必须保留这个开关，否则用户传入全零特征时结果没法解释。
3.2 逻辑回归源码差异：sigmoid只多三行，坑藏在后面
线性回归和逻辑回归在代码结构上惊人地相似。逻辑回归只是在预测函数外面套了一个sigmoid，损失从MSE换成交叉熵，梯度表达形式上却更简洁。很多初学者觉得逻辑回归就是把线性回归的输出“压到0到1之间”，这个理解本身没错，但如果只在MSE后面加sigmoid，梯度那里一定会出问题。
原因在于：继续用MSE作为损失，梯度里会多出一个sigmoid'(z)因子，收敛极慢，还容易陷入梯度接近0的平台；改用交叉熵后，sigmoid求导的漂亮性质会让梯度化简为Xᵀ(p - y)，干净且数值稳定。这就是机器学习模型设计里“损失函数必须和输出层匹配”的实际含义。
class LogisticRegression: def __init__(self, lr=0.01, epochs=500, batch_size=32): self.lr = lr self.epochs = epochs self.batch_size = batch_size self.w_ = None self.losses_ = [] def _sigmoid(self, z): z = np.clip(z, -500, 500) return 1.0 / (1.0 + np.exp(-z)) def loss(self, X, y): p = self._sigmoid(X @ self.w_) return -np.mean(y * np.log(p + 1e-15) + (1 - y) * np.log(1 - p + 1e-15)) def grad(self, X, y): p = self._sigmoid(X @ self.w_) return X.T @ (p - y) / X.shape[0] def fit(self, X, y): Xb = np.c_[np.ones(X.shape[0]), X] self.w_ = np.zeros(Xb.shape[1]) y = np.asarray(y).reshape(-1) n = Xb.shape[0] rng = np.random.default_rng(0) for epoch in range(self.epochs): idx = rng.permutation(n) for i in range(0, n, self.batch_size): Xb_b = Xb[idx[i:i + self.batch_size]] y_b = y[idx[i:i + self.batch_size]] grad = self.grad(Xb_b, y_b) self.w_ -= self.lr * grad self.losses_.append(self.loss(Xb, y)) return self def predict_proba(self, X): Xb = np.c_[np.ones(X.shape[0]), X] return self._sigmoid(Xb @ self.w_) def predict(self, X, threshold=0.5): return (self.predict_proba(X) >= threshold).astype(int)逻辑说明：fit里先拼接一列1处理截距，再强制把y压成一维，正好呼应2.1节的数据契约。梯度表达式Xᵀ(p - y)和线性回归的Xᵀ(Xw - y)几乎一样，只是预测函数不同，这恰恰说明把模型解耦成“损失+梯度”之后，训练循环和优化逻辑完全通用。
参数说明：_sigmoid里np.clip(z, -500, 500)是防止exp溢出导致NaN，这是sigmoid实现的标准防呆；1e-15加在log里面是防止log(0)，交叉熵实现几乎都要留这一手。predict的threshold=0.5是默认切分点，但如果正负样本不平衡，0.5往往不是最优切分，实际使用时应单独调阈值而不是改模型参数。
3.3 正则化怎么加：L2与L1对梯度回传的差异
正则化是源码进阶绕不开的部分。写过朴素版本之后，下一步几乎必然要加正则化，否则高维稀疏特征下模型很容易过拟合。加正则化的位置有两处：一是在损失函数里加惩罚项，二是在梯度里同步加对应导数。两处必须同时改，漏掉任何一边，梯度检查都会失败。
关键细节是截距项不参与正则化。原因很直观：截距只负责整体平移，不对应任何具体特征，惩罚它会引入与数据无关的偏差。所以下面的代码里正则只作用在w[1:]，w[0]跳过。
def loss_with_reg(self, X, y, reg=0.01, penalty='l2'): p = self._sigmoid(X @ self.w_) base = -np.mean(y * np.log(p + 1e-15) + (1 - y) * np.log(1 - p + 1e-15)) if penalty == 'l2': return base + 0.5 * reg * np.sum(self.w_[1:] ** 2) elif penalty == 'l1': return base + reg * np.sum(np.abs(self.w_[1:])) def grad_with_reg(self, X, y, reg=0.01, penalty='l2'): p = self._sigmoid(X @ self.w_) grad = X.T @ (p - y) / X.shape[0] if penalty == 'l2': grad[1:] += reg * self.w_[1:] elif penalty == 'l1': grad[1:] += reg * np.sign(self.w_[1:]) return grad逻辑说明：L2正则损失里写0.5 * reg * w²，梯度对应reg * w，求导后系数干净，不出现多余的2，推导时省事；L1正则损失是reg * |w|，但它在w=0处不可导，代码里用np.sign(w)作为次梯度替代，这是工程上常见的近似处理，精度足够。
参数说明：reg在小数据集上一般从0.001到0.1之间试。重点提醒：加了正则之后，2.2节数值梯度检查传入的必须是无名函数包装后的loss_with_reg和grad_with_reg，而不是单独传基础损失和基础梯度，否则正则部分的梯度永远不会被校验到。很多人排查半天“为什么加L2之后损失曲线更不平滑”，最后发现是这里错了。
4. 机器学习算法源码的高频翻车点排查：维度、梯度与过拟合
4.1 梯度检查不通过：形状、公式、数值按顺序查
现象：check_gradient返回的相对误差到了1e-2甚至更大，但损失函数看起来在下降，训练也能跑完。
原因拆解：最常见来源按概率排序是维度没对齐、公式少项、数值精度不够。维度问题典型的是y是列向量、X是矩阵，X.T @ (p - y)得到(n_features, 1)而不是(n_features,)，和w_形状不一致，NumPy广播一通操作后看似不报错，但梯度已经错了；公式问题典型的是交叉熵对sigmoid求导时手动展开出错，或者正则项求导忘记乘系数；数值问题则是eps选得过大或过小，中心差分失真。
解决：先打印X.shape、y.shape、w_.shape、grad.shape，确认四者符合(n_samples, n_features)、(n_samples,)、(n_features,)、(n_features,)；再把eps分别试1e-6和1e-7，如果相对误差随eps变化剧烈，说明是数值精度而非公式错误；最后把损失函数和梯度函数分开测试，让w_全为0，手动手算一个样本的梯度，和代码输出对一下。这个顺序走一遍，基本五分钟内能定位。
4.2 损失曲线先降后跌：学习率过大的三个修复手段
现象：训练刚开始loss快速下降，跑几个epoch之后曲线突然冲高，之后反复剧烈震荡，甚至出现NaN。
原因：学习率太大，参数更新步子跨过了损失函数的低谷；或者输入特征没有标准化，某一维特征的数值范围巨大，对应梯度也巨大；或者数据里有极端离群点，单个样本的梯度把参数推向错误方向。
解决：第一步，把lr调小一个量级，通常就能看到损失曲线从“跳水式震荡”变成平滑下降；第二步，给训练加梯度裁剪，把梯度范数限制在一个阈值内，我一般用max_norm=1.0或5.0，这是应对离群点的直接手段；第三步，回到2.1节检查是否对特征做过标准化，没做就先补上。以上三步都无效，再看batch_size是不是太小，噪声过大，调到64或128再试。这里有个血泪经验：源码调试时先怀疑学习率，再怀疑数据，最后才怀疑公式，顺序反了会白搭好几个小时。
4.3 训练集完美、测试集崩盘：数据泄露的检查顺序
现象：训练集上准确率接近100%，一到验证集或测试集就掉到60%以下，而且不管怎么调参都救不回来。
原因：绝大多数情况是数据泄露。最典型的是把StandardScaler的fit调用在了合并后的全量数据上，测试集的均值方差混进了训练预处理中；另一种是调参过程中反复用测试集评估，测试集信息间接影响了模型选择；还有一种是分类任务中切分前没有按标签分层抽样，测试集里某个类别样本极少。
解决：按顺序排查。先检查预处理代码，确保scaler只fit过训练集；再检查切分函数，是否按标签分层，保证训练和测试里类别比例一致；最后检查调参流程，用验证集选超参数，测试集只在最终确认时碰一次。
提示：如果是时间序列数据，随机切分本身就无效。必须改成按时间顺序的前后切分，否则未来的信息一定会泄漏进训练过程，模型在回测里再漂亮，上线也必然翻车。
数据泄露这类问题最讨厌的地方在于代码不报错，损失也在正常下降，只能靠流程约束来预防。所以我会把“测试集只允许碰一次”直接写进项目 README，并在代码里用断言强制检查：测试集用于调参就抛异常。
4.4 决策树过深与K-Means空簇：两个非梯度算法的经典翻车
决策树和K-Means不走梯度下降，它们的常见问题很不一样，但同样高频，值得单独列两个现场。
现场一：决策树在训练集上完美分类，测试集效果差，树很深、叶子节点很多。原因是决策树无约束生长时会把训练数据里的噪声当成规律学进去，属于典型的过拟合。解决：在源码里实现max_depth、min_samples_split、min_samples_leaf三个停止条件，缺一个都会失控。我的经验是max_depth从3开始往上试，min_samples_leaf不小于总样本量的1%，这两个组合比单纯限制深度更稳。
现场二：K-Means跑完之后，某个簇的样本数为0。原因是初始中心点选得太近，或者某个中心点被别的中心点“抢走”了全部样本，收敛后形成空簇。解决：初始化改用k-means++策略，逐个选择离已选中心最远的样本作为新中心；同时迭代里加空簇重随机化逻辑——发现某个簇为空，就重新在全局随机挑一个样本替换它的中心。另外K-Means对K值的选择非常敏感，别当超参随手填，先画肘部图，看损失下降变平缓的拐点，那才是相对合理的K值。
5. 让源码可信的三个进阶验证技巧：对拍、学习曲线与回归测试
5.1 与scikit-learn对拍：把差异控制在可解释范围
手写源码最怕“自己觉得自己对了”。与成熟的scikit-learn实现做对拍，是我验证算法正确性的收尾动作。具体做法是同一份数据、同一超参数，分别跑手写实现和sklearn版本，对比coef_、intercept_和预测结果。
from sklearn.linear_model import LinearRegression as SkLR from sklearn.linear_model import LogisticRegression as SkLogit sk = SkLR().fit(X_train, y_train) mine = LinearRegression().fit_solve(X_train, y_train) print("coef diff:", np.abs(sk.coef_ - mine.coef_).max()) print("intercept diff:", abs(sk.intercept_ - mine.intercept_))逻辑说明：同一个凸问题的最优解是唯一的。线性回归闭式解和sklearn的结果在数值精度内应该一致，差异超过1e-6就要回头查。逻辑回归要注意sklearn默认加了L2正则，且默认solver是lbfgs，与手写梯度下降的收敛精度不同，对拍时要显式设置penalty='none'，否则你会对着“明明是同一个模型”排查半天。
5.2 画一条完整的学习曲线，判断偏差与方差
准确率本身说明不了训练过程是否健康。我习惯把每个epoch的损失画成曲线，同时画训练和验证两条。训练损失持续高于验证损失，是欠拟合，增加模型复杂度或加特征；训练损失低、验证损失高，是过拟合，上正则化或减深度；两条曲线平行且都不降，说明模型容量到了瓶颈。这比只看终点指标更能指导下一轮改法。画学习曲线不需要额外库，用matplotlib两行就行，关键是曲线要保留原始epoch维度的数据，这就是2.3节history数组存在的意义。
5.3 把梯度检查沉淀成回归测试
最后这个习惯我强烈推荐：写完算法后不把梯度检查当一次性脚本，而是沉淀成pytest用例，每次改动代码自动跑一遍。实现方法很直接：模型类里提供loss和grad两个通用接口，测试里固定一份小数据和小参数初始化，断言check_gradient返回值小于1e-6。这样以后重构、加正则、换优化器，一旦梯度公式被破坏，测试立刻变红，而不是等模型上线了才发现效果不对。
def test_logistic_gradient(): model = LogisticRegression() X = np.random.randn(20, 5) y = (np.random.rand(20) > 0.5).astype(int) model.w_ = np.random.randn(6) Xb = np.c_[np.ones(X.shape[0]), X] rel = check_gradient( lambda w: model.loss(Xb, y), lambda w: model.grad(Xb, y), model.w_) assert rel < 1e-6逻辑说明：测试里的固定随机种子保证用例可复现；X只用20个样本、5个特征，梯度计算毫秒级完成；model.w_用随机值而不是全零，是因为全零附近梯度天然更简单，测不出维度错位。这个用例每次运行都会重新验算次梯度、sigmoid防溢出和维度广播，是我目前认为最值得投入的自动化测试之一。
我个人这几年的习惯是：新算法落地前不急着调参，先把梯度检查、与sklearn对拍、回归测试三件事做完，后面所有实验都在这个地基上跑。凡是图省事跳过梯度检查的项目，最后几乎都要花更多时间在更隐蔽的bug上，这个亏我吃过不只一次。希望帮到你。
本文还有配套的精品资源，点击获取
