Hướng Dẫn Nâng Cấp vnstock_pipeline v2.3.1

Bản cập nhật v2.3.1 mang đến thay đổi lớn trong kiến trúc lưu trữ dữ liệu với Kho lưu trữ tập trung (Centralized Storage) và loại bỏ một số thành phần phụ trợ không cần thiết nhằm tối ưu tốc độ.

Tài liệu này hướng dẫn cách chuyển đổi hệ thống cũ của bạn sang phiên bản kiến trúc mới một cách mượt mà và an toàn.

📌 1. Tổng Quan Những Thay Đổi Lớn

• Quản lý cấu hình tập trung (pipeline.toml): Mọi cài đặt về nơi lưu trữ, định dạng xuất mặc định không còn nằm rải rác trong code. Bạn chỉ cần điều chỉnh một lần thông qua công cụ dòng lệnh (CLI).
• Tự động nhận diện thư mục lưu: Các lớp tải dữ liệu (Exporter) không yêu cầu truyền tham số base_path nữa; đường dẫn tự động được nhận dạng.

🔄 2. Chuyển Đổi Mã Nguồn Cũ

Nếu bạn đang viết Script để kết nối WebSocket thời gian thực theo cấu trúc cũ, bạn cần gỡ bỏ các khai báo sử dụng bộ xử lý cơ sở dữ liệu và chuyển sang định dạng phẳng (như .csv hoặc .parquet).

Gợi ý sử dụng AI Agent: Để tự động hóa việc tái cấu trúc mã nguồn một cách nhanh chóng, bạn có thể gọi AI Agent và kích hoạt Kỹ năng (Skill) migration-assistant được tích hợp sẵn trên website (thay thế cho phiên bản cũ trước đây lưu trên Github). AI sẽ quét mã nguồn dự án của bạn và thực hiện thay thế sang cấu trúc mới nhất.

Cú pháp cũ (v2.2):

from vnstock_pipeline.stream import WSSClient, DuckDBProcessor

client = WSSClient(market="HOSE")
client.add_processor(DuckDBProcessor("data/market_data.db"))

Cú pháp mới (v2.3.1):

from vnstock_pipeline.stream import WSSClient, CSVProcessor

client = WSSClient(market="HOSE")
# Truyền naming="standard" để dữ liệu theo chuẩn FIX/Bloomberg (Ví dụ: total_volume, price)
client.add_processor(CSVProcessor("data/{event_type}_%Y-%m-%d.csv", naming="standard"))

📋 3. Di chuyển kho dữ liệu cũ (Data Migration)

Nếu bạn đã có một thư mục dữ liệu tự thu thập từ bản vnstock_pipeline cũ, bạn không cần phải xóa đi và tải lại từ đầu. Hệ thống cung cấp công cụ tự động dọn dẹp và sắp xếp lại dữ liệu cũ vào kho lưu trữ mới.

Công cụ migrate-legacy

Chỉ với một dòng lệnh, hệ thống sẽ tự động nhận diện định dạng, phân loại nhóm dữ liệu (ohlcv, trades, finance...) và sắp xếp khoa học vào kho chuẩn mới được cấu hình tại pipeline.toml.

# Lệnh tự động chuyển đổi dữ liệu từ kho lưu trữ cũ
python -m vnstock_pipeline.cli storage migrate-legacy --source ./old_data_folder

Lợi ích của việc nâng cấp kho lưu trữ

1. Quản trị dễ dàng: Dữ liệu có thể luân chuyển nhanh chóng giữa bố cục phẳng (Flat) và phân cấp (Nested) chỉ bằng 1 dòng lệnh.
2. Cảnh báo lệch cấu trúc (Schema Guard): Từ v2.3.1, khi cấu trúc bảng dữ liệu gốc có thay đổi đột ngột làm hỏng CSDL, hệ thống sẽ tự động cách ly tệp dữ liệu lỗi vào khu vực .quarantine để bảo vệ dữ liệu gốc an toàn tuyệt đối.