Chỉ cần nhập một URL nguồn, toàn bộ trang web sẽ được phát trực tuyến

Thu thập dữ liệu

Yozh Crawler thu thập dữ liệu trên một trang web bắt đầu từ một URL hạt giống duy nhất và truyền trực tiếp mọi trang được phát hiện qua SSE. Nó đảm nhận toàn bộ quá trình khám phá — mở rộng phạm vi, loại trừ trùng lặp, xác định phạm vi, trích xuất liên kết, thử lại và tuân thủ các quy tắc lịch sự — trong khi việc truy xuất từng trang được ủy quyền cho Yozh Scraper qua HTTP. Chỉ có duy nhất một bộ công cụ Playwright cần vận hành, và mọi tính năng của trình trích xuất (proxy, chế độ ẩn danh, phiên làm việc, quy tắc trích xuất) cũng được áp dụng cho các trang web đã thu thập.

• Điều kiện phạm vi — same-domain / subdomains / all / regex, với các mẫu bao gồm và loại trừ cùng các giới hạn max_depth / max_pages giới hạn cứng.
• Loại bỏ trùng lặp dựa trên dấu vân tay — Các URL được chuẩn hóa rồi mã hóa băm (SHA1), do đó các truy vấn được sắp xếp lại và các biến thể có dấu gạch chéo ở cuối sẽ được gộp lại thành một lượt truy cập.
• Cơ chế luân phiên theo từng miền — một máy chủ chậm hoặc có dung lượng lớn sẽ không thể làm cạn kiệt nguồn công nhân của các máy chủ khác.
• Bộ giới hạn tốc độ thích ứng — một thùng token toàn cục cho từng miền (có độ dao động) được chia sẻ giữa các tác vụ; một 429 giảm một nửa RPS trong khoảng thời gian làm mát.
• Tình trạng phiên làm việc — Hệ thống chấm điểm theo phong cách Crawlee: 401/403/429 khi phiên làm việc kết thúc, các lỗi sẽ làm tăng điểm số của phiên, còn thành công sẽ làm giảm điểm số; luân chuyển phiên khi điểm số ≥ 3 hoặc sau 50 lần sử dụng.
• Phát trực tuyến SSE — mỗi tác vụ đều phát ra stats, page, page_error, và các sự kiện done / cancelled . Hãy xử lý các kết quả ngay khi chúng xuất hiện.

Bắt đầu nhanh

Trình thu thập dữ liệu được nối dây vào gốc docker-compose.yml và chạy song song với trình trích xuất:

docker compose up --build
# scraper  → http://localhost:8000
# crawler  → http://localhost:8001

Hoặc chạy nó trên máy cục bộ mà không cần Docker — chỉ SCRAPER_URL vào một trình thu thập dữ liệu đang chạy:

cd yozh-crawler
pip install -r requirements.txt
cp .env.example .env          # edit SCRAPER_URL if needed
python -m uvicorn src.main:app --reload --port 8001

Cách sử dụng cơ bản

Gửi yêu cầu thu thập dữ liệu kèm theo seed_url và một scope. Lời gọi này sẽ trả về một job_id ngay lập tức; sau đó, quá trình thu thập dữ liệu sẽ chạy ở chế độ nền trên các tác vụ công việc.

curl -X POST http://localhost:8001/api/v1/crawl 
  -H "Content-Type: application/json" 
  -d '{
    "seed_url": "https://example.com",
    "scope": {"mode": "same-domain", "max_depth": 2, "max_pages": 50,
              "per_domain_rps": 1.0, "per_domain_concurrency": 1},
    "scrape_options": {"proxy_type": "none"},
    "enable_scraping": false
  }'

Kết quả trả về chỉ là mã công việc:

{ "job_id": "crawl_abc123" }

Từ đây, bạn có thể phát trực tiếp các sự kiện hoặc truy vấn công việc để lấy bản ghi đầy đủ.

Khám phá so với khai thác — nút enable_scraping chuyển đổi

Cùng một công cụ thu thập dữ liệu hoạt động theo cả hai hướng. Một biến boolean dùng để lựa chọn giữa chế độ khám phá tiết kiệm tài nguyên và chế độ thu thập dữ liệu toàn diện — và mỗi chế độ sử dụng cấu hình proxy riêng, do đó không xảy ra hiện tượng ảnh hưởng lẫn nhau.

Phạm vi thu thập dữ liệu

Phạm vi xác định giới hạn của quá trình thu thập dữ liệu: nơi mà quá trình này được phép truy cập, và mức độ tác động tối đa được phép đối với từng máy chủ. Đây là scope đối tượng trong yêu cầu.

Kết quả phát trực tuyến (SSE)

Mỗi tác vụ đều cung cấp một luồng sự kiện do máy chủ gửi (Server-Sent Events). Hãy đọc luồng này để thực hiện các thao tác trên các trang ngay khi chúng được phát hiện, thay vì phải chờ quá trình thu thập dữ liệu hoàn tất.

curl -N http://localhost:8001/api/v1/crawl/crawl_abc123/events

Dòng dữ liệu phát ra năm loại sự kiện:

Một page sự kiện trong chế độ khám phá trông như sau:

{
  "event": "page",
  "url": "https://example.com/docs/intro",
  "parent_url": "https://example.com/docs",
  "depth": 2,
  "status_code": 200,
  "took_ms": 812,
  "scrape_response": null
}

Tình trạng và kết quả

Bạn thích phương thức thăm dò hơn? Bản ghi công việc có thể được truy vấn bất cứ lúc nào — kể cả trong quá trình thu thập dữ liệu, với các trang đã được phát hiện cho đến thời điểm đó. /results là một tên gọi khác của điểm cuối công việc, được giữ lại để đảm bảo tính đối xứng với trình thu thập dữ liệu.

curl http://localhost:8001/api/v1/crawl/crawl_abc123
curl http://localhost:8001/api/v1/crawl/crawl_abc123/results

{
  "job_id": "crawl_abc123",
  "status": "running",
  "stats": {
    "visited": 47, "queued": 12, "failed": 0,
    "dedup_skipped": 9, "out_of_scope": 31, "retries_total": 2
  },
  "pages": [
    { "url": "https://example.com/", "parent_url": null,
      "depth": 0, "status_code": 200, "took_ms": 640 }
  ]
}

Hủy quá trình thu thập dữ liệu

Dừng một tác vụ đang chạy bằng lệnh DELETE. Hủy nhẹ là tùy chọn mặc định và là lựa chọn an toàn.

# soft — stop scheduling, let in-flight requests drain
curl -X DELETE "http://localhost:8001/api/v1/crawl/crawl_abc123?hard=false"

# hard — abort in-flight asyncio tasks immediately
curl -X DELETE "http://localhost:8001/api/v1/crawl/crawl_abc123?hard=true"

MCP

fastapi-mcp được triển khai tại /mcp dưới dạng một điểm cuối HTTP có thể phát trực tuyến. Chỉ cần di chuột hoặc đặt con trỏ vào đó, các công cụ sẽ tự động xuất hiện:

• health
• create_crawl
• get_crawl
• get_crawl_results
• cancel_crawl

"open-crawler": {
  "type": "http",
  "url": "http://localhost:8001/mcp"
}

Tài liệu tham khảo về cấu hình

Yêu cầu — CrawlRequest

Mỗi trang — ScrapeOptions (đã chọn)

Biến môi trường

Tham khảo API

Các chi tiết quan trọng