Cài đặt & Khởi tạo

Cài đặt thư viện

Thư viện vnstock_quant được phát hành dưới dạng gói cài đặt nhị phân dựng sẵn (binary wheels) biên dịch sẵn cho lõi Rust, tích hợp đầy đủ mọi phụ thuộc cần thiết. Bạn không cần cài đặt trình biên dịch C (C compiler) hay thư viện TA-Lib C bên ngoài.

Chạy lệnh cài đặt tiêu chuẩn:

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

Nếu bạn đang xây dựng môi trường Vibe Coding hoặc sử dụng kèm thư viện vnstock, bạn có thể cài đặt đồng thời:

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

Sau khi cài đặt, kiểm tra phiên bản bằng dòng lệnh:

python -c "import vnstock_quant; print(vnstock_quant.__version__)"
# Kết quả: 0.1.3

Khởi tạo ở bản Cộng đồng

Với bản Cộng đồng, bạn không cần nhập bất kỳ khoá API tài trợ nào. Thư viện tự động kích hoạt chế độ dùng thử bản quyền máy tính cục bộ (device-bound trial) ngay khi bạn gọi phép tính đầu tiên:

import pandas as pd
from vnstock_quant import Indicator

# Chuẩn bị dữ liệu mẫu OHLCV
df = pd.DataFrame({
    "open": [25.0, 25.2, 25.5, 25.3, 25.8],
    "high": [25.4, 25.6, 25.8, 25.7, 26.0],
    "low": [24.9, 25.0, 25.2, 25.1, 25.5],
    "close": [25.3, 25.5, 25.4, 25.6, 25.9],
    "volume": [1200000, 1500000, 980000, 1100000, 1850000]
})

# Khởi tạo đối tượng Indicator
ta = Indicator(df)

# Tính chỉ báo SMA 3 phiên (tiêu tốn 1 lượt dùng thử)
sma3 = ta.sma(length=3)
print(sma3)

Tra cứu lượt dùng thử

Bản Cộng đồng được cấp 30 lượt dùng thử mỗi ngày. Để kiểm tra số lượt tính toán còn lại và thời điểm làm mới, dùng hàm entitlement() của chính vnstock_quant (hàm này không tính lượt):

import vnstock_quant as vq

# Kiểm tra trạng thái cấp quyền và số lượt còn lại
trial = vq.entitlement()["trial"]  # None khi cấp hiện tại không bị đếm lượt
if trial:
    print("Số lượt còn lại hôm nay:", trial["remaining"], "/", trial["daily"])
    print("Làm mới lúc:", trial["resets_at"])

Xử lý thông báo khi hết lượt dùng thử

Khi bạn thực hiện quá 30 phép tính trong cùng một ngày, thư viện sẽ phát sinh ngoại lệ chuẩn QuotaExceededError:

from vnstock_quant.errors import QuotaExceededError

try:
    rsi = ta.rsi(length=14)
except QuotaExceededError as e:
    print(f"Thông báo: {e.message}")
    print(f"Mã lỗi: {e.code}")  # QUANT_TRIAL_EXHAUSTED
    print("Vui lòng đợi đến 00:00 (giờ VN) hoặc tài trợ từ cấp Bronze để không bị đếm lượt.")

Chuẩn bị định dạng dữ liệu đầu vào

Để đảm bảo các phép tính chỉ báo kỹ thuật và chỉ số tài chính chạy mượt mà, bảng dữ liệu pandas.DataFrame của bạn cần tuân thủ quy ước chuẩn:

Dữ liệu nến giá kỹ thuật (OHLCV)

• Các cột bắt buộc: open, high, low, close, volume (chữ thường).
• Kiểu dữ liệu: Số thực (float64), riêng cột volume có thể là số thực hoặc số nguyên (int64).
• Thứ tự thời gian: Dữ liệu cần được sắp xếp theo thời gian tăng dần từ quá khứ đến hiện tại.

Dữ liệu báo cáo tài chính (FA)

• Bảng dữ liệu chứa các chỉ tiêu kế toán VAS (ví dụ revenue, net_profit, total_assets, equity...).
• Có thể dùng trực tiếp dữ liệu xuất ra từ hàm BCTC của vnstock: Fundamental().equity("HPG").financial_ratio().

Đọc tiếp

• Chỉ báo kỹ thuật — Khám phá chi tiết 10 chỉ báo kỹ thuật của bản Cộng đồng.
• Chỉ số tài chính — 10 tỷ số BCTC quan trọng nhất để phân tích cổ phiếu.
• Chuyển đổi từ vnstock_ta — Hướng dẫn nâng cấp mã nguồn cũ.