Hướng dẫn Cơ bản
Mục lục
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:
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ệu | Mặc Định | Mô Tả |
|---|---|---|---|
site_name | str | None | Tên định danh của báo trong SITES_CONFIG (ví dụ: "vnexpress", "cafef") |
custom_config | dict | None | Dictionary chứa cấu hình bộ chọn và nguồn RSS/Sitemap tự định nghĩa |
limit_per_feed | int | 20 | Số lượng bài viết tối đa cần lấy từ mỗi nguồn RSS feed |
limit | int | 10 | Tổng số lượng bài viết thu thập khi gọi get_articles() |
sitemap_url | str / list | None | Đườ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:
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ệu | Mặc Định | Mô Tả |
|---|---|---|---|
site_name | str | Bắt buộc | Tên định danh báo trong hệ thống cấu hình |
request_delay | float | 1.0 | Thời gian tạm dừng (giây) giữa các lần gửi yêu cầu HTTP |
output_path | str | "./data" | Thư mục lưu trữ tập tin tạm |
limit | int | 10 | Số lượng bài viết tối đa cần bóc tách chi tiết |
sitemap_url | str / list | None | URL sitemap cụ thể cần quét dữ liệu |
debug | bool | False | Bậ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 aiohttp và asyncio, 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:
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ệu | Mặc Định | Mô Tả |
|---|---|---|---|
site_name | str | Bắt buộc | Tên định danh trang báo |
max_concurrency | int | 5 | Số lượng kết nối song song tối đa |
sources | list | Bắt buộc | Danh sách đường dẫn Sitemap XML nguồn |
top_n | int | 10 | Số 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:
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ánh | RSS Feeds (Tin Mới) | Sitemap XML (Lịch Sử) |
|---|---|---|
| Tốc độ thu thập | Nhanh | Phụ thuộc số bài và thời gian trễ |
| Phạm vi dữ liệu | Chứa các bài mới phát hành gần đây | Chứa danh sách bài viết theo thời gian lưu trữ của báo |
| Độ sâu thông tin | Có sẵn thông tin tóm tắt và ngày đăng | Cầ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ụng | Giám sát tin tức mới, nhận thông báo tin bài | Xây dựng bộ dữ liệu phân tích, huấn luyện mô hình |
| Cơ chế dự phòng | Tự động chuyển sang Sitemap nếu RSS không hoạt động | Tự độ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ệu | Kiểu Dữ Liệu | Mô Tả Chi Tiết | Ví Dụ Dữ Liệu Mẫu |
|---|---|---|---|
url | str | Đường dẫn URL của bài viết | "https://cafef.vn/thi-truong-chung-khoan-2026.chn" |
title | str | Tiêu đề bài viết | "Thị trường chứng khoán bật tăng mạnh phiên đầu tuần" |
short_description | str | Đ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..." |
content | str | Nộ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_time | datetime | Thời gian xuất bản (dạng ISO) | 2026-04-15 09:30:00 |
author | str | Tên tác giả hoặc nguồn dẫn | "Nguyễn Văn A" / "Theo CafeF" |
category | str | Chuyên mục tin tức | "Chứng khoán" / "Tài chính vĩ mô" |
tags | str | Danh sách từ khóa / Tags bài viết | "VN-Index, Chứng khoán, Lãi suất" |
view_counts | int | Số lượt xem (nếu báo có hiển thị) | 15200 |
image_url | str | Đường dẫn ảnh đại diện bài viết | "https://cdn.cafef.vn/thumb_w/640/image.jpg" |
source | str | Tê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