Cách giải CAPTCHA bằng TinyFish AgentQL – Hướng dẫn từng bước sử dụng CapSolver

Khi tự động hóa web được cấp bằng AI của bạn gặp phải bức tường CAPTCHA, toàn bộ quy trình sẽ bị đình trệ. Các trang web không thể tải, các biểu mẫu không thể gửi, và việc trích xuất dữ liệu sẽ dừng lại — tất cả đều do một thử thách được thiết kế để chặn bot. TinyFish AgentQL là một bộ công cụ mạnh mẽ để kết nối AI với web, bao gồm các truy vấn ngôn ngữ tự nhiên, tích hợp Playwright, và trích xuất dữ liệu có cấu trúc ở quy mô doanh nghiệp. Tuy nhiên, giống như bất kỳ khung phần mềm tự động hóa trình duyệt nào khác, nó cũng bị chặn bởi CAPTCHA.

CapSolver thay đổi hoàn toàn điều này. Bằng cách tải tiện ích mở rộng CapSolver Chrome vào ngữ cảnh trình duyệt Playwright của AgentQL, CAPTCHA sẽ được giải quyết tự động và vô hình trong nền. Không cần giải quyết thủ công. Không cần điều phối API phức tạp từ phía bạn. Các tập lệnh tự động hóa của bạn sẽ tiếp tục chạy như thể CAPTCHA chưa từng tồn tại.

Điều tốt nhất? Các truy vấn và tập lệnh AgentQL của bạn không cần bất kỳ dòng mã nào liên quan đến CAPTCHA. Tiện ích mở rộng xử lý việc phát hiện, giải quyết và chèn token hoàn toàn tự động trong khi trợ lý của bạn tập trung vào những gì nó làm tốt nhất — trích xuất dữ liệu và tự động hóa quy trình.

TinyFish AgentQL là gì?

TinyFish AgentQL là công cụ lập trình dành cho doanh nghiệp để kết nối các trợ lý AI và LLM với môi trường web trực tiếp. Được phát triển bởi TinyFish, nó cung cấp ngôn ngữ truy vấn được cấp bằng AI cho phép bạn tìm các phần tử trang và trích xuất dữ liệu có cấu trúc bằng ngôn ngữ tự nhiên — không cần các lựa chọn CSS hoặc XPaths mong manh.

Tính năng chính

• Ngôn ngữ truy vấn được cấp bằng AI: Tìm các phần tử một cách trực quan dựa trên nội dung trang. Các truy vấn tự phục hồi khi giao diện thay đổi theo thời gian.
• Tích hợp Playwright: Các SDK Python và JavaScript tích hợp liền mạch với Playwright để tự động hóa trình duyệt nâng cao.
• Trích xuất dữ liệu có cấu trúc: Xác định hình dạng đầu ra và nhận dữ liệu sạch, có cấu trúc từ bất kỳ trang nào — công khai hoặc riêng tư, tĩnh hoặc động.
• API REST: Thực hiện truy vấn mà không cần SDK thông qua điểm cuối REST.
• Trình gỡ lỗi trình duyệt: Một tiện ích mở rộng Chrome để kiểm tra và tinh chỉnh truy vấn theo thời gian thực.
• Khả năng chống chịu đa trang: Hoạt động trên các trang web tương tự mà không cần sửa đổi, thích ứng động với các thay đổi trên trang.
• Quy mô doanh nghiệp: Được xây dựng cho các khối lượng công việc có lưu lượng cao, chạy hàng trăm tác vụ song song.

AgentQL hoạt động trên bất kỳ trang nào — bao gồm nội dung đã xác thực và các trang được tạo động — làm cho nó lý tưởng cho tự động hóa web quy mô lớn, thu thập dữ liệu và quy trình trợ lý AI.

CapSolver là gì?

CapSolver là dịch vụ giải CAPTCHA được cấp bằng AI, tự động giải các thách thức CAPTCHA đa dạng. Với thời gian phản hồi nhanh và khả năng tương thích rộng, CapSolver tích hợp liền mạch vào các quy trình tự động hóa.

Các loại CAPTCHA được hỗ trợ

• reCAPTCHA v2 (hộp kiểm và vô hình)
• reCAPTCHA v3 & v3 Doanh nghiệp
• Cloudflare Turnstile
• Cloudflare 5 giây thử thách
• AWS WAF CAPTCHA
• Nhiều hơn nữa

Tại sao tích hợp này khác biệt?

Hầu hết các tích hợp giải CAPTCHA yêu cầu bạn viết mã mẫu: tạo nhiệm vụ, kiểm tra kết quả, chèn token vào các trường ẩn. Đó là cách tiếp cận tiêu chuẩn với các tập lệnh Playwright hoặc Puppeteer gốc.

AgentQL + CapSolver tiếp cận một cách hoàn toàn khác:

Nhận thức chính: Tiện ích mở rộng CapSolver chạy bên trong ngữ cảnh trình duyệt Playwright của AgentQL. Khi AgentQL điều hướng đến trang có CAPTCHA, tiện ích mở rộng phát hiện nó, giải quyết nó trong nền, và chèn token — tất cả trước khi tập lệnh của bạn tương tác với biểu mẫu. Mã tự động hóa của bạn vẫn sạch sẽ, tập trung và không có CAPTCHA.

Yêu cầu tiên quyết

Trước khi thiết lập tích hợp, hãy đảm bảo bạn có:

• TinyFish AgentQL đã cài đặt (SDK Python hoặc SDK JavaScript)
• Tài khoản CapSolver với khóa API (đăng ký tại đây)
• Node.js 16+ và Python 3.8+ (tùy thuộc vào lựa chọn SDK của bạn)
• Playwright đã cài đặt với Chromium

Quan trọng: Tiện ích mở rộng Chrome chỉ hoạt động với Chromium trong một cơ sở dữ liệu duy trì trong Playwright. Đây là yêu cầu của Playwright, không phải giới hạn của AgentQL.

Thiết lập từng bước

Bước 1: Cài đặt AgentQL

SDK Python:

pip install agentql
playwright install chromium

SDK JavaScript:

npm install agentql
npx playwright install chromium

Bước 2: Tải xuống tiện ích mở rộng CapSolver Chrome

Tải tiện ích mở rộng CapSolver Chrome và giải nén nó vào một thư mục chuyên dụng:

1. Truy cập phiên bản tiện ích mở rộng CapSolver Chrome v1.17.0
2. Tải xuống CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. Giải nén zip:

mkdir -p ~/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/capsolver-extension/

4. Xác minh việc giải nén thành công:

ls ~/capsolver-extension/manifest.json

Bạn nên thấy manifest.json — điều này xác nhận tiện ích mở rộng ở đúng vị trí.

Bước 3: Cấu hình khóa API CapSolver của bạn

Mở tệp cấu hình tiện ích mở rộng tại ~/capsolver-extension/assets/config.js và thay giá trị apiKey bằng khóa của bạn:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // ← khóa của bạn ở đây
  useCapsolver: true,
  // ... phần còn lại của cấu hình
};

Bạn có thể lấy khóa API từ bảng điều khiển CapSolver.

Bước 4: Khởi động AgentQL với tiện ích mở rộng CapSolver

Bước quan trọng là khởi động Chromium của Playwright với một cơ sở dữ liệu duy trì tải tiện ích mở rộng CapSolver.

Ví dụ Python:

import agentql
from playwright.sync_api import sync_playwright
import time
import os

# Đường dẫn đến tiện ích mở rộng CapSolver
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")

def main():
    with sync_playwright() as p:
        # Khởi động Chromium với cơ sở dữ liệu duy trì và tiện ích mở rộng CapSolver
        context = p.chromium.launch_persistent_context(
            user_data_dir="./browser-data",
            headless=False,  # Tiện ích mở rộng yêu cầu chế độ có giao diện
            args=[
                f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
                f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
            ],
        )

        # Bao bọc trang bằng AgentQL để thực hiện truy vấn AI
        page = agentql.wrap(context.pages[0])

        # Điều hướng đến trang mục tiêu
        page.goto("https://example.com/protected-page")

        # Chờ CapSolver phát hiện và giải CAPTCHA
        time.sleep(30)

        # Tìm và nhấp vào nút gửi bằng truy vấn ngôn ngữ tự nhiên của AgentQL
        response = page.query_elements("""
        {
            submit_button
        }
        """)

        # Nhấp vào nút gửi — CAPTCHA đã được giải!
        response.submit_button.click()

        # Trích xuất dữ liệu sau khi gửi
        result = page.query_data("""
        {
            confirmation_message
        }
        """)

        print(f"Kết quả: {result['confirmation_message']}")

        context.close()

if __name__ == "__main__":
    main()

Ví dụ JavaScript:

const { chromium } = require('playwright');
const agentql = require('agentql');
const path = require('path');
const os = require('os');

const CAPSOLVER_EXTENSION_PATH = path.join(os.homedir(), 'capsolver-extension');

(async () => {
  // Khởi động Chromium với cơ sở dữ liệu duy trì và tiện ích mở rộng CapSolver
  const context = await chromium.launchPersistentContext('./browser-data', {
    headless: false, // Tiện ích mở rộng yêu cầu chế độ có giao diện
    args: [
      `--disable-extensions-except=${CAPSOLVER_EXTENSION_PATH}`,
      `--load-extension=${CAPSOLVER_EXTENSION_PATH}`,
    ],
  });

  // Lấy trang đầu tiên và bao bọc bằng AgentQL
  const page = agentql.wrap(context.pages()[0]);

  // Điều hướng đến trang mục tiêu
  await page.goto('https://example.com/protected-page');

  // Chờ CapSolver xử lý bất kỳ CAPTCHA nào
  await page.waitForTimeout(30000);

  // Sử dụng truy vấn AgentQL để tương tác — CAPTCHA đã được giải
  const response = await page.queryElements(`{
    submit_button
  }`);

  await response.submit_button.click();

  // Trích xuất dữ liệu kết quả
  const result = await page.queryData(`{
    confirmation_message
  }`);

  console.log('Kết quả:', result.confirmation_message);

  await context.close();
})();

Bước 5: Xác minh tiện ích mở rộng đã được tải

Sau khi khởi động trình duyệt, bạn có thể xác minh tiện ích mở rộng CapSolver đang hoạt động bằng cách điều hướng đến chrome://extensions trong cửa sổ trình duyệt. Bạn nên thấy tiện ích mở rộng CapSolver được liệt kê và kích hoạt.

Ngoài ra, kiểm tra bảng điều khiển trình duyệt để xem các thông báo ghi nhật ký của CapSolver cho thấy dịch vụ worker đang chạy.

Cách sử dụng

Sau khi thiết lập hoàn tất, sử dụng CapSolver với AgentQL là đơn giản.

Quy tắc vàng

Không viết mã đặc biệt cho CAPTCHA. Chỉ cần thêm thời gian chờ trước khi tương tác với các biểu mẫu được bảo vệ bởi CAPTCHA, và để tiện ích mở rộng thực hiện công việc của nó.

Ví dụ 1: Gửi biểu mẫu sau reCAPTCHA

page.goto("https://example.com/contact")

# Điền vào biểu mẫu bằng truy vấn AgentQL
response = page.query_elements("""
{
    contact_form {
        name_field
        email_field
        message_field
        submit_button
    }
}
""")

response.contact_form.name_field.fill("John Doe")
response.contact_form.email_field.fill("john@example.com")
response.contact_form.message_field.fill("Xin chào, tôi có một câu hỏi về dịch vụ của quý vị.")

# Chờ CapSolver giải CAPTCHA
time.sleep(30)

# Gửi — token CAPTCHA đã được chèn
response.contact_form.submit_button.click()

Ví dụ 2: Trang đăng nhập với Cloudflare Turnstile

page.goto("https://example.com/login")

# Chờ CapSolver giải quyết thách thức Turnstile
time.sleep(25)

# Tìm các phần tử biểu mẫu đăng nhập với AgentQL
response = page.query_elements("""
{
    login_form {
        email_input
        password_input
        login_button
    }
}
""")

# Điền vào biểu mẫu — Turnstile đã được xử lý
response.login_form.email_input.fill("me@example.com")
response.login_form.password_input.fill("mypassword123")

# Nhấp vào đăng nhập
response.login_form.login_button.click()

Ví dụ 3: Trích xuất dữ liệu từ trang được bảo vệ

page.goto("https://example.com/data")

# Chờ CAPTCHA được giải
time.sleep(30)

# Trích xuất dữ liệu có cấu trúc với AgentQL
data = page.query_data("""
{
    products[] {
        name
        price
        rating
        availability
    }
}
""")

for product in data['products']:
    print(f"{product['name']}: ${product['price']} ({product['rating']} sao)")

Thời gian chờ được đề xuất

Lời khuyên: Khi không chắc, hãy sử dụng 30 giây. Tốt hơn là chờ lâu hơn một chút so với việc gửi quá sớm. Thời gian bổ sung không ảnh hưởng đến kết quả.

Cách hoạt động ở phía sau

Đây là những gì xảy ra khi AgentQL chạy với tiện ích mở rộng CapSolver được tải:

Tập lệnh AgentQL của bạn
───────────────────────────────────────────────────
page.goto("https://...")       ──► Chromium tải trang
                                           │
                                           ▼
                               ┌─────────────────────────────┐
                               │  Trang có widget CAPTCHA     │
                               │                               │
                               │  Tiện ích mở rộng CapSolver:   │
                               │  1. Script nội dung phát hiện  │
                               │     CAPTCHA trên trang        │
                               │  2. Service worker gọi        │
                               │     API CapSolver             │
                               │  3. Token nhận được           │
                               │  4. Token chèn vào trường ẩn   │
                               └─────────────────────────────┘
                                           │
                                           ▼
time.sleep(30)                   Tiện ích mở rộng giải CAPTCHA...
                                           │
                                           ▼
page.query_elements(...)         AgentQL tìm thấy các phần tử biểu mẫu
submit_button.click()            Biểu mẫu gửi với token hợp lệ
                                           │
                                           ▼
                               "Xác minh thành công!"

Cách tiện ích mở rộng được tải

Khi Playwright khởi động Chromium với cờ --load-extension:

1. Chromium bắt đầu với tiện ích mở rộng CapSolver được tải
2. Tiện ích mở rộng được kích hoạt — service worker của nó bắt đầu và các script nội dung được chèn vào mọi trang
3. Trên các trang có CAPTCHA — script nội dung phát hiện widget, gọi API CapSolver và chèn token giải pháp vào trang
4. AgentQL hoạt động bình thường — các truy vấn, nhấp chuột và trích xuất dữ liệu hoạt động như bình thường, với CAPTCHA đã được xử lý

Tham chiếu cấu hình đầy đủ

Đây là cài đặt Python đầy đủ với tất cả các tùy chọn cấu hình cho tích hợp AgentQL + CapSolver:

import agentql
from playwright.sync_api import sync_playwright
import os

# Cấu hình
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")
USER_DATA_DIR = "./browser-data"

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        user_data_dir=USER_DATA_DIR,
        headless=False,
        args=[
            f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
            f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
        ],
    )
    page = agentql.wrap(context.pages[0])
    # ... mã tự động hóa của bạn ở đây
    context.close()

Các tùy chọn cấu hình

Khóa API của CapSolver được cấu hình trực tiếp trong tệp assets/config.js của tiện ích mở rộng (xem Bước 3 ở trên).

Chẩn đoán và khắc phục sự cố

Tiện ích mở rộng không tải

Triệu chứng: CAPTCHAs không được giải tự động.

Nguyên nhân: Bạn có thể đang sử dụng ngữ cảnh trình duyệt thông thường thay vì ngữ cảnh bền vững, hoặc đang chạy ở chế độ không đầu.

Giải pháp: Tiện ích mở rộng trong Playwright yêu cầu ngữ cảnh bền vững và chế độ có giao diện người dùng:

# ✅ Đúng — ngữ cảnh bền vững, có giao diện người dùng
context = p.chromium.launch_persistent_context(
    user_data_dir="./browser-data",
    headless=False,
    args=[...các tham số tiện ích...]
)

# ❌ Sai — ngữ cảnh thông thường (tiện ích mở rộng sẽ không tải)
browser = p.chromium.launch()
context = browser.new_context()

CAPTCHA không được giải (Form thất bại)

Nguyên nhân có thể:

• Thời gian chờ không đủ — Tăng lên 60 giây
• Khóa API không hợp lệ — Kiểm tra bảng điều khiển CapSolver
• Số dư không đủ — Nạp tiền tài khoản CapSolver của bạn
• Tiện ích mở rộng không tải — Xem phần "Tiện ích mở rộng không tải" ở trên

Chế độ không đầu không được hỗ trợ

Triệu chứng: Chương trình chạy nhưng tiện ích mở rộng không xuất hiện.

Nguyên nhân: Các tiện ích mở rộng Chrome không hoạt động trong chế độ không đầu.

Giải pháp: Sử dụng chế độ có giao diện người dùng với màn hình ảo trên máy chủ:

# Cài đặt Xvfb
sudo apt-get install xvfb

# Khởi động màn hình ảo
Xvfb :99 -screen 0 1280x720x24 &

# Thiết lập DISPLAY
export DISPLAY=:99

Tương thích với Google Chrome 137+

Triệu chứng: Cờ tiện ích mở rộng bị bỏ qua mà không thông báo.

Nguyên nhân: Google Chrome 137+ đã loại bỏ hỗ trợ cho --load-extension trong các phiên bản được đánh dấu thương hiệu.

Giải pháp: Sử dụng Chromium được tích hợp trong Playwright (được khuyến khích) hoặc Chrome for Testing:

# Cài đặt Chromium của Playwright (được khuyến khích)
npx playwright install chromium

# Hoặc tải xuống Chrome for Testing
# Truy cập: https://googlechromelabs.github.io/chrome-for-testing/

Nguyên tắc tốt nhất

1. Luôn sử dụng thời gian chờ dài. Thời gian chờ càng nhiều càng an toàn. CAPTCHA thường được giải trong 5-20 giây, nhưng độ trễ mạng, thách thức phức tạp hoặc thử lại có thể làm tăng thời gian. 30-60 giây là khoảng thời gian lý tưởng.

2. Giữ mã tự động hóa sạch sẽ. Không thêm logic đặc biệt cho CAPTCHA vào truy vấn AgentQL của bạn. Tiện ích mở rộng xử lý mọi thứ — mã của bạn nên tập trung hoàn toàn vào trích xuất dữ liệu và tương tác.

3. Theo dõi số dư CapSolver của bạn. Mỗi lần giải CAPTCHA sẽ tốn tiền. Kiểm tra số dư tại capsolver.com/dashboard thường xuyên để tránh gián đoạn.

4. Luôn sử dụng ngữ cảnh bền vững. Luôn khởi động với launch_persistent_context() khi bạn cần tiện ích mở rộng. Điều này cũng lưu trữ cookie và dữ liệu phiên giữa các lần chạy, có thể giảm tần suất CAPTCHA.

5. Sử dụng Xvfb trên máy chủ không đầu. Các tiện ích mở rộng Chrome yêu cầu ngữ cảnh màn hình. Thiết lập Xvfb cho các môi trường máy chủ mà không có màn hình vật lý.

Kết luận

Sự tích hợp TinyFish AgentQL + CapSolver mang lại giải pháp CAPTCHA ẩn cho bộ công cụ tự động hóa web mạnh mẽ nhất hiện có. Thay vì viết mã xử lý CAPTCHA phức tạp, bạn chỉ cần:

1. Tải tiện ích mở rộng CapSolver và cấu hình khóa API của bạn
2. Khởi động trình duyệt Playwright của AgentQL với tiện ích mở rộng được tải qua ngữ cảnh bền vững
3. Viết mã tự động hóa như bình thường — chỉ cần thêm thời gian chờ trước khi gửi biểu mẫu

Tiện ích mở rộng CapSolver xử lý phần còn lại — phát hiện CAPTCHA, giải chúng qua API CapSolver và chèn token vào trang. Mã AgentQL của bạn không bao giờ cần biết gì về CAPTCHA cả.

Đây là cách giải CAPTCHA khi kết hợp tự động hóa web dựa trên AI với giải pháp CAPTCHA dựa trên AI: ẩn, tự động và không cần mã.

Sẵn sàng bắt đầu chưa? Đăng ký CapSolver và sử dụng mã khuyến mãi AGENTQL để nhận thêm 6% khi nạp tiền lần đầu!

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

Tôi có cần viết mã cụ thể cho CAPTCHA trong các truy vấn AgentQL của mình không?

Không. Tiện ích mở rộng CapSolver hoạt động hoàn toàn ở nền trong ngữ cảnh trình duyệt Playwright. Chỉ cần thêm time.sleep() hoặc waitForTimeout() trước khi gửi biểu mẫu, và tiện ích mở rộng sẽ xử lý phát hiện, giải và chèn token tự động.

Tại sao tôi cần sử dụng ngữ cảnh bền vững?

Playwright chỉ hỗ trợ tiện ích mở rộng khi sử dụng launch_persistent_context(). Đây là yêu cầu kiến trúc của Playwright. Các ngữ cảnh trình duyệt thông thường được tạo qua browser.new_context() không thể tải tiện ích mở rộng.

Tôi có thể chạy ở chế độ không đầu không?

Không. Tiện ích mở rộng Chrome yêu cầu trình duyệt có giao diện người dùng. Đối với các môi trường máy chủ không có màn hình, sử dụng Xvfb (X Virtual Framebuffer) để tạo màn hình ảo.

CapSolver hỗ trợ loại CAPTCHA nào?

CapSolver hỗ trợ reCAPTCHA v2 (hộp kiểm và ẩn), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA và nhiều loại khác. Tiện ích mở rộng tự động phát hiện loại CAPTCHA và giải chúng tương ứng.

Chi phí của CapSolver là bao nhiêu?

CapSolver cung cấp giá cả cạnh tranh dựa trên loại CAPTCHA và khối lượng. Truy cập capsolver.com để xem giá hiện tại.

AgentQL có miễn phí không?

AgentQL cung cấp các gói miễn phí và trả phí. SDK và ngôn ngữ truy vấn có sẵn cho phát triển và kiểm thử. Truy cập tinyfish.ai để biết chi tiết về giá cả.

Tôi nên chờ bao lâu để CAPTCHA được giải?

Đối với phần lớn CAPTCHA, 30-60 giây là đủ. Thời gian giải thực tế thường là 5-20 giây, nhưng việc thêm thời gian dự phòng đảm bảo độ tin cậy. Nếu không chắc, hãy sử dụng 30 giây.