Cách giải quyết Cloudflare Turnstile trong các agent LlamaIndex

TL;DR

• Bao bọc hàm CapSolver Turnstile hẹp bằng LlamaIndex FunctionTool.from_defaults().
• Sử dụng tác vụ được tài liệu hóa AntiTurnstileTaskProxyLess với URL trang chính xác và khóa trang web.
• Gửi action và cdata chỉ khi trang được cấp phép hiển thị các giá trị tùy chọn này.
• Trả lại token giải pháp cho mã trình duyệt xác định thay vì lưu trữ nó trong bộ nhớ agent dài hạn.
• Thêm kiểm tra tên miền được phê duyệt, một lần thử lại giới hạn, ghi nhật ký bị che đi, và nhánh xem xét của con người trước khi triển khai.

Giới thiệu

Cách an toàn nhất để giải Cloudflare Turnstile trong các agent LlamaIndex là phơi bày CapSolver như một công cụ hàm có kiểu dữ liệu, đồng thời giữ trạng thái trình duyệt, bí mật và kiểm tra cấp phép bên ngoài mô hình. LlamaIndex có thể quyết định rằng một thử thách được hỗ trợ chặn bước tiếp theo được phê duyệt, nhưng Python xác định nên kiểm tra mục tiêu, xây dựng tác vụ được tài liệu hóa AntiTurnstileTaskProxyLess, và trả lại token giải pháp có thời hạn ngắn cho bộ điều khiển trình duyệt. Điều này tuân theo kiến trúc agent AI của CapSolver: mô hình quyết định, trình điều phối công cụ xác định hành động, và lớp giải quyết cốt lõi thực hiện nó. Hướng dẫn này hiển thị các trường Turnstile chính xác, triển khai FunctionTool của LlamaIndex, quy trình FunctionAgent, chuyển giao token an toàn, thử lại giới hạn, và các biện pháp sử dụng có trách nhiệm cho QA, RPA và tự động hóa trình duyệt được phép.

Tại sao FunctionTool của LlamaIndex là lựa chọn phù hợp?

LlamaIndex coi công cụ là API dành cho agent. Tài liệu chính thức về công cụ của nó giải thích rằng FunctionTool có thể bao bọc các hàm Python đồng bộ hoặc bất đồng bộ và suy ra lược đồ từ chữ ký hàm. Tên công cụ, mô tả, chú thích và văn bản mô tả ảnh hưởng đến việc mô hình gọi nó.

Giới hạn này hữu ích cho việc phục hồi thử thách vì mô hình không bao giờ nên tạo mã giải quyết tùy ý hoặc nhận khóa API CapSolver. Một hàm hẹp có thể chấp nhận chỉ URL trang được phê duyệt, khóa trang web Turnstile và dữ liệu mô tả widget tùy chọn.

Bài viết trên blog AI của CapSolver đề cập đến tích hợp agent, trong khi FAQ AI và tự động hóa của CapSolver giải thích cách phục hồi thử thách bổ sung cho một stack agent hiện có.

Hiểu tác vụ Turnstile chính thức

Tài liệu Cloudflare Turnstile của CapSolver xác định AntiTurnstileTaskProxyLess. Tác vụ yêu cầu websiteURL và websiteKey. Dữ liệu mô tả tùy chọn có thể bao gồm các giá trị action và cdata của widget.

CapSolver tự động hỗ trợ các trình bày Turnstile được quản lý, không tương tác và ẩn, vì vậy tác vụ không cần một loại con. Tài liệu Turnstile của Cloudflare mô tả widget và quy trình xác minh phía máy chủ được trang chủ sử dụng.

Cài đặt LlamaIndex và CapSolver

pip install llama-index llama-index-llms-openai capsolver

Đối với kiến trúc agent CapSolver rộng hơn được cung cấp trong tài liệu người dùng, hãy cài đặt các gói cốt lõi và agent:

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

Cấu hình bí mật bên ngoài prompt:

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Ví dụ SDK trực tiếp dưới đây sử dụng các trường tác vụ Turnstile chính xác. LlamaIndex cung cấp vỏ khung; CapSolver thực hiện tác vụ.

Tạo hàm Turnstile có kiểu dữ liệu

Xác minh URL trước khi gửi đến CapSolver. Mô hình không nên chọn tên miền tùy ý.

import os
from typing import Annotated
from urllib.parse import urlparse

import capsolver

capsolver.api_key = os.environ["CAPSOLVER_API_KEY"]

ALLOWED_HOSTS = {
    "staging.example.com",
    "qa.example.com",
}


def solve_turnstile(
    website_url: Annotated[str, "Trang HTTPS được phê duyệt chứa Turnstile"],
    website_key: Annotated[str, "Khóa trang web Turnstile chính xác từ trang"],
    action: Annotated[str, "Giá trị data-action tùy chọn"] = "",
    cdata: Annotated[str, "Giá trị data-cdata tùy chọn"] = "",
) -> dict:
    """Giải Cloudflare Turnstile cho trang được phê duyệt và trả lại token."""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "Mục tiêu nằm ngoài danh sách tên miền được phê duyệt",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "Định dạng khóa trang web Turnstile không mong đợi",
        }

    task = {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    metadata = {}
    if action:
        metadata["action"] = action
    if cdata:
        metadata["cdata"] = cdata
    if metadata:
        task["metadata"] = metadata

    try:
        solution = capsolver.solve(task)
        token = solution.get("token")
        if not token:
            return {"success": False, "error": "Không có token được trả về"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

Kiểm tra định dạng là cảnh báo sớm hữu ích, nhưng không thay thế cho việc trích xuất chính xác tham số từ trang được cấp phép. Sử dụng hướng dẫn mở rộng trình duyệt CapSolver khi bạn cần kiểm tra cấu hình widget trong quá trình phát triển.

Bao bọc hàm bằng LlamaIndex

FunctionTool.from_defaults() chuyển đổi chữ ký hàm và văn bản mô tả thành lược đồ công cụ agent.

from llama_index.core.tools import FunctionTool

turnstile_tool = FunctionTool.from_defaults(
    fn=solve_turnstile,
    name="solve_turnstile",
    description=(
        "Giải Cloudflare Turnstile chỉ cho trang HTTPS được phê duyệt. "
        "Sử dụng URL trang chính xác, khóa trang và hành động/cdata tùy chọn "
        "được cung cấp bởi bộ điều khiển trình duyệt đáng tin cậy."
    ),
)

Giữ tên ngắn và mô tả vận hành. Không mô tả công cụ như cơ chế truy cập chung. Mô hình nên hiểu rằng nó là hành động phục hồi bên trong quy trình đã được phê duyệt.

Thêm công cụ vào LlamaIndex FunctionAgent

FunctionAgent của LlamaIndex sử dụng khả năng gọi công cụ của LLM để chọn và thực hiện các công cụ.

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini", temperature=0)

agent = FunctionAgent(
    tools=[turnstile_tool],
    llm=llm,
    system_prompt=(
        "Bạn chỉ hoạt động trong các quy trình trình duyệt được phê duyệt. "
        "Gọi solve_turnstile chỉ khi ứng dụng đáng tin cậy cung cấp "
        "URL trang chính xác và khóa trang. Không bao giờ tạo mục tiêu, khóa, "
        "hành động hoặc cdata. Gọi công cụ một lần. Nếu thất bại, dừng lại và "
        "yêu cầu xem xét của người vận hành."
    ),
)

Khởi chạy với tham số được tạo bởi mã trình duyệt xác định:

import asyncio

async def main():
    response = await agent.run(
        "Quy trình thử nghiệm được phê duyệt phát hiện Turnstile tại "
        "https://staging.example.com/account-check với khóa trang "
        "0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA và hành động "
        "account_check. Gọi công cụ đã đăng ký một lần và trả lại "
        "kết quả cấu trúc."
    )
    print(response)

asyncio.run(main())

Trong sản xuất, tránh xây dựng thông điệp này trực tiếp từ văn bản không đáng tin cậy. Bộ điều khiển trình duyệt nên trích xuất, xác minh và serial hóa các giá trị.

Giữ việc tiêu thụ token ngoài mô hình

Token Turnstile có thời hạn ngắn và liên quan đến quy trình trang web. Truyền nó trực tiếp từ kết quả công cụ đáng tin cậy đến mã trình duyệt xác định khi có thể.

async def apply_turnstile_token(page, token: str) -> None:
    await page.evaluate(
        """
        (token) => {
          const field = document.querySelector(
            'input[name="cf-turnstile-response"]'
          );
          if (!field) {
            throw new Error('Không tìm thấy trường phản hồi Turnstile');
          }
          field.value = token;
          field.dispatchEvent(new Event('input', { bubbles: true }));
          field.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Một số ứng dụng sử dụng trình bày dựa trên callback hoặc gửi bởi máy chủ. Kiểm tra ứng dụng thử nghiệm của bạn và tuân theo tích hợp được hỗ trợ. Tài liệu Siteverify của Cloudflare giải thích rằng chủ trang xác minh token phía máy chủ.

Hướng dẫn Turnstile của CapSolver cung cấp bối cảnh triển khai, và FAQ xử lý sự cố của CapSolver giúp chẩn đoán các giải pháp bị từ chối.

Thêm một lần thử lại giới hạn

Không để agent lặp vô hạn. Phân loại lỗi xác minh là cuối cùng, và cho phép tối đa một lần thử lại cho thời gian chờ tạm thời.

import asyncio

async def solve_with_policy(params: dict) -> dict:
    last_error = "lỗi không xác định"

    for attempt in range(1, 3):
        result = solve_turnstile(**params)
        if result.get("success"):
            return {**result, "attempt": attempt}

        last_error = result.get("error", last_error)
        normalized = last_error.lower()
        if "allowlist" in normalized or "site-key" in normalized:
            break
        if attempt == 1:
            await asyncio.sleep(2)

    return {
        "success": False,
        "error": last_error,
        "requires_operator_review": True,
    }

Ghi lại tên miền, loại tác vụ, thời gian, số lần thử và kết quả đã chuẩn hóa. Không bao giờ ghi lại token đầy đủ, khóa API, cookie hoặc nội dung biểu mẫu.

Chế độ Token vs Chế độ Trình duyệt

Tài liệu CapSolver được cung cấp bởi người dùng ám chỉ solve_captcha đến giải pháp token cốt lõi và solve_on_page đến phục hồi trình duyệt. Nếu trang là động, cài đặt phần mở rộng trình duyệt và giữ phiên trình duyệt ban đầu nguyên vẹn:

pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

Sử dụng các hướng dẫn tự động hóa CapSolver cho các quy trình trình duyệt liên quan và trang sản phẩm CapSolver cho các danh mục giải pháp được hỗ trợ.

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.

Các biện pháp kiểm soát sản xuất

Một tích hợp Turnstile LlamaIndex sản xuất nên sử dụng danh sách tên miền được phê duyệt, lưu trữ bí mật tách biệt, chuyển giao token có thời hạn ngắn, một lần thử lại giới hạn, ghi nhật ký bị che, xem xét của người vận hành và phân tách nghiêm ngặt giữa tự động hóa chỉ đọc và hành động có ảnh hưởng lớn.

FAQ giải quyết CAPTCHA của CapSolver giải thích chu kỳ tác vụ, và FAQ web-scraping của CapSolver đề cập đến các yếu tố vận hành.

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

Sử dụng tích hợp này chỉ trên các ứng dụng bạn sở hữu, kiểm tra hoặc có quyền tự động hóa rõ ràng. Giải quyết thử thách không cấp quyền truy cập dữ liệu riêng tư, tạo tài khoản, gửi giao dịch hoặc bỏ qua các điều khoản trang. Áp dụng giới hạn tốc độ, duy trì nhật ký kiểm toán và yêu cầu xác nhận trước bất kỳ hành động nào thay đổi dữ liệu hoặc ảnh hưởng đến người dùng.

Kết luận

Để giải Cloudflare Turnstile trong LlamaIndex đáng tin cậy, hãy biến CapSolver thành FunctionTool hẹp và giữ cấp phép, bí mật, thử lại và tiêu thụ token trong mã xác định. Agent LlamaIndex quyết định khi cần phục hồi, công cụ tạo tác vụ được tài liệu hóa AntiTurnstileTaskProxyLess, và trình duyệt tiếp tục quy trình được phê duyệt tương tự với token được trả lại.

Bắt đầu với CapSolver, xác minh tích hợp với trang thử nghiệm bạn kiểm soát, và thêm danh sách cho phép và ghi nhật ký bị che trước khi triển khai.

FAQ

Tôi nên sử dụng lớp công cụ LlamaIndex nào?

Sử dụng FunctionTool.from_defaults() để bao bọc hàm Python đồng bộ hoặc bất đồng bộ có kiểu dữ liệu. Đối với mô hình gọi công cụ, truyền công cụ kết quả đến FunctionAgent.

Tác vụ Turnstile có yêu cầu proxy không?

Tác vụ được tài liệu hóa AntiTurnstileTaskProxyLess sử dụng đường dẫn không proxy của CapSolver, vì vậy bạn không cần cung cấp proxy trong tác vụ.

Những trường nào là bắt buộc?

websiteURL và websiteKey là bắt buộc. Chỉ bao gồm metadata.action và metadata.cdata khi widget được cấp phép hiển thị chúng.

Token nên được lưu trữ trong bộ nhớ LlamaIndex không?

Không. Ưu tiên chuyển giao trực tiếp đến mã trình duyệt đáng tin cậy và chỉ trả lại trạng thái thành công hoặc thất bại bị che cho agent.

Điều gì sẽ xảy ra sau khi thất bại lặp lại?

Kiểm tra URL, khóa trang, dữ liệu mô tả tùy chọn và trạng thái trang. Sau một lần thử lại giới hạn, dừng và định tuyến quy trình đến xem xét của người vận hành.