Vnstock Logo

Nâng cấp từ bản 0.5 lên 1.0

Cộng đồng

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 DataFrame có 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ặc fa.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

Shell
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.5Bả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_quantCài trực tiếp bằng pip với --extra-index-url như trên
Phụ thuộc vnstock thế hệ 5Phụ 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:

Python
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àmBản 0.5Bản 1.0
ta.from_vnstocksource có giá trị mặc địnhMặc định source=None (theo quy tắc trong vnstock.sources)
fa.Dataset.loadMột tham số sourceTách source (nguồn báo cáo) và price_source (nguồn giá), thêm estimate_shares=False
compat.vnstock_ta.DataSourcesource có giá trị mặc địnhMặ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.5Bả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_shares vào fa.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_INPUT thay vì tự thay bằng 0 như trước.
  • Mẫu ngành lấy từ attrs["template"] của bảng; com_type nhận cả dn, tctd, ctck, dnpnt lẫn regular, bank, securities, insurance.
  • Dataset.from_frames() nhận thêm bảng báo cáo theo hồ sơ cột v6 (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ủa vnstock 6 thì giữ prices_adjusted=True (mặc định) và không khai corporate_actions.
  • Đừng chuyển events() thành corporate_actions rồi chạy trên giá đã điều chỉnh với prices_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.warnings có thêm cảnh báo khi dùng biểu phí verified=False hoặc hồ sơ vn_futures.
  • Kết quả của công cụ JSON run_backtest có thêm trường daily_returns, truyền thẳng được sang deflated_sharpe_ratio.

5. Mã lỗi khi tải dữ liệu

Bản 0.5Bả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 5DependencyError 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

  1. Đã cài "vnstock_quant>=1.0,<2" từ kho gói của vnstocks.com trong môi trường ảo mới.
  2. Nếu tải dữ liệu bằng vnstock 6: đã lưu khoá bằng vnstock keys set <nguồn>, xoá tên nguồn cũ và đặt source= hợp lệ.
  3. Với fa: đã truyền total_shares cùng bảng giá gốc qua from_frames() nếu cần chỉ số định giá, và xử lý mã MISSING_INPUT.
  4. Với backtest: không khai corporate_actions khi chạy trên giá đã điều chỉnh.
  5. Đã 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.