• 人工智能
• 计算机视觉

captcha-recognizer 是一款基于深度学习的滑块验证码识别库：给它一张带缺口的验证码背景图或全图，它就能自动识别出滑块缺口的位置，返回缺口坐标[x1, y1, x2, y2]和置信度。支持pip install captcha-recognizer一键安装，可本地运行，也可部署为 HTTP API 服务。本文用 5 分钟带你完成安装，并附上一份最常见的依赖冲突避坑清单。

1. captcha-recognizer 能识别什么

它内置了一个通用的缺口检测模型（ONNX 格式，随包自带），识别逻辑位于 slider.py。支持的验证码类型：

模型文件在 slider.onnx，安装后无需额外下载任何模型。下图是识别效果：蓝色框标出缺口位置，标签显示置信度 0.94。

💡 除了 pip 本地调用，项目还提供 HTTP API 的服务器部署方案，适合团队协作使用。

2. 环境要求与一键安装步骤

版本要求

• Python >= 3.6.0（Linux / Windows / macOS 均可）
• 依赖只有 3 个，见 requirements.txt：opencv-python、shapely、onnxruntime，执行 pip 安装时会自动装好

安装命令

打开终端，一条命令搞定：

pip install captcha-recognizer

建议先创建虚拟环境，避免污染全局 Python 环境：

python -m venv myenv # Windows 激活 myenv\Scripts\activate # Linux / macOS 激活 source myenv/bin/activate pip install captcha-recognizer

安装完成后可以用 predict.py 这类示例脚本快速验证是否可用。

3. 3 行代码跑通第一次滑块识别

from captcha_recognizer.slider import Slider box, confidence = Slider().identify(source='captcha.png', show=True) print(f'缺口坐标: {box}') print('置信度', confidence)

参数说明：

• source：待识别图片，支持文件路径、bytes字节流、numpy.ndarray
• show：为True时会弹窗展示识别效果图；线上环境请保持默认False
• 返回值：box为缺口左上角和右下角坐标，confidence为置信度（0~1，默认阈值 0.5）

更多示例可参考 README.md 中的使用示例章节。

4. 依赖避坑清单：90% 的安装问题都出在这

⚠️ 坑一：opencv-python 与 numpy 版本冲突（最常见）

opencv-python编译时绑定的 numpy 版本与实际安装的 numpy 不一致时，会出现ImportError或 cv2 导入报错。README 中给出的两组已验证兼容组合，任选一组锁定版本即可：

# 组合 1 pip install opencv-python==4.12.0.88 numpy==2.2.6 # 组合 2 pip install opencv-python==4.8.0.74 numpy==1.23.0

📌 如果项目里其他依赖锁定了某个 numpy 版本，优先选择与它接近的 opencv-python 版本，不要随意pip install -U升级。

⚠️ 坑二：从源码复制代码导致模型文件缺失

Slider初始化时会定位captcha_recognizer/models/slider.onnx。如果你只是把几个.py文件拷进项目，而不走pip install captcha-recognizer，会因找不到模型文件而报错。推荐始终从 PyPI 安装，模型文件会随包一起分发。

⚠️ 坑三：GPU 与 CPU 环境混淆

推理会话默认按设备自动选择CUDAExecutionProvider或CPUExecutionProvider（见 slider.py 中InferenceSession的初始化逻辑）。纯 CPU 环境直接用默认的onnxruntime即可，无需安装onnxruntime-gpu，装错反而容易启动失败。

5. 进阶：滑块偏移量怎么算

某些验证码的滑块初始位置并非紧贴图片左边框，存在固定偏移量 offset，实际滑块距离 = 缺口x1坐标 − offset。offset 固定的话用截图工具量一次即可；动态偏移可调用identify_offset方法自动获取，详见 README.md 的注意事项章节。

此外，如果前端对图片做了缩放，滑块距离也要按渲染缩放比例换算，避免"识别准了、拖偏了"的假失败。

总结：5 分钟上手清单

1. ✅ 确认 Python >= 3.6，创建虚拟环境
2. ✅ 执行pip install captcha-recognizer
3. ✅ 用Slider().identify(source='你的图.png')拿到缺口坐标
4. ✅ 遇到 cv2 报错，按上文锁定 opencv-python + numpy 兼容版本组合

项目采用 MIT 许可，MIT 协议自由开源，版本演进记录可查 HISTORY.md。本文内容仅供学习交流，请勿用于非法用途。

• 人工智能
• 计算机视觉