Cài đặt và xác thực

Trang này hướng dẫn bạn cài đặt thư viện vnstock_pipeline thế hệ 5, thiết lập môi trường Python, đăng nhập tài khoản tài trợ và kiểm tra trạng thái hoạt động của hệ thống.

Yêu cầu hệ thống

• Hệ điều hành: macOS (Apple Silicon hoặc Intel), Linux (Ubuntu, Debian, CentOS), Windows (10/11 x64).
• Phiên bản Python: Python 3.10 trở lên.
• Môi trường: Cài vào cùng môi trường cố định với vnstock: ~/.venv trên macOS và Linux, $HOME\.venv trên Windows; trên Google Colab hay GitHub Codespaces thì cài thẳng, không tạo môi trường. Cách tạo môi trường và trường hợp máy còn bản 4.x ở trang Cài đặt vnstock.

python3 -m venv ~/.venv            # macOS, Linux (bỏ qua nếu đã có)
source ~/.venv/bin/activate

py -m venv "$HOME\.venv"          # Windows (bỏ qua nếu đã có)
& "$HOME\.venv\Scripts\Activate.ps1"

Các lệnh dưới đây chạy trong môi trường đã kích hoạt.

Cài đặt thư viện

Thư viện vnstock_pipeline được phân phối qua kho gói riêng của Vnstock. Bạn có thể cài đặt bằng một trong hai cách sau:

Cách 1: Cài đặt trực tiếp qua pip

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-pipeline

Tuỳ chọn --extra-index-url giúp pip nhận diện và tải đúng phiên bản mới nhất từ máy chủ phân phối của dự án, trong khi các thư viện phụ thuộc (pandas, pyarrow, requests) vẫn được tải từ PyPI chuẩn.

Cách 2: Cài đặt qua trình quản lý vnstock

Nếu bạn đã cài đặt thư viện vnstock thế hệ 5 trên máy:

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock
vnstock register
vnstock install

Lệnh vnstock install sẽ nhận diện cấp tài trợ của tài khoản và cài đặt đầy đủ các thư viện được cấp quyền tương ứng cho bạn.

Đăng nhập và xác thực

Thư viện sử dụng hệ thống xác thực tập trung dùng chung cho toàn bộ hệ sinh thái Vnstock. Bạn chỉ cần đăng nhập một lần duy nhất trên máy tính:

vnstock register

Khi được nhắc, hãy dán khoá API lấy từ trang tài khoản của bạn trên website vnstocks.com. Thông tin xác thực sẽ được mã hoá và lưu trữ an toàn trong thư mục cấu hình cá nhân (~/.vnstock/).

Kiểm tra trạng thái cấp phép

Bạn có thể kiểm tra nhanh trạng thái tài khoản và cấp tài trợ trực tiếp bằng Python:

import vnstock_pipeline

# Kiểm tra trạng thái xác thực và thời hạn bản phát hành
status = vnstock_pipeline.license_status()
print(status)

{
    'active': True,
    'entitled': True,
    'tier': 'golden',
    'release': {
        'version': '3.1.1',
        'valid_days_remaining': 342,
        'expired': False
    }
}

Các thông tin quan trọng trong kết quả:

• active: Trạng thái hoạt động của khoá xác thực trên máy.
• entitled: Xác nhận tài khoản có quyền chạy các tác vụ tải dữ liệu (Golden trở lên).
• tier: Cấp tài trợ hiện tại của bạn; entitled chỉ là true khi cấp là golden hoặc diamond.
• release: Thông tin về bản phát hành hiện tại trên máy bạn.

Thời hạn bản phát hành (Release Lifetime)

Để quy trình tải dữ liệu theo kịp các thay đổi cấu trúc từ nguồn, mỗi bản phát hành của vnstock_pipeline có một vòng đời hoạt động nhất định:

• Thời hạn: Mỗi bản dùng được 365 ngày kể từ ngày công bố.
• Cảnh báo nâng cấp: Khi thời hạn còn dưới 30 ngày, thư viện sẽ hiển thị một thông báo nhắc nhở (FutureWarning) ở lần gọi hàm đầu tiên để bạn chủ động nâng cấp.
• Khi hết hạn: Các lệnh tải dữ liệu trực tuyến (run ...) sẽ tạm dừng và thông báo mã VNSTOCK_RELEASE_EXPIRED kèm câu lệnh nâng cấp bằng pip. Khi đó, bạn chỉ cần chạy lại lệnh cài đặt pip install -U ... để cập nhật lên phiên bản mới nhất.

Đọc dữ liệu đã lưu không cần mạng

Dữ liệu bạn đã tải nằm trên máy và do bạn quản lý; quyền với dữ liệu vẫn theo điều kiện của nguồn. Các thao tác đọc, lọc, xem cấu trúc và xuất dữ liệu cục bộ:

from vnstock_pipeline.core.storage import DataManager

manager = DataManager()
# Đọc dữ liệu từ đĩa hoàn toàn ngoại tuyến (offline)
df = manager.load_ohlcv("ACB")

Hoặc qua dòng lệnh:

vnstock_pipeline inspect data/ohlcv/ACB.parquet
vnstock_pipeline export amibroker --date latest

Tất cả các thao tác trên đều chạy trực tiếp trên đĩa cứng của bạn mà không gửi bất kỳ yêu cầu mạng nào và không cần kiểm tra quyền tài khoản.

Bước tiếp theo

Sau khi cài đặt và xác thực thành công, mời bạn xem trang Cấu hình và lưu trữ để thiết lập thư mục lưu trữ và làm quen với lớp DataManager.