Nguyên Lý Hoạt Động Của Vnstock
Vnstock là một thư viện Python về bản chất là công cụ đọc dữ liệu công khai và xử lý, chuẩn hoá định dạng dữ liệu thành tiêu chuẩn chung giúp các AI Agent và người dùng dễ dàng sử dụng để phân tích đầu tư.
Nhấn vào từng tầng để xem chi tiết cơ chế hoạt động
Nguồn dữ liệu (Đầu vào)
Các nền tảng cho phép truy cập dữ liệu tài chính công khai phục vụ phân tích và đầu tư chứng khoán.
REST API Công khai
Các công ty chứng khoán (Vietcap, KB Securities, vv)
Trang HTML
Bảng biểu, nội dung chi tiết tin tức
Sitemap/RSS
Báo chí tài chính (CafeF, VietStock)
WebSocket
Dữ liệu thời gian thực
Vnstock về bản chất là một công cụ đọc và chuẩn hoá dữ liệu — hoạt động tương tự như trình duyệt web, kết nối người dùng tới các nguồn dữ liệu công khai mà họ có quyền truy cập.
Dữ liệu chính được truy xuất từ hạ tầng chia sẻ của các công ty chứng khoán (Vietcap, KB Securities, Mirae Assets, v.v.) — những đơn vị cung cấp dữ liệu phục vụ phân tích và đầu tư cho đại chúng.
Toàn bộ quá trình diễn ra qua giao thức HTTP tiêu chuẩn, không yêu cầu xác thực định danh. Dữ liệu thu được có chất lượng cao và có thể kiểm chứng với nhiều nguồn tham chiếu khác nhau.
Tầng Kết Nối (Fetcher Layer)
Tự động hóa quá trình truy cập và trích xuất dữ liệu từ các nguồn tài chính công khai mà không yêu cầu đăng nhập hay phiên làm việc riêng.
requests
Gửi yêu cầu HTTP lấy dữ liệu
BeautifulSoup
Bóc tách cấu trúc HTML/XML
json
Đọc và giải mã dữ liệu JSON từ API
websocket-client
Subscribe dữ liệu được trao đổi theo thời gian thực
Fetcher hoạt động giống như một trình duyệt tự động: gửi HTTP request đến URL công khai và nhận dữ liệu trả về dưới dạng JSON, HTML hoặc mã nhị phân.
Người truy cập không trải qua bước xác thực định danh (authentication) — đây là đặc điểm quan trọng giúp dữ liệu từ Vnstock luôn minh bạch về nguồn gốc và tham chiếu.
Tầng Chuẩn hoá (Standardizer Layer)
Đảm nhận việc làm sạch, ép kiểu và đồng bộ hệ quy chiếu, biến đổi dữ liệu thô phi cấu trúc thành định dạng bảng tiêu chuẩn.
Bóc tách & Giải mã
Giải mã ý nghĩa từ dữ liệu thô
Ép kiểu dữ liệu
Định dạng Số, Chuỗi, Thời gian
Đồng bộ Đơn vị
Chuyển đổi Tỷ, Nghìn, % về quy chuẩn
Chuẩn hoá tên gọi
Đồng nhất tiêu chuẩn tên gọi
Chuẩn hoá bảng
Tổ chức thành bảng dữ liệu
Mỗi nguồn dữ liệu trả về cấu trúc khác nhau (tên cột, đơn vị, kiểu dữ liệu). Standardizer đồng bộ tất cả về một chuẩn duy nhất.
Ví dụ: Nguồn VCI trả về dữ liệu giá đóng cửa có tên "c" tron chuỗi json kiểu số nguyên với đơn vị đồng, Standardizer chuyển thành cột "close" kiểu số thực, đơn vị ngìn đồng.
Output cuối cùng luôn là pandas DataFrame với cấu trúc cố định — giúp code phân tích hoạt động nhất quán bất kể nguồn dữ liệu.
Tầng Nghiệp vụ (Implementation Layer)
Triển khai kiến trúc dữ liệu toàn diện: chọn lọc, kết hợp & tính toán các bộ dữ liệu chuyên sâu cho từng nhóm phân tích.
Nhóm Tham chiếu
Dữ liệu mã, ngành, sàn giao dịch, công ty
Nhóm Thị trường
Chỉ số, Giá & Khối lượng, cung cầu, độ rộng, khối ngoại, vv
Nhóm Tài chính
Báo cáo tài chính, chỉ số tài chính
Nhóm Vĩ mô
Dữ liệu kinh tế vĩ mô, lãi suất, tỷ giá, hàng hoá, vv
Nhóm Insights
Tìm kiếm cơ hội, đánh giá và xếp hạng
Mỗi module thực thi logic nghiệp vụ riêng biệt: tính toán chỉ số, kết hợp nhiều API, lọc và chuyển đổi dữ liệu theo yêu cầu phân tích.
Ví dụ: Module Fundamental gọi nhiều API khác nhau để lấy Bảng cân đối kế toán, Kết quả kinh doanh, Lưu chuyển tiền tệ — rồi chuẩn hoá thành một DataFrame thống nhất.
Screener cho phép thiết lập điều kiện lọc đa tiêu chí (P/E, ROE, tăng trưởng doanh thu...) và trả về danh sách mã phù hợp.
Tầng Kết nối (Adapter Layer)
Đóng vai trò trung gian bền vững: dịch yêu cầu thao tác của người dùng tới đúng nguồn dữ liệu và xử lý lỗi kết nối tự động.
Điều hướng Nguồn
Phân bổ lệnh gọi (VCI / KBS / TCBS...)
Khớp Tham số
Cấu hình lệnh tiêu chuẩn tương thích hệ thống
Xử lý Lỗi & Thử lại
Tự động khôi phục kết nối khi gặp gián đoạn
Adapter giúp người dùng chỉ cần thay đổi tham số `source` để chuyển đổi giữa các nguồn dữ liệu mà không cần viết code phức tạp.
Khi một nguồn gặp lỗi (timeout, server down), người dùng chọn chuyển đổi tới nguồn dự phòng thông qua Adapter.
Tầng này không chứa logic nghiệp vụ — chỉ đảm bảo khớp chính xác giữa giao diện người dùng và lõi hệ thống.
Tầng Giao diện (Unified UI)
Hệ thống cú pháp được thiết kế tối giản theo chuẩn mực quốc tế, hỗ trợ quá trình phân tích dữ liệu hiệu quả.
Market()
Giá, khối lượng, giao dịch nội bộ & khối ngoại
Fundamental()
Báo cáo tài chính & chỉ số định giá doanh nghiệp
Macro()
Dữ liệu kinh tế vĩ mô, lãi suất, tỷ giá
Reference()
Thông tin tham chiếu: mã CK, ngành, sàn, công ty
Insights()
Bộ lọc cổ phiếu, đánh giá & xếp hạng
Analytics()
Phân tích kỹ thuật & mô hình thống kê
Đây là tầng duy nhất người dùng tương tác trực tiếp. Cú pháp được thiết kế thống nhất giữa các nhóm chức năng, giúp giảm thời gian làm quen.
Tham số đầu vào tuân theo chuẩn quốc tế (ISO date format, snake_case naming) để đảm bảo khả năng tương thích với các công cụ phân tích phổ biến.
Mỗi class cung cấp các method riêng biệt (history, financial_report, intraday...) với hỗ trợ auto-complete và tài liệu tham chiếu tích hợp.
Đầu ra hệ thống (Outputs)
Dữ liệu sau khi hoàn thiện được ứng dụng trực tiếp vào hệ sinh thái phân tích chuyên nghiệp.
Bảng dữ liệu Pandas
Trực quan hóa, phân tích mô hình & kiểm thử chiến lược
Lưu trữ & Trích xuất
Tương thích CSDL (PostgreSQL, DuckDB) và file (CSV, Parquet)
Nền tảng cho AI (Agents)
Tạo môi trường lập trình hiệu quả với AI Agent
Dữ liệu đầu ra mặc định là pandas DataFrame — chuẩn chung cho xử lý dữ liệu trong Python, tương thích đa nền tảng công cụ.
Dữ liệu có thể được lưu trữ trực tiếp vào các CSDL hiệu năng cao (DuckDB, PostgreSQL) hoặc xuất ra file Parquet/CSV để chia sẻ.
Với chuẩn đầu ra nhất quán, tài liệu đầy đủ, Agent Skill hiện đại, dữ liệu từ Vnstock tích hợp liền mạch vào các AI Agent tự động.
Nguyên tắc thiết kế cốt lõi
Ba nguyên tắc nền tảng định hình toàn bộ kiến trúc Vnstock.
Minh bạch nguồn gốc
Mọi dữ liệu đều truy xuất từ nguồn công khai qua giao thức web, không lưu trữ bản sao trung gian để phân phối. Người dùng luôn kết nối tới trang web mục tiêu thông qua công cụ Vnstock.
Tách bạch lớp xử lý
Kiến trúc 5 tầng tách biệt rõ ràng giữa thu thập, chuẩn hoá, nghiệp vụ, kết nối và giao diện. Thay đổi một tầng không làm ảnh hưởng đến các tầng còn lại.
Đầu ra chuẩn hoá
Bất kể nguồn dữ liệu nào, đầu ra luôn là pandas DataFrame với cấu trúc cố định, đặt tên, định dạng và đơn vị thống nhất — sẵn sàng để phân tích ngay.
Sẵn sàng sử dụng Vnstock?
Khám phá tài liệu hướng dẫn chi tiết hoặc tìm hiểu thêm về kiến trúc thư viện để tùy chỉnh theo nhu cầu.