Cách giải reCAPTCHA v3 trong LlamaIndex Agents

TL;DR

• Bao bọc hàm CapSolver bất đồng bộ có độ rộng hẹp bằng LlamaIndex FunctionTool; không tiết lộ khóa API, thông tin xác thực proxy, cookie hoặc đối tượng trình duyệt thô cho mô hình.
• Đọc websiteURL, websiteKey và pageAction từ quy trình được ủy quyền đang chạy. Không bao giờ để đại diện tạo ra chúng.
• Sử dụng ReCaptchaV3TaskProxyLess cho chế độ token máy chủ proxy hoặc ReCaptchaV3Task khi phải cung cấp proxy được phê duyệt.
• Xem xét token được trả về là dữ liệu thời gian chạy ngắn hạn, gửi nó ngay lập tức thông qua mã tin cậy và xác minh trạng thái ứng dụng trước khi tiếp tục.
• Giới hạn số lần giải quyết, định tuyến các lỗi lặp lại đến xem xét của người vận hành và chỉ ghi lại dữ liệu mô tả đã bị che đi.

Giới thiệu

Một trình giải reCAPTCHA v3 đáng tin cậy của LlamaIndex là công cụ phục hồi có kiểu, không phải khả năng duyệt web không giới hạn. Đại diện LlamaIndex nên quyết định khi một nhiệm vụ được phê duyệt bị chặn, trong khi mã tin cậy xác minh mục tiêu, đọc chính xác site key và hành động từ trang hiện tại, gọi CapSolver, gửi token và xác minh trạng thái mong đợi. Sự phân tách này quan trọng vì reCAPTCHA v3 chạy mà không cần hộp kiểm tương tác và đánh giá yêu cầu cụ thể hành động. Một token được tạo cho URL sai hoặc pageAction có thể bị từ chối ngay cả khi cuộc gọi API thành công. Hướng dẫn này cho thấy các trường nhiệm vụ chính thức của CapSolver, FunctionTool bất đồng bộ của LlamaIndex, kiểm soát chính sách phía máy chủ, xử lý chế độ phiên, kết quả có cấu trúc, thử lại có giới hạn, xác minh trình duyệt và khả năng quan sát trong sản xuất.

Hiểu ranh giới công cụ LlamaIndex

Tài liệu công cụ chính thức của LlamaIndex giải thích rằng FunctionTool bao bọc các hàm Python đồng bộ hoặc bất đồng bộ và có thể suy ra lược đồ hàm. Nó cũng lưu ý rằng tên công cụ, mô tả và mô tả tham số mạnh mẽ ảnh hưởng đến cách mô hình chọn và gọi một công cụ.

Đối với trình giải reCAPTCHA v3 của LlamaIndex, hãy giữ cho công cụ hẹp:

Đại diện LlamaIndex
    ↓ chọn một công cụ có kiểu
FunctionTool bao bọc
    ↓ xác minh tham chiếu tin cậy
Executor CapSolver
    ↓ trả về giải pháp có thời hạn ngắn
Dịch vụ trình duyệt
    ↓ gửi và xác minh
Quy trình LlamaIndex tiếp tục

Tài liệu CapSolver AI Agents mô tả cùng một phân chia lao động: mô hình quyết định, trình thích ứng tiết lộ lược đồ và lõi thực hiện các nhiệm vụ được hỗ trợ.

Biết các tham số reCAPTCHA v3 cần thiết

Tài liệu reCAPTCHA v3 của CapSolver định nghĩa bốn loại nhiệm vụ:

Các trường cơ bản là:

Hướng dẫn reCAPTCHA v3 của Google mô tả tên hành động là một phần của tích hợp. Hành động quan sát trên trang nên được giữ nguyên.

Bài viết reCAPTCHA của CapSolver chứa các hướng dẫn khắc phục sự cố và triển khai bổ sung.

Không để mô hình tạo ra tham số mục tiêu

Truyền tham chiếu đến trạng thái phía máy chủ, không phải giá trị tùy ý.

from dataclasses import dataclass
from urllib.parse import urlparse

@dataclass(frozen=True)
class CaptchaContext:
    context_id: str
    website_url: str
    website_key: str
    page_action: str
    enterprise: bool = False
    proxy_profile: str | None = None
    session_mode: bool = False

TRUSTED_CONTEXTS: dict[str, CaptchaContext] = {}
ALLOWED_HOSTS = {"staging.example.com", "portal.example.org"}


def get_trusted_context(context_id: str) -> CaptchaContext:
    context = TRUSTED_CONTEXTS.get(context_id)
    if context is None:
        raise ValueError("Unknown CAPTCHA context")

    host = urlparse(context.website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Target is outside the approved host policy")

    if not context.website_key or not context.page_action:
        raise ValueError("Trusted context is missing required v3 parameters")

    return context

Mô hình chỉ nhận được context_id. Dịch vụ trình duyệt sở hữu trang hiện tại, site key, hành động và liên kết proxy.

Cài đặt các gói được hỗ trợ

Tài liệu CapSolver Agent do người dùng cung cấp chỉ ra rằng cần cài đặt gói core trước khi cài đặt gói agent:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install llama-index-core

Thiết lập khóa API trong môi trường chạy:

export CAPSOLVER_API_KEY="your-capsolver-api-key"

Không dán khóa vào lời nhắc, notebook, tập dữ liệu kịch bản hoặc dấu vết. Câu hỏi thường gặp về AI và tự động hóa của CapSolver giải thích mô hình tích hợp.

Tạo executor CapSolver phía máy chủ

capsolver-agent cung cấp create_executor() cho ranh giới mô hình–adapter–core.

import os
from capsolver_agent.schema import create_executor

executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=120,
)

Executor phân phát solve_captcha đến CapSolver Core và trả về kết quả có cấu trúc. Giữ nó trong mã ứng dụng tin cậy.

Viết hàm giải quyết bất đồng bộ hẹp

Hàm giải quyết ngữ cảnh tin cậy, chọn loại nhiệm vụ chính thức và gọi executor.

from typing import Annotated

async def solve_recaptcha_v3(
    context_id: Annotated[
        str,
        "ID không rõ ràng cho ngữ cảnh CAPTCHA trình duyệt hiện tại được phê duyệt"
    ],
) -> dict:
    """Giải reCAPTCHA v3 cho ngữ cảnh trình duyệt được phê duyệt.

    Chỉ sử dụng khi quy trình hiện tại báo cáo điểm kiểm tra reCAPTCHA v3 được hỗ trợ. Không bao giờ đoán hoặc sửa đổi URL, site key hoặc hành động mục tiêu.
    """
    context = get_trusted_context(context_id)

    captcha_type = (
        "reCaptchaV3Enterprise"
        if context.enterprise
        else "reCaptchaV3"
    )

    args = {
        "captcha_type": captcha_type,
        "website_url": context.website_url,
        "website_key": context.website_key,
        "page_action": context.page_action,
    }

    if context.proxy_profile:
        args["proxy"] = resolve_proxy(context.proxy_profile)

    result = await executor.execute("solve_captcha", args)
    if not result.get("success"):
        return {
            "success": False,
            "context_id": context_id,
            "error": normalize_error(result.get("error")),
        }

    solution = result.get("solution") or {}
    token = solution.get("token")
    if not token:
        return {
            "success": False,
            "context_id": context_id,
            "error": "solution did not contain a token",
        }

    receipt = await submit_solution_and_verify(
        context_id=context_id,
        token=token,
        session_cookie=extract_session_cookie(solution),
    )

    return {
        "success": receipt["verified"],
        "context_id": context_id,
        "verified": receipt["verified"],
        "next_state": receipt["next_state"],
    }

resolve_proxy, normalize_error và submit_solution_and_verify là các trình thích ứng chính sách do ứng dụng sở hữu. Chúng không nên hiển thị với mô hình.

Bao bọc hàm bằng LlamaIndex FunctionTool

from llama_index.core.tools import FunctionTool

tool = FunctionTool.from_defaults(
    async_fn=solve_recaptcha_v3,
    name="solve_recaptcha_v3",
    description=(
        "Giải reCAPTCHA v3 cho ngữ cảnh trình duyệt được phê duyệt hiện tại. "
        "Đầu vào phải là một context_id không rõ ràng được cung cấp bởi dịch vụ trình duyệt. "
        "Không gọi cho các trang không được hỗ trợ hoặc các máy chủ không được phê duyệt."
    ),
)

Kiểm tra lược đồ trong quá trình phát triển:

schema = tool.metadata.get_parameters_dict()
print(schema)

Điều này tuân theo mẫu FunctionTool đã được tài liệu hóa của LlamaIndex trong khi giảm bề mặt tham số của mô hình xuống một định danh không rõ ràng.

Gắn công cụ với đại diện LlamaIndex

from llama_index.core.agent.workflow import FunctionAgent

agent = FunctionAgent(
    llm=llm,
    tools=[tool],
    system_prompt=(
        "Chỉ hoạt động các quy trình trình duyệt được phê duyệt. Khi dịch vụ trình duyệt "
        "báo cáo điểm kiểm tra reCAPTCHA v3 được hỗ trợ, gọi "
        "solve_recaptcha_v3 với context_id được cung cấp. Gọi một lần. "
        "Tiếp tục chỉ khi verified=true; nếu không, yêu cầu xem xét."
    ),
)

Chạy quy trình với quan sát trình duyệt tin cậy:

response = await agent.run(
    "Quy trình thử nghiệm được phê duyệt đang chờ tại điểm kiểm tra reCAPTCHA v3. "
    "Sử dụng context_id ctx_7f19 và tiếp tục chỉ khi verified."
)

Đại diện không bao giờ thấy khóa API, proxy thô, token hoặc cookie.

Đọc pageAction từ trang đang chạy

Một trình giải reCAPTCHA v3 đáng tin cậy của LlamaIndex nên không tái sử dụng hành động chung như login trên mọi mục tiêu. Dịch vụ trình duyệt nên đọc tích hợp hiện tại của mục tiêu.

async def collect_v3_context(page, context_id: str) -> CaptchaContext:
    website_url = page.url
    host = urlparse(website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Unapproved target")

    values = await page.evaluate("""
    () => {
      const scripts = Array.from(document.scripts)
        .map(s => s.textContent || '')
        .join('\n');

      const siteKey =
        document.querySelector('[data-sitekey]')?.getAttribute('data-sitekey')
        || null;

      const actionMatch = scripts.match(
        /grecaptcha(?:\.enterprise)?\.execute\([^,]+,\s*\{\s*action:\s*['\"]([^'\"]+)/
      );

      return {
        siteKey,
        pageAction: actionMatch ? actionMatch[1] : null,
        enterprise: scripts.includes('grecaptcha.enterprise')
      };
    }
    """)

    if not values["siteKey"] or not values["pageAction"]:
        raise RuntimeError("Could not read required v3 parameters")

    return CaptchaContext(
        context_id=context_id,
        website_url=website_url,
        website_key=values["siteKey"],
        page_action=values["pageAction"],
        enterprise=values["enterprise"],
    )

Đối với tích hợp phức tạp, sử dụng hướng dẫn mở rộng CapSolver để kiểm tra tham số trang trong quá trình phát triển và kiểm thử được phê duyệt.

Xử lý chế độ phiên một cách cẩn trọng

Tài liệu chính thức v3 của CapSolver ghi chú rằng một số mục tiêu có thể trả về recaptcha-ca-t khi isSession được kích hoạt. Xem xét nó là dữ liệu phiên ngắn hạn, nhạy cảm.

SESSION_KEYS = {
    "recaptcha-ca-t",
    "recaptcha_ca_t",
}


def extract_session_cookie(solution: dict) -> str | None:
    raw = solution.get("raw") or {}
    for key in SESSION_KEYS:
        value = solution.get(key) or raw.get(key)
        if value:
            return value
    return None

Chỉ kích hoạt chế độ phiên khi tích hợp mục tiêu yêu cầu và quy trình được phê duyệt. Lưu giá trị trong bộ nhớ quy trình hoặc lưu trữ mã hóa ngắn hạn; không bao giờ đặt nó trong ngữ cảnh LlamaIndex.

Gửi và xác minh trong mã trình duyệt tin cậy

Hướng dẫn xác minh phía máy chủ của Google giải thích rằng một trang xác minh token trên backend của nó. Hệ thống tự động của bạn nên gửi token thông qua cùng luồng ứng dụng được phê duyệt, sau đó xác minh trạng thái trang kết quả.

async def submit_solution_and_verify(
    context_id: str,
    token: str,
    session_cookie: str | None,
) -> dict:
    browser_state = BROWSER_CONTEXTS[context_id]
    page = browser_state.page

    if session_cookie:
        await browser_state.context.add_cookies([{
            "name": "recaptcha-ca-t",
            "value": session_cookie,
            "domain": urlparse(page.url).hostname,
            "path": "/",
            "secure": True,
        }])

    await page.evaluate(
        """({ token }) => {
          let input = document.querySelector(
            'textarea[name="g-recaptcha-response"]'
          );
          if (!input) {
            input = document.createElement('textarea');
            input.name = 'g-recaptcha-response';
            input.style.display = 'none';
            document.body.appendChild(input);
          }
          input.value = token;
          input.dispatchEvent(new Event('change', { bubbles: true }));
        }""",
        {"token": token},
    )

    await trigger_trusted_callback(page, browser_state.callback_name)

    try:
        await page.locator(browser_state.success_selector).wait_for(
            state="visible",
            timeout=15000,
        )
        return {"verified": True, "next_state": "continue"}
    except Exception:
        return {"verified": False, "next_state": "operator_review"}

Khám phá callback là cụ thể cho mục tiêu. Lưu nó trong ngữ cảnh trình duyệt tin cậy thay vì yêu cầu mô hình tạo JavaScript.

Hướng dẫn API phản hồi reCAPTCHA của CapSolver giải thích các mẫu xử lý phản hồi phổ biến.

Áp dụng một lần và trạng thái rõ ràng

from enum import Enum

class RecoveryState(str, Enum):
    DETECTED = "detected"
    SOLVING = "solving"
    VERIFIED = "verified"
    REVIEW_REQUIRED = "review_required"

ATTEMPTS: dict[str, int] = {}

async def guarded_solve(context_id: str) -> dict:
    attempts = ATTEMPTS.get(context_id, 0)
    if attempts >= 1:
        return {
            "success": False,
            "context_id": context_id,
            "next_state": RecoveryState.REVIEW_REQUIRED,
            "error": "recovery budget exhausted",
        }

    ATTEMPTS[context_id] = attempts + 1
    return await solve_recaptcha_v3(context_id)

Một cuộc gọi lặp lại thường cho thấy tham số lỗi thời, hành động sai, trạng thái trình duyệt hết hạn hoặc đường dẫn không hỗ trợ. Dừng vòng lặp và thu thập dữ liệu chẩn đoán.

Ghi lại quan sát đã che đi

Ghi lại dữ liệu mô tả hoạt động, không phải bí mật.

from datetime import datetime, timezone


def recovery_event(context: CaptchaContext, result: dict) -> dict:
    return {
        "event": "recaptcha_v3_recovery",
"context_id": context.context_id,
        "host": urlparse(context.website_url).hostname,
        "page_action": context.page_action,
        "enterprise": context.enterprise,
        "session_mode": context.session_mode,
        "success": result.get("success", False),
        "next_state": str(result.get("next_state")),
        "observed_at": datetime.now(timezone.utc).isoformat(),
    }

Không ghi lại websiteKey nếu chính sách của bạn coi nó là cấu hình, và không bao giờ ghi lại các token giải pháp, cookie phiên, khóa API, proxy thô hoặc HTML trang riêng đầy đủ.

Câu hỏi thường gặp về lỗi của CapSolver https://www.capsolver.com/faq/errors-and-troubleshooting có thể giúp chuẩn hóa các danh mục lỗi.

Mã thưởng: Sử dụng mã WEBS tại Bảng điều khiển CapSolver để nhận thêm 5% thưởng cho mỗi lần nạp tiền.

Tóm tắt so sánh

Mẫu ngữ cảnh không trong suốt cung cấp cho tác nhân LlamaIndex đủ quyền kiểm soát để yêu cầu phục hồi mà không để nó ghi đè các tham số nhạy cảm hoặc cụ thể cho mục tiêu.

Danh sách kiểm tra sản xuất

• Lưu khóa API và hồ sơ proxy trong kho lưu trữ bí mật.
• Cho phép chỉ các máy chủ được phê duyệt và mục đích công việc chính xác.
• Đọc websiteKey và pageAction từ trang hiện tại đang chạy.
• Đảm bảo cài đặt Doanh nghiệp và phiên làm việc phù hợp với tích hợp mục tiêu.
• Gửi token ngay lập tức thông qua mã trình duyệt đáng tin cậy.
• Xác minh trạng thái ứng dụng mong đợi trước khi tiếp tục.
• Cho phép một lần thử giải quyết, sau đó định tuyến đến xem xét của nhân viên.
• Gạch bỏ token, cookie, proxy và thông tin xác thực khỏi các bản ghi.
• Kiểm tra lại sơ đồ công cụ mỗi khi SDK hoặc lời nhắc thay đổi.

Trang sản phẩm của CapSolver https://www.capsolver.com/products liệt kê các danh mục giải pháp được hỗ trợ, trong khi blog AI của CapSolver https://www.capsolver.com/blog/ai đề cập đến các mẫu tích hợp liên quan đến tác nhân.

Sử dụng có trách nhiệm

Sử dụng quy trình này chỉ trên các ứng dụng bạn sở hữu, kiểm tra hoặc có sự cho phép rõ ràng để tự động hóa. Khả năng kỹ thuật không cấp quyền truy cập. Tôn trọng các điều khoản, giới hạn tốc độ, yêu cầu bảo mật và ranh giới xác thực. Không sử dụng công cụ tác nhân để truy cập tài khoản riêng tư, hồ sơ bị hạn chế hoặc quy trình của bên thứ ba mà không có sự cho phép. Đặt các hành động có tác động cao như gửi, thanh toán, đặt chỗ và thay đổi tài khoản phía sau bước chính sách và xác nhận riêng biệt.

Kết luận

Một công cụ giải quyết reCAPTCHA v3 cho LlamaIndex sản xuất nên tiết lộ một hàm phục hồi hẹp, có kiểu. Dịch vụ trình duyệt cung cấp ID ngữ cảnh đáng tin cậy, mã phía máy chủ bảo tồn URL chính xác, khóa trang, hành động, chế độ Doanh nghiệp và chính sách proxy, CapSolver trả về giải pháp có thời hạn ngắn, và trình duyệt xác minh trạng thái mong đợi trước khi tác nhân tiếp tục.

Bắt đầu tích hợp LlamaIndex được phê duyệt với CapSolver, kiểm tra nó trên quy trình thử nghiệm được kiểm soát và thêm các ràng buộc tham số và các tuyên bố thử lại trước khi sản xuất.

Câu hỏi thường gặp

reCAPTCHA v3 có yêu cầu nhấp vào hộp kiểm không?

Không. reCAPTCHA v3 dựa trên điểm số và thường chạy nền. Quy trình phải bảo tồn khóa trang, URL và hành động của mục tiêu.

Tại sao pageAction quan trọng?

Hành động xác định thao tác đang được đánh giá, chẳng hạn như đăng nhập hoặc gửi. Sử dụng hành động chính xác được đọc từ tích hợp đang chạy thay vì giá trị chung chung.

Tác nhân LlamaIndex có nên nhận token không?

Ưu tiên gửi từ phía máy chủ và chỉ trả về trạng thái đã xác minh. Token là dữ liệu thời gian chạy có thời hạn ngắn và không nên đi vào ngữ cảnh mô hình hoặc nhật ký.

Khi nào nên bật chế độ phiên?

Bật chế độ chỉ khi mục tiêu được ủy quyền yêu cầu giá trị phiên trả về. Lưu trữ giá trị đó trong bộ nhớ chạy có mã hóa thời gian ngắn.

Điều gì nên xảy ra sau khi thử thất bại?

Dừng lại sau số lần đã cấu hình, ghi lại sự kiện chẩn đoán đã gạch bỏ, làm mới các tham số trang đáng tin cậy nếu cần thiết và định tuyến quy trình đến xem xét của nhân viên.