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 từ nguồn bên thứ ba 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 nguồn có điểm truy cập hoặc nội dung công khai; điều kiện tự động hóa và sử dụng dữ liệu phụ thuộc vào từng nguồn.
Giao diện truy vấn
Các công ty chứng khoán (Vietcap, KB Securities, v.v.)
Trang mạng
Bảng biểu, nội dung chi tiết tin tức
Sitemap/RSS Feed
Báo chí tài chính (CafeF, VietStock)
Kết nối trong phiên
Dữ liệu được trao đổi liên tục qua WebSocket
Vnstock về bản chất là một công cụ đọc và chuẩn hoá dữ liệu — phần mềm chạy trên máy của bạn, gửi truy vấn thẳng tới các nguồn bên thứ ba mà bạn có quyền truy cập và chuẩn hoá kết quả ngay tại đó.
Dữ liệu thường được truy xuất từ điểm truy cập hoặc nội dung công khai của các công ty chứng khoán và nguồn thông tin khác. Vnstock không đại diện cho các nguồn này và không cấp phép thay cho họ.
Theo thiết kế hiện tại, yêu cầu đi trực tiếp từ hạ tầng người dùng tới nguồn; Vnstock không làm máy chủ trung chuyển, không cung cấp thông tin đăng nhập của nguồn và không cam kết vượt giới hạn truy cập. Dữ liệu cần được kiểm chứng với nguồn phù hợp.
Tầng kết nối
Tự động hóa quá trình truy cập và đọc dữ liệu từ các giao diện truy vấn công khai mà không yêu cầu đăng nhập hay phiên làm việc riêng.
Gửi yêu cầu
Gửi yêu cầu theo giao thức mạng để lấy dữ liệu
Đọc trang mạng
Tách nội dung từ trang và tập tin dữ liệu
Đọc dữ liệu cấu trúc
Đọc và giải mã dữ liệu có cấu trúc
Kết nối liên tục
Nhận dữ liệu trong phiên, cập nhật theo độ trễ của nguồn
Bộ phận truy xuất là phần mềm chạy trên máy của bạn, làm việc ở mức giao thức: gửi yêu cầu tới điểm truy cập của nguồn và nhận dữ liệu dạng văn bản, trang mạng hoặc mã nhị phân. Việc điểm truy cập không yêu cầu đăng nhập không tự tạo ra giấy phép sử dụng dữ liệu.
Nguồn có thể áp dụng mã kiểm tra người dùng, tường lửa, giới hạn số lần truy cập hoặc biện pháp khác. Vnstock không thiết kế để vượt các biện pháp đó.
Tầng chuẩn hoá
Đả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 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ụ
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 phân hệ thực hiện một nhóm xử lý riêng: tính toán chỉ số, kết hợp nhiều nguồn, lọc và chuyển đổi dữ liệu theo yêu cầu phân tích.
Ví dụ: phân hệ phân tích nền tảng lấy Bảng cân đối kế toán, Kết quả kinh doanh và Lưu chuyển tiền tệ từ các nguồn phù hợp — rồi chuẩn hóa thành một bảng dữ liệu 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 thích ứng
Đó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
Bộ phận kết nối 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 chương trình phức tạp.
Khi một nguồn không phản hồi hoặc máy chủ gặp sự cố, người dùng có thể chuyển sang nguồn dự phòng thông qua bộ phận kết nối tương ứng.
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
Hệ thống cú pháp lệnh thông qua "Unified UI" được thiết kế tối giản lấy cảm hứng từ 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
Dữ liệu sau khi hoàn thiện, sẵn sàng kết nối với các hệ sinh thái phân tích chuyên nghiệp và các dự án kết hợp AI Agent.
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 Agent
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 bạn truy xuất qua 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
Yêu cầu được tạo từ hạ tầng người dùng tới nguồn công khai; Vnstock không làm máy chủ trung chuyển hoặc lưu trữ bản sao trung gian để phân phối. Quyền sử dụng dữ liệu phụ thuộc vào từng nguồn.
Tách bạch lớp xử lý
Kiến trúc phân 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, kết quả đầu ra được chuẩn hóa thành bảng có cấu trúc, tên trường, định dạng và đơn vị thống nhất — sẵn sàng để phân tích.
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.