Nâng cấp phiên bản 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 cơ chế 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).
• 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 được đọc từ cấu hình chung.

2. Chuyển đổi mã nguồn cũ

Nếu bạn đang viết Script nhận dữ liệu trong phiên qua WebSocket 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: Để hỗ trợ 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. AI sẽ rà soát mã nguồn dự án của bạn và hỗ trợ cập nhật 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 thư mục dữ liệu cũ (Data Migration)

Nếu bạn đã có một thư mục dữ liệu đã tải bằng 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ụ dọn dẹp và sắp xếp lại dữ liệu cũ vào thư mục lưu trữ mới.

Công cụ migrate-legacy

Chỉ với một dòng lệnh, hệ thống sẽ 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 thư mục chuẩn mới được cấu hình tại pipeline.toml.

# Lệnh chuyển đổi dữ liệu từ thư mục cũ
python -m vnstock_pipeline.cli storage migrate-legacy --source ./old_data_folder

Lợi ích của việc nâng cấp cấu trúc 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ẽ cách ly tệp dữ liệu lỗi vào khu vực .quarantine để bảo vệ dữ liệu gốc.