尧图网页设计 
简介一套面向高校大数据课设与毕设场景的完整项目资源基于Hadoop与Spark实现中文手写数字的实时识别覆盖从特征提取、模型训练到结果可视化的全流程适合计算机相关专业学生或编程爱好者二次开发。压缩包共18个文件以12个Python脚本为核心包含HOG特征计算、RDD与DataFrame两种逻辑回归实现、t-SNE降维绘图等模块另有实验方案PDF、资源说明文本和两段演示录制视频整体仅25.79MB轻量易部署解压后按英文路径放置即可运行。目前已有147人学习下载项目结构清晰附带的视频和文档能帮助快速理解运行步骤即使遇到环境配置问题也可对照说明排查实验报告中的系统架构与参数调优说明以及分模块的Python代码为二次开发或答辩展示提供了扎实参考。1. 大数据课设里最难回答的一个问题这套系统里Hadoop和Spark到底在干嘛每年大数据课设答辩总有人被同一个问题卡住系统叫“实时识别”你的 Hadoop 和 Spark 到底在哪一步起作用这份题为“基于 Hadoop 和 Spark 的中文手写数字实时识别系统”的课设源码包把答案拆得很清楚——HDFS 负责训练样本和模型的存储Spark Streaming 负责消费图像流并做批量推断中文手写数字识别只是验证整条大数据链路的业务载体。压缩包里除了源码还带了演示视频、实验报告和演示录制视频恰好对应答辩要过的三关代码能跑、逻辑能讲、现场不出乱子。适合正在选大数据课设或大数据毕业设计题目、又不想只做词频统计这类“假大数据”的人。2. 先定架构再写代码这套实时识别系统里 Hadoop 和 Spark 分别扛什么活2.1 识别本身单机就能跑为什么课设非要扯上 Hadoop 和 Spark中文手写数字识别本质是一个图像分类问题。一个 CNN 模型在普通笔记本上用 CPU 也能训练单机跑推理更是轻松。那为什么课设要绕一大圈用 Hadoop 和 Spark核心原因是课设的验收标准不是“模型准不准”而是“你有没有用大数据技术栈解决一个完整问题”。如果把一个手写识别模型单独丢出来老师只能问模型本身的问题但当你把它架在 Hadoop 和 Spark 上验收点就变成了数据怎么存储、流怎么接入、计算怎么分布、结果怎么回写。识别模型只是这条链路上的一环它存在的意义是让大数据的每一步都有业务落点。具体分工上我一般会把 HDFS 作为训练样本和模型的存储层原始图片、数据增强后的样本、训练好的 ONNX 模型文件、模型评估日志全部丢到 HDFS 目录下答辩时可以展示hdfs dfs -ls的文件清单证明 Hadoop 不是摆设。Spark 承担两类计算一类是离线的样本统计分析统计各类别样本量、计算均值方差用于归一化另一类是重头戏——Structured Streaming 消费 Kafka 里的图像消息按微批做推理。这样“批”和“流”都在 Spark 上体现出来了。还有一点要提前想清楚Spark MLlib 自带的那套分类器并不适合直接用。MLlib 里没有 CNN只有逻辑回归、决策树这类传统模型用它们直接识别 28×28 的图像准确率很难看而且中文数字这种笔画结构很容易被传统特征工程搞砸。所以模型的训练我用 PyTorch 完成训练完导出 ONNX推理阶段由 Spark 进程加载 ONNX 模型。这相当于把“训练框架”和“推理引擎”解耦Spark 不依赖 PyTorch 环境也能跑识别。2.2 四层架构画板接入、Kafka 缓冲、Spark 流式推断、结果回写整套系统我习惯按四层来组织每一层的职责单一答辩时画拓扑图也好画。接入层是一个 HTML5 Canvas 画板用户在浏览器里用鼠标或触控笔写一个中文数字零、一、二、三……九或阿拉伯数字0-9写完点击提交。前端把画布内容转成 PNG 的 base64 字符串连同 session_id、时间戳一起封装成 JSON通过 WebSocket 发到后端网关。网关这边用 Flask 写一个小服务收下 JSON 后原样投递到 Kafka 的handwrite_in主题。为什么中间非要插一个 Kafka因为 Spark Streaming 直接读 WebSocket 数据很别扭而 Kafka 天然带 offset 管理和消息积压能力也能让“消息队列”这个大数据组件在链路里露脸。传输层就是 Kafka 单节点主题handwrite_in分区数建议 2 到 4。分区太多在课设环境里反而浪费而且演示时如果只有一个画板在写入多分区只会让下游处理更碎。这里要注意Kafka 依赖 ZooKeeper 做协调如果 Hadoop 集群里已经装了 ZooKeeperKafka 直接复用即可不需要单独再维护一套协调服务。计算层是 Spark Structured Streaming。它从 Kafka 拉取 JSON 消息解析出 base64 图片字段在 Executor 里批量解码、归一化、缩放再交给 ONNX Runtime 做推理。输出的是一个包含 session_id、预测类别、置信度、时间戳的 DataFrame。下一层是结果层把推理结果写回 Redis用 session_id 做 key设置 60 秒过期时间前端收到结果后弹出一个“识别为三置信度 0.97”的提示同时后端把同样内容推到 WebSocket 给所有展示大屏刷新。从用户写完数字到页面出现结果整个链路大约是 1 到 3 秒这个延迟符合“流式微批处理”的定位。2.3 环境选型伪分布式、虚拟机集群还是local[*]课设环境怎么搭决定了你后面几周是快乐调代码还是痛苦修环境。我见过太多人一上来就按网上的 Hadoop 集群部署教程整四台虚拟机折腾一周连 NameNode 都没起来最后只能回来用伪分布式。常见的做法是分三个阶段走。第一阶段是本地开发用 Hadoop 伪分布式搭建 HDFS 单节点NameNode、DataNode、SecondaryNameNode 都在本机Spark 跑在local[*]模式Kafka 和 Redis 也全在本机。这个阶段的目标只有一个把端到端链路跑通代码能出结果。伪分布式的好处是 HDFS 的读写逻辑和真实集群完全一致hdfs://路径也能用只是没有多节点冗余而已。网上搜“hadoop 伪分布式搭建”和“spark 的安装与使用”能找到大量教程照着做即可但记得 Hadoop 和 Spark 的版本要匹配否则后面会踩 RPC 协议的坑。第二阶段是答辩演示环境。如果手头有虚拟机资源我建议至少准备三台一台跑 NameNode ResourceManager Kafka ZooKeeper两台跑 DataNode NodeManager。Spark 提交任务时用 YARN 模式这样资源调度由 YARN 管理答辩时能展示 Spark UI 上的 Executor 列表和批次处理时间说服力强很多。但如果你只有一台物理机别硬上集群——单机伪分布式加local[*]也能把演示做完前提是实验报告里写清楚部署策略为什么课设环境用伪分布式生产环境如何扩展到集群。这个解释本身就是加分项。第三阶段是录制演示视频。视频里最好直接录三节点集群的 Spark UI 界面如果环境不稳定至少也要录伪分布式下jps命令的输出证明 Hadoop 各进程都在。别小看这个很多人的演示视频里连jps都没出现过答辩时只能口头说“我有集群”。下面是三种环境选型的对比给还没动手的同学一个参考环境方案适用阶段优点风险单机伪分布式 local[*]开发调试环境简单出问题好排查演示时无法展示集群并行度三节点虚拟机 YARN答辩演示能截 Spark UI、YARN 资源分配图搭建周期长硬件要求高单机 Docker 容器模拟节点过渡方案环境可重装快照方便网络配置复杂容器间通信易出错我自己的做法是开发用伪分布式答辩前一周切到三节点虚拟机拍完演示视频就再也不动环境了。记住一个原则课设的分数来自你能讲清楚架构而不是集群规模有多大。3. 把中文手写数字识别先跑成离线模型数据集、CNN 训练与 ONNX 导出3.1 数据集怎么凑中文大写数字和阿拉伯数字混排类别定 20 类还是 10 类“中文手写数字”这个表述有个容易忽略的细节它到底是指汉字的“一、二、三”还是指阿拉伯数字“1、2、3”如果只识别阿拉伯数字那就变成了 MNIST 中文版体现不出“中文”二字如果只识别汉字数字类别又太少模型太简单。常见的做法是两类都做——模型同时输出 0 到 9 的阿拉伯数字和中文字符形成 20 个类别然后在后处理阶段把“3”和“三”、“2”和“二”映射成同一个语义结果。数据集方面CASIA-HWDB 是完整的中文手写数据集规模太大、下载和处理成本高课设周期紧张时没必要全量使用。更务实的路线是找现成的中文数字手写子集或者自己组织 50 到 100 人书写、扫描后按字符切分凑出每个类别 300 到 500 张图。20 个类别加起来 6000 到 10000 张已经足够训练一个高准确率的 CNN。图像统一转成灰度 28×28这一步和 MNIST 的预处理方式一致后续代码写起来最顺手。还要注意类别不平衡的问题。很多人收集数据时会把“一”“二”“三”这种好写的字多写几遍“零”“六”“九”这种笔画结构复杂的写少了导致模型对复杂字符欠拟合。我的做法是训练前先统计各类别样本量用np.bincount看一眼分布少于平均数的类别做额外增强随机旋转 ±15 度、平移 ±2 像素、加高斯噪声。数据增强这步不能省尤其是手写笔画轻重不同导致的灰度差异归一化时要用整个数据集的均值和方差而不是简单除以 255。3.2 PyTorch 训练一个能用的 CNNLeNet 变体、Adam 和 6 个 epoch训练脚本我用 PyTorch 写模型结构上用 LeNet 的变体而不是更深的 ResNet。原因很简单输入只有 28×28样本量几千张太深的网络容易过拟合而且训练时间会拖慢整个课设节奏。一个两轮卷积加两轮池化、最后接两个全连接层的网络已经能在这场任务上拿到 98% 以上的准确率。下面是一个最小可运行的训练脚本核心结构可以直接抄import torch import torch.nn as nn from torch.utils.data import DataLoader from torchvision import datasets, transforms class HandwriteCNN(nn.Module): def __init__(self, num_classes20): super().__init__() self.features nn.Sequential( nn.Conv2d(1, 32, 3, padding1), nn.BatchNorm2d(32), nn.ReLU(inplaceTrue), nn.MaxPool2d(2), nn.Conv2d(32, 64, 3, padding1), nn.BatchNorm2d(64), nn.ReLU(inplaceTrue), nn.MaxPool2d(2), ) self.classifier nn.Sequential( nn.Flatten(), nn.Linear(64 * 7 * 7, 128), nn.Dropout(0.3), nn.ReLU(inplaceTrue), nn.Linear(128, num_classes) ) def forward(self, x): return self.classifier(self.features(x)) transform transforms.Compose([ transforms.Resize((32, 32)), transforms.CenterCrop(28), transforms.ToTensor(), transforms.Normalize((0.5,), (0.5,)), ]) train_loader DataLoader(train_dataset, batch_size64, shuffleTrue) model HandwriteCNN(num_classes20) optimizer torch.optim.Adam(model.parameters(), lr1e-3) loss_fn nn.CrossEntropyLoss() for epoch in range(6): for images, labels in train_loader: optimizer.zero_grad() outputs model(images) loss loss_fn(outputs, labels) loss.backward() optimizer.step() print(fepoch {epoch 1} finished)这段代码里的几个参数值得说清楚。batch_size64对 CPU 训练比较友好太大内存压力高太小梯度抖动厉害。lr1e-3配合 Adam 是默认稳妥组合如果 loss 下降很慢可以改成余弦退火。Dropout(0.3)加在全连接层前面专门防过拟合——样本量只有几千张时不加 Dropout 的训到后期训练集准确率 100%、验证集却往下掉。num_classes20对应前面说的阿拉伯数字和中文数字混排方案如果你只做中文数字就改成 10但后处理逻辑也要跟着改。训练到第 6 个 epoch 左右验证集准确率通常会收敛。不要盲目加 epoch超过 10 轮后过拟合明显实验报告里可以放一张训练曲线说明这个现象。如果你发现收敛后准确率还不到 95%优先检查数据集而不是网络结构看看是不是某些类别的样本数太少或者图像在 Resize 和 CenterCrop 时把笔画截掉了。3.3 导出 ONNX 模型给 Spark 留一个不依赖训练框架的推理接口训练完成后模型要交给 Spark 用。Spark 的 Executor 里不可能跑 PyTorch所以需要把 PyTorch 模型导出成 ONNX 格式。ONNX Runtime 的 Python 包体积小、依赖干净可以被打进 Spark 的 Python 环境里。导出代码很简单model.eval() dummy_input torch.randn(1, 1, 28, 28) torch.onnx.export( model, dummy_input, handwrite.onnx, input_names[input], output_names[output], dynamic_axes{input: {0: batch}, output: {0: batch}}, opset_version11 )dynamic_axes这一行很重要。它告诉 ONNX 导出器输入和输出的第 0 维batch 维是动态的这样 Spark 那边一次推一张还是推 100 张都能用同一个模型文件。如果不加这个参数ONNX 会固化输入形状为[1,1,28,28]批量推理时反而要重复构造模型。导出后本地先校验一遍用onnxruntime加载模型拿一张训练集的图片跑一次推理确认输入输出名称和形状和预期一致。这一步能避免后面 Spark 端模型加载失败的问题——很多时候不是 Spark 配错了而是 ONNX 文件本身有问题。3.4 在本地先验证模型混淆矩阵和置信度阈值模型导出前先用验证集算一次混淆矩阵。这一步的目的不是看总体准确率而是看哪些类别互相混淆“三”和“3”、“二”和“2”是常见的混淆对“零”和“六”因为笔画都有交叉结构也容易混。有了混淆矩阵就能定置信度阈值。我一般把阈值设在 0.8低于这个值的结果标记为“不确定”而不是硬给一个类别。这样做的好处有两个一是演示时遇到书写潦草的字不会输出离谱答案二是实验报告里可以写“系统具备不确定性感知能力”这是非常简单但老师爱听的加分点。另外本地验证时要固定一张测试图记录它的预测结果和耗时。这张图以后要用于演示视频的离线回放不能让演示时的测试样例和实验报告的截图对不上。4. 实时识别链路搭建Spark Structured Streaming 消费 Kafka 图像流4.1 实时不等于毫秒级Structured Streaming 的微批和 Trigger 先对齐预期很多同学一听到“实时识别”就往毫秒级响应上想结果把系统做得很复杂最后延迟反而降不下来。这里要先对齐预期Spark Structured Streaming 是微批模型不是逐条处理模型。你画一个数字提交后图片先进 KafkaSpark 每隔一段时间Trigger 间隔拉取一批消息统一做解码和推理。所以端到端延迟最少也是一个 Trigger 间隔加上推理时间。我一般把 Trigger 设为 3 秒。如果设成 0尽可能快Spark 会拼命以最小批次拉数据在课设场景下前端只有一个人在画批次里经常只有一条消息批处理开销序列化、任务调度、结果回写远大于推理本身延迟反而更高。设成 3 秒前端提交后最多等 3 秒就能进下一个批次配合推理和回写整体延迟控制在 3 到 5 秒内。这个数字在答辩时直接说“我是微批流处理秒级响应”不会有任何问题。还要注意的是 checkpoint 目录。Structured Streaming 必须指定 checkpoint 位置否则启动直接报错。课设里把 checkpoint 放在 HDFS 的/spark/checkpoint下既能体现 Hadoop 的参与又能保证重启后不重复消费 Kafka 消息。如果你用的是伪分布式记得hdfs dfs -mkdir -p /spark/checkpoint提前建好目录否则权限问题足够让你排查半小时。4.2 Spark 消费 Kafka 的最小代码base64 解码、预处理、批量预测下面这段代码是整条链路的核心直接放在 Spark 作业里跑。用 PySpark 的mapInPandas做批量推断每个批次的数据以 Pandas DataFrame 形式传入 Python 函数在函数里统一加载 ONNX 模型并推理。from pyspark.sql import SparkSession from pyspark.sql.types import (StructType, StructField, StringType, IntegerType, FloatType) from pyspark.sql.functions import from_json, col import io import base64 import numpy as np import cv2 import onnxruntime as ort _ort_session None def get_session(): global _ort_session if _ort_session is None: _ort_session ort.InferenceSession( /models/handwrite.onnx, providers[CPUExecutionProvider] ) return _ort_session def predict_batch(pdf): session get_session() images [] for _, row in pdf.iterrows(): raw base64.b64decode(row[image_base64]) img cv2.imdecode(np.frombuffer(raw, dtypenp.uint8), cv2.IMREAD_GRAYSCALE) img cv2.resize(img, (28, 28)) img img.astype(np.float32) / 255.0 img (img - 0.5) / 0.5 images.append(img) inputs np.stack(images).reshape(-1, 1, 28, 28) outputs session.run([output], {input: inputs})[0] pdf[pred] outputs.argmax(axis1) pdf[conf] outputs.max(axis1).astype(float) return pdf[[session_id, pred, conf, ts]] schema StructType([ StructField(session_id, StringType()), StructField(image_base64, StringType()), StructField(ts, StringType()), ]) result_schema StructType([ StructField(session_id, StringType()), StructField(pred, IntegerType()), StructField(conf, FloatType()), StructField(ts, StringType()), ]) spark SparkSession.builder \ .appName(ChineseHandwriteRealTimeOCR) \ .master(local[*]) \ .config(spark.sql.shuffle.partitions, 4) \ .getOrCreate() raw spark.readStream \ .format(kafka) \ .option(kafka.bootstrap.servers, localhost:9092) \ .option(subscribe, handwrite_in) \ .option(maxOffsetsPerTrigger, 200) \ .load() parsed raw.select( from_json(col(value).cast(string), schema).alias(msg) ).select(msg.*) results parsed.mapInPandas(predict_batch, result_schema) query results.writeStream \ .outputMode(append) \ .format(console) \ .option(truncate, false) \ .trigger(processingTime3 seconds) \ .option(checkpointLocation, hdfs://localhost:9000/spark/checkpoint) \ .start() query.awaitTermination()这段代码有两个关键设计。第一get_session用了模块级全局变量缓存 ONNX session。mapInPandas会在每个 Executor 的 Python worker 进程里反复调用predict_batch如果不缓存每个批次都重新加载模型推理耗时会被模型加载耗掉大半延迟直接爆炸。第二imdecode解码时用np.frombuffer包一层这是因为 OpenCV 的imdecode需要拿到一个可读的缓冲区直接传 bytes 在某些版本会报错。maxOffsetsPerTrigger设置为 200表示每个 Trigger 最多拉 200 条 Kafka 消息。演示时只有一个画板这个值根本用不满但设置它能防止如果之前积压了大量消息一次性全拉进来导致批次处理时间过长。4.3 结果回写 Redis前端轮询和 WebSocket 推送二选一推理结果出来了怎么送到前端两种常见做法前端轮询 Redis 或后端 WebSocket 推送。课设演示我推荐主用 WebSocket 推送前端代码量少展示效果也更“实时”。在writeStream里可以换成foreachBatch来写 Redisimport redis import json def write_to_redis(batch_df, batch_id): r redis.Redis(hostlocalhost, port6379, db0) for row in batch_df.collect(): key focr:result:{row[session_id]} r.set(key, json.dumps({ pred: int(row[pred]), conf: float(row[conf]), ts: row[ts] }), ex60) query results.writeStream \ .foreachBatch(write_to_redis) \ .option(checkpointLocation, hdfs://localhost:9000/spark/checkpoint/redis) \ .start()ex60表示结果 60 秒后自动过期避免 Redis 里的 key 越积越多演示结束后内存也不会有压力。如果你做的是大屏展示前端每 2 秒调用一次 Redis 的 GET 接口也能接受但轮询带来的延迟感和多余的 HTTP 请求会让答辩观感变差所以我建议按 WebSocket 推送来做。4.4 参数怎么设maxOffsetsPerTrigger、trigger 间隔和 checkpointStructured Streaming 的参数看起来简单实际调起来有几个容易踩坑的地方。下面这张表是我用过比较顺手的配置组合参数推荐值说明trigger processingTime3 seconds微批间隔太短则单批消息少、开销大太长则实时感差maxOffsetsPerTrigger200限制单批最大消息数防止积压导致雪崩spark.sql.shuffle.partitions4开发/ 节点数×2集群默认 200课设数据量下纯浪费调度资源checkpointLocationhdfs://.../checkpoint必须设置否则流启动就报错spark.sql.streaming.schemaInference不使用从 Kafka 读数据写死 schema不需要推断spark.sql.shuffle.partitions这个参数很多人忽略。默认值是 200意味着只要有一次 shuffle就会生成 200 个小任务。课设环境里数据量几千条200 个分区纯粹是增加调度开销本地开发时改成 4 个分区集群演示时改成节点数乘以 2批次处理时间明显下降。另外如果你用的是 YARN 模式别忘了给 Executor 留够内存。ONNX Runtime 加载模型需要一定内存我一般给 Executor 设spark.executor.memory2g太小会频繁 GC 导致批次时间波动。5. 课设排坑记录从 Yarn 卡死到演示视频翻车的 5 个血泪案例5.1 现象Spark 作业提交后一直停在 Yarn RMProxy答辩现场直接尬住这个问题最常见的场景是代码在local[*]下跑得好好的一到三节点集群上用 YARN 模式提交日志就卡在yarn.RMProxy等了十分钟也没有 Container 启动。原因通常是资源没对上。要么是 ResourceManager 所在节点的队列资源被占满要么是spark.executor.memory和spark.yarn.am.memory之和超出了 NodeManager 的单节点可用内存。排查方法很简单看 ResourceManager 的 Web UI找到你的 application点进 Attempts 看诊断信息基本都会写明资源不足的细节。解决先把spark.dynamicAllocation.enabled关掉手动指定num-executors为 2每个 Executor 1GB 内存、一个核这样最小资源需求就能算清楚。另外确认yarn.nodemanager.resource.memory-mb要大于所有 Executor 加上 AM 的总内存。我在课设里吃过一次亏三台虚拟机每台只给了 2GB 内存还跑着 Hadoop 进程Spark 分两个 Executor 后内存直接爆掉后来把 NodeManager 的资源上限调到 3GB 才正常。5.2 现象画完数字要等 8 秒才出结果被老师质疑“这不叫实时”这个坑几乎每个人都踩过。原因一般有两个一是 ONNX session 在每个批次里重复加载二是 Trigger 设成了 0Spark 为了一条消息也要调度一个批次。解决分三步走。首先按前面 4.2 的写法把 session 缓存成模块级全局变量模型加载只做一次然后把 Trigger 从 0 改成 3 秒让消息攒成一批再算最后在mapInPandas里不要用循环逐张推理而是把整批图片堆成[-1, 1, 28, 28]的张量一次喂给 ONNX Runtime。优化后我在伪分布式下的实际延迟稳定在 2 秒出头——一个 Trigger 间隔加推理加回写答辩完全够用。如果你把优化做了还是慢把spark.sql.shuffle.partitions改小试试。默认 200 个分区会在结果回写阶段产生大量小任务每条结果都走一次调度积少成多就是一个严重的延迟来源。5.3 现象“三”和“3”、“二”和“2”互相认错后处理把它救回来一开始我以为这是模型问题加数据增强、调网络结构折腾很久准确率还是卡在 95% 左右错误几乎都集中在中文数字和阿拉伯数字的相似笔画上。后来想明白了模型输出 20 类但“3”和“三”在语义上是同一个数字模型并不需要同时把它们分对只需要在输出层做合并。解决写一个简单的后处理映射把预测类别中阿拉伯数字和对应中文数字归一成一个结果。同时把置信度阈值压到 0.8低于阈值的返回“不确定”。这一处理不仅让演示效果更自然还顺带把“零”和“六”这类容易混淆的类别兜住了——至少不会给出一个言之凿凿的错答案。这个经验也说明一个问题业务层的规则能解决的不要指望模型硬扛。实验报告里写清楚这套后处理逻辑比单纯堆准确率数字有说服力得多。5.4 现象Spark 读 Kafka 报 OffsetOutOfRange 和 Session 超时的“玄学”问题明明代码没动第二天启动作业就报OffsetOutOfRangeException或者消费者一直卡在JoinGroup超时。这类问题乍看很玄学其实大部分是 Kafka 侧的事。第一个常见原因是 Kafka 的消息保留时间太短。课设环境里 Kafka 默认 retention 通常是一周或更短如果你前一天测试往里灌了消息第二天 checkpoint 记录的 offset 已经被 Kafka 删掉Spark 再按旧 offset 去拉自然报越界。解决给主题设置较长保留时间比如retention.ms86400000一天足够课设用或者干脆把 checkpoint 删掉重新跑。注意删 checkpoint 等于重跑所有逻辑如果 Kafka 里已经没有积压消息问题不大。第二个原因是消费者组会话超时。Spark 处理一批消息耗时较长超过session.timeout.ms默认的 45 秒Kafka 会认为消费者挂了触发 RebalanceRebalance 之后又把之前处理到一半的消息重新分配造成重复消费或卡顿。解决把session.timeout.ms调到 60 秒以上同时heartbeat.interval.ms设成 10 秒左右记住心跳间隔必须是超时的三分之一以内否则 Kafka 直接报配置非法。遇到这类问题别急着改代码先看 Kafka 的消费组日志。我用过一个笨办法临时把maxOffsetsPerTrigger调成 1逐条确认能消费再逐步放大量很快就能定位是哪一环卡住了。5.5 现象演示录制视频和实验报告对不上答案都在那三个附件的坑里标题里那三个附件——源码、演示视频、实验报告——看着只是交付物实际上对应着答辩验收的潜规则老师会交叉验证。我就见过有人演示视频里用的是三号字体的截图实验报告里却写的是新模型的准确率代码里模型路径还报错三个材料各说各话被问得下不来台。解决方法是录视频前先固定“测试基线”。具体做法是准备 10 张固定的测试图片先跑一遍离线回放确认这 10 张全部识别正确、置信度都在 0.85 以上然后带着这个结果写实验报告最后录制演示视频也用这 10 张。这样演示视频、实验报告、代码提交版本三者一致老师怎么挑都对得上。录制演示视频时也别只录结果界面我一般会带一下启动过程start-dfs.sh、start-yarn.sh、Kafka、最后提交 Spark 作业让视频里出现完整的操作过程。这一分钟的长度能解决大量“是不是事先录好的”质疑也让“演示录制视频”这个附件真正发挥作用。6. 让实时识别更像“真系统”延迟压缩三板斧与答辩前验证6.1 从 2 秒到 500 毫秒session 复用、批量推断、结果缓存前面提到的优化做完后延迟已经能稳定在 2 到 3 秒。如果你想再进一步让答辩现场的体感明显提升还有三板斧可以上。第一是模型预热。Spark 作业启动后第一个批次里模型加载和图像解码混在一起往往特别慢。解决在writeStream启动前先离线读一张测试图片跑一次推理让 Executor 里的 worker 进程提前把 session 加载好。第二是结果缓存以图片的感知哈希为 key把识别结果直接放在 Redis 里如果同一张图片短时间内再次提交直接返回缓存结果避免重复推理。第三是批大小和 Trigger 的配合前端画板可以做一个“连续提交分帧”的机制让用户在 3 秒内连续写多个数字Spark 一次推理一条批量消息把批处理的吞吐优势真正用起来。下面是可以直接落到配置里的参数表手段配置位置效果预期模型预热作业启动前预推理一次第一个批次不再出现延迟尖峰结果缓存Redis 以图片 hash 做 key重复图片零推理耗时批量推断mapInPandas内堆叠 batch单图推理延时可压缩到几十毫秒合并 TriggerprocessingTime3s让 3 秒内的多次提交合并成一批6.2 答辩前必做的三个验证离线回放、断网自检和置信度日志第一个验证是离线回放。写一个 Python 小脚本按固定顺序把 10 张测试图片经 Kafka Producer 发送到handwrite_in同时录制屏幕确保每一个结果都是录制期间真实生成的。离线回放不仅能验证链路还能让你在答辩前拍出高质量的演示视频而不是现场手忙脚乱画字。第二个验证是断网自检。把 Kafka 停掉观察 Spark 作业的表现——好的情况是作业等待连接、不崩溃重启 Kafka 后恢复消费。这个自检保证答辩现场万一消息队列出问题你不会当着老师的面重启 JVM。第三个验证是置信度日志。给每次推理写一条 JSON 日志包含 session_id、图片哈希、预测类别、置信度、耗时。实验报告的“系统测试”章节直接贴这组日志比任何口头描述都有说服力。我自己的习惯是答辩前一晚把这三个验证跑一遍然后把测试日志固定存档。这不是制造完美假象而是保证演示结果是可重复的——真实系统的底气来自验证过后心里有底。希望这份经验能帮你的课设少走点弯路把时间花在把链路讲清楚上而不是跟环境和版本纠缠。本文还有配套的精品资源点击获取 基于Hadoop与Spark的中文手写数字实时识别系统：架构与实战
简介一套面向高校大数据课设与毕设场景的完整项目资源基于Hadoop与Spark实现中文手写数字的实时识别覆盖从特征提取、模型训练到结果可视化的全流程适合计算机相关专业学生或编程爱好者二次开发。压缩包共18个文件以12个Python脚本为核心包含HOG特征计算、RDD与DataFrame两种逻辑回归实现、t-SNE降维绘图等模块另有实验方案PDF、资源说明文本和两段演示录制视频整体仅25.79MB轻量易部署解压后按英文路径放置即可运行。目前已有147人学习下载项目结构清晰附带的视频和文档能帮助快速理解运行步骤即使遇到环境配置问题也可对照说明排查实验报告中的系统架构与参数调优说明以及分模块的Python代码为二次开发或答辩展示提供了扎实参考。1. 大数据课设里最难回答的一个问题这套系统里Hadoop和Spark到底在干嘛每年大数据课设答辩总有人被同一个问题卡住系统叫“实时识别”你的 Hadoop 和 Spark 到底在哪一步起作用这份题为“基于 Hadoop 和 Spark 的中文手写数字实时识别系统”的课设源码包把答案拆得很清楚——HDFS 负责训练样本和模型的存储Spark Streaming 负责消费图像流并做批量推断中文手写数字识别只是验证整条大数据链路的业务载体。压缩包里除了源码还带了演示视频、实验报告和演示录制视频恰好对应答辩要过的三关代码能跑、逻辑能讲、现场不出乱子。适合正在选大数据课设或大数据毕业设计题目、又不想只做词频统计这类“假大数据”的人。2. 先定架构再写代码这套实时识别系统里 Hadoop 和 Spark 分别扛什么活2.1 识别本身单机就能跑为什么课设非要扯上 Hadoop 和 Spark中文手写数字识别本质是一个图像分类问题。一个 CNN 模型在普通笔记本上用 CPU 也能训练单机跑推理更是轻松。那为什么课设要绕一大圈用 Hadoop 和 Spark核心原因是课设的验收标准不是“模型准不准”而是“你有没有用大数据技术栈解决一个完整问题”。如果把一个手写识别模型单独丢出来老师只能问模型本身的问题但当你把它架在 Hadoop 和 Spark 上验收点就变成了数据怎么存储、流怎么接入、计算怎么分布、结果怎么回写。识别模型只是这条链路上的一环它存在的意义是让大数据的每一步都有业务落点。具体分工上我一般会把 HDFS 作为训练样本和模型的存储层原始图片、数据增强后的样本、训练好的 ONNX 模型文件、模型评估日志全部丢到 HDFS 目录下答辩时可以展示hdfs dfs -ls的文件清单证明 Hadoop 不是摆设。Spark 承担两类计算一类是离线的样本统计分析统计各类别样本量、计算均值方差用于归一化另一类是重头戏——Structured Streaming 消费 Kafka 里的图像消息按微批做推理。这样“批”和“流”都在 Spark 上体现出来了。还有一点要提前想清楚Spark MLlib 自带的那套分类器并不适合直接用。MLlib 里没有 CNN只有逻辑回归、决策树这类传统模型用它们直接识别 28×28 的图像准确率很难看而且中文数字这种笔画结构很容易被传统特征工程搞砸。所以模型的训练我用 PyTorch 完成训练完导出 ONNX推理阶段由 Spark 进程加载 ONNX 模型。这相当于把“训练框架”和“推理引擎”解耦Spark 不依赖 PyTorch 环境也能跑识别。2.2 四层架构画板接入、Kafka 缓冲、Spark 流式推断、结果回写整套系统我习惯按四层来组织每一层的职责单一答辩时画拓扑图也好画。接入层是一个 HTML5 Canvas 画板用户在浏览器里用鼠标或触控笔写一个中文数字零、一、二、三……九或阿拉伯数字0-9写完点击提交。前端把画布内容转成 PNG 的 base64 字符串连同 session_id、时间戳一起封装成 JSON通过 WebSocket 发到后端网关。网关这边用 Flask 写一个小服务收下 JSON 后原样投递到 Kafka 的handwrite_in主题。为什么中间非要插一个 Kafka因为 Spark Streaming 直接读 WebSocket 数据很别扭而 Kafka 天然带 offset 管理和消息积压能力也能让“消息队列”这个大数据组件在链路里露脸。传输层就是 Kafka 单节点主题handwrite_in分区数建议 2 到 4。分区太多在课设环境里反而浪费而且演示时如果只有一个画板在写入多分区只会让下游处理更碎。这里要注意Kafka 依赖 ZooKeeper 做协调如果 Hadoop 集群里已经装了 ZooKeeperKafka 直接复用即可不需要单独再维护一套协调服务。计算层是 Spark Structured Streaming。它从 Kafka 拉取 JSON 消息解析出 base64 图片字段在 Executor 里批量解码、归一化、缩放再交给 ONNX Runtime 做推理。输出的是一个包含 session_id、预测类别、置信度、时间戳的 DataFrame。下一层是结果层把推理结果写回 Redis用 session_id 做 key设置 60 秒过期时间前端收到结果后弹出一个“识别为三置信度 0.97”的提示同时后端把同样内容推到 WebSocket 给所有展示大屏刷新。从用户写完数字到页面出现结果整个链路大约是 1 到 3 秒这个延迟符合“流式微批处理”的定位。2.3 环境选型伪分布式、虚拟机集群还是local[*]课设环境怎么搭决定了你后面几周是快乐调代码还是痛苦修环境。我见过太多人一上来就按网上的 Hadoop 集群部署教程整四台虚拟机折腾一周连 NameNode 都没起来最后只能回来用伪分布式。常见的做法是分三个阶段走。第一阶段是本地开发用 Hadoop 伪分布式搭建 HDFS 单节点NameNode、DataNode、SecondaryNameNode 都在本机Spark 跑在local[*]模式Kafka 和 Redis 也全在本机。这个阶段的目标只有一个把端到端链路跑通代码能出结果。伪分布式的好处是 HDFS 的读写逻辑和真实集群完全一致hdfs://路径也能用只是没有多节点冗余而已。网上搜“hadoop 伪分布式搭建”和“spark 的安装与使用”能找到大量教程照着做即可但记得 Hadoop 和 Spark 的版本要匹配否则后面会踩 RPC 协议的坑。第二阶段是答辩演示环境。如果手头有虚拟机资源我建议至少准备三台一台跑 NameNode ResourceManager Kafka ZooKeeper两台跑 DataNode NodeManager。Spark 提交任务时用 YARN 模式这样资源调度由 YARN 管理答辩时能展示 Spark UI 上的 Executor 列表和批次处理时间说服力强很多。但如果你只有一台物理机别硬上集群——单机伪分布式加local[*]也能把演示做完前提是实验报告里写清楚部署策略为什么课设环境用伪分布式生产环境如何扩展到集群。这个解释本身就是加分项。第三阶段是录制演示视频。视频里最好直接录三节点集群的 Spark UI 界面如果环境不稳定至少也要录伪分布式下jps命令的输出证明 Hadoop 各进程都在。别小看这个很多人的演示视频里连jps都没出现过答辩时只能口头说“我有集群”。下面是三种环境选型的对比给还没动手的同学一个参考环境方案适用阶段优点风险单机伪分布式 local[*]开发调试环境简单出问题好排查演示时无法展示集群并行度三节点虚拟机 YARN答辩演示能截 Spark UI、YARN 资源分配图搭建周期长硬件要求高单机 Docker 容器模拟节点过渡方案环境可重装快照方便网络配置复杂容器间通信易出错我自己的做法是开发用伪分布式答辩前一周切到三节点虚拟机拍完演示视频就再也不动环境了。记住一个原则课设的分数来自你能讲清楚架构而不是集群规模有多大。3. 把中文手写数字识别先跑成离线模型数据集、CNN 训练与 ONNX 导出3.1 数据集怎么凑中文大写数字和阿拉伯数字混排类别定 20 类还是 10 类“中文手写数字”这个表述有个容易忽略的细节它到底是指汉字的“一、二、三”还是指阿拉伯数字“1、2、3”如果只识别阿拉伯数字那就变成了 MNIST 中文版体现不出“中文”二字如果只识别汉字数字类别又太少模型太简单。常见的做法是两类都做——模型同时输出 0 到 9 的阿拉伯数字和中文字符形成 20 个类别然后在后处理阶段把“3”和“三”、“2”和“二”映射成同一个语义结果。数据集方面CASIA-HWDB 是完整的中文手写数据集规模太大、下载和处理成本高课设周期紧张时没必要全量使用。更务实的路线是找现成的中文数字手写子集或者自己组织 50 到 100 人书写、扫描后按字符切分凑出每个类别 300 到 500 张图。20 个类别加起来 6000 到 10000 张已经足够训练一个高准确率的 CNN。图像统一转成灰度 28×28这一步和 MNIST 的预处理方式一致后续代码写起来最顺手。还要注意类别不平衡的问题。很多人收集数据时会把“一”“二”“三”这种好写的字多写几遍“零”“六”“九”这种笔画结构复杂的写少了导致模型对复杂字符欠拟合。我的做法是训练前先统计各类别样本量用np.bincount看一眼分布少于平均数的类别做额外增强随机旋转 ±15 度、平移 ±2 像素、加高斯噪声。数据增强这步不能省尤其是手写笔画轻重不同导致的灰度差异归一化时要用整个数据集的均值和方差而不是简单除以 255。3.2 PyTorch 训练一个能用的 CNNLeNet 变体、Adam 和 6 个 epoch训练脚本我用 PyTorch 写模型结构上用 LeNet 的变体而不是更深的 ResNet。原因很简单输入只有 28×28样本量几千张太深的网络容易过拟合而且训练时间会拖慢整个课设节奏。一个两轮卷积加两轮池化、最后接两个全连接层的网络已经能在这场任务上拿到 98% 以上的准确率。下面是一个最小可运行的训练脚本核心结构可以直接抄import torch import torch.nn as nn from torch.utils.data import DataLoader from torchvision import datasets, transforms class HandwriteCNN(nn.Module): def __init__(self, num_classes20): super().__init__() self.features nn.Sequential( nn.Conv2d(1, 32, 3, padding1), nn.BatchNorm2d(32), nn.ReLU(inplaceTrue), nn.MaxPool2d(2), nn.Conv2d(32, 64, 3, padding1), nn.BatchNorm2d(64), nn.ReLU(inplaceTrue), nn.MaxPool2d(2), ) self.classifier nn.Sequential( nn.Flatten(), nn.Linear(64 * 7 * 7, 128), nn.Dropout(0.3), nn.ReLU(inplaceTrue), nn.Linear(128, num_classes) ) def forward(self, x): return self.classifier(self.features(x)) transform transforms.Compose([ transforms.Resize((32, 32)), transforms.CenterCrop(28), transforms.ToTensor(), transforms.Normalize((0.5,), (0.5,)), ]) train_loader DataLoader(train_dataset, batch_size64, shuffleTrue) model HandwriteCNN(num_classes20) optimizer torch.optim.Adam(model.parameters(), lr1e-3) loss_fn nn.CrossEntropyLoss() for epoch in range(6): for images, labels in train_loader: optimizer.zero_grad() outputs model(images) loss loss_fn(outputs, labels) loss.backward() optimizer.step() print(fepoch {epoch 1} finished)这段代码里的几个参数值得说清楚。batch_size64对 CPU 训练比较友好太大内存压力高太小梯度抖动厉害。lr1e-3配合 Adam 是默认稳妥组合如果 loss 下降很慢可以改成余弦退火。Dropout(0.3)加在全连接层前面专门防过拟合——样本量只有几千张时不加 Dropout 的训到后期训练集准确率 100%、验证集却往下掉。num_classes20对应前面说的阿拉伯数字和中文数字混排方案如果你只做中文数字就改成 10但后处理逻辑也要跟着改。训练到第 6 个 epoch 左右验证集准确率通常会收敛。不要盲目加 epoch超过 10 轮后过拟合明显实验报告里可以放一张训练曲线说明这个现象。如果你发现收敛后准确率还不到 95%优先检查数据集而不是网络结构看看是不是某些类别的样本数太少或者图像在 Resize 和 CenterCrop 时把笔画截掉了。3.3 导出 ONNX 模型给 Spark 留一个不依赖训练框架的推理接口训练完成后模型要交给 Spark 用。Spark 的 Executor 里不可能跑 PyTorch所以需要把 PyTorch 模型导出成 ONNX 格式。ONNX Runtime 的 Python 包体积小、依赖干净可以被打进 Spark 的 Python 环境里。导出代码很简单model.eval() dummy_input torch.randn(1, 1, 28, 28) torch.onnx.export( model, dummy_input, handwrite.onnx, input_names[input], output_names[output], dynamic_axes{input: {0: batch}, output: {0: batch}}, opset_version11 )dynamic_axes这一行很重要。它告诉 ONNX 导出器输入和输出的第 0 维batch 维是动态的这样 Spark 那边一次推一张还是推 100 张都能用同一个模型文件。如果不加这个参数ONNX 会固化输入形状为[1,1,28,28]批量推理时反而要重复构造模型。导出后本地先校验一遍用onnxruntime加载模型拿一张训练集的图片跑一次推理确认输入输出名称和形状和预期一致。这一步能避免后面 Spark 端模型加载失败的问题——很多时候不是 Spark 配错了而是 ONNX 文件本身有问题。3.4 在本地先验证模型混淆矩阵和置信度阈值模型导出前先用验证集算一次混淆矩阵。这一步的目的不是看总体准确率而是看哪些类别互相混淆“三”和“3”、“二”和“2”是常见的混淆对“零”和“六”因为笔画都有交叉结构也容易混。有了混淆矩阵就能定置信度阈值。我一般把阈值设在 0.8低于这个值的结果标记为“不确定”而不是硬给一个类别。这样做的好处有两个一是演示时遇到书写潦草的字不会输出离谱答案二是实验报告里可以写“系统具备不确定性感知能力”这是非常简单但老师爱听的加分点。另外本地验证时要固定一张测试图记录它的预测结果和耗时。这张图以后要用于演示视频的离线回放不能让演示时的测试样例和实验报告的截图对不上。4. 实时识别链路搭建Spark Structured Streaming 消费 Kafka 图像流4.1 实时不等于毫秒级Structured Streaming 的微批和 Trigger 先对齐预期很多同学一听到“实时识别”就往毫秒级响应上想结果把系统做得很复杂最后延迟反而降不下来。这里要先对齐预期Spark Structured Streaming 是微批模型不是逐条处理模型。你画一个数字提交后图片先进 KafkaSpark 每隔一段时间Trigger 间隔拉取一批消息统一做解码和推理。所以端到端延迟最少也是一个 Trigger 间隔加上推理时间。我一般把 Trigger 设为 3 秒。如果设成 0尽可能快Spark 会拼命以最小批次拉数据在课设场景下前端只有一个人在画批次里经常只有一条消息批处理开销序列化、任务调度、结果回写远大于推理本身延迟反而更高。设成 3 秒前端提交后最多等 3 秒就能进下一个批次配合推理和回写整体延迟控制在 3 到 5 秒内。这个数字在答辩时直接说“我是微批流处理秒级响应”不会有任何问题。还要注意的是 checkpoint 目录。Structured Streaming 必须指定 checkpoint 位置否则启动直接报错。课设里把 checkpoint 放在 HDFS 的/spark/checkpoint下既能体现 Hadoop 的参与又能保证重启后不重复消费 Kafka 消息。如果你用的是伪分布式记得hdfs dfs -mkdir -p /spark/checkpoint提前建好目录否则权限问题足够让你排查半小时。4.2 Spark 消费 Kafka 的最小代码base64 解码、预处理、批量预测下面这段代码是整条链路的核心直接放在 Spark 作业里跑。用 PySpark 的mapInPandas做批量推断每个批次的数据以 Pandas DataFrame 形式传入 Python 函数在函数里统一加载 ONNX 模型并推理。from pyspark.sql import SparkSession from pyspark.sql.types import (StructType, StructField, StringType, IntegerType, FloatType) from pyspark.sql.functions import from_json, col import io import base64 import numpy as np import cv2 import onnxruntime as ort _ort_session None def get_session(): global _ort_session if _ort_session is None: _ort_session ort.InferenceSession( /models/handwrite.onnx, providers[CPUExecutionProvider] ) return _ort_session def predict_batch(pdf): session get_session() images [] for _, row in pdf.iterrows(): raw base64.b64decode(row[image_base64]) img cv2.imdecode(np.frombuffer(raw, dtypenp.uint8), cv2.IMREAD_GRAYSCALE) img cv2.resize(img, (28, 28)) img img.astype(np.float32) / 255.0 img (img - 0.5) / 0.5 images.append(img) inputs np.stack(images).reshape(-1, 1, 28, 28) outputs session.run([output], {input: inputs})[0] pdf[pred] outputs.argmax(axis1) pdf[conf] outputs.max(axis1).astype(float) return pdf[[session_id, pred, conf, ts]] schema StructType([ StructField(session_id, StringType()), StructField(image_base64, StringType()), StructField(ts, StringType()), ]) result_schema StructType([ StructField(session_id, StringType()), StructField(pred, IntegerType()), StructField(conf, FloatType()), StructField(ts, StringType()), ]) spark SparkSession.builder \ .appName(ChineseHandwriteRealTimeOCR) \ .master(local[*]) \ .config(spark.sql.shuffle.partitions, 4) \ .getOrCreate() raw spark.readStream \ .format(kafka) \ .option(kafka.bootstrap.servers, localhost:9092) \ .option(subscribe, handwrite_in) \ .option(maxOffsetsPerTrigger, 200) \ .load() parsed raw.select( from_json(col(value).cast(string), schema).alias(msg) ).select(msg.*) results parsed.mapInPandas(predict_batch, result_schema) query results.writeStream \ .outputMode(append) \ .format(console) \ .option(truncate, false) \ .trigger(processingTime3 seconds) \ .option(checkpointLocation, hdfs://localhost:9000/spark/checkpoint) \ .start() query.awaitTermination()这段代码有两个关键设计。第一get_session用了模块级全局变量缓存 ONNX session。mapInPandas会在每个 Executor 的 Python worker 进程里反复调用predict_batch如果不缓存每个批次都重新加载模型推理耗时会被模型加载耗掉大半延迟直接爆炸。第二imdecode解码时用np.frombuffer包一层这是因为 OpenCV 的imdecode需要拿到一个可读的缓冲区直接传 bytes 在某些版本会报错。maxOffsetsPerTrigger设置为 200表示每个 Trigger 最多拉 200 条 Kafka 消息。演示时只有一个画板这个值根本用不满但设置它能防止如果之前积压了大量消息一次性全拉进来导致批次处理时间过长。4.3 结果回写 Redis前端轮询和 WebSocket 推送二选一推理结果出来了怎么送到前端两种常见做法前端轮询 Redis 或后端 WebSocket 推送。课设演示我推荐主用 WebSocket 推送前端代码量少展示效果也更“实时”。在writeStream里可以换成foreachBatch来写 Redisimport redis import json def write_to_redis(batch_df, batch_id): r redis.Redis(hostlocalhost, port6379, db0) for row in batch_df.collect(): key focr:result:{row[session_id]} r.set(key, json.dumps({ pred: int(row[pred]), conf: float(row[conf]), ts: row[ts] }), ex60) query results.writeStream \ .foreachBatch(write_to_redis) \ .option(checkpointLocation, hdfs://localhost:9000/spark/checkpoint/redis) \ .start()ex60表示结果 60 秒后自动过期避免 Redis 里的 key 越积越多演示结束后内存也不会有压力。如果你做的是大屏展示前端每 2 秒调用一次 Redis 的 GET 接口也能接受但轮询带来的延迟感和多余的 HTTP 请求会让答辩观感变差所以我建议按 WebSocket 推送来做。4.4 参数怎么设maxOffsetsPerTrigger、trigger 间隔和 checkpointStructured Streaming 的参数看起来简单实际调起来有几个容易踩坑的地方。下面这张表是我用过比较顺手的配置组合参数推荐值说明trigger processingTime3 seconds微批间隔太短则单批消息少、开销大太长则实时感差maxOffsetsPerTrigger200限制单批最大消息数防止积压导致雪崩spark.sql.shuffle.partitions4开发/ 节点数×2集群默认 200课设数据量下纯浪费调度资源checkpointLocationhdfs://.../checkpoint必须设置否则流启动就报错spark.sql.streaming.schemaInference不使用从 Kafka 读数据写死 schema不需要推断spark.sql.shuffle.partitions这个参数很多人忽略。默认值是 200意味着只要有一次 shuffle就会生成 200 个小任务。课设环境里数据量几千条200 个分区纯粹是增加调度开销本地开发时改成 4 个分区集群演示时改成节点数乘以 2批次处理时间明显下降。另外如果你用的是 YARN 模式别忘了给 Executor 留够内存。ONNX Runtime 加载模型需要一定内存我一般给 Executor 设spark.executor.memory2g太小会频繁 GC 导致批次时间波动。5. 课设排坑记录从 Yarn 卡死到演示视频翻车的 5 个血泪案例5.1 现象Spark 作业提交后一直停在 Yarn RMProxy答辩现场直接尬住这个问题最常见的场景是代码在local[*]下跑得好好的一到三节点集群上用 YARN 模式提交日志就卡在yarn.RMProxy等了十分钟也没有 Container 启动。原因通常是资源没对上。要么是 ResourceManager 所在节点的队列资源被占满要么是spark.executor.memory和spark.yarn.am.memory之和超出了 NodeManager 的单节点可用内存。排查方法很简单看 ResourceManager 的 Web UI找到你的 application点进 Attempts 看诊断信息基本都会写明资源不足的细节。解决先把spark.dynamicAllocation.enabled关掉手动指定num-executors为 2每个 Executor 1GB 内存、一个核这样最小资源需求就能算清楚。另外确认yarn.nodemanager.resource.memory-mb要大于所有 Executor 加上 AM 的总内存。我在课设里吃过一次亏三台虚拟机每台只给了 2GB 内存还跑着 Hadoop 进程Spark 分两个 Executor 后内存直接爆掉后来把 NodeManager 的资源上限调到 3GB 才正常。5.2 现象画完数字要等 8 秒才出结果被老师质疑“这不叫实时”这个坑几乎每个人都踩过。原因一般有两个一是 ONNX session 在每个批次里重复加载二是 Trigger 设成了 0Spark 为了一条消息也要调度一个批次。解决分三步走。首先按前面 4.2 的写法把 session 缓存成模块级全局变量模型加载只做一次然后把 Trigger 从 0 改成 3 秒让消息攒成一批再算最后在mapInPandas里不要用循环逐张推理而是把整批图片堆成[-1, 1, 28, 28]的张量一次喂给 ONNX Runtime。优化后我在伪分布式下的实际延迟稳定在 2 秒出头——一个 Trigger 间隔加推理加回写答辩完全够用。如果你把优化做了还是慢把spark.sql.shuffle.partitions改小试试。默认 200 个分区会在结果回写阶段产生大量小任务每条结果都走一次调度积少成多就是一个严重的延迟来源。5.3 现象“三”和“3”、“二”和“2”互相认错后处理把它救回来一开始我以为这是模型问题加数据增强、调网络结构折腾很久准确率还是卡在 95% 左右错误几乎都集中在中文数字和阿拉伯数字的相似笔画上。后来想明白了模型输出 20 类但“3”和“三”在语义上是同一个数字模型并不需要同时把它们分对只需要在输出层做合并。解决写一个简单的后处理映射把预测类别中阿拉伯数字和对应中文数字归一成一个结果。同时把置信度阈值压到 0.8低于阈值的返回“不确定”。这一处理不仅让演示效果更自然还顺带把“零”和“六”这类容易混淆的类别兜住了——至少不会给出一个言之凿凿的错答案。这个经验也说明一个问题业务层的规则能解决的不要指望模型硬扛。实验报告里写清楚这套后处理逻辑比单纯堆准确率数字有说服力得多。5.4 现象Spark 读 Kafka 报 OffsetOutOfRange 和 Session 超时的“玄学”问题明明代码没动第二天启动作业就报OffsetOutOfRangeException或者消费者一直卡在JoinGroup超时。这类问题乍看很玄学其实大部分是 Kafka 侧的事。第一个常见原因是 Kafka 的消息保留时间太短。课设环境里 Kafka 默认 retention 通常是一周或更短如果你前一天测试往里灌了消息第二天 checkpoint 记录的 offset 已经被 Kafka 删掉Spark 再按旧 offset 去拉自然报越界。解决给主题设置较长保留时间比如retention.ms86400000一天足够课设用或者干脆把 checkpoint 删掉重新跑。注意删 checkpoint 等于重跑所有逻辑如果 Kafka 里已经没有积压消息问题不大。第二个原因是消费者组会话超时。Spark 处理一批消息耗时较长超过session.timeout.ms默认的 45 秒Kafka 会认为消费者挂了触发 RebalanceRebalance 之后又把之前处理到一半的消息重新分配造成重复消费或卡顿。解决把session.timeout.ms调到 60 秒以上同时heartbeat.interval.ms设成 10 秒左右记住心跳间隔必须是超时的三分之一以内否则 Kafka 直接报配置非法。遇到这类问题别急着改代码先看 Kafka 的消费组日志。我用过一个笨办法临时把maxOffsetsPerTrigger调成 1逐条确认能消费再逐步放大量很快就能定位是哪一环卡住了。5.5 现象演示录制视频和实验报告对不上答案都在那三个附件的坑里标题里那三个附件——源码、演示视频、实验报告——看着只是交付物实际上对应着答辩验收的潜规则老师会交叉验证。我就见过有人演示视频里用的是三号字体的截图实验报告里却写的是新模型的准确率代码里模型路径还报错三个材料各说各话被问得下不来台。解决方法是录视频前先固定“测试基线”。具体做法是准备 10 张固定的测试图片先跑一遍离线回放确认这 10 张全部识别正确、置信度都在 0.85 以上然后带着这个结果写实验报告最后录制演示视频也用这 10 张。这样演示视频、实验报告、代码提交版本三者一致老师怎么挑都对得上。录制演示视频时也别只录结果界面我一般会带一下启动过程start-dfs.sh、start-yarn.sh、Kafka、最后提交 Spark 作业让视频里出现完整的操作过程。这一分钟的长度能解决大量“是不是事先录好的”质疑也让“演示录制视频”这个附件真正发挥作用。6. 让实时识别更像“真系统”延迟压缩三板斧与答辩前验证6.1 从 2 秒到 500 毫秒session 复用、批量推断、结果缓存前面提到的优化做完后延迟已经能稳定在 2 到 3 秒。如果你想再进一步让答辩现场的体感明显提升还有三板斧可以上。第一是模型预热。Spark 作业启动后第一个批次里模型加载和图像解码混在一起往往特别慢。解决在writeStream启动前先离线读一张测试图片跑一次推理让 Executor 里的 worker 进程提前把 session 加载好。第二是结果缓存以图片的感知哈希为 key把识别结果直接放在 Redis 里如果同一张图片短时间内再次提交直接返回缓存结果避免重复推理。第三是批大小和 Trigger 的配合前端画板可以做一个“连续提交分帧”的机制让用户在 3 秒内连续写多个数字Spark 一次推理一条批量消息把批处理的吞吐优势真正用起来。下面是可以直接落到配置里的参数表手段配置位置效果预期模型预热作业启动前预推理一次第一个批次不再出现延迟尖峰结果缓存Redis 以图片 hash 做 key重复图片零推理耗时批量推断mapInPandas内堆叠 batch单图推理延时可压缩到几十毫秒合并 TriggerprocessingTime3s让 3 秒内的多次提交合并成一批6.2 答辩前必做的三个验证离线回放、断网自检和置信度日志第一个验证是离线回放。写一个 Python 小脚本按固定顺序把 10 张测试图片经 Kafka Producer 发送到handwrite_in同时录制屏幕确保每一个结果都是录制期间真实生成的。离线回放不仅能验证链路还能让你在答辩前拍出高质量的演示视频而不是现场手忙脚乱画字。第二个验证是断网自检。把 Kafka 停掉观察 Spark 作业的表现——好的情况是作业等待连接、不崩溃重启 Kafka 后恢复消费。这个自检保证答辩现场万一消息队列出问题你不会当着老师的面重启 JVM。第三个验证是置信度日志。给每次推理写一条 JSON 日志包含 session_id、图片哈希、预测类别、置信度、耗时。实验报告的“系统测试”章节直接贴这组日志比任何口头描述都有说服力。我自己的习惯是答辩前一晚把这三个验证跑一遍然后把测试日志固定存档。这不是制造完美假象而是保证演示结果是可重复的——真实系统的底气来自验证过后心里有底。希望这份经验能帮你的课设少走点弯路把时间花在把链路讲清楚上而不是跟环境和版本纠缠。本文还有配套的精品资源点击获取