Vnstock Logo

Lưu trữ dữ liệu tối ưu

Mở rộng

Mục lục

Tài liệu bản cũ: vnstock_pipeline v2.3.2

Bản mặc định hiện là vnstock_pipeline v3.1.1, gộp bản Cộng đồng và bản Mở rộng vào một thư viện. Trang này giữ lại cho máy còn cài vnstock_pipeline v2.3.2: mã viết theo trang này vẫn chạy với bản đó. Đã cài bản mới thì đọc trang tương ứng của v3.1.1.

Máy đang cài bản nào: chạy python -c "import vnstock; print(vnstock.__version__)", ra số bắt đầu bằng 5. là thế hệ 5.

Giới thiệu

Kể từ phiên bản v2.3.1, hệ thống lưu trữ của vnstock_pipeline đã được tái thiết kế hoàn toàn với cơ chế lưu trữ tập trung. Bạn không còn phải truyền thủ công các biến cấu hình đường dẫn hay lo lắng về việc dữ liệu bị phân mảnh ở nhiều nơi. Hệ thống quản lý vị trí, cấu trúc thư mục, định dạng tệp và cách ly dữ liệu lỗi.

Kiến trúc lưu trữ tập trung (pipeline.toml)

Toàn bộ thông số cấu hình lưu trữ được quản lý tập trung thông qua một tệp cấu hình duy nhất:

  • Mac/Linux: ~/.vnstock/config/pipeline.toml
  • Windows: %USERPROFILE%\.vnstock\config\pipeline.toml

Cấu trúc thư mục linh hoạt

Hệ thống hiện tại hỗ trợ hai chế độ tổ chức thư mục để phù hợp với các nhu cầu khác nhau:

  • Cấu trúc Phẳng - Flat (Mặc định): Dành cho người dùng cá nhân, lược bỏ các cấp thư mục trung gian để dễ dàng truy cập trực tiếp các tệp dữ liệu (.parquet hay .csv).

    Text
    ├── stock_db/
│   ├── ohlcv/                          
│   │   ├── ACB.parquet
│   ├── trades/                         
│   │   ├── ACB.parquet
│   ├── session_stats/                  
│   │   ├── foreign_flow/
│   │   │   └── ACB.parquet

  • Cấu trúc Phân Cấp - Nested: Dành cho các hệ thống dữ liệu lớn, tổ chức chặt chẽ theo từng lớp siêu dữ liệu.

    Text
    ├── stock_db/
│   ├── processed/                      # Lớp dữ liệu
│   │   ├── market/                     # Tên miền
│   │   │   ├── ohlcv/                  # Danh mục
│   │   │   │   ├── 1D/                 # Khung thời gian
│   │   │   │   │   ├── equity/         # Loại tài sản
│   │   │   │   │   │   └── ACB.parquet

Quản trị lưu trữ bằng giao diện dòng lệnh (CLI)

Giao diện dòng lệnh giúp bạn dễ dàng tùy biến dữ liệu mà không cần viết các đoạn mã Python phức tạp.

1. Thay đổi cấu hình cơ bản

Shell
# Xem cấu hình lưu trữ hiện tại
python -m vnstock_pipeline.cli storage config

# Đổi kiến trúc thư mục lưu trữ (từ Flat sang Nested và ngược lại)
python -m vnstock_pipeline.cli storage set-layout nested

# Thay đổi định dạng lưu trữ mặc định (CSV hoặc Parquet)
# Chú ý: Lệnh này sẽ hỏi bạn có muốn chuyển đổi dữ liệu cũ sang chuẩn mới không.
python -m vnstock_pipeline.cli storage set-format parquet -y

2. Dọn dẹp và kiểm soát chất lượng dữ liệu

Để tiết kiệm dung lượng ổ cứng cho máy tính/máy chủ và kiểm tra chất lượng dữ liệu đầu vào trước khi chạy mô hình:

Shell
# Xoá các tệp dữ liệu cũ hơn 90 ngày để giải phóng bộ nhớ
python -m vnstock_pipeline.cli storage cleanup --days 90

# Phân tích chất lượng dữ liệu: phát hiện đứt gãy thời gian và tệp lỗi/quá hạn
python -m vnstock_pipeline.cli storage audit --category ohlcv --stale-days 5

# Xây dựng lại hệ thống mục lục dữ liệu
python -m vnstock_pipeline.cli storage build-catalog

Tính năng bảo vệ cấu trúc dữ liệu (Schema Guard)

Khi nguồn cấp dữ liệu có những thay đổi bất ngờ về cấu trúc bảng (thiếu cột quan trọng hoặc đổi tên cột), hệ thống:

  1. Phát hiện sai lệch cấu trúc: Đối chiếu cấu trúc dữ liệu mới tải về với cấu trúc chuẩn ban đầu.
  2. Cách ly dữ liệu lỗi: Đưa các tệp gây sai lệch cấu trúc vào thư mục cách ly (.tmp/.quarantine/) thay vì ghi đè làm hỏng dữ liệu gốc của bạn. Đồng thời tạo ra tệp .diff.json ghi nhận chi tiết nguyên nhân lỗi.
  3. Các tệp bị cách ly sẽ được xoá sau 14 ngày.

Kiểm tra dữ liệu cách ly:

Shell
# Xem danh sách các tệp dữ liệu bị cách ly do lệch cấu trúc
python -m vnstock_pipeline.cli quarantine list

# Chấp nhận sự thay đổi cấu trúc này và cập nhật nó thành cấu trúc chuẩn mới
python -m vnstock_pipeline.cli quarantine adopt ohlcv ACB

Di chuyển dữ liệu cũ (Migration)

Nếu bạn có một thư mục dữ liệu đã tải bằng bản vnstock_pipeline cũ và muốn tái cấu trúc, hãy tham khảo Hướng dẫn nâng cấp phiên bản. Hệ thống cung cấp công cụ dọn dẹp và đưa dữ liệu cũ vào thư mục lưu trữ mới bằng công cụ dòng lệnh migrate-legacy mà không cần tải lại từ đầu.

Lợi ích của việc sử dụng Parquet so với CSV:

  1. Tiết kiệm dung lượng: Dữ liệu được nén hiệu quả, tệp nhỏ hơn đáng kể so với CSV.
  2. Tốc độ xử lý nhanh: Tối ưu tốc độ đọc/ghi dữ liệu lớn qua thư viện pyarrow.
  3. Ghi nối tiếp an toàn: Ghi đè hoặc chèn dòng dữ liệu mới liên tục mà không làm hỏng cấu trúc tệp, hỗ trợ truy vấn lọc cột nhanh chóng và chính xác.