Kiểm định chất lượng & hiệu năng

Một thư viện định lượng tài chính chỉ thực sự có giá trị khi kết quả tính toán kiểm chứng được và tốc độ đủ để tính trên nhiều mã.

Trước khi vnstock_quant ra đời, các nhà nghiên cứu và lập trình viên phân tích định lượng tại Việt Nam thường phải đối mặt với hai vấn đề lớn:

1. Sự phân mảnh và khó khăn khi cài đặt: Các thư viện Python truyền thống thường phụ thuộc vào các module C bên ngoài (như TA-Lib C core), dễ gặp lỗi tương thích trên Windows hoặc Apple Silicon ("dependency hell"), hoặc phải ghép 4–5 gói riêng lẻ (pandas-ta, empyrical, quantstats, pyxirr), mỗi gói một quy ước kiểu dữ liệu.
2. Khác biệt về quy ước tính: Mỗi thư viện có quy ước riêng về giai đoạn khởi động (warm-up), cách căn ngày tháng, và có thể đổi nhánh tính khi máy có hoặc không có thư viện C, nên cùng một chỉ báo có thể ra số khác nhau giữa các máy; một số phép tính còn chạy bằng vòng lặp Python nên chậm.

Thư viện vnstock_quant thế hệ 5 được thiết kế để giải quyết các bài toán trên bằng mô hình: Lõi tính toán Rust hiệu năng cao kết hợp lớp giao diện Python chuẩn mực, phân phối dưới dạng binary wheels biên dịch sẵn (zero C dependency ngoài), quy tụ trọn vẹn 5 trụ cột phân tích (TA, FA, Risk, Portfolio, Valuation) trong một thư viện duy nhất.

Tài liệu này công bố toàn bộ dữ liệu đối chiếu thực nghiệm, phương pháp kiểm định chéo với các mốc chuẩn quốc tế và kết quả đo kiểm hiệu năng thực tế.

---

1. Triết lý phát triển: Kế thừa chuẩn hoá & Thống nhất trong lõi Rust

Thống nhất trong một thư viện duy nhất

Thay vì người dùng phải tự tìm kiếm, cài đặt và bảo trì nhiều thư viện riêng lẻ với nguy cơ xung đột phiên bản (đặc biệt khi nâng cấp lên Python 3.12+ và pandas 2.x), vnstock_quant gom vào một thư viện:

• 58 chỉ báo kỹ thuật (TA) kế thừa bề mặt API thân thuộc của pandas-ta.
• 99 chỉ số báo cáo tài chính VAS (FA) chuẩn hoá cho 4 mô hình ngành.
• 33 thước đo rủi ro & hiệu suất (Risk) chuẩn CFA Institute.
• 38 hàm quản lý & tối ưu hoá danh mục (Portfolio) có tham số phí và thuế giao dịch tại Việt Nam.
• Mô hình định giá chiết khấu cổ tức và P/E hợp lý (Valuation) theo giáo trình CFA.

An toàn bộ nhớ và loại bỏ phụ thuộc phức tạp

• Không cần cài đặt C compiler: vnstock_quant được dựng sẵn dạng binary wheel cho macOS (Intel và Apple Silicon) và Linux x86_64/aarch64 dùng glibc 2.17 trở lên. Chưa có bản dựng sẵn cho Windows và Linux musl. Cài bằng pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant, hoặc vnstock install vnstock_quant khi đã có vnstock thế hệ 5.
• An toàn bộ nhớ (Memory Safety): Được viết hoàn toàn bằng Rust với nguyên tắc kiểm soát quyền sở hữu bộ nhớ chặt chẽ, giảm nguy cơ lỗi bộ nhớ (như Segmentation Fault) khi xử lý chuỗi dữ liệu lịch sử dài.
• Kết quả nhất quán trên mọi máy tính: Thế hệ cũ trước đây thường cho ra kết quả khác nhau tuỳ vào việc môi trường có cài TA-Lib C hay không. Với vnstock_quant, phép tính luôn đi qua cùng một lõi Rust, không đổi nhánh theo việc máy có cài TA-Lib C hay không.

---

2. Hệ thống mốc chuẩn đối chiếu thực nghiệm

Để kết quả kiểm chứng được, vnstock_quant đối chiếu với các mốc độc lập sau:

---

3. Báo cáo kiểm định 58 chỉ báo kỹ thuật

Báo cáo được trích xuất từ quy trình kiểm thử tự động trên 4 bộ dữ liệu kiểm định (daily, ticks_flat, gaps, range_index) và tập dữ liệu tham chiếu của QuantConnect LEAN.

Phân loại mức tin cậy (Confidence Levels)

Mỗi chỉ báo trong vnstock_quant đều được gắn nhãn tin cậy minh bạch trong catalog:

• Mức A (34 chỉ báo): Khớp hoàn toàn với mốc chuẩn công nghiệp TA-Lib C core 0.8.1 (sai số tương đối $0.0\text{e}+00$ hoặc $\le 10^{-12}$).
• Mức B (14 chỉ báo): Khớp với dữ liệu kiểm thử của QuantConnect LEAN hoặc công thức bài báo khoa học gốc (sai số $\le 10^{-8}$).
• Mức C (10 chỉ báo): Khớp với định nghĩa của chính tác giả phát minh (John Ehlers, Bill Williams, John Carter TTM Squeeze).

Bảng đối chiếu sai số chi tiết

Dưới đây là kết quả kiểm định số học của 58 chỉ báo so với các thư viện quốc tế và sự cải tiến so với thế hệ cũ:

(Ghi chú: Bảng rút gọn hiển thị các chỉ báo tiêu biểu. Toàn bộ 58 chỉ báo đều vượt qua 100% các ca kiểm thử hồi quy tự động).

16 chỉ báo đã sửa so với vnstock_ta 1.x

Trong vnstock_ta 1.x, một số chỉ báo lệch định nghĩa gốc do lỗi vòng lặp hoặc lỗi công thức. vnstock_quant đã sửa như sau:

1. psar: Sửa lỗi nhảy điểm đảo chiều không đúng công thức gia tốc của Wilder.
2. supertrend: Sửa lỗi trôi dải band trong các đợt biến động mạnh kéo dài.
3. dm: Sửa thuật toán cộng dồn Wilder Directional Movement.
4. cci: Sửa phép tính độ lệch tuyệt đối trung bình (Mean Absolute Deviation).
5. stdev & variance: Sửa việc nhầm lẫn giữa độ lệch chuẩn mẫu ($N-1$) và độ lệch chuẩn tổng thể ($N$), đồng bộ hoàn toàn với TA-Lib C.
6. obv: Sửa lỗi xử lý nến đứng giá (Close bằng phiên trước thì giữ nguyên khối lượng tích luỹ, không bị cộng dồn sai).
7. vp (Volume Profile): Sửa lỗi phân bố lại các bin khối lượng và bảo toàn 100% tổng khối lượng giao dịch.
8. squeeze & squeeze_pro: Sửa lỗi công thức dải Keltner Channel bên trong khiến tín hiệu siết/bung nén bị ngược pha.
9. cmo: Sửa phép làm mượt không đúng định nghĩa nguyên bản của Tushar Chande.
10. cg & fisher: Sửa hiện tượng tràn số thực khi giá trị tiến gần biên độ dao động.
11. kst: Sửa hệ số nhân trọng số 4 khung thời gian của Martin Pring.
12. nvi: Sửa điều kiện so sánh khối lượng sụt giảm so với phiên liền trước.
13. mfi: Sửa lỗi chia cho 0 khi dòng tiền âm bằng 0 trong giai đoạn thị trường tăng kịch trần liên tục.
14. pivots: Sửa lỗi lệch ngày khi tính điểm xoay trên dữ liệu intraday.
15. adx: Khắc phục hiện tượng không hội tụ số khởi động giữa các nền tảng.
16. macd: Chuẩn hoá chính xác giá trị khởi động của chuỗi EMA 12 và EMA 26.

---

4. Báo cáo hiệu năng thực tế (Benchmark Results)

Môi trường và phương pháp đo kiểm

• Phần cứng thử nghiệm: Apple M4 (10 nhân, 16 GB RAM, macOS arm64), đo ngày 06/10/2026, một luồng.
• Phần mềm: vnstock_quant 0.1.0 (lõi Rust biên dịch ở chế độ --release), Python 3.14, numpy 2.2, pandas 2.3.
• Dữ liệu đo: Dữ liệu tổng hợp 5.000 phiên ngày (khoảng 20 năm), mô phỏng bước giá và đặc thù thị trường chứng khoán Việt Nam.
• Lưu ý: Đây là số đo tham khảo trên một máy cụ thể; máy khác cho số khác. Tỷ lệ giữa các thư viện ổn định hơn số tuyệt đối.
• Tiêu chuẩn đo lường: Chạy lặp tối thiểu 7 lần sau 2 lượt warm-up; tính giá trị trung vị (median).

Tốc độ tính toán trọn bộ 58 chỉ báo kỹ thuật

Bảng so sánh thời gian thực thi khi tính toàn bộ 58 chỉ báo cho cùng một mã cổ phiếu (5.000 phiên):

So sánh thời gian xử lý từng chỉ báo tiêu biểu

Thời gian đo bằng đơn vị micro giây (µs). $1\text{ ms} = 1.000\text{ µs}$:

Năng lực tính toán trên quy mô toàn sàn (1.600 mã chứng khoán)

Mô phỏng bài toán lọc cổ phiếu hằng ngày: tính 15 chỉ báo cốt lõi (sma, ema, wma, rsi, macd, bbands, atr, stoch, adx, cci, willr, mfi, obv, vwap, hlc3) trên 1.600 chuỗi dữ liệu tổng hợp, cỡ toàn bộ mã niêm yết tại HOSE, HNX và UPCoM (mỗi chuỗi 1.250 phiên ~ 5 năm, dữ liệu đã nằm trong bộ nhớ):

Nhờ lõi Rust, thời gian tính chỉ báo kỹ thuật cho cỡ toàn bộ cổ phiếu trên sàn giảm từ 14 giây xuống chỉ còn hơn 1 giây (nhanh hơn 11.6 lần).

Khả năng co giãn theo kích thước dữ liệu

Thử nghiệm độ phức tạp thuật toán với chuỗi dữ liệu nến 1 phút kéo dài từ 1.000 đến 1.000.000 phiên trên tổ hợp 13 chỉ báo:

Kích thước chuỗi     vnstock_quant         vnstock_ta cũ         Tương quan
-------------------------------------------------------------------------
1.000 phiên              0.53 ms               14.3 ms             27.0x
10.000 phiên             1.28 ms              111.9 ms             87.1x
100.000 phiên            8.86 ms              819.7 ms             92.6x
1.000.000 phiên         97.10 ms            8.171.3 ms             84.2x

Lõi Rust duy trì sự tối ưu hoá bộ nhớ đệm CPU L1/L2/L3, giúp tốc độ xử lý nhanh hơn từ 84x đến 92x khi xử lý dữ liệu nến phút.

---

5. Chuẩn hoá học thuật & Khắc phục sai lệch mô hình Tài chính, Rủi ro, Danh mục

Chất lượng của vnstock_quant không chỉ nằm ở tốc độ của các chỉ báo kỹ thuật, mà còn nằm ở sự chuẩn hoá học thuật nghiêm ngặt trong phân tích BCTC, quản lý danh mục và định lượng rủi ro.

Khắc phục các sai lệch kinh điển trong phân tích tài chính (FA)

Quá trình rà soát và đối chiếu thực nghiệm đã xử lý các lỗi tính toán định lượng hay gặp sau:

1. Lỗi không quy đổi dòng tiền theo năm: Một lỗi hay gặp khi tự tính là chia lợi nhuận của một quý đơn lẻ cho vốn chủ sở hữu cuối kỳ mà không quy đổi theo năm ($x4$ hoặc 4 quý gần nhất - TTM), dẫn đến ROE bị tính sai lệch gấp 3–4 lần. vnstock_quant tự động chuẩn hoá theo chu kỳ 4 quý gần nhất (TTM) hoặc quy đổi theo năm chính xác.
2. Lỗi không lấy bình quân mẫu số: Các chỉ số hiệu quả hoạt động (ROA, ROE, Vòng quay tài sản) chuẩn CFA bắt buộc phải tính trên tài sản/vốn chủ bình quân $\frac{\text{Đầu kỳ} + \text{Cuối kỳ}}{2}$. vnstock_quant áp dụng mặc định phép tính bình quân này.
3. Minh bạch bằng cột reason: Khi dữ liệu BCTC của doanh nghiệp gặp bất thường (như vốn chủ sở hữu âm do lỗ luỹ kế, hoặc doanh nghiệp mới niêm yết chưa đủ 4 quý lịch sử), hàm tính toán không trả về giá trị sai lệch gây hiểu lầm mà trả về mã giải trình rõ ràng (NEGATIVE_EQUITY, INSUFFICIENT_PERIODS), để bộ lọc tự động của bạn nhận biết và bỏ qua điểm số liệu đó.

Chuẩn hoá đo lường rủi ro (Risk)

• Chuẩn hoá tỷ số Sharpe: Tính toán chuẩn mực với tử số là giá trị trung bình số học của phần bù rủi ro kỳ vọng ($\overline{R - R_f}$) chia cho độ lệch chuẩn số học, tránh lỗi dùng CAGR (trung bình hình học) ở tử số khiến Sharpe ratio bị đảo dấu âm/dương sai lệch.
• Thích ứng với biên độ trần/sàn Việt Nam: Với quy định biên độ giá $\pm 7\%$ (HOSE) hay $\pm 10\%$ (HNX), phân phối lợi suất chứng khoán Việt Nam có hiện tượng đuôi béo và bất đối xứng rõ rệt. vnstock_quant cung cấp mô hình Cornish-Fisher VaR/CVaR và chỉ số thanh khoản Amihud (2002) được kiểm định theo đúng công thức bài báo khoa học gốc.
• Căn chỉnh lịch giao dịch thực tế: Khắc phục lỗi ghép dữ liệu theo số thứ tự dòng thay vì theo ngày giao dịch (Trading Date Index), tránh lệch phiên khi cổ phiếu bị tạm ngừng giao dịch.

Quản lý danh mục & Tối ưu hoá (Portfolio)

• Tái cân bằng theo dòng thời gian: portfolio_returns tính lợi suất danh mục theo lịch tái cân bằng (tháng, quý, năm hoặc khi tỷ trọng lệch quá dải cho phép), tỷ trọng trôi theo giá giữa hai lần tái cân bằng. Việc tỷ trọng mục tiêu không dùng thông tin tương lai (Lookahead Bias) do bạn tự kiểm soát.
• Tối ưu hoá chỉ mua (Long-only Constrained Optimization): Giải thuật tối ưu hoá danh mục phương sai tối thiểu (GMV) và tỷ trọng rủi ro bằng nhau (ERC) được tích hợp điều kiện biên chặt chẽ: $w_i \ge 0$, $\sum w_i = 1$, và quy tắc làm tròn lô 100 cổ phiếu theo quy định giao dịch tại Việt Nam, không âm thầm trả về danh mục chia đều $1/N$ khi solver gặp ràng buộc khó.
• Tính cả chi phí giao dịch: Truyền bộ tham số pm.VN_COSTS (phí môi giới $0.15\%$, thuế bán chứng khoán $0.1\%$) vào portfolio_returns để lợi suất danh mục theo lịch tái cân bằng đã trừ phí và thuế.

---

6. Tổng kết giá trị mang lại cho người dùng

vnstock_quant chạy bộ kiểm thử hồi quy tự động trước mỗi bản phát hành.

---

Đọc tiếp

• Chỉ báo kỹ thuật — Tính toán 58 chỉ báo kỹ thuật với lõi Rust.
• Chỉ số tài chính — Tự tính 99 chỉ số BCTC VAS và mô hình dòng tiền CFA.
• Đo lường rủi ro và hiệu suất — 33 thước đo hiệu suất và rủi ro chuẩn CFA.
• Chuyển đổi từ vnstock_ta — Hướng dẫn nâng cấp từ vnstock_ta 1.x sang vnstock_quant.