Giới thiệu Vnstock Pipeline

Giới thiệu

Với mô hình luồng xử lý tự động (pipeline), thư viện giúp bạn giải quyết các bài toán dữ liệu phức tạp:

• Quản lý dữ liệu tập trung: Tất cả thiết lập về vị trí lưu, định dạng tệp (Parquet, CSV, Excel) và cấu trúc thư mục đều được điều khiển qua một tệp cấu hình duy nhất (pipeline.toml).
• Bảo vệ toàn vẹn dữ liệu: Các quy trình kiểm duyệt chạy ngầm giúp phát hiện dữ liệu rỗng, đứt gãy thời gian, và tự động cách ly các tệp lỗi vào khu vực riêng (.quarantine), bảo vệ cơ sở dữ liệu chính của bạn khỏi sai lệch cấu trúc.
• Quản trị qua dòng lệnh: Hỗ trợ bộ công cụ dòng lệnh giúp kiểm soát, di chuyển, chuyển đổi định dạng và dọn dẹp dữ liệu cũ nhanh chóng mà không cần viết mã lập trình.
• Tác vụ tổng hợp dữ liệu đa dạng: Cung cấp sẵn các luồng tải dữ liệu đầy đủ từ giá lịch sử (OHLCV), sổ lệnh trong phiên, báo cáo tài chính, giao dịch tổ chức, cho đến tin tức và sự kiện doanh nghiệp.
• Lập lịch và phục hồi lỗi thông minh: Tự động điều phối tải số lượng lớn mã cổ phiếu với tốc độ cao. Ghi nhận chi tiết các mã lỗi do sự cố mạng và hỗ trợ tải bù nhanh chóng.
• Tích hợp phần mềm phân tích: Hỗ trợ xuất dữ liệu và đồng bộ trực tiếp vào cơ sở dữ liệu AmiBroker thông qua tiến trình tự động (chỉ hỗ trợ trên hệ điều hành Windows).

Bạn có thể bắt đầu nhanh chóng bằng cách sử dụng công cụ dòng lệnh hoặc xem các mẫu lệnh tải dữ liệu thường dùng.

Hướng dẫn cài đặt

Yêu cầu hệ thống

• Python phiên bản 3.10 trở lên.
• Các thư viện phụ thuộc chính: pandas, numpy, requests, duckdb.

Cài đặt thư viện

Bạn nên sử dụng chương trình cài đặt tự động do Vnstock cung cấp, tương thích cho từng hệ điều hành để đảm bảo môi trường hoạt động ổn định nhất.

Kiến trúc tổng quan

vnstock_pipeline được xây dựng dựa trên cấu trúc phân lớp linh hoạt, giúp dễ dàng mở rộng và bảo trì:

Luồng xử lý dữ liệu

Dữ liệu thô (API/WebSocket)
    │
    ▼
[Trình thu thập] → Lấy dữ liệu (theo nhóm hoặc từng mã riêng lẻ)
    │
    ▼
[Trình kiểm duyệt] → Kiểm tra tính hợp lệ, phát hiện sai sót cấu trúc
    │
    ▼
[Trình biến đổi] → Làm sạch, tính toán thêm thông tin, loại bỏ dữ liệu trùng
    │
    ▼
[Trình xuất tệp] → Đọc cấu hình lưu trữ tập trung -> Ghi ra Parquet/CSV/Excel
    │
    ▼
[Kho dữ liệu] → Lưu vào máy tính (~/stock_db) & Cập nhật danh mục

Bộ điều phối (Scheduler) sẽ quản lý toàn bộ quá trình này:

• Tự động chia công việc thành nhiều luồng chạy song song để tăng tốc độ tải.
• Tự nhận diện và bỏ qua các mã không có dữ liệu để tiết kiệm thời gian chờ.
• Ghi chép nhật ký hoạt động chi tiết và xuất danh sách các mã lỗi ra tệp error_log.csv để dễ dàng chạy tải bù.

Cấu trúc lưu trữ dữ liệu

Thay vì phải tự khai báo đường dẫn thủ công, mọi trình xuất dữ liệu giờ đây đều tự động đọc cấu hình từ tệp trung tâm. Hệ thống cung cấp hai cách bố trí thư mục để bạn tuỳ chọn:

• Bố cục Phẳng (Flat - Mặc định): Dành cho người dùng cá nhân muốn tìm kiếm tệp nhanh chóng (Ví dụ: stock_db/ohlcv/ACB.parquet).
• Bố cụ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 phân lớp và loại tài sản (Ví dụ: stock_db/processed/market/ohlcv/1D/equity/ACB.parquet).

Bản quyền dữ liệu

Công cụ Vnstock Pipeline đóng vai trò tự động hóa việc kết nối thông qua các tính năng của thư viện lõi Vnstock Data. Tất cả dữ liệu bạn truy cập thuộc sở hữu và quản lý của các nguồn cung cấp gốc. Vnstock không lưu trữ, sao chép, hay tái phân phối bất kỳ dữ liệu nào.

Miễn trừ trách nhiệm