Vnstock thế hệ 5
Mục lục
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 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 đây | Từ 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ước | Trang | Nội dung chính |
|---|---|---|
| 1 | Cài đặt | Cà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 |
| 3 | Truy xuất thông tin tham chiếu | Reference(): danh sách mã, hồ sơ công ty, phân ngành ICB, chỉ số, sự kiện |
| 4 | Truy xuất dữ liệu thị trường | Market(): 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ế |
| 5 | Truy xuất báo cáo tài chính | Fundamental(): kết quả kinh doanh, cân đối kế toán, lưu chuyển tiền tệ, chỉ số tài chính |
| 6 | Truy 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 |
| 7 | Cấp tài khoản và giới hạn | Danh 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 |
| 8 | Xử lý lỗi | Cá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ợ:
- Xếp hạng và độ rộng thị trường: Thống kê và xếp hạng thị trường (Insights) với
Insights(). - Định giá toàn thị trường: Định giá thị trường (Analytics) với
Analytics(). - Tỷ giá ngoại tệ ngân hàng: Tỷ giá ngân hàng (Retail) với
Retail(). - Dữ liệu chứng chỉ quỹ: Thông tin quỹ mở (Fund) với
Fund(). - Tài liệu tham khảo kỹ thuật: Kiến trúc thư viện và Nguồn dữ liệu bên thứ ba.
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ện | Tên gói cài đặt (pip) | Phiên bản | Vai trò | Cấp tối thiểu |
|---|---|---|---|---|
vnstock | vnstock | v5.x | Thư 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_pipeline | vnstock-pipeline | v3.x | Quả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ệu | Golden |
vnstock_news | vnstock-news | v3.x | Theo dõi tin tức tài chính qua RSS và sơ đồ trang tin chính thức | Silver |
vnstock_quant | vnstock-quant | v0.3.x | Tí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ềnlength="30d"hoặc dùngstart,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.InputErrorkế thừaValueError, giúp khốitry...except ValueErrorcũ 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ấplevel, đơ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ằngformat="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ớpBrokerkhô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.
