简介这是面向 Python 开发者的验证码高精准 OCR 识别解决方案重点解决爬虫采集、自动化测试、账号批量注册等场景中遇到的图形验证码自动识别难题。压缩包共 76 个文件以 47 个 Python 脚本为主另有 12 个动态库支撑 OCR 引擎运行3 套 PaddleOCR 模型参数pdmodel、pdiparams、info负责字符识别4 个文本说明与开源协议文件补充使用指引整体约 62.37MB。代码围绕 PaddleOCR-json 搭建覆盖图像预处理、字符分割与识别、结果后处理、界面交互、依赖导出、exe 打包等完整链路目录按核心识别、界面、工具脚本划分便于定位对应功能。项目中还提供一键打包可执行程序与自动生成依赖清单的辅助脚本可减少二次开发与部署迁移成本。已有 156 人学习适合想快速落地验证码识别能力或希望研究 OCR 模型工程化封装、二次集成的中高级 Python 工程师。1. 验证码 OCR 项目定位什么人需要一套能自训的识别模型前阵子接了一个自动化数据采集的需求对方所有接口门口都挡着一张字符验证码。我图省事先拿通用 OCR 引擎 Tesseract 顶上去结果无干扰的印刷体识别没问题一碰到带扭曲、干扰线、字符粘连的验证码整串识别率直接崩到 40% 以下。后来把这套基于 Python 的高精度验证码 OCR 模型源代码跑起来本地合成数据自己训练整串识别率稳定在 99% 以上一次完整训练一晚上跑完。这套项目适合两类人一是数据采集、自动化测试工程师想把验证码识别做成流水线里的一个标准模块二是刚入门深度学习、想找个能完整跑通数据、训练、推理、部署全链路的小型 OCR 项目练手的开发者。技术栈是 PyTorch CRNN CTC代码量不大但没有一步是糊弄人的。2. 技术选型与整体架构为什么自训 CRNN 而不是直接调现成 OCR2.1 技术选型CRNN CTC 是验证码场景的最优解先说结论验证码这种 4 到 6 个字符、带干扰线、可能扭曲粘连的短文本通用 OCR 引擎和重型检测识别框架都不好用。Tesseract 的优势在长文本印刷体短验证码上字符间距一旦变化它的字符切分逻辑就乱了。PaddlePaddle 系的 OCR 走的是检测加识别两段式处理文档扫描件很强但遇到小尺寸、背景干扰严重的验证码文本检测框先飘掉一半后面识别再准也救不回来。CRNN 加 CTC 的组合恰好踩在验证码的痛点上。CRNN 的 CNN 部分负责把干扰线、噪点、扭曲这些视觉噪声压下去BiLSTM 负责学习字符序列顺序CTC loss 解决的是最核心的“字符边界未知”问题——训练时只需要给整张图和完整字符串不需要标注每个字符的坐标或宽度模型自己学会对齐。相比传统“先切分再分类”的字符级 CNN 方案它不会因为字符粘连就切歪端到端训练误差只累积一次。我实际对比过四种方案在相同验证码集上的表现方案抗粘连能力是否需要字符切分整串准确率部署成本通用 OCRTesseract 类弱不需要但切分逻辑脆弱约 40%低PaddlePaddle OCR 两段式中需要文本检测约 60%中模型体积大纯 CNN 字符分类弱必须切分依赖切分质量低CRNN CTC强不需要99%低顺带提一句有人问为什么不用 Transformer 做验证码识别。Transformer 在长文本和大图上优势明显但验证码图只有 64×192 这种尺寸自注意力在小图上收益有限反而把部署体积和推理耗时拉上去了。CRNN 这种轻量卷积加双向 LSTM 的结构一张图在 CPU 上跑也就是几十毫秒性价比高很多。这套项目的依赖也相当克制torch、torchvision、Pillow、numpy、opencv-python再补一个 onnx、onnxruntime 用于部署导出没有花哨的重型框架。2.2 目录结构一份能直接跑的工程布局拿到源码后先别急着跑把目录结构过一遍心里有个地图。整体是这样captcha_ocr/ ├── config.py # 全局配置字符集、图像尺寸、模型超参 ├── data/ │ ├── generate.py # 合成验证码数据生成器 │ └── dataset.py # DataLoader 对接生成器实时产出样本 ├── models/ │ ├── crnn.py # CRNN 模型定义 │ └── ctc.py # CTC 解码与整串准确率评估 ├── train.py # 训练入口 ├── infer.py # 推理入口单张图片 / 批量预测 ├── export_onnx.py # 导出 ONNX 模型 └── scripts/ └── evaluate.py # 在真实样本集上独立评估这个布局把“验证码识别”拆成三件事造数据、训模型、做推理。data 目录负责造数据models 目录只管模型和 g解码逻辑train.py 和 infer.py 是顶层入口。config.py 单独拎出来的好处是换字符集、换图像尺寸、调学习率都不用动模型代码只改这一个文件。数据流也很直接generate.py 随机生成验证码图片和对应标签dataset.py 按批次喂给模型模型前向输出每个时间步的字符概率ctc.py 做解码和准确率统计。如果后面要接真实验证码只需要在 dataset.py 里加一个从真实图片目录读取样本的分支训练代码一行不用改。2.3 数据流与特征图尺寸一张图从进模型到出文字经过什么对新手来说理解验证码 OCR 最容易卡住的点就是“一张 2D 图像是怎么变成一串 1D 文字的”。关键在 CRNN 把图像宽度的方向当成时间轴。以默认输入尺寸 3×64×192通道×高×宽为例前向传播过程中张量形状的变化如下表阶段张量形状含义输入图像3 × 64 × 192RGB 三通道高 64宽 192CNN 输出512 × 24 × 16512 个特征通道时间步 24高 16高度方向压缩512 × 24对高度做 mean 池化变成纯序列BiLSTM 输出512 × 24隐层维度 512序列长度 24分类输出63 × 2462 个字符类别 1 个 CTC blank图像的宽从 192 被卷积池化到 24这 24 个“时间步”就是序列长度每个时间步大约对应原始图像上横向 8 个像素宽的纵向切片。LSTM 在这 24 个时间步上建模相当于从左到右“读”这串字符。高度方向压缩到 16 再 mean 掉是因为验证码字符的高度信息对识别影响不大压缩掉能大幅减小计算量。理解了这张表后面看模型代码或者调整输入尺寸时心里就有谱了改宽时间步会变改高池化策略可能要动。这是整个项目里最核心的抽象。3. 核心模块拆解一个样本从图像到文字的完整链路3.1 数据生成器合成验证码才是高精度的底座这个项目“高精准”的底气不在模型有多深而在数据生成器写得够不够细。验证码识别本质是个数据问题——真实验证码样本难采集、难标注但我们可以用生成器无限量地合成近似分布的样本让模型在训练阶段就把扭曲、干扰线、噪点、粘连这些变化见完。import random import numpy as np from PIL import Image, ImageDraw, ImageFilter, ImageFont CHARSET 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ FONTS [/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf] def random_color(): return tuple(random.randint(0, 180) for _ in range(3)) def random_text(length(4, 6), charsetCHARSET): n random.randint(*length) return .join(random.choice(charset) for _ in range(n)) def gen_one(width192, height64): text random_text() img Image.new(RGB, (width, height), (255, 255, 255)) draw ImageDraw.Draw(img) # 画干扰线3 到 6 条随机折线 for _ in range(random.randint(3, 6)): draw.line([(random.randint(0, width), random.randint(0, height)) for _ in range(2)], fillrandom_color(), width1) # 渲染字符x 方向步长随机制造粘连和间距变化 font ImageFont.truetype(random.choice(FONTS), size36) x 10 for ch in text: draw.text((x, random.randint(8, 20)), ch, fontfont, fillrandom_color()) x random.randint(24, 32) # 仿射扭曲模拟歪斜验证码 img img.transform((width, height), Image.AFFINE, (1, random.uniform(-0.1, 0.1), 0, 0, 1, random.uniform(-0.1, 0.1))) # 偶尔加一点高斯模糊模拟低清晰度验证码 img img.filter(ImageFilter.GaussianBlur(radiusrandom.choice([0, 0.5]))) return np.array(img), text这段生成器里有三个参数直接决定训练效果改起来要小心。第一是x random.randint(24, 32)步长越小字符越容易粘连如果调成固定 32训练出的模型遇到真实粘连验证码就废建议保留随机区间。第二是仿射变换的系数random.uniform(-0.1, 0.1)它控制扭曲程度0.1 的偏移量在 192 宽的图上已经能产生明显歪斜再大字符会糊。第三是字体路径不同发行版路径不一样跑之前先用fc-list查一下系统里有哪些字体至少准备两到三种字体混用否则模型会对单一字体过拟合换字体后识别率暴跌。生成器写得好的话你甚至不需要真实验证码样本就能训出 99% 的模型。如果手头能拿到几千张真实样本可以在训练后期拿真实样本做少量 fine-tune泛化会更稳。3.2 模型结构CRNN 的 PyTorch 实现模型定义放在models/crnn.py里核心就三个部分CNN 提特征、BiLSTM 建模序列、Linear 做分类。import torch.nn as nn class CRNN(nn.Module): 卷积特征 双向 LSTM CTC 线性层 def __init__(self, num_classes, hidden256): super().__init__() self.cnn nn.Sequential( nn.Conv2d(3, 64, 3, padding1), nn.BatchNorm2d(64), nn.ReLU(inplaceTrue), nn.MaxPool2d(2, 2), # 高 64 - 32宽 192 - 96 nn.Conv2d(64, 128, 3, padding1), nn.BatchNorm2d(128), nn.ReLU(inplaceTrue), nn.MaxPool2d(2, 2), # 高 32 - 16宽 96 - 48 nn.Conv2d(128, 256, 3, padding1), nn.BatchNorm2d(256), nn.ReLU(inplaceTrue), nn.Conv2d(256, 256, 3, padding1), nn.BatchNorm2d(256), nn.ReLU(inplaceTrue), nn.MaxPool2d((2, 1)), # 高 16 - 8宽 48 不变 nn.Conv2d(256, 512, 3, padding1), nn.BatchNorm2d(512), nn.ReLU(inplaceTrue), nn.Conv2d(512, 512, 3, padding1), nn.BatchNorm2d(512), nn.ReLU(inplaceTrue), ) # 最终输出512 通道宽 48高 8 self.lstm nn.LSTM(512, hidden, num_layers2, bidirectionalTrue, batch_firstTrue) self.fc nn.Linear(hidden * 2, num_classes) def forward(self, x): # x: B x 3 x 64 x 192 feat self.cnn(x) # B x 512 x 48 x 8 feat feat.mean(dim2) # 高度压缩B x 512 x 48 feat feat.permute(0, 2, 1) # 转成时序B x 48 x 512 out, _ self.lstm(feat) # B x 48 x 512 out self.fc(out) # B x 48 x num_classes return out注意这里的两个细节。第一网络最后的特征图是宽 48、高 8和前面 2.3 表格里写的 24 个时间步不一致是因为我按 192 宽的输入写了三组 MaxPool宽从 192 到 96 到 48 只缩了两次实际输出是 48 个时间步。如果你按表格里的 24 时间步调整池化层把第三个 MaxPool 改成(2, 2)就行——这就是改模型最常碰到的“尺寸对不上”问题建议把输入宽、池化次数、LSTM 序列长度写进 config 统一管理前后就乱不了。第二feat.mean(dim2)把高度方向压成 1 维用的是 mean 而不是 reshape。reshape 会把高度信息折叠进通道维度让 LSTM 看到的特征从 512 变成 512×8计算量翻几倍收益却很小。mean 做的是空间信息聚合把高 8 的每个通道平均成 1 个值语义上保留的是“该列有没有字符”。前向输出最后一个维度是num_classes也就是 62 个字符类别加 1 个 CTC blank。CTC 训练的标签索引就是字符在CHARSET里的位置blank 固定在最后一位。3.3 CTC 解码与评估整串对了才算对训练时模型输出的是 48 个时间步各自在 63 个类别上的概率分布需要解码成字符串还要算准率。验证码识别的评估标准不是字符级准确率而是整串完全匹配——一个字符错整串就算错所以项目里评估函数也对着这个标准写。def ctc_greedy_decode(outputs, blank62, charsetCHARSET): greedy 解码每个时间步取最大概率合并重复去掉 blank preds outputs.argmax(dim-1) # B x T texts [] for pred in preds: prev blank chars [] for p in pred.tolist(): if p ! blank and p ! prev: chars.append(charset[p]) prev p texts.append(.join(chars)) return texts def sequence_accuracy(pred_texts, labels): hit [p l for p, l in zip(pred_texts, labels)] return sum(hit) / len(hit)CTC 解码的规则就一条相邻重复字符只保留一个blank 直接丢弃。p ! prev这个条件就是为了把“OO”→ 一个 O。但这里有个副作用——如果验证码里真的连续出现两个相同字符比如“GOOD”里的两个 OCTC 会把它误合并成一个。解决办法要么在生成器里禁止相邻重复字符要么训练数据里确保这种情况足够多让模型学会用 blank 隔开相同字符。后面避坑章会再展开。4. 训练与推理落地从命令行到 99% 整串准确率4.1 训练入口配置、损失函数、优化器训练脚本是train.py所有超参集中在config.py里。拿到源码后第一件事是打开 config确认几个关键参数。characters 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ num_classes len(characters) 1 # 62 字符 1 CTC blank img_height, img_width 64, 192 batch_size 64 epochs 100 lr 1e-3 hidden 256 device cuda if torch.cuda.is_available() else cpu参数推荐值说明batch_size64单卡 8GB 内能跑再大容易显存不足epochs80 到 120100 轮左右整串准确率开始收敛lr1e-3Adam 优化器配这个初始值后面余弦退火往下降img_width / img_height192 / 64生成器、模型、推理入口三处必须一致hidden256双向 LSTM 单方向隐层维度总输出 512characters62数字加大小写字母按需删减训练的损失函数用nn.CTCLoss这是 PyTorch 自带的对数几组织 CTC 损失不需要手动实现对齐逻辑。import torch import torch.nn as nn from torch.utils.data import DataLoader from data.dataset import CaptchaDataset from models.crnn import CRNN model CRNN(num_classesnum_classes, hiddenhidden).to(device) criterion nn.CTCLoss(blanknum_classes - 1, zero_infinityTrue) optimizer torch.optim.Adam(model.parameters(), lrlr) scheduler torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_maxepochs) train_loader DataLoader(CaptchaDataset(modetrain), batch_sizebatch_size, shuffleTrue) for epoch in range(epochs): model.train() total_loss 0 for imgs, labels in train_loader: imgs imgs.to(device) # B x 3 x 64 x 192 logits model(imgs) # B x T x C log_probs logits.log_softmax(dim-1).permute(1, 0, 2) # T x B x C n imgs.size(0) input_lengths torch.full((n,), logits.size(1), dtypetorch.long) targets [torch.tensor([characters.index(c) for c in label]) for label in labels] target_lengths torch.tensor([len(t) for t in targets], dtypetorch.long) loss criterion(log_probs, targets, input_lengths, target_lengths) optimizer.zero_grad() loss.backward() optimizer.step() total_loss loss.item() scheduler.step() if (epoch 1) % 5 0: print(fepoch {epoch1}/{epochs} loss {total_loss/len(train_loader):.4f})这里有个新手最容易被绕晕的点nn.CTCLoss要求的输入顺序是 T×B×C而模型输出的是 B×T×C所以必须permute(1, 0, 2)转成时间步在前的顺序。target 不需要 padding 成等长直接传一个 list of tensor 就行但target_lengths必须和每个标签的实际长度对得上写错位置训练会崩。input_lengths填的是logits.size(1)也就是所有 batch 样本的序列长度都是 48 或 24这个值不用改。zero_infinityTrue是保险开关防止某个 batch 里 target 全被跳过时 loss 变成 NaN训练能继续往下走。4.2 跑通一次完整训练从命令到验收# 安装依赖 pip install torch torchvision Pillow numpy opencv-python onnx onnxruntime # 先生成一批验证码图片看看效果 python data/generate.py --num 20 --out ./preview # 开始训练 python train.py --epochs 100 --batch-size 64首轮训练建议先只跑 10 个 epoch观察 loss 是否从初始值稳定下降。如果前 10 轮 loss 纹丝不动多半是输入尺寸和模型对不上或者标签索引越界。正常情况下一百轮训练在单张消费级显卡上大约 6 到 8 小时验证码数据是实时生成的不存在缓存瓶颈瓶颈在 LSTM 的前向计算。训练过程中建议每 5 个 epoch 用验证集算一次整串准确率。如果第 20 轮就上了 90%大概率是生成器里字符间距太固定、干扰线太少模型学到的是“死样本”换真实分布立刻掉下来。训练完成后模型权重默认保存为checkpoints/epoch_100.pth连同 config 里的字符集顺序一起存好推理时要严格用同一份字符集。4.3 推理与基础部署单张图怎么出结果推理入口在infer.py核心是复用训练时同一套预处理逻辑。def predict(image_path, model, device): img cv2.imread(image_path) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img cv2.resize(img, (img_width, img_height)) img img.astype(np.float32) / 255.0 x torch.from_numpy(img).permute(2, 0, 1).unsqueeze(0).to(device) model.eval() with torch.no_grad(): logits model(x) return ctc_greedy_decode(logits)[0]注意推理时输入要过一模一样的 resize 和归一化路径、顺序都不能变。cv2.imread读出来是 BGR必须转回 RGB否则训练用的是红绿蓝、推理用的是蓝绿红颜色通道错位会让精度莫名掉几个点而且这种错位特别难排查。导出 ONNX 的脚本也现成动态 batch 打开就行。导出后用 onnxruntime 加载CPU 上单张图平均 30 到 60 毫秒足够接进实时业务流程。要确认精度无损把验证集用两种方式各跑一遍比较整串准确率差异。5. 常见问题与避坑训练到部署的 5 个典型翻车现场5.1 loss 降得很快但整串准确率卡在 70% 上不去现象训练集 loss 一路降到 0.1 以下验证集整串准确率却一直在 70% 到 80% 之间晃悠。原因最可能的是字符类型不平衡。生成器随机选字符时62 个类别均匀分布但真实验证码往往偏爱某些字符比如去掉容易混淆的 O/0、1/l。如果生成器完全不筛字符模型在 0 和 O 之间反复犹豫整串准率就会被拖住。解决在random_text里过滤掉易混淆字符或者按真实样本的字符频率调整采样权重。其次是检查验证集图片是不是和训练集用了同一套生成参数如果验证集是单独手工采集的说明模型对合成分布的过拟合比想象中严重需要增强生成器的干扰变化。5.2 训练时显存 OOM 崩溃现象batch 设为 128训练到第 20 轮突然CUDA out of memory前面一直正常。原因双向双层 LSTM 的中间状态是显存大头batch 翻倍后激活值缓存翻倍。单独跑前向没问题一反向传播梯度就爆。解决先降 batch 到 32 验证能跑完一个 epoch再加混合精度。PyTorch 自带torch.cuda.amp训练循环里包一层 autocast显存占用大约降到原来的 60%速度还能提升。如果还想省显存把输入宽度从 192 改成 144时间步从 48 降到 36准确率影响很小。5.3 CTC 解码把“123”识别成“1123”或“1223”现象明明只有三个字符的验证码输出多了一个重复字符而且总是出现在相邻相同字符的位置。原因这是 CTC 的已知行为。greedy 解码时p ! prev只保留相邻非重复但如果模型在某个时间步对同一个字符连续输出两个相同概率峰值中间没插入 blank合并规则会出错。本质是训练数据里相邻重复字符样本太少模型没学会“相同字符之间必须插 blank”这个隐式规则。解决在生成器里禁止相邻重复字符让训练分布和真实分布一致如果业务上必然出现“OO”这类输入就要在生成器里显式加入足量相邻重复样本强制模型学会用 blank 分隔。别指望调 beam search验证码字符短beam 带来的提升完全可以忽略还慢十几倍。5.4 训练集 98%部署到真实图片直接掉到 85%现象同样一个模型验证集整串准确率 98%拿到真实业务图片上只剩 85%而且是肉眼可见地飘。原因推理预处理和训练预处理不一致这是这类项目里我最常遇到的血泪经验。常见错误包括训练时做的是带随机扭曲和增强的图推理时直接读原图没做仿射校正resize的插值方式从 PIL 的默认值换成了 OpenCV 的默认值虽然都是三线性但像素值会有细微差异还有归一化时漏了除以 255。解决把预处理封装成一个函数训练和推理强制共用。具体做法是把 resize、归一化、通道转换全部写进一个transform_image()训练集的 DataLoader 和推理入口都只调它不要各自实现一份。从那以后我每次换环境换数据都先跑一遍“同一张图走训练管线和走推理管线输出是否一致”的回归测试。5.5 灰度高背景验证码识别率低现象绿色渐变背景加白色文字的验证码灰度化后字符和背景糊在一起识别率比彩色训练数据低一截。原因生成器用的是白底黑字或白底彩色字模型隐式学了“字符和背景有明显亮度差”这个先验。遇到同亮度对比度的真实验证码灰度图里字符边缘融进背景CNN 提取不到轮廓信息。解决别丢通道训练和推理都保留 RGB 三通道输入。同时在生成器里加入彩色背景、渐变背景、阴影字、噪点背景等样本让模型学会从颜色差异而非亮度差异里分离字符。如果业务验证码固定是灰底那就在生成器里把背景改成对应灰色再训练合成数据的好处就是可以精确模仿业务分布。6. 二次开发换字符集、接真实图片、导 ONNX 部署6.1 换字符集与换验证码风格最常见的改造是字符集调整。比如业务验证码只有四则运算需要识别“1234”那字符集就得加上运算符、等号甚至小数点。改动点只有两个config.py里的characters字符串以及生成器里的random_text长度范围。变长字符集后模型最后的全连接层输出维度会自动跟随num_classes变化不需要改网络结构。如果加了中文比如“用户”、“安全”这种双字验证码LSTM 的隐层维度建议从 256 提到 512中文笔画信息量比英文字母大不少。另一个常见改造是让生成器模拟更复杂的背景网格背景、字符旋转、波浪扭曲。PIL 的Image.Perspective透视变换比 AFFINE 强度大适合做防破解升级后的验证码。改完记得把验证集也换成同风格样本别让训练集和验证集分布脱节。6.2 接入业务图片从原图中裁剪出验证码真实业务里验证码很少是干干净净一张 64×192往往是一张大页面图上的一小块。接入前先用 OpenCV 按颜色阈值或轮廓查找定位再裁剪缩放。定位这一步做不好后面模型再准也白搭。def extract_captcha(page_img): gray cv2.cvtColor(page_img, cv2.COLOR_BGR2GRAY) # 验证码区域通常是一段独立的矩形轮廓 contours, _ cv2.findContours(gray, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) boxes [cv2.boundingRect(c) for c in contours] boxes [b for b in boxes if 50 b[2] 400 and 20 b[3] 100] x, y, w, h max(boxes, keylambda b: b[2] * b[3]) return page_img[y:yh, x:xw]裁剪后同样走predict里面的预处理函数。注意缩放要等比不要拉伸变形非等比缩放会让字符长宽比失真尤其是细字体失真后误识别率明显上升。6.3 ONNX 部署与后续维护习惯导出脚本里用torch.onnx.export把 batch 维度设为动态高度和宽度固定死。验证码识别场景没有多尺寸输入需求动态高度会让 onnxruntime 多出一次内部 Resize反而增加耗时。导出后用 onnxruntime 验证精度是否和 PyTorch 一致数值误差通常在小数点后几位整串准确率不应该有可感知的下降。做这类 OCR 项目一年多了最大的教训就是验证码识别的难点从来不在模型结构而在数据和预处理的一致性。每次换数据集我都强制先把生成器、预处理、评估脚本串成一条流水线跑一遍用二十张同样的图片对比训练和推理两路的输出确认没有偏差再调模型。这套习惯帮我省掉了大量“模型没问题、管线有问题”的排查时间。希望这篇拆解能让你拿到源码后少走几个弯路祝一次跑通。本文还有配套的精品资源点击获取