DannyLuna17/VisionAIRecaptchaSolver

GitHub: DannyLuna17/VisionAIRecaptchaSolver

一个基于 YOLO 视觉模型与无头浏览器的自动化 reCAPTCHA 求解库，用于绕过图像挑战并提取令牌。

Stars: 42 | Forks: 6

# Vision AI reCAPTCHA 求解器

[](https://www.codefactor.io/repository/github/dannyluna17/VisionAIRecaptchaSolver)

使用基于 YOLO 的视觉模型（57k 图像数据集）对 reCAPTCHA v2 和 v3 进行 AI 求解的库。该库提供同步和异步 API，用于自动化图像挑战求解和令牌提取。 https://github.com/user-attachments/assets/3d0de5bd-6bbd-4a1a-bb06-fd7efa9d55fd ## 主要功能 - 支持 reCAPTCHA v2 图像挑战（3x3 选择、3x3 动态、4x4 方形）和 v3 隐形流程 - 同步与异步求解器 API，支持上下文管理器 - 可配置的代理、浏览器路径、超时和检测阈值 - 提供命令行界面（CLI）用于快速测试和自动化 - 无头模式运行 - 自动模型预热和后台初始化 - 首次运行时自动下载模型（分类 + 检测） ## 工作原理 1. `recaptcha-domain-replicator` 启动一个本地 HTTPS 服务器并复制目标 reCAPTCHA 组件。 2. 启动 Chromium 浏览器会话并自动与复选框/挑战进行交互。 3. 下载挑战图像并由 YOLO 模型分析： - 分类模型用于 3x3 挑战 - 检测模型用于 4x4 挑战 4. 求解器点击预测的方块，提交验证并提取令牌。 ### RecaptchaDomainReplicator 使用 本项目使用 `RecaptchaDomainReplicator`（来自 [`recaptcha-domain-replicator`](https://github.com/DannyLuna17/RecaptchaDomainReplicator)）构建本地副本页面并启动浏览器会话。它会创建一个新的复制器，启动本地 HTTPS 服务器，并返回浏览器实例以及令牌句柄。 ## 系统要求 - Python 3.10 或更新版本 - 浏览器：基于 Chromium 的浏览器（Chrome for Testing、Edge） - 用于凭据代理：使用 [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/#stable) 或 Microsoft Edge（较新版本的 Google Chrome 不支持此功能） - 管理员权限（可选）：仅在需要修改主机文件或端口转发时必需 ## 安装 ``` pip install vision-ai-recaptcha-solver ``` 从源码安装（推荐用于开发）： ``` python -m venv .venv .venv\Scripts\activate pip install -e ".[dev]" ``` ## 快速开始（同步） ``` from vision_ai_recaptcha_solver import RecaptchaSolver, SolverConfig config = SolverConfig( timeout=200, # Optional: point to a specific Chromium binary # browser_path="path/to/chrome.exe", # proxy="http://username:password@ip:port", ) with RecaptchaSolver(config) as solver: result = solver.solve( website_key="your_site_key", website_url="https://example.com/your-page-with-recaptcha", ) print(result.token) print(result.captcha_type.value) print(result.time_taken) print(result.attempts) ``` ### 隐形 reCAPTCHA（v3） ``` from vision_ai_recaptcha_solver import RecaptchaSolver, SolverConfig config = SolverConfig(timeout=120) with RecaptchaSolver(config) as solver: result = solver.solve( website_key="your_site_key", website_url="https://example.com/login", is_invisible=True, action="login", is_enterprise=False, api_domain="google.com", cookies=None, user_agent=None, ) print(result.token) ``` ## 异步使用 ``` import asyncio from pathlib import Path from vision_ai_recaptcha_solver import AsyncRecaptchaSolver, SolverConfig async def main(): config = SolverConfig( timeout=180, server_port=8443, download_dir=Path("tmp1"), ) async with AsyncRecaptchaSolver(config) as solver: result = await solver.solve( website_key="your_site_key", website_url="https://example.com/your-page-with-recaptcha", ) print(result.token) asyncio.run(main()) ``` ### 并发异步求解 每个求解器实例应使用不同的 `server_port` 和 `download_dir` 以避免冲突。 ``` import asyncio from pathlib import Path from vision_ai_recaptcha_solver import AsyncRecaptchaSolver, SolverConfig async def solve_one(name: str, config: SolverConfig): async with AsyncRecaptchaSolver(config) as solver: result = await solver.solve( website_key="your_site_key", website_url="https://example.com/your-page-with-recaptcha", ) return name, result async def main(): config_a = SolverConfig(server_port=8443, download_dir=Path("tmp-a")) config_b = SolverConfig(server_port=8444, download_dir=Path("tmp-b")) results = await asyncio.gather( solve_one("A", config_a), solve_one("B", config_b), ) for name, result in results: print(name, result.captcha_type.value, result.time_taken) asyncio.run(main()) ``` ## 命令行界面 该包提供了一个控制台脚本： ``` vision-ai-recaptcha-solver --help ``` 求解验证码： ``` vision-ai-recaptcha-solver solve \ --website-key "your_site_key" \ --website-url "https://example.com/your-page-with-recaptcha" \ --no-headless \ --timeout 180 \ --output json ``` 求解隐形 reCAPTCHA（v3）： ``` vision-ai-recaptcha-solver solve \ --website-key "your_site_key" \ --website-url "https://example.com/login" \ --invisible \ --action "login" ``` 运行针对 Google 测试页面的演示： ``` vision-ai-recaptcha-solver demo ``` ## 配置参考 `SolverConfig` 控制运行时行为和验证。 | 选项 | 默认值 | 描述 | | --- | --- | --- | | `model_path` | `None` | 分类 ONNX 模型路径。如果为 `None`，则自动从 Hugging Face 下载。 | | `detection_model_path` | `None` | 检测模型路径。如果为 `None`，则使用 `yolo12x.pt`。 | | `download_dir` | `Path("tmp")` | 下载图像和临时文件的目录。 | | `server_port` | `8443` | 复制器使用的本地 HTTPS 端口。 | | `proxy` | `None` | 代理 URL，格式为 `protocol://[user:pass@]host:port`。 | | `browser_path` | `None` | Chromium 可执行文件路径。如果省略则自动检测。 | | `headless` | `False` | 以无头模式运行浏览器。 | | `timeout` | `300.0` | 等待令牌提取的最大秒数。 | | `max_attempts` | `12` | 求解挑战的最大尝试次数。 | | `human_delay_mean` | `0.2` | 交互之间的平均延迟（秒），模拟人类行为。 | | `human_delay_sigma` | `0.1` | 人类延迟的标准差。 | | `log_level` | `"WARNING"` | 日志级别（`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`）。 | | `persist_html` | `False` | 保留生成的 HTML 副本。 | | `verbose` | `False` | 启用详细输出。 | | `conf_threshold` | `0.7` | 方块分类置信度阈值。 | | `min_confidence_threshold` | `0.2` | 3x3 挑战中前 3 个方块的最低置信度。 | | `fourth_cell_threshold` | `0.7` | 包含第 4 个单元格的置信度阈值。 | | `detection_conf_threshold` | `0.6` | 4x4 检测的置信度阈值。 | | `default_timeout` | `10.0` | 浏览器操作的默认超时时间。 | | `image_download_retries` | `3` | 图像下载重试次数。 | | `image_download_retry_delay` | `1.0` | 重试之间的基础延迟。 | | `register_signal_handlers` | `True` | 注册 SIGINT/SIGTERM 信号处理程序用于清理。 | | `cleanup_tmp_on_close` | `True` | 求解器关闭时删除 `download_dir`。 | ### 求解参数 `RecaptchaSolver.solve()` 和 `AsyncRecaptchaSolver.solve()` 均支持： - `website_key`：reCAPTCHA 站点密钥（必需） - `website_url`：包含挑战的 URL（必需） - `is_invisible`：是否为隐形/v3（默认 `False`） - `action`：隐形 reCAPTCHA 的操作名称（可选） - `is_enterprise`：是否为企业版 reCAPTCHA（默认 `False`） - `api_domain`：`google.com` 或 `recaptcha.net`（默认 `google.com`） - `bypass_domain_check`：跳过域名验证（默认 `True`） - `use_ssl`：对本地服务器使用 HTTPS（默认 `True`） - `cookies`：求解前设置的可选 cookie 字典列表 - `user_agent`：可选的自定义用户代理字符串 ## 结果对象 `SolveResult` 在成功求解后返回： - `token`：reCAPTCHA 响应令牌 - `cookies`：浏览器会话中的 - `time_taken`：耗时（秒） - `captcha_type`：`dynamic_3x3`、`selection_3x3`、`square_4x4`、`invisible`、`no_challenge`、`unknown` 之一 - `attempts`：求解尝试次数 ## 模型资源 - 分类模型：[`recaptcha_classification_57k.onnx`](https://huggingface.co/DannyLuna/recaptcha-classification-57k) - 基于 [57k 图像数据集](https://huggingface.co/datasets/DannyLuna/recaptcha-57k-images-dataset) 训练。 - 首次使用时自动从 Hugging Face 下载。 - 可通过 `SolverConfig(model_path=...)` 覆盖。 - 检测模型：`yolo12x.pt` - 由 `ultralytics` 加载（不存在时自动下载）。 - 可通过 `SolverConfig(detection_model_path=...)` 覆盖。 ## 示例脚本 仓库包含两个可运行的演示脚本，用于访问 Google 的公共测试页面并显示 令牌提取时间和验证码类型检测。请将它们作为模板使用。 - `demo.py`：使用 `RecaptchaSolver` 的同步求解 - 运行：`python demo.py` - `demo_async.py`：使用 `AsyncRecaptchaSolver` 的异步工作流 - 选项 1：并发运行两次求解 - 选项 2：在后台运行一次求解，同时执行其他任务 - 运行：`python demo_async.py` ## 开发 运行测试： ``` pytest ``` ## 项目结构 - `src/vision_ai_recaptcha_solver/` - 核心库 - `src/vision_ai_recaptcha_solver/captcha/` - 挑战类型处理器 - `src/vision_ai_recaptcha_solver/detector/` - YOLO 模型集成 - `src/vision_ai_recaptcha_solver/models/` - 模型资源 - `tests/` - 单元测试 - `demo.py`、`demo_async.py` - 示例脚本 ## 故障排除 - `browser_path does not exist`：在 `SolverConfig(browser_path=...)` 中传入有效的 Chromium 可执行文件路径。 在 Windows 上，路径应以 `.exe` 结尾。 - `Invalid proxy URL format`：代理必须为 `protocol://[user:pass@]host:port` 格式。支持协议： `http`、`https`、`socks4`、`socks5`。`[]` 表示可选。 - `CaptchaNotFoundError` 或 `ElementNotFoundError`：确认 `website_url` 指向一个渲染了 reCAPTCHA iframe 的页面，并且 `website_key` 与该页面匹配。 - `Port or temp directory conflicts`：同时运行多个求解器时，请设置唯一的 `server_port` 和 `download_dir` 值，或不显式设置这些字段以让它们自动选择。 ## 法律与负责任使用 RecaptchaDomainReplicator 仅供教育和研究用途。请负责任地使用并遵守所有适用的法律和服务条款。 ## 许可证 本项目根据 [MIT 许可证](LICENSE) 授权。