Hướng dẫn Nâng Cấp Phiên Bản v3.2.9

Phiên bản v3.2.9 khắc phục các sai lệch của dữ liệu khớp lệnh trong phiên, nên số liệu bạn nhận được sẽ khác bản cũ.

Nếu code của bạn không dùng trades() hoặc intraday() và bạn đang sử dụng bản 3.2.8, hãy nâng cấp thẳng lên v3.2.9, không cần chỉnh gì.

1. Cột time của trades() cổ phiếu nay có múi giờ

Nguồn mặc định cho dữ liệu khớp lệnh cổ phiếu chuyển từ KBS sang VND, kéo theo cột time đổi kiểu từ datetime64[ns] sang datetime64[ns, Asia/Ho_Chi_Minh]. So sánh với mốc thời gian không múi giờ sẽ báo lỗi:

df = Market().equity('ACB').trades()
df[df['time'] > pd.Timestamp('2026-09-04 09:30')]
# TypeError: Invalid comparison between dtype=datetime64[ns, Asia/Ho_Chi_Minh] and Timestamp

Chọn một trong hai cách:

# Gắn múi giờ cho mốc so sánh
df[df['time'] > pd.Timestamp('2026-09-04 09:30', tz='Asia/Ho_Chi_Minh')]

# Hoặc bỏ múi giờ khỏi cột để giữ nguyên code phía sau
df['time'] = df['time'].dt.tz_localize(None)

Muốn giữ nguyên nguồn KBS như cũ, đặt một lần lúc khởi động chương trình:

from vnstock_data.ui.config import set_route
set_route('market.equity.trades', 'kbs', 'quote', 'Quote', 'intraday')

Nhóm phái sinh vẫn dùng KBS, không đổi.

2. Khối lượng và nhãn match_type thay đổi

• Khối lượng khớp lệnh giảm về đúng thực tế. Trước đây nguồn KBS trả cả hai chiều mua/bán nên tổng khối lượng bị gấp đôi, ảnh hưởng nặng nhất tới hợp đồng tương lai. Nếu có báo cáo hay kết quả backtest xây trên số cũ, hãy chạy lại.
• Nhãn ATO/ATC chính xác hơn. Phiên ATO của hợp đồng tương lai được nhận diện đúng khung 08:45–09:00, đồng thời các lệnh không rõ chiều không còn bị gán nhầm thành ATO/ATC. Nếu code lọc theo match_type để tính khối lượng phiên định kỳ, con số sẽ thay đổi.
• Xuất hiện nhãn PLO với các mã sàn HNX. Nếu code giả định match_type chỉ có Buy/Sell, hãy bổ sung nhánh xử lý.

3. Số bản ghi mặc định cho phái sinh: 1.000 → 100.000

Một phiên của VN30F1M có gần 100.000 lệnh khớp, giới hạn cũ chỉ đủ phủ cụm ATC cuối phiên. Mặc định mới lấy trọn phiên, đổi lại lời gọi mất vài giây:

Market().futures('VN30F1M').trades()             # trọn phiên
Market().futures('VN30F1M').trades(limit=1000)   # nhanh, chỉ dữ liệu gần nhất

Cổ phiếu giữ mặc định 1.000 bản ghi như cũ.

Khi dữ liệu trả về chưa phủ hết phiên, thư viện sẽ cảnh báo kèm mức giới hạn nên tăng lên. Nếu chạy tác vụ tự động và không cần cảnh báo này:

import warnings
warnings.filterwarnings('ignore', message='.*chưa phủ hết phiên.*')

4. Nên chuyển khỏi nguồn VCI cho dữ liệu khớp lệnh

Nguồn API đã áp giới hạn 100 bản ghi mỗi lượt gọi cho dữ liệu khớp lệnh của VCI. Lấy trọn một phiên vì thế cần hàng trăm lượt gọi và thường bị ngắt kết nối giữa chừng, đặc biệt với mã thanh khoản lớn và hợp đồng tương lai.

from vnstock_data import Quote

df = Quote(source='VCI', symbol='VN30F1M').intraday()   # không còn phù hợp

df = Quote(source='KBS', symbol='VN30F1M').intraday()   # có nhãn Mua/Bán chủ động
df = Quote(source='MAS', symbol='VN30F1M').intraday()
df = Quote(source='VND', symbol='VN30F1M').intraday()

Nếu dùng Unified UI thì không cần làm gì, trades() vốn không định tuyến qua VCI. VCI vẫn dùng tốt cho các nhóm dữ liệu khác.

Không cần chỉnh code

Mã phái sinh kiểu cũ như VN30F1M nay tự động chuyển sang mã KRX ở mọi lớp truy xuất nên không còn trả về kết quả rỗng; bổ sung Market().future(...) bên cạnh Market().futures(...); sửa lỗi giá và mốc thời gian sai ở nguồn MAS; cây API show_api() hiển thị đầy đủ trở lại.