简介一套基于朴素贝叶斯算法的垃圾邮件过滤Python项目面向计算机科学与信息安全、数据科学、人工智能等相关专业学生、教师及企业开发者兼顾课程设计、毕业设计与机器学习入门拓展。压缩包共407个文件核心包含20个Python脚本、说明文档与配置文本另有大量分主题邮件样本用于训练及测试整体约995KB结构清晰、轻量易用。目前已有481人学习下载适合希望快速搭建邮件过滤原型的开发者参考。项目完整覆盖训练、测试与评估流程可先选择训练集训练随后查看精确度控制台会逐封显示判断过程并支持自定义或使用内置屏蔽词输入邮件编号即可完成判别如需测试真实邮箱邮件可按说明配置邮箱抓取模块并在相关网站完成设置。同时提供test-ham与test-spam目录便于按不同规模组织正常邮件与垃圾邮件样本操作说明细致能显著减少环境搭建与数据准备时间。1. 这个标题做的是什么一套能跑、能讲、能答辩的邮件过滤项目打开这份「Python实现基于朴素贝叶斯的垃圾邮件过滤系统项目源码操作说明(可用于毕设).zip」你拿到的不是一份只能跑通的玩具代码而是一整套「从语料到评估」的完整技术方案。它解决的是这样一个真实需求毕业设计要一个能演示、能讲清原理、能答上老师追问的机器学习项目而垃圾邮件过滤正好是朴素贝叶斯最经典、最容易讲透的落地场景之一。整个项目会围绕英文或中文邮件文本的预处理、词频特征提取、朴素贝叶斯模型训练、预测与指标评估来展开让你从零搭出一个分类准确率基本可用的过滤系统。这套方案适合两类人。一类是正在做毕设、需要快速理解代码并且能在答辩里讲明白的学生另一类是刚学完Python和机器学习基础、想找一个完整项目练手的开发者。如果你只是想收藏源码当「后悔药」那这篇文章帮不了你如果你想弄懂每一步为什么这么写、参数为什么这么设、坑在哪那这份操作说明式的拆解就是照着做的底气。2. 朴素贝叶斯为什么是垃圾邮件过滤的默认选择多项式模型与拉普拉斯平滑2.1 贝叶斯公式在邮件分类里的实际含义垃圾邮件过滤本质是一个二分类问题给定一封邮件的文本内容判断它属于「正常邮件」ham还是「垃圾邮件」spam。朴素贝叶斯模型做这件事时用的就是贝叶斯公式P(类别 | 邮件内容) P(邮件内容 | 类别) × P(类别) / P(邮件内容)把这个公式翻译成工程语言我们需要计算「这封邮件在垃圾邮件类别下的似然概率」和「在正常邮件类别下的似然概率」再乘上先验概率 P(垃圾邮件) 和 P(正常邮件)最后比较两个后验概率的大小哪边大就分到哪边。先验概率 P(类别) 是训练集里两类邮件的占比比如你的语料中垃圾邮件占 35%那 P(spam) 0.35。这部分很好算。真正麻烦的是 P(邮件内容 | 类别)因为一封邮件的「内容」是成千上万个词组合出来的序列直接计算整句出现的概率根本不可能——数据太稀疏了训练集里几乎不会出现和测试邮件一模一样的句子。这时候朴素贝叶斯的「朴素」假设就派上用场了它假设邮件里每个词的出现与否是相互独立的。这样一来P(邮件内容 | 类别) 就能拆成每个词在类别下的条件概率的乘积。虽然这个假设在语言场景下严格说是错的——「中奖」和「奖金」明显有关联——但在实际工程里这个简化让计算变得可行而且分类效果出奇地好尤其是文本分类这种特征维度高、噪声大的场景。这也是为什么连一些商业级反垃圾邮件系统里朴素贝叶斯仍然是重要的baseline模型之一。2.2 多项式模型与伯努利模型垃圾邮件场景选哪个有了条件独立的假设下一个问题是「词的概率」怎么定义。这里有两种常见模型伯努利模型只关心「词是否出现」用 0/1 表示特征多项式模型关心「词出现了几次」特征值是该词在邮件中的词频。具体到垃圾邮件过滤行业里几乎默认选多项式模型。原因很直白垃圾邮件太喜欢重复关键词了。「免费」「点击」「0元」这种词在垃圾邮件里往往反复出现一次出现和五次出现的迷惑性完全不同。多项式模型能捕捉到这个强度差异让重复出现的高危词对分类结果的贡献更大。伯努利模型把所有重复都压成 1信息损失明显。在 scikit-learn 里这两个模型分别对应MultinomialNB和BernoulliNB。做毕设的话你直接用MultinomialNB就好。它的假设是每个特征词的出现次数服从多项式分布配合CountVectorizer输出的词频矩阵整个链路在数学上是对齐的。还有一点值得在答辩时主动讲出来文本分类还有个常见选择是 TF-IDF 特征配合「多项式朴素贝叶斯」。TF-IDF 会给常见的停用词降权给稀有词提权在长文本上往往比纯词频表现好。但垃圾邮件通常比较短词频信息已经够用而且 TF-IDF 的特征空间会更稀疏贝叶斯模型的概率估计不容易稳定。所以作为毕设项目先用词频把主线跑通再把 TF-IDF 作为「改进方向」写进论文里反而是更聪明的做法。2.3 拉普拉斯平滑到底在防什么多项式模型计算 P(词 | 类别) 的方式是该词在类别下所有邮件中出现的总次数除以该类别下所有词的总出现次数。听起来合理但有个致命问题如果某个词只在正常邮件里出现过在垃圾邮件里一次都没出现那 P(词 | spam) 就是 0。多个这样的词乘起来整封邮件的 P(邮件 | spam) 会变成 0哪怕其他词强烈暗示这是垃圾邮件。这就是「数据稀疏」带来的零概率问题。解法就是拉普拉斯平滑也叫加 1 平滑在分子上加 α分母上加上 α × 词表大小保证所有词的条件概率都大于 0并且总和仍然等于 1。在MultinomialNB里这个 α 就是alpha参数。默认是 1.0也就是标准的加一平滑。做毕设时不用做太复杂的调参alpha1.0起步如果发现测试集上概率分布过于极端比如后验概率接近 1 或 0可以试着调到 0.5 或 2.0 看变化。这个参数的调节过程本身就能写进答辩的「实验分析」里导师看到你不会只会默认参数印象分会好不少。3. 先把环境与数据集备好Python、sklearn 与邮件语料的最小准备3.1 Python 运行环境与依赖库安装这个项目对硬件没有要求普通笔记本就能跑。Python 版本建议 3.8 以上社区里大多数兼容性问题在 3.8 都已经解决。先确认你机器上的 Python 环境终端执行python --version pip --version如果还没装 Python去官网下载对应系统的安装包安装时勾选「Add Python to PATH」这是 Windows 上最容易被忽略的一步。装完后再做一次版本检查能正常输出版本号说明 PATH 配置没问题。接下来创建独立虚拟环境避免把系统 Python 搞乱。我一般这样做mkdir spam-filter cd spam-filter python -m venv venv source venv/bin/activate # Windows 是 venv\Scripts\activate pip install scikit-learn jieba joblib这里三个依赖库各有分工scikit-learn提供朴素贝叶斯分类器、特征提取和评估函数jieba用于中文邮件分词joblib用来保存和加载训练好的模型。英文邮件的话jieba可以不用装用 scikit-learn 自带的CountVectorizer默认分词规则就能处理。需要注意joblib是独立于 scikit-learn 的库很多初学会漏装到这一步训练时报ModuleNotFoundError: No module named joblib其实就一条pip install joblib的事。装上以后建议顺手敲一句确认版本python -c import sklearn, joblib, jieba; print(sklearn.__version__, joblib.__version__, jieba.__version__)能打印出版本号环境就绪。后面所有代码都在这个虚拟环境里跑避免和系统 Python 的包互相污染。3.2 语料准备目录结构、样本组织与训练测试划分环境只是壳真正决定过滤系统效果的是数据。毕设项目一般不用爬全网数据用公开的邮件数据集或者自己标注小批量邮件都行。常见的做法是建这样的目录结构spam-filter/ ├── data/ │ ├── ham/ # 正常邮件每封一个 txt │ ├── spam/ # 垃圾邮件每封一个 txt │ ├── train/ # 切分后的训练集脚本生成 │ └── test/ # 切分后的测试集脚本生成 ├── app/ │ ├── preprocess.py # 文本预处理 │ ├── train.py # 训练脚本 │ ├── predict.py # 预测接口 │ └── evaluate.py # 评估指标 └── models/ # 保存的模型文件每个 txt 文件就是一封邮件的纯文本正文。文件名不用讲究但建议前缀区分类别比如ham_001.txt、spam_023.txt。数据规模上毕设场景 2000 封以上比较稳妥最少也不能低于几百封否则模型会把噪声学进去。准备好语料后用train_test_split按 7:3 或 8:2 划分训练集和测试集。这里有个原则切分时要按邮件文件为单位不能在邮件内部切。单个类别的邮件先打乱再分保证训练集和测试集都能同时覆盖两类。直接手动复制粘贴容易让分布失真写个脚本更可靠。# split_data.py import os import random import shutil def split_data(source_ham_dir, source_spam_dir, train_dir, test_dir, test_ratio0.3, seed42): random.seed(seed) for src, dst_base in [(source_ham_dir, ham), (source_spam_dir, spam)]: files [f for f in os.listdir(src) if f.endswith(.txt)] random.shuffle(files) split_idx int(len(files) * (1 - test_ratio)) for i, fname in enumerate(files): target os.path.join(train_dir if i split_idx else test_dir, dst_base) os.makedirs(target, exist_okTrue) shutil.copy(os.path.join(src, fname), os.path.join(target, fname))这段代码的核心逻辑是先把文件名列表洗牌再按比例切出split_idx前 70% 进训练集后 30% 进测试集。seed42保证每次运行结果可复现——这一点在毕设里很加分答辩时可以说「固定随机种子确保了实验的可对比性」。测试集占比用 0.3 是经验值如果你的语料总数偏少可以改成 0.2 留更多数据训练。3.3 文本预处理英文小写化与中文分词邮件文本不像新闻稿那么规整带 HTML 标签、URL、数字、大小写混写。预处理做不好后面特征提取就全是噪声。英文邮件的常见做法是import re def clean_text(text): text text.lower() text re.sub(rhttp\S|www\.\S, , text) # 去掉URL text re.sub(r[^], , text) # 去掉HTML标签 text re.sub(r[^a-z\s], , text) # 只保留字母和空格 return re.sub(r\s, , text).strip()这里走了四步统一小写消除大小写干扰去掉 URL 和 HTML 标签这两类和正文语义无关的结构噪声把非字母字符替换成空格最后压缩连续空格。注意第 3 步的正则[^a-z\s]会把数字、标点全部剔除因为词频统计里这些符号没有判别力反而会污染特征维度。中文邮件则走另一条链路。中文没有天然的空格分词需要引入jiebaimport jieba def clean_cn_text(text): text re.sub(r[^], , text) text re.sub(r[^\u4e00-\u9fa5\s], , text) # 只保留中文字符 words jieba.cut(text) return .join([w for w in words if len(w.strip()) 0])jieba.cut默认返回一个生成器 .join(...)把分词结果拼成空格分隔的字符串方便下一步CountVectorizer直接消费。这里有个关键点分词后再过滤掉停用词。像「的」「了」「我」「是」这类无差别高频词无论哪类邮件都会大量出现它们会把词频矩阵的维度撑大却不贡献分类信息。停用词表可以自己维护一个简单列表stop_words set([的, 了, 是, 我, 你, 他, 在, 有, 和, 就, 不, 人, 都, 一, 一个, 上, 也, 很, 到, 说]) def remove_stopwords(word_list): return [w for w in word_list if w not in stop_words]英文可以用CountVectorizer的stop_wordsenglish参数直接去掉常见英文停用词省事且效果够用。预处理这块是「黑匣子」最容易藏 bug 的地方——训练脚本和预测脚本必须共用一个预处理函数否则训练时看到的是分词后的文本预测时却喂了原始文本特征就完全对不上了。4. 核心代码实现从词频向量到分类器的完整训练流程4.1 特征提取CountVectorizer 的参数设置与中文分词接入CountVectorizer是 scikit-learn 里做词频统计的标准工具。它会读入一批文本统计每个词的词频输出一个稀疏矩阵行是邮件样本列是词表里的词值是词频。它的几个关键参数直接决定特征空间长什么样。# app/build_features.py from sklearn.feature_extraction.text import CountVectorizer import jieba # 针对中文邮件自定义分词器 def jieba_tokenizer(text): return jieba.lcut(text) vectorizer CountVectorizer( tokenizerjieba_tokenizer, # 中文必须自定义英文可省略 stop_wordsNone, # 停用词在预处理阶段已过滤 max_features5000, # 只保留词频最高的5000个词 min_df2, # 至少在2封邮件中出现过 ngram_range(1, 2) # 单个词 相邻双词组合 )max_features5000是控制特征维度上限的开关。中文邮件词表动辄上万甚至几万如果全部纳入特征矩阵会非常稀疏训练时间和内存都会涨而且很多低频词就是噪声。限定 5000 个高频词模型更稳、训练更快。min_df2进一步剔除只在极少数邮件里出现一次的生僻词。ngram_range(1, 2)是让特征里包含「中奖」这种双词组合因为单个「中」很中性但「中奖」就高度可疑了——这对垃圾邮件识别非常有效。英文场景则简单得多不需要自定义分词器直接把原始文本拆词# 英文邮件版 vectorizer_en CountVectorizer( max_features5000, min_df2, stop_wordsenglish, ngram_range(1, 2) )CountVectorizer默认的 token 规则是按空格和标点拆词英文本身就带空格这个规则够用。tokenizer参数只在中文场景必须覆盖。还要留意stop_wordsenglish里内置的停用词表有限如果发现垃圾邮件里某些高频干扰词没被滤掉可以在实例化时传入自定义表stop_wordslist(my_stop_words)。4.2 训练脚本训练集拟合、参数释义与模型持久化特征提取器准备好后训练本身只分三步读语料、转向量、喂给朴素贝叶斯。# app/train.py import os import joblib from sklearn.naive_bayes import MultinomialNB from sklearn.model_selection import train_test_split from sklearn.feature_extraction.text import CountVectorizer from build_features import jieba_tokenizer def load_corpus(folder, label): texts, labels [], [] for fname in os.listdir(folder): if not fname.endswith(.txt): continue with open(os.path.join(folder, fname), r, encodingutf-8) as f: texts.append(f.read()) labels.append(label) return texts, labels ham_texts, ham_labels load_corpus(data/train/ham, 0) spam_texts, spam_labels load_corpus(data/train/spam, 1) X_texts ham_texts spam_texts y ham_labels spam_labels # 再做一次训练/测试切分用具体化参数保证复现性 X_train, X_test, y_train, y_test train_test_split( X_texts, y, test_size0.2, random_state42, stratifyy ) vectorizer CountVectorizer( tokenizerjieba_tokenizer, max_features5000, min_df2, ngram_range(1, 2) ) X_train_vec vectorizer.fit_transform(X_train) X_test_vec vectorizer.transform(X_test) clf MultinomialNB(alpha1.0, fit_priorTrue) clf.fit(X_train_vec, y_train) joblib.dump(vectorizer, models/vectorizer.joblib) joblib.dump(clf, models/classifier.joblib)拆开讲几个容易忽略的点。stratifyy是切分参数让训练集和测试集里正常邮件与垃圾邮件的占比保持一致。如果不加这个随机切分时可能训练集里垃圾邮件占比偏高、测试集里偏低评估结果就失真了。MultinomialNB(alpha1.0, fit_priorTrue)里fit_prior控制是否从数据中学习先验概率。默认True意味着模型会使用训练集里垃圾邮件的实际占比作为 P(spam)。如果你的语料里两类邮件本来就不平衡保留fit_priorTrue是合理的只有当你事先知道真实场景中垃圾邮件比例明显不同时才需要手动调class_prior。vectorizer.transform(X_test)这里要注意测试集只用transform不用fit_transform。训练时fit_transform已经在拟合词表了测试集再fit一遍就会生成一套全新的词表两个向量维度对不上模型直接报错或乱猜。这是新手常翻车的地方记住「训练 fit测试只 transform」。4.3 预测接口与评估指标不只看准确率要看 F1 与混淆矩阵模型训练完不是终点得有一份能说明效果的评估报告。文本分类项目里准确率Accuracy是最直观的指标但仅靠它是不够的——如果语料里 80% 是正常邮件模型无脑全预测为正常也能拿到 80% 的准确率看起来「不错」但垃圾邮件一封都没拦住系统完全没用。所以核心评估要看精确率Precision、召回率Recall和 F1。精确率回答「被判定为垃圾邮件的邮件里真正是垃圾的比例」召回率回答「所有真正的垃圾邮件里被拦下来的比例」。垃圾邮件场景召回率往往更要紧漏掉一封垃圾邮件比误拦一封正常邮件更不可接受。但也不能走极端正常邮件被大量误拦用户一样会抱怨。所以工程上默认看 F1兼顾两者。# app/evaluate.py from sklearn.metrics import (accuracy_score, precision_score, recall_score, f1_score, confusion_matrix, classification_report) import joblib import os def load_test_data(): texts, labels [], [] for label, folder in [(0, data/test/ham), (1, data/test/spam)]: for fname in os.listdir(folder): if fname.endswith(.txt): with open(os.path.join(folder, fname), encodingutf-8) as f: texts.append(f.read()) labels.append(label) return texts, labels vectorizer joblib.load(models/vectorizer.joblib) clf joblib.load(models/classifier.joblib) X_test, y_test load_test_data() X_test_vec vectorizer.transform(X_test) y_pred clf.predict(X_test_vec) print(准确率:, round(accuracy_score(y_test, y_pred), 4)) print(精确率:, round(precision_score(y_test, y_pred), 4)) print(召回率:, round(recall_score(y_test, y_pred), 4)) print(F1:, round(f1_score(y_test, y_pred), 4)) print(confusion_matrix(y_test, y_pred)) print(classification_report(y_test, y_pred, target_names[正常邮件, 垃圾邮件]))classification_report会直接输出每一类的精确率、召回率、F1 和支持样本数答辩时把这串结果贴上去比只说「准确率 97%」要有说服力得多。混淆矩阵也是必看内容正常情况下绝大多数样本落在矩阵的对角线如果某一类错误特别多说明特征或数据出了问题。需要特别说明毕设里很多人会把「训练集里再划 20% 做测试」和「用整个原始语料切出的独立测试集」混为一谈。上面代码里训练和测试已经分开过一轮了——data/train和data/test预先切好训练脚本只吃 train 目录评估脚本只吃 test 目录。这是最干净的评估方式任何调参都不该碰到 test 集否则模型在测试集上的表现相当于「开卷考试」数据泄露成绩虚高。5. 避坑清单邮件过滤项目里 5 个高频翻车点与排查方法5.1 中文邮件进入 CountVectorizer 后特征全部错乱现象训练出的模型准确率异常低或者预测时报ValueError: dimension mismatch。原因中文没有空格分词CountVectorizer默认按空格和标点把整封邮件当成一个词特征提取完全失效。另一种情况是训练前用了jieba_tokenizer但预测前忘了用同一个 tokenizer两个阶段的词表不一致。解决统一使用自定义 tokenizer并验证输入文本确实被切成了空格分隔的词序列。打印前几封邮件预处理后的内容肉眼确认有分词效果再进模型。排查时可以先跑一小批数据检查vectorizer.get_feature_names_out()里的词是否合理。5.2 准确率很高但垃圾邮件基本全漏召回率极低现象准确率 95% 以上但recall_score只有 0.2 左右大量垃圾邮件漏网。原因语料严重不均衡。比如 1000 封邮件里 900 封正常、100 封垃圾模型学到的最优策略是「全预测正常」因为这样整体错误率最低。这是朴素贝叶斯在类别不均衡数据上的典型表现。解决先看混淆矩阵确认是不是这种情况。然后做两件事一是用class_weightbalanced或手动调整class_prior让模型对少数类更敏感二是评估时不要只看准确率以 F1 或召回率为主要指标。如果两类样本数差太大最直接的办法是收集更多垃圾邮件样本把比例拉到至少 3:1 以内。5.3 alpha 设为 0 后新邮件预测概率直接归零现象MultinomialNB(alpha0.0)时某些邮件预测概率为 0甚至报概率和不为 1 的警告。原因alpha0 等价于关闭平滑训练集中没出现过的词出现在测试邮件里时条件概率为 0乘积直接整体归零。邮件过滤场景里新词几乎必然出现这个设置等于自断后路。解决alpha 至少保留一个极小正值工程上默认 1.0 就不错。想调优可以用 0.1、0.5、1.0、2.0 各跑一遍对比 F1通常差异不会太大。毕设里建议做这个对比实验把结果做成表格是很好的「参数敏感性分析」素材。5.4 用 predict_proba 调整阈值时输出概率异常「自信」现象调用clf.predict_proba(X_test)后几乎所有结果都输出 0.9999 或 0.0001 这种极端概率看起来模型非常自信。原因朴素贝叶斯在特征维度高、条件独立假设下概率乘积的结果天然两极分化。这不算 bug但会导致简单的 0.5 阈值不可靠而且「概率」的绝对值不能当作置信度来解读。解决调整阈值时不要看概率绝对值而是对排序后的概率做五折或十折验证选 F1 最大的阈值点。也可以换成TfidfVectorizer做特征加权概率分布会平滑一些。记住一个经验贝叶斯的概率只能用来排序不能当真实概率用。5.5 训练时用整封邮件正文预测时却带着邮件头或 HTML 标签现象离线评估表现很好但拿到真实邮件一测就失灵准确率断崖式下降。原因训练语料是纯文本正文真实邮件带了 From、Subject、HTML 格式等额外信息。模型训练时没见过这些格式预测时它们变成未登录特征或干扰特征分布完全不一致。解决预处理阶段统一用前面的clean_text函数把 HTML 标签、URL、非字母字符全剔掉。真实场景还应该把主题Subject单独抽出来处理主题里的「RE:」「FWD:」这类前缀是垃圾邮件高频特征但直接混在正文里会增加噪声。毕设里建议在操作说明中写清「本系统处理的是已剥离邮件头与附件的纯文本正文」这既是边界也是答辩时的保护。6. 从毕设到能用的过滤器阈值调节、增量训练与交叉验证做完一个能跑的模型只是起点真正让这个项目从「课程作业」升级为「可演示系统」是最后三个进阶动作。它们不需要改架构只改几个参数和调用方式但能让答辩内容丰富一个量级。第一个动作是阈值调节。clf.predict()默认在垃圾邮件后验概率超过 0.5 时才判为垃圾邮件但实际场景里漏判和误判的代价不一样。少数用户宁可正常邮件被多拦几封也不愿垃圾邮件进收件箱。这时可以绕过predict直接用predict_probaprobs clf.predict_proba(X_test_vec)[:, 1] # 垃圾邮件的后验概率 y_mine (probs 0.4).astype(int) # 自定义阈值例如 0.4这个改动的价值在于你可以拿测试集跑一遍 0.30.6 的阈值扫描画一张「阈值-F1」变化表选最优值写进操作说明。导师问「为什么这个阈值比 0.5 好」你直接回「因为我们更看重召回率阈值调低让更多可疑邮件被拦下」。这句话一出口项目的工程深度立刻不一样。第二个动作是增量训练。真实邮件是源源不断来的重新全量训练一次又慢又浪费计算。MultinomialNB支持partial_fit可以分批次学习新数据model.partial_fit(X_batch, y_batch, classes[0, 1])注意第一次调用必须传classes参数之后可以忽略。这个思路适合当「模型上线后的更新策略」写进毕设论文里比「重新训练」方案更像真实产品。第三个动作是交叉验证。手动切一次训练集/测试集运气成分很大。用cross_val_score做五折交叉验证能更准确估计模型效果from sklearn.model_selection import cross_val_score scores cross_val_score(clf, X_vec, y, cv5, scoringf1) print(scores.mean(), scores.std())cv5表示把数据分五份轮流当测试集最终得到五个 F1 值和标准差。标准差越小说明模型在不同数据切片上表现越稳定。这一步能直接回答答辩必问题「你的模型在不同数据子集上效果稳定吗」做毕设这几年我见过太多项目倒在最后一步模型能跑但阈值是默认的、参数是抄的、评估只报了一个准确率。这几个动作花不了半天但它们把「这是个 demo」变成「这是个方案」。如果你从头把这篇笔记的操作顺序走一遍到交叉验证这一步停一下用自己语料的真实数字补上表格这个项目的完成度已经超出大部分毕设同题水平了。希望帮到你。本文还有配套的精品资源点击获取