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ý cấu hình lưu trữ 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: Có sẵn các tác vụ giúp bạn tải dữ liệu từ nguồn bên thứ ba, gồm 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, 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 việc cập nhật cho danh sách mã bạn theo dõi, chỉ tải phần dữ liệu mới. Ghi nhận chi tiết các mã lỗi do sự cố mạng và cho phép tải bù đúng những mã còn thiếu thay vì chạy lại từ đầu.
• 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ôi trường hoạt động ổn định.

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ô từ nguồn (API/WebSocket)
    │
    ▼
[Trình truy xuất] → 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
    │
    ▼
[Lưu trữ cục bộ] → 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:

• Chia công việc cho một số luồng chạy đồng thời có giới hạn, có khoảng nghỉ giữa các yêu cầu và tự chờ khi nguồn yêu cầu giảm tần suất.
• 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. Dữ liệu bạn truy cập qua thư viện thuộc quyền của nguồn gốc. Vnstock không vận hành kho dữ liệu thị trường để bán lại; dữ liệu nghiệp vụ nằm trên hạ tầng do bạn cấu hình, còn dịch vụ tài khoản, giấy phép và hạn mức xử lý dữ liệu theo Chính sách quyền riêng tư.

Miễn trừ trách nhiệm