简介：这是面向 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 而不是直接调现成 OCR

2.1 技术选型：CRNN + CTC 是验证码场景的最优解

先说结论：验证码这种 4 到 6 个字符、带干扰线、可能扭曲粘连的短文本，通用 OCR 引擎和重型检测识别框架都不好用。Tesseract 的优势在长文本印刷体，短验证码上字符间距一旦变化，它的字符切分逻辑就乱了。PaddlePaddle 系的 OCR 走的是检测加识别两段式，处理文档扫描件很强，但遇到小尺寸、背景干扰严重的验证码，文本检测框先飘掉一半，后面识别再准也救不回来。

CRNN 加 CTC 的组合恰好踩在验证码的痛点上。CRNN 的 CNN 部分负责把干扰线、噪点、扭曲这些视觉噪声压下去，BiLSTM 负责学习字符序列顺序，CTC loss 解决的是最核心的“字符边界未知”问题——训练时只需要给整张图和完整字符串，不需要标注每个字符的坐标或宽度，模型自己学会对齐。相比传统“先切分再分类”的字符级 CNN 方案，它不会因为字符粘连就切歪，端到端训练误差只累积一次。

我实际对比过四种方案在相同验证码集上的表现：

顺带提一句，有人问为什么不用 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（通道×高×宽）为例，前向传播过程中张量形状的变化如下表：

图像的宽从 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), charset=CHARSET): n = random.randint(*length) return "".join(random.choice(charset) for _ in range(n)) def gen_one(width=192, height=64): 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)], fill=random_color(), width=1) # 渲染字符，x 方向步长随机，制造粘连和间距变化 font = ImageFont.truetype(random.choice(FONTS), size=36) x = 10 for ch in text: draw.text((x, random.randint(8, 20)), ch, font=font, fill=random_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(radius=random.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, hidden=256): super().__init__() self.cnn = nn.Sequential( nn.Conv2d(3, 64, 3, padding=1), nn.BatchNorm2d(64), nn.ReLU(inplace=True), nn.MaxPool2d(2, 2), # 高 64 -> 32，宽 192 -> 96 nn.Conv2d(64, 128, 3, padding=1), nn.BatchNorm2d(128), nn.ReLU(inplace=True), nn.MaxPool2d(2, 2), # 高 32 -> 16，宽 96 -> 48 nn.Conv2d(128, 256, 3, padding=1), nn.BatchNorm2d(256), nn.ReLU(inplace=True), nn.Conv2d(256, 256, 3, padding=1), nn.BatchNorm2d(256), nn.ReLU(inplace=True), nn.MaxPool2d((2, 1)), # 高 16 -> 8，宽 48 不变 nn.Conv2d(256, 512, 3, padding=1), nn.BatchNorm2d(512), nn.ReLU(inplace=True), nn.Conv2d(512, 512, 3, padding=1), nn.BatchNorm2d(512), nn.ReLU(inplace=True), ) # 最终输出：512 通道，宽 48，高 8 self.lstm = nn.LSTM(512, hidden, num_layers=2, bidirectional=True, batch_first=True) 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(dim=2) # 高度压缩：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(dim=2)把高度方向压成 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, blank=62, charset=CHARSET): """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”里的两个 O，CTC 会把它误合并成一个。解决办法要么在生成器里禁止相邻重复字符，要么训练数据里确保这种情况足够多，让模型学会用 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"

训练的损失函数用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_classes=num_classes, hidden=hidden).to(device) criterion = nn.CTCLoss(blank=num_classes - 1, zero_infinity=True) optimizer = torch.optim.Adam(model.parameters(), lr=lr) scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs) train_loader = DataLoader(CaptchaDataset(mode="train"), batch_size=batch_size, shuffle=True) 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), dtype=torch.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], dtype=torch.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(f"epoch {epoch+1}/{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_infinity=True是保险开关，防止某个 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 换字符集与换验证码风格

最常见的改造是字符集调整。比如业务验证码只有四则运算，需要识别“12+34=”，那字符集就得加上运算符、等号，甚至小数点。改动点只有两个：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, key=lambda b: b[2] * b[3]) return page_img[y:y+h, x:x+w]

裁剪后同样走predict里面的预处理函数。注意缩放要等比，不要拉伸变形，非等比缩放会让字符长宽比失真，尤其是细字体，失真后误识别率明显上升。

6.3 ONNX 部署与后续维护习惯

导出脚本里用torch.onnx.export，把 batch 维度设为动态，高度和宽度固定死。验证码识别场景没有多尺寸输入需求，动态高度会让 onnxruntime 多出一次内部 Resize，反而增加耗时。导出后用 onnxruntime 验证精度是否和 PyTorch 一致，数值误差通常在小数点后几位，整串准确率不应该有可感知的下降。

做这类 OCR 项目一年多了，最大的教训就是：验证码识别的难点从来不在模型结构，而在数据和预处理的一致性。每次换数据集，我都强制先把生成器、预处理、评估脚本串成一条流水线跑一遍，用二十张同样的图片对比训练和推理两路的输出，确认没有偏差再调模型。这套习惯帮我省掉了大量“模型没问题、管线有问题”的排查时间。希望这篇拆解能让你拿到源码后少走几个弯路，祝一次跑通。

本文还有配套的精品资源，点击获取