Nâng cấp từ bản 0.5 lên 1.0
Mục lục
Từ ngày 10/11/2026, các phiên bản thuộc thế hệ 5 (vnstock 5.x và vnstock_quant 0.x) đã ngừng xác thực. Để tiếp tục dùng thư viện, bạn cần nâng cấp lên vnstock_quant từ bản 1.0.0 trở đi.
Bản 1.0 giữ nguyên công thức và cách gọi của các hàm tính toán ở bản 0.5. Nếu mã của bạn chỉ truyền bảng pandas.DataFrame tự chuẩn bị vào để tính chỉ báo, chỉ số hay chạy thử chiến lược, mọi thứ chạy ngay không cần sửa. Những chỗ cần cập nhật nằm ở bước tải dữ liệu, vì vnstock 6 chuyển sang kết nối Open API của các nguồn.
Xác định phạm vi cần cập nhật
- Chỉ tính trên
DataFramecó sẵn: nâng cấp môi trường lên 1.0 (mục 1) và chạy lại kiểm thử của bạn. - Có gọi
ta.from_vnstock()hoặcfa.Dataset.load(): xem mục 2 và mục 3. - Có dùng
backtest: xem mục 4. - Có bắt lỗi tự động trong script: xem mục 5.
1. Cài môi trường và gói 1.0
python -m venv ~/.venv && source ~/.venv/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant>=1.0,<2"| Bản 0.5 | Bản 1.0 |
|---|---|
pip install "vnstock_quant[vnstock]" | pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant>=1.0,<2" (không còn extra [vnstock]) |
vnstock install vnstock_quant | Cài trực tiếp bằng pip với --extra-index-url như trên |
Phụ thuộc vnstock thế hệ 5 | Phụ thuộc vnstock>=6.0.0,<7 và vnstock-oapi>=0.1.1,<1; nếu môi trường có vnstock khác thế hệ 6 thì hàm tải báo DependencyError |
Phạm vi bản Cộng đồng ở bản 1.0: 10 chỉ báo kỹ thuật cơ bản, 10 chỉ số tài chính cơ bản và chạy thử chiến lược một mã, theo lượt dùng thử trong ngày (xem Quyền dùng và hạn mức).
2. Hàm tải dữ liệu
Thế hệ 6 không đặt nguồn mặc định. Xoá các tên nguồn cũ của thế hệ 5 khỏi mã (vnstock 6 báo VNSTOCK_INPUT_SOURCE khi gặp tên nguồn không thuộc hệ Open API), lưu khoá của nguồn bạn đã đăng ký bằng vnstock keys set <nguồn>, rồi truyền source= hoặc đặt quy tắc một lần:
import vnstock
vnstock.sources.use("<nguồn A>") # mọi hàm chưa nêu nguồn
vnstock.sources.use("<nguồn B>", route="fundamental.equity.*") # riêng báo cáo tài chính| Hàm | Bản 0.5 | Bản 1.0 |
|---|---|---|
ta.from_vnstock | source có giá trị mặc định | Mặc định source=None (theo quy tắc trong vnstock.sources) |
fa.Dataset.load | Một tham số source | Tách source (nguồn báo cáo) và price_source (nguồn giá), thêm estimate_shares=False |
compat.vnstock_ta.DataSource | source có giá trị mặc định | Mặc định source=None |
Nếu không muốn dùng vnstock 6, bạn chuyển sang đọc bảng có sẵn trên máy, hoặc tự lấy phản hồi gốc bằng vnstock-oapi (xem Tải dữ liệu đầu vào).
3. Chỉ số tài chính (fa)
| Bản 0.5 | Bản 1.0 |
|---|---|
Dataset.load() có sẵn số cổ phiếu và giá gốc theo ngày, nên P/E, P/B có số | Dữ liệu tải qua vnstock 6 không có số cổ phiếu theo ngày và giá lịch sử đã điều chỉnh, nên chỉ số định giá mặc định trả MISSING_MARKET kèm cảnh báo |
Cách tính lại P/E, P/B, EPS, BVPS:
- Khuyến nghị: truyền bảng giá đóng cửa gốc kèm cột
total_sharesvàofa.Dataset.from_frames(statements, prices={...}). - Tham khảo nhanh:
fa.Dataset.load(..., estimate_shares=True)ước tính số cổ phiếu từ vốn điều lệ; có thể lệch đáng kể sau các đợt phát hành.
Những điểm khác:
- Báo cáo chỉ có chỉ tiêu cấp 1 thì chỉ số cần dòng chi tiết trả
MISSING_INPUTthay vì tự thay bằng 0 như trước. - Mẫu ngành lấy từ
attrs["template"]của bảng;com_typenhận cảdn,tctd,ctck,dnpntlẫnregular,bank,securities,insurance. Dataset.from_frames()nhận thêm bảng báo cáo theo hồ sơ cộtv6(report_period,item_id,item_value).- Mỗi lần
Dataset.load()ở bản Cộng đồng nhận tối đa 3 mã.
4. Chạy thử chiến lược (backtest)
- Dùng nến từ
ohlcv()củavnstock6 thì giữprices_adjusted=True(mặc định) và không khaicorporate_actions. - Đừng chuyển
events()thànhcorporate_actionsrồi chạy trên giá đã điều chỉnh vớiprices_adjusted=False: sự kiện quyền sẽ bị tính hai lần. - Cổ tức tiền và cổ phiếu thưởng cùng ngày giao dịch không hưởng quyền: cổ tức luôn tính trên số cổ phiếu trước khi nhận thưởng, không còn phụ thuộc thứ tự khai.
res.warningscó thêm cảnh báo khi dùng biểu phíverified=Falsehoặc hồ sơvn_futures.- Kết quả của công cụ JSON
run_backtestcó thêm trườngdaily_returns, truyền thẳng được sangdeflated_sharpe_ratio.
5. Mã lỗi khi tải dữ liệu
| Bản 0.5 | Bản 1.0 |
|---|---|
VNSTOCK_TIER_ROUTE khi tải giá | Bộ mã của tầng Open API: VNSTOCK_INPUT_SOURCE, VNSTOCK_ROUTE_UNSUPPORTED, VNSTOCK_CREDENTIAL_MISSING, VNSTOCK_SOURCE_AUTH, VNSTOCK_SOURCE_LOGIN, VNSTOCK_SOURCE_OTP, VNSTOCK_SOURCE_RATE_LIMITED |
DependencyError khi chưa cài vnstock 5 | DependencyError khi vnstock đang cài không thuộc thế hệ 6 |
| — | Cảnh báo một lần mỗi tiến trình khi tải báo cáo tài chính (dữ liệu Open API đang ở mức thử nghiệm) |
Xem cây ngoại lệ tại Quy ước dữ liệu đầu vào và xử lý lỗi.
6. Thời hạn của bản cài
Bản 1.0.0 là bản chính thức (vq.entitlement()["release"]["pre_release"] == False), dùng được 1 năm kể từ ngày phát hành (xem release["expires_at"]). Gần tới hạn, release["warning"] hiện lời nhắc cập nhật. Nếu từng cài bản thử nghiệm 1.0.0rc1 hay 1.0.0rc2 (hạn 30 ngày), hãy chạy lại lệnh pip install -U ở mục 1.
Danh sách kiểm tra khi nâng cấp xong
- Đã cài
"vnstock_quant>=1.0,<2"từ kho gói củavnstocks.comtrong môi trường ảo mới. - Nếu tải dữ liệu bằng
vnstock6: đã lưu khoá bằngvnstock keys set <nguồn>, xoá tên nguồn cũ và đặtsource=hợp lệ. - Với
fa: đã truyềntotal_sharescùng bảng giá gốc quafrom_frames()nếu cần chỉ số định giá, và xử lý mãMISSING_INPUT. - Với
backtest: không khaicorporate_actionskhi chạy trên giá đã điều chỉnh. - Đã chạy lại toàn bộ kịch bản và đọc các cảnh báo
VnstockQuantWarningít nhất một lần.
Hướng dẫn nâng cấp cho các mô-đun của bản Mở rộng ở Nâng cấp từ bản 0.5 bản Mở rộng.
