Cài đặt và thiết lập

Tổng quan

vnstock_quant được phân phối dưới dạng các gói nhị phân dựng sẵn (pre-compiled binary wheels) thông qua kho lưu trữ riêng của Vnstock. Bạn chỉ cần cài đặt bằng công cụ pip tiêu chuẩn của Python 3.10 trở lên mà không cần cài đặt trình biên dịch Rust hay bất kỳ công cụ phát triển phần mềm nào khác.

Cài đặt gói

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. Các lệnh dưới đây chạy trong môi trường đó đã kích hoạt (source ~/.venv/bin/activate; Windows & "$HOME\.venv\Scripts\Activate.ps1"):

# Cài đặt thư viện tính toán vnstock_quant
pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant

# Hoặc cài đặt kèm luôn thư viện vnstock để tự động tải dữ liệu trực tiếp
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant[vnstock]"

Yêu cầu môi trường

• Hệ điều hành: macOS 10.12 trở lên trên chip Intel (x86_64), macOS 11 trở lên trên chip Apple Silicon (arm64); Linux x86_64 và aarch64 dùng glibc 2.17 trở lên (chuẩn manylinux2014).
• Phiên bản Python: Python 3.10 trở lên (một bản dựng dùng chung cho mọi phiên bản từ 3.10).
• Thư viện nền tảng: numpy>=1.24, pandas>=2.0 (tự động cài đặt khi chạy pip).

Kiểm tra trạng thái cấp quyền và bản phát hành

Sau khi cài đặt xong, bạn có thể kiểm tra trạng thái quyền hạn của máy hiện tại bằng hàm vq.entitlement(). Hàm này chạy cục bộ, không tốn lượt tính và không phát sinh lỗi:

import vnstock_quant as vq

# Kiểm tra cấp tài trợ, tính năng mở khoá và số lượt dùng thử còn lại
status = vq.entitlement()
print(status)

Đầu ra của hàm cung cấp các thông tin chẩn đoán chi tiết:

• tier: Cấp tài trợ hiện tại nhận diện được trên máy (guest khi chưa đăng nhập, free, bronze, silver, golden, diamond).
• features: Danh sách các nhóm tính năng đang được phép sử dụng (ta_basic, ta, fa_basic, fa, fa_advanced, risk, portfolio; mô hình định giá dùng chung quyền portfolio).
• trial: Đối với bản Cộng đồng, từ điển này cho biết tổng số lượt dùng thử trong ngày (daily), số lượt đã dùng (used), số lượt còn lại (remaining), số mã tối đa mỗi lần tải (max_symbols) và thời điểm làm mới (resets_at).
• release: Thông tin hạn dùng của bản đang cài: phiên bản (version), có phải bản thử không (pre_release), ngày dựng (build_date), ngày hết hạn (expires_at) và số ngày còn lại (days_left).

Kiểm tra thông tin chi tiết của bản build native:

# Xem thông tin biên dịch lõi Rust
info = vq.build_info()
print(info)

Hệ thống phân cấp ngoại lệ

vnstock_quant xây dựng hệ thống mã lỗi nghiêm ngặt và đồng nhất. Mọi lỗi đều kế thừa từ lớp cơ sở VnstockQuantError, mang mã lỗi ổn định (error code) và thông điệp hướng dẫn xử lý bằng tiếng Việt:

VnstockQuantError (Lớp cơ sở)
├── InvalidParameterError      # Tham số không hợp lệ (mã: QUANT_INVALID_PARAMETER)
├── UnknownIndicatorError      # Tên chỉ báo kỹ thuật không tồn tại (mã: QUANT_UNKNOWN_INDICATOR)
├── UnknownRatioError          # Mã chỉ số tài chính không tồn tại (mã: QUANT_UNKNOWN_RATIO)
├── InputDataError             # Dữ liệu đầu vào sai cấu trúc hoặc rỗng (mã: QUANT_INPUT_DATA)
├── TierRequiredError          # Tính năng đòi hỏi cấp tài trợ cao hơn (mã: QUANT_TIER_REQUIRED)
├── QuotaExceededError         # Hết lượt tính thử nghiệm trong ngày (mã: QUANT_TRIAL_EXHAUSTED)
├── ReleaseExpiredError        # Bản phát hành đã hết hạn hiệu lực (mã: VNSTOCK_RELEASE_EXPIRED)
├── EntitlementError           # Lỗi cấu hình bản quyền hoặc thiết bị
└── DependencyError            # Thiếu thư viện phụ trợ (ví dụ chưa cài vnstock)

Ví dụ bắt lỗi theo nghiệp vụ

import vnstock_quant as vq

try:
    # Ví dụ gọi hàm tính toán cần quyền hạn
    result = vq.portfolio.twr(values, flows)
except vq.TierRequiredError as e:
    print(f"Lỗi quyền hạn [{e.code}]: {e}")
    print(f"Cấp tài trợ yêu cầu tối thiểu: {e.required_tier}")
except vq.QuotaExceededError as e:
    print(f"Đã hết lượt dùng thử hôm nay [{e.code}]. Lượt sẽ được làm mới lúc 00:00.")
except vq.InvalidParameterError as e:
    print(f"Tham số không hợp lệ: {e}")
except vq.VnstockQuantError as e:
    print(f"Lỗi chung của vnstock_quant: {e}")

Tắt cảnh báo hệ thống

Các lưu ý không làm dừng chương trình được phát qua lớp cảnh báo VnstockQuantWarning (ví dụ: cảnh báo tự động bỏ qua các chỉ số nâng cao khi chạy tính toán hàng loạt toàn bộ chỉ số ở cấp Cộng đồng). Bạn có thể tắt cảnh báo này nếu muốn:

import warnings
from vnstock_quant import VnstockQuantWarning

# Bỏ qua các thông báo khuyến nghị của vnstock_quant
warnings.filterwarnings("ignore", category=VnstockQuantWarning)

Các quy ước phương pháp luận chung

Để đảm bảo tính nhất quán trên toàn bộ hệ thống, vnstock_quant áp dụng các quy ước tính toán sau:

Đọc tiếp

• Chỉ báo kỹ thuật — Sử dụng 58 chỉ báo kỹ thuật với tốc độ cao.
• Chỉ số tài chính — Phân tích báo cáo tài chính và 99 chỉ số VAS.
• Đo lường rủi ro & hiệu suất — Đo lường Sharpe, Sortino, VaR và thanh khoản Amihud.