Vnstock Logo

Kết nối dữ liệu trong phiên qua WebSocket

Mở rộng

Mục lục

Tài liệu bản cũ: vnstock_pipeline v2.3.2

Bản mặc định hiện là vnstock_pipeline v3.1.1, 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_pipeline v2.3.2: 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 v3.1.1.

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.

Tài liệu bản cũ (2.x)

Trang này mô tả tính năng của Vnstock Pipeline 2.x. Từ thế hệ 5, các mô-đun nhận dữ liệu trong phiên đóng gói sẵn cho nguồn bên thứ ba đã được gỡ; gọi các lớp cũ sẽ nhận mã lỗi PIPELINE_FEATURE_REMOVED. Nếu cần nhận dữ liệu trong phiên từ nguồn bạn có quyền dùng, xem Khung streaming dữ liệu.

Giới thiệu

Vnstock Pipeline 2.x có công cụ giúp bạn kết nối tới luồng dữ liệu thị trường chứng khoán trong phiên của nguồn thông qua giao thức WebSocket. Dữ liệu cập nhật theo độ trễ của nguồn; độ trễ, tính liên tục và quyền sử dụng phụ thuộc vào nguồn. Tính năng này phục vụ nhu cầu theo dõi và phân tích dữ liệu thị trường trong phiên trên máy tính của bạn.

Tính năng chính

  • Dữ liệu theo từng lệnh khớp: Nhận dữ liệu trong phiên ở mức từng lệnh khớp (tick-by-tick) qua WebSocket, theo độ trễ của nguồn.
  • Quản lý phiên thông minh: Duy trì kết nối, ngắt kết nối vào giờ nghỉ trưa và phục hồi khi đứt kết nối.
  • Cấu trúc dữ liệu chuẩn hóa: Hệ thống trả về cấu trúc dữ liệu nhất quán, lấy cảm hứng từ chuẩn FIX/Bloomberg (kích hoạt bằng tham số naming="standard").
Lưu ý thay đổi kiến trúc

Kể từ bản v2.3.1, thiết kế hệ thống tập trung vào việc ghi dữ liệu nhận được ra tệp Parquet/CSV tại vị trí lưu cục bộ do bạn cấu hình. Việc xử lý chuyên sâu như đẩy vào cơ sở dữ liệu DuckDB hay Firebase sẽ được chuyển giao cho người dùng để đảm bảo tính tinh gọn, tránh cài đặt thừa thư viện.

1. Chuẩn Hóa Cấu Trúc Dữ Liệu (Standard Schemas)

Hệ thống cho phép bạn chuyển tên trường của dữ liệu gốc (dùng nhiều từ viết tắt) sang cách đặt tên thống nhất bằng cách truyền cờ naming="standard" khi thiết lập.

Nguyên tắc chuẩn hóa (Standard Naming)

  1. Sử dụng snake_case: Ví dụ total_volume thay vì TotalVol.
  2. Loại bỏ viết tắt: Ngoại trừ các thuật ngữ toàn cầu như ETF, CW.
  3. Phân loại rõ ràng bằng hậu tố: _price (giá), _volume (khối lượng), _value (giá trị).
  4. Đồng bộ với Vnstock Data: Thời gian luôn là time, mã chứng khoán luôn là symbol.
  5. Phân giải sổ lệnh: Sổ lệnh (Board) được tách thành bên mua (bid) và bên bán (ask) thay vì gộp chung.

Mẫu cấu trúc dữ liệu trả về

Ví dụ 1: Giá Cổ Phiếu Khớp Lệnh (stock) Dữ liệu trả về cho mỗi lần có giao dịch khớp lệnh:

  • time: 2026-03-20 09:10:14 (Thời điểm khớp)
  • symbol: PVS (Mã chứng khoán)
  • price: 42.3 (Giá khớp cuối)
  • volume: 10 (Khối lượng khớp)
  • total_volume: 4280 (Tổng khối lượng tích lũy)
  • side: B (Bên Mua chủ động) hoặc S (Bên Bán chủ động)

Ví dụ 2: Sổ Lệnh / Bảng Giá (board) Dữ liệu cập nhật các bước giá đang chờ mua/bán:

  • bid_price_1, bid_price_2, bid_price_3: 3 bước giá chờ mua tốt nhất.
  • bid_vol_1, bid_vol_2, bid_vol_3: Khối lượng chờ mua tương ứng.
  • ask_price_1, ask_price_2, ask_price_3: 3 bước giá chờ bán tốt nhất.
  • ask_vol_1, ask_vol_2, ask_vol_3: Khối lượng chờ bán tương ứng.

2. Kinh Nghiệm Vận Hành

  1. Kiểm soát bộ nhớ RAM: Khi tính toán các chỉ báo kỹ thuật liên tục, hãy sử dụng cấu trúc bộ nhớ có giới hạn vòng (như collections.deque trong Python). Không dùng mảng danh sách (list) thông thường để tránh tràn bộ nhớ khi cắm máy chạy cả ngày.
  2. Lập trình phi đồng bộ (Async): Mọi tác vụ mất thời gian (ví dụ: ghi dữ liệu ra ổ cứng, gửi tin nhắn cảnh báo qua mạng) đều phải bọc trong các tiến trình chạy ngầm (asyncio.create_task()). Việc chặn luồng chính quá lâu sẽ khiến hệ thống không kịp nhận dữ liệu mới và bị ngắt kết nối.
  3. Số lượng mã tối ưu: Mỗi tiến trình chỉ nên đăng ký theo dõi từ 10 đến 20 mã cổ phiếu quan trọng nhất để giảm nguy cơ bỏ sót cập nhật.