• 人工智能
• 计算机视觉

captcha-recognizer 是一个开源的滑块验证码识别库，只需一行代码调用Slider().identify()，即可自动定位验证码图片中的滑块缺口，并返回缺口坐标与置信度。本指南带你通过 pip 快速安装，完整掌握 identify() 方法的参数、返回值，以及滑块偏移量的换算技巧，轻松实现滑块缺口坐标定位。

一、identify() 方法能做什么

captcha-recognizer 内置基于深度学习训练的通用缺口检测模型，模型文件 slider.onnx 随 pip 包一起分发，安装即可用，无需额外下载或训练。它支持两类输入：

• 单缺口背景图：不含滑块的验证码背景图
• 验证码全图：包含滑块与背景图的整张截图

调用 identify() 方法 后，它会自动完成图片预处理、模型推理与结果筛选，返回两个值：

下面这张来自仓库示例的图片，就是一张典型的单缺口滑块验证码背景图，缺口位于画面中部：

二、3 步完成安装与首次识别

1. pip 一键安装

pip install captcha-recognizer

依赖要求很简单，Python >= 3.6，以及 requirements.txt 中声明的opencv-python、shapely、onnxruntime，跨平台支持 Linux / Windows / macOS。

2. 一行代码识别缺口

from captcha_recognizer.slider import Slider box, confidence = Slider().identify(source='example.png') print(f'缺口坐标: {box}') # 例如 [154.2, 98.1, 176.5, 121.3] print('置信度', confidence) # 例如 0.93

仓库根目录的 predict.py 就是一个完整的批量识别示例脚本，可以直接运行体验。

3. 查看识别效果

identify()的show参数默认关闭。本地调试时传入show=True，会弹出 OpenCV 窗口显示缺口识别结果——下图中蓝色矩形框即定位到的滑块缺口位置，0.94为置信度：

想直观感受整个识别流程，还可以查看仓库中的动图演示 online-demo.gif。

三、identify() 参数完整说明

💡 关于source：内部由 image_to_array() 统一转换，所以无论是从磁盘读路径、接收 HTTP 请求的字节流，还是直接传内存中的图片数组，都能直接识别。

四、滑块偏移量：从缺口坐标到实际拖动距离

这是新手最容易踩的坑：box里的x1是缺口的坐标，而滑块拖动距离还要考虑滑块自身的初始偏移。

实际拖动距离 = x1 - offset

以 offset 为 8 的例子：识别得 x1 = 154，则实际应拖动 154 - 8 =146像素。

• 偏移量固定的验证码：用截图或测量工具量一次滑块距图片边框的像素即可；
• 偏移量动态的验证码：用姊妹方法 identify_offset() 自动获取：

offset, confidence = Slider().identify_offset(source='example.png') print(f'偏移量: {offset}')

五、常见问题排查与注意事项

• 识别结果为空（box 为 []、confidence 为 0）：说明图片中没有可信的缺口，常见于图片不是滑块验证码、缺口被模糊处理或图片过小。可适当调低conf再试。
• opencv-python 与 numpy 版本冲突：建议使用官方验证过的兼容组合：opencv-python==4.12.0.88 + numpy==2.2.6，或opencv-python==4.8.0.74 + numpy==1.23.0。
• 前端渲染缩放的图片：如果验证码在页面上被缩放显示，实际拖动距离还需按渲染比例等比换算后再拖动。
• 服务器部署：show必须保持False，否则无图形界面环境下会报错；如需服务化，可参考作者的 HTTP API 方案在服务器部署识别接口。
• 合规提示：本项目仅供学习与研究使用，请遵守目标网站的服务条款，严禁用于任何非法用途。

六、identify() 快速参考

掌握以上几点，你就能用一行代码完成滑块缺口识别：安装 → 调用identify()→ 用x1 - offset换算出最终拖动距离。更多版本演进细节可查看 HISTORY.md，中文说明见 README.md。

• 人工智能
• 计算机视觉