Nâng cấp từ bản 2.x
Mục lục
Trang này dành cho người dùng đang có kịch bản truy xuất và lưu trữ dữ liệu xây dựng bằng vnstock_pipeline
bản 2.x và muốn chuyển sang thế hệ 5 để dùng lõi xử lý mới và cơ chế kiểm soát chất lượng dữ liệu.
Khả năng tương thích ngược
Thế hệ 5 của vnstock_pipeline được thiết kế như một bản nâng cấp thay thế trực tiếp (drop-in replacement):
- Đường dẫn import giữ nguyên: Các lớp lập trình cốt lõi như
DataManager,StorageConfig,PathBuildertiếp tục import từ các đường dẫn quen thuộc (vnstock_pipeline.core.storage). - Giao diện dòng lệnh đồng nhất: Toàn bộ các câu lệnh CLI như
storage,run ohlcv,run trades,export amibrokerđều giữ nguyên cú pháp tham số và hành vi hoạt động. - Dữ liệu cũ tiếp tục đọc được: Các tệp Parquet và CSV đã tạo từ bản 2.x hoàn toàn có thể đọc trực tiếp bằng thế hệ 5 mà không bắt buộc phải tải lại từ đầu.
Bảng đối chiếu những thay đổi cốt lõi
| Hạng mục | Bản cũ (2.x) | Thế hệ 5 (3.x) |
|---|---|---|
| Xác thực tài khoản | Quản lý tệp khoá riêng rẽ cho từng thư viện | Đăng nhập một lần duy nhất qua lệnh vnstock register, dùng chung cho cả hệ sinh thái |
| Kiểm soát cấu trúc | Người dùng tự kiểm tra dữ liệu | Đối chiếu Schema Baseline và cách ly dữ liệu lỗi vào .quarantine |
| Gián đoạn kết nối khi tải theo lô | Dễ phải chạy lại toàn bộ khi mất kết nối giữa chừng | Ghi nhận tệp lỗi và hỗ trợ tải bù nhanh với --retry-errors |
| Khung Streaming | Đi kèm nguồn cấp đóng gói sẵn | Chuyển sang khung kết nối mở SocketIOClient, người dùng tự chủ động cấu hình nguồn cấp |
| Cây thư mục dữ liệu | Phụ thuộc lệnh tree cài thêm trên hệ điều hành | Tự dựng cây thư mục trực quan trực tiếp từ mã nguồn, chạy mượt mà trên cả Windows |
| Vòng đời phát hành | Không giới hạn thời gian bản phát hành | Bản chính thức có thời hạn 365 ngày để bản cài trên máy theo kịp các thay đổi từ nguồn |
Các điểm cần lưu ý khi nâng cấp
1. Thay đổi cơ chế streaming nguồn cấp
Ở thế hệ 5, các mô-đun streaming đóng gói sẵn của nguồn bên thứ ba trong bản 2.x đã được loại bỏ để tuân thủ
chính sách an toàn và độc lập của hệ sinh thái. Khi gọi các lớp streaming cũ, hệ thống sẽ trả về mã lỗi
PIPELINE_FEATURE_REMOVED.
Nếu dự án của bạn có nhu cầu nhận dữ liệu trực tiếp trong phiên, hãy chuyển sang sử dụng SocketIOClient hoặc
BaseWebSocketClient và cấu hình địa chỉ nguồn cấp của riêng bạn theo hướng dẫn tại trang
Khung streaming dữ liệu.
2. Di chuyển dữ liệu cũ sang cấu trúc mới
Nếu thư mục dữ liệu cũ của bạn được tổ chức theo các quy ước trước đây và bạn muốn chuẩn hoá về cấu trúc tập trung của thế hệ 5:
vnstock_pipeline storage migrate-legacy --source /duong-dan/kho-du-lieu-cuLệnh này sẽ rà soát toàn bộ thư mục dữ liệu cũ, chuẩn hoá lại quy cách đặt tên tệp và cập nhật danh mục metadata tập trung.
Quy trình nâng cấp từng bước
Bước 1: Cài đặt phiên bản mới
pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-pipelineKiểm tra phiên bản sau khi cài đặt:
python -c "import vnstock_pipeline; print(vnstock_pipeline.__version__)"
# Kết quả hiển thị: 3.1.1Bước 2: Đăng nhập tài khoản
Nếu máy tính của bạn chưa đăng nhập tài khoản Vnstock:
vnstock registerNhập khoá API của tài khoản thuộc chương trình tài trợ từ cấp Golden trở lên.
Bước 3: Khởi tạo tệp cấu hình mới
vnstock_pipeline storage init-configKiểm tra lại đường dẫn base_path trong tệp pipeline.toml vừa tạo để trỏ đúng vào thư mục lưu trữ dữ liệu của bạn.
Bước 4: Chạy kiểm thử đọc dữ liệu
Kiểm tra xem mã nguồn Python của bạn có đọc được dữ liệu hiện có hay không:
from vnstock_pipeline.core.storage import DataManager
manager = DataManager()
# Đọc thử 5 dòng dữ liệu của một mã có sẵn
df = manager.load_ohlcv("VNM")
print(df.head())Nếu dữ liệu hiển thị chính xác, hệ thống của bạn đã sẵn sàng hoạt động với các tính năng mới của thế hệ 5.