Vnstock Logo

Vnstock thế hệ 5

Mở rộng

Mục lục

Tài liệu phiên bản trước: vnstock v5.0.1

Trang này viết cho phiên bản trước thế hệ 6 và được giữ để tra cứu. Phiên bản hiện hành là vnstock v6.0.1 — xem tài liệu v6.0.1 và hướng dẫn chuyển sang thế hệ 6.

Trang lưu trữ: tài liệu thế hệ 5

Trang này viết cho vnstock thế hệ 5, giữ lại để tra cứu.

vnstock thế hệ 5 là thư viện Python hiện đại giúp bạn tự truy xuất dữ liệu chứng khoán, tài chính và kinh tế vĩ mô từ các nguồn bên thứ ba về máy cá nhân, nhận về bảng pandas.DataFrame có tên cột thống nhất. Thư viện chạy trực tiếp trên môi trường của bạn với lõi tính toán hiệu năng cao bằng Rust; truy vấn đi thẳng từ máy bạn tới nguồn dữ liệu.

Thế hệ 5 hợp nhất toàn bộ trải nghiệm trước đây thành một thư viện duy nhất mang tên vnstock cho mọi cấp tài khoản:

Trước đâyTừ thế hệ 5
vnstock 4.x (bản Cộng đồng)vnstock 5.x, dùng không khoá hoặc với khoá cấp Cộng đồng
vnstock_data 3.x (bản Mở rộng)vnstock 5.x, dùng với khoá cấp quyền sử dụng (Bronze, Silver, Golden, Diamond)

Cùng một lệnh cài, cùng tên lớp, cùng cách gọi.


Đọc theo thứ tự này

Tám trang dưới đây dẫn bạn qua toàn bộ quy trình thiết lập, xác thực và truy xuất các nhóm dữ liệu cốt lõi:

BướcTrangNội dung chính
1Cài đặtCài vào môi trường ảo ~/.venv, Google Colab, nâng cấp và hạn dùng của bản cài
2Đăng nhập và dòng lệnhĐăng nhập bằng khoá API, xem cấp và hạn mức sử dụng, chẩn đoán môi trường
3Truy xuất thông tin tham chiếuReference(): danh sách mã, hồ sơ công ty, phân ngành ICB, chỉ số, sự kiện
4Truy xuất dữ liệu thị trườngMarket(): nến giá OHLCV, khớp lệnh, bảng giá của cổ phiếu, phái sinh, chứng quyền, tài sản quốc tế
5Truy xuất báo cáo tài chínhFundamental(): kết quả kinh doanh, cân đối kế toán, lưu chuyển tiền tệ, chỉ số tài chính
6Truy xuất dữ liệu kinh tế vĩ môMacro(): GDP, CPI, xuất nhập khẩu, FDI, lãi suất, tỷ giá, cung tiền
7Cấp tài khoản và giới hạnDanh mục hàm theo cấp, số kỳ báo cáo, độ dài lịch sử nến, hạn mức chung
8Xử lý lỗiCác loại ngoại lệ có kiểu, mã lỗi và cách bắt lỗi an toàn

Mỗi trang hàm đều ghi rõ điều kiện cấp tài khoản: Mọi cấp (Khách, Cộng đồng, Gói quyền sử dụng) hay Gói quyền sử dụng (Bronze trở lên).


Tính năng mở rộng và tham khảo

Khi cần phân tích chuyên sâu hơn, các nhóm tính năng mở rộng cung cấp công cụ bổ trợ:


Hệ sinh thái thư viện trong đợt phát hành thế hệ 5

Đợt phát hành Vnstock thế hệ 5 quy tụ các thư viện chuyên biệt phục vụ từng khâu trong chu trình nghiên cứu đầu tư. Toàn bộ hệ sinh thái dùng chung cơ chế xác thực và đăng nhập một lần qua lệnh vnstock register.

Tuy vậy, mỗi thư viện thành phần mang số hiệu phiên bản riêng (semantic versioning), phản ánh lịch sử và lộ trình phát triển độc lập của từng gói:

Thư việnTên gói cài đặt (pip)Phiên bảnVai tròCấp tối thiểu
vnstockvnstockv5.xThư viện cốt lõi truy xuất dữ liệu chứng khoán, tài chính, vĩ môMọi cấp
vnstock_pipelinevnstock-pipelinev3.xQuản lý quy trình lưu trữ tệp cục bộ (Parquet, DuckDB), tải theo lô và bảo vệ dữ liệuGolden
vnstock_newsvnstock-newsv3.xTheo dõi tin tức tài chính qua RSS và sơ đồ trang tin chính thứcSilver
vnstock_quantvnstock-quantv0.3.xTính toán định lượng chuyên sâu (TA, FA, Risk, Portfolio, Valuation) với lõi Rust hiệu năng cao (thay vnstock_ta)Cộng đồng dùng thử 30 lượt/ngày; Gói quyền sử dụng mở đầy đủ

Bên cạnh 4 thư viện xử lý trên, đợt phát hành thế hệ 5 còn bao gồm công cụ cầu nối cục bộ Vnstock MCP (vnstock-mcp v0.4.x) giúp Trợ lý AI trực tiếp gọi bộ thư viện Vnstock ngay trên máy cá nhân.


Đang có mã viết cho bản cũ

Tài liệu lưu trữ vẫn ở nguyên vị trí cũ để tra cứu (chọn phiên bản ở ô cạnh tiêu đề trang để xem).

Khi chuyển sang thế hệ 5, phần lớn mã viết theo cú pháp giao diện hợp nhất của vnstock_data chạy tiếp bình thường: chỉ cần đổi dòng import sang from vnstock import .... Các lớp kiểu cũ (Quote, Listing, Company, Finance, Trading) vẫn import được.

Bốn điểm cần lưu ý nhất khi chạy mã cũ:

  • ohlcv(length=N) trả N nến của khung thời gian đang hỏi (thay vì hiểu là N ngày như bản cũ). Muốn lấy theo số ngày, truyền length="30d" hoặc dùng start, end.
  • Lỗi là ngoại lệ có kiểu mang thuộc tính code, không phải dòng chữ in ra rồi trả về None. InputError kế thừa ValueError, giúp khối try...except ValueError cũ vẫn bắt được.
  • Báo cáo tài chính chuẩn hoá theo chuẩn VAS: toàn bộ chỉ tiêu chuẩn hoá theo Chuẩn mực Kế toán Việt Nam với mã cố định id, phân cấp level, đơn vị unit, mặc định trả bảng dạng dài (format="long") hoặc chuyển sang dạng rộng bằng format="wide". Chi tiết xem bài viết Phân tích báo cáo tài chính từ cấu trúc dữ liệu Vnstock.
  • Lớp Vnstock() của bản 4.x và lớp Broker không còn ở thế hệ 5.

Xem hướng dẫn chuyển đổi chi tiết:


Phạm vi công cụ và miễn trừ

  • Thư viện không đặt lệnh và không kết nối tài khoản chứng khoán của công ty chứng khoán.
  • Thư viện không cung cấp khuyến nghị đầu tư, không phát tín hiệu mua bán. Mọi số liệu do bạn tự truy xuất và tự phân tích.
  • Dữ liệu đến từ các nguồn bên thứ ba mà bạn kết nối; thư viện không sở hữu hay phân phối lại dữ liệu gốc. Khi nguồn thay đổi cấu trúc hoặc gặp gián đoạn, thư viện báo lỗi rõ ràng.
  • Thư viện không phải mã nguồn mở, được phát hành dưới dạng gói nhị phân dựng sẵn theo giấy phép sử dụng cá nhân.