Quy ước dữ liệu đầu vào và xử lý lỗi
Mục lục
Trang này tổng hợp những quy tắc áp dụng chung cho toàn bộ các mô-đun của vnstock_quant: cấu trúc dữ liệu đầu vào mà các hàm yêu cầu, cách thư viện báo lỗi và cảnh báo, cùng các quy ước phương pháp luận mà kết quả tính toán tuân theo. Trang tài liệu của từng nhóm hàm sẽ chỉ đi sâu vào những điểm đặc thù của riêng nhóm đó.
Năm nguyên tắc cốt lõi khi gọi hàm (dành cho người dùng và AI Agent)
Trước khi gọi bất kỳ hàm tính toán nào, hãy kiểm tra đủ năm yếu tố sau:
- Không gian tên và tên hàm: Tra cứu chính xác qua
catalog()hoặc trang tài liệu của mô-đun; không tự đoán tên hàm. - Cấu trúc bảng và các cột bắt buộc: Giữ đúng tên cột viết thường, chỉ mục thời gian (
DatetimeIndex) và đảm bảo các cột có cùng độ dài. - Đơn vị tính: Mọi tỷ lệ phần trăm đều biểu diễn dưới dạng phân số thập phân; đơn vị giá phải đồng nhất trong suốt một phép tính.
- Quyền sử dụng tính năng: Kiểm tra trực tiếp từ
vq.entitlement()["features"]; không suy diễn từ ví dụ minh hoạ hoặc tên gói trong tài liệu. - Cách kiểm tra kết quả và bắt lỗi: Đọc thêm thông tin trong
attrs, cộtreason, danh sáchwarningsvà bắt ngoại lệ theo thuộc tínhcodethay vì so khớp chuỗi văn bản thông báo.
Khi lập trình cho AI Agent tự động gọi hàm, hãy ưu tiên sử dụng schema(name) và call(name, **args) ở những mô-đun có hỗ trợ giao diện JSON. Tuyệt đối không tự điền số 0 vào dữ liệu khuyết thiếu, không tự chọn nguồn dữ liệu thay người dùng và không tìm cách đổi giao diện gọi hàm để lách giới hạn cấp quyền.
Cấu trúc dữ liệu đầu vào theo từng nhóm hàm
Thư viện nhận dữ liệu đầu vào dưới dạng pandas.DataFrame hoặc pandas.Series và trả về kết quả được căn chỉnh khớp với chỉ mục thời gian bạn truyền vào. Lớp giao tiếp Python chỉ làm nhiệm vụ chuyển đổi các cột sang mảng số rồi đóng gói lại kết quả có gắn nhãn; toàn bộ quá trình kiểm tra tính hợp lệ và tính toán đều diễn ra trong lõi Rust. Nếu bảng thiếu cột bắt buộc hoặc các cột lệch độ dài, thư viện sẽ báo lỗi InputDataError kèm tên cột bị thiếu.
| Nhóm hàm | Cấu trúc dữ liệu đầu vào | Lưu ý quan trọng |
|---|---|---|
ta, backtest, micro.cvd, micro.realized | Bảng nến OHLCV: các cột open, high, low, close, volume viết thường, có chỉ mục thời gian DatetimeIndex hoặc cột time | Mô-đun ta chỉ yêu cầu những cột mà chỉ báo đó thực sự dùng; backtest có thêm tham số price_unit để tự nhận diện giá theo nghìn đồng hay đồng |
risk, portfolio | pandas.Series hoặc DataFrame chứa chuỗi lợi suất giản đơn theo kỳ, có chỉ mục DatetimeIndex | Nên tính từ chuỗi giá đóng cửa đã điều chỉnh bằng hàm risk.returns(prices); khi so sánh hai chuỗi, thư viện tự căn chỉnh theo các ngày giao dịch chung |
fa | Báo cáo tài chính dạng bảng dọc (long format): gồm các cột period, id, value (hồ sơ v5) hoặc report_period, item_id, item_value (hồ sơ v6), sử dụng mã chỉ tiêu của vnstock và gói trong đối tượng fa.Dataset | Các chỉ số dùng mẫu số bình quân cần tối thiểu hai kỳ báo cáo. Bảng giá phục vụ định giá cần cột time, close (tính bằng đồng; nếu truyền bảng hồ sơ v6 theo nghìn đồng thì thư viện tự quy đổi) và total_shares |
prices | Bảng giá gốc chưa điều chỉnh theo phiên (gồm giá tham chiếu, giá trần, giá sàn nếu có, cùng OHLC và khối lượng) kết hợp với bảng sự kiện quyền từ events() (event_type, ex_right_date, ratio) | Bảng có giá đóng cửa lẻ bước giá 10 đồng sẽ bị từ chối vì đó là dấu hiệu của bảng giá đã điều chỉnh; xem chi tiết tại trang Điều chỉnh giá theo sự kiện quyền |
micro.bars, micro.classify | Bảng dữ liệu khớp lệnh từng lệnh (tick): gồm time, price, volume và cột phân loại lệnh chủ động nếu nguồn có (match_type ở hồ sơ v5; side và session ở hồ sơ v6) | Lệnh khớp trong phiên định kỳ ATO, ATC không có bên chủ động; nếu bảng dữ liệu không có cột bên chủ động thì thư viện ước lượng bằng quy tắc bước giá (tick rule) |
Tương thích giữa hai hồ sơ cột v5 và v6 của vnstock 6
vnstock 6 có thể trả về bảng dữ liệu theo hồ sơ cột v5 (mặc định) hoặc hồ sơ v6 (đặt tên cột mới và biểu diễn giá theo đơn vị nghìn đồng ở nhiều bảng). Khi bạn gọi các hàm tải dữ liệu tích hợp sẵn trong vnstock_quant, thư viện luôn yêu cầu hồ sơ v5. Ngược lại, nếu bạn tự tải bảng dữ liệu ở ngoài rồi truyền vào hàm tính toán thì dùng hồ sơ nào cũng được: thư viện sẽ tự đọc siêu dữ liệu attrs["profile"] trên DataFrame để quy đổi đơn vị khi cần thiết.
Kết quả đầu ra luôn là DataFrame hoặc Series giữ nguyên chỉ mục với bảng đầu vào. Các thông tin bổ sung được đính kèm trong từ điển attrs (chẳng hạn bảng hệ số điều chỉnh của hàm prices.adjust nằm tại attrs["factors"]). Lưu ý rằng thư viện không tự động đổi đơn vị giá trừ khi hàm có tham số unit hoặc price_unit; bạn nên thống nhất một đơn vị giá xuyên suốt phiên làm việc.
Cây phân cấp ngoại lệ và bảng mã lỗi
Mọi ngoại lệ riêng của vnstock_quant đều kế thừa từ lớp cơ sở VnstockQuantError. Mỗi ngoại lệ đi kèm một mã lỗi (code) cố định giúp bạn dễ dàng phân nhánh xử lý giữa lỗi tham số, lỗi dữ liệu đầu vào, lỗi cấp quyền và các lỗi môi trường khác:
VnstockQuantError (Lớp cơ sở)
├── InvalidParameterError # Tham số sai tên, sai kiểu hoặc ngoài khoảng (mã: QUANT_INVALID_PARAMETER)
├── UnknownIndicatorError # Không có chỉ báo, tính năng hay hàm mang tên đó (mã: QUANT_UNKNOWN_INDICATOR,
│ # QUANT_UNKNOWN_FEATURE, QUANT_UNKNOWN_FUNCTION)
├── UnknownRatioError # Mã chỉ số tài chính không tồn tại (mã: QUANT_UNKNOWN_RATIO)
├── InputDataError # Dữ liệu đầu vào thiếu cột hoặc các cột lệch độ dài (mã: QUANT_INPUT_DATA)
│ └── CausalityViolationError # Tín hiệu hoặc chỉ báo trong backtest đọc dữ liệu tương lai (mã: QUANT_CAUSALITY_VIOLATION)
├── DependencyError # Thiếu vnstock, hoặc vnstock đang cài không thuộc thế hệ 6 (mã: QUANT_DEPENDENCY_MISSING)
├── EntitlementError # Cấp quyền hiện tại không mở tính năng này
│ ├── TierRequiredError # Cần gói quyền sử dụng cao hơn (mã: QUANT_TIER_REQUIRED, QUANT_SCOPE_LIMIT)
│ └── QuotaExceededError # Hết lượt dùng thử trong ngày, hoặc một lần chạy thử quá lớn cho cấp (mã: QUANT_TRIAL_EXHAUSTED, QUANT_QUOTA_LIMIT)
├── AuthError # Lỗi API key, thiết bị hoặc kết nối máy chủ cấp quyền
├── UnsupportedError # Bản phát hành đã bị tắt, cần nâng cấp (mã: VNSTOCK_RELEASE_DISABLED)
│ └── ReleaseExpiredError # Bản phát hành đã hết hạn hiệu lực (mã: VNSTOCK_RELEASE_EXPIRED)
└── InternalError # Lỗi ngoài dự kiến bên trong thư việnĐối với các lỗi phát sinh từ tầng vnstock 6 trong quá trình tải dữ liệu (như chưa chọn nguồn, nguồn không hỗ trợ loại dữ liệu đang gọi, thiếu khoá Open API hoặc bị nguồn từ chối), vnstock_quant giữ nguyên ngoại lệ gốc mà không bọc lại. Mã của các lỗi này luôn bắt đầu bằng tiền tố VNSTOCK_:
Mã lỗi (code) | Nguyên nhân | Cách khắc phục |
|---|---|---|
VNSTOCK_INPUT_SOURCE | Chưa chỉ định nguồn dữ liệu khi gọi hàm tải | Truyền tham số source= hoặc cấu hình trước bằng vnstock.sources.use(...) |
VNSTOCK_ROUTE_UNSUPPORTED | Nguồn dữ liệu đã chọn không hỗ trợ loại dữ liệu này | Kiểm tra danh sách nguồn hỗ trợ bằng vnstock.sources.readers(route) |
VNSTOCK_CREDENTIAL_MISSING | Chưa lưu khoá Open API cho nguồn dữ liệu đã chọn | Chạy lệnh vnstock keys set <nguồn> trong terminal |
VNSTOCK_SOURCE_AUTH, VNSTOCK_SOURCE_LOGIN, VNSTOCK_SOURCE_OTP | Nguồn từ chối khoá xác thực hoặc yêu cầu mở phiên đăng nhập / OTP | Kiểm tra lại khoá bằng vnstock keys check <nguồn>; nếu nguồn yêu cầu OTP thì chạy vnstock auth <nguồn> |
VNSTOCK_SOURCE_RATE_LIMITED | Nguồn tạm thời từ chối do gửi quá nhiều truy vấn liên tiếp | Đợi vài phút rồi thử lại, đồng thời giảm số lượng mã trong mỗi lần tải |
Riêng trong hàm fa.Dataset.load(), nếu gặp một trong sáu mã lỗi cấu hình nguồn ở trên khi đang tải phần giá đóng cửa hoặc thuyết minh BCTC, thư viện sẽ không dừng toàn bộ quá trình mà chỉ phát một cảnh báo, đồng thời đánh dấu các chỉ số liên quan là MISSING_MARKET hoặc MISSING_INPUT. Ngược lại, các lỗi kết nối mạng hoặc lỗi chạm ngưỡng tần suất (VNSTOCK_SOURCE_RATE_LIMITED) vẫn được ném ra ngay lập tức.
Mọi đối tượng ngoại lệ đều cung cấp đầy đủ các thuộc tính: code (mã định danh lỗi), kind (nhóm phân loại lỗi), message (thông báo bằng tiếng Việt), retryable (cờ cho biết có nên tự động thử lại hay không) và action (hướng dẫn cách xử lý tiếp theo, có thể là None). Khi chuyển sang chuỗi bằng str(e), thông báo có định dạng chuẩn [code] message (action).
Ví dụ cách bắt và xử lý ngoại lệ trong mã Python
import vnstock_quant as vq
try:
# Ví dụ gọi hàm tính toán cần quyền hạn
result = vq.portfolio.twr(values, flows)
except vq.TierRequiredError as e:
print(f"Lỗi quyền hạn: {e.message}")
print(f"Việc nên làm: {e.action}")
except vq.QuotaExceededError as e:
print(f"Đã hết lượt dùng thử hôm nay [{e.code}]. Lượt sẽ được làm mới lúc 00:00 giờ Việt Nam.")
except vq.AuthError as e:
print(f"Không kiểm tra được quyền sử dụng: {e}")
except vq.InvalidParameterError as e:
print(f"Tham số không hợp lệ: {e}")
except vq.VnstockQuantError as e:
print(f"Lỗi chung của vnstock_quant: {e}")Các cảnh báo hệ thống và cách lọc cảnh báo
Những lưu ý quan trọng nhưng không làm dừng chương trình được phát qua lớp cảnh báo VnstockQuantWarning. Trong bản 1.0, khi một phép tính thiếu dữ liệu đầu vào tin cậy từ nguồn, thư viện chọn cách tắt phép tính đó hoặc phát cảnh báo nêu rõ điều kiện áp dụng, thay vì âm thầm trả về một con số dễ gây hiểu nhầm:
| Nội dung cảnh báo | Khi nào xuất hiện | Cách xử lý để có kết quả chuẩn xác |
|---|---|---|
Bảng dữ liệu thử nghiệm của vnstock 6 | Xuất hiện một lần mỗi tiến trình khi tải BCTC hoặc lịch sự kiện từ Open API | Đối chiếu lại với báo cáo tài chính gốc hoặc văn bản công bố của sở giao dịch trước khi dùng cho quyết định quan trọng |
| Nguồn không trả về dòng dữ liệu nào | Khi hàm tải chuỗi lịch sử dài không nhận được bất kỳ dòng nào trong toàn bộ khoảng ngày yêu cầu | Kiểm tra lại mã chứng khoán và khoảng thời gian truy vấn (các cửa sổ 3 năm trống trước ngày cổ phiếu niêm yết sẽ không phát cảnh báo này) |
| Tắt chỉ số định giá do thiếu số cổ phiếu | Khi tính fa mà bảng dữ liệu không có cột total_shares | Truyền cột total_shares qua Dataset.from_frames, hoặc bật estimate_shares=True để ước tính tham khảo |
| Tắt chỉ số định giá do giá đã điều chỉnh | Khi giá đóng cửa lẻ bước giá 10 đồng, hoặc bảng giá từ vnstock được đánh dấu là giá đã điều chỉnh | Cung cấp bảng giá đóng cửa gốc (chưa điều chỉnh) thông qua Dataset.from_frames |
| Số cổ phiếu lưu hành chỉ là ước tính | Khi bạn bật tuỳ chọn estimate_shares=True trong fa | Chỉ dùng để tham khảo nhanh vì số ước tính từ vốn điều lệ có thể lệch đáng kể sau các đợt phát hành mới |
| Không tách được lệnh phiên ATO, ATC | Khi bảng dữ liệu khớp lệnh không có cột session | Chủ động lọc bỏ các lệnh khớp tại khung giờ 09:15 và 14:45 trước khi đưa vào tính toán nếu cần độ chính xác cao |
| Biểu phí chưa được xác minh | Khi chạy backtest với một mã biểu phí có thuộc tính verified=False | Truyền trực tiếp mức phí thực tế của bạn qua tham số fee |
| Chưa mô phỏng đầy đủ chi phí phái sinh | Khi chạy backtest với hồ sơ thị trường vn_futures | Lưu ý rằng lãi lỗ mô phỏng thường cao hơn thực tế; cần tự trừ thêm thuế, phí quản lý vị thế và phí ký quỹ |
Bạn có thể dùng mô-đun warnings chuẩn của Python để ẩn các cảnh báo này sau khi đã đọc và nắm rõ ý nghĩa của chúng:
import warnings
from vnstock_quant import VnstockQuantWarning
# Bỏ qua các cảnh báo không trọng yếu của vnstock_quant
warnings.filterwarnings("ignore", category=VnstockQuantWarning)Các quy ước phương pháp luận dùng chung
Trước khi đối chiếu kết quả giữa các mô-đun hoặc so sánh với nguồn bên ngoài, hãy lưu ý các quy ước tính toán thống nhất dưới đây:
| Quy ước | Chi tiết áp dụng trong thư viện |
|---|---|
| Biểu diễn tỷ lệ và phần trăm | Mọi tỷ lệ phần trăm đều được truyền vào và trả ra dưới dạng phân số thập phân (ví dụ 0.18 tương ứng với 18%). |
| Giá đóng cửa và chuỗi lợi suất | Chuỗi lợi suất giản đơn cần được tính từ giá đóng cửa đã điều chỉnh (adjusted close). Nếu dùng giá gốc chưa điều chỉnh, ngày giao dịch không hưởng quyền sẽ tạo ra các phiên sụt giảm giá giả tạo. |
| Số phiên giao dịch trong một năm | Mặc định dùng 252 phiên/năm theo thông lệ quốc tế cho dữ liệu ngày (52 tuần, 12 tháng). Thống kê thực tế trên sàn HOSE giai đoạn 2017–2025 ghi nhận trung bình 249,8 phiên/năm; bạn có thể truyền periods=250 vào các hàm đo rủi ro nếu muốn quy đổi năm sát với lịch giao dịch Việt Nam. |
Lãi suất phi rủi ro (rf) | Được hiểu là lãi suất theo năm, mặc định bằng 0. Bạn có thể truyền vào lợi suất trái phiếu Chính phủ kỳ hạn 1 năm hoặc lãi suất tiền gửi tiết kiệm kỳ hạn 12 tháng. |
Căn chỉnh chỉ mục thời gian (time) | Dựa trên DatetimeIndex của pandas. Khi tính tương quan hoặc so sánh với chỉ số tham chiếu (Benchmark), hai chuỗi dữ liệu luôn được căn chỉnh theo ngày giao dịch chung, không ghép theo số thứ tự dòng. |
Xử lý dữ liệu khuyết thiếu (NaN) | Thư viện không bao giờ âm thầm điền số 0 vào ô trống. Trong mô-đun fa, chỉ số thiếu dữ liệu đầu vào sẽ trả NaN kèm mã giải thích trong cột reason (kể cả khi báo cáo chỉ có chỉ tiêu cấp 1). Trong mô-đun portfolio, các hàm tối ưu sẽ từ chối tính toán nếu chuỗi lợi suất có chứa NaN. |
| Dấu của độ đo rủi ro sụt giảm (VaR / CVaR) | Luôn trả về giá trị dương biểu thị mức sụt giảm (thua lỗ) tiềm năng tại ngưỡng tin cậy đã chọn. |
| Ràng buộc không bán khống (Long-only) | Các bài toán tối ưu hoá danh mục mặc định không cho phép tỷ trọng âm (bán khống), phù hợp với quy định hiện hành trên thị trường cổ phiếu cơ sở Việt Nam. |
Tài liệu đọc tiếp
- Quyền dùng và hạn mức theo cấp tài khoản — Chi tiết các tình huống dẫn tới ngoại lệ
TierRequiredErrorvàQuotaExceededError. - Điều chỉnh giá theo sự kiện quyền — Giải thích vì sao chuỗi lợi suất cần được tính trên giá đã điều chỉnh.
- Đối chiếu kết quả và tốc độ xử lý — Các thư viện và bộ dữ liệu chuẩn dùng để kiểm định kết quả của
vnstock_quant.
