Giới thiệu Vnstock bản Mở rộng
Mục lục
Bản mặc định hiện là vnstock v5.0.0, gộp bản Cộng đồng và bản Mở rộng vào một thư viện. Trang này giữ lại cho máy còn cài vnstock_data v3.2.9: mã viết theo trang này vẫn chạy với bản đó. Đã cài bản mới thì đọc trang tương ứng của v5.0.0.
Máy đang cài bản nào: chạy python -c "import vnstock; print(vnstock.__version__)", ra số bắt đầu bằng 5. là thế hệ 5.
Dành cho người tài trợ đã tham gia chương trình Vnstock Sponsor hoặc người dùng muốn so sánh tính năng giữa bản Cộng đồng (vnstock, công khai mã nguồn theo giấy phép riêng, miễn phí cho cá nhân, học tập và nghiên cứu) và bản Mở rộng (vnstock_data) trước khi quyết định tài trợ.
Tổng quan so sánh
| Tiêu chí | vnstock | vnstock_data |
|---|---|---|
| Loại | Mã nguồn công khai theo giấy phép riêng | Mã nguồn đóng (cấm sao chép, tái phân phối) |
| Mức phí | Miễn phí cho cá nhân, học tập và nghiên cứu | Tham gia đóng góp qua Gói tài trợ |
| Phân phối | Công khai qua PyPI và Github | Tại website qua trình cài đặt riêng |
| Hạn mức | Một hạn mức chung mức cơ bản cho mọi thư viện, chia theo giờ, ngày, tháng | Hạn mức chung lớn hơn theo cấp tài trợ, dùng chung cho mọi thư viện |
| Yêu cầu đồng thời | Người dùng tự kiểm soát; nên giữ mức đồng thời thấp và có khoảng nghỉ | Thư viện gộp kết nối, dừng gọi khi nguồn từ chối và tạm ngừng khi nguồn không phản hồi |
| Dữ liệu trong phiên | Qua REST API, độ trễ tương đối khoảng 1-5 giây theo nguồn | Qua WebSocket, cập nhật theo độ trễ của nguồn |
| Phạm vi dữ liệu | Hạn chế: Xem chi tiết | Đầy đủ phạm vi dữ liệu nguồn trả về. Xem chi tiết |
| Mục đích sử dụng | Bộ hàm và API gọn hơn, phù hợp cho học tập, nghiên cứu, tra cứu nhanh, làm quen với lập trình và AI. | Bộ hàm và API chuyên sâu hơn, phù hợp cho người dùng chuyên nghiệp và quy trình phân tích tự động chạy trên hạ tầng của bạn. |
Người tài trợ nhận quyền sử dụng phần mềm mở rộng có thời hạn, hạn mức cao hơn và mức ưu tiên hỗ trợ cao hơn. Vnstock không bán dữ liệu. Hạn mức là đơn vị kỹ thuật để giữ tải ở mức hợp lý với nguồn, không phải dữ liệu bán theo đơn vị.
So sánh tính năng chi tiết
1. Dữ liệu giá cổ phiếu
| Chức năng | vnstock (Bản Cộng đồng) | vnstock_data (Bản Mở rộng) |
|---|---|---|
| Lịch sử giá OHLCV | Tối đa 8 năm (khung ngày) và 1 năm (khung phút) | Truy cập toàn bộ dữ liệu từ khi cổ phiếu niêm yết |
| Giá khớp lệnh trong ngày | Tối đa 30.000 bản ghi giao dịch | Toàn bộ bản ghi nguồn trả về cho phiên |
| Tải dữ liệu trong phiên | Sử dụng REST API - độ trễ thực tế ~1-5s trong phiên, theo nguồn | Sử dụng WebSocket nhận dữ liệu trong phiên theo độ trễ của nguồn, kết hợp thư viện vnstock_pipeline khi sử dụng gói tài trợ Golden trở lên. Mặc định sẽ dùng REST API như bản Cộng đồng. |
2. Dữ liệu tài chính & Doanh nghiệp
| Chức năng | vnstock (Bản Cộng đồng) | vnstock_data (Bản Mở rộng) |
|---|---|---|
| Chỉ số tài chính & BCTC | Tối đa 8 kỳ (xác thực API key) hoặc 4 kỳ (chế độ khách) | Toàn bộ số kỳ lịch sử nguồn trả về. |
| Thuyết minh báo cáo tài chính | Không hỗ trợ | Hỗ trợ trích xuất chi tiết thuyết minh BCTC |
| Tải báo cáo tài chính PDF | Không hỗ trợ tải file PDF scan | Hỗ trợ tải toàn bộ các loại báo cáo chính thức của doanh nghiệp. Tiện lợi khi ứng dụng tải về trích xuất dữ liệu bằng nhận dạng hình ảnh thông qua AI Agent, đặc biệt hữu ích cho phần diễn giải thuyết minh BCTC. |
| Chỉ tiêu sức khỏe tài chính | Không hỗ trợ | Đầy đủ bộ tiêu chí chuẩn hoá để đánh giá nhanh sức khỏe tài chính của doanh nghiệp |
3. Dữ liệu vĩ mô & Hàng hóa
| Chức năng | vnstock (Bản Cộng đồng) | vnstock_data (Bản Mở rộng) |
|---|---|---|
| Chỉ số kinh tế vĩ mô | Không hỗ trợ | Thông số GDP, CPI, FDI, xuất nhập khẩu... |
| Tỷ giá & Lãi suất liên ngân hàng | Không hỗ trợ | Cập nhật theo lịch công bố của nguồn |
| Giá hàng hóa thế giới & VN | Không hỗ trợ | Giá thép, dầu thô, nông sản, kim loại quý... |
Giải đáp thắc mắc thường gặp
1. Đã tài trợ nhưng thư viện vẫn báo bản Cộng đồng
Đây là bối rối phổ biến nhất của người tài trợ sau khi tham gia gói tài trợ. Mặc dù tài khoản của bạn đã được kích hoạt thành công trên hệ thống, bạn vẫn thấy thông báo sử dụng bản Community, và thư viện vẫn giữ nhịp gọi của bản Cộng đồng (thông báo của thư viện ghi "60 lượt gọi/phút").
Nguyên nhân cốt lõi
Bạn đang chạy code dựa trên thư viện vnstock bản Cộng đồng và thực hiện xác thực bằng hàm register_user().
Thư viện vnstock bản Cộng đồng không thể tự chuyển đổi sang tính năng của bản Mở rộng. Bản Mở rộng là một bộ thư viện độc lập cần cài đặt riêng nhưng hỗ trợ chuyển đổi code dễ dàng.
Cách xử lý
-
Cài đặt thư viện bản Mở rộng: Bộ thư viện dành cho người tài trợ là các thư viện riêng (như
vnstock_data,vnstock_ta,vnstock_pipeline), không thể cài đặt qua lệnhpip install vnstock_datathông thường. Bạn bắt buộc phải cài đặt thông qua trình cài đặt riêng tại trang Cài đặt bản Mở rộng. -
Thay đổi câu lệnh Import trong code: Sau khi cài đặt thành công, hãy cập nhật lại toàn bộ mã nguồn của bạn để import từ thư viện mới:
- Cách cũ (Bản Cộng đồng):
Python
from vnstock import Quote, Listing - Cách mới (Bản Mở rộng):
Python
from vnstock_data import Market, Reference
- Cách cũ (Bản Cộng đồng):
Khi bạn import từ vnstock_data, thư viện sẽ tự động nhận diện API Key và áp dụng đúng cấp tài trợ của bạn: thêm nhóm hàm, nhịp gọi rộng hơn và hạn mức chung của cấp đó. Phần trăm hạn mức còn lại của giờ, ngày, tháng xem ở trang tài khoản.
2. Chuyển đổi mã nguồn từ Bản Cộng đồng sang Bản Mở rộng
Hầu hết các chức năng trên bản Mở rộng được thiết kế tương thích ngược với bản Cộng đồng giúp bạn dễ dàng chuyển đổi chỉ bằng cách đổi tên thư viện khi nạp lệnh.
Lưu ý về cấu trúc dữ liệu tài chính (nguồn VCI) Riêng đối với dữ liệu tài chính lấy từ nguồn VCI, cấu trúc bảng dữ liệu trả về giữa bản Cộng đồng và bản Mở rộng sẽ có sự khác biệt nhỏ về tên cột hoặc định dạng. Bạn cần lưu ý điều chỉnh lại các đoạn code xử lý bảng dữ liệu (DataFrame) sau khi chuyển đổi sang bản Mở rộng đối với nguồn này. Vnstock cung cấp sẵn Agent Skill hỗ trợ chuyển đổi code tự động tại Agent Guide.