Vnstock Logo

Hướng dẫn Cơ bản

Phiên bản v2.2.2

Cập nhật lần cuối:

Thảo luận

Mục lục

Phương pháp sử dụng
Các hàm và tham số dưới đây cung cấp kiến thức nền tảng về thư viện. Bạn cũng có thể tham khảo tài liệu Agent Guide để hỗ trợ các công cụ AI Agent tự động viết kịch bản thu thập dữ liệu theo yêu cầu.

1. Chi Tiết Các Lớp Crawler & Phương Thức API

Thư viện vnstock_news cung cấp 4 lớp Crawler phục vụ các nhu cầu thu thập dữ liệu khác nhau:

1.1 Crawler - Giao diện thu thập đơn giản

Crawler là lớp thu thập dữ liệu cơ bản, phù hợp với nhu cầu lấy nhanh bài viết mới hoặc kiểm tra cấu hình trang báo.

Khởi tạo:

Python
from vnstock_news import Crawler

# Cách 1: Sử dụng cấu hình có sẵn của báo (ví dụ: vnexpress, tuoitre, cafef)
crawler = Crawler(site_name="vnexpress")

# Cách 2: Truyền cấu hình tùy chỉnh cho trang web mới
custom_site_config = {
    "name": "Báo Mới Custom",
    "domain": "baomoicustom.vn",
    "rss_urls": ["https://baomoicustom.vn/rss/feed.xml"],
    "sitemap_url": "https://baomoicustom.vn/sitemap.xml",
    "config": {
        "title_selector": {"tag": "h1", "class": "title-detail"},
        "content_selector": {"tag": "div", "class": "article-content"}
    }
}
crawler_custom = Crawler(custom_config=custom_site_config)

Phương thức chính:

  • get_articles_from_feed(limit_per_feed=20): Lấy danh sách bài viết từ các kênh RSS Feed.
  • get_articles(sitemap_url=None, limit=10, limit_per_feed=None): Ưu tiên lấy từ RSS Feed, nếu không có RSS sẽ chuyển sang lấy danh sách URL từ Sitemap.

Bảng tham số Crawler:

Tham SốKiểu Dữ LiệuMặc ĐịnhMô Tả
site_namestrNoneTên định danh của báo trong SITES_CONFIG (ví dụ: "vnexpress", "cafef")
custom_configdictNoneDictionary chứa cấu hình bộ chọn và nguồn RSS/Sitemap tự định nghĩa
limit_per_feedint20Số lượng bài viết tối đa cần lấy từ mỗi nguồn RSS feed
limitint10Tổng số lượng bài viết thu thập khi gọi get_articles()
sitemap_urlstr / listNoneĐường dẫn Sitemap XML tùy chỉnh

1.2 BatchCrawler - Thu thập đồng bộ dữ liệu lịch sử

BatchCrawler thực hiện tải nội dung chi tiết bài viết theo cơ chế đồng bộ, hỗ trợ lưu dữ liệu tạm để tiếp tục tiến trình nếu bị gián đoạn.

Ví dụ sử dụng:

Python
from vnstock_news import BatchCrawler

# Khởi tạo BatchCrawler với khoảng trễ 1.5 giây giữa các yêu cầu
crawler = BatchCrawler(
    site_name="cafef",
    request_delay=1.5,
    output_path="./output_data"
)

# Tải nội dung chi tiết của 100 bài viết từ Sitemap
df_articles = crawler.fetch_articles(limit=100)
print(f"Tổng số bài viết đã bóc tách: {len(df_articles)}")

Bảng tham số BatchCrawler:

Tham SốKiểu Dữ LiệuMặc ĐịnhMô Tả
site_namestrBắt buộcTên định danh báo trong hệ thống cấu hình
request_delayfloat1.0Thời gian tạm dừng (giây) giữa các lần gửi yêu cầu HTTP
output_pathstr"./data"Thư mục lưu trữ tập tin tạm
limitint10Số lượng bài viết tối đa cần bóc tách chi tiết
sitemap_urlstr / listNoneURL sitemap cụ thể cần quét dữ liệu
debugboolFalseBật/tắt chế độ ghi log chi tiết

1.3 AsyncBatchCrawler - Thu thập bất đồng bộ

AsyncBatchCrawler sử dụng thư viện aiohttpasyncio, hỗ trợ tải song song nhiều bài viết cùng lúc để tăng tốc độ thu thập.

Ví dụ sử dụng:

Python
import asyncio
from vnstock_news import AsyncBatchCrawler

async def run_async_pipeline():
    crawler = AsyncBatchCrawler(
        site_name="tuoitre",
        max_concurrency=5  # Giới hạn tối đa 5 yêu cầu gửi đi đồng thời
    )
    
    # Lấy 200 bài viết từ Sitemap của Báo Tuổi Trẻ
    df_result = await crawler.fetch_articles_async(
        sources=["https://tuoitre.vn/news-sitemap.xml"],
        top_n=200
    )
    return df_result

df_tuoitre = asyncio.run(run_async_pipeline())
print(f"Thu thập thành công {len(df_tuoitre)} bài viết.")

Bảng tham số AsyncBatchCrawler:

Tham SốKiểu Dữ LiệuMặc ĐịnhMô Tả
site_namestrBắt buộcTên định danh trang báo
max_concurrencyint5Số lượng kết nối song song tối đa
sourceslistBắt buộcDanh sách đường dẫn Sitemap XML nguồn
top_nint10Số lượng bài viết tối đa cần bóc tách từ danh sách URLs

1.4 EnhancedNewsCrawler - Động cơ thu thập mở rộng

EnhancedNewsCrawler tích hợp bộ nhớ đệm (Cache), cơ chế làm sạch văn bản, kiểm tra tính hợp lệ dữ liệu và tự động thử lại khi gặp lỗi kết nối.

Ví dụ sử dụng:

Python
import asyncio
from vnstock_news import EnhancedNewsCrawler

async def run_enhanced_pipeline():
    crawler = EnhancedNewsCrawler(
        cache_enabled=True,
        cache_ttl=86400,    # Thời gian lưu bộ nhớ đệm 24 giờ
        max_concurrency=5
    )
    
    df_data = await crawler.fetch_articles_async(
        sources=["https://cafef.vn/latest-news-sitemap.xml"],
        site_name="cafef",
        top_n=100,
        clean_content=True  # Tự động loại bỏ các thẻ HTML rác và quảng cáo
    )
    return df_data

df_enhanced = asyncio.run(run_enhanced_pipeline())

2. So Sánh Nguồn Dữ Liệu: RSS Feeds và Sitemap XML

Việc lựa chọn nguồn thu thập phụ thuộc vào mục đích sử dụng cụ thể:

Tiêu Chí So SánhRSS Feeds (Tin Mới)Sitemap XML (Lịch Sử)
Tốc độ thu thậpNhanhPhụ thuộc số bài và thời gian trễ
Phạm vi dữ liệuChứa các bài mới phát hành gần đâyChứa danh sách bài viết theo thời gian lưu trữ của báo
Độ sâu thông tinCó sẵn thông tin tóm tắt và ngày đăngCần gửi thêm yêu cầu HTTP để bóc tách nội dung chi tiết
Mục đích sử dụngGiám sát tin tức mới, nhận thông báo tin bàiXây dựng bộ dữ liệu phân tích, huấn luyện mô hình
Cơ chế dự phòngTự động chuyển sang Sitemap nếu RSS không hoạt độngTự động phân giải các Sitemap động theo tháng/năm

Gợi ý: Bạn có thể kết hợp sử dụng RSS Feeds để cập nhật bài viết mới định kỳ và quét Sitemap XML để bổ sung các bài viết bị sót.


3. Cấu Trúc Dữ Liệu Trả Về

Dữ liệu bài viết sau khi bóc tách từ các lớp Crawler được trả về dưới dạng Pandas DataFrame hoặc List[Dict] với 11 trường dữ liệu chuẩn hóa:

Cột Dữ LiệuKiểu Dữ LiệuMô Tả Chi TiếtVí Dụ Dữ Liệu Mẫu
urlstrĐường dẫn URL của bài viết"https://cafef.vn/thi-truong-chung-khoan-2026.chn"
titlestrTiêu đề bài viết"Thị trường chứng khoán bật tăng mạnh phiên đầu tuần"
short_descriptionstrĐoạn tóm tắt / Sapo bài viết"Dòng tiền khối ngoại quay trở lại mua ròng..."
contentstrNội dung văn bản (đã loại bỏ HTML)"Nội dung chi tiết các đoạn văn bản trong bài..."
publish_timedatetimeThời gian xuất bản (dạng ISO)2026-04-15 09:30:00
authorstrTên tác giả hoặc nguồn dẫn"Nguyễn Văn A" / "Theo CafeF"
categorystrChuyên mục tin tức"Chứng khoán" / "Tài chính vĩ mô"
tagsstrDanh sách từ khóa / Tags bài viết"VN-Index, Chứng khoán, Lãi suất"
view_countsintSố lượt xem (nếu báo có hiển thị)15200
image_urlstrĐường dẫn ảnh đại diện bài viết"https://cdn.cafef.vn/thumb_w/640/image.jpg"
sourcestrTên định danh nguồn báo"cafef" / "vnexpress"

Dữ liệu trả về ở dạng Pandas DataFrame giúp bạn dễ dàng thực hiện lọc, nhóm, lưu trữ ra tập tin CSV/Parquet hoặc nạp vào các quy trình xử lý dữ liệu tiếp theo.

Thảo luận

Đang tải bình luận...