# Vnstock - Hệ sinh thái Python cho nghiên cứu đầu tư cá nhân | Full Documentation Context > Vnstock gồm năm thư viện Python kết nối thành một quy trình nghiên cứu: tổ chức đầu vào, xử lý dòng thông tin, tính toán định lượng, tự động hoá và tương tác với trợ lý AI trên hạ tầng do người dùng kiểm soát. > > vnstock và vnstock_news đảm nhiệm lớp đầu vào; vnstock_quant cung cấp tính toán định lượng; vnstock_pipeline tổ chức tự động hoá; vnstock_mcp làm cầu nối cục bộ cho trợ lý AI gọi bộ công cụ ngay trên máy cá nhân. Kết nối dữ liệu chỉ là một mắt xích của hệ sinh thái. Bản Cộng đồng miễn phí cho cá nhân, học tập và nghiên cứu theo giấy phép riêng; bản Mở rộng dành cho người dùng gói quyền sử dụng và vẫn cấp quyền theo diện cá nhân. Vnstock cấp quyền trực tiếp đối với các công cụ phần mềm, khung quy trình và máy chủ MCP cục bộ do dự án phát triển; riêng với dữ liệu lấy qua module kết nối nguồn bên thứ ba, điều kiện sử dụng dữ liệu tuân theo từng nguồn. > Vnstock is a five-library Python ecosystem for personal investment research: input organization, information processing, quantitative computation, workflow automation, and local AI tool orchestration. Data connectivity is one part of the system, not the product's full identity. The software runs on user-controlled infrastructure. Vnstock directly licenses its computation, pipeline, and local MCP software tools; when using third-party source connectors (vnstock, vnstock_news), source data remains subject to each source's terms. ## Phạm vi hệ sinh thái - vnstock và vnstock_news tổ chức dữ liệu và thông tin đầu vào cho quy trình nghiên cứu. - vnstock_quant cung cấp các phép tính định lượng có thể kiểm tra lại. - vnstock_pipeline giúp lưu trữ, điều phối và tự động hoá công việc lặp lại. - vnstock_mcp là cầu nối chạy cục bộ (Local) giúp ứng dụng AI gọi trực tiếp bộ công cụ Vnstock ngay trên máy cá nhân và xuất mã Python tái lập (không phải dịch vụ MCP trực tuyến phát dữ liệu từ máy chủ). ## Ranh giới cần hiểu đúng - Các công cụ tính toán, lưu trữ quy trình và máy chủ MCP cục bộ (vnstock_quant, vnstock_pipeline, vnstock_mcp, Agent Skills) là phần mềm do Vnstock phát triển và cấp quyền trực tiếp cho người dùng vận hành trên mọi bảng dữ liệu đầu vào. - Truy vấn qua module kết nối nguồn ngoài (vnstock, vnstock_news) xuất phát từ môi trường của người dùng và đi tới nguồn bạn chọn; điều kiện sử dụng dữ liệu lấy về tuân theo từng nguồn. - Dịch vụ do Vnstock vận hành xử lý dữ liệu tài khoản, thanh toán, giấy phép, thiết bị, hạn mức, bảo mật và đo lường kỹ thuật theo Chính sách quyền riêng tư. - Vnstock bảo lưu quyền đối với mã phần mềm, cấu trúc dữ liệu, hệ phân loại, bảng ánh xạ, tài liệu, thiết kế và nhãn hiệu; không tuyên bố sở hữu nội dung của nguồn bên thứ ba chỉ vì đã chuẩn hoá chúng. - Vnstock là công cụ nghiên cứu và tính toán định lượng; việc diễn giải kết quả và ra quyết định đầu tư thuộc về người dùng. # Library Documentation & User Guides ## Document: Bản cũ 4.x Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member/cai-dat-go-loi/legacy](/onboard-member/cai-dat-go-loi/legacy). --- ## Document: Cài đặt và gỡ lỗi Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member/cai-dat-go-loi](/onboard-member/cai-dat-go-loi). --- ## Document: Lỗi môi trường Python Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/docs/goi-quyen-su-dung/go-loi-va-cau-hoi-thuong-gap](/docs/goi-quyen-su-dung/go-loi-va-cau-hoi-thuong-gap). --- ## Document: Trung tâm hướng dẫn gói quyền sử dụng Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member](/onboard-member). --- ## Document: Agent Skills Hub Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/agent-skills-hub](/agent-skills-hub). --- ## Document: Bản cũ 4.x Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/legacy](/onboard/legacy). --- ## Document: Cài Python lần đầu Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/cai-dat-moi-truong-python](/onboard/cai-dat-moi-truong-python). --- ## Document: Chạy thử trên Colab Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/trai-nghiem-vnstock](/onboard/trai-nghiem-vnstock). --- ## Document: Trung tâm hướng dẫn Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard](/onboard). --- ## Document: Vibe Coding với Vnstock Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/vibe-coding](/onboard/vibe-coding). --- ## Document: Nhóm hàm truy xuất dữ liệu cổ phiếu
Bảng thông tin dưới đây mô tả về độ phủ (coverage) của dữ liệu có thể truy xuất từ Vnstock3. Lưu ý: Vnstock3 chạy trên máy của bạn, gửi truy vấn thẳng tới các API truy cập công khai của công ty chứng khoán và tải dữ liệu vào môi trường Python. Dữ liệu truy xuất qua Vnstock3 là dữ liệu tham khảo từ nguồn bên thứ ba; tính sẵn sàng và độ chính xác phụ thuộc nguồn, bạn tự kiểm tra trước khi dùng. Thông tin tần suất cập nhật dựa vào kinh nghiệm quan sát các thay đổi trong đặc tính và cập nhật của dữ liệu.
| Nhóm thông tin | Lớp | Mục | Hàm | Tần suất cập nhật | Nguồn truy xuất | | ------------------- | ------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Danh sách niêm yết | Listing | [Tất cả mã](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `all_symbols()` | - | VCI | | | | [Tất cả mã chia theo sàn](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_exchange()` | - | VCI | | | | [Tất cả mã chia theo nhóm](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_group('VN30')` | - | VCI | | | | [Tất cả mã chia theo ngành](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_industries()` | - | VCI | | | | [Danh sách ngành icb](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `industries_icb()` | - | VCI | | | | [Danh sách mã CK quốc tế](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#4-tim-kiem) | `search_symbol_id('USD')` | trong phiên, theo độ trễ của nguồn | MSN | | Thông tin công ty | Company | [Tổng quan](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `overview()` | - | TCBS | | | | [Hồ sơ công ty](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `profile()` | - | TCBS | | | | [Cổ đông lớn](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `shareholders()` | - | TCBS | | | | [Lãnh đạo](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `officers()` | - | TCBS | | | | [Công ty con](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `subsidiaries()` | - | TCBS | | | | [Cổ tức](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `dividends()` | - | TCBS | | | | [Giao dịch nội bộ](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `insider_deals()` | - | TCBS | | | | [Sự kiện](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `events()` | - | TCBS | | | | [Tin tức](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `news()` | - | TCBS | | Báo cáo tài chính | Finance | Báo cáo kết quả kinh doanh | `income_statement()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bao-cao-ket-qua-kinh-doanh), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bao-cao-ket-qua-kinh-doanh) | | | | Bảng cân đối kế toán | `balance_sheet()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bang-can-doi-ke-toan), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bang-can-doi-ke-toan) | | | | Báo cáo lưu chuyển tiền tệ | `cash_flow()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bao-cao-luu-chuyen-tien-te), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bao-cao-luu-chuyen-tien-te) | | | | Chỉ số tài chính | `ratio()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#chi-so-tai-chinh), [TCBS](/docs/vnstock/bao-cao-tai-chinh#chi-so-tai-chinh) | | Giá chứng khoán | Quote | Giá lịch sử (đồ thị nến) | `history(start='2020-01-01', end='2024-12-31')` | Trong phiên theo độ trễ của nguồn, chi tiết đến cấp độ phút | [VCI](/docs/vnstock/thong-ke-gia-lich-su#gia-lich-su-ohlcv), TCBS | | | | Khớp lệnh trong ngày | `intraday(symbol='ACB', show_log=False)` | Trong phiên theo từng giao dịch, chi tiết đến cấp độ giây, theo độ trễ của nguồn | [VCI](/docs/vnstock/thong-ke-gia-lich-su#du-lieu-khop-lenh-intraday), TCBS | | | | Khối lượng giao dịch theo bước giá. | `price_depth('ACB')` | Trong phiên, theo độ trễ của nguồn | VCI, TCBS | | Thông tin Giao dịch | Trading | Thông tin bảng giá | `price_board(['ACB'])` | Trong phiên, theo độ trễ của nguồn | [VCI](/docs/vnstock/du-lieu-thi-truong-market-data), TCBS | --- ## Document: Giới Thiệu

Dành cho người dùng gói quyền sử dụng

Các thư viện này dành cho người dùng gói quyền sử dụng Vnstock, giúp bạn tự động hoá quy trình truy xuất, phân tích và xử lý dữ liệu thị trường chứng khoán Việt Nam. Mỗi thư viện có tài liệu hướng dẫn riêng.

## Tổng quan hệ sinh thái Bản Mở rộng cấp quyền theo cấp đối với năm phần mềm thế hệ 5: `vnstock`, `vnstock_quant`, `vnstock_mcp`, `vnstock_news` và `vnstock_pipeline`. Mỗi phần mềm giải quyết một lớp công việc riêng trong quy trình của người dùng.

Vnstock

Kết nối và chuẩn hoá dữ liệu thị trường

Một thư viện, một cách gọi hàm cho mọi cấp. Công cụ chạy trên máy của bạn, gửi truy vấn thẳng tới nguồn và chuẩn hoá dữ liệu ngay tại đó; quyền sử dụng quyết định hàm nào chạy. Bản Mở rộng mở thêm dữ liệu intraday, khối ngoại, BCTC đủ chỉ tiêu và vĩ mô.

Bản Mở rộng: Bronze+ Tài liệu →

Vnstock Quant

Tính toán định lượng trên bảng dữ liệu

Thay cho vnstock_ta: chỉ báo kỹ thuật, chỉ số tài chính, đo lường rủi ro và tối ưu danh mục với lõi Rust. Cộng đồng dùng thử 10 chỉ báo và 10 chỉ số cơ bản; Bronze mở chỉ số tài chính, rủi ro và danh mục; từ Silver có đủ 58 chỉ báo kỹ thuật.

Đủ chỉ báo: Silver+ Tài liệu →

Vnstock MCP

Cầu nối cho trợ lý AI

Máy chủ MCP chạy trên máy của bạn để trợ lý AI gọi các thư viện Vnstock. Dùng được từ bản Cộng đồng; công cụ nào hiện ra theo quyền sử dụng của các thư viện bên dưới, và mỗi lần gọi tính vào hạn mức chung của gói.

Từ Cộng đồng Tài liệu →

Vnstock News

Truy xuất tin tức đa nguồn

Truy xuất tin tức từ hơn 20 trang tin tài chính Việt Nam, trong phạm vi điều kiện của từng trang. Hỗ trợ RSS, Sitemap, trích xuất Markdown và phân tích xu hướng tích hợp sẵn cho nghiên cứu chuyên sâu.

Yêu cầu: Silver+
Tài liệu →

Vnstock Pipeline

Data pipeline tự động hiện đại

Tự động hoá quy trình dữ liệu trên hạ tầng của bạn, với số luồng đồng thời có giới hạn và khoảng nghỉ giữa các yêu cầu. Hỗ trợ xuất đa định dạng (CSV, Parquet, DuckDB) và kiến trúc linh hoạt.

Yêu cầu: Golden+ Tài liệu →
--- ## Lựa chọn gói quyền sử dụng phù hợp Xem chi tiết các gói quyền sử dụng và so sánh quyền lợi để chọn gói phù hợp với nhu cầu của bạn:
So sánh gói quyền sử dụng Cài đặt & sử dụng
--- ## Lưu ý quan trọng

Bản quyền & Miễn trừ trách nhiệm

Công ty cấp quyền sử dụng đối với từng phần mềm. Riêng nội dung được kết nối qua vnstock hoặc vnstock_news vẫn thuộc phạm vi quyền và điều kiện của nguồn tương ứng. Vnstock không vận hành kho nội dung thị trường để bán lại; dữ liệu nghiệp vụ nằm trên hạ tầng do bạn cấu hình, còn dịch vụ tài khoản, giấy phép và hạn mức xử lý dữ liệu theo Chính sách quyền riêng tư.

Dự án Vnstock được cung cấp chỉ nhằm mục đích nghiên cứu, giáo dục và sử dụng cá nhân. Vnstock và người dùng chịu trách nhiệm trong phạm vi vai trò của mình: bạn chịu trách nhiệm về credential, mục đích sử dụng và việc phân phối kết quả; Vnstock chịu trách nhiệm về mô tả trung thực và thiết kế phần mềm. Trong phạm vi pháp luật cho phép, Vnstock và tác giả không chịu trách nhiệm đối với thiệt hại hay tổn thất phát sinh từ việc sử dụng thư viện. Vnstock không cung cấp tư vấn đầu tư hoặc tín hiệu giao dịch.

--- ## Document: Lịch sử phiên bản Trang này gom thay đổi của bản Mở rộng từ nhật ký riêng của từng thư viện, xếp theo ngày. Nhãn **[Mở rộng]** đánh dấu phần chỉ có ở bản Mở rộng. Muốn đọc riêng một thư viện, mở mục Lịch sử phiên bản trong tài liệu của thư viện đó. ## 27-10-2026 ### vnstock_quant (v0.5.0) #### Mô-đun mới: chạy thử chiến lược (`backtest`) `vnstock_quant.backtest` chạy thử chiến lược trên dữ liệu giá bạn chuẩn bị, theo luật thị trường Việt Nam, trong cùng lõi Rust với các nhóm hàm khác: bảng quy tắc dùng đúng 58 chỉ báo của `ta`, tear sheet dùng 33 thước đo của `risk`, chung cấp quyền và cây lỗi của thư viện. Tài liệu: [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu). - **Tín hiệu**: mảng `[-1, 0, 1]`, cặp `entries`/`exits` hoặc bảng quy tắc `rule_dsl` dạng JSON; kiểm thiên lệch nhìn trước tương lai cho cả hàm tín hiệu và bảng quy tắc (`check_causality`, `check_rule_dsl_causality`). - **Luật thị trường**: mặc định lô 100, bước giá theo sàn, biên độ, phiên khóa trần và khóa sàn, T+2.5, thuế bán 0,1% tính riêng ngoài phí; hồ sơ phái sinh VN30F, crypto, cổ phiếu quốc tế, ngoại hối; cổ tức tiền, cổ phiếu thưởng và quyền mua trên giá gốc. - **Khớp lệnh**: chế độ `vn_realistic` và bốn chế độ tái tạo hành vi mặc định của backtesting.py, backtrader, vectorbt, zipline, khớp tới từng lệnh trên 11 kịch bản đối chứng; lệnh giới hạn và lệnh dừng theo phiên, nhiều lô trong một vị thế, chốt lời từng phần, dừng lỗ động, chặn rủi ro cấp tài khoản. - **Danh mục và chống quá khớp**: `run_portfolio` cho nhiều mã chung một tài khoản và tái cân bằng theo tỷ trọng; `sweep`, `walk_forward`, `monte_carlo`, `deflated_sharpe_ratio`. - **Gọi bằng JSON**: `catalog()`, `schema()` và `call()` với 10 công cụ dùng được trực tiếp cho trợ lý AI và Vnstock MCP. - **Lỗi và quyền**: lớp lỗi mới `CausalityViolationError` (`QUANT_CAUSALITY_VIOLATION`); mã `QUANT_QUOTA_LIMIT` (`QuotaExceededError`) khi một lần chạy vượt quy mô của cấp; `vq.entitlement()` có thêm khoá `backtest` và bộ quy tắc `quant_entitlement_v3`. - **[Mở rộng]** Từ Bronze mở đủ chỉ báo, danh mục, dò tham số, walk-forward, Monte Carlo; các cấp khác nhau ở quy mô mỗi lần chạy. - Extra `chart` (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) cài [`vnstock_chart`](/docs/vnstock-chart) để vẽ kết quả chạy thử. #### Mô-đun mới: giá điều chỉnh (`prices`) - **[Mở rộng]** `vnstock_quant.prices` chuyển giá chưa điều chỉnh sang giá đã điều chỉnh theo cổ tức tiền, cổ phiếu thưởng và quyền mua, kiểm từng sự kiện với giá tham chiếu của sàn: `prices.adjust()`, `prices.factors()` và `prices.from_vnstock()`. Xem [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh). #### Chỉ số tài chính (`fa`) Các chỉ số nêu sau cho số khác bản 0.4.0; những chỉ số không nhắc tới giữ nguyên. Mỗi thay đổi được kiểm trên dữ liệu thị trường tải ngày 27/10/2026 và trên 64 mã của bộ đối chiếu. Cách tính chi tiết xem ở [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa). - **P/E, P/B, P/S, P/CF, EV/EBITDA kỳ năm**: Lấy giá đóng cửa và số cổ phiếu của cùng một phiên, tại ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4 và P/E bằng giá / EPS trong cùng một dòng. Bản trước lấy giá cuối năm sau nhân với số cổ phiếu của năm báo cáo: chỉ số dùng giá của một năm sau kỳ báo cáo, và thấp hơn thực tế khi có chia cổ phiếu trong năm sau (P/E năm 2024 của VCB ra 9,5 thay vì 14,65; FPT ra 17,9 thay vì 22,2). Tham số `overrides={"year_valuation": ...}` không còn dùng được. - **Dòng quý 4 của chuỗi quý**: Mẫu số bình quân (ROE, ROA, vòng quay, số ngày thu tiền...) là bình quân 4 điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán. Bản trước dùng bình quân đầu năm và cuối năm, làm chuỗi quý nhảy ở mỗi quý 4 (ROE quý 4 của ngân hàng cao hơn trung bình hai quý kề 2,2%; nay −0,3%, ngang các quý khác). ROE quý 4/2025 của FPT từ 28,29% thành 27,25%. Dòng năm không đổi. - **[Mở rộng]** **Tăng trưởng tín dụng và huy động theo quý** (`RT_BANK_LOAN_GROWTH`, `RT_BANK_DEPOSIT_GROWTH`): Quý 4 so với cuối quý 3 như các quý khác. Bản trước so quý 4 với cuối năm trước, trộn tăng trưởng một quý với tăng trưởng cả năm (tín dụng VCB quý 4/2025: 15,5% thành 2,7%). Dòng năm không đổi. - **[Mở rộng]** **CIR và thu nhập ngoài lãi theo quý** (`RT_BANK_CIR`, `RT_BANK_NOII`): Quý 4 tính trên số riêng của quý 4, như các quý khác. Bản trước dùng số cả năm. - **[Mở rộng]** **Chỉ số dòng tiền kinh doanh với ngân hàng và công ty chứng khoán**: `RT_VALUE_P_CF`, `RT_VALUE_CFPS`, `RT_CF_CROA`, `RT_CF_CROE`, `RT_CF_INCOME_QUALITY`, `RT_CF_DEBT_COVERAGE`, `RT_CF_DIVIDEND_PAYMENT`, `RT_CF_TO_REVENUE` trả `NOT_APPLICABLE` cho hai loại hình này. Dòng tiền kinh doanh của ngân hàng và công ty chứng khoán chủ yếu là tiền gửi, cho vay và mua bán chứng khoán; P/CF quý của VCB đi từ −13,7 tới 123,3 trong hai năm. - **[Mở rộng]** **Tỷ lệ dồn tích theo lưu chuyển tiền tệ** (`RT_QUALITY_ACCRUALS_CF`): Loại tiền chi cho vay, gửi có kỳ hạn và tiền thu hồi khỏi dòng tiền đầu tư, cho khớp với tài sản hoạt động thuần (đã loại tiền và đầu tư ngắn hạn). Tương quan với bản theo bảng cân đối tăng từ 0,16 lên 0,87 (266 năm-doanh nghiệp); FPT năm 2025 từ 0,575 thành 0,220. - **[Mở rộng]** **DuPont**: `RT_DUPONT_TAX_BURDEN` là lợi nhuận sau thuế / lợi nhuận trước thuế, theo giáo trình CFA (FPT năm 2025: 0,861, bằng 1 − thuế suất hiệu dụng). Chỉ số mới `RT_DUPONT_PARENT_SHARE` (lợi nhuận cổ đông công ty mẹ / lợi nhuận sau thuế) tách phần của cổ đông không kiểm soát; tích sáu thành phần bằng ROE. Thư viện có 100 chỉ số. - **Mô tả ROE trong `fa.describe()`**: Bỏ câu nói hồ sơ `vn` đổi mẫu số từ năm 2022; ROE luôn chia cho vốn chủ của cổ đông công ty mẹ bình quân. - **`fa.Dataset.load()` khi chưa tải được giá**: Nếu cấp của `vnstock` chưa mở giá chưa điều chỉnh, thư viện cảnh báo một lần và vẫn tính các chỉ số từ báo cáo tài chính; chỉ số định giá trả `MISSING_MARKET`. Dùng `prices=False` để bỏ qua bước tải giá. #### Thay đổi khác - **Vi cấu trúc (`micro`)**: Mỗi lần gọi một hàm tính là một lượt, kể cả hàm chạy nhiều bước bên trong như `bars` và `cvd`. - **Đo lượt dùng**: Thư viện không còn hỏi đồng ý đo lượt dùng ở lần chạy đầu. Lựa chọn đặt trên vnstocks.com, mục tùy chọn dữ liệu của tài khoản; chưa chọn thì không đo. Tắt riêng trên máy bằng `vnstock_quant.telemetry.disable()` hoặc biến môi trường `VNSTOCK_TELEMETRY=0`. ## 18-10-2026 ### vnstock_chart (v1.0.0) #### Phát hành dưới tên vnstock_chart - **Đổi tên**: `vnstock_ezchart` thành `vnstock_chart`. Hai gói được cài riêng; nếu đang dùng gói cũ, xem [cách chuyển sang vnstock_chart](/docs/vnstock-chart/khac-biet-voi-ezchart). - **Kênh phát hành**: Cài từ kho phát hành thư viện của Vnstock bằng `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart`. - **Phụ thuộc**: Yêu cầu `vnstock>=5.0`. `squarify` (cho `treemap()`) và `wordcloud` là phụ thuộc tuỳ chọn, cài bằng `vnstock-chart[all]`; thiếu chúng thì các hàm còn lại vẫn chạy. - **Sửa lỗi đóng gói**: Bản cài qua `pip install` có đủ mọi thư mục con, không còn lỗi `ModuleNotFoundError` mà `vnstock_ezchart` 1.0.1 và 1.0.2 gặp. ## 17-10-2026 ### vnstock_quant (v0.4.0) #### Dữ liệu khung phút - **[Mở rộng]** **Ichimoku**: Với nến trong ngày, span tương lai đi tiếp theo nhịp phiên giao dịch có trong dữ liệu (bỏ qua giờ nghỉ trưa, hết phiên thì sang ngày làm việc kế tiếp), thay vì lùi xa 26 ngày. Thị trường giao dịch cả cuối tuần (ví dụ tiền mã hoá) được giữ Thứ 7 và Chủ nhật. Nến ngày không đổi. - **[Mở rộng]** **Ichimoku với cột thời gian**: Bảng có cột `time` (hoặc `date`, `ngay`...) trên chỉ mục số thứ tự, như dữ liệu trả về từ `vnstock`, nay có span tương lai đánh chỉ mục theo thời gian. Bảng chính vẫn giữ chỉ mục của bạn. - **VWAP và pivots**: Đọc được cột thời gian dạng `dd/mm/YYYY HH:MM` và `dd/mm/YYYY HH:MM:SS`. - **[Mở rộng]** **MFI**: Khi dữ liệu có nến thiếu giá trị, chỉ báo trả `NaN` cho các cửa sổ chứa nến đó, không còn dừng chương trình. - **[Mở rộng]** **Rủi ro (`risk`)**: Lợi suất theo phút được gộp thành lợi suất ngày trước khi tính các thước đo quy đổi theo năm, và được ghép với chuỗi đối chiếu theo đúng mốc thời gian (kể cả khi một bên thiếu vài phút). Áp dụng cho các hàm `risk` và `portfolio.risk_decomposition`. Lợi suất ngày cho kết quả như trước. - **Chỉ số tài chính (`fa`)**: Bảng giá theo phút được đọc thành một phiên mỗi ngày, lấy giá của nến cuối ngày (kể cả phiên ATC). Bảng giá ngày không đổi. #### Thay đổi khác - **[Mở rộng]** **`portfolio`**: Bổ sung tham số `flow_dates` cho `twr`, `periods` cho `covariance`, lịch tái cân bằng `M`/`Q`/`Y` cho `portfolio_returns`, và `weights`/`benchmark_weights` cho `ex_ante_tracking_error` (`active_weights` không còn bắt buộc). Cách gọi cũ cho kết quả như cũ. - **[Mở rộng]** **`portfolio.twr`**: Chạy được với chỉ mục ngày có múi giờ. - **[Mở rộng]** **`fa.Dataset.from_frames`**: Bỏ các dòng giá thiếu thời gian; chuỗi thời gian lẫn nhiều múi giờ khác nhau báo `ValueError`. - **Thông báo lỗi**: `vwap` với `anchor` không hợp lệ báo `InvalidParameterError` bằng tiếng Việt, giống `micro.cvd`. - **Chú thích hàm**: Chú thích viết bằng tiếng Anh; mô tả ngắn của 58 chỉ báo viết song ngữ (tiếng Anh trước, tiếng Việt sau). Công thức và phương pháp chi tiết xem ở các trang tài liệu. - **Đo lượt dùng**: Câu hỏi đồng ý đo lượt dùng ở lần chạy đầu thống nhất giữa các thư viện thế hệ 5. ## 15-10-2026 ### vnstock > Cập nhật Vnstock 5.0.3 Bản này thay cho 5.0.2 (đã rút khỏi kho phát hành). Hướng đi của thư viện: mọi con số bạn nhận được đều kiểm chứng được. Số liệu một nguồn tự tính theo phương pháp riêng, không công bố cách tính, không còn được cung cấp; phần tính toán do các thư viện tính toán và phân tích của Vnstock đảm nhận, chạy trên máy bạn, theo công thức công khai. ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock ``` **Không còn hỗ trợ.** Các hàm dưới đây giữ tên để mã cũ không lỗi khi import, nhưng gọi là báo `UnsupportedError` mã `VNSTOCK_FEATURE_REMOVED`: * **[Mở rộng]** `Insights().flow.active()`: dòng tiền mua, bán chủ động. Lệnh khớp nào tính là bên chủ động do nguồn tự phân loại. * **[Mở rộng]** `Insights().sector(...)`: `flow()`, `flow_intraday()`, `index_intraday()`, `valuation()`, `rrg()`; `Insights().equity(...)`: `order_flow()`, `order_flow_history()`, `peer_compare()`, `rrg()`. Các hàm này chưa từng trả dữ liệu ở thế hệ 5; nay báo rõ là không làm. * **[Mở rộng]** `Reference().company(...).ratio_summary()`. * Các hàm cùng loại ở lớp tương thích `vnstock.explorer.asean` (RRG, tín hiệu, chỉ số sợ hãi và tham lam, mua bán chủ động, định giá và dòng tiền ngành, so sánh cùng ngành). **Thay đổi cần lưu ý** * **[Mở rộng]** `Insights().sentiment.breadth()` bỏ ba cột `pe`, `pb`, `position_line` (số liệu nguồn tự tính). Bảng giữ các cột tỷ lệ mã có giá trên đường trung bình 20 và 50 phiên. * **[Mở rộng]** `Fundamental().equity(...).ratio()` dùng được đến hết ngày 15/01/2027, mỗi lần gọi kèm `FutureWarning`. Bảng này do mỗi nguồn tự tính bằng công thức riêng. Hãy chuyển sang `vnstock_quant.fa.ratios()`: chỉ số tính trên máy bạn từ báo cáo tài chính công bố đã chuẩn hoá, theo công thức công khai đã kiểm chứng. **Dòng lệnh** * `vnstock tools` thay cho `vnstock api`: cây các hàm để bạn tự truy xuất dữ liệu. Cây chỉ hiện hàm nên dùng; tên cũ, tên khác, hàm sắp bỏ và không còn hỗ trợ vẫn gọi được và vẫn xem được bằng `vnstock doc`. Gõ `vnstock api` vẫn chạy. * `vnstock onboard` (mới): hướng dẫn ngắn cho trợ lý AI trước khi làm việc với vnstock, gồm phiên bản, cấp và thư viện bổ sung trên máy, quy tắc cần theo, bước tiếp theo theo cấp và các skill cấp đó đọc được. Câu lệnh khởi động trên [vnstocks.com/onboard](https://vnstocks.com/onboard) nay bảo trợ lý chạy lệnh này đầu tiên. * `vnstock skills show ` chỉ in phần giới thiệu công khai của skill (mô tả, cấp cần có, trang giới thiệu); nội dung skill dành cho trợ lý AI đọc trong phiên làm việc. **Cải thiện khác** * Thông tin trích dẫn nguồn trong `df.attrs` (tên nguồn, đường dẫn điều khoản, tuyên bố miễn trừ) được cập nhật từ vnstocks.com, không cần chờ bản mới. * Gói cài nhẹ hơn: thư viện lõi trên macOS ARM giảm từ 10,3 MB xuống 7,9 MB. ### vnstock_news (v3.1.1) #### Bản 3.x trên lõi Rust, thuộc đợt phát hành Vnstock thế hệ 5 - **Lõi xử lý mới**: Bản 3.x chạy trên lõi Rust biên dịch sẵn, thay cho lõi Python của bản 2.x. Các lớp cũ (`Crawler`, `BatchCrawler`, `AsyncBatchCrawler`, `EnhancedNewsCrawler`, `Cache`, `ContentCleaner`, `InputValidator`) vẫn dùng được, nên mã viết cho bản 2.x chạy tiếp mà không phải viết lại. - **Hai hàm gọn mới**: `fetch_feeder()` lấy danh sách tin mới, `fetch_articles()` đọc chi tiết bài viết. Bảng đối chiếu mã cũ và mới xem ở [chuyển đổi từ bản cũ](/docs/vnstock-news/chuyen-doi-tu-ban-cu). - **Sửa lỗi lệch giờ**: Lọc `within="1h"` không còn lấy nhầm bài của 8 tiếng trước; thời gian chuẩn hoá theo giờ Việt Nam (UTC+07:00). - **Nhận diện thời gian tiếng Việt**: Các dạng tương đối như `"5 phút trước"`, `"hôm qua"` được đổi về ngày giờ chuẩn. - **Sửa lỗi dính chữ**: Chữ không còn bị nối liền (`Giávàngtăng` nay đọc đúng là `Giá vàng tăng`). - **An toàn kết nối**: Xác thực TLS luôn bật mặc định, chặn các chuyển hướng không an toàn. - **Tiện hơn khi import**: `SITES_CONFIG` và `SUPPORTED_SITES` import thẳng từ `vnstock_news`. - **[Mở rộng]** **Quyền sử dụng**: Thư viện dành cho người dùng bản Mở rộng từ cấp Silver trở lên. ### vnstock_pipeline (v3.1.1) #### Bản 3.x trên lõi Rust, thuộc đợt phát hành Vnstock thế hệ 5 - **Lõi xử lý mới**: Bản 3.x chạy trên lõi Rust biên dịch sẵn, xử lý nhanh hơn bản 2.x khi thư mục dữ liệu lớn. - **Cấu hình tập trung**: Vị trí lưu, định dạng tệp (Parquet nén hoặc CSV) và cấu trúc thư mục do tệp `pipeline.toml` điều khiển, quản lý bằng giao diện dòng lệnh. - **Tải bù theo mã lỗi**: Mã gặp sự cố mạng được ghi vào sổ nhật ký, tuỳ chọn `--retry-errors` tải bù đúng các mã đó mà không phải chạy lại từ đầu. - **Cách ly tệp bất thường**: Khi cấu trúc cột đổi hoặc dữ liệu rỗng, đứt gãy thời gian, tệp được chuyển vào vùng `.quarantine`, không lẫn vào kho chính. - **Cây thư mục tự dựng**: Cây thư mục dữ liệu hiển thị ngay từ thư viện, không cần công cụ `tree` cài thêm. - **Cách nâng cấp**: xem [nâng cấp từ bản 2.x](/docs/vnstock-pipeline/chuyen-doi/nang-cap-tu-ban-2x). - **[Mở rộng]** **Quyền sử dụng**: Thư viện dành cho người dùng bản Mở rộng từ cấp Golden trở lên. ## 12-10-2026 ### vnstock_mcp (v0.4.0) #### Bản đầu tiên có tài liệu - **Cầu nối chạy cục bộ**: Trợ lý AI trên máy bạn khởi chạy tiến trình `vnstock-mcp` từ môi trường Python cá nhân; không có máy chủ trung gian đứng giữa. - **Kết nối bằng một lệnh**: `vnstock-mcp --setup <ứng dụng>` in sẵn cấu hình cho Claude Desktop, ChatGPT desktop, Gemini Tasks, Claude Code, Codex, Antigravity, VS Code và Cursor; thêm `--write` để ghi thẳng vào tệp cấu hình. - **Mã tham chiếu và mã Python tái lập**: Mỗi kết quả lưu trong không gian làm việc cục bộ kèm mã `call_id` (`c1`, `c2`...) và ghi vào nhật ký phiên. `research_journal(method="script")` xuất các bước đã chạy thành một tệp Python độc lập. - **Công cụ nghiên cứu**: `research_normalize` chuẩn hoá bảng về cột chuẩn của Vnstock, `research_benchmark` đối chiếu số liệu, `research_universe` tra danh mục chỉ tiêu VAS. Các mô-đun `vnstock_quant` gọi được trên bảng đã chuẩn hoá qua `data="c1"`. - **Lọc công cụ theo hồ sơ và quyền**: Trợ lý AI chỉ thấy công cụ khả dụng với tài khoản và hồ sơ (`--profile`) bạn chọn. - **[Mở rộng]** **Số công cụ theo cấp**: Từ cấp Bronze mở 39 công cụ (hồ sơ `full`) hoặc 29 (hồ sơ `research`); bộ 58 chỉ báo kỹ thuật đầy đủ mở từ cấp Silver. Chi tiết ở [phân quyền và cấp quyền sử dụng](/docs/vnstock-mcp/phan-quyen-va-cap-tai-tro). ## 10-10-2026 ### vnstock_quant (v0.1.3) - **Thư viện xác thực**: Ghim `vnstock-auth` ở bản 0.5.1, thống nhất với các thư viện thế hệ 5 khác. Không đổi cách tính. ## 09-10-2026 ### vnstock_quant (v0.1.2) - **Giữ chỉ mục đầu vào**: Kết quả chỉ báo giữ nguyên chỉ mục của bảng bạn truyền vào. Cột thời gian chỉ được dùng cho `vwap` và `pivots`. - **Nhận cột thời gian**: Với bảng dữ liệu thô, thư viện tự nhận cột thời gian và chuyển thành `DatetimeIndex`. - **Gọi lớp chính gọn hơn**: Các lớp chính nhập được thẳng từ `vnstock_quant`; thông báo lỗi rõ hơn khi thiếu cột. ## 08-10-2026 ### vnstock_quant (v0.1.1) - **Hạn dùng bản phát hành**: Thư viện kiểm tra hạn dùng của bản cài trước khi tính; thông tin hạn dùng xem ở `vq.entitlement()["release"]`. - **Chú thích song ngữ**: Chú thích hàm của các mô-đun `ta`, `fa`, `risk`, `portfolio`, `valuation` có cả tiếng Việt và tiếng Anh. - **Bản hết hạn**: Bản đã hết hạn báo lỗi `VNSTOCK_RELEASE_EXPIRED` kèm lệnh cập nhật. ### vnstock_quant (v0.1.0) #### Bản phát hành đầu tiên của Vnstock Quant thế hệ 5 - **Gói cài đặt dựng sẵn**: Gói nhị phân dựng sẵn (binary wheels) dùng chung cho Python 3.10 trở lên, trên macOS (Intel và Apple Silicon) và Linux x86_64/aarch64 dùng glibc 2.17 trở lên. - **Đối chiếu chỉ báo**: Kết quả 58 chỉ báo kỹ thuật được đối chiếu với TA-Lib C 0.8.1 và QuantConnect LEAN. - **Kiểm tra tham số**: Tham số nến không hợp lệ báo lỗi `InvalidParameterError` thay vì trả kết quả sai lệch. - **Tái cấu trúc từ vnstock_ta sang vnstock_quant**: Gộp và nâng cấp thư viện `vnstock_ta` sang namespace mới `vnstock_quant` với lõi tính toán biên dịch bằng Rust (`_native.abi3.so`). - **58 chỉ báo kỹ thuật hiệu năng cao**: Tính đủ 58 chỉ báo nhanh hơn 25,9 lần so với phiên bản cũ (5.000 phiên, số đo tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026); lõi Rust nhả khoá GIL của Python trong lúc tính. - **Khắc phục lỗi thuật toán**: Sửa 16 chỉ báo bị sai lệch công thức trong phiên bản cũ (bao gồm CCI, KST, PSAR, Supertrend, Squeeze, OBV, MFI). - **Giữ cú pháp gọi hàm**: Lớp `Indicator` giữ nguyên tên 58 phương thức chỉ báo, tên và giá trị mặc định của tham số; chuyển đổi bằng cách đổi tên gói khi import. Một số chỉ báo cho số khác bản cũ, xem [danh sách khác biệt](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta). #### Mô-đun Chỉ số Tài chính (FA) và Mô hình Điểm số [Mở rộng] - **Tự tính toán 99 chỉ số tài chính**: Tự động tính chỉ số từ hệ thống BCTC chuẩn hoá VAS cho 4 loại hình doanh nghiệp: phi tài chính (`dn`), ngân hàng (`tctd`), chứng khoán (`ctck`) và bảo hiểm (`dnpnt`). - **Chuẩn hoá dòng tiền CFA**: Tích hợp công thức tính toán dòng tiền tự do doanh nghiệp (FCFF) và dòng tiền tự do chủ sở hữu (FCFE). - **Hệ thống mô hình điểm số**: Bổ sung mô hình phân rã DuPont (3 và 5 nhân tố), điểm số dự báo phá sản Altman Z''-score, điểm chất lượng kinh doanh Piotroski F-score và mô hình phát hiện gian lận Beneish M-score. - **Kiểm thử công thức**: Công thức được kiểm thử trên báo cáo tài chính dựng tay theo ví dụ của giáo trình CFA. Cách tính và cách hiệu chỉnh theo chuẩn mực kế toán Việt Nam được ghi ở tài liệu từng chỉ số, để bạn tự tính lại từ báo cáo tài chính. #### Mô-đun Đo lường Rủi ro và Hiệu suất (Risk) [Mở rộng] - **33 thước đo rủi ro chuẩn CFA**: Tích hợp các hàm tính toán Sharpe, Sortino, Treynor, Information Ratio, Alpha, Omega, Ulcer Index và các biến thể VaR / CVaR (lịch sử, phân phối chuẩn, Cornish-Fisher). - **Kiểm định đối chứng quốc tế**: Toàn bộ các thước đo được đối chiếu song song với thư viện `empyrical` và `quantstats` với sai số dấu phẩy động cực nhỏ (≤ 2e-14). - **Thước đo đặc thù cho thị trường Việt Nam**: Bổ sung hệ số đo độ kém thanh khoản Amihud (`risk.amihud`), hệ số Beta hiệu chỉnh Dimson cho cổ phiếu thanh khoản thấp (`risk.dimson_beta`) và các tỷ lệ theo dõi tần suất đứng giá / chạm biên độ trần sàn (`zero_return_ratio`, `limit_hit_ratio`). #### Giao diện gọi hàm JSON cho trợ lý AI - **[Mở rộng]** **Chuẩn hoá JSON Schema cho AI Agent**: Bổ sung hàm `portfolio.schema(name)` và `portfolio.catalog()` xuất schema tự mô tả tham số, hỗ trợ kết nối trực tiếp với các mô hình ngôn ngữ lớn (OpenAI, Claude, Antigravity) và các trợ lý tự động hoá. - **[Mở rộng]** **Thực thi hàm bằng JSON**: Giới thiệu hàm `portfolio.call(name, **kwargs)` cho phép AI kích hoạt các hàm danh mục và định giá bằng payload JSON với quy ước epoch days và phân số thập phân. - **Chẩn đoán cấp quyền và bản build**: Bổ sung hai hàm chẩn đoán chạy cục bộ `vq.entitlement()` và `vq.build_info()`, hỗ trợ theo dõi lượt dùng thử của bản Cộng đồng và kiểm tra tính toàn vẹn của lõi Rust. ## 06-10-2026 ### vnstock > Cập nhật Vnstock 4.1.1 và Vnstock 5.0.0a3 Một số nhóm dữ liệu đã được gỡ khỏi thư viện. Các hàm dưới đây không còn trả dữ liệu: * **Giá vàng trong nước:** `Retail().gold()` (cả `source="sjc"` và `source="btmc"`), `sjc_gold_price()`, `btmc_goldprice()`. Tỷ giá ngoại tệ `Retail().exchange_rate()` giữ nguyên. * **Quỹ mở:** `Fund()`, `Market().fund`, `Reference().fund` (danh sách quỹ, NAV, danh mục nắm giữ). * **Riêng Vnstock 5.0.0a3:** gỡ thêm `Fundamental().equity(...).filing()`, các chuỗi vĩ mô sản xuất công nghiệp, doanh thu bán lẻ, dân số và lao động, và lãi suất (`interest_rate()`) của nhóm vĩ mô. ## 04-10-2026 ### vnstock_data > Cập nhật phiên bản vnstock_data 3.3.1 > Khắc phục lỗi trừ sai lượt sử dụng khi mạng chập chờn và lỗi chặn kết nối khi chạy đa tiến trình. * **Bảo toàn hạn mức khi mạng chập chờn:** Khắc phục tình trạng một yêu cầu lấy dữ liệu bị hệ thống tính trừ nhiều lần vào hạn mức tài khoản khi mạng không ổn định và máy tự động gọi lại (retry). Giờ đây, mỗi lần gọi hàm chỉ tính đúng một lượt dùng dù phải thử lại bao nhiêu lần, giúp người dùng tiết kiệm số lượt gọi xác thực tài khoản. * **Chạy dữ liệu song song mượt mà hơn:** Sửa lỗi từ chối kết nối (429 Too Many Requests) khi người dùng chạy nhiều tiến trình lấy dữ liệu cùng lúc (như dùng `vnstock_pipeline`). Hệ thống đã được tối ưu cơ chế xác thực, giúp việc tải dữ liệu khối lượng lớn diễn ra trơn tru. ## 27-09-2026 ### vnstock_data > Cập nhật vnstock installer GUI v3.1.3 & CLI v3.0.3 * **Cài `vnstock` và `vnai` từ kho phát hành thư viện của Vnstock:** Trình cài lấy hai gói này từ `https://vnstocks.com/api/simple` ngay ở bước đầu và báo lỗi rõ ràng nếu không kết nối được kho phát hành. Cài lại trình cài giao diện bằng lệnh `pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.3`. * **Hiển thị đúng theo gói quyền sử dụng:** Danh sách gói hiện cả những thư viện chưa có trong gói quyền sử dụng của bạn, kèm cấp quyền sử dụng cần có (Bronze có `vnstock_data`; Silver thêm `vnstock_ta`, `vnstock_news`; Golden và Diamond thêm `vnstock_pipeline`). Lệnh kiểm tra sau khi cài chỉ gồm các gói đã cài thật. * **Chế độ dòng lệnh trên mọi hệ điều hành, kể cả Windows:** `vnstock-cli-installer --non-interactive` cài không cần mở cửa sổ, cùng tham số với bản `.run` của macOS/Linux (`--api-key`, `--venv-path`, `--language`), hợp với trợ lý AI. Xem [hướng dẫn cho Windows](/onboard-member/cai-dat-go-loi/legacy/cai-dat-nang-cao#windows). Khoá lấy từ tệp đã lưu hoặc biến `VNSTOCK_API_KEY`; thêm `--json` để nhận kết quả dạng máy đọc được. * **Sửa lỗi:** gói đã bỏ chọn vẫn bị cài; lần cài đầu trong môi trường ảo mới báo lỗi nhầm dù gói đã cài xong; trên Windows không tìm thấy `uv` khi thư mục `Scripts` không nằm trong PATH. ## 26-09-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.9 Bản này tập trung vào bảo mật và trả lại quyền kiểm soát cho bạn khi dùng Vnstock cùng trợ lý AI. Cần `vnai` 2.6.2 trở lên, nên hãy cập nhật cả hai gói: ```bash pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai ``` **Bảo mật** * **`import vnstock` không còn tự ghi tệp nào.** Ở các bản trước, mỗi lần `import vnstock`, thư viện tự chèn một đoạn hướng dẫn vào tệp quy tắc của trợ lý AI: `AGENTS.md` trong dự án và mặc định cả tệp dùng chung toàn máy của Claude Code, Codex, Antigravity. Nội dung đoạn này tải từ vnstocks.com lúc ghi, nên có thể thay đổi mà bạn không hề hay biết, và bạn cũng chưa từng yêu cầu. Từ bản này: * Tính năng chỉ chạy khi bạn chủ động bật: `enable_agent()` rồi `setup_agent()`. * Mặc định chỉ ghi vào `AGENTS.md` của dự án; tệp toàn cục chỉ được ghi khi bạn chỉ định. * Nội dung được đóng gói sẵn trong `vnai`, không tải từ máy chủ nữa. * Nếu máy còn đoạn cũ do bản trước để lại, thư viện chỉ in một thông báo một lần, không tự sửa gì. Muốn gỡ sạch, chạy `vnstock.remove_agent_files("all")`. * **Tài liệu chủ đề ghi rõ nguồn gốc.** Nội dung trả về từ `load_skill()` mở đầu bằng dòng cho biết đây là tài liệu tải về và tải từ đâu. Tên chủ đề chỉ nhận dạng tên đơn giản, để trợ lý AI không thể dẫn lượt gọi mang API key của bạn tới địa chỉ khác. Bỏ lớp "mã hoá" XOR cho tài liệu người dùng gói quyền sử dụng: nó không bảo vệ được gì mà chỉ khiến bạn khó kiểm tra trợ lý AI đang đọc gì. * **Quảng cáo không thể chạy mã.** Nội dung quảng bá hiển thị trong Jupyter được lọc bỏ script, frame, trình xử lý sự kiện và liên kết `javascript:`; văn bản trong terminal được lọc ký tự điều khiển. Khi đầu ra đang bị ghi lại (ví dụ trợ lý AI chạy lệnh), thư viện chỉ hiện nội dung đóng gói sẵn, không hiện nội dung từ máy chủ. * **`register_user()` nhập API key ở chế độ ẩn**, không còn hiện key trên màn hình hay lưu lại trong đầu ra của notebook. Nếu biến môi trường `VNSTOCK_API_KEY` đã có, hàm đề nghị lưu luôn key đó. Truyền key trực tiếp làm tham số vẫn chạy nhưng không khuyến khích. **Thay đổi khác** * Chú thích trong mã từng viết riêng cho trợ lý AI nay là tài liệu lập trình thông thường; `migrate_to_sponsor()` cũng thôi in dòng nhắn gửi "AI Agent". * `migrate_to_sponsor(dry_run=True)` liệt kê những thay đổi sẽ thực hiện mà không ghi tệp, và hàm trả về số tệp đã đổi. * `setup_agent()` chạy trực tiếp thay vì chạy nền, tránh trường hợp hai tiến trình cùng ghi làm lặp đoạn hướng dẫn. Tham số `async_mode` vẫn nhận nhưng không còn tác dụng. * `register_user()` không còn in nhầm "bạn đang dùng bản Cộng đồng" sau khi lưu key của người dùng gói quyền sử dụng. * README cập nhật lệnh cài từ kho phát hành thư viện của Vnstock và mô tả cơ chế bật/tắt hướng dẫn cho trợ lý AI. ## 25-09-2026 ### vnstock > Đổi lệnh cài đặt `vnstock` và `vnai` Từ phiên bản này, hai gói `vnstock` và `vnai` được cài từ kho phát hành thư viện của Vnstock. Lệnh cài và lệnh cập nhật cho bản Cộng đồng: ```bash pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai ``` * Lệnh cũ `pip install -U vnstock` sẽ báo `Could not find a version that satisfies the requirement vnai`. Thêm phần `--extra-index-url` như trên là cài được. * Phần `--extra-index-url` chỉ bổ sung thêm một nơi tìm gói; các thư viện khác như `pandas` vẫn tải từ PyPI như cũ. * Nhà tài trợ không cần làm gì thêm: trình cài `vnstock-installer` và trình cài dòng lệnh vốn đã dùng kho phát hành này. Khi cài lại trình cài giao diện, ghim đúng phiên bản: `pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.2`. * Nhờ trợ lý AI cài hộ thì dẫn nó tới `vnstocks.com/files/vibe-onboarding.md`. Tệp hướng dẫn này đã có sẵn các bước cài đặt và cập nhật mới. ## 23-09-2026 ### vnstock_data > Phát hành phiên bản v3.3.1 khắc phục lỗi cài đặt từ PyPI và tình trạng chương trình đứng hàng phút khi nguồn dữ liệu ngừng phản hồi. * **Cài đặt từ PyPI dùng được ngay:** Bản v3.3.0 không khai báo ràng buộc `vnstock` 4.0.8 nên máy có sẵn bản cũ hơn gặp lỗi `ImportError` ngay ở dòng `import vnstock_data`. Nay trình cài đặt tự nâng đúng bản. * **Không còn chờ vô ích khi máy chủ im lặng:** Một lượt gọi tới endpoint không phản hồi trước đây ngốn hơn hai phút do thư viện tự thử lại ngầm, nay dừng sau 30 giây. Bước mở kết nối tách riêng với hạn mức 10 giây nên nguồn không truy cập được bị loại nhanh hơn hẳn. * **Tự tạm ngừng khi một nguồn liên tục không phản hồi:** Sau 3 lượt liên tiếp không nhận được hồi đáp từ cùng một máy chủ, thư viện tạm ngừng gọi tới đó 60 giây và báo lỗi tức thì, thay vì để chương trình treo hàng giờ và tiếp tục gửi yêu cầu tới máy chủ đang không phản hồi. Dùng `reset_circuit()` nếu muốn thử lại ngay. * **Thông báo lỗi mạng nói đúng nguyên nhân:** Trước đây mọi sự cố đều hiện cùng một câu "Không mở được kết nối tới máy chủ dữ liệu". Nay phân biệt rõ máy chủ nhận yêu cầu nhưng không trả kết quả, không phân giải được tên miền, hết giờ chờ khi mở kết nối, hay chứng chỉ bảo mật không hợp lệ, mỗi trường hợp kèm hướng xử lý riêng. * **Bộ lọc cổ phiếu cần ít lượt gọi hơn:** `Insights().screener.filter()` nay lấy 500 mã mỗi lượt thay vì 50, giảm số lượt gọi tới nguồn cho cùng một bộ lọc. Kết quả không còn bị cắt giữa chừng, và một bộ lọc không hợp lệ trả về rỗng thay vì làm chương trình dừng đột ngột. * **Sửa lỗi phản hồi không đọc được:** Thư viện từng khai báo chấp nhận những định dạng nén mà nó không giải nén được, khiến một số phản hồi trở về dạng thô không đọc được mà không báo lỗi gì. Nay thư viện chỉ khai báo những định dạng nó thực sự xử lý được. * **KBS và MBK dùng chung hạ tầng truy xuất:** Hai nguồn này nay cũng được hưởng cơ chế gộp kết nối, tự thử lại khi lỗi mạng và dừng gọi khi nguồn từ chối như các nguồn còn lại. ## 15-09-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.8 **Tính năng chính: tôn trọng tín hiệu từ chối của nguồn** * **Dừng gọi khi nguồn từ chối, tạm ngừng theo từng máy chủ.** Khi nguồn từ chối lượt gọi hoặc báo giới hạn tần suất, thư viện nay **dừng ngay thay vì thử lại**, để không tạo thêm tải lên hệ thống của nguồn. Sau đó thư viện tạm ngừng gọi tới chính máy chủ đó trong một khoảng thời gian; các lượt gọi trong khoảng này báo lỗi ngay mà không mở kết nối. * **Thời gian tạm ngừng mặc định**: 60 giây khi bị giới hạn tần suất, 300 giây khi nguồn yêu cầu xác minh hoặc từ chối truy cập. Nếu máy chủ có nói rõ cần chờ bao lâu thì thư viện tôn trọng con số đó. Thời gian chờ chỉnh được qua `Config`; `reset_circuit()` xoá trạng thái tạm ngừng. * **Nhóm lỗi mới để bắt đúng tình huống**: `DataSourceBlockedError` cùng các lỗi cụ thể `RateLimitedError`, `ChallengeRequiredError`, `AccessDeniedError`, `CircuitOpenError`. Mỗi lỗi mang theo địa chỉ, máy chủ, mã trạng thái và thời gian chờ còn lại. Code cũ bắt `except ConnectionError` vẫn hoạt động bình thường. * **Chỉ thử lại những lỗi thật sự thoáng qua.** Lỗi mạng chập chờn được thử lại; lỗi do nguồn từ chối, tham số sai hay phương thức không được hỗ trợ thì hiện ra ngay với đúng thông báo gốc, thay vì bị nuốt sau nhiều lần thử vô ích. **Thay đổi cần lưu ý** * **Loại bỏ cấu hình proxy**: Gỡ bỏ các tham số `proxy_config`, `proxy_mode` và `proxy_list` khỏi constructor của `Quote`, `Trading`, `Finance`, `Listing`, `Company` ở cả nguồn KBS và VCI, cùng các tiện ích proxy đi kèm. **Code truyền các tham số này sẽ báo lỗi `TypeError`** — hãy bỏ chúng đi. * **Ngừng hỗ trợ `random_agent`**: Tham số này không còn tác dụng (sẽ hiện cảnh báo nếu dùng); hãy bỏ nó khỏi mã của bạn. * **`RateLimitError` nay là tên gọi khác của `RateLimitedError`**: `except RateLimitError` vẫn chạy, nhưng lỗi này đã chuyển sang nhóm "bị nguồn từ chối" nên không còn được tự động thử lại. Lớp cũ chưa từng được ném ra ở đâu nên không có đoạn mã nào đổi hành vi. **Cải thiện** * Đơn giản hoá tầng gửi yêu cầu trong `vnstock.core.utils.client`, giảm số nhánh xử lý và giúp thông báo lỗi dễ đọc hơn. * **Bật/tắt được phần tự tạo tệp hướng dẫn cho AI**: bổ sung `agent_status()`, `disable_agent()`, `enable_agent()` và `remove_agent_files()` vào API công khai. Thư viện chỉ ghi `AGENTS.md` trong dự án và tệp ghi nhớ toàn cục của ba công cụ được hỗ trợ; các đường dẫn cũ không còn được ghi và `remove_agent_files("legacy")` dọn sạch máy đã lỡ nhận chúng. * **`except VnstockError` nay bắt được mọi lỗi của thư viện.** Nhóm lỗi nguồn từ chối trước đó nằm ngoài cây `VnstockError` nên ai dùng cách bắt này sẽ bỏ lọt đúng nhóm lỗi cần xử lý nhất. **Tài liệu & giấy phép** * Làm rõ điều kiện giấy phép trong README: bản công khai mã nguồn trên GitHub theo giấy phép riêng, miễn phí cho mục đích cá nhân, học tập và nghiên cứu. Đây không phải giấy phép nguồn mở theo chuẩn OSI; phân phối lại và mục đích thương mại cần văn bản chấp thuận từ tác giả. * Bổ sung phần miễn trừ trách nhiệm và điều kiện giấy phép cho bản tiếng Anh của README, trước đây chỉ có ở phần tiếng Việt. * Bổ sung tuyên bố Vnstock không liên kết, không được tài trợ hay chứng thực bởi bất kỳ tổ chức nào được nhắc tới trong tài liệu và mã nguồn. Vnstock cấp quyền sử dụng phần mềm, không cấp quyền sử dụng dữ liệu; điều kiện của từng nguồn do bạn tự kiểm tra và tuân thủ. * Bổ sung ghi chú về dữ liệu ẩn danh của môi trường chạy được ghi nhận nhằm cải thiện hiệu năng và độ ổn định. ### vnstock_data > Phát hành phiên bản v3.3.0 đưa API Báo cáo tài chính trở lại đúng chuẩn v3.2.8 và khắc phục các sai lệch của dữ liệu khớp lệnh nhóm phái sinh. * **API Báo cáo tài chính trở lại đúng chuẩn v3.2.8:** Phiên bản v3.2.9 đã vô tình quay ngược về thiết kế cũ của v3.2.7, làm mất bộ tham số đã công bố ở v3.2.8. Nay toàn bộ bộ tham số chuẩn được khôi phục: `com_type` để chỉ định loại hình công ty, `drop_empty` để lược bỏ chỉ tiêu rỗng, `format` để chọn cấu trúc trả về (`'long'`, `'wide'`, `'time_series'`), và `lang` mặc định là tiếng Việt. Nếu bạn đã chỉnh mã nguồn theo v3.2.9, hãy đọc kỹ cảnh báo cuối mục này. * **Nến trong phiên lấy trọn phần lịch sử nguồn còn giữ:** Với các khung `1m`, `5m`, `15m`, `30m` và `1H`, chỉ cần không nêu khoảng thời gian là thư viện lấy tối đa những gì nguồn còn lưu — khoảng ba năm, lùi tới 09/2023: ```python Market().futures('VN30F1M').ohlcv(interval='1m') # 180.264 nến, từ 11-09-2023 Market().equity('ACB').ohlcv(interval='1m') # 165.745 nến, từ 11-09-2023 ``` Trước đây các lệnh gọi này chỉ lấy được một phần rất nhỏ: nguồn mặc định chỉ trả tối đa khoảng 18.000 nến một phút (gần 4 tháng) bất kể khoảng ngày yêu cầu, còn mã phái sinh thì bị quy đổi sang hợp đồng tháng cụ thể nên chuỗi bị cắt về đúng ngày hợp đồng đó niêm yết. Nay hàm lấy dữ liệu trong phiên tự chuyển sang nguồn có độ sâu lớn nhất và giữ nguyên mã bạn nhập. Khung `1D` trở lên không đổi. * **Khôi phục dữ liệu khớp lệnh của hợp đồng tương lai:** Ở v3.2.9, gọi dữ liệu khớp lệnh cho `VN30F1M` trả về kết quả rỗng. Nguyên nhân là nguồn dữ liệu chỉ chấp nhận mã hợp đồng theo quy ước mới cho nhóm hàm này. Nay thư viện tự quy đổi đúng chỗ cần quy đổi và giữ nguyên mã ở chỗ không cần. * **Sửa sai đơn vị giá khớp lệnh phái sinh:** Giá từng lệnh khớp của hợp đồng tương lai bị chia cho 1.000, trả về `1.9478` thay vì `1947.8`. Quy tắc quy đổi đơn vị nay thống nhất giữa dữ liệu nến và dữ liệu khớp lệnh: chỉ số và phái sinh yết bằng điểm nên giữ nguyên, chỉ cổ phiếu mới quy về nghìn đồng.

Phiên bản này có hai thay đổi phá vỡ tương thích:

## 06-09-2026 ### vnstock_data > Phát hành 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 (`trades`/`intraday`), đặc biệt với nhóm phái sinh. * **Khối lượng khớp lệnh trở về đúng thực tế:** Khắc phục tình trạng tổng khối lượng bị gấp đôi so với số liệu sở công bố. * **Nhãn ATO/ATC chính xác hơn:** Nhận diện đúng phiên ATO 08:45–09:00 của hợp đồng tương lai, đồng thời không còn gán nhầm nhãn cho các lệnh khớp liên tục. Bổ sung nhãn `PLO` cho mã sàn HNX. * **Sửa lỗi giá và thời gian ở nguồn MAS:** Khắc phục tình trạng chỉ trả về vài chục dòng, sai đơn vị giá và mốc thời gian nhảy về năm 1970. * **Mặc định lấy trọn phiên cho phái sinh:** Nâng giới hạn mặc định lên 100.000 bản ghi để phủ hết phiên, thay vì 1.000 bản ghi chỉ đủ chạm cụm ATC cuối phiên. Thư viện cũng tự cảnh báo khi dữ liệu trả về chưa phủ hết phiên. * **Thêm nguồn khớp lệnh VND:** Hỗ trợ cả cổ phiếu, chứng quyền và hợp đồng tương lai, cấu trúc dữ liệu đồng nhất với các nguồn còn lại. * **Gọi mã phái sinh kiểu cũ vẫn ra dữ liệu:** Các mã như `VN30F1M` được tự động chuyển sang mã KRX ở mọi lớp truy xuất. Bổ sung `Market().future(...)` bên cạnh `Market().futures(...)`. * **Lưu ý về nguồn VCI:** Nhà cung cấp đã áp giới hạn 100 bản ghi mỗi lượt gọi cho dữ liệu khớp lệnh, nên lấy cả phiên từ VCI sẽ cần rất nhiều lượt gọi. Nếu cần dữ liệu cả phiên, hãy chọn nguồn trả đủ phiên trong ít lượt gọi hơn như KBS, MAS hoặc VND. * **Khôi phục cây API `show_api()`:** Cây hiển thị đầy đủ mọi nhóm tài sản kèm nguồn dữ liệu và mô tả chức năng của từng hàm.
Phiên bản này đổi nguồn mặc định của dữ liệu khớp lệnh cổ phiếu và làm số liệu khối lượng khác đi so với bản cũ. Xem hướng dẫn nâng cấp v3.2.9 để biết cần chỉnh gì.
## 16-08-2026 ### vnstock_data > Phát hành phiên bản v3.2.8 nâng cấp nhóm hàm Báo cáo tài chính, chuẩn hoá cấu trúc chỉ tiêu theo chuẩn mực kế toán VAS. * **Đồng nhất API Báo cáo tài chính (Finance):** Tất cả các nguồn cấp dữ liệu (VCI, MAS, KBS) giờ đây đã được đồng nhất về cùng một định dạng chuẩn **Tidy Data (Long-form)**, giúp loại bỏ hoàn toàn sự thiếu nhất quán giữa các nguồn. * **Chuẩn hoá mã định danh (Semantic ID):** Áp dụng bộ Taxonomy ID chuẩn mực (ví dụ: `BS_CASH_AND_PRECIOUS_METALS`) làm khoá chính, giúp mã nguồn phân tích định lượng không bị gãy sụp đổ khi tên hiển thị của chỉ tiêu thay đổi. * **Hệ thống tham số mới mạnh mẽ:** * Thay thế tham số `dropna` bằng `drop_empty`. * Hỗ trợ tuỳ chỉnh linh hoạt cấu trúc dữ liệu trả về thông qua tham số `format` (`'long'`, `'wide'`, `'time_series'`). * Thêm tham số `com_type` giúp hệ thống bóc tách chính xác báo cáo dựa trên loại hình công ty (`Regular`, `Bank`, `Securities`, `Insurance`) khi cơ chế nhận diện tự động không thành công. * **Nâng cấp tài liệu & Hướng dẫn (Migration):** Cung cấp bảng tham chiếu chi tiết và [tài liệu hướng dẫn nâng cấp](/docs/vnstock/nang-cap-phien-ban/v3.2.8) mã nguồn dành riêng cho các thay đổi của phiên bản cập nhật này. ## 03-08-2026 ### vnstock_data > Phát hành phiên bản v3.2.7 tập trung vào nâng cấp trải nghiệm truy xuất dữ liệu & vá lỗi * **Khắc phục lỗi tham số kỳ báo cáo cho Finance module - nguồn VCI**: Xử lý triệt để tình trạng dữ liệu báo cáo tài chính bị trộn lẫn. Hiện tại, khi gọi `Finance(..., period='year').balance_sheet()`, kết quả trả về sẽ hoàn toàn chuẩn xác theo cột năm (tránh lẫn với dữ liệu quý), giúp việc phân tích chuỗi thời gian liền mạch. * **Tự động phân trang ở Trading module - nguồn CafeF**: Nguồn CafeF trả 20 bản ghi mỗi trang. Các hàm (lịch sử giá, giao dịch khối ngoại, tự doanh, thống kê cung cầu...) nay tự gọi các trang kế tiếp để trả về đủ số bản ghi `limit` bạn yêu cầu. Mỗi trang là một lượt gọi tới nguồn, nên hãy đặt `limit` vừa đủ nhu cầu. * **Khắc phục lỗi cắt xén dữ liệu từ Trading module - nguồn VCI**: Xử lý tình trạng dữ liệu bị cắt cụt âm thầm (chỉ trả về ~100 dòng) khi gọi chuỗi thời gian dài. Giờ đây, khi bạn truyền khoảng ngày `start` và `end`, thư viện tự chia thành các lượt gọi theo giới hạn mỗi lượt của nguồn để dữ liệu không bị cắt cụt. Khoảng ngày càng dài thì càng nhiều lượt gọi, nên chỉ lấy khoảng bạn thật sự cần. ## 01-08-2026 ### vnstock_pipeline > Phát hành `vnstock_pipeline` phiên bản 2.3.2 - Hỗ trợ trích xuất và cập nhật dữ liệu trực tiếp sang phần mềm AmiBroker trên máy tính Windows. **Tính Năng Nổi Bật** - **Cập Nhật Dữ Liệu AmiBroker Trực Tiếp**: Xuất và nạp dữ liệu giá (đã điều chỉnh và chưa điều chỉnh), chỉ số thị trường, cùng dữ liệu giao dịch Khối ngoại & Tự doanh trực tiếp vào phần mềm AmiBroker đang mở trên máy tính qua OLE. - **Chế Độ Cập Nhật Liên Tục (Chạy Ngầm)**: Theo dõi và nạp thêm dữ liệu mới nhất vào AmiBroker theo khoảng thời gian bạn cài đặt mà không cần thao tác tệp thủ công. - **Thêm Các Câu Lệnh Tiện Ích**: Cung cấp các câu lệnh dễ dùng để thiết lập xuất dữ liệu và điều phối các nhóm tác vụ định kỳ. **Cải Tiến Hệ Thống** - **Quản Lý Cài Đặt Tập Trung**: Sử dụng một file cấu hình duy nhất (`pipeline.toml`) để thiết lập nơi lưu trữ, định dạng file mặc định (ví dụ: `.csv`, `.parquet`) một cách dễ dàng. - **Hoạt Động Ổn Định Hơn**: Cải thiện độ ổn định và tính an toàn khi cập nhật dữ liệu cho danh sách mã dài, hệ thống tự tạo sẵn các thư mục cần thiết và xử lý mượt mà hơn khi phát sinh lỗi kết nối. ## 22-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.6 giúp sửa lỗi và tối ưu hoá mã nguồn. * **Sửa lỗi trích xuất thuyết minh báo cáo tài chính (Nguồn VCI):** Cập nhật lại cấu trúc hàm trích xuất thuyết minh báo cáo tài chính để hàm hoạt động ổn định và trả về dữ liệu đầy đủ thay vì kết quả rỗng. ## 18-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.5 mang đến cho bạn nhiều lựa chọn dữ liệu hơn và nâng cao độ ổn định của hệ thống. * **Thêm nguồn dữ liệu giao dịch mới:** Tích hợp thêm nguồn `asean` và `mbk` giúp bạn có thêm các lựa chọn đáng tin cậy khi phân tích dữ liệu lịch sử giao dịch. * **Mở rộng tra cứu thông tin doanh nghiệp:** Bổ sung tính năng lấy dữ liệu thông tin niêm yết từ nguồn CafeF giúp bạn dễ dàng theo dõi các thông tin quan trọng của doanh nghiệp. * **Trải nghiệm mượt mà hơn với nguồn ASEAN:** Khắc phục hoàn toàn tình trạng lỗi kết nối khi lấy dữ liệu các nhóm hàm Insight, Sector và Trading từ nguồn ASEAN. ## 16-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.4 giúp quá trình truy xuất dữ liệu báo cáo tài chính từ nguồn KBS ổn định. * **Dữ liệu tài chính ổn định hơn:** Hệ thống giờ đây có khả năng tự động xử lý và phục hồi (fallback) khi nguồn KBS thay đổi định dạng, giảm gián đoạn khi bạn truy xuất báo cáo tài chính. ## 28-06-2026 ### vnstock_news > Phát hành `vnstock_data` phiên bản 3.2.3 hoàn thiện cấu trúc tin tức của công ty niêm yết và chuẩn hoá mô hình dữ liệu. - **Chuẩn hoá mô hình dữ liệu (Unified Schema) cho Tin tức doanh nghiệp:** Giao diện `Reference().company('MÃ_CK').news()` được chuẩn hoá hoàn toàn trên 3 nguồn `vci`, `kbs`, và `cafef` với chung 10 cột dữ liệu thống nhất (`id`, `symbol`, `title`, `summary`, `content`, `publish_time`, `source`, `url`, `category`, `image_url`). - **Nâng cấp tính năng lấy tin tức chi tiết:** Bổ sung tham số `mode='detail'` cho phép đọc nội dung chi tiết bài viết và bóc tách các link đính kèm trực tiếp từ `vci` và `cafef`. - **Hỗ trợ tuỳ chỉnh tham số linh hoạt:** Chuẩn hoá các tham số bộ lọc thời gian (`start`, `end`, `length`, `limit`) và nâng cấp khả năng truyền linh hoạt `**kwargs` xuống hàm của từng nguồn. ## 20-06-2026 ### vnstock_pipeline > Phát hành `vnstock_pipeline` phiên bản 2.3.1 cấu trúc lại toàn bộ kiến trúc lưu trữ dữ liệu, giới thiệu file cấu hình tập trung `pipeline.toml` và cải tiến mạnh mẽ CLI hỗ trợ quản trị cơ sở dữ liệu chứng khoán hiệu quả. **Thay Đổi Mang Tính Phá Vỡ** - **Gỡ bỏ `DuckDBProcessor` & `FirebaseProcessor`**: Cấu trúc mới tập trung gom dữ liệu thô lưu trữ định dạng Parquet/CSV hiệu suất cao. Người dùng tự quản lý Data Warehouse (DuckDB/Supabase) theo nhu cầu. Thay đổi này ít tác động tới người dùng vì cách dùng này không được giới thiệu chính thức. - **Quản lý tập trung tham số `base_path`**: Không cần truyền `base_path` khi khởi tạo `Exporter` trong các pipeline tùy biến; đường dẫn được đọc trực tiếp từ cấu hình tập trung. - **Công cụ di chuyển dữ liệu cũ**: Bổ sung lệnh CLI `python -m vnstock_pipeline.cli storage migrate-legacy` hỗ trợ người dùng chuyển đổi thư mục dữ liệu cũ sang cấu trúc phân lớp tập trung mới một cách an toàn. **Tính Năng Nổi Bật** - **Kiến Trúc Lưu Trữ Tập Trung (`pipeline.toml`)**: Quản lý thiết lập đường dẫn (`base_path`), chế độ lưu mặc định (`parquet`/`csv`/`excel`) và cơ chế ghi đè định dạng (`format_overrides`) cho từng nhóm dữ liệu ngay tại `~/.vnstock/config/pipeline.toml`. - **Linh Hoạt 2 Chế Độ Phân Cấp Thư Mục**: - **Flat Layout (Mặc định)**: Thân thiện cho người dùng cá nhân (ví dụ: `~/stock_db/ohlcv/ACB.parquet`). - **Nested Layout**: Phân cấp chuẩn mực (`[layer]/[domain]/...`), tối ưu cho người dùng chuyên sâu và AI Agent. - **Bảo Vệ An Toàn Cấu Trúc Dữ Liệu**: So sánh dữ liệu mới tải với cấu trúc chuẩn (`Baseline Schema`). Cách ly an toàn các file lỗi hoặc thay đổi cấu trúc nghiêm trọng vào `.tmp/.quarantine/` nhằm bảo vệ CSDL chính. - **Xử Lý Lỗi & Khôi Phục Thông Minh**: Ghi nhận file `error_log.csv` cho các mã lỗi do rớt mạng hoặc thiếu dữ liệu. Cung cấp cờ `--retry-errors` để tải bù đúng những mã thất bại thay vì chạy lại từ đầu. - **Công Cụ Quản Trị Bằng Dòng Lệnh (CLI)**: Cung cấp nhiều lệnh mới tiện dụng như kiểm toán CSDL (`storage audit`), đổi định dạng (`set-format`), dọn rác định kỳ (`cleanup`), trích xuất cấu trúc nhanh (`storage preview`). - **Khởi Tạo Rổ Thanh Khoản (Universe)**: Lệnh `universe build-liquidity` giúp xếp hạng tính thanh khoản các cổ phiếu qua đa khung thời gian để sinh ra tệp theo dõi lưu mặc định vào cấu hình `liquidity_auto`. - **Template Pipeline Tích Hợp Sẵn**: Hỗ trợ các tác vụ như gom 5 bảng báo cáo tài chính vào Multi-sheet Excel, tải tin tức thị trường có lọc trùng lặp qua bộ đệm Streaming, và cập nhật sự kiện doanh nghiệp liền mạch. - **Trích Xuất Chuẩn Amibroker**: Tích hợp module DuckDB tại chỗ, xuất nhanh toàn bộ dữ liệu ra định dạng `.csv` chuẩn tương thích Amibroker bằng một dòng lệnh. ## 24-05-2026 ### vnstock_data > Phát hành vnstock_data phiên bản 3.2.0 và cập nhật đồng loạt các thư viện trong gói sponsor với những tinh chỉnh nhỏ giúp tăng tính ổn định của hệ thống. * **Kết nối dữ liệu ASEAN (Unified UI)**: * Tích hợp luồng dữ liệu từ trung tâm phân tích của Asean Securities, mở rộng mạnh mẽ năng lực phân tích và giúp người dùng tiếp cận dữ liệu với góc nhìn đa chiều: * **Insights**: Cung cấp bộ công cụ chuyên sâu đo lường tâm lý thị trường (`sentiment`: breadth, heatmap, contribution), theo vết dòng tiền (`flow`: foreign, proprietary, active). Đào sâu phân tích cấp độ Ngành (`sector`) và Cổ phiếu (`equity`) thông qua biểu đồ Relative Rotation Graph (`rrg`), định giá (`valuation`), so sánh ngang hàng (`peer_compare`), và phân tích dòng lệnh (`order_flow`). * **Vĩ mô & Hàng hoá (Macro)**: Thay thế lõi truy xuất dữ liệu Vĩ mô (Kinh tế, Tiền tệ) sang nguồn ASEAN. Bổ sung truy xuất các chỉ số toàn cầu như Lợi suất trái phiếu (`bond_yield`), Lãi suất Fed (`fed_rate`), và các rổ hàng hoá phái sinh chuẩn quốc tế trực tiếp qua `Macro().global` và `Macro().commodity()`. * **Tương thích & Ổn định**: * Khi người dùng truy xuất các hàng hoá đặc thù của Việt Nam (VD: Vàng SJC, Thép D10, Lợn Hơi) qua tham số `market="VN"`, hệ thống tự động fallback mượt mà về nguồn SPL cũ, đảm bảo không bị gián đoạn trải nghiệm phân tích số liệu cục bộ. * **Trải nghiệm Phát triển**: Toàn bộ các endpoints mới được dán nhãn `[Experimental]` khi gọi lệnh `show_api()`, giúp các nhà phân tích phân biệt và nắm bắt nhanh chóng kho công cụ mới này. **Chi tiết cấu trúc API Tree (Các hàm mới & nâng cấp):** ```bash ├── Insights │ ├── equity() │ │ ├── order_flow() -> DataFrame # Phân bổ dòng tiền chủ động │ │ ├── order_flow_history() -> DataFrame # Lịch sử giao dịch & dòng lệnh │ │ ├── peer_compare() -> DataFrame # So sánh với các mã cùng ngành │ │ └── rrg() -> DataFrame # Sức mạnh tương đối (RRG) │ ├── flow │ │ ├── active() -> DataFrame # Dòng tiền chủ động mua/bán │ │ ├── foreign() -> DataFrame # Giao dịch khối ngoại (FII) │ │ └── proprietary() -> DataFrame # Giao dịch tự doanh │ ├── sector() │ │ ├── flow() -> DataFrame # Dòng tiền tổng hợp toàn ngành │ │ ├── flow_intraday() -> DataFrame # Dòng tiền ngành trong ngày │ │ ├── index_intraday() -> DataFrame # Chỉ số ngành trong ngày │ │ ├── members() -> DataFrame # Chỉ số tài chính của các mã trong ngành │ │ ├── rrg() -> DataFrame # Sức mạnh tương đối ngành (RRG) │ │ └── valuation() -> DataFrame # Tỷ số định giá ngành │ └── sentiment │ ├── breadth() -> DataFrame # Độ rộng thị trường │ ├── contribution() -> DataFrame # Top đóng góp điểm số │ └── heatmap() -> DataFrame # Bản đồ nhiệt toàn thị trường └── Macro ├── commodity() │ ├── coke() -> DataFrame # Giá Hợp đồng tương lai Than Cốc │ ├── corn() -> DataFrame # Giá Ngô Mỹ │ ├── gas() -> DataFrame # Khí tự nhiên / Xăng dầu VN │ ├── gold() -> DataFrame # Vàng thế giới / Vàng SJC │ ├── iron_ore() -> DataFrame # Quặng sắt Trung Quốc │ ├── listing() -> DataFrame # Danh sách hàng hoá hỗ trợ │ ├── oil_crude() -> DataFrame # Dầu thô WTI │ ├── pork() -> DataFrame # Giá Lợn Hơi VN / TQ │ ├── related_industry() -> DataFrame # Nhóm ngành liên quan Hàng hoá │ ├── related_stock() -> DataFrame # Nhóm cổ phiếu liên quan Hàng hoá │ ├── soybean() -> DataFrame # Giá Đậu nành Mỹ │ ├── steel() -> DataFrame # Thép HRC thế giới / Thép D10 VN │ └── sugar() -> DataFrame # Giá Đường London ├── currency() │ ├── deposit_rate() -> DataFrame # Lãi suất huy động │ ├── exchange_rate() -> DataFrame # Tỷ giá trung tâm │ ├── interbank_rate() -> DataFrame # Lãi suất liên ngân hàng │ ├── omo() -> DataFrame # Nghiệp vụ thị trường mở (OMO) │ └── policy_rate() -> DataFrame # Lãi suất điều hành ├── economy() │ ├── cpi() -> DataFrame # Chỉ số giá tiêu dùng (CPI) │ ├── credit() -> DataFrame # Tăng trưởng tín dụng │ ├── fdi() -> DataFrame # Vốn đầu tư trực tiếp nước ngoài │ ├── gdp() -> DataFrame # Tổng sản phẩm quốc nội (GDP) │ ├── import_export() -> DataFrame # Xuất nhập khẩu │ ├── money_supply() -> DataFrame # Cung tiền M2 │ ├── state_budget() -> DataFrame # Thu ngân sách nhà nước │ └── total_investment() -> DataFrame # Tổng vốn đầu tư └── global ├── bond_yield() -> DataFrame # Lợi suất TPCP (VN / Mỹ) ├── fed_rate() -> DataFrame # Lãi suất Fed └── index() -> DataFrame # Các chỉ số thế giới (DXY, SPX...) ``` ## 19-05-2026 ### vnstock_pipeline > Cập nhật và sửa lỗi cho vnstock_pipeline phiên bản 2.2.3 - **Sửa `ceiling_price`**: Khắc phục lỗi cột giá trần (`ceiling_price`) bị gắn sai giá trị các cờ màu sắc (như `e`, `d`) do nhầm lẫn ánh xạ với một trường mã màu trong dữ liệu gốc. - **Thêm thông tin giá**: Tách và trích xuất chính xác giá trị số cho giá trần (`ceiling_actual`), giá sàn (`floor_price`), và giá tham chiếu (`reference_price`) cho cả cổ phiếu cơ sở và phái sinh. - **Sửa `market_id` cho Phái sinh**: Chuẩn hóa sàn giao dịch thành `HNX` cho dữ liệu hợp đồng tương lai phái sinh (`stockps`). ## 18-05-2026 ### vnstock_pipeline > Phiên bản vnstock_pipeline 2.2.2 mang đến nhiều nâng cấp quan trọng giúp bạn xây dựng hệ thống quản lý tải dữ liệu và kết nối dữ liệu trong phiên qua WebSocket gọn và dễ dùng hơn. Các cập nhật mới nhất giúp cải thiện độ tương thích của các thư viện trong hệ sinh thái Vnstock với chuẩn Unified UI mới nhất. #### Cảnh báo chỉ báo & Dữ liệu trong phiên Hệ thống luồng dữ liệu được tối ưu hoá với `redis`, cung cấp sẵn các kịch bản thường dùng để theo dõi chỉ báo, giúp bạn: - **Nhận cảnh báo:** Phát hiện các điều kiện chỉ báo (giao cắt MACD, quá mua/quá bán RSI, đột biến dòng tiền...) và gửi cảnh báo về kênh Discord của bạn qua Webhook. - **Tự kết nối lại:** Thuật toán kết nối mới giúp hệ thống ổn định hơn và tự kết nối lại khi rớt mạng. #### Xem nhanh dữ liệu không cần mở trình soạn thảo Công cụ dòng lệnh tích hợp mới (`vnstock_pipeline`) giúp bạn tiết kiệm thời gian: - Xem nhanh tổng quan, dung lượng và cấu trúc của bất kỳ tệp dữ liệu chứng khoán nào chỉ với các lệnh CLI đơn giản mà AI Agent có thể sử dụng như một công cụ. - Lọc, tìm kiếm (ví dụ: lọc các mã có giá > 50) và xem thống kê dữ liệu ngay trên cửa sổ lệnh mà không cần phải khởi động các phần mềm phân tích nặng nề. #### Quản lý chất lượng & độ toàn vẹn dữ liệu - **Kiểm định chất lượng:** Hệ thống kiểm tra, phát hiện và cảnh báo các khoảng trống hoặc lỗi bất thường trước khi lưu trữ. - **Trực quan & Dễ tích hợp:** Toàn bộ tên mã chứng khoán và định dạng báo cáo tài chính đều được chuẩn hóa thống nhất, dễ đọc và dễ dàng đưa vào phần mềm riêng của bạn. ## 16-05-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.3 **Bổ sung** * **Giao dịch Trái phiếu**: Bổ sung cấu trúc dữ liệu trái phiếu vào tầng giao diện Unified UI, đồng nhất kiến trúc với bản Mở rộng và bổ sung các hàm ohlcv, trades, quote. * **InstrumentType Enum**: Thêm phân loại định danh chứng khoán chuyên sâu để chuẩn hoá việc nhận diện các loại tài sản tài chính. **Thay đổi & Cải thiện** * Bổ sung danh sách các chỉ số index từ HNX, UPCOM và cải thiện khả năng nhận diện symbol qua hàm get_asset_type chính xác hơn với hỗ trợ các mã index mới. * **Dữ liệu Báo cáo Tài chính**: Hỗ trợ hệ số nhân (`unit_multiplier`), ánh xạ nhất quán cấu trúc cột dữ liệu giữa các nguồn KBS và VCI. * **Xử lý Nguồn dữ liệu (MSN & VCI)**: Xây dựng cơ chế resolve mã `SecId` động cho nguồn MSN để sửa lỗi truy xuất dữ liệu lịch sử; sửa lỗi kết nối nguồn VCI và kiểm tra an toàn URL khi tải danh sách mã. ### vnstock_ta #### Cập nhật Vnstock Data 3.1.8 - **Chuẩn hoá Báo cáo Tài chính (Unified UI)**: - Đồng bộ Schema báo cáo tài chính cho các nguồn dữ liệu (MAS, VCI), xử lý triệt để lỗi lệch cột và lẫn lộn ngôn ngữ (mixed labels) bằng hệ thống Mapping chỉ số La Mã (Roman numeral). - Bổ sung thông tin kỳ báo cáo (`report_period`) cho nguồn VCI, giúp kết quả tương thích với giao diện Unified UI. - **Thị trường Trái phiếu (Bond Market)**: - Tích hợp lớp domain `bond` vào hệ thống Unified UI, mở rộng khả năng tra cứu dữ liệu thị trường trái phiếu. #### Cập nhật Vnstock TA 1.0.3 > Bản Vnstock TA 1.0.3 cập nhật cách cài đặt và xử lý dữ liệu cho người dùng phiên bản cũ. **✨ Bạn có thể làm gì với bản cập nhật này?** - **Sử dụng kho chỉ báo đa dạng**: Bổ sung nhóm chỉ báo Thống kê (Statistics), chỉ báo sức mạnh xu hướng (Aroon) và mở rộng đáng kể các nhóm chỉ báo Xu hướng (Trend), Biến động (Volatility). - **Vẽ biểu đồ chuyên nghiệp với phong cách hiện đại**: Hệ thống Theme mới giúp biểu đồ có giao diện hiện đại và nhất quán. Các chỉ báo phức tạp nhiều đường (như StochRSI, ADX, PVO...) giờ đây đã có chú thích (legend) và nhãn dữ liệu rõ ràng, dễ đọc. **⚡ Tối ưu trải nghiệm sử dụng** - **Giảm gói phụ thuộc**: Bỏ `pyecharts` và `panel` khỏi phần cài đặt để giảm các thành phần cần cài cùng thư viện. - **Dữ liệu ổn định và nhanh chóng**: Chuyển đổi toàn bộ việc lấy dữ liệu sang giao diện Unified UI của Vnstock, giúp tốc độ tính toán nhanh và độ tin cậy cao hơn. ## 12-05-2026 ### vnstock_data > Cập nhật vnstock installer GUI v3.1.2 & CLI v3.0.2 * **Nhận diện mẫu Venv**: Đồng bộ cơ chế nhận diện các tên thư mục môi trường ảo phổ biến (`venv`, `.venv`, `env`). * **Cảnh báo tương tác**: Bổ sung hộp thoại xác nhận khi người dùng cung cấp đường dẫn không theo quy chuẩn môi trường ảo. * **Cơ chế an toàn**: Kiểm tra sự tồn tại của tệp `pyvenv.cfg` và các mẫu định danh venv trước khi thực hiện thao tác sửa đổi thư mục môi trường ảo bị lỗi. * **Gợi ý đường dẫn thông minh**: Tự động gợi ý thêm hậu tố `.venv` nếu người dùng chọn thư mục dự án làm nơi cài đặt môi trường ảo. ## 05-05-2026 ### vnstock_data (v3.1.7) * Bổ sung khả năng truy xuất tài liệu và báo cáo tài chính cho từng mã chứng khoán. Người dùng có thể truy xuất danh sách liên kết đến file báo cáo tài chính định dạng PDF của từng mã thông qua lập trình đơn giản. ```python from vnstock_data import Fundamental fun = Fundamental() fun.equity('FPT').filing(doc_type='annual_report') ``` * Tinh chỉnh chức năng hàm tiện ích `show_api` để hiển thị thông tin cây API trọn vẹn hơn theo từng cấp. * Ví dụ để xem tất cả cấu trúc bên dưới nhóm hàm `Reference` có thể gọi `show_api('Reference')` * Để xem chi tiết sâu hơn 1 cấp nữa, có thể sử dụng cú pháp chaining dạng `show_api('Reference.equity')` ## 02-05-2026 ### vnstock_data (v3.1.6) * Sửa lỗi xảy ra với `vnstock_data/explorer/vci/listing.py", line 35, in all_symbols` xung đột thư viện sau khi code bị làm rối. ## 01-05-2026 ### vnstock_data (v3.1.5) * Cập nhật khả năng tuỳ chỉnh điều kiện lọc cho hàm lọc dữ liệu cổ phiếu từ VCI trong giao diện hợp nhất tại lớp `Insights` * Sửa lỗi khởi tạo cấu hình kết nối trong `vnstock_data/core/utils/client.py` khi gọi lệnh mẫu `Company(symbol='VIC', source='KBS').overview()` ## 29-04-2026 ### vnstock_data (v3.1.4) * Cập nhật CLI Installer phiên bản 3.1.4 * Bổ sung danh sách mapping chính xác các chỉ số index từ HNX, UPCOM để truy xuất dữ liệu lịch sử ohlcv từ VCI ## 27-04-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0 **Thư viện dữ liệu** * Sửa lỗi truy cập dữ liệu từ nguồn VCI cho các module thông tin niêm yết (Listing), thông tin công ty (Company), và thông tin BCTC (Finance). Thay thế cơ chế lấy dữ liệu từ GraphQL sang REST API mới của Vietcap. * Sửa lỗi tham số `to_df` bị thiếu gây ngừng chương trình. * Cập nhật Unified UI (giao diện người dùng hợp nhất): cung cấp cách thức sử dụng hệ thống class/method chuẩn hoá cho toàn thư viện, thương thích với cách đặt tên và tiêu chuẩn của bản Mở rộng đã giới thiệu trước đó. **Tiện ích** * Cải thiện khả năng sử dụng Google Colab thuận tiện hơn khi không yêu cầu kết nối Google Drive bắt buộc. * Cải thiện logic phát hiện phiên bản phần mềm của hệ sinh thái vnstock đã cập nhật để không hiện lại thông báo phiền phức. * **[Mở rộng]** Tinh chỉnh lời nhắn hướng dẫn chuyển câu lệnh import sang thư viện của bản Mở rộng cho người dùng gói quyền sử dụng mới. **Tài liệu** * Cập nhật Vnstock Agent Guide với các hướng dẫn mới nhất hỗ trợ chuyển đổi code sử dụng class Vnstock sẽ bị loại bỏ từ 1/9/2026 vào skill `vnstock-migration-expert`. **Thông báo** * Hiển thị cảnh báo ngừng hoạt động cho lớp hàm Vnstock thường được sử dụng qua lệnh `from vnstock import Vnstock` sẽ kết thúc hỗ trợ vào 31/8/2026. * Thông báo nâng cấp đi kèm hướng dẫn chuyển đổi code sang các lớp hàm tương đương trong thư viện. * Agent Skills hỗ trợ việc chuyển đổi được bố sung hướng dẫn trong Vnstock Agent Guide. ## 23-04-2026 ### vnstock_data (v3.1.3) * **Chuẩn hoá & Mở rộng Báo cáo Tài chính (Fundamental & Financial Health)**: * Mở rộng Schema tài chính với các trường dữ liệu chi tiết từ nguồn MAS. * Định chuẩn hóa bộ tiêu chí đánh giá cho 4 nhóm ngành: Ngân hàng, Chứng khoán, Bảo hiểm và Đa ngành theo tiêu chuẩn phân tích chung tương tự giao diện tại TCBS. * **Hạ tầng & Tối ưu hóa (Infrastructure & Refactoring)**: * Nâng cấp các module tiện ích lõi để cải thiện hiệu năng kết nối. * **Sửa lỗi & Ổn định hệ thống (Bug Fixes)**: * Khắc phục triệt để lỗi sai tỷ lệ giá (price scaling) cho các tài sản Chỉ số (Index) và Phái sinh (Derivative) tại module `quote` (nguồn KBS). * Sửa lỗi truy xuất dữ liệu danh sách niêm yết (listing) và báo giá (quote) cho nguồn Dukascopy. * Xử lý các lỗi nhỏ trong UI Registry và logic phân loại ngành giúp hệ thống hoạt động chính xác hơn. * **Chuyển đổi giao thức dữ liệu VCI (API Migration)**: * Chuyển đổi toàn bộ quy trình lấy danh sách (Listing) và mã ngành (ICB) từ nguồn VCI từ GraphQL sang REST API để tăng độ ổn định và tốc độ phản hồi. ## 12-04-2026 ### vnstock_data > Phần mềm `vnstock_data` cập nhật phiên bản 3.1.0: Hoàn thiện bộ dữ liệu hợp nhất (Unified UI) và bổ sung bổ sung dữ liệu thị trường Quốc tế. * **Thị trường Quốc tế & Crypto**: * Tích hợp dữ liệu tiền mã hoá (Cryptocurrency) thông qua API Binance Spot (hỗ trợ dữ liệu `ohlcv`, `order_book`, `intraday`, `quote`). Khung kiến trúc được trang bị thuật toán chờ và gửi lại để duy trì kết nối khi gặp giới hạn truy vấn API. * Xây dựng kiến trúc Explorer cung cấp biểu đồ đa khung thời gian cho Ngoại hối (Forex), Hàng hoá (Commodity) và các chỉ số toàn cầu thông qua Dukascopy và ForexSB. Cung cấp bộ cấu hình Múi giờ gốc sang múi giờ Hệ thống (`Asia/Ho_Chi_Minh`). * **Thị trường Nội địa (Unified UI)**: * Nâng cấp API cho thị trường chỉ số (Index Market): Hệ thống hỗ trợ lấy bộ dữ liệu thống kê giao dịch lịch sử của tất cả các loại chỉ số thông qua phương thức `trade_history()`. Hỗ trợ tên chỉ số quy chuẩn để tra lệnh. * Bổ sung hàm tóm tắt bức tranh tài chính tổng hợp `financial_health` (tổ hợp 3 bảng báo cáo tài chính và các chỉ số tài chính). Chuẩn hoá chuyển ngữ thẻ Scorecard chuyên ngành: Ngân hàng, Chứng khoán, Bảo hiểm, hỗ trợ trích lọc linh hoạt. Quy chuẩn này lấy cảm hứng từ cấu trúc báo cáo của nền tảng TCBS, giúp duy trì sự nhất quán trong bộ tiêu chí cố định trong phân tích cơ bản cho doanh nghiệp, tránh phải xử lý bộ tiêu chí không thống nhất trong các báo cáo tài chính vốn có nhiều khác biệt giữa các nguồn khác nhau. Sử dụng bộ tiêu chí này giúp người dùng hạn chế phải thay đổi code khi nguồn dữ liệu gặp sự cố hoặc phiên bản phần mềm thay đổi ảnh hưởng tới bộ tiêu chí này. -Nguồn mặc định cho dữ liệu tài chính của các hàm tại Unified UI được chuyển đổi từ KBS sang MAS để tăng số kỳ báo cáo tài chính lên trên 10 năm, thay vì bị giới hạn 4 kỳ mặc định của API từ KBS. * Tối ưu tra cứu dữ liệu Vĩ mô (Macro) và Hàng hoá: Áp dụng kỹ thuật quét lùi tự động và đắp điền dữ liệu khuyết rỗng (Forward-fill) để xử lý hoàn thiện độ trễ công bố thông tin, giảm thiểu phát sinh lỗi. * Cải thiện khả năng chuẩn hoá symbol nhập nhập vào hàm của CafeF để nhận diện các chỉ số chính xác VNINDEX/HOSE, HNXINDEX/HNX, UPCOMINDEX/UPCOM và VN30. * Tái cấu trúc chuẩn thư viện: Áp dụng chuẩn hoá, bổ sung tham số định danh nhà cung cấp `source` theo yêu cầu từ phiên bản. * **Tài liệu Agent Guide**: * Cập nhật mô tả các hàm và nguồn dữ liệu bổ sung * Cung cấp schema dữ liệu chuẩn hoá giúp xác định mô hình dữ liệu và xây dựng sản phẩm tin cậy hơn, giảm thiểu việc phải chạy từng đoạn code để kiểm tra cấu trúc dữ liệu. * **Bổ sung bộ Notebook hoàn chỉnh**: * Bổ sung bộ Notebook hoàn chỉnh về các hàm tại Unified UI và theo kiểu gọi Adapter Pattern (thay đổi tham số source kiểu cũ) phản ánh đầy đủ trạng thái mới nhất của thư viện. ## 07-04-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.0.1 sửa các lỗi quan trọng và tinh chỉnh trải nghiệm người dùng. * **Unified UI**: Bổ sung hàm `cash_flow` vào giao diện hợp nhất; cập nhật mô tả cho hàm `trade_history` (thống kê giao dịch, giá chứng khoán trước khi pha loãng). * **Nguồn KBS**: Sửa lỗi chia điểm index cho 1000 và lỗi 502 Bad Gateway do web phân định lại cấu trúc URL; tinh chỉnh chuẩn hoá tên chỉ tiêu tài chính. * **Nguồn MBK (Vĩ mô)**: Cải thiện thuật toán truy xuất dữ liệu theo tham số `length` và tự động *forward fill* để khắc phục lỗi trả về dữ liệu rỗng. * **Nguồn SPL (Hàng hoá)**: Sửa lỗi truy xuất dữ liệu null sinh ra do không khớp cấu hình múi giờ. * **Nguồn VCI**: Bổ sung cơ chế tương thích pandas cho hàm map và applymap để hoạt động tốt cho tất cả phiên bản từ 2.1.0 và trước đó. ## 05-04-2026 ### vnstock
Bản cập nhật v3.5.1 mang đến những bước tiến lớn trong trải nghiệm lập trình AI (Vibe Coding) và hỗ trợ cập nhật cấu trúc nền tảng êm ái hơn bao giờ hết.
**Tính năng bổ sung nổi bật** * **Chuẩn hóa API cột dữ liệu (Module KBS)**: Mình đã thiết kế lại định danh tên cột dữ liệu chứng khoán nhằm khớp chính xác 100% với giao diện trên terminal của phần mềm KBS thực tế. * Cột `total_trades` 👉 `volume_accumulated` (tổng khối lượng) * Sinh thêm cột ánh xạ 👉 `volume_last` (khối lượng khớp lệnh lần cuối). **Lưu ý cho bạn**: Anh em đang phân tích DataFrame dựa vào các key trên nhớ cập nhật lại tên hàm nhé để pipeline hệ thống tiếp tục chạy ổn định. * **[Mở rộng]** **Hệ thống chuyển đổi "Một chạm" (Auto Migration)**: Chuyển dự án từ bản Cộng đồng sang bản Mở rộng giờ đây không còn là thao tác "Find & Replace" đầy rủi ro nơm nớp lo sợ làm hỏng code. Chỉ với một hàm gọi `migrate_to_sponsor()`, thư viện sẽ trực tiếp sử dụng công nghệ Cây cú pháp trừu tượng (AST) rà quét và tự động chuyển đổi cấu trúc mã nguồn cũ của bạn sang nền tảng chuyên sâu một cách an toàn tuyệt đối! * **Hệ thống Nhận diện Môi trường (Auto-Detection Guardrail)**: Vnstock nay trở nên tinh tế hơn bao giờ hết: Nếu nhận thấy bạn đang ở tư cách thành viên Sponsor của mình nhưng lại vô tình nhập các hàm phân tích của gói cơ bản, hệ thống sẽ tự động nhắc nhở và điều hướng để hỗ trợ bạn dùng đúng các hàm của bản Mở rộng mà bạn đã đăng ký. * **Tối ưu hóa Vibe Coding cùng AI**: Vnstock dồn tâm huyết phát triển các chỉ báo hệ thống ngầm (System Prompts) thiết kế đặc biệt dành cho các AI Agent khi phân tích mã nguồn. Giờ đây, các AI sẽ tự nhận diện rõ năng lực của API và đóng vai trò người cố vấn thay vì cố gắng tự gỡ rối hoặc rò rỉ mã lỗi. Chúng sẽ giúp bạn phân tích khi nào việc nâng cấp lên bản Mở rộng sẽ mang lại giá trị cao hơn nhiều việc cắm cúi code. *** ## 03-04-2026 ### vnstock_news > **Phát hành vnstock_news 2.2.0: theo dõi tin tức ổn định hơn** > > Bản phát hành mới khắc phục nhiều lỗi trong quá trình xử lý dữ liệu và cải thiện độ ổn định khi đọc tin từ 21 trang tin tại Việt Nam. #### Nâng cấp nổi bật - **Kiến trúc hợp nhất nguồn tin:** Kết hợp và tự động dự phòng chéo (fallback) giữa luồng RSS và Sitemap, giúp ứng dụng của bạn tiếp tục nhận tin mới khi một trong hai luồng gặp sự cố. - **Trích xuất metadata linh hoạt:** Tăng cường khả năng bắt chính xác Selector qua các thuộc tính linh hoạt (`id`, `data-slot`, `rel`) thay vì phụ thuộc mỗi thẻ `class` theo CSS Selector truyền thống. Chủ động trích xuất thêm thẻ Tags, Lượt xem và Chuyên mục của bài. - **Làm sạch tự động & Xử lý thời gian:** - **Date Parser:** Tự động chuẩn hoá và ép kiểu các định dạng thời gian khác nhau (như *15 phút trước*, *Thứ năm...*) về chuẩn ISO thống nhất. - **Spam/Media Link Filter:** Rà soát và loại bỏ link nhiễu phân trang, hình ảnh, URL rác đính kèm trong RSS. #### Cải tiến độ ổn định - Sửa dứt điểm tình trạng trả về Data nhưng cột Nội dung trống rỗng (Missing Content 100%) gây ra bởi lỗi đọc JSON. - **Bổ sung nguồn tin mới được hỗ trợ:** Bổ sung và tinh chỉnh cấu trúc CSS cho hàng loạt website tin tức mới (Tiền Phong, Người Lao Động, Thanh Niên, Znews, Dân Trí, Đầu Tư, VnEconomy). - Bổ sung bộ kịch bản dùng thử "All-in-one" và tái cấu trúc tài liệu ví dụ, tự động dọn dẹp kết quả xuất file vào phân vùng tĩnh `/output/`.
Nhấp để xem danh sách website tin tức được hỗ trợ sẵn (cập nhật 06/10/2026) | STT | Tên Website / Báo | Tên Config | Loại Hình | RSS | Sitemap | | --- | ------------------------- | ---------------------- | ------------ | --- | ------- | | 1 | **Nhân Dân** | nhandan | Cơ quan TW | ✅ | ✅ | | 2 | **Tiền Phong** | tienphong | Cơ quan TW | ✅ | ✅ | | 3 | **VietNamNet** | vietnamnet | Bộ Ngành | ✅ | ✅ | | 4 | **Dân Trí** | dantri | Bộ Ngành | ✅ | ✅ | | 5 | **VnExpress** | vnexpress | Bộ Ngành | ✅ | ✅ | | 6 | **Báo Đầu Tư** | baodautu | Bộ Ngành | ✅ | ✅ | | 7 | **Thời Báo Tài Chính** | thoibaotaichinhvietnam | Bộ Ngành | ✅ | ✅ | | 8 | **Thanh Niên** | thanhnien | Tổ chức TW | ✅ | ✅ | | 9 | **Tuổi Trẻ** | tuoitre | Địa phương | ✅ | ✅ | | 10 | **VnEconomy** | vneconomy | Chuyên ngành | ✅ | ✅ | | 11 | **Diễn Đàn Doanh Nghiệp** | dddn | Chuyên ngành | ✅ | ✅ | | 12 | **PetroTimes** | petrotimes | Chuyên ngành | ✅ | ✅ | | 13 | **Znews (Tri thức)** | znews | Chuyên ngành | ✅ | ✅ | | 14 | **CafeF** | cafef | Trang tin | ✅ | ✅ | | 15 | **CafeBiz** | cafebiz | Trang tin | ✅ | ✅ | | 16 | **VietStock** | vietstock | Trang tin | ✅ | ✅ | | 17 | **24h** | 24h | Tổng hợp | ✅ | ✅ | | 18 | **Người Quan Sát** | nguoiquansat | Tổng hợp | ✅ | ✅ |
## 27-03-2026 ### vnstock_data * Cập nhật CLI Installer phiên bản 3.0.2 * Tự động nhận diện API Key đã lưu trong môi trường thay vì yêu cầu người dùng nhập lại. * Tinh chỉnh thiết lập để người dùng tiện cài đặt bộ thư viện trên Google Colab, không yêu cầu bắt buộc phải kết nối Google Drive. * Nâng cấp cơ chế bỏ qua thông báo chuyển đổi câu lệnh import từ vnstock sang vnstock_data gây phiền phức ## 11-03-2026 ### vnstock_data > **Phát hành vnstock_data 3.0.0: Thế hệ mới với Unified UI và Thị trường Quốc tế.** > > Phiên bản 3.0.0 không chỉ là một bản cập nhật thông thường, mà là bước chuyển mình quan trọng của hệ sinh thái Vnstock. Phiên bản này mang đến kiến trúc 7 lớp tiêu chuẩn nghiệp vụ và trải nghiệm lập trình (DX) được nâng cấp vượt trội. * **Kiến trúc 7 Lớp & Unified UI (U2)**: * Hoàn thiện mô hình **Unified UI** với 7 phân vùng chức năng rõ rệt: `Reference`, `Market`, `Fundamental`, `Analytics`, `Alternative`, `Macro`, và `Insights`. * Cách tiếp cận "Vấn đề là trên hết": Bạn không còn phải lo lắng về việc dữ liệu đến từ đâu, chỉ cần tập trung vào việc bạn muốn làm gì (định giá, xem bảng giá hay tra cứu thông tin cơ bản). Chất lượng và nguồn dữ liệu tốt nhất sẽ được Vnstock khuyến nghị. Bạn có thể cá nhân hoá nguồn dữ liệu như cách lập trình cũ nếu muốn để khai thác các chức năng có sẵn nhưng ẩn sâu trong mã nguồn. * Bổ sung thông tin hồ sơ (profile) chi tiết cho **Chứng quyền** và **Hợp đồng tương lai**, giúp bạn nắm bắt đầy đủ thông tin sản phẩm trước khi giao dịch. * Tích hợp **Lịch sự kiện thị trường**: từ dữ liệu lịch sử (nghỉ lễ, sự cố thị trường... từ năm 2000) đến các sự kiện hiện tại và sắp diễn ra. * **Trợ lý lập trình thông minh (Next-Gen DX)**: * Tái kích hoạt tính năng **Autocomplete** và **Docstring** vượt trội trên các IDE (VSCode, PyCharm), giúp việc viết code nhanh và ít lỗi hơn. * Bổ sung bộ công cụ khám phá API: `show_api()` để vẽ sơ đồ thư viện ngay trong terminal và `show_doc()` để đọc nhanh hướng dẫn sử dụng cho từng hàm. * Tài liệu (Docstrings) đã được chuyển đổi sang tiếng Anh chuẩn để dễ dàng tiếp cận và phù hợp với tiêu chuẩn lập trình hiện đại và tương tác với AI Agent. * **Chuẩn hóa & Tối ưu hóa hệ thống**: * **Chuẩn hoá dữ liệu bảng giá từ nguồn KBS**: Giải quyết triệt để các vấn đề về hiển thị lô chẵn, lô lẻ; đồng bộ hóa dữ liệu cho đa dạng loại tài sản từ cổ phiếu, phái sinh, chứng quyền đến trái phiếu. * Dữ liệu được **tự động chuẩn hóa (Normalization)** từ nhiều nguồn khác nhau về một định dạng duy nhất, giúp việc tính toán và phân tích nhất quán hơn. * Cơ chế **Lọc tham số (Kwargs Filtering)**: Giúp giảm thiểu lỗi runtime khi bạn vô tình truyền thừa tham số, tăng tính ổn định cho chương trình. * Tối ưu hóa cấu trúc nội bộ của thư viện. * **Cập nhật Vnstock Agent Guide**: Tài liệu hướng dẫn chi tiết và các quy tắc cho AI Agent trong lập trình tự động được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) *** ## 07-03-2026 ### vnstock
Phiên bản 3.5.0 mang tính bản lề trong việc tái cấu trúc thư viện, tập trung loại bỏ các nguồn cấp thiếu ổn định và chuẩn hóa điểm dữ liệu để hướng tới sự tương thích với AI (Vibe Coding).
**Các thay đổi quan trọng (Breaking Changes)** * **Tinh gọn các kết nối nguồn**: Để bộ công cụ tinh gọn và vận hành ổn định, Vnstock ngừng các module kết nối tới TCBS và bộ lọc cổ phiếu (Screener). **[Mở rộng]** Bộ lọc nhiều tiêu chí khi đó có ở bản Mở rộng. * **Chuẩn hóa Thông số Bảng giá (KBS Quote)**: Cập nhật định dạng dữ liệu giá lịch sử (`history`) và dữ liệu trong ngày (`intraday`) thống nhất sử dụng hệ số thập phân (đơn vị nghìn đồng) thay cho VND. Điều này giúp tính toán nhẹ nhàng hơn nhưng bạn nhớ điều chỉnh lại các công thức nhân chia mệnh giá trong dòng code cũ để tránh tình trạng lệch dữ liệu biểu đồ phân tích. * **Loại bỏ hàm `price_depth`**: Hàm này đã ngừng trên module `vci.quote`. **[Mở rộng]** Khi đó tính năng chỉ có ở bản Mở rộng. **Tính năng bổ sung & Cải tiến** * **Dữ liệu Sự kiện Thị trường (Market Events)**: Vnstock thấu hiểu nỗi đau của những ai làm backtesting khi chiến lược bị lệch pha do các ngày nghỉ lễ hay những hôm nghẽn hệ thống. Module mới `vnstock.core.utils.market_events` ra đời cung cấp bộ lịch sử sự kiện chứng khoán Việt Nam từ năm 2000. Đây là công cụ đắc lực hỗ trợ các mô hình AI và thuật toán phân tích chuỗi thời gian (time-series) của bạn vượt qua bài toán nhiễu loạn dữ liệu. * **Hàng loạt Cải thiện Ổn định**: Vá ngoạn mục hàng loạt lỗi hệ thống: Bổ sung phương pháp lấy mã cổ phiếu fallback cực thông minh (hiệu quả khi sàn thiếu column gốc); sửa lỗi bắt dữ liệu cho Hợp đồng tương lai đáo hạn và nâng cấp thuật toán đọc số bar trên khung ngày (`500b`) cho KBS Quote được chính xác. Cùng với đó là hoàn thiện việc tích hợp `pytz` hỗ trợ làm đồng bộ các bộ dữ liệu đa không gian múi giờ. *** ## 05-03-2026 ### vnstock_data * **Cập nhật module Unified UI (U2)**: Cập nhật các lớp UI cung cấp cấu trúc lệnh hợp nhất với phân nhóm chặt chẽ lấy cảm hứng từ chuẩn FIX và Bloomberg Terminal giúp điều hướng dễ dàng theo mặc định do Vnstock thiết kế và người dùng không cần cài đặt nguồn dữ liệu. Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) * **Bổ sung hàm lấy thông tin Chứng quyền và hợp đồng tương lai**: * Cung cấp hàm trong giao diện U2 để lấy thông tin chứng quyền và hợp đồng tương lai thông qua Reference().derivatives().warrant() và Reference().derivatives().futures() * **Bổ sung hàm lấy thông tin bộ lọc cổ phiếu từ VCI** thông qua U2 tại `Insights().screener()` * **Cải thiện & bổ sung API nguồn Vĩ mô**: * Bổ sung method `interest_rate` để lấy dữ liệu Lãi suất bình quân & Doanh số trên thị trường liên ngân hàng. Hỗ trợ tham số `format='pivot'` (mặc định) để trả về bảng dạng nhóm cột (MultiIndex giống biểu diễn trên website) hoặc `format='long'` để trả về định dạng phẳng (raw format). * Tích hợp thêm tham số khoảng thời gian tương đối `length` (ví dụ: `90`, `1Y`, `30D`, `100b`) tương tự như cách sử dụng trong `quote.history`. Tính năng này áp dụng đồng bộ cho tất cả các hàm vĩ mô (`gdp`, `cpi`, `interest_rate`, `exchange_rate` v.v...) để bỏ qua việc nhập ngày bắt đầu `start` và kết thúc `end`. * Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) là 1 năm (`1Y`) để trả về thông tin ở khoảng thời gian phù hợp và nhẹ. * Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) * **Cải thiện trải nghiệm sử dụng module lấy dữ liệu hàng hoá**: * Tích hợp khả năng lấy thời gian tương đối thông qua tham số `length` tương tự như module `macro` và `quote.history`. * Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) về 1 năm (`1Y`) thay vì lấy toàn bộ lịch sử như trước đây. * Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) ## 01-02-2026 ### vnstock
Phiên bản 3.4.2 tập trung vào sửa lỗi và cải thiện tính ổn định, đặc biệt là tương thích với các phiên bản pandas khác nhau và chuẩn hóa dữ liệu giá.
**Sửa lỗi quan trọng** * **Sửa lỗi tương thích pandas**: Khắc phục vấn đề `include_groups` parameter không được hỗ trợ trong pandas 2.1.4, giúp hàm `intraday()` hoạt động bình thường trên mọi phiên bản pandas * **Sửa lỗi kiểm thử Listing**: Cập nhật các bài kiểm thử để xử lý chính xác kiểu dữ liệu `pd.Series` trả về từ `all_future_indices` và các phương thức liên quan * **Sửa lỗi kiểm thử Quote**: Cải thiện khả năng xử lý dữ liệu thiếu và các hợp đồng đã hết hạn một cách linh hoạt mà không làm thất bại toàn bộ bộ kiểm thử * **Sửa lỗi KBS Quote**: Cải thiện khả năng diễn giải các độ dài lookback dựa trên thanh (ví dụ: '500b') sử dụng logic `interpret_lookback_length` **Cải tiến** * **Bổ sung liên kết đến Agent Guide**: Giúp dễ dàng truy cập và sử dụng bộ hướng dẫn chi tiết cho AI trong Vibe Coding. * **Chuẩn hóa dữ liệu giá KBS**: Chuyển đổi dữ liệu giá từ nguồn KBS sang sử dụng giá trị thập phân (đơn vị nghìn) thay vì VND trong các phương thức `history` và `intraday`, giúp dữ liệu nhất quán và dễ xử lý hơn **Loại bỏ** * **Loại bỏ phương thức `price_depth`**: khỏi `vnstock.explorer.vci.quote`, tập trung các hàm cơ bản cho bản Cộng đồng. *** ## 31-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.4, sửa lỗi và cải thiện trải nghiệm người dùng * Chuẩn hoá định dạng dữ liệu giá thành dạng thập phân xx.xx (ngàn) thay vì xxxx (đồng) cho các hàm `history` và `intraday` trong lớp Quote của nguồn dữ liệu KBS. * Sửa lỗi không cho phép gọi tham số length trong hàm `history` của lớp Quote của nguồn dữ liệu VCI, VND, MAS khi không truyền tham số `start` và `end`. * Sửa lỗi không nhận diện nguồn VND cho lớp hàm Market * Cập nhật chương trình cài đặt vnstock installer chế độ GUI và CLI sử dụng `uv` là công cụ quản lý thư viện thay cho `pip`, tăng tốc độ cài đặt và giảm 30% thời gian hoàn thành. ## 28-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.2, sửa lỗi và cải thiện trải nghiệm người dùng * Chuẩn hoá tham số `period` để lấy dữ liệu báo cáo tài chính cho các phương thức trong lớp Finance của nguồn dữ liệu KBS - cho phép gọi tham số này khi khởi tạo lớp Finance thay vì gọi ở mỗi phương thức. * Bổ sung tham số `length` cho phép lấy dữ liệu hàng hoá theo cách tính thời gian tương đối so với hiện tại thay vì bắt buộc nhập ngày bắt đầu và kết thúc. * Tinh chỉnh nhỏ cho lớp Commodity giúp nạp thư viện chính xác, loại bỏ lỗi liên quan nested f-string sinh ra trong quá trình bảo mật mã nguồn. ## 27-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.1, bổ sung tài liệu hướng dẫn chi tiết Vnstock Agent Guide. * Bổ sung hàm tiện ích `convert_derivative_symbol` giúp chuyển đổi mã hợp đồng tương lai kiểu cũ (VN30F1M) sang kiểu mới sau áp dụng KRX (tương đương 41I1G2000 tại thời điểm tháng 1/2026) * Cải thiện nguồn KBS * Sửa lỗi không nhận diện nguồn dữ liệu KBS từ Finance wrapper * Bổ sung khả năng lấy dữ liệu báo cáo tài chính nhiều năm thay vì cố định 4 năm như phiên bản trước * Tự động nhận diện và chuyển đổi mã hợp đồng tương lai sang kiểu mới để gọi các hàm `history` và `intraday` trong lớp hàm Quote. * Bổ sung khả năng lấy dữ liệu các mã index phổ biến HNXINDEX, HNXINDEX, UPCOMINDEX, VN30, VN100, HNX30 trong hàm `history` của lớp Quote. * Cải thiện chung * Hiện cảnh báo mã index không có dữ liệu `intraday`. ## 23-01-2026 ### vnstock
Phiên bản 3.4.0 đã được phát hành chính thức. Cài đặt ngay với lệnh pip install vnstock -U. Phiên bản này tập trung vào trải nghiệm người dùng: dữ liệu tài chính sạch hơn, trực quan dễ hiểu hơn và cài đặt/xác thực thuận tiện hơn.
**Những điểm nổi bật** * **Cài đặt & xác thực dễ dàng** * Cài nhanh bằng `pip install vnstock -U` và nhập API Key từ trang quản lý tài khoản Vnstock để sử dụng, hỗ trợ hàm trực tiếp từ thư viện để sử dụng. * **Báo cáo tài chính thân thiện với người dùng từ nguồn KBS** * Dữ liệu báo cáo giờ đây được chuẩn hóa tốt hơn: cột rõ ràng, ít trùng lặp và dễ đọc. * Hỗ trợ **lọc ngôn ngữ** (Tiếng Việt / Tiếng Anh / Cả hai) và các chế độ hiển thị (`standardized_only`, `all_fields`, `auto_convert`) giúp bạn nhanh chóng lấy dữ liệu phù hợp cho báo cáo hoặc phân tích. * **Dữ liệu đáng tin cậy & chuẩn hóa tiếng Việt** * Cải tiến chuẩn hóa văn bản tiếng Việt (bảng ký tự nâng cấp, chuyển đổi tên trường ổn định) giúp việc tìm, so sánh và tự động hoá xử lý dữ liệu trở nên dễ dàng hơn. * Tự động **phát hiện xung đột các trường thông tin trong BCTC** và sinh ID khi cần, giảm rủi ro nhầm lẫn khi trộn nhiều nguồn dữ liệu. * Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. * **Trực quan hoá & báo cáo nhanh** * Tích hợp `vnstock_ezchart` cùng tiện ích mở rộng cho pandas để vẽ biểu đồ và tạo báo cáo chỉ bằng vài dòng mã. * **Ổn định & chất lượng phát hành** * Cải thiện quy trình kiểm thử và CI/CD giúp phát hành phiên bản ổn định hơn, lỗi được phát hiện và sửa nhanh hơn. **Một vài thay đổi nhỏ** * Cập nhật đường dẫn đăng ký API key từ `/account` → `/login` (trải nghiệm đăng ký/đăng nhập thống nhất hơn). * Tối ưu hiệu suất mô-đun dữ liệu KBS và một số tinh chỉnh nội bộ để nâng cao tốc độ và độ tin cậy. *** ### vnstock_data * Phát hành phiên bản 2.2.0, bổ sung kết nối nguồn KBS, dùng được trên Google Colab và Kaggle. * Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. * Cập nhật yêu cầu phiên bản gói phụ thuộc tương thích. ## 11-11-2025 ### vnstock * 🚀 **Phiên bản v3.3.0** * **Tương thích hệ thống thư viện Sponsor** sử dụng phương thức xác thực người dùng và quyền sử dụng thông qua Vnstock API key thay cho Github. * **Tăng tốc sử dụng Vnstock trên Google Colab**: Cho phép lưu trữ thư viện & cấu hình vĩnh viễn trong Google Drive để khởi động nhanh thay vì cài đặt lại sau mỗi phiên làm việc. * **Quản lý nguồn thống nhất**: Đưa các nguồn đang hỗ trợ (VCI, TCBS, FMP, XNO, DNSE) về một cơ chế quản lý chung * **Kết nối FMP & XNO**: Thêm kết nối tới hai nguồn này; bạn dùng API key của chính mình do FMP và XNO cấp * **Tái tổ chức mã nguồn**: Gộp các module trong core.utils, chuẩn hóa cách đặt tên và cấu trúc trong common * **Bổ sung kiểm thử**: Thêm bộ test cho các module VCI, TCBS, FMP với kiểm thử tích hợp * **Chuyển sang pyproject.toml**: Thay thế setup.py bằng pyproject.toml, cập nhật các thư viện phụ thuộc * **Cấu hình Context7**: Thiết lập hệ thống lập chỉ mục tài liệu cho AI * **Cập nhật tài liệu**: Làm mới notebook hướng dẫn nhanh, hướng dẫn sử dụng * 🔧 **Cải thiện kỹ thuật** * Chuẩn hóa hằng số thị trường, chỉ số và định nghĩa kiểu dữ liệu * Cải thiện xử lý lỗi và thông báo xác thực * Tái cấu trúc mã nguồn tiêu chuẩn với tài liệu mô tả bằng tiếng Anh * 📚 **Tài liệu** * Cập nhật notebook hướng dẫn nhanh cho FMP và XNO ## 31-08-2025 ### vnstock_news > Phát hành phiên bản Vnstock News 2.1.0 nâng cấp cơ chế tải dữ liệu và cung cấp khả năng tuỳ biến linh hoạt, bổ sung tài liệu hướng dẫn chi tiết.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/legacy/cai-dat-phan-mem). - Thay đổi hoàn toàn cấu trúc chương trình theo hướng chặt chẽ và module hoá - Cung cấp cơ chế tự xử lý link sitemap và rss linh hoạt đối với các website sử dụng cơ chế động ví dụ sitemap theo năm-tháng, sitemap với số đếm tăng dần. - Hỗ trợ 21 trang web trong danh sách định nghĩa sẵn, người dùng có thể tự bổ sung cấu hình để theo dõi tin tức từ các trang khác ngoài danh sách. ## 29-08-2025 ### vnstock_pipeline > Phát hành phiên bản Vnstock Pipeline 2.0.1 nâng cấp cơ chế tải dữ liệu Intraday và streaming dữ liệu trong phiên qua WebSocket.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/legacy/cai-dat-phan-mem). - Bổ sung tài liệu hướng dẫn tuỳ biến chương trình - Cải thiện trải nghiệm sử dụng: tuỳ chọn địa điểm lưu file khi streaming, lọc dữ liệu mong muốn thay vì tự lưu toàn bộ. - Cải thiện khả năng truy cập dữ liệu intraday liên tục trong phiên giao dịch và ghép nối thông minh hơn. - Bổ sung tính năng Data Manager cho phép quản lý cấu trúc dữ liệu lưu trữ khoa học và chặt chẽ - Bổ sung khả năng lưu trữ dữ liệu định dạng parquet, tệp nhỏ hơn đáng kể so với CSV và tăng hiệu năng xử lý. ## 21-07-2025 ### vnstock_data > Phát hành phiên bản Vnstock Data 2.1.3 và nâng cấp cơ chế quản lý license chính xác hơn. Để thực hiện nâng cấp phiên bản, các bạn vui lòng chạy lại chương trình cài đặt, lưu ý nên chạy thử và trải nghiệm qua môi trường như Github Codespace để hình dung các thay đổi để không làm ảnh hưởng đến chương trình hiện có. Hệ thống **không thể quay lại phiên bản cú sau nâng cấp**.
Nâng cấp


#### Ads Free Ẩn banner quảng cáo đối với người dùng đang duy trì gói sponsor trừ những thông báo đặc biệt liên quan đến trải nghiệm người dùng hoặc yêu cầu nâng cấp bắt buộc. #### Vnstock Data Explorer * Bổ sung nguồn Fmarket vào mã nguồn * Bổ sung và nâng cấp các API của nguồn VCI * Thay thế API các nhóm hàm Quote, Listing class gặp lỗi từ chối truy cập và đổi url * Bổ sung bộ API mới cho nhóm hàm thuộc Financial class * Cập nhật API mới * Cho phép sử dụng tiếp API cũ từ máy tính local nếu muốn. * Sửa đổi nhóm hàm Trading cho phép lấy dữ liệu phân tích lịch sử giao dịch & bảng giá * Thêm các hàm `foreign_trade` để lấy riêng thông tin giao dịch nước ngoài * Loại bỏ các hàm `trading_stats` và `side_stats` trong nhóm hàm thuộc Trading class để không trùng thông tin với hàm `price_board` ## 02-06-2025 ### vnstock_data #### Vnstock Data Explorer
Bổ sung hàm truy xuất dữ liệu lịch sử giao dịch từ VCI với Trading class thay thế dữ liệu từ CafeF gặp lỗi.
Chi tiết hàm bổ sung tại [Nguồn VCI - Thống kê giao dịch](/docs/vnstock/du-lieu-giao-dich) ## 23-05-2025 ### vnstock
Chính thức phát hành phiên bản mới sau khi đã cập nhật bản thử nghiệm từ 17/05/2025 hỗ trợ mã hợp đồng tương lai mới sau khi chuyển đổi hệ thống KRX.
* Hỗ trợ mã hợp đồng tương lai mới theo chuẩn KRX: 1. **Loại CK phái sinh** (ký tự 1) 2. **Nhóm CK** (ký tự 2: 1=Future, 2=Spread) 3. **Tài sản cơ sở** (ký tự 3–4: I1=VN30, B5=GB05, BA=GB10, I2=VN100) 4. **Năm đáo hạn** (ký tự 5: 0→W, loại trừ I,O,U) 5. **Tháng đáo hạn** (ký tự 6: 1→C) 6. **Mã sản phẩm** (ký tự 7–9, ví dụ 000 = HĐTL) * **Ví dụ chuyển đổi**: VN30F2504 → 41I1F4000 Cập nhật này giúp Vnstock nhận diện đúng loại hợp đồng tương lai khi bạn nhập mã hợp đồng theo cấu trúc mới. ## 07-05-2025 ### vnstock
Cập nhật mã nguồn trên Github cho phiên bản kế tiếp. Bạn có thể cập nhật phiên bản để trải nghiệm trong khi phiên bản ổn định sẽ được phát hành trong những ngày tới.
Cài đặt phiên bản thử nghiệm: ```bash pip install vnstock -U ``` Xem thêm hướng dẫn tại [Tải về & Cài đặt](/onboard/trai-nghiem-vnstock) **Cập nhật nổi bật** * [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Gỡ và thay thế một thư viện phụ thuộc bên ngoài trong toàn bộ hệ sinh thái * Sửa lỗi hàm `intraday` sau cập nhật hệ thống KRX * Dữ liệu từ nguồn VCI thay đổi kiểu dữ liệu (`object`/`float`) thay vì `int` như trước đó. * Dữ liệu từ nguồn TCBS bị sai lệnh múi giờ (dữ liệu mới đã chuẩn múi giờ GMT+7) * Bổ sung thông tin bạn đồng hành đóng góp mã nguồn và tài trợ dự án nổi bật vào mô tả dự án. ## 22-04-2025 ### vnstock
Phiên bản **3.2.4** tái cấu trúc bộ adapter từ `vnstock/common` → `vnstock/api` với thuật toán xử lý chặt chẽ hơn, dần loại bỏ lớp trung gian không cần thiết hiện đang sử dụng với `Vnstock` class; bổ sung **notebook minh họa**; tối ưu hóa quy trình **báo lỗi** và **theo dõi dự án** trên GitHub.
**Cải tiến kiến trúc** * Bổ sung cấu trúc Adapter mới tại `vnstock/api` * Thuật toán mới tăng độ chính xác và linh hoạt khi chuyển đổi nguồn dữ liệu * Loại bỏ lớp trung gian cấp cao Vnstock, trực tiếp sử dụng các lớp: `Quote`, `Finance`, `Trading`, `Listing`, `Company` * Tương thích ngược: mọi hàm và class cũ vẫn hoạt động bình thường **Hướng dẫn minh họa** * Bổ sung file notebook minh họa mới sử dụng các cấu trúc lớp trung gian chuyển đổi nguồn nhanh chóng [tại đây](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/wrapper/1_1_quickstart_stock_vietnam.ipynb) **Hoàn thiện quy trình phát triển** * Báo lỗi qua [GitHub Issues](https://github.com/thinh-vu/vnstock/issues) tại trang Github Vnstock * Theo dõi lộ trình qua [GitHub Projects](https://github.com/users/thinh-vu/projects/4) tại trang Github Vnstock ### vnstock_data #### Vnstock Data Explorer > Phiên bản `vnstock_data` **2.1.0** đánh dấu bước tiến lớn trong khả năng quản lý và mở rộng dữ liệu, với việc áp dụng **cấu trúc Adapter** chuẩn hóa toàn bộ giao tiếp với nguồn cấp dữ liệu. ##### ✨ Những Thay Đổi Quan Trọng | Hạng mục | Thay đổi | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cấu trúc thư viện** | Triển khai mô hình **Adapter Pattern** cho tất cả các lớp dữ liệu (Quote, Trading, Finance, Listing, Company, Macro, Commodity, v.v.). | | **Cách gọi hàm** | Các hàm khi sử dụng Adapter cần truyền **tham số `source`** để xác định rõ nguồn bạn muốn truy vấn. | | **Mặc định `source`** | Tham số `source` **không còn mặc định ngầm định** như phiên bản trước. Nếu không truyền `source` đúng, hàm có thể gây lỗi `NotSupportedError`. | | **Hướng dẫn chi tiết hơn** | Bổ sung [bảng tra cứu](/docs/vnstock/vnstock-data-v3/gioi-thieu-vnstock-data) phương thức hỗ trợ theo nguồn cấp dữ liệu, và sơ đồ hệ thống trực quan. | ##### 🚨 Lưu Ý Ảnh Hưởng Đến Đoạn Mã Cũ Nếu bạn đang sử dụng `vnstock_data` theo cách cũ ```python from vnstock_data import Trading trading = Trading(symbol='MSN') quote.history(start="2024-01-01", end="2024-04-01") ``` ➡️ Từ phiên bản 2.1.0, đoạn code trên **sẽ lỗi** nếu thông tin `source` không trùng khớp với nguồn cấp dữ liệu hỗ trợ. Cụ thể, bạn cần sửa lại thành: ```python from vnstock_data import Trading quote = Quote(source="cafef", symbol="VCI") quote.history(start="2024-01-01", end="2025-04-18", interval="1D") ``` ## 27-03-2025 ### vnstock > Cập nhật phiên bản 3.2.3 cải thiện trải nghiệm người dùng * Xử lý chính xác các cột có tên trùng lặp trong hàm `balance_sheet` trả về bảng cân đối kế toán. Theo đó cột xuất hiện sau với tên trùng lặp sẽ được đặt tên với tiền tố `_`. Ví dụ `Chứng khoán kinh doanh` và `_Chứng khoán kinh doanh` cho cột xuất hiện sau. Hai cột này tồn tại có ý nghĩa theo hình thức cha/con trên bảng cân đối kế toán tiêu chuẩn. * Merge [pull request 159](https://github.com/thinh-vu/vnstock/pull/159): Bổ sung cột sẽ được lựa chọn hiển thị tiếng Việt khi trích xuất dữ liệu từ Dict * Bổ sung `tenacity` là gói phụ thuộc khi cài đặt dự án * Sửa lỗi không cho truy cập dữ liệu intraday từ nguồn TCBS ngoài giờ giao dịch. * Sửa lỗi hàm Pandas `map` và thay thế với `applymap` để tương thích với bản Pandas cũ hơn 2.x trong module company của nguồn VCI (dòng 135) * Cập nhật file README đổi tên Vnstock3 thành Vnstock ## 24-03-2025 ### vnstock > Cập nhật phiên bản 3.2.2 sửa lỗi 502 Bad Request xuất hiện với nguồn dữ liệu VCI. Lỗi 502 Bad Request xuất hiện trùng thời điểm với việc nâng cấp lên phiên bản 3.2.1 đã khiến nhiều người thắc mắc. Sau khi phân tích, nguyên nhân được xác định: VCI đã thay đổi địa chỉ cấp dữ liệu API, khiến các yêu cầu gửi đến API cũ không còn hiệu lực và dẫn đến phản hồi không ổn định. ## 23-03-2025 ### vnstock > Cập nhật phiên bản 3.2.1 với nhiều thay đổi quan trọng * Bổ sung tính năng bộ lọc cổ phiếu từ TCBS * Thêm dữ liệu thông tin công ty từ nguồn VCI * Kết nối Google Drive từ Colab - Không bao giờ quên lưu dữ liệu nữa * Cải tiến trải nghiệm người dùng * Nhận diện phiên giao dịch: tự động gửi cảnh báo lỗi chi tiết giúp bạn điều hướng dễ dàng khi truy cập dữ liệu `intraday` và `price_depth` trước phiên giao dịch. * Cảnh báo chủ động rate limit * Chuẩn hóa tên cột: Thay đổi `ticker` → `symbol`, `HOSE` → `HSX`, giúp dữ liệu đồng nhất, dễ xử lý hơn. * Cập nhật API key MSN: Đảm bảo việc lấy dữ liệu luôn ổn định và nhanh chóng. * Tái cấu trúc mã nguồn * Tăng mức độ module hóa mã nguồn * Cấu trúc tinh gọn và dễ bảo trì * Chuẩn hóa xử lý lỗi Chi tiết, vui lòng xem trong bài blog.
Xem thêm
## 02-01-2025 ### vnstock
Hợp nhất thư viện Vnstock3 và Vnstock Legacy, sử dụng chung tên gọi thư viện là vnstock từ hệ thống phân phối phần mềm pypi.org. Từ 2/1/2025, mọi cài đặt thư viện vnstock được mặc định hiểu là thư viện thế hệ 3, bắt đầu từ phiên bản 3.1.0
* Cập nhật thư viện lên trang phân phối pypi.org. Câu lệnh cài đặt mặc định: `pip install -U vnstock` sẽ luôn cài đặt phiên bản vnstock mới nhất vào máy của bạn. Câu lệnh `pip install vnstock3` sẽ vẫn có hiệu lực, chỉ cập nhật đến phiên bản 3.1.0. * Cập nhật tài liệu hướng dẫn trên website và file Demo. Tất cả lệnh sẽ sử dụng `vnstock` để chỉ định phiên bản hiện tại của Vnstock3.1.0.1. Tham khảo blog để biết thêm chi tiết [tại đây](/blog/chuyen-doi-sang-vnstock3-truoc-2025). ## 02-11-2024 ### vnstock > Phát hành chính thức phiên bản v3.0.9 qua PyPI. Cài đặt với câu lệnh: `pip install -U vnstock` trên máy của bạn. * Nâng cấp hàm truy xuất dữ liệu từ nguồn VCI cho báo cáo tài chính. Lọc các cột dữ liệu không liên quan, trùng lặp xuất hiện trong các phiên bản trước đó. Chỉ tập trung các giá trị dữ liệu cho đúng loại hình công ty của mã bạn tra cứu. Có 4 nhóm công ty bao gồm Công ty phổ thông, Ngân hàng, Chứng khoán, Bảo hiểm. * Sửa lỗi chuyển đổi nhanh mã cổ phiếu. Cho phép cài đặt tham số `symbol` khi gọi hàm với cú pháp `stock.finance(symbol='TCB')`. Việc này giúp bạn không cần phải cập nhật mã symbol khi khởi tạo class mà có thể thayd đổi trong method gọi dữ liệu cụ thể. Thay đổi này sau đó sẽ áp dụng cho class trong các hàm tiếp theo. * Bổ sung thêm tuỳ chọn tham số `show_log` trong các class của Vnstock, bạn có thể tắt log message (các hiển thị cảnh báo) bằng cách đặt `show_log=False`. * Khắc phục lỗi định dạng `NoneType Object` khi không nhập mã chứng khoán trong Listing class với câu lệnh: ``` from vnstock3 import Vnstock stock = Vnstock().stock(source='VCI') ``` * Khắc phục lỗi 404 khi truy cập dữ liệu giá từ module Quote của VCI do API url thay đổi. * Khắc phục lỗi không nhận diện các mã chỉ số khi tra cứu lịch sử giá từ module Quote.history. Các mã chỉ số chuẩn sử dụng cho tra cứu thị trường chứng khoán Việt Nam gồm: VNINDEX, HNXINDEX, UPCOMINDEX * Bổ sung khả năng lấy dữ liệu giá lịch sử cho Trái phiếu niêm yết & nâng cấp cơ chế nhận diện loại tài sản với khả năng nhận diện mã nhập vào là Trái phiếu. ## 15-10-2024 ### vnstock Cập nhật phiên bản mới, gỡ lỗi một số vấn đề phát sinh được báo lỗi: -Lỗi khi gọi lịch sử giá: [issue 147](https://github.com/thinh-vu/vnstock/issues/147) * Bổ sung cơ chế báo lỗi khi dữ liệu trả về không như mong muốn với BCTC: [issue 133](https://github.com/thinh-vu/vnstock/issues/133#issuecomment-2395270403) ## 12-08-2024 ### vnstock Cập nhật mã nguồn phiên bản 0.3.0.7 * Sửa lỗi mốc thời gian giá lịch sử không ổn định. Hiện tại có thể lấy thông tin giá lịch sử thuộc tất cả các khung thời gian với tham số `end` là ngày hiện tại. Mã báo lỗi 135: [tại đây](https://github.com/thinh-vu/vnstock/issues/135) * Bổ sung cơ chế xử lý lỗi khi thông tin `event_desc` trả về trong DataFrame không chứa thành phần HTML cần chuyển đổi thành văn bản. Mã báo lỗi 141 [tại đây](https://github.com/thinh-vu/vnstock/issues/141#issuecomment-2271610641) * Sửa lỗi & cải thiện phương thức lấy dữ liệu báo cáo tài chính từ VCI: * Sửa lỗi tên biến `UNIT_MAPPING` không khớp * Tự động loại bỏ dữ liệu N/A trong báo cáo tài chính. Việc này giúp loại bỏ các dữ liệu không có ý nghĩa và trùng lặp tên cột. Bạn có thể tuỳ chỉnh sử dụng tham số dropna=False để chỉ định giữ lại dữ liệu nguyên bản (có thể trùng lặp tên cột - khác ý nghĩa dữ liệu) và N/A. * Kế thừa mô-đun kết nối DNSE từ phiên bản Vnstock Legacy. Mô-đun này không còn trong thư viện hiện hành. * Bổ sung thông tin gói phụ thuộc * Bổ sung phiên bản cố định cho các gói phụ thuộc vào file [requirements.txt](https://github.com/thinh-vu/vnstock/blob/main/requirements.txt) * Bổ sung `seaborn` vào danh sách gói phụ thuộc để loại bỏ lỗi khi cài đặt trên máy tính mới không có sẵn `seaborn`. ## 10-07-2024 ### vnstock Cập nhật mã nguồn phiên bản 0.3.0.6 * Chuyển đổi mã nguồn Vnstock Legacy sang Vnstock3 cho bộ công cụ gửi tin nhắn qua Telegram, Lark, Slack [tại đây](/docs/vnstock/gui-tin-nhan-telegram-slack-larksuite). * Chuyển đổi mã nguồn module `fund.py` từ Vnstock Legacy sang Vnstock3 [tại đây](/docs/vnstock/quy-mo-fund). * Loại bỏ cơ chế bắt buộc người dùng chấp nhận điều khoản, điều kiện rõ ràng. Mặc định, bạn chấp nhận điều khoản & điều kiện khi tiếp tục sử dụng Vnstock3. * Sửa lỗi và cải thiện trải nghiệm: * Xác thực thông tin mã quỹ nhập vào [tại đây](https://github.com/thinh-vu/vnstock/issues/118) * Lỗi khi lấy giá lịch sử theo tháng [tại đây](https://github.com/thinh-vu/vnstock/issues/127) ## 21-06-2024 ### vnstock Cập nhật phiên bản 0.3.0.5 * Sửa lỗi không hiển thị đúng múi giờ trong thời gian của bảng giá lịch sử với khung thời gian giờ và phút, chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/131) * Sửa lỗi không cho phép truy xuất thông tin giá từ TCBS nếu `symbol` không phải là mã cổ phiếu. Chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/128) * Bổ sung xác thực thông tin nhập liệu cho hàm `history` * Thời gian bắt đầu phải nhỏ hơn thời gian kết thúc. ## 03-06-2024 ### vnstock Cập nhật phiên bản 0.3.0.3 * Tích hợp khả năng vẽ biểu đồ bằng vnstock_ezchart trực tiếp vào thư viện. Chi tiết [tại đây](/docs/vnstock/bieu-dien-du-lieu) * Tách riêng notebook min hoạ theo chủ đề. Chi tiết [tại đây](https://github.com/thinh-vu/vnstock/tree/main/docs) * Cập nhật hàm truy xuất api_key từ nguồn dữ liệu MSN, khắc phục lỗi truy xuất dữ liệu các loại chứng khoán quốc tế. * Cập nhật nội dung phản ánh các thay đổi của dự án trên Website. ## 25-05-2024 ### vnstock
Hoàn thiện tính năng, sửa lỗi và bổ sung tài liệu hướng dẫn.
* Sửa lỗi tự động ghi đè thông tin mã cổ phiếu theo mã báo lỗi [9547585](https://github.com/thinh-vu/vnstock/discussions/16#discussioncomment-9547585) * Hoàn thiện nhóm hàm chức năng truy xuất dữ liệu tài chính. Hiện tại có thể gọi thuộc tính `finance` từ lớp Vnstock() thay vì gọi hàm từ trực tiếp nguồn dữ liệu kiểu `vnstock3.explorer.vci.finance`. * Cập nhật hàm minh hoạ trong [Demo Notebook](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/vnstock3_demo.ipynb). * Bổ sung tài liệu hướng dẫn chi tiết * [Thông tin niêm yết](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Thông tin công ty](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Báo cáo tài chính](/docs/vnstock/bao-cao-tai-chinh) * Dành cho nhóm phát triển: * Bổ sung cấu trúc thư mục `tests` dùng cho việc kiểm thử gói phần mềm. ## 10-05-2024 ### vnstock
Ra mắt phiên bản Vnstock thế hệ thứ 3 - Vnstock3.
![](/images/Hello_Vnstock3_10-05-2024-97749fc40c003ac445c205b3215bed4c.png) ## 06-05-2024 ### vnstock_data #### Vnstock Data Explorer
Cập nhật phiên bản Vnstock Data 2.1.1 sửa lỗi hàm Intraday sau khi triển khai hệ thống KRX từ 5/5/2025 và cải thiện trải nghiệm người dùng.
* [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Gỡ một thư viện phụ thuộc bên ngoài không còn cần thiết * [Issue 172](https://github.com/thinh-vu/vnstock/issues/172): Bổ sung hàm `price_board` cho Trading class thuộc nguồn dữ liệu VCI * [Issue 178](https://github.com/thinh-vu/vnstock/issues/178) và sửa lỗi dữ liệu Intraday sau cập nhật hệ thống KRX cho nguồn VCI và MAS. * Đóng [Issue 169](https://github.com/thinh-vu/vnstock/issues/169) vì dữ liệu khung thời gian `1W` đã được hỗ trợ sẵn trong thư viện. * [Issue 166](https://github.com/thinh-vu/vnstock/issues/166) Cập nhật thiết lập rate limit cho các nguồn dữ liệu trong gói quyền sử dụng, tránh hiển thị nhầm thông báo nâng cấp. ## 02-04-2024 ### vnstock
Cập nhật tài liệu hướng dẫn và sửa đổi nhỏ cho hàm gửi tin nhắn Telegram.
## 23-01-2024 ### vnstock
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app *
### vnstock
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 0.2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app ## 21-01-2024 ### vnstock * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ### vnstock * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ## 03-01-2024 ### vnstock * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ### vnstock * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ## 02-01-2024 ### vnstock * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. ### vnstock * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. ## 24-12-2023 ### vnstock * Cập nhật tài liệu dự án * Tài liệu truy xuất giá lịch sử * Hướng dẫn truy xuất dữ liệu giao dịch nước ngoài/tự doanh sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ### vnstock * Cập nhật tài liệu dự án * Tài liệu truy xuất giá lịch sử * Hướng dẫn truy xuất dữ liệu giao dịch nước ngoài/tự doanh sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ## 16-12-2023 ### vnstock * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data`. * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program. * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ### vnstock * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data`. * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program. * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ## 14-12-2023 ### vnstock Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. * Cập nhật tài liệu dự án ### vnstock Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. * Cập nhật tài liệu dự án ## 10-12-2023 ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ## 09-11-2023 ### vnstock > Phát hành phiên bản 0.2.8.5 * Cập nhật hàm `stock_intraday_data` * Bổ sung tham số `investor_segment`, mặc định nhận giá trị `True` cho phép trả về dữ liệu khớp lệnh theo phân nhóm nhà đầu tư (như các phiên bản trước), khi đặt là `False` cho phép trả về dữ liệu thô, không gộp thông tin lệnh theo phân nhóm. * Bổ sung hàm `amibroker_ohlc_export` cho phép xuất dữ liệu sang định dạng CSV để nạp dữ liệu cho Amibroker. * Bổ sung hướng dẫn tích hợp vnstock với dự án sử dụng thư viện phân tích kỹ thuật TA-lib python. * Giới thiệu một số thư viện Backtesting trong python giúp nghiên cứu định lượng trên dữ liệu lịch sử. ## 08-11-2023 ### vnstock > Phát hành phiên bản 0.2.8.4 * Tùy biến hàm `stock_historical_data` giúp dễ dàng sử dụng với các thư viện phân tích kỹ thuật khác trong Python. * Thêm tham số `decor`, nhận giá trị mặc định là `False` (không thay đổi dữ liệu trả về với cách sử dụng hiện tại của người dùng). Khi đặt `decor=True`, áp dụng thay tên các cột trong DataFrame trả về dưới dạng Title Case tức `Open, High, Low, Close, Time, Ticker` thay vì `open, high, low, close, time, ticker` như hiện tại đồng thời đặt cột Time là index. Việc này giảm bớt cho người dùng phải viết thêm câu lệnh khi sử dụng dữ liệu vnstock kết hợp các thư viện phân tích kỹ thuật phổ biến vốn dùng thư viện Yahoo Finance làm nguồn cấp dữ liệu. * Bổ sung tham số `source` cho phép chọn nguồn tải dữ liệu là `TCBS` hay `DNSE`. Nguồn dữ liệu `TCBS` cho lấy dữ liệu lịch sử theo ngày (resolution = `1D`) trong thời gian dài, không hỗ trợ khung thời gian nhỏ hơn. Trong khi đó nguồn dữ liệu `DNSE` cho phép lấy dữ liệu với nhiều khung thời gian khác nhau, giới hạn 90 ngày gần nhất đối với dữ liệu phút, 10 năm gần nhất đối với dữ liệu ngày. * Cập nhật lớp kết nối nguồn TCBS ## 05-11-2023 ### vnstock * Tích hợp kết nối DNSE Lightspeed API (không còn trong thư viện hiện hành). Phát hành phiên bản 0.2.8.2. Sử dụng lệnh `pip install -U vnstock` để cập nhật phiên bản. ## 29-10-2023 ### vnstock * Tích hợp API endpoints cơ bản của DNSE vào vnstock * Demo cho các nhà đầu tư cách tạo 1 request và kết nối hệ thống DNSE để lấy JWT token * Demo xuất thông tin tài khoản * Cập nhật tài liệu sử dụng ## 27-10-2023 ### vnstock * Bổ sung và hoàn thiện một số hàm cho vnstock * Hàm `listing_companies` nay được cung cấp thêm khả năng lấy danh sách công ty niêm yết từ SSI/FiinTrade. Việc này giúp người dùng có thể tham chiếu mã công ty từ mã cổ phiếu để lấy thông tin trong một số trường hợp đặc biệt FiinTrade sử dụng mã này thay cho mã cổ phiếu. Ví dụ, thay vì dùng mã cổ phiếu `BCM` gây ra lỗi cho hàm, bạn cần sử dụng mã công ty tương ứng là `BIDC` * Hàm `indices_listing` cho phép liệt kê tất cả mã chỉ số hiện có trên sàn. * Hàm `financial_ratio_compare` cho phép so sánh chỉ số tài chính của một danh sách các mã cổ phiếu. ## 26-10-2023 ### vnstock * Khôi phục các hàm lấy dữ liệu từ nguồn SSI gồm `financial_report`, `fr_trade_heatmap`, `market_top_mover` sau khi nguồn SSI mở lại khả năng truy cập cho các nhóm dữ liệu này. * Cập nhật tài liệu sử dụng kèm theo * Cập nhật Demo Notebook ## 25-10-2023 ### vnstock * Bổ sung hướng dẫn xuất dữ liệu sang các định dạng phổ biến bao gồm CSV, Excel, và dữ liệu cho Amibroker. * Thử nghiệm tính năng Blog của Mkdocs Matterial cho chuyên mục Kiến thức. ## 21-10-2023 ### vnstock * Giới thiệu cách sử dụng vnstock trong Google Sheets với Neptyne for Google Sheets. * Di chuyển mục nội dung vnstock cho Google Sheets sang tab `Ứng dụng & Tích hợp` ## 20-10-2023 ### vnstock * Chuyển đổi nền tảng tài liệu từ Pretty-Docs sang [MkDocs Matterial](https://squidfunk.github.io/mkdocs-material/) thân thiện và nhiều tính năng hữu ích hơn. * Cập nhật mô tả các hàm để tiện theo dõi bao gồm: * Xoay DataFrame kết quả trả về để có thể hiển thị đầy đủ tên các cột dữ liệu * Bổ sung mô tả tham số đầu vào của hàm ## 14-10-2023 ### vnstock > Phiên bản: 0.2.2: Đưa tính năng vẽ đồ thị chính thức vào phiên bản ổn định, cập nhật hàm truy xuất giá lịch sử * Cập nhật hàm `stock_historical_data` để trả về thông tin chính xác * Loại bỏ bước tính toán nhân chỉ số và mã phái sinh với 1000 khi trả về dữ liệu. Cách tính này làm sai lệch giá trị của chỉ số và mã phái sinh vì bản chất giá trị OHLC này khác với giá cổ phiếu. * Bổ sung thêm tham số **beautify**, đặt giá trị mặc định là True để giữ nguyên cách nhân 1000 cho giá cổ phiếu. Người dùng có thể chuyển về False để giữ nguyên giá trị OHLC dạng thập phân rút gọn. * Chính thức đưa các hàm vẽ đồ thị vào phiên bản chính thức của vnstock sau quá trình thử nghiệm * Hàm **candlestick_chart** cho phép vẽ đồ thị nến cùng các đường trung bình động, hỗ trợ, kháng cự cơ bản. ![candlestick](/images/VIC_candlestick.png) * Hàm **bollinger_bands_chart** cho phép vẽ đồ thị nến (hoặc đường) kèm các dải Bollinger Bands. Hàm này cần sử dụng kèm hàm **bollinger_bands** để chuyển đổi dữ liệu OHLC tiêu chuẩn sang dữ liệu Bollinger Bands. ![bollinger bands](/images/bollinger_bands_chart.png) ## 10-10-2023 ### vnstock * Hàm **listing_company** được điều chỉnh để hỗ trợ truy xuất danh sách mã cổ phiếu cập nhật trực tiếp qua API. * Bổ sung tham số **live** nhận giá trị True hoặc False, mặc định là False cho phép truy xuất danh sách cổ phiếu từ tệp csv lưu trữ trên Github. Cấu trúc của file dữ liệu cục bộ chứa thông tin đầy đủ hơn so với chế độ trực tiếp. * Loại bỏ tham số **path** ## 06-10-2023 ### vnstock > Thay đổi cấu trúc thư mục và tài liệu vnstock repo trên Github * Tái cấu trúc cây thư mục của vnstock repo trên Github * Chuyển toàn bộ file markdown vào thư mục **docs** trừ file README (Tiếng Việt). * Chuyển thư mục **src** vào bên trong thư mục **docs** và đổi tên thành **resources**. Các file ảnh đính kèm dự án được đưa vào sâu hơn 1 cấp bên trong thư mục **images**. * Đơn giản hóa nội dung file README của repo. Đưa tất cả tài liệu hướng dẫn vào vnstock docs. * Bổ sung cơ chế kiểm tra mã phản hồi (status_code) của API trước khi trả về dữ liệu cho hàm **stock_intraday_data** ## 05-10-2023 ### vnstock > vnstock docs Phiên bản 1.1 sử dụng Pretty-Docs theme Thử nghiệm thành công và ra mắt phiên bản thử nghiệm 1.0 cho trang tài liệu vnstock docs sử dụng pretty-docs theme. ## 22-08-2023 ### vnstock * Cập nhật tệp dữ liệu **listing_companies** lên phiên bản mới nhất. * Cập nhật hàm **financial flow** * Thêm tham số **get_all** để lấy tất cả dữ liệu có sẵn hoặc chỉ dữ liệu mới nhất (5 năm hoặc 10 quý). * Cập nhật Demo Notebook để minh họa các thay đổi mới nhất. ## 24-07-2023 ### vnstock * Bắt đầu triển khai hàm truy xuất dữ liệu chứng khoán phái sinh. * Kết hợp một hàm sàng lọc cổ phiếu từ TCBS vào thư viện. * Cải thiện hàm stock_historical_data với các cập nhật sau: * Khi độ khung thời gian (resolution) được đặt thành **1D**, cột thời gian sẽ hiển thị theo định dạng ngày **YYYY-mm-dd**. * Thêm một giá trị mới **derivative** cho tham số **type**, cho phép truy xuất dữ liệu phái sinh. * Các tham chiếu hàm trong tệp README đã được cấu trúc theo các tình huống sử dụng thực tế, như Phân tích Kỹ thuật, Phân tích Cơ bản, Sàng lọc Cổ phiếu, vv. Điều này giúp cho tài liệu thân thiện và có tổ chức hơn với người dùng. Phiên bản tiếng Anh của tệp README cũng đã được cập nhật để phù hợp với phiên bản tiếng Việt. ## 22-07-2023 ### vnstock * Bổ sung hướng dẫn vào [Demo Notebook](https://github.com/thinh-vu/vnstock/blob/legacy/demo/gen2_vnstock_demo_index_all_functions_testing_2023.ipynb) giúp người dùng xuất dữ liệu từ Google Colab ra Google Sheets. ## 14-07-2023 ### vnstock * Phát hành phiên bản 0.17 trên PyPI. * Những thay đổi trên nhánh **beta** sẽ được cập nhật vào nhánh **main** và phát hành qua PyPI hàng tháng từ bây giờ. * File README.md đã được cập nhật để đồng bộ hóa phiên bản tiếng Anh và tiếng Việt. * Hàm listing_companies dùng tệp tham chiếu listing_companies_enhanced-2023.csv đi kèm repo. * Hàm mới, price_depth, đã được giới thiệu để lấy giá và khối lượng giao dịch cho danh sách các cổ phiếu. Hàm này có thể được sử dụng song song với hàm price_board. ## 13-07-2023 ### vnstock * Phân loại các tính năng của vnstock trong file Demo Jupyter Notebook theo 5 nhóm chính: 1. Thị trường (Market Watch) 2. Phân tích cơ bản (Fundamental Analysis) 3. Phân tích kỹ thuật (Technical Analysis) 4. Lựa chọn cổ phiếu (Stock Screening) 5. Trung tâm giao dịch (Trading Center) * Đã sửa lại file demo notebook để cập nhật các hàm mới. * Khôi phục giá đơn vị của stock_historical_data từ 1000 VND thành VND bằng cách nhân với 1000. * Hàm **price_board** đã được cập nhật. * Bổ sung hàm mới trong mô đun **utils.py** để trích xuất giá trị ngày tháng theo định dạng YYYY-mm-dd. ## 05-07-2023 ### vnstock * Cập nhật file README.md (áp dụng cho tiếng Việt trước). * Các hàm liên quan đến nguồn dữ liệu SSI không hoạt động đã bị loại bỏ. * Hàm **financial_ratio** đã được cải tiến với các cập nhật sau đây: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị (transpose), với năm/quý đóng vai trò là chỉ mục, giúp sử dụng thuận tiện hơn. * Tham số **is_all** đã trở thành tham số phụ tùy chọn. * Hàm **industry_analysis** và stock_ls_analysis đã được cải thiện: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị, với tên mã cổ phiếu làm tiêu đề cột, giúp dễ sử dụng. * Thêm tham số **lang**, cho phép hiển thị cột DataFrame bằng nhãn tiếng Việt hoặc tiếng Anh. ## 29-06-2023 ### vnstock * Đã cập nhật hàm stock_intraday_data để cung cấp thêm dữ liệu chi tiết trả về bởi hàm và dễ sử dụng hơn * Cập nhật hàm stock_historical_data để hỗ trợ lấy dữ liệu lịch sử về các chỉ số. ## 22-06-2023 ### vnstock * Phát hành phiên bản 0.15 rên Pypi. * Giới thiệu một tính năng mới cho hàm stock_historical_data, cho phép lấy dữ liệu với nhiều độ phân giải thời gian khác nhau. Đã nâng cấp API tương ứng hỗ trợ hàm này. * Bao gồm tham số độ phân giải để cho phép người dùng lấy dữ liệu giá tại các khoảng thời gian 1 phút, 3 phút, 5 phút, 15 phút, 30 phút, 1 giờ hoặc 1 ngày. * Sửa tên cột trong bảng dữ liệu trả về từ tradingDate thành time. * Đã đánh dấu rõ các hàm không khả dụng cho các API liên quan tới SSI. * Tùy chọn **mode='live'** trong hàm listing_companies() đã được loại bỏ. Hàm này bây giờ chỉ đọc danh sách công ty từ tệp csv trên repo github này. * Cập nhật cây thư mục cho github repo, thêm thư mục dữ liệu và thêm tệp dữ liệu, thư mục demo để lưu trữ các tệp demo. ## 07-06-2023 ### vnstock Chính thức hỗ trợ hướng dẫn sử dụng bằng tiếng Việt cho tệp thư viện thông qua file README.md, giúp thúc đẩy khả năng tiếp cận với vnstock cho người dùng Việt Nam. ## 20-05-2023 ### vnstock * Nhánh **main** dành riêng cho các cập nhật quan trọng, trong khi nhánh **beta** được sử dụng cho các cập nhật nhỏ. Từ bây giờ, gói PyPI sẽ phản ánh nội dung của nhánh **main**. * Hàm listing_companies() bây giờ có thể đọc danh sách công ty từ tệp csv trên repo github này hoặc từ một yêu cầu API trực tiếp. * Hàm stock_intraday_data() bây giờ có một giới hạn mới là 100 cho tham số page_size do TCBS thiết lập. --- ## Document: Tự động nạp Agent Skills và tài liệu Cơ chế nạp Agent Skills giống nhau ở cả hai bản, nên chỉ có một tài liệu. Nội dung nằm tại [/docs/tai-lieu/vnstock-agent-skills](/docs/tai-lieu/vnstock-agent-skills). --- ## Document: Lịch sử phiên bản Trang này gom thay đổi của bản Cộng đồng từ nhật ký riêng của từng thư viện, xếp theo ngày. Muốn đọc riêng một thư viện, mở mục Lịch sử phiên bản trong tài liệu của thư viện đó. ## 27-10-2026 ### vnstock_quant (v0.5.0) #### Mô-đun mới: chạy thử chiến lược (`backtest`) `vnstock_quant.backtest` chạy thử chiến lược trên dữ liệu giá bạn chuẩn bị, theo luật thị trường Việt Nam, trong cùng lõi Rust với các nhóm hàm khác: bảng quy tắc dùng đúng 58 chỉ báo của `ta`, tear sheet dùng 33 thước đo của `risk`, chung cấp quyền và cây lỗi của thư viện. Tài liệu: [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu). - **Tín hiệu**: mảng `[-1, 0, 1]`, cặp `entries`/`exits` hoặc bảng quy tắc `rule_dsl` dạng JSON; kiểm thiên lệch nhìn trước tương lai cho cả hàm tín hiệu và bảng quy tắc (`check_causality`, `check_rule_dsl_causality`). - **Luật thị trường**: mặc định lô 100, bước giá theo sàn, biên độ, phiên khóa trần và khóa sàn, T+2.5, thuế bán 0,1% tính riêng ngoài phí; hồ sơ phái sinh VN30F, crypto, cổ phiếu quốc tế, ngoại hối; cổ tức tiền, cổ phiếu thưởng và quyền mua trên giá gốc. - **Khớp lệnh**: chế độ `vn_realistic` và bốn chế độ tái tạo hành vi mặc định của backtesting.py, backtrader, vectorbt, zipline, khớp tới từng lệnh trên 11 kịch bản đối chứng; lệnh giới hạn và lệnh dừng theo phiên, nhiều lô trong một vị thế, chốt lời từng phần, dừng lỗ động, chặn rủi ro cấp tài khoản. - **Danh mục và chống quá khớp**: `run_portfolio` cho nhiều mã chung một tài khoản và tái cân bằng theo tỷ trọng; `sweep`, `walk_forward`, `monte_carlo`, `deflated_sharpe_ratio`. - **Gọi bằng JSON**: `catalog()`, `schema()` và `call()` với 10 công cụ dùng được trực tiếp cho trợ lý AI và Vnstock MCP. - **Lỗi và quyền**: lớp lỗi mới `CausalityViolationError` (`QUANT_CAUSALITY_VIOLATION`); mã `QUANT_QUOTA_LIMIT` (`QuotaExceededError`) khi một lần chạy vượt quy mô của cấp; `vq.entitlement()` có thêm khoá `backtest` và bộ quy tắc `quant_entitlement_v3`. - Backtest một mã với 10 chỉ báo cơ bản trong bảng quy tắc, 3 lượt mỗi ngày. Lượt backtest đếm riêng, không trừ vào 30 phép tính chỉ báo và chỉ số; xem `vq.entitlement()["backtest"]`. - Extra `chart` (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) cài [`vnstock_chart`](/docs/vnstock-chart) để vẽ kết quả chạy thử. #### Mô-đun mới: giá điều chỉnh (`prices`) #### Chỉ số tài chính (`fa`) Các chỉ số nêu sau cho số khác bản 0.4.0; những chỉ số không nhắc tới giữ nguyên. Mỗi thay đổi được kiểm trên dữ liệu thị trường tải ngày 27/10/2026 và trên 64 mã của bộ đối chiếu. Cách tính chi tiết xem ở [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa). - **P/E, P/B, P/S, P/CF, EV/EBITDA kỳ năm**: Lấy giá đóng cửa và số cổ phiếu của cùng một phiên, tại ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4 và P/E bằng giá / EPS trong cùng một dòng. Bản trước lấy giá cuối năm sau nhân với số cổ phiếu của năm báo cáo: chỉ số dùng giá của một năm sau kỳ báo cáo, và thấp hơn thực tế khi có chia cổ phiếu trong năm sau (P/E năm 2024 của VCB ra 9,5 thay vì 14,65; FPT ra 17,9 thay vì 22,2). Tham số `overrides={"year_valuation": ...}` không còn dùng được. - **Dòng quý 4 của chuỗi quý**: Mẫu số bình quân (ROE, ROA, vòng quay, số ngày thu tiền...) là bình quân 4 điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán. Bản trước dùng bình quân đầu năm và cuối năm, làm chuỗi quý nhảy ở mỗi quý 4 (ROE quý 4 của ngân hàng cao hơn trung bình hai quý kề 2,2%; nay −0,3%, ngang các quý khác). ROE quý 4/2025 của FPT từ 28,29% thành 27,25%. Dòng năm không đổi. - **Mô tả ROE trong `fa.describe()`**: Bỏ câu nói hồ sơ `vn` đổi mẫu số từ năm 2022; ROE luôn chia cho vốn chủ của cổ đông công ty mẹ bình quân. - **`fa.Dataset.load()` khi chưa tải được giá**: Nếu cấp của `vnstock` chưa mở giá chưa điều chỉnh, thư viện cảnh báo một lần và vẫn tính các chỉ số từ báo cáo tài chính; chỉ số định giá trả `MISSING_MARKET`. Dùng `prices=False` để bỏ qua bước tải giá. #### Thay đổi khác - **Vi cấu trúc (`micro`)**: Mỗi lần gọi một hàm tính là một lượt, kể cả hàm chạy nhiều bước bên trong như `bars` và `cvd`. - **Đo lượt dùng**: Thư viện không còn hỏi đồng ý đo lượt dùng ở lần chạy đầu. Lựa chọn đặt trên vnstocks.com, mục tùy chọn dữ liệu của tài khoản; chưa chọn thì không đo. Tắt riêng trên máy bằng `vnstock_quant.telemetry.disable()` hoặc biến môi trường `VNSTOCK_TELEMETRY=0`. ## 18-10-2026 ### vnstock_chart (v1.0.0) #### Phát hành dưới tên vnstock_chart - **Đổi tên**: `vnstock_ezchart` thành `vnstock_chart`. Hai gói được cài riêng; nếu đang dùng gói cũ, xem [cách chuyển sang vnstock_chart](/docs/vnstock-chart/khac-biet-voi-ezchart). - **Kênh phát hành**: Cài từ kho phát hành thư viện của Vnstock bằng `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart`. - **Phụ thuộc**: Yêu cầu `vnstock>=5.0`. `squarify` (cho `treemap()`) và `wordcloud` là phụ thuộc tuỳ chọn, cài bằng `vnstock-chart[all]`; thiếu chúng thì các hàm còn lại vẫn chạy. - **Sửa lỗi đóng gói**: Bản cài qua `pip install` có đủ mọi thư mục con, không còn lỗi `ModuleNotFoundError` mà `vnstock_ezchart` 1.0.1 và 1.0.2 gặp. ## 17-10-2026 ### vnstock_quant (v0.4.0) #### Dữ liệu khung phút - **VWAP và pivots**: Đọc được cột thời gian dạng `dd/mm/YYYY HH:MM` và `dd/mm/YYYY HH:MM:SS`. - **Chỉ số tài chính (`fa`)**: Bảng giá theo phút được đọc thành một phiên mỗi ngày, lấy giá của nến cuối ngày (kể cả phiên ATC). Bảng giá ngày không đổi. #### Thay đổi khác - **Thông báo lỗi**: `vwap` với `anchor` không hợp lệ báo `InvalidParameterError` bằng tiếng Việt, giống `micro.cvd`. - **Chú thích hàm**: Chú thích viết bằng tiếng Anh; mô tả ngắn của 58 chỉ báo viết song ngữ (tiếng Anh trước, tiếng Việt sau). Công thức và phương pháp chi tiết xem ở các trang tài liệu. - **Đo lượt dùng**: Câu hỏi đồng ý đo lượt dùng ở lần chạy đầu thống nhất giữa các thư viện thế hệ 5. ## 15-10-2026 ### vnstock > Cập nhật Vnstock 5.0.3 Bản này thay cho 5.0.2 (đã rút khỏi kho phát hành). Hướng đi của thư viện: mọi con số bạn nhận được đều kiểm chứng được. Số liệu một nguồn tự tính theo phương pháp riêng, không công bố cách tính, không còn được cung cấp; phần tính toán do các thư viện tính toán và phân tích của Vnstock đảm nhận, chạy trên máy bạn, theo công thức công khai. ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock ``` **Không còn hỗ trợ.** Các hàm dưới đây giữ tên để mã cũ không lỗi khi import, nhưng gọi là báo `UnsupportedError` mã `VNSTOCK_FEATURE_REMOVED`: * Các hàm cùng loại ở lớp tương thích `vnstock.explorer.asean` (RRG, tín hiệu, chỉ số sợ hãi và tham lam, mua bán chủ động, định giá và dòng tiền ngành, so sánh cùng ngành). **Dòng lệnh** * `vnstock tools` thay cho `vnstock api`: cây các hàm để bạn tự truy xuất dữ liệu. Cây chỉ hiện hàm nên dùng; tên cũ, tên khác, hàm sắp bỏ và không còn hỗ trợ vẫn gọi được và vẫn xem được bằng `vnstock doc`. Gõ `vnstock api` vẫn chạy. * `vnstock onboard` (mới): hướng dẫn ngắn cho trợ lý AI trước khi làm việc với vnstock, gồm phiên bản, cấp và thư viện bổ sung trên máy, quy tắc cần theo, bước tiếp theo theo cấp và các skill cấp đó đọc được. Câu lệnh khởi động trên [vnstocks.com/onboard](https://vnstocks.com/onboard) nay bảo trợ lý chạy lệnh này đầu tiên. * `vnstock skills show ` chỉ in phần giới thiệu công khai của skill (mô tả, cấp cần có, trang giới thiệu); nội dung skill dành cho trợ lý AI đọc trong phiên làm việc. **Cải thiện khác** * Thông tin trích dẫn nguồn trong `df.attrs` (tên nguồn, đường dẫn điều khoản, tuyên bố miễn trừ) được cập nhật từ vnstocks.com, không cần chờ bản mới. * Gói cài nhẹ hơn: thư viện lõi trên macOS ARM giảm từ 10,3 MB xuống 7,9 MB. ## 12-10-2026 ### vnstock_mcp (v0.4.0) #### Bản đầu tiên có tài liệu - **Cầu nối chạy cục bộ**: Trợ lý AI trên máy bạn khởi chạy tiến trình `vnstock-mcp` từ môi trường Python cá nhân; không có máy chủ trung gian đứng giữa. - **Kết nối bằng một lệnh**: `vnstock-mcp --setup <ứng dụng>` in sẵn cấu hình cho Claude Desktop, ChatGPT desktop, Gemini Tasks, Claude Code, Codex, Antigravity, VS Code và Cursor; thêm `--write` để ghi thẳng vào tệp cấu hình. - **Mã tham chiếu và mã Python tái lập**: Mỗi kết quả lưu trong không gian làm việc cục bộ kèm mã `call_id` (`c1`, `c2`...) và ghi vào nhật ký phiên. `research_journal(method="script")` xuất các bước đã chạy thành một tệp Python độc lập. - **Công cụ nghiên cứu**: `research_normalize` chuẩn hoá bảng về cột chuẩn của Vnstock, `research_benchmark` đối chiếu số liệu, `research_universe` tra danh mục chỉ tiêu VAS. Các mô-đun `vnstock_quant` gọi được trên bảng đã chuẩn hoá qua `data="c1"`. - **Lọc công cụ theo hồ sơ và quyền**: Trợ lý AI chỉ thấy công cụ khả dụng với tài khoản và hồ sơ (`--profile`) bạn chọn. - **Số công cụ và dùng thử**: Bản Cộng đồng mở 29 công cụ (hồ sơ `full`) hoặc 21 (hồ sơ `research`), kèm 30 lượt dùng thử định lượng mỗi ngày. ## 10-10-2026 ### vnstock_quant (v0.1.3) - **Thư viện xác thực**: Ghim `vnstock-auth` ở bản 0.5.1, thống nhất với các thư viện thế hệ 5 khác. Không đổi cách tính. ## 09-10-2026 ### vnstock_quant (v0.1.2) - **Giữ chỉ mục đầu vào**: Kết quả chỉ báo giữ nguyên chỉ mục của bảng bạn truyền vào. Cột thời gian chỉ được dùng cho `vwap` và `pivots`. - **Nhận cột thời gian**: Với bảng dữ liệu thô, thư viện tự nhận cột thời gian và chuyển thành `DatetimeIndex`. - **Gọi lớp chính gọn hơn**: Các lớp chính nhập được thẳng từ `vnstock_quant`; thông báo lỗi rõ hơn khi thiếu cột. ## 08-10-2026 ### vnstock_quant (v0.1.1) - **Hạn dùng bản phát hành**: Thư viện kiểm tra hạn dùng của bản cài trước khi tính; thông tin hạn dùng xem ở `vq.entitlement()["release"]`. - **Chú thích song ngữ**: Chú thích hàm của các mô-đun `ta`, `fa`, `risk`, `portfolio`, `valuation` có cả tiếng Việt và tiếng Anh. - **Bản hết hạn**: Bản đã hết hạn báo lỗi `VNSTOCK_RELEASE_EXPIRED` kèm lệnh cập nhật. ### vnstock_quant (v0.1.0) #### Bản phát hành đầu tiên của Vnstock Quant thế hệ 5 - **Dùng thử mỗi ngày**: Bản Cộng đồng có 30 lượt dùng thử (30 phép tính) mỗi ngày cho 10 chỉ báo kỹ thuật cơ bản và 10 chỉ số tài chính VAS. Tra cứu số lượt còn lại bằng `vnstock_quant.entitlement()` (khoá `trial`). - **Gói cài đặt dựng sẵn**: Gói nhị phân dựng sẵn (binary wheels) dùng chung cho Python 3.10 trở lên, trên macOS (Intel và Apple Silicon) và Linux x86_64/aarch64 dùng glibc 2.17 trở lên. - **Đối chiếu chỉ báo**: Kết quả 58 chỉ báo kỹ thuật được đối chiếu với TA-Lib C 0.8.1 và QuantConnect LEAN. - **Kiểm tra tham số**: Tham số nến không hợp lệ báo lỗi `InvalidParameterError` thay vì trả kết quả sai lệch. - **Tái cấu trúc từ vnstock_ta sang vnstock_quant**: Gộp và nâng cấp thư viện `vnstock_ta` sang namespace mới `vnstock_quant` với lõi tính toán biên dịch bằng Rust (`_native.abi3.so`). - **58 chỉ báo kỹ thuật hiệu năng cao**: Tính đủ 58 chỉ báo nhanh hơn 25,9 lần so với phiên bản cũ (5.000 phiên, số đo tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026); lõi Rust nhả khoá GIL của Python trong lúc tính. - **Khắc phục lỗi thuật toán**: Sửa 16 chỉ báo bị sai lệch công thức trong phiên bản cũ (bao gồm CCI, KST, PSAR, Supertrend, Squeeze, OBV, MFI). - **Giữ cú pháp gọi hàm**: Lớp `Indicator` giữ nguyên tên 58 phương thức chỉ báo, tên và giá trị mặc định của tham số; chuyển đổi bằng cách đổi tên gói khi import. Một số chỉ báo cho số khác bản cũ, xem [danh sách khác biệt](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta). #### Giao diện gọi hàm JSON cho trợ lý AI - **Chẩn đoán cấp quyền và bản build**: Bổ sung hai hàm chẩn đoán chạy cục bộ `vq.entitlement()` và `vq.build_info()`, hỗ trợ theo dõi lượt dùng thử của bản Cộng đồng và kiểm tra tính toàn vẹn của lõi Rust. ## 06-10-2026 ### vnstock > Cập nhật Vnstock 4.1.1 và Vnstock 5.0.0a3 Một số nhóm dữ liệu đã được gỡ khỏi thư viện. Các hàm dưới đây không còn trả dữ liệu: * **Giá vàng trong nước:** `Retail().gold()` (cả `source="sjc"` và `source="btmc"`), `sjc_gold_price()`, `btmc_goldprice()`. Tỷ giá ngoại tệ `Retail().exchange_rate()` giữ nguyên. * **Quỹ mở:** `Fund()`, `Market().fund`, `Reference().fund` (danh sách quỹ, NAV, danh mục nắm giữ). * **Riêng Vnstock 5.0.0a3:** gỡ thêm `Fundamental().equity(...).filing()`, các chuỗi vĩ mô sản xuất công nghiệp, doanh thu bán lẻ, dân số và lao động, và lãi suất (`interest_rate()`) của nhóm vĩ mô. ## 26-09-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.9 Bản này tập trung vào bảo mật và trả lại quyền kiểm soát cho bạn khi dùng Vnstock cùng trợ lý AI. Cần `vnai` 2.6.2 trở lên, nên hãy cập nhật cả hai gói: ```bash pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai ``` **Bảo mật** * **`import vnstock` không còn tự ghi tệp nào.** Ở các bản trước, mỗi lần `import vnstock`, thư viện tự chèn một đoạn hướng dẫn vào tệp quy tắc của trợ lý AI: `AGENTS.md` trong dự án và mặc định cả tệp dùng chung toàn máy của Claude Code, Codex, Antigravity. Nội dung đoạn này tải từ vnstocks.com lúc ghi, nên có thể thay đổi mà bạn không hề hay biết, và bạn cũng chưa từng yêu cầu. Từ bản này: * Tính năng chỉ chạy khi bạn chủ động bật: `enable_agent()` rồi `setup_agent()`. * Mặc định chỉ ghi vào `AGENTS.md` của dự án; tệp toàn cục chỉ được ghi khi bạn chỉ định. * Nội dung được đóng gói sẵn trong `vnai`, không tải từ máy chủ nữa. * Nếu máy còn đoạn cũ do bản trước để lại, thư viện chỉ in một thông báo một lần, không tự sửa gì. Muốn gỡ sạch, chạy `vnstock.remove_agent_files("all")`. * **Tài liệu chủ đề ghi rõ nguồn gốc.** Nội dung trả về từ `load_skill()` mở đầu bằng dòng cho biết đây là tài liệu tải về và tải từ đâu. Tên chủ đề chỉ nhận dạng tên đơn giản, để trợ lý AI không thể dẫn lượt gọi mang API key của bạn tới địa chỉ khác. Bỏ lớp "mã hoá" XOR cho tài liệu người dùng gói quyền sử dụng: nó không bảo vệ được gì mà chỉ khiến bạn khó kiểm tra trợ lý AI đang đọc gì. * **Quảng cáo không thể chạy mã.** Nội dung quảng bá hiển thị trong Jupyter được lọc bỏ script, frame, trình xử lý sự kiện và liên kết `javascript:`; văn bản trong terminal được lọc ký tự điều khiển. Khi đầu ra đang bị ghi lại (ví dụ trợ lý AI chạy lệnh), thư viện chỉ hiện nội dung đóng gói sẵn, không hiện nội dung từ máy chủ. * **`register_user()` nhập API key ở chế độ ẩn**, không còn hiện key trên màn hình hay lưu lại trong đầu ra của notebook. Nếu biến môi trường `VNSTOCK_API_KEY` đã có, hàm đề nghị lưu luôn key đó. Truyền key trực tiếp làm tham số vẫn chạy nhưng không khuyến khích. **Thay đổi khác** * Chú thích trong mã từng viết riêng cho trợ lý AI nay là tài liệu lập trình thông thường; `migrate_to_sponsor()` cũng thôi in dòng nhắn gửi "AI Agent". * `migrate_to_sponsor(dry_run=True)` liệt kê những thay đổi sẽ thực hiện mà không ghi tệp, và hàm trả về số tệp đã đổi. * `setup_agent()` chạy trực tiếp thay vì chạy nền, tránh trường hợp hai tiến trình cùng ghi làm lặp đoạn hướng dẫn. Tham số `async_mode` vẫn nhận nhưng không còn tác dụng. * `register_user()` không còn in nhầm "bạn đang dùng bản Cộng đồng" sau khi lưu key của người dùng gói quyền sử dụng. * README cập nhật lệnh cài từ kho phát hành thư viện của Vnstock và mô tả cơ chế bật/tắt hướng dẫn cho trợ lý AI. ## 25-09-2026 ### vnstock > Đổi lệnh cài đặt `vnstock` và `vnai` Từ phiên bản này, hai gói `vnstock` và `vnai` được cài từ kho phát hành thư viện của Vnstock. Lệnh cài và lệnh cập nhật cho bản Cộng đồng: ```bash pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai ``` * Lệnh cũ `pip install -U vnstock` sẽ báo `Could not find a version that satisfies the requirement vnai`. Thêm phần `--extra-index-url` như trên là cài được. * Phần `--extra-index-url` chỉ bổ sung thêm một nơi tìm gói; các thư viện khác như `pandas` vẫn tải từ PyPI như cũ. * Nhà tài trợ không cần làm gì thêm: trình cài `vnstock-installer` và trình cài dòng lệnh vốn đã dùng kho phát hành này. Khi cài lại trình cài giao diện, ghim đúng phiên bản: `pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.2`. * Nhờ trợ lý AI cài hộ thì dẫn nó tới `vnstocks.com/files/vibe-onboarding.md`. Tệp hướng dẫn này đã có sẵn các bước cài đặt và cập nhật mới. ## 15-09-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.8 **Tính năng chính: tôn trọng tín hiệu từ chối của nguồn** * **Dừng gọi khi nguồn từ chối, tạm ngừng theo từng máy chủ.** Khi nguồn từ chối lượt gọi hoặc báo giới hạn tần suất, thư viện nay **dừng ngay thay vì thử lại**, để không tạo thêm tải lên hệ thống của nguồn. Sau đó thư viện tạm ngừng gọi tới chính máy chủ đó trong một khoảng thời gian; các lượt gọi trong khoảng này báo lỗi ngay mà không mở kết nối. * **Thời gian tạm ngừng mặc định**: 60 giây khi bị giới hạn tần suất, 300 giây khi nguồn yêu cầu xác minh hoặc từ chối truy cập. Nếu máy chủ có nói rõ cần chờ bao lâu thì thư viện tôn trọng con số đó. Thời gian chờ chỉnh được qua `Config`; `reset_circuit()` xoá trạng thái tạm ngừng. * **Nhóm lỗi mới để bắt đúng tình huống**: `DataSourceBlockedError` cùng các lỗi cụ thể `RateLimitedError`, `ChallengeRequiredError`, `AccessDeniedError`, `CircuitOpenError`. Mỗi lỗi mang theo địa chỉ, máy chủ, mã trạng thái và thời gian chờ còn lại. Code cũ bắt `except ConnectionError` vẫn hoạt động bình thường. * **Chỉ thử lại những lỗi thật sự thoáng qua.** Lỗi mạng chập chờn được thử lại; lỗi do nguồn từ chối, tham số sai hay phương thức không được hỗ trợ thì hiện ra ngay với đúng thông báo gốc, thay vì bị nuốt sau nhiều lần thử vô ích. **Thay đổi cần lưu ý** * **Loại bỏ cấu hình proxy**: Gỡ bỏ các tham số `proxy_config`, `proxy_mode` và `proxy_list` khỏi constructor của `Quote`, `Trading`, `Finance`, `Listing`, `Company` ở cả nguồn KBS và VCI, cùng các tiện ích proxy đi kèm. **Code truyền các tham số này sẽ báo lỗi `TypeError`** — hãy bỏ chúng đi. * **Ngừng hỗ trợ `random_agent`**: Tham số này không còn tác dụng (sẽ hiện cảnh báo nếu dùng); hãy bỏ nó khỏi mã của bạn. * **`RateLimitError` nay là tên gọi khác của `RateLimitedError`**: `except RateLimitError` vẫn chạy, nhưng lỗi này đã chuyển sang nhóm "bị nguồn từ chối" nên không còn được tự động thử lại. Lớp cũ chưa từng được ném ra ở đâu nên không có đoạn mã nào đổi hành vi. **Cải thiện** * Đơn giản hoá tầng gửi yêu cầu trong `vnstock.core.utils.client`, giảm số nhánh xử lý và giúp thông báo lỗi dễ đọc hơn. * **Bật/tắt được phần tự tạo tệp hướng dẫn cho AI**: bổ sung `agent_status()`, `disable_agent()`, `enable_agent()` và `remove_agent_files()` vào API công khai. Thư viện chỉ ghi `AGENTS.md` trong dự án và tệp ghi nhớ toàn cục của ba công cụ được hỗ trợ; các đường dẫn cũ không còn được ghi và `remove_agent_files("legacy")` dọn sạch máy đã lỡ nhận chúng. * **`except VnstockError` nay bắt được mọi lỗi của thư viện.** Nhóm lỗi nguồn từ chối trước đó nằm ngoài cây `VnstockError` nên ai dùng cách bắt này sẽ bỏ lọt đúng nhóm lỗi cần xử lý nhất. **Tài liệu & giấy phép** * Làm rõ điều kiện giấy phép trong README: bản công khai mã nguồn trên GitHub theo giấy phép riêng, miễn phí cho mục đích cá nhân, học tập và nghiên cứu. Đây không phải giấy phép nguồn mở theo chuẩn OSI; phân phối lại và mục đích thương mại cần văn bản chấp thuận từ tác giả. * Bổ sung phần miễn trừ trách nhiệm và điều kiện giấy phép cho bản tiếng Anh của README, trước đây chỉ có ở phần tiếng Việt. * Bổ sung tuyên bố Vnstock không liên kết, không được tài trợ hay chứng thực bởi bất kỳ tổ chức nào được nhắc tới trong tài liệu và mã nguồn. Vnstock cấp quyền sử dụng phần mềm, không cấp quyền sử dụng dữ liệu; điều kiện của từng nguồn do bạn tự kiểm tra và tuân thủ. * Bổ sung ghi chú về dữ liệu ẩn danh của môi trường chạy được ghi nhận nhằm cải thiện hiệu năng và độ ổn định. ## 16-05-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0.3 **Bổ sung** * **Giao dịch Trái phiếu**: Bổ sung cấu trúc dữ liệu trái phiếu vào tầng giao diện Unified UI, đồng nhất kiến trúc với bản Mở rộng và bổ sung các hàm ohlcv, trades, quote. * **InstrumentType Enum**: Thêm phân loại định danh chứng khoán chuyên sâu để chuẩn hoá việc nhận diện các loại tài sản tài chính. **Thay đổi & Cải thiện** * Bổ sung danh sách các chỉ số index từ HNX, UPCOM và cải thiện khả năng nhận diện symbol qua hàm get_asset_type chính xác hơn với hỗ trợ các mã index mới. * **Dữ liệu Báo cáo Tài chính**: Hỗ trợ hệ số nhân (`unit_multiplier`), ánh xạ nhất quán cấu trúc cột dữ liệu giữa các nguồn KBS và VCI. * **Xử lý Nguồn dữ liệu (MSN & VCI)**: Xây dựng cơ chế resolve mã `SecId` động cho nguồn MSN để sửa lỗi truy xuất dữ liệu lịch sử; sửa lỗi kết nối nguồn VCI và kiểm tra an toàn URL khi tải danh sách mã. ## 27-04-2026 ### vnstock > Cập nhật phiên bản Vnstock 4.0 **Thư viện dữ liệu** * Sửa lỗi truy cập dữ liệu từ nguồn VCI cho các module thông tin niêm yết (Listing), thông tin công ty (Company), và thông tin BCTC (Finance). Thay thế cơ chế lấy dữ liệu từ GraphQL sang REST API mới của Vietcap. * Sửa lỗi tham số `to_df` bị thiếu gây ngừng chương trình. * Cập nhật Unified UI (giao diện người dùng hợp nhất): cung cấp cách thức sử dụng hệ thống class/method chuẩn hoá cho toàn thư viện, thương thích với cách đặt tên và tiêu chuẩn của bản Mở rộng đã giới thiệu trước đó. **Tiện ích** * Cải thiện khả năng sử dụng Google Colab thuận tiện hơn khi không yêu cầu kết nối Google Drive bắt buộc. * Cải thiện logic phát hiện phiên bản phần mềm của hệ sinh thái vnstock đã cập nhật để không hiện lại thông báo phiền phức. **Tài liệu** * Cập nhật Vnstock Agent Guide với các hướng dẫn mới nhất hỗ trợ chuyển đổi code sử dụng class Vnstock sẽ bị loại bỏ từ 1/9/2026 vào skill `vnstock-migration-expert`. **Thông báo** * Hiển thị cảnh báo ngừng hoạt động cho lớp hàm Vnstock thường được sử dụng qua lệnh `from vnstock import Vnstock` sẽ kết thúc hỗ trợ vào 31/8/2026. * Thông báo nâng cấp đi kèm hướng dẫn chuyển đổi code sang các lớp hàm tương đương trong thư viện. * Agent Skills hỗ trợ việc chuyển đổi được bố sung hướng dẫn trong Vnstock Agent Guide. ## 05-04-2026 ### vnstock
Bản cập nhật v3.5.1 mang đến những bước tiến lớn trong trải nghiệm lập trình AI (Vibe Coding) và hỗ trợ cập nhật cấu trúc nền tảng êm ái hơn bao giờ hết.
**Tính năng bổ sung nổi bật** * **Chuẩn hóa API cột dữ liệu (Module KBS)**: Mình đã thiết kế lại định danh tên cột dữ liệu chứng khoán nhằm khớp chính xác 100% với giao diện trên terminal của phần mềm KBS thực tế. * Cột `total_trades` 👉 `volume_accumulated` (tổng khối lượng) * Sinh thêm cột ánh xạ 👉 `volume_last` (khối lượng khớp lệnh lần cuối). **Lưu ý cho bạn**: Anh em đang phân tích DataFrame dựa vào các key trên nhớ cập nhật lại tên hàm nhé để pipeline hệ thống tiếp tục chạy ổn định. * **Hệ thống Nhận diện Môi trường (Auto-Detection Guardrail)**: Vnstock nay trở nên tinh tế hơn bao giờ hết: Nếu nhận thấy bạn đang ở tư cách thành viên Sponsor của mình nhưng lại vô tình nhập các hàm phân tích của gói cơ bản, hệ thống sẽ tự động nhắc nhở và điều hướng để hỗ trợ bạn dùng đúng các hàm của bản Mở rộng mà bạn đã đăng ký. * **Tối ưu hóa Vibe Coding cùng AI**: Vnstock dồn tâm huyết phát triển các chỉ báo hệ thống ngầm (System Prompts) thiết kế đặc biệt dành cho các AI Agent khi phân tích mã nguồn. Giờ đây, các AI sẽ tự nhận diện rõ năng lực của API và đóng vai trò người cố vấn thay vì cố gắng tự gỡ rối hoặc rò rỉ mã lỗi. Chúng sẽ giúp bạn phân tích khi nào việc nâng cấp lên bản Mở rộng sẽ mang lại giá trị cao hơn nhiều việc cắm cúi code. *** ## 07-03-2026 ### vnstock
Phiên bản 3.5.0 mang tính bản lề trong việc tái cấu trúc thư viện, tập trung loại bỏ các nguồn cấp thiếu ổn định và chuẩn hóa điểm dữ liệu để hướng tới sự tương thích với AI (Vibe Coding).
**Các thay đổi quan trọng (Breaking Changes)** * **Tinh gọn các kết nối nguồn**: Để bộ công cụ tinh gọn và vận hành ổn định, Vnstock ngừng các module kết nối tới TCBS và bộ lọc cổ phiếu (Screener). **[Mở rộng]** Bộ lọc nhiều tiêu chí khi đó có ở bản Mở rộng. * **Chuẩn hóa Thông số Bảng giá (KBS Quote)**: Cập nhật định dạng dữ liệu giá lịch sử (`history`) và dữ liệu trong ngày (`intraday`) thống nhất sử dụng hệ số thập phân (đơn vị nghìn đồng) thay cho VND. Điều này giúp tính toán nhẹ nhàng hơn nhưng bạn nhớ điều chỉnh lại các công thức nhân chia mệnh giá trong dòng code cũ để tránh tình trạng lệch dữ liệu biểu đồ phân tích. * **Loại bỏ hàm `price_depth`**: Hàm này đã ngừng trên module `vci.quote`. **[Mở rộng]** Khi đó tính năng chỉ có ở bản Mở rộng. **Tính năng bổ sung & Cải tiến** * **Dữ liệu Sự kiện Thị trường (Market Events)**: Vnstock thấu hiểu nỗi đau của những ai làm backtesting khi chiến lược bị lệch pha do các ngày nghỉ lễ hay những hôm nghẽn hệ thống. Module mới `vnstock.core.utils.market_events` ra đời cung cấp bộ lịch sử sự kiện chứng khoán Việt Nam từ năm 2000. Đây là công cụ đắc lực hỗ trợ các mô hình AI và thuật toán phân tích chuỗi thời gian (time-series) của bạn vượt qua bài toán nhiễu loạn dữ liệu. * **Hàng loạt Cải thiện Ổn định**: Vá ngoạn mục hàng loạt lỗi hệ thống: Bổ sung phương pháp lấy mã cổ phiếu fallback cực thông minh (hiệu quả khi sàn thiếu column gốc); sửa lỗi bắt dữ liệu cho Hợp đồng tương lai đáo hạn và nâng cấp thuật toán đọc số bar trên khung ngày (`500b`) cho KBS Quote được chính xác. Cùng với đó là hoàn thiện việc tích hợp `pytz` hỗ trợ làm đồng bộ các bộ dữ liệu đa không gian múi giờ. *** ## 01-02-2026 ### vnstock
Phiên bản 3.4.2 tập trung vào sửa lỗi và cải thiện tính ổn định, đặc biệt là tương thích với các phiên bản pandas khác nhau và chuẩn hóa dữ liệu giá.
**Sửa lỗi quan trọng** * **Sửa lỗi tương thích pandas**: Khắc phục vấn đề `include_groups` parameter không được hỗ trợ trong pandas 2.1.4, giúp hàm `intraday()` hoạt động bình thường trên mọi phiên bản pandas * **Sửa lỗi kiểm thử Listing**: Cập nhật các bài kiểm thử để xử lý chính xác kiểu dữ liệu `pd.Series` trả về từ `all_future_indices` và các phương thức liên quan * **Sửa lỗi kiểm thử Quote**: Cải thiện khả năng xử lý dữ liệu thiếu và các hợp đồng đã hết hạn một cách linh hoạt mà không làm thất bại toàn bộ bộ kiểm thử * **Sửa lỗi KBS Quote**: Cải thiện khả năng diễn giải các độ dài lookback dựa trên thanh (ví dụ: '500b') sử dụng logic `interpret_lookback_length` **Cải tiến** * **Bổ sung liên kết đến Agent Guide**: Giúp dễ dàng truy cập và sử dụng bộ hướng dẫn chi tiết cho AI trong Vibe Coding. * **Chuẩn hóa dữ liệu giá KBS**: Chuyển đổi dữ liệu giá từ nguồn KBS sang sử dụng giá trị thập phân (đơn vị nghìn) thay vì VND trong các phương thức `history` và `intraday`, giúp dữ liệu nhất quán và dễ xử lý hơn **Loại bỏ** * **Loại bỏ phương thức `price_depth`**: khỏi `vnstock.explorer.vci.quote`, tập trung các hàm cơ bản cho bản Cộng đồng. *** ## 23-01-2026 ### vnstock
Phiên bản 3.4.0 đã được phát hành chính thức. Cài đặt ngay với lệnh pip install vnstock -U. Phiên bản này tập trung vào trải nghiệm người dùng: dữ liệu tài chính sạch hơn, trực quan dễ hiểu hơn và cài đặt/xác thực thuận tiện hơn.
**Những điểm nổi bật** * **Cài đặt & xác thực dễ dàng** * Cài nhanh bằng `pip install vnstock -U` và nhập API Key từ trang quản lý tài khoản Vnstock để sử dụng, hỗ trợ hàm trực tiếp từ thư viện để sử dụng. * **Báo cáo tài chính thân thiện với người dùng từ nguồn KBS** * Dữ liệu báo cáo giờ đây được chuẩn hóa tốt hơn: cột rõ ràng, ít trùng lặp và dễ đọc. * Hỗ trợ **lọc ngôn ngữ** (Tiếng Việt / Tiếng Anh / Cả hai) và các chế độ hiển thị (`standardized_only`, `all_fields`, `auto_convert`) giúp bạn nhanh chóng lấy dữ liệu phù hợp cho báo cáo hoặc phân tích. * **Dữ liệu đáng tin cậy & chuẩn hóa tiếng Việt** * Cải tiến chuẩn hóa văn bản tiếng Việt (bảng ký tự nâng cấp, chuyển đổi tên trường ổn định) giúp việc tìm, so sánh và tự động hoá xử lý dữ liệu trở nên dễ dàng hơn. * Tự động **phát hiện xung đột các trường thông tin trong BCTC** và sinh ID khi cần, giảm rủi ro nhầm lẫn khi trộn nhiều nguồn dữ liệu. * Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. * **Trực quan hoá & báo cáo nhanh** * Tích hợp `vnstock_ezchart` cùng tiện ích mở rộng cho pandas để vẽ biểu đồ và tạo báo cáo chỉ bằng vài dòng mã. * **Ổn định & chất lượng phát hành** * Cải thiện quy trình kiểm thử và CI/CD giúp phát hành phiên bản ổn định hơn, lỗi được phát hiện và sửa nhanh hơn. **Một vài thay đổi nhỏ** * Cập nhật đường dẫn đăng ký API key từ `/account` → `/login` (trải nghiệm đăng ký/đăng nhập thống nhất hơn). * Tối ưu hiệu suất mô-đun dữ liệu KBS và một số tinh chỉnh nội bộ để nâng cao tốc độ và độ tin cậy. *** ## 11-11-2025 ### vnstock * 🚀 **Phiên bản v3.3.0** * **Tương thích hệ thống thư viện Sponsor** sử dụng phương thức xác thực người dùng và quyền sử dụng thông qua Vnstock API key thay cho Github. * **Tăng tốc sử dụng Vnstock trên Google Colab**: Cho phép lưu trữ thư viện & cấu hình vĩnh viễn trong Google Drive để khởi động nhanh thay vì cài đặt lại sau mỗi phiên làm việc. * **Quản lý nguồn thống nhất**: Đưa các nguồn đang hỗ trợ (VCI, TCBS, FMP, XNO, DNSE) về một cơ chế quản lý chung * **Kết nối FMP & XNO**: Thêm kết nối tới hai nguồn này; bạn dùng API key của chính mình do FMP và XNO cấp * **Tái tổ chức mã nguồn**: Gộp các module trong core.utils, chuẩn hóa cách đặt tên và cấu trúc trong common * **Bổ sung kiểm thử**: Thêm bộ test cho các module VCI, TCBS, FMP với kiểm thử tích hợp * **Chuyển sang pyproject.toml**: Thay thế setup.py bằng pyproject.toml, cập nhật các thư viện phụ thuộc * **Cấu hình Context7**: Thiết lập hệ thống lập chỉ mục tài liệu cho AI * **Cập nhật tài liệu**: Làm mới notebook hướng dẫn nhanh, hướng dẫn sử dụng * 🔧 **Cải thiện kỹ thuật** * Chuẩn hóa hằng số thị trường, chỉ số và định nghĩa kiểu dữ liệu * Cải thiện xử lý lỗi và thông báo xác thực * Tái cấu trúc mã nguồn tiêu chuẩn với tài liệu mô tả bằng tiếng Anh * 📚 **Tài liệu** * Cập nhật notebook hướng dẫn nhanh cho FMP và XNO ## 23-05-2025 ### vnstock
Chính thức phát hành phiên bản mới sau khi đã cập nhật bản thử nghiệm từ 17/05/2025 hỗ trợ mã hợp đồng tương lai mới sau khi chuyển đổi hệ thống KRX.
* Hỗ trợ mã hợp đồng tương lai mới theo chuẩn KRX: 1. **Loại CK phái sinh** (ký tự 1) 2. **Nhóm CK** (ký tự 2: 1=Future, 2=Spread) 3. **Tài sản cơ sở** (ký tự 3–4: I1=VN30, B5=GB05, BA=GB10, I2=VN100) 4. **Năm đáo hạn** (ký tự 5: 0→W, loại trừ I,O,U) 5. **Tháng đáo hạn** (ký tự 6: 1→C) 6. **Mã sản phẩm** (ký tự 7–9, ví dụ 000 = HĐTL) * **Ví dụ chuyển đổi**: VN30F2504 → 41I1F4000 Cập nhật này giúp Vnstock nhận diện đúng loại hợp đồng tương lai khi bạn nhập mã hợp đồng theo cấu trúc mới. ## 07-05-2025 ### vnstock
Cập nhật mã nguồn trên Github cho phiên bản kế tiếp. Bạn có thể cập nhật phiên bản để trải nghiệm trong khi phiên bản ổn định sẽ được phát hành trong những ngày tới.
Cài đặt phiên bản thử nghiệm: ```bash pip install vnstock -U ``` Xem thêm hướng dẫn tại [Tải về & Cài đặt](/onboard/trai-nghiem-vnstock) **Cập nhật nổi bật** * [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Gỡ và thay thế một thư viện phụ thuộc bên ngoài trong toàn bộ hệ sinh thái * Sửa lỗi hàm `intraday` sau cập nhật hệ thống KRX * Dữ liệu từ nguồn VCI thay đổi kiểu dữ liệu (`object`/`float`) thay vì `int` như trước đó. * Dữ liệu từ nguồn TCBS bị sai lệnh múi giờ (dữ liệu mới đã chuẩn múi giờ GMT+7) * Bổ sung thông tin bạn đồng hành đóng góp mã nguồn và tài trợ dự án nổi bật vào mô tả dự án. ## 22-04-2025 ### vnstock
Phiên bản **3.2.4** tái cấu trúc bộ adapter từ `vnstock/common` → `vnstock/api` với thuật toán xử lý chặt chẽ hơn, dần loại bỏ lớp trung gian không cần thiết hiện đang sử dụng với `Vnstock` class; bổ sung **notebook minh họa**; tối ưu hóa quy trình **báo lỗi** và **theo dõi dự án** trên GitHub.
**Cải tiến kiến trúc** * Bổ sung cấu trúc Adapter mới tại `vnstock/api` * Thuật toán mới tăng độ chính xác và linh hoạt khi chuyển đổi nguồn dữ liệu * Loại bỏ lớp trung gian cấp cao Vnstock, trực tiếp sử dụng các lớp: `Quote`, `Finance`, `Trading`, `Listing`, `Company` * Tương thích ngược: mọi hàm và class cũ vẫn hoạt động bình thường **Hướng dẫn minh họa** * Bổ sung file notebook minh họa mới sử dụng các cấu trúc lớp trung gian chuyển đổi nguồn nhanh chóng [tại đây](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/wrapper/1_1_quickstart_stock_vietnam.ipynb) **Hoàn thiện quy trình phát triển** * Báo lỗi qua [GitHub Issues](https://github.com/thinh-vu/vnstock/issues) tại trang Github Vnstock * Theo dõi lộ trình qua [GitHub Projects](https://github.com/users/thinh-vu/projects/4) tại trang Github Vnstock ## 27-03-2025 ### vnstock > Cập nhật phiên bản 3.2.3 cải thiện trải nghiệm người dùng * Xử lý chính xác các cột có tên trùng lặp trong hàm `balance_sheet` trả về bảng cân đối kế toán. Theo đó cột xuất hiện sau với tên trùng lặp sẽ được đặt tên với tiền tố `_`. Ví dụ `Chứng khoán kinh doanh` và `_Chứng khoán kinh doanh` cho cột xuất hiện sau. Hai cột này tồn tại có ý nghĩa theo hình thức cha/con trên bảng cân đối kế toán tiêu chuẩn. * Merge [pull request 159](https://github.com/thinh-vu/vnstock/pull/159): Bổ sung cột sẽ được lựa chọn hiển thị tiếng Việt khi trích xuất dữ liệu từ Dict * Bổ sung `tenacity` là gói phụ thuộc khi cài đặt dự án * Sửa lỗi không cho truy cập dữ liệu intraday từ nguồn TCBS ngoài giờ giao dịch. * Sửa lỗi hàm Pandas `map` và thay thế với `applymap` để tương thích với bản Pandas cũ hơn 2.x trong module company của nguồn VCI (dòng 135) * Cập nhật file README đổi tên Vnstock3 thành Vnstock ## 24-03-2025 ### vnstock > Cập nhật phiên bản 3.2.2 sửa lỗi 502 Bad Request xuất hiện với nguồn dữ liệu VCI. Lỗi 502 Bad Request xuất hiện trùng thời điểm với việc nâng cấp lên phiên bản 3.2.1 đã khiến nhiều người thắc mắc. Sau khi phân tích, nguyên nhân được xác định: VCI đã thay đổi địa chỉ cấp dữ liệu API, khiến các yêu cầu gửi đến API cũ không còn hiệu lực và dẫn đến phản hồi không ổn định. ## 23-03-2025 ### vnstock > Cập nhật phiên bản 3.2.1 với nhiều thay đổi quan trọng * Bổ sung tính năng bộ lọc cổ phiếu từ TCBS * Thêm dữ liệu thông tin công ty từ nguồn VCI * Kết nối Google Drive từ Colab - Không bao giờ quên lưu dữ liệu nữa * Cải tiến trải nghiệm người dùng * Nhận diện phiên giao dịch: tự động gửi cảnh báo lỗi chi tiết giúp bạn điều hướng dễ dàng khi truy cập dữ liệu `intraday` và `price_depth` trước phiên giao dịch. * Cảnh báo chủ động rate limit * Chuẩn hóa tên cột: Thay đổi `ticker` → `symbol`, `HOSE` → `HSX`, giúp dữ liệu đồng nhất, dễ xử lý hơn. * Cập nhật API key MSN: Đảm bảo việc lấy dữ liệu luôn ổn định và nhanh chóng. * Tái cấu trúc mã nguồn * Tăng mức độ module hóa mã nguồn * Cấu trúc tinh gọn và dễ bảo trì * Chuẩn hóa xử lý lỗi Chi tiết, vui lòng xem trong bài blog.
Xem thêm
## 02-01-2025 ### vnstock
Hợp nhất thư viện Vnstock3 và Vnstock Legacy, sử dụng chung tên gọi thư viện là vnstock từ hệ thống phân phối phần mềm pypi.org. Từ 2/1/2025, mọi cài đặt thư viện vnstock được mặc định hiểu là thư viện thế hệ 3, bắt đầu từ phiên bản 3.1.0
* Cập nhật thư viện lên trang phân phối pypi.org. Câu lệnh cài đặt mặc định: `pip install -U vnstock` sẽ luôn cài đặt phiên bản vnstock mới nhất vào máy của bạn. Câu lệnh `pip install vnstock3` sẽ vẫn có hiệu lực, chỉ cập nhật đến phiên bản 3.1.0. * Cập nhật tài liệu hướng dẫn trên website và file Demo. Tất cả lệnh sẽ sử dụng `vnstock` để chỉ định phiên bản hiện tại của Vnstock3.1.0.1. Tham khảo blog để biết thêm chi tiết [tại đây](/blog/chuyen-doi-sang-vnstock3-truoc-2025). ## 02-11-2024 ### vnstock > Phát hành chính thức phiên bản v3.0.9 qua PyPI. Cài đặt với câu lệnh: `pip install -U vnstock` trên máy của bạn. * Nâng cấp hàm truy xuất dữ liệu từ nguồn VCI cho báo cáo tài chính. Lọc các cột dữ liệu không liên quan, trùng lặp xuất hiện trong các phiên bản trước đó. Chỉ tập trung các giá trị dữ liệu cho đúng loại hình công ty của mã bạn tra cứu. Có 4 nhóm công ty bao gồm Công ty phổ thông, Ngân hàng, Chứng khoán, Bảo hiểm. * Sửa lỗi chuyển đổi nhanh mã cổ phiếu. Cho phép cài đặt tham số `symbol` khi gọi hàm với cú pháp `stock.finance(symbol='TCB')`. Việc này giúp bạn không cần phải cập nhật mã symbol khi khởi tạo class mà có thể thayd đổi trong method gọi dữ liệu cụ thể. Thay đổi này sau đó sẽ áp dụng cho class trong các hàm tiếp theo. * Bổ sung thêm tuỳ chọn tham số `show_log` trong các class của Vnstock, bạn có thể tắt log message (các hiển thị cảnh báo) bằng cách đặt `show_log=False`. * Khắc phục lỗi định dạng `NoneType Object` khi không nhập mã chứng khoán trong Listing class với câu lệnh: ``` from vnstock3 import Vnstock stock = Vnstock().stock(source='VCI') ``` * Khắc phục lỗi 404 khi truy cập dữ liệu giá từ module Quote của VCI do API url thay đổi. * Khắc phục lỗi không nhận diện các mã chỉ số khi tra cứu lịch sử giá từ module Quote.history. Các mã chỉ số chuẩn sử dụng cho tra cứu thị trường chứng khoán Việt Nam gồm: VNINDEX, HNXINDEX, UPCOMINDEX * Bổ sung khả năng lấy dữ liệu giá lịch sử cho Trái phiếu niêm yết & nâng cấp cơ chế nhận diện loại tài sản với khả năng nhận diện mã nhập vào là Trái phiếu. ## 15-10-2024 ### vnstock Cập nhật phiên bản mới, gỡ lỗi một số vấn đề phát sinh được báo lỗi: -Lỗi khi gọi lịch sử giá: [issue 147](https://github.com/thinh-vu/vnstock/issues/147) * Bổ sung cơ chế báo lỗi khi dữ liệu trả về không như mong muốn với BCTC: [issue 133](https://github.com/thinh-vu/vnstock/issues/133#issuecomment-2395270403) ## 12-08-2024 ### vnstock Cập nhật mã nguồn phiên bản 0.3.0.7 * Sửa lỗi mốc thời gian giá lịch sử không ổn định. Hiện tại có thể lấy thông tin giá lịch sử thuộc tất cả các khung thời gian với tham số `end` là ngày hiện tại. Mã báo lỗi 135: [tại đây](https://github.com/thinh-vu/vnstock/issues/135) * Bổ sung cơ chế xử lý lỗi khi thông tin `event_desc` trả về trong DataFrame không chứa thành phần HTML cần chuyển đổi thành văn bản. Mã báo lỗi 141 [tại đây](https://github.com/thinh-vu/vnstock/issues/141#issuecomment-2271610641) * Sửa lỗi & cải thiện phương thức lấy dữ liệu báo cáo tài chính từ VCI: * Sửa lỗi tên biến `UNIT_MAPPING` không khớp * Tự động loại bỏ dữ liệu N/A trong báo cáo tài chính. Việc này giúp loại bỏ các dữ liệu không có ý nghĩa và trùng lặp tên cột. Bạn có thể tuỳ chỉnh sử dụng tham số dropna=False để chỉ định giữ lại dữ liệu nguyên bản (có thể trùng lặp tên cột - khác ý nghĩa dữ liệu) và N/A. * Kế thừa mô-đun kết nối DNSE từ phiên bản Vnstock Legacy. Mô-đun này không còn trong thư viện hiện hành. * Bổ sung thông tin gói phụ thuộc * Bổ sung phiên bản cố định cho các gói phụ thuộc vào file [requirements.txt](https://github.com/thinh-vu/vnstock/blob/main/requirements.txt) * Bổ sung `seaborn` vào danh sách gói phụ thuộc để loại bỏ lỗi khi cài đặt trên máy tính mới không có sẵn `seaborn`. ## 10-07-2024 ### vnstock Cập nhật mã nguồn phiên bản 0.3.0.6 * Chuyển đổi mã nguồn Vnstock Legacy sang Vnstock3 cho bộ công cụ gửi tin nhắn qua Telegram, Lark, Slack [tại đây](/docs/vnstock/gui-tin-nhan-telegram-slack-larksuite). * Chuyển đổi mã nguồn module `fund.py` từ Vnstock Legacy sang Vnstock3 [tại đây](/docs/vnstock/quy-mo-fund). * Loại bỏ cơ chế bắt buộc người dùng chấp nhận điều khoản, điều kiện rõ ràng. Mặc định, bạn chấp nhận điều khoản & điều kiện khi tiếp tục sử dụng Vnstock3. * Sửa lỗi và cải thiện trải nghiệm: * Xác thực thông tin mã quỹ nhập vào [tại đây](https://github.com/thinh-vu/vnstock/issues/118) * Lỗi khi lấy giá lịch sử theo tháng [tại đây](https://github.com/thinh-vu/vnstock/issues/127) ## 21-06-2024 ### vnstock Cập nhật phiên bản 0.3.0.5 * Sửa lỗi không hiển thị đúng múi giờ trong thời gian của bảng giá lịch sử với khung thời gian giờ và phút, chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/131) * Sửa lỗi không cho phép truy xuất thông tin giá từ TCBS nếu `symbol` không phải là mã cổ phiếu. Chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/128) * Bổ sung xác thực thông tin nhập liệu cho hàm `history` * Thời gian bắt đầu phải nhỏ hơn thời gian kết thúc. ## 03-06-2024 ### vnstock Cập nhật phiên bản 0.3.0.3 * Tích hợp khả năng vẽ biểu đồ bằng vnstock_ezchart trực tiếp vào thư viện. Chi tiết [tại đây](/docs/vnstock/bieu-dien-du-lieu) * Tách riêng notebook min hoạ theo chủ đề. Chi tiết [tại đây](https://github.com/thinh-vu/vnstock/tree/main/docs) * Cập nhật hàm truy xuất api_key từ nguồn dữ liệu MSN, khắc phục lỗi truy xuất dữ liệu các loại chứng khoán quốc tế. * Cập nhật nội dung phản ánh các thay đổi của dự án trên Website. ## 25-05-2024 ### vnstock
Hoàn thiện tính năng, sửa lỗi và bổ sung tài liệu hướng dẫn.
* Sửa lỗi tự động ghi đè thông tin mã cổ phiếu theo mã báo lỗi [9547585](https://github.com/thinh-vu/vnstock/discussions/16#discussioncomment-9547585) * Hoàn thiện nhóm hàm chức năng truy xuất dữ liệu tài chính. Hiện tại có thể gọi thuộc tính `finance` từ lớp Vnstock() thay vì gọi hàm từ trực tiếp nguồn dữ liệu kiểu `vnstock3.explorer.vci.finance`. * Cập nhật hàm minh hoạ trong [Demo Notebook](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/vnstock3_demo.ipynb). * Bổ sung tài liệu hướng dẫn chi tiết * [Thông tin niêm yết](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Thông tin công ty](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Báo cáo tài chính](/docs/vnstock/bao-cao-tai-chinh) * Dành cho nhóm phát triển: * Bổ sung cấu trúc thư mục `tests` dùng cho việc kiểm thử gói phần mềm. ## 10-05-2024 ### vnstock
Ra mắt phiên bản Vnstock thế hệ thứ 3 - Vnstock3.
![](/images/Hello_Vnstock3_10-05-2024-97749fc40c003ac445c205b3215bed4c.png) ## 02-04-2024 ### vnstock
Cập nhật tài liệu hướng dẫn và sửa đổi nhỏ cho hàm gửi tin nhắn Telegram.
## 23-01-2024 ### vnstock
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app *
### vnstock
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 0.2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app ## 21-01-2024 ### vnstock * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ### vnstock * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ## 03-01-2024 ### vnstock * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ### vnstock * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ## 02-01-2024 ### vnstock * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. ### vnstock * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. ## 24-12-2023 ### vnstock * Cập nhật tài liệu dự án * Tài liệu truy xuất giá lịch sử * Hướng dẫn truy xuất dữ liệu giao dịch nước ngoài/tự doanh sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ### vnstock * Cập nhật tài liệu dự án * Tài liệu truy xuất giá lịch sử * Hướng dẫn truy xuất dữ liệu giao dịch nước ngoài/tự doanh sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ## 16-12-2023 ### vnstock * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data`. * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program. * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ### vnstock * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data`. * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program. * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ## 14-12-2023 ### vnstock Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. * Cập nhật tài liệu dự án ### vnstock Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. * Cập nhật tài liệu dự án ## 10-12-2023 ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ### vnstock * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ## 09-11-2023 ### vnstock > Phát hành phiên bản 0.2.8.5 * Cập nhật hàm `stock_intraday_data` * Bổ sung tham số `investor_segment`, mặc định nhận giá trị `True` cho phép trả về dữ liệu khớp lệnh theo phân nhóm nhà đầu tư (như các phiên bản trước), khi đặt là `False` cho phép trả về dữ liệu thô, không gộp thông tin lệnh theo phân nhóm. * Bổ sung hàm `amibroker_ohlc_export` cho phép xuất dữ liệu sang định dạng CSV để nạp dữ liệu cho Amibroker. * Bổ sung hướng dẫn tích hợp vnstock với dự án sử dụng thư viện phân tích kỹ thuật TA-lib python. * Giới thiệu một số thư viện Backtesting trong python giúp nghiên cứu định lượng trên dữ liệu lịch sử. ## 08-11-2023 ### vnstock > Phát hành phiên bản 0.2.8.4 * Tùy biến hàm `stock_historical_data` giúp dễ dàng sử dụng với các thư viện phân tích kỹ thuật khác trong Python. * Thêm tham số `decor`, nhận giá trị mặc định là `False` (không thay đổi dữ liệu trả về với cách sử dụng hiện tại của người dùng). Khi đặt `decor=True`, áp dụng thay tên các cột trong DataFrame trả về dưới dạng Title Case tức `Open, High, Low, Close, Time, Ticker` thay vì `open, high, low, close, time, ticker` như hiện tại đồng thời đặt cột Time là index. Việc này giảm bớt cho người dùng phải viết thêm câu lệnh khi sử dụng dữ liệu vnstock kết hợp các thư viện phân tích kỹ thuật phổ biến vốn dùng thư viện Yahoo Finance làm nguồn cấp dữ liệu. * Bổ sung tham số `source` cho phép chọn nguồn tải dữ liệu là `TCBS` hay `DNSE`. Nguồn dữ liệu `TCBS` cho lấy dữ liệu lịch sử theo ngày (resolution = `1D`) trong thời gian dài, không hỗ trợ khung thời gian nhỏ hơn. Trong khi đó nguồn dữ liệu `DNSE` cho phép lấy dữ liệu với nhiều khung thời gian khác nhau, giới hạn 90 ngày gần nhất đối với dữ liệu phút, 10 năm gần nhất đối với dữ liệu ngày. * Cập nhật lớp kết nối nguồn TCBS ## 05-11-2023 ### vnstock * Tích hợp kết nối DNSE Lightspeed API (không còn trong thư viện hiện hành). Phát hành phiên bản 0.2.8.2. Sử dụng lệnh `pip install -U vnstock` để cập nhật phiên bản. ## 29-10-2023 ### vnstock * Tích hợp API endpoints cơ bản của DNSE vào vnstock * Demo cho các nhà đầu tư cách tạo 1 request và kết nối hệ thống DNSE để lấy JWT token * Demo xuất thông tin tài khoản * Cập nhật tài liệu sử dụng ## 27-10-2023 ### vnstock * Bổ sung và hoàn thiện một số hàm cho vnstock * Hàm `listing_companies` nay được cung cấp thêm khả năng lấy danh sách công ty niêm yết từ SSI/FiinTrade. Việc này giúp người dùng có thể tham chiếu mã công ty từ mã cổ phiếu để lấy thông tin trong một số trường hợp đặc biệt FiinTrade sử dụng mã này thay cho mã cổ phiếu. Ví dụ, thay vì dùng mã cổ phiếu `BCM` gây ra lỗi cho hàm, bạn cần sử dụng mã công ty tương ứng là `BIDC` * Hàm `indices_listing` cho phép liệt kê tất cả mã chỉ số hiện có trên sàn. * Hàm `financial_ratio_compare` cho phép so sánh chỉ số tài chính của một danh sách các mã cổ phiếu. ## 26-10-2023 ### vnstock * Khôi phục các hàm lấy dữ liệu từ nguồn SSI gồm `financial_report`, `fr_trade_heatmap`, `market_top_mover` sau khi nguồn SSI mở lại khả năng truy cập cho các nhóm dữ liệu này. * Cập nhật tài liệu sử dụng kèm theo * Cập nhật Demo Notebook ## 25-10-2023 ### vnstock * Bổ sung hướng dẫn xuất dữ liệu sang các định dạng phổ biến bao gồm CSV, Excel, và dữ liệu cho Amibroker. * Thử nghiệm tính năng Blog của Mkdocs Matterial cho chuyên mục Kiến thức. ## 21-10-2023 ### vnstock * Giới thiệu cách sử dụng vnstock trong Google Sheets với Neptyne for Google Sheets. * Di chuyển mục nội dung vnstock cho Google Sheets sang tab `Ứng dụng & Tích hợp` ## 20-10-2023 ### vnstock * Chuyển đổi nền tảng tài liệu từ Pretty-Docs sang [MkDocs Matterial](https://squidfunk.github.io/mkdocs-material/) thân thiện và nhiều tính năng hữu ích hơn. * Cập nhật mô tả các hàm để tiện theo dõi bao gồm: * Xoay DataFrame kết quả trả về để có thể hiển thị đầy đủ tên các cột dữ liệu * Bổ sung mô tả tham số đầu vào của hàm ## 14-10-2023 ### vnstock > Phiên bản: 0.2.2: Đưa tính năng vẽ đồ thị chính thức vào phiên bản ổn định, cập nhật hàm truy xuất giá lịch sử * Cập nhật hàm `stock_historical_data` để trả về thông tin chính xác * Loại bỏ bước tính toán nhân chỉ số và mã phái sinh với 1000 khi trả về dữ liệu. Cách tính này làm sai lệch giá trị của chỉ số và mã phái sinh vì bản chất giá trị OHLC này khác với giá cổ phiếu. * Bổ sung thêm tham số **beautify**, đặt giá trị mặc định là True để giữ nguyên cách nhân 1000 cho giá cổ phiếu. Người dùng có thể chuyển về False để giữ nguyên giá trị OHLC dạng thập phân rút gọn. * Chính thức đưa các hàm vẽ đồ thị vào phiên bản chính thức của vnstock sau quá trình thử nghiệm * Hàm **candlestick_chart** cho phép vẽ đồ thị nến cùng các đường trung bình động, hỗ trợ, kháng cự cơ bản. ![candlestick](/images/VIC_candlestick.png) * Hàm **bollinger_bands_chart** cho phép vẽ đồ thị nến (hoặc đường) kèm các dải Bollinger Bands. Hàm này cần sử dụng kèm hàm **bollinger_bands** để chuyển đổi dữ liệu OHLC tiêu chuẩn sang dữ liệu Bollinger Bands. ![bollinger bands](/images/bollinger_bands_chart.png) ## 10-10-2023 ### vnstock * Hàm **listing_company** được điều chỉnh để hỗ trợ truy xuất danh sách mã cổ phiếu cập nhật trực tiếp qua API. * Bổ sung tham số **live** nhận giá trị True hoặc False, mặc định là False cho phép truy xuất danh sách cổ phiếu từ tệp csv lưu trữ trên Github. Cấu trúc của file dữ liệu cục bộ chứa thông tin đầy đủ hơn so với chế độ trực tiếp. * Loại bỏ tham số **path** ## 06-10-2023 ### vnstock > Thay đổi cấu trúc thư mục và tài liệu vnstock repo trên Github * Tái cấu trúc cây thư mục của vnstock repo trên Github * Chuyển toàn bộ file markdown vào thư mục **docs** trừ file README (Tiếng Việt). * Chuyển thư mục **src** vào bên trong thư mục **docs** và đổi tên thành **resources**. Các file ảnh đính kèm dự án được đưa vào sâu hơn 1 cấp bên trong thư mục **images**. * Đơn giản hóa nội dung file README của repo. Đưa tất cả tài liệu hướng dẫn vào vnstock docs. * Bổ sung cơ chế kiểm tra mã phản hồi (status_code) của API trước khi trả về dữ liệu cho hàm **stock_intraday_data** ## 05-10-2023 ### vnstock > vnstock docs Phiên bản 1.1 sử dụng Pretty-Docs theme Thử nghiệm thành công và ra mắt phiên bản thử nghiệm 1.0 cho trang tài liệu vnstock docs sử dụng pretty-docs theme. ## 22-08-2023 ### vnstock * Cập nhật tệp dữ liệu **listing_companies** lên phiên bản mới nhất. * Cập nhật hàm **financial flow** * Thêm tham số **get_all** để lấy tất cả dữ liệu có sẵn hoặc chỉ dữ liệu mới nhất (5 năm hoặc 10 quý). * Cập nhật Demo Notebook để minh họa các thay đổi mới nhất. ## 24-07-2023 ### vnstock * Bắt đầu triển khai hàm truy xuất dữ liệu chứng khoán phái sinh. * Kết hợp một hàm sàng lọc cổ phiếu từ TCBS vào thư viện. * Cải thiện hàm stock_historical_data với các cập nhật sau: * Khi độ khung thời gian (resolution) được đặt thành **1D**, cột thời gian sẽ hiển thị theo định dạng ngày **YYYY-mm-dd**. * Thêm một giá trị mới **derivative** cho tham số **type**, cho phép truy xuất dữ liệu phái sinh. * Các tham chiếu hàm trong tệp README đã được cấu trúc theo các tình huống sử dụng thực tế, như Phân tích Kỹ thuật, Phân tích Cơ bản, Sàng lọc Cổ phiếu, vv. Điều này giúp cho tài liệu thân thiện và có tổ chức hơn với người dùng. Phiên bản tiếng Anh của tệp README cũng đã được cập nhật để phù hợp với phiên bản tiếng Việt. ## 22-07-2023 ### vnstock * Bổ sung hướng dẫn vào [Demo Notebook](https://github.com/thinh-vu/vnstock/blob/legacy/demo/gen2_vnstock_demo_index_all_functions_testing_2023.ipynb) giúp người dùng xuất dữ liệu từ Google Colab ra Google Sheets. ## 14-07-2023 ### vnstock * Phát hành phiên bản 0.17 trên PyPI. * Những thay đổi trên nhánh **beta** sẽ được cập nhật vào nhánh **main** và phát hành qua PyPI hàng tháng từ bây giờ. * File README.md đã được cập nhật để đồng bộ hóa phiên bản tiếng Anh và tiếng Việt. * Hàm listing_companies dùng tệp tham chiếu listing_companies_enhanced-2023.csv đi kèm repo. * Hàm mới, price_depth, đã được giới thiệu để lấy giá và khối lượng giao dịch cho danh sách các cổ phiếu. Hàm này có thể được sử dụng song song với hàm price_board. ## 13-07-2023 ### vnstock * Phân loại các tính năng của vnstock trong file Demo Jupyter Notebook theo 5 nhóm chính: 1. Thị trường (Market Watch) 2. Phân tích cơ bản (Fundamental Analysis) 3. Phân tích kỹ thuật (Technical Analysis) 4. Lựa chọn cổ phiếu (Stock Screening) 5. Trung tâm giao dịch (Trading Center) * Đã sửa lại file demo notebook để cập nhật các hàm mới. * Khôi phục giá đơn vị của stock_historical_data từ 1000 VND thành VND bằng cách nhân với 1000. * Hàm **price_board** đã được cập nhật. * Bổ sung hàm mới trong mô đun **utils.py** để trích xuất giá trị ngày tháng theo định dạng YYYY-mm-dd. ## 05-07-2023 ### vnstock * Cập nhật file README.md (áp dụng cho tiếng Việt trước). * Các hàm liên quan đến nguồn dữ liệu SSI không hoạt động đã bị loại bỏ. * Hàm **financial_ratio** đã được cải tiến với các cập nhật sau đây: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị (transpose), với năm/quý đóng vai trò là chỉ mục, giúp sử dụng thuận tiện hơn. * Tham số **is_all** đã trở thành tham số phụ tùy chọn. * Hàm **industry_analysis** và stock_ls_analysis đã được cải thiện: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị, với tên mã cổ phiếu làm tiêu đề cột, giúp dễ sử dụng. * Thêm tham số **lang**, cho phép hiển thị cột DataFrame bằng nhãn tiếng Việt hoặc tiếng Anh. ## 29-06-2023 ### vnstock * Đã cập nhật hàm stock_intraday_data để cung cấp thêm dữ liệu chi tiết trả về bởi hàm và dễ sử dụng hơn * Cập nhật hàm stock_historical_data để hỗ trợ lấy dữ liệu lịch sử về các chỉ số. ## 22-06-2023 ### vnstock * Phát hành phiên bản 0.15 rên Pypi. * Giới thiệu một tính năng mới cho hàm stock_historical_data, cho phép lấy dữ liệu với nhiều độ phân giải thời gian khác nhau. Đã nâng cấp API tương ứng hỗ trợ hàm này. * Bao gồm tham số độ phân giải để cho phép người dùng lấy dữ liệu giá tại các khoảng thời gian 1 phút, 3 phút, 5 phút, 15 phút, 30 phút, 1 giờ hoặc 1 ngày. * Sửa tên cột trong bảng dữ liệu trả về từ tradingDate thành time. * Đã đánh dấu rõ các hàm không khả dụng cho các API liên quan tới SSI. * Tùy chọn **mode='live'** trong hàm listing_companies() đã được loại bỏ. Hàm này bây giờ chỉ đọc danh sách công ty từ tệp csv trên repo github này. * Cập nhật cây thư mục cho github repo, thêm thư mục dữ liệu và thêm tệp dữ liệu, thư mục demo để lưu trữ các tệp demo. ## 07-06-2023 ### vnstock Chính thức hỗ trợ hướng dẫn sử dụng bằng tiếng Việt cho tệp thư viện thông qua file README.md, giúp thúc đẩy khả năng tiếp cận với vnstock cho người dùng Việt Nam. ## 20-05-2023 ### vnstock * Nhánh **main** dành riêng cho các cập nhật quan trọng, trong khi nhánh **beta** được sử dụng cho các cập nhật nhỏ. Từ bây giờ, gói PyPI sẽ phản ánh nội dung của nhánh **main**. * Hàm listing_companies() bây giờ có thể đọc danh sách công ty từ tệp csv trên repo github này hoặc từ một yêu cầu API trực tiếp. * Hàm stock_intraday_data() bây giờ có một giới hạn mới là 100 cho tham số page_size do TCBS thiết lập. --- ## Document: Tự động nạp Agent Skills và tài liệu ## Tổng quan Cơ chế tải động[^1] cho phép các AI Agent trong môi trường lập trình tự động nạp trực tiếp các bộ kỹ năng[^2] và tài liệu hướng dẫn từ hệ thống máy chủ của Vnstock, thay vì phải lưu trữ các tệp tin tĩnh trên máy tính cá nhân. Mục đích của cơ chế này là khắc phục những hạn chế từ phiên bản hướng dẫn từng lưu trên kho GitHub. Cách triển khai đó cho phép tải về toàn bộ tài liệu để nghiên cứu nhưng lại không thuận tiện trong việc cập nhật thường xuyên và tích hợp vào dự án Vibe Coding, dẫn đến tình trạng nội dung bị phân mảnh và không đồng bộ với tài liệu chính thức. Việc hợp nhất về một nguồn tài liệu duy nhất[^3] giúp Vnstock kiểm soát chất lượng chặt chẽ hơn, đồng thời mang lại cho người dùng trải nghiệm đồng bộ dù làm việc ở bất kỳ môi trường lập trình nào. ## Cài đặt Tính năng này có ở cả `vnstock` thế hệ 5 và `vnstock` 4.x. Cách cài và cách lưu khoá khác nhau giữa hai thế hệ; cách gọi skill thì giống nhau. ### vnstock thế hệ 5 Thế hệ 5 tự tải skill, không cần cài thêm `vnai`. Cài theo [trang cài đặt thế hệ 5](/docs/vnstock/cai-dat), rồi đăng nhập một lần trên máy, trong terminal của chính bạn: ```bash vnstock register # hỏi khoá, gõ không hiện lên màn hình vnstock status # xem lại cấp, hạn dùng, thiết bị ``` Thế hệ 5 lưu khoá đã mã hoá trong thư mục `~/.vnstock/auth/`, không còn để dạng thường trong `api_key.json`. Biến môi trường `VNSTOCK_API_KEY`, nếu có, luôn được dùng trước. Tệp `api_key.json` của bản 4.x chỉ được nhập vào kho mã hoá một lần, ở lần chạy đầu trên máy chưa từng đăng nhập thế hệ 5; muốn đổi khoá thì chạy lại `vnstock register`, sửa tệp cũ không có tác dụng. Trợ lý AI không cần và không được đọc khoá: thư viện tự gửi khoá khi tải skill. Trong notebook, đăng nhập bằng Python với khoá đặt sẵn trong biến môi trường: ```python import os import vnstock vnstock.login(os.environ["VNSTOCK_API_KEY"]) ``` Trợ lý AI tải skill và tài liệu bằng: ```python from vnstock.utils.agents import load_skill, load_skill_catalog, load_doc, load_docs_catalog catalog = load_skill_catalog() # danh mục skill, kèm cấp cần có print(load_skill("vnstock-bootstrap")) # nội dung một skill ``` Đường dẫn cũ `vnstock.core.utils.agents` vẫn dùng được. Khoá đi kèm request là khoá bạn đã đăng nhập, trong header `Authorization`, không nằm trên URL. Chưa đăng nhập thì vẫn tải được các skill mở cho mọi cấp. Khi không tải được, thư viện báo lỗi rõ lý do: khoá chưa hợp lệ, cấp hiện tại chưa mở skill đó (kèm cấp cần có), không có skill tên đó, hoặc máy chủ chưa trả lời. Thế hệ 5 **không ghi gì vào tệp của bạn**: không có `enable_agent()` hay `setup_agent()`. Muốn trợ lý biết cách dùng vnstock trong mọi phiên làm việc, tick ô ghi hướng dẫn khi chép lời nhắc ở [trang hướng dẫn cài đặt](/onboard). Trợ lý sẽ cho bạn xem khối hướng dẫn trước, rồi mới thêm vào `AGENTS.md` của dự án. ### vnstock 4.x Cài hoặc cập nhật đồng thời cả hai thư viện `vnstock` và `vnai` lên các phiên bản tương thích mới nhất: ```bash pip install -U --extra-index-url https://vnstocks.com/api/simple "vnstock>=4.0.9" "vnai>=2.6.2" ``` Hai gói này được cài từ kho phát hành thư viện của Vnstock nên lệnh cần phần `--extra-index-url`. Dấu ngoặc kép quanh tên gói là bắt buộc: thiếu chúng, dấu `>` bị cửa sổ dòng lệnh hiểu là lệnh ghi ra tệp, và pip cài sai phiên bản mà không báo lỗi. Thư viện đọc [API Key](/account#api-key) của bạn từ biến môi trường `VNSTOCK_API_KEY` hoặc từ tệp đã lưu trên máy, rồi gửi kèm trong header `Authorization` tới `vnstocks.com` để máy chủ kiểm quyền tải kỹ năng. Khoá không bao giờ nằm trên URL. Lưu khoá bằng lệnh `python -c "from vnstock import register_user; register_user()"` chạy trong terminal của chính bạn: khoá được nhập ẩn. Đừng dán khoá vào khung chat với trợ lý AI. Trợ lý gọi skill bằng `from vnstock.core.utils.agents import load_skill`. ## Kiến trúc hoạt động Hệ thống hoạt động dựa trên sự liên kết giữa máy chủ của website Vnstock và thư viện Python ở phía người dùng, để AI luôn có ngữ cảnh theo tài liệu mới nhất. ### 1. Agent Skills Hub (Trung tâm Kỹ năng) Tất cả các bộ kỹ năng dành cho AI được quản lý tập trung tại **Agent Skills Hub**. Dựa vào Mã khóa cá nhân (API Key), hệ thống sẽ tự động phân quyền truy cập các nhóm kỹ năng phù hợp với cấp quyền của bạn: * **Người dùng bản Cộng đồng:** Được quyền tiếp cận các bộ kỹ năng nền tảng. Nhóm kỹ năng này hướng dẫn AI cách vận hành thư viện `vnstock` bản Cộng đồng (phát hành theo giấy phép riêng) để kết nối dữ liệu thị trường, thiết lập môi trường và cấu hình tự động hóa. * **Người dùng gói quyền sử dụng:** Tùy thuộc vào cấp quyền, hệ thống mở thêm các kỹ năng chuyên sâu. Những kỹ năng này giúp AI dùng đúng năm phần mềm hiện hành: `vnstock`, `vnstock_quant`, `vnstock_mcp`, `vnstock_news` và `vnstock_pipeline`. Công ty cấp quyền sử dụng phần mềm theo từng cấp; riêng nội dung được kết nối qua `vnstock` hoặc `vnstock_news` vẫn chịu điều kiện của nguồn tương ứng. Bên cạnh các bộ kỹ năng, Agent Skills Hub cũng tự động cho phép AI Agent đọc trực tiếp toàn bộ tài liệu hướng dẫn chính thức trên web thông qua API, giúp AI luôn nắm bắt kịp thời những cập nhật mới nhất mà không cần bạn phải sao chép thủ công. ### 2. Trợ lý AI dùng các kỹ năng thế nào Bạn ra lệnh bằng ngôn ngữ tự nhiên như bình thường: lấy dữ liệu thị trường, đọc báo cáo tài chính, tính chỉ báo kỹ thuật, tra tài liệu của một hàm. Khi việc cần một hướng dẫn chuyên sâu, trợ lý tải kỹ năng tương ứng từ máy chủ Vnstock và dùng nó làm tài liệu tham khảo. Kỹ năng chỉ là tài liệu. Nó không cấp thêm quyền nào cho trợ lý, và không đè lên chỉ dẫn của bạn hay quy tắc an toàn của chính trợ lý. Trợ lý được dặn nói trước với bạn khi tải một kỹ năng, và hỏi bạn trước khi chạy lệnh cài đặt nào. ### 3. Thư viện ghi gì lên máy bạn Mục này và mục 4 chỉ áp dụng cho `vnstock` 4.x. Thế hệ 5 không ghi gì vào tệp của bạn (xem phần cài đặt ở trên). Từ `vnstock` 4.0.9 / `vnai` 2.6.2, **thư viện không ghi gì khi `import`**. Việc ghi hướng dẫn cho trợ lý AI là tuỳ chọn bạn tự bật: ```bash python -c "import vnstock; vnstock.enable_agent(); vnstock.setup_agent(); print(vnstock.agent_status())" ``` Bật mà không nêu tên thì chỉ ghi `AGENTS.md` trong thư mục dự án. Tệp toàn cục phải nêu đích danh: | Tệp | Công cụ đọc tệp này | Phạm vi | Bật bằng | | --- | --- | --- | --- | | `AGENTS.md` ở thư mục dự án | Nhiều trợ lý AI | Chỉ dự án đó | `enable_agent()` | | `~/.claude/CLAUDE.md` | Claude Code | **Mọi dự án trên máy** | `enable_agent("claude")` | | `~/.gemini/GEMINI.md` | Google Antigravity, Gemini | **Mọi dự án trên máy** | `enable_agent("antigravity")` | | `~/.codex/AGENTS.md` | Codex | **Mọi dự án trên máy** | `enable_agent("codex")` | Thứ được ghi là văn bản nằm sẵn trong gói `vnai` đã cài (tệp `vnai/beam/agent_bootstrap.py`), **không tải từ mạng**, và chỉ đổi khi bạn nâng cấp `vnai`. Bản đọc được trên web là kỹ năng [vnstock-bootstrap](/skill/vnstock-bootstrap). Khối này **không bao giờ** yêu cầu trợ lý hỏi khoá truy cập qua khung chat, chèn khoá vào mã, hay làm việc gì mà không cho bạn biết. Nếu bạn thấy một văn bản xưng là của Vnstock yêu cầu những điều đó, đừng làm theo và báo cho Vnstock qua support@vnstocks.com. Kỹ năng chủ đề (lọc cổ phiếu, chỉ báo kỹ thuật...) chỉ được tải khi có lệnh `load_skill(...)`, trả về dạng chữ đọc được, và mở đầu bằng một dòng ghi rõ đó là tài liệu tải từ `vnstocks.com` chứ không phải yêu cầu của bạn.
Các bản trước vnstock 4.0.9 / vnai 2.6.2 tự ghi khối hướng dẫn vào cả bốn tệp trên mỗi lần import, bằng nội dung tải từ website. Bản mới không tự sửa các tệp đó, mà báo cho bạn một lần nếu còn sót khối, kèm lệnh gỡ ở mục dưới.
### 4. Xem, tắt và gỡ Cài bằng lời nhắc ở [trang hướng dẫn cài đặt](/onboard) là cách đơn giản nhất để chọn: lời nhắc hiện nguyên văn để bạn đọc trước khi dán, và có tuỳ chọn **"Cho trợ lý ghi hướng dẫn dùng vnstock vào AGENTS.md của dự án"**, để sẵn là bật (khuyên dùng) và bạn bỏ chọn được. Với thế hệ 5, chính trợ lý AI thêm khối hướng dẫn, kèm nội dung dự kiến để bạn xem khi duyệt kế hoạch; với 4.x, trợ lý bật tính năng ghi của thư viện. Muốn tự làm bằng lệnh, xem tính năng đang bật hay tắt và sẽ ghi vào đâu: ```bash python -c "import vnstock; print(vnstock.agent_status())" ``` Tắt hẳn **và** gỡ khối đã ghi khỏi mọi tệp, kể cả khối do bản cũ để lại. Biến môi trường ở đầu lệnh chỉ cần khi máy còn bản cũ: nó chặn chính lần `import` này ghi lại khối trong lúc đang gỡ. ```bash # macOS / Linux VNSTOCK_DISABLE_AGENT_SETUP=1 python -c "import vnstock; vnstock.disable_agent(); print(vnstock.remove_agent_files('all'))" ``` ```powershell # Windows PowerShell $env:VNSTOCK_DISABLE_AGENT_SETUP="1"; python -c "import vnstock; vnstock.disable_agent(); print(vnstock.remove_agent_files('all'))" ``` Lựa chọn lưu ở `~/.vnstock/config/agent.json`. Phần bạn tự viết trong các tệp trên được giữ nguyên; tệp chỉ chứa khối Vnstock thì bị xoá.
Một số khối rất cũ không có dấu kết thúc. Với khối kiểu đó, lệnh gỡ xoá từ đầu khối tới hết tệp. Nếu bạn đã tự viết thêm nội dung vào sau khối Vnstock trong các tệp trên, hãy chép phần đó ra chỗ khác trước khi chạy lệnh.
Dùng trong CI hay Docker thì khai báo biến môi trường: - `VNSTOCK_AGENT_TARGETS=project,codex`: bật và chỉ ghi đúng các đích liệt kê. - `VNSTOCK_AGENT_TARGETS=none` hoặc `VNSTOCK_DISABLE_AGENT_SETUP=1`: không ghi vào tệp nào. ## Bản quyền và Sử dụng Toàn bộ nội dung các bộ kỹ năng (Agent Skills), tài liệu hướng dẫn và mã nguồn liên quan được cung cấp thông qua hệ thống này đều thuộc bản quyền sở hữu trí tuệ của Vnstock.

Người dùng được cấp quyền sử dụng và cá nhân hoá các tài nguyên này nhằm phục vụ trực tiếp cho quá trình học tập, nghiên cứu và phát triển dự án. Tuy nhiên, nghiêm cấm mọi hành vi sao chép, trích xuất dữ liệu trái phép nhằm mục đích vô hiệu hóa hoặc vượt qua cơ chế xác thực tài khoản của hệ thống.

Mọi hành động tái phân phối, chia sẻ công khai, hoặc thương mại hóa tài sản trí tuệ của Vnstock dưới mọi hình thức đều cấu thành hành vi vi phạm bản quyền và sẽ bị xử lý nghiêm ngặt theo các quy định hiện hành.

[^1]: **Tải động (Dynamic Loading):** Nạp dữ liệu trực tiếp từ máy chủ qua API khi cần, thay vì lưu trữ tệp tĩnh. [^2]: **Bộ kỹ năng (Agent Skills):** Các tập lệnh và hướng dẫn chuyên biệt giúp AI hiểu kiến trúc hệ thống và thực thi tác vụ Vnstock hiệu quả. [^3]: **Nguồn tài liệu duy nhất (Single Source of Truth - SSOT):** Nguyên tắc lưu trữ và cập nhật thông tin từ một nền tảng thống nhất, tránh sai lệch. [^4]: **Tập luật khởi tạo (Bootstrap Instruction):** Các quy tắc nền tảng tự động nạp lúc khởi động để thiết lập hành vi và giới hạn cho AI. [^5]: **Điều kiện kích hoạt (Trigger Condition):** Tiêu chí xác định thời điểm một quy tắc hay chức năng cụ thể được phép thực thi. --- ## Document: Sao chép có định dạng, in và xuất PDF từ Markdown Không phải người nhận nào cũng làm việc trực tiếp với file `.md`. Markdown Live Editor giúp chuyển nội dung đã biên tập sang công cụ văn phòng hoặc bản in mà không phải dựng lại định dạng bằng tay. ## Sao chép tài liệu kèm định dạng Nút sao chép của chế độ trực quan ghi cả hai dạng dữ liệu vào bộ nhớ tạm: * HTML để ứng dụng hỗ trợ văn bản có định dạng giữ tiêu đề, chữ nhấn mạnh, danh sách, bảng và liên kết. * Plain text làm phương án tương thích với ứng dụng chỉ nhận văn bản. Bạn có thể dán nội dung vào Microsoft Word, Google Docs, email hoặc cửa sổ trò chuyện. Kết quả cuối cùng phụ thuộc vào khả năng xử lý HTML của ứng dụng đích; nên kiểm tra bảng, khối mã và hình ảnh sau khi dán. ## Khi nào nên sao chép kèm định dạng? * Gửi một phần tài liệu trong email mà người nhận không dùng Markdown. * Chuyển bản nháp sang Google Docs để cùng biên tập với nhóm nội dung. * Dán bảng và danh sách vào Word mà không dựng lại thủ công. * Đưa nội dung đã trình bày vào cửa sổ trò chuyện để giữ cấu trúc dễ đọc. Nếu người nhận cần tiếp tục làm việc bằng Git hoặc bảo toàn mã nguồn chính xác, hãy chia sẻ file Markdown thay vì văn bản có định dạng. ## Xem trước bản in Tính năng **Print** (In) mở bản xem trước được dàn trang bằng Paged.js[^pagedjs]. Từ cửa sổ trình duyệt, bạn có thể in hoặc chọn **Save as PDF** (Lưu thành PDF). Luồng thực tế gồm: 1. Rà soát tài liệu trong chế độ trực quan. 2. Mở bản xem trước khi in. 3. Kiểm tra ngắt trang, bảng, hình ảnh, đầu trang và chân trang. 4. Dùng hộp thoại in của trình duyệt để in hoặc lưu PDF. ## Cấu hình đầu trang, chân trang và số trang Các thiết lập chính: | Setting | Mặc định | Mục đích | | ------------------------------------ | ------------------------- | ------------------------------ | | `markdownLive.printHeaderFormat` | `{title}` | Nội dung đầu trang | | `markdownLive.printFooterFormat` | `{signature}` | Nội dung chân trang | | `markdownLive.printPageNumberFormat` | `{page}` | Đánh số trang; để trống để tắt | | `markdownLive.printFontFamily` | Phông chữ trình soạn thảo | Phông chữ dùng khi in | | `markdownLive.printAutoTOC` | `false` | Tạo mục lục ở đầu bản in | ## Dùng thông tin YAML làm biến khi in Bạn có thể khai báo thông tin mô tả ở đầu file: ```yaml --- title: Báo cáo kiến trúc author: Vnstock signature: Thịnh Vũ website: https://vnstocks.com --- ``` Sau đó tham chiếu trong cấu hình: ```text Đầu trang: {title} — {author} Chân trang: {signature} · {website} ``` Biến không tồn tại sẽ không thể tạo ra nội dung mong muốn, vì vậy hãy kiểm tra phần thông tin YAML ở đầu file trước khi xuất bản. ## Tạo mục lục tự động Bật `markdownLive.printAutoTOC` để thêm mục lục dựa trên tiêu đề vào đầu bản in. Trước khi lưu PDF, hãy kiểm tra: * Mỗi tài liệu có một H1 rõ ràng. * Các phần con dùng H2/H3 đúng thứ bậc. * Heading ngắn và mô tả đúng nội dung. * Không nhảy cấp tiêu đề chỉ để thay đổi kích thước chữ. ## Checklist trước khi gửi tài liệu * Mermaid và công thức đã hiển thị đúng. * Bảng rộng không bị cắt ở mép trang. * Hình ảnh có độ phân giải phù hợp. * Liên kết nội bộ cần thiết đã được chuyển thành địa chỉ người nhận truy cập được. * Đầu trang và chân trang không chứa biến thay thế rỗng. * Mục lục và số trang đúng. * Không còn ghi chú rà soát chưa được xử lý. ## Tiếp tục khám phá * [Bắt đầu với Obsidian-style Markdown Editor](/docs/tien-ich/markdown-live-editor/gioi-thieu-va-cai-dat) * [Rà soát Markdown cùng AI](/docs/tien-ich/markdown-live-editor/review-markdown-cung-ai-agent) * [Giao diện và Thao tác Điều hướng](/docs/tien-ich/markdown-live-editor/giao-dien-va-thao-tac) * [Cú pháp Markdown được hỗ trợ](/docs/tien-ich/markdown-live-editor/cu-phap-markdown-ho-tro) * [Liên kết nội bộ, liên kết ngược và đồ thị](/docs/tien-ich/markdown-live-editor/wikilinks-backlinks-va-graph-view) * [Quản lý hình ảnh và mẫu tài liệu](/docs/tien-ich/markdown-live-editor/quan-ly-hinh-anh-va-template) [^pagedjs]: **Paged.js** là thư viện dàn nội dung web thành các trang phù hợp để in hoặc lưu thành PDF. --- ## Document: Cú pháp Markdown, Mermaid và LaTeX được hỗ trợ **Markdown Live Editor** được thiết kế để hiển thị tốt các tài liệu kỹ thuật. Kế thừa triết lý từ Obsidian và GitHub, tiện ích không chỉ dừng lại ở cú pháp Markdown cơ bản mà còn hỗ trợ các khối nội dung nâng cao như toán học LaTeX, sơ đồ Mermaid, khối lưu ý Admonitions, liên kết nội bộ Wikilink và hệ thống Template. ## 1. Cú pháp Markdown Chuẩn (GitHub Flavored Markdown) ![Cú pháp markdown cơ bản](/images/markdown-live-editor/basic-markdown-syntax.png) Tiện ích hỗ trợ đầy đủ các định dạng Markdown tiêu chuẩn phổ biến: * **Tiêu đề phân cấp**: Hỗ trợ từ H1 đến H6 (`#` đến `######`). * **Định dạng phông chữ**: In đậm (`**chữ đậm**`), in nghiêng (`*chữ nghiêng*`), gạch ngang (`~~gạch ngang~~`). * **Danh sách linh hoạt**: * Danh sách không thứ tự (`*` hoặc `-`). * Danh sách có thứ tự (`1.`, `2.`). * Danh sách công việc Task list (`- [ ] Chưa xong` và `- [x] Đã hoàn thành`). * **Khối trích dẫn (Blockquote)**: Bắt đầu bằng dấu `>`. * **Mã nguồn**: Mã trong dòng (Inline code `` `code` ``) và khối mã nguồn nhiều dòng (Code block ` ``` `) với tính năng tô màu cú pháp (Syntax Highlighting) chuyên nghiệp. * **Đường phân cách nội dung**: Sử dụng `---` hoặc `***`. *** ## 2. Bảng biểu Trực quan & Tùy biến Hiển thị Bảng trong Markdown thuần thường tốn nhiều công sức căn chỉnh thủ công. Với Live Editor: * **Chỉnh sửa trực quan qua chuột phải**: Nhấp chuột phải vào bảng để *Thêm hàng/cột*, *Xóa hàng/cột*, hoặc *Xóa bảng* mà không cần căn thủ công từng dấu gạch đứng `|`. ![Menu ngữ cảnh cho bảng](/images/markdown-live-editor/table-context-menu-markdown-live-editor.png) * **Tùy biến chế độ hiển thị**: Cấu hình thông qua thiết lập `markdownLive.tableDisplayMode`: ![Cài đặt chế độ hiển thị bảng](/images/markdown-live-editor/table-display-settings.png) * `scroll`: Giữ nguyên cấu trúc dữ liệu theo cột và cho phép cuộn ngang (rất thích hợp cho bảng dữ liệu tài chính nhiều cột). * `wrap`: Tự động xuống dòng nội dung ô để bảng luôn vừa vặn với độ rộng màn hình. *** ## 3. Khối Lưu ý & Cảnh báo (Admonitions / Callouts) ![Các dạng khối cảnh báo phổ biến được hỗ trọ](/images/markdown-live-editor/obsidian-style-callouts-markdown-live-editor.png) Tạo điểm nhấn thị giác cho tài liệu bằng các khối cảnh báo và ghi chú theo chuẩn Obsidian / GitHub: ```markdown > [!NOTE] > Đây là khối ghi chú cung cấp thêm thông tin hữu ích cho người đọc. > [!TIP] > Mẹo nhỏ giúp tối ưu hóa thao tác khi soạn thảo. > [!WARNING] > Cảnh báo quan trọng cần kiểm tra kỹ trước khi tiếp tục. ``` Các loại Admonition được hỗ trợ đầy đủ kèm màu sắc và icon đặc trưng bao gồm: * **Thông tin & Ghi chú:** `note`, `info` (Thông tin chung hoặc bổ sung). * **Mẹo & Hướng dẫn:** `tip` (Mẹo và gợi ý hữu ích). * **Quan trọng & Tóm tắt:** `important`, `abstract` (Điểm quan trọng hoặc tóm tắt nội dung). * **Cảnh báo & Rủi ro:** `warning`, `caution` (Cảnh báo rủi ro hoặc lưu ý mức độ cao). * **Trạng thái & Lỗi:** `success`, `done`, `error`, `bug`, `fail`, `danger` (Báo cáo thành công, hoàn thành hoặc lỗi nghiêm trọng). * **Khác:** `quote` (Trích dẫn), `example` (Ví dụ minh họa), `question`, `todo` (Câu hỏi hoặc việc cần làm). *** ## 4. Công thức Toán học LaTeX (KaTeX) ![Hiển thị công thức toán học](/images/markdown-live-editor/katex-cong-thuc-toan-hoc-markdown-live-editor.png) Được trợ lực bởi thư viện KaTeX hiệu năng cao, các công thức toán học đều được render sắc nét, chuẩn mực như trên tạp chí khoa học: * **Công thức trong dòng (Inline)**: Bao bọc công thức bằng một cặp dấu `$`, ví dụ `$E(R) = \sum p_i r_i$`. * **Công thức khối (Block)**: Tách thành khối độc lập bằng cặp dấu `$$`: ```markdown $$ \sigma^2 = \sum_{i=1}^{n} p_i (r_i - E(R))^2 $$ ``` Công thức được hiển thị trực tiếp ngay trong quá trình gõ, giúp bạn dễ dàng rà soát ký hiệu mà không phải đọc mã LaTeX thô. *** ## 5. Lưu đồ Mermaid Phác thảo kiến trúc hệ thống, quy trình nghiệp vụ hoặc luồng dữ liệu trực tiếp bằng mã Mermaid ngay trong tài liệu mà không cần phần mềm vẽ sơ đồ rời: ````markdown ```mermaid sequenceDiagram participant Alice participant Bob Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts
prevail! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good! ``` ```` sẽ hiển thị ![Lưu đồ Mermaid trong Markdown Live Editor](/images/markdown-live-editor/mermaid-diagram-markdown-live-editor.png) ### Tính năng tương tác trên sơ đồ Mermaid: * **Thanh công cụ nổi**: Phóng to (Zoom In), thu nhỏ (Zoom Out), đặt lại tỷ lệ (Reset) và xem toàn màn hình (Fullscreen). * **Chỉnh sửa nhanh**: Nhấp đúp vào sơ đồ trong Live Mode để mở khung chỉnh sửa mã Mermaid trực tiếp. * **Tự động thích ứng theme**: Màu sắc sơ đồ tự động đồng bộ theo giao diện Sáng / Tối (Light / Dark theme) của VS Code. *** ## 6. Thẻ HTML Tương tác HTML viết xen trong Markdown được hiển thị an toàn và chuẩn xác ở chế độ trực quan, tiêu biểu là các khối đóng/mở nội dung `
` và ``: ```html
Nhấp để xem giải thích chi tiết Nội dung chi tiết được ẩn bên trong khối có thể đóng/mở tương tác trực tiếp ngay khi đang soạn thảo.
``` Khi cần kiểm soát chi tiết từng thuộc tính HTML phức tạp, bạn có thể chuyển sang **Source Mode** bằng phím tắt `Alt + M` (hoặc `Opt + M` trên macOS). *** ## 7. Chú thích cuối trang & Thẻ * **Chú thích cuối trang (Footnotes)**: Giúp tài liệu học thuật và báo cáo nghiên cứu trở nên chuyên nghiệp: ```markdown Nhận định này dựa trên phân tích dữ liệu thị trường năm 2024.[^1] [^1]: Báo cáo phân tích định lượng thị trường chứng khoán năm 2024. ``` * **Thẻ (Hashtags)**: Đặt các thẻ như `#nghien-cuu`, `#kien-truc` trong nội dung. Thẻ sẽ được nhận diện và hỗ trợ tìm kiếm, phân nhóm trong đồ thị liên kết Graph View. *** ## 8. Liên kết nội bộ & Nhúng Ghi chú * **Liên kết nội bộ (Wikilink[^wikilink])**: Cú pháp liên kết phong cách Obsidian giúp kết nối các tài liệu với nhau: ```markdown [[tong-quan-kien-truc]] [[tong-quan-kien-truc|Tài liệu Kiến trúc Hệ thống]] ``` Gõ `[[` để mở danh sách gợi ý tự động tìm file trong không gian làm việc. * **Nhúng toàn bộ nội dung file (Transclusion)**: ```markdown ![[gioi-thieu-chung]] ``` Tiện ích sẽ tự động đọc file được chỉ định, lược bỏ phần YAML Frontmatter ở đầu và nhúng trực tiếp nội dung vào vị trí khai báo. File nguồn vẫn độc lập, rất tiện lợi khi tái sử dụng các đoạn văn mẫu, quy ước chung hoặc phần mở đầu. *** ## 9. Siêu dữ liệu YAML - thuộc tính YAML ghi chú Phần siêu dữ liệu ở đầu file (được bao bọc bởi `---`) được tách biệt thành bảng **Properties** hiện đại có thể thu gọn: ```yaml --- title: "Báo cáo Phân tích Kỹ thuật" author: "Thịnh Vũ" tags: - chung-khoan - phan-tich-dinh-luong color: "#6c8cff" --- ``` Các thuộc tính này hỗ trợ quản lý dữ liệu bài viết, tự động hiển thị tiêu đề khi xuất bản in/PDF, và trường `color` sẽ định hình màu sắc điểm nút đại diện cho file trên Graph View. *** ## 10. Hệ thống mẫu ghi chú **Markdown Live Editor** tích hợp sẵn hệ thống chèn mẫu tài liệu, tương thích ngược với các cú pháp phổ biến của **Templater** trong Obsidian: Để sử dụng, hãy thiết lập thư mục chứa file mẫu trong cài đặt `markdownLive.templateFolder` (mặc định: `.vscode/templates`). ### Các Placeholder thông dụng: | Cú pháp | Ý nghĩa & Hoạt động | | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `<% tp.file.title %>` | Tự động lấy tên file hiện tại (không kèm đuôi `.md`), hữu ích khi tạo tiêu đề H1 tự động (`# <% tp.file.title %>`). | | `<% tp.date.now() %>` | Chèn ngày hiện tại theo định dạng chuẩn `YYYY-MM-DD`. | | `<% tp.date.now("format") %>` | Chèn ngày tháng theo định dạng tùy chỉnh. Hỗ trợ các token `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`. Ví dụ: `<% tp.date.now("DD/MM/YYYY HH:mm") %>`. |
Nhấn Ctrl + Shift + E (hoặc Cmd + Shift + E trên macOS) để mở menu danh sách Template và chèn ngay vào vị trí con trỏ.
*** Tiếp theo: [Liên kết nội bộ, liên kết ngược và đồ thị](/docs/tien-ich/markdown-live-editor/wikilinks-backlinks-va-graph-view). [^wikilink]: **Wikilink** là cú pháp liên kết nội bộ dạng `[[ten-ghi-chu]]`, chuẩn phổ biến trong Obsidian và các hệ thống quản lý tri thức Zettelkasten. --- ## Document: Giao diện và Thao tác # Giao diện và Thao tác Điều hướng Sức mạnh lớn nhất của **Markdown Live Editor** nằm ở khả năng dung hòa sự thanh lịch của một ứng dụng ghi chú hiện đại với tính chính xác, chặt chẽ của một môi trường phát triển (IDE). Bạn không bao giờ bị khóa chặt vào một góc nhìn duy nhất mà có thể linh hoạt chuyển đổi theo từng tác vụ. ## 1. Kiến trúc Giao diện Kép (Live Preview & Source Mode) Tùy thuộc vào nhu cầu làm việc, bạn có thể chuyển đổi mượt mà giữa hai chế độ soạn thảo: * **Live Editor (Trực quan)**: Xây dựng trên nền tảng Milkdown[^milkdown], đây là chế độ xem và soạn thảo Markdown trực quan (WYSIWYG). Mọi cú pháp tiêu đề, in đậm, bảng biểu, công thức KaTeX hay sơ đồ Mermaid đều được hiển thị định dạng ngay lập tức. * *Phù hợp khi*: Đọc và biên tập tài liệu dài, rà soát nội dung AI tạo ra, tập trung vào câu chữ thay vì ký hiệu Markdown, kiểm tra bố cục trực quan, hoặc chọn đoạn văn bản để gửi ngữ cảnh sang AI. * **Source Mode (Mã nguồn)**: Sử dụng CodeMirror 6[^codemirror], cung cấp trải nghiệm highlight cú pháp chuẩn mực, quen thuộc với lập trình viên. * *Phù hợp khi*: Chỉnh sửa YAML Frontmatter ở đầu file, kiểm tra ký tự thoát/khoảng trắng, xử lý khối HTML phức tạp, hoặc dán các khối Markdown lớn.
Nhờ thuật toán đồng bộ cuộn dựa trên tỷ lệ tiến trình, khi bạn chuyển đổi qua lại giữa hai chế độ, màn hình luôn giữ nguyên vị trí ngữ cảnh đang làm việc. Thêm vào đó, nút Open in Text Editor cho phép bạn nhanh chóng mở file bằng trình soạn thảo văn bản mặc định của VS Code để sử dụng các extension khác hoặc tiếp tục quy trình Git quen thuộc.
*** ## 2. Thanh công cụ (Toolbar) ![Thanh công cụ của Markdown Live Edito](/images/markdown-live-editor/markdown-live-editor-toolbar.png) Được hiển thị tối giản ở phía trên cùng của giao diện, thanh công cụ giúp bạn truy cập nhanh tất cả các định dạng và tính năng mở rộng một cách trực quan: * **Lịch sử chỉnh sửa**: * **Menu Hoàn tác & Làm lại** (Chứa tính năng Undo và Redo) * **Cấu trúc tài liệu (Headings)**: * `¶ Paragraph` **Dropdown Heading**: Chuyển đổi linh hoạt giữa văn bản thường (Paragraph) và các cấp độ thẻ tiêu đề từ H1 đến H6. * **Định dạng văn bản cơ bản**: * **In đậm** (Bold) * **In nghiêng** (Italic) * **Gạch ngang** (Strikethrough) * **Trích dẫn** (Blockquote) * **Chú thích / Chỉ số trên** (Footnote / Superscript) * **Mã nguồn**: * **Mã nguồn nội tuyến / Khối mã nguồn** (Inline Code / Code block) * **Danh sách (Lists)**: * **Menu Danh sách**: Trình đơn thả xuống để chèn danh sách không thứ tự (Bullet), danh sách có thứ tự (Ordered), và danh sách công việc (Task list). * **Chèn Liên kết & Đa phương tiện**: * **Liên kết thường** (Link) * **Liên kết nội bộ Obsidian** (Wikilink `[[]]`) * **Chèn Hình ảnh** (Image) * **Chèn Bảng biểu** (Table) * **Chèn Mục lục** (Table of Contents) * **Hộp thông báo**: * **Menu Admonition**: Trình đơn thả xuống để chèn các khối cảnh báo (Note, Tip, Important, Warning, Caution). * **Tiện ích & Xuất bản**: * **Tìm kiếm & Thay thế** (Find & Replace) * **Xuất file PDF** (Export PDF) * **Sao chép Rich Text kèm định dạng** (Copy HTML Clipboard) * **Điều khiển giao diện**: * **Menu Thu/Phóng** (Zoom In / Zoom Out) * **Bật/Tắt chế độ Mã nguồn** (Toggle Source Mode) * **Mở bằng VS Code Text Editor** (Plain Text Editor) *** ## 3. Câu lệnh nhanh `/` (Slash Commands) Lấy cảm hứng từ Obsidian và Notion, bạn chỉ cần gõ dấu `/` khi soạn thảo, một menu lệnh sẽ xuất hiện. Không cần rời tay khỏi bàn phím, bạn có thể dùng các phím ↓, ↑ và Enter để chọn chèn nhanh các định dạng phổ biến: * Tiêu đề (H1 - H3) * Danh sách (Bullet, Ordered, Task List) * Thành phần phức tạp: Blockquote, Code Block, Table, Image * Cấu trúc đặc thù: YAML Frontmatter, Footnote *** ## 4. Tìm kiếm & Thay thế Nhấn phím tắt `Ctrl + F` (hoặc `Cmd + F` trên macOS) hoặc nhấp biểu tượng kính lúp trên Toolbar để mở thanh tìm kiếm nội tuyến: * **Tìm kiếm toàn diện**: Quét và làm nổi bật tất cả kết quả khớp trong tài liệu. * **Điều hướng nhanh**: Nhảy tới kết quả trước/sau tức thì. * **Bộ lọc chính xác**: Hỗ trợ phân biệt chữ hoa/chữ thường (Match Case). * **Thay thế linh hoạt**: Thay thế từng vị trí hoặc Thay thế tất cả (Replace All) mà không cần chuyển sang chế độ mã nguồn. ## 5. Mục lục nội dung (TOC) Mục lục nổi thông minh tự động theo dõi cấu trúc các thẻ tiêu đề H1–H4: * Nhấp vào từng mục tiêu đề để cuộn mượt mà đến phần tương ứng. * Tự động thu gọn khi không sử dụng để giải phóng không gian soạn thảo, hoặc ghim cố định khi làm việc với tài liệu dài. *** ## 6. Phím tắt (Shortcuts) Các phím tắt được thiết kế tinh tế giúp duy trì tốc độ gõ phím. Hệ thống tự động phân biệt giữa hệ điều hành Windows/Linux và macOS: | Lệnh / Hành động | Phím tắt (Windows/Linux) | Phím tắt (macOS) | | :------------------------------ | :----------------------- | :----------------------- | | **Mở Markdown Live Editor** | `Ctrl + Alt + Shift + M` | `Cmd + Ctrl + Shift + M` | | **Lưu file hiện tại** | `Ctrl + S` | `Cmd + S` | | **Gửi bối cảnh tới AI Agent** | `Ctrl + Shift + L` | `Cmd + Shift + L` | | **Chèn Template** | `Ctrl + Shift + E` | `Cmd + Shift + E` | | **Chèn Liên kết (Link)** | `Ctrl + K` | `Cmd + K` | | **Chèn Hình ảnh** | `Ctrl + Shift + I` | `Cmd + Opt + I` | | **Chèn Bảng biểu** | `Ctrl + Shift + T` | `Cmd + Opt + T` | | **Chèn Code Block** | `Ctrl + Shift + C` | `Cmd + Opt + C` | | **Chèn Trích dẫn (Blockquote)** | `Ctrl + Shift + Q` | `Cmd + Opt + Q` | | **In đậm (Bold)** | `Ctrl + Shift + B` | `Cmd + Opt + B` | | **In nghiêng (Italic)** | `Ctrl + I` | `Cmd + I` | | **Chèn Heading 1 -> 6** | `Ctrl + Shift + 1 -> 6` | `Cmd + Opt + 1 -> 6` | | **Bật/Tắt Graph View** | `Ctrl + Shift + G` | `Cmd + Shift + G` | | **Tìm kiếm (Find)** | `Ctrl + F` | `Cmd + F` | | **Bật/Tắt Live Mode** | `Alt + M` | `Opt + M` | | **Zoom In/Out** | `Ctrl + =` / `Ctrl + -` | `Cmd + =` / `Cmd + -` | *** ## 7. Tùy biến Cấu hình (Settings) ![Mở cài đặt tiện ích mở rộng Markdown Live Editor từ Extensions](/images/markdown-live-editor/mo-cai-dat-tien-ich-markdown-live-editor.png) Extension cung cấp các thiết lập tại **User / Workspace Settings** (nhấn phím tắt `Cmd + ,` trên macOS hoặc `Ctrl + ,` trên Windows/Linux và tìm kiếm từ khóa `Markdown Live`), cho phép bạn tinh chỉnh môi trường làm việc theo đúng nhu cầu: ![Giao diện tùy chỉnh cấu hình Markdown Live Editor trong Settings](/images/markdown-live-editor/user-settings-markdown-live-editor.png)
### Cấu hình chung (General) * **Language** (`markdownLive.language`): * **Mô tả:** Lựa chọn ngôn ngữ giao diện hiển thị cho Markdown Live Editor (menu ngữ cảnh, thanh công cụ, thông báo trạng thái). * **Giá trị nhận:** * `en` (Mặc định): Tiếng Anh. * `vi`: Tiếng Việt. * **Table Display Mode** (`markdownLive.tableDisplayMode`): * **Mô tả:** Chế độ hiển thị bảng biểu trong trình soạn thảo trực quan. * **Giá trị nhận:** * `scroll` (Mặc định): Bật thanh cuộn ngang khi bảng có nhiều cột hoặc dữ liệu dài, giúp bảo toàn cấu trúc cột mà không làm vỡ bố cục. * `wrap`: Tự động ngắt chữ xuống dòng trong các ô dữ liệu để toàn bộ bảng luôn hiển thị vừa vặn trong khung nhìn. ### Trình soạn thảo & Giao diện (Editor & UI) * **Font Family** (`markdownLive.fontFamily`): * **Mô tả:** Bộ phông chữ hiển thị trong chế độ soạn thảo trực quan (WYSIWYG). * **Giá trị nhận:** * `sans-serif` (Mặc định): Phông chữ không chân hiện đại, thanh thoát và dễ đọc. * `serif`: Phông chữ có chân phong cách báo chí truyền thống, mang lại trải nghiệm đọc viết trang nhã (tương tự Medium hoặc Substack). * **Enable Slash Command** (`markdownLive.enableSlashCommand`): * **Mô tả:** Bật hoặc tắt menu gợi ý lệnh nhanh khi gõ ký tự gạch chéo `/` trong trình soạn thảo. * **Giá trị nhận:** * `true` (Mặc định): Hiển thị menu gợi ý để chèn nhanh tiêu đề, danh sách, khối mã nguồn, hình ảnh hoặc bảng. * `false`: Tắt menu Slash command nếu bạn muốn gõ ký tự `/` tự do mà không làm xuất hiện popup. ### Không gian làm việc & Quản lý ghi chú (Workspace & Notes) * **Default Note Directory** (`markdownLive.defaultNoteDirectory`): * **Mô tả:** Thư mục mặc định để lưu trữ ghi chú mới khi bạn nhấn biểu tượng **New Note** trên thanh bên (Sidebar). Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc của workspace, ví dụ: `notes/journal` hoặc `content/docs`). Mặc định để trống `""` (sẽ tạo ghi chú mới ngay tại thư mục gốc workspace). * **Sidebar Scan Directory** (`markdownLive.sidebarScanDirectory`): * **Mô tả:** Thư mục chỉ định để thanh bên Markdown Live quét và hiển thị danh sách tài liệu. Giúp tối ưu hiệu năng và giữ thanh bên gọn gàng trong các dự án lớn, monorepo hoặc website có cấu trúc thư mục phức tạp. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Ví dụ: `content/docs` hoặc `notes`). Mặc định để trống `""` (quét toàn bộ workspace). * **Template Folder** (`markdownLive.templateFolder`): * **Mô tả:** Thư mục lưu trữ các file mẫu tài liệu Markdown (.md) dùng để chèn nhanh mẫu vào bài viết hiện tại hoặc tạo ghi chú mới từ template. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc, ví dụ: `templates` hoặc `.vscode/templates`). Mặc định để trống `""` (tắt tính năng template). * **Enable Graph View** (`markdownLive.enableGraphView`): * **Mô tả:** Bật hoặc tắt tính năng hiển thị Biểu đồ liên kết cục bộ (Local Graph View) trong thanh bên để theo dõi các liên kết hai chiều (Backlinks / Outlinks). * **Giá trị nhận:** * `true` (Mặc định): Kích hoạt biểu đồ liên kết cục bộ. * `false`: Tắt biểu đồ liên kết cục bộ. * **Graph Depth** (`markdownLive.graphDepth`): * **Mô tả:** Độ sâu quét liên kết mặc định hiển thị trên biểu đồ Local Graph (xác định số cấp bậc láng giềng liên kết mở rộng từ tài liệu hiện tại). * **Giá trị nhận:** `số nguyên từ 1 đến 10` (Mặc định: `2`). ### Quản lý Hình ảnh (Images) * **Image Directory** (`markdownLive.imageDirectory`): * **Mô tả:** Thư mục tự động lưu trữ file ảnh khi bạn dán (paste) trực tiếp từ clipboard vào tài liệu Markdown. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc, ví dụ: `assets/images` hoặc `public/images`). Mặc định: `assets/images`. * **Image Public Path** (`markdownLive.imagePublicPath`): * **Mô tả:** Tiền tố thư mục áp dụng cho các đường dẫn ảnh tuyệt đối (bắt đầu bằng `/`) trong Markdown để trình soạn thảo hiển thị đúng ảnh cục bộ trong chế độ xem trước trực tiếp. Ví dụ: trong các framework web như Next.js hay Docusaurus, ảnh được viết dạng `![Ảnh](/images/banner.png)` nhưng file vật lý lưu tại `public/images/banner.png`, bạn điền `public` (hoặc `/public`) vào thiết lập này. * **Giá trị nhận:** `chuỗi ký tự` (Ví dụ: `public` hoặc `static`). Mặc định để trống `""` (phân giải trực tiếp từ thư mục gốc workspace). ### In ấn & Xuất bản PDF (Printing & Export) * **Print Header Format** (`markdownLive.printHeaderFormat`): * **Mô tả:** Định dạng nội dung tiêu đề đầu trang (Header) khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, hỗ trợ các biến YAML Frontmatter như `{title}`, `{author}`, `{date}`. Mặc định: `"{title}"`. * **Print Footer Format** (`markdownLive.printFooterFormat`): * **Mô tả:** Định dạng nội dung chân trang (Footer) khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, hỗ trợ các biến YAML Frontmatter như `{signature}`, `{website}`. Mặc định: `"{signature}"`. * **Print Page Number Format** (`markdownLive.printPageNumberFormat`): * **Mô tả:** Định dạng hiển thị số trang khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, sử dụng biến `{page}` để hiển thị số trang hiện tại (ví dụ: `Trang {page}` hoặc `Page {page}`). Mặc định: `"{page}"`. Để trống `""` nếu muốn tắt đánh số trang. * **Print Font Family** (`markdownLive.printFontFamily`): * **Mô tả:** Bộ phông chữ tùy chỉnh áp dụng riêng khi in hoặc xuất bản tài liệu sang file PDF. * **Giá trị nhận:** `chuỗi tên font` (Ví dụ: `'Times New Roman, serif'` hoặc `'Arial, sans-serif'`). Mặc định để trống `""` (sử dụng phông chữ mặc định của trình soạn thảo). * **Print Auto TOC** (`markdownLive.printAutoTOC`): * **Mô tả:** Tự động tạo và chèn Mục lục (Table of Contents) ở đầu tài liệu khi in hoặc xuất file PDF. * **Giá trị nhận:** * `true`: Tự động chèn mục lục vào bản in/file PDF. * `false` (Mặc định): Không tự động chèn mục lục. *** Tiếp theo: [Cú pháp Markdown, Mermaid và LaTeX được hỗ trợ](/docs/tien-ich/markdown-live-editor/cu-phap-markdown-ho-tro). [^milkdown]: **Milkdown** là nền tảng mã nguồn mở dùng để xây trình soạn thảo Markdown trực quan (WYSIWYG) dạng Plugin-driven. [^codemirror]: **CodeMirror 6** là thành phần soạn thảo mã nguồn hiện đại, hiệu năng cao chạy trong môi trường web/webview. --- ## Document: Giới thiệu & Cài đặt # Obsidian-style Markdown Editor: Trải nghiệm viết liền mạch ngay trong VS Code **Obsidian-style Markdown Editor** (hay *Markdown Live Editor*) biến VS Code thành môi trường soạn thảo Markdown trực quan WYSIWYG[^wysiwyg], mang trải nghiệm ghi chú và quản lý tri thức của Obsidian vào Visual Studio Code và Antigravity IDE. ![Giao diện làm việc của Markdown Live Editor](/images/markdown-live-editor/giao-dien-lam-viec-obsidian-style-markdown-editor.png) ## Vấn đề và Giải pháp ### Nỗi đau của người dùng Markdown trong kỷ nguyên Agent-first Trong kỷ nguyên làm việc theo mô hình Agent-first[^agent-first], Markdown không chỉ là văn bản thô mà còn là phương tiện giao tiếp chính giữa lập trình viên và AI. Quy trình phát triển phần mềm hiện đại là một vòng lặp tương tác liên tục: 1. Bạn tạo file `README.md` hoặc `plan.md` để phác thảo bối cảnh và yêu cầu cốt lõi. 2. AI phát triển ý tưởng thành tài liệu chi tiết kèm bảng dữ liệu, sơ đồ kiến trúc hoặc lưu đồ. 3. Bạn đọc lại, rà soát và trực tiếp chỉnh sửa những điểm chưa chính xác. 4. Bạn bôi đen đoạn văn bản cụ thể đưa vào ngữ cảnh trò chuyện để giao nhiệm vụ tiếp theo cho Agent. Tuy nhiên, **trình soạn thảo code truyền thống làm đứt gãy quy trình này**: * **Đọc tài liệu bị gián đoạn:** Việc phải đọc các khối mã phức tạp như công thức LaTeX[^latex] hay sơ đồ Mermaid[^mermaid] dưới dạng mã thô khiến bạn mất thời gian hình dung cấu trúc thực tế. * **Màn hình bị chia cắt:** Chế độ chia đôi màn hình để xem trước mặc định vừa tốn diện tích hiển thị vừa gây phân tâm khi cuộn trang.
Xem ảnh giao diện chia đôi màn hình ![Giao diện chia đôi màn hình mặc định của Visual St](/images/markdown-live-editor/split-preview-giao-dien-chia-doi-man-hinh-vscode.png)
* **Đứt gãy luồng suy nghĩ:** Phải chuyển đổi qua lại giữa VS Code và ứng dụng ghi chú chuyên biệt như Obsidian làm chậm nhịp làm việc. ### Giải pháp từ Markdown Live Editor Tiện ích mang đến trải nghiệm soạn thảo trực quan mượt mà ngay trong VS Code: * **Chỉnh sửa trực tiếp:** Viết và sửa văn bản trực tiếp trên giao diện đã định dạng mà không cần mở cửa sổ xem trước phụ. * **Hiển thị trực quan tức thì:** Tự động hiển thị sơ đồ Mermaid, công thức LaTeX, khối mã nguồn, bảng biểu và định dạng văn bản rich text. * **Đồng bộ hai chế độ:** Dễ dàng chuyển sang chế độ mã nguồn CodeMirror 6[^codemirror] khi cần can thiệp cú pháp thô, vị trí con trỏ và cuộn trang luôn được đồng bộ chính xác. * **Tương thích đa nền tảng:** Hoạt động đồng nhất trên VS Code Desktop, Remote SSH Workspace và cả trình duyệt web `vscode.dev`. ## Tính năng quản lý tri thức chuẩn Obsidian Tiện ích mang trọn vẹn những công cụ quản lý tri thức mạnh mẽ của Obsidian vào không gian làm việc của bạn: * **Không gian làm việc linh hoạt:** Quản lý toàn bộ tài liệu trong workspace như một Vault[^vault] tri thức thông qua thanh Sidebar chuyên biệt. * **Wikilinks và liên kết hai chiều:** Hỗ trợ cú pháp liên kết `[[Tên bài viết]]`[^wikilink] và nhúng file `![[Tài liệu]]`, tự động đánh chỉ mục toàn bộ tài liệu để điều hướng và kết nối ngữ cảnh nhanh chóng. * **Biểu đồ liên kết Graph View:** Trực quan hóa cấu trúc và mối quan hệ giữa các tài liệu dự án qua Graph View[^graph-view] ở cả cấp độ cục bộ lẫn toàn cục. * **Hoạt động trọn vẹn trên Desktop và Web:** Khác với nhiều tiện ích phụ thuộc môi trường máy tính cục bộ khiến tính năng quét file bị vô hiệu hóa trên trình duyệt, Markdown Live Editor tối ưu cơ chế lập chỉ mục để hoạt động mượt mà ngay trên `vscode.dev`. Khi cần đọc lại tài liệu, chỉnh sửa nhẹ hay xem biểu đồ mạng lưới trên web, mọi tính năng đều sẵn sàng mà không gặp rào cản tài nguyên. * **Frontmatter và Templates:** Chuẩn hóa siêu dữ liệu với YAML Frontmatter[^frontmatter] và tự động chèn các mẫu tài liệu đã định sẵn với biến linh hoạt như `<% tp.file.title %>`. ## Hướng dẫn Cài đặt ![Cách cài đặt tiện ích mở rộng](/images/markdown-live-editor/obsidian-style-markdown-editor-install-extension.png) 1. Mở **Antigravity IDE** hoặc **VS Code**. 2. Mở mục **Extensions** bằng phím tắt `Cmd+Shift+X` (macOS) hoặc `Ctrl+Shift+X` (Windows/Linux). 3. Tìm kiếm từ khóa: `Obsidian-style Markdown Editor`. 4. Chọn **Install**. 5. Mở cài đặt tiện ích mở rộng này như dưới đây ![Mở cài đặt tiện ích mở rộng Markdown Live Editor từ Extensions](/images/markdown-live-editor/mo-cai-dat-tien-ich-markdown-live-editor.png) ## Cách khởi động và Lệnh Command Palette ### Các cách mở Live Editor * **Cách 1 - Phím tắt:** Mở file `.md` bất kỳ và nhấn `Cmd + Ctrl + Shift + M` (macOS) hoặc `Ctrl + Alt + Shift + M` (Windows/Linux). * **Cách 2 - Biểu tượng trên thanh tiêu đề:** Khi mở file Markdown ở chế độ code thô, nhấn biểu tượng **Markdown** ở góc trên bên phải. ![Mở Markdown Live Editor bằng biểu tượng trên thanh tiêu đề Editor](/images/markdown-live-editor/mo-markdown-live-editor-tu-thanh-tieu-de.png) * **Cách 3 - Menu chuột phải:** Trong thanh Explorer, nhấp chuột phải vào file `.md` và chọn **"Open in Markdown Live Editor"**. ![Mở Markdown Live Editor từ menu chuột phải trong Explorer](/images/markdown-live-editor/mo-markdown-live-editor-tu-menu-chuot-phai-explorer.png) ### Các lệnh Command Palette hữu ích ![Danh sách lệnh Markdown Live Editor trong Command Palette](/images/markdown-live-editor/cac-lenh-command-palette-markdown-live-editor.png)
Nhấn `Cmd+Shift+P` (macOS) hoặc `Ctrl+Shift+P` (Windows/Linux) và gõ `Markdown Live` để gọi nhanh: * `Markdown Live: Toggle Graph View`: Bật hoặc tắt biểu đồ liên kết cục bộ cho file hiện tại. * `Markdown Live: Show Global Graph`: Mở biểu đồ liên kết toàn cục cho toàn bộ workspace. * `Markdown Live: Insert Template`: Chèn mẫu Markdown đã thiết lập sẵn vào vị trí con trỏ. * `Markdown Live: Re-index Vault`: Quét và cập nhật lại chỉ mục liên kết toàn bộ tài liệu trong workspace. * `Markdown Live: Send to AI Agent Context`: Gửi đoạn văn bản đang chọn vào khung chat của AI Agent để xử lý tiếp. *** Tiếp theo: [Rà soát Markdown cùng AI trong VS Code](/docs/tien-ich/markdown-live-editor/review-markdown-cung-ai-agent). [^agent-first]: **Agent-first** là mô hình làm việc lấy các tác nhân AI làm trọng tâm trong việc hỗ trợ khởi tạo, xử lý và tự động hóa các tác vụ. [^wysiwyg]: **WYSIWYG** (*What You See Is What You Get*) là phương thức hiển thị nội dung trực quan giống kết quả xuất bản ngay trong lúc soạn thảo. [^latex]: **LaTeX** là hệ thống soạn thảo chuyên dùng để biểu diễn các biểu thức toán học và tài liệu khoa học phức tạp. [^mermaid]: **Mermaid** là công cụ vẽ biểu đồ và sơ đồ luồng tự động bằng cú pháp văn bản Markdown. [^codemirror]: **CodeMirror 6** là thư viện biên tập mã nguồn thế hệ mới trên nền web, tối ưu hiệu năng cao và hỗ trợ mở rộng linh hoạt. [^vault]: **Vault** là thuật ngữ trong Obsidian dùng để chỉ thư mục gốc lưu trữ toàn bộ hệ thống tài liệu và ghi chú cá nhân. [^wikilink]: **Wikilink** là cú pháp liên kết nội bộ dạng `[[Tên tài liệu]]`, chuẩn mực kết nối thông tin trong các hệ thống quản lý tri thức cá nhân (PKM). [^graph-view]: **Graph View** là tính năng biểu diễn trực quan mối quan hệ và các liên kết chéo giữa các bài viết dưới dạng đồ thị mạng lưới. [^frontmatter]: **YAML Frontmatter** là khối dữ liệu cấu hình đặt ở đầu file Markdown giữa hai cặp dấu `---`, dùng để lưu thuộc tính bài viết như tiêu đề, ngày tạo hay thẻ phân loại. --- ## Document: Quản lý hình ảnh và mẫu Markdown trong VS Code Hình ảnh và mẫu tài liệu thường tạo ra nhiều thao tác phụ khi viết Markdown: lưu file ở đâu, dùng đường dẫn nào, đổi tên có làm hỏng liên kết không và làm sao giữ cấu trúc tài liệu nhất quán. Markdown Live Editor xử lý các bước này trong thư mục làm việc hiện tại. ## Dán hoặc kéo thả hình ảnh Khi dán hoặc kéo một ảnh vào trình soạn thảo, tiện ích: 1. Đọc dữ liệu ảnh bằng API của trình duyệt. 2. Lưu file vào thư mục cấu hình bởi `markdownLive.imageDirectory`. 3. Tạo tên file dựa trên thời điểm lưu. 4. Chèn đường dẫn Markdown tương đối từ tài liệu hiện tại đến ảnh. Thư mục mặc định là `assets/images`. Ví dụ: ```markdown ![Sơ đồ kiến trúc](../../assets/images/image-1788061200000.png) ``` Ảnh được lưu thành file riêng thay vì chuỗi base64[^base64] dài trong Markdown, vì vậy kho mã nguồn dễ rà soát và quản lý hơn. ## Đổi tên và xoá ảnh từ trình soạn thảo Mở trình đơn chuột phải trên một ảnh cục bộ để: * **Rename** (Đổi tên): đổi tên file vật lý và cập nhật đường dẫn trong tài liệu hiện tại. * **Delete** (Xoá): xác nhận rồi xoá file ảnh khỏi thư mục làm việc. Tiện ích không áp dụng thao tác file cho ảnh nhúng bằng base64. Sau khi đổi tên ảnh được dùng ở nhiều tài liệu, nên tìm kiếm toàn bộ thư mục làm việc vì đường dẫn trong các file khác không nhất thiết được cập nhật tự động. ## Kiểm tra tài nguyên khi xoá ghi chú Khi xoá một file Markdown, tiện ích có thể rà các tài nguyên cục bộ được tham chiếu và cho phép chọn ảnh liên quan để chuyển vào thùng rác. Luôn kiểm tra xem ảnh có được ghi chú khác sử dụng không trước khi xác nhận. ## Cấu hình đường dẫn ảnh cho Next.js và Vite Website thường lưu file tại `public/images/chart.png` nhưng Markdown cần dùng địa chỉ `/images/chart.png`. Đặt: ```json { "markdownLive.imagePublicPath": "public" } ``` Khi gặp: ```markdown ![Biểu đồ](/images/chart.png) ``` Chế độ trực quan sẽ tìm file vật lý tại `public/images/chart.png` mà không sửa đường dẫn dùng khi website hiển thị. Tính năng này phù hợp với Next.js, Vite và các dự án có thư mục `public`. `imagePublicPath` chỉ là phần đầu được thêm vào khi tìm file; hãy đặt giá trị tương ứng với cấu trúc thật của kho mã nguồn. ## Duyệt ghi chú trong thanh bên Markdown Live Sidebar cung cấp các tab: * **Recent Files** (File gần đây): quay lại các tài liệu vừa mở. * **Vault Files** (File ghi chú): duyệt các file Markdown trong phạm vi đã chọn. * **Annotations** (Ghi chú): xem các đoạn đã đánh dấu và nhận xét khi rà soát. Danh sách ghi chú có thể hiển thị đoạn xem trước và ảnh thu nhỏ, giúp nhận diện nội dung trước khi mở file. ## Tạo ghi chú mới Đặt `markdownLive.defaultNoteDirectory` nếu muốn ghi chú mới luôn nằm trong một thư mục như `notes` hoặc `content/docs`. Nếu để trống, tiện ích tạo ghi chú tại thư mục gốc của dự án. ## Cấu hình thư mục mẫu Đặt thư mục mẫu theo đường dẫn tương đối từ thư mục làm việc: ```json { "markdownLive.templateFolder": "templates" } ``` Sau đó dùng **Markdown Live: Insert Template** (Chèn mẫu) hoặc `Cmd/Ctrl + Shift + E` để chèn mẫu vào tài liệu hiện tại. Bạn cũng có thể tạo ghi chú mới từ mẫu trong thanh bên. ## Các biến thay thế được hỗ trợ Khi chèn mẫu vào file hiện tại: ```markdown # <% tp.file.title %> Ngày tạo: <% tp.date.now("YYYY-MM-DD") %> ``` Extension hỗ trợ: * `<% tp.file.title %>` * `<% tp.date.now() %>` * `<% tp.date.now("FORMAT") %>` với các token ngày giờ cơ bản Khi tạo ghi chú từ thanh bên, `{{title}}` được thay bằng tên ghi chú mới. Cú pháp trên lấy cảm hứng từ tiện ích Obsidian Templater[^templater] nhưng chỉ hỗ trợ một số lệnh, không chạy JavaScript hoặc toàn bộ giao diện lập trình của Templater. Hãy kiểm tra các mẫu phức tạp trước khi chuyển từ Obsidian. Tiếp theo: [Sao chép có định dạng, in và xuất PDF](/docs/tien-ich/markdown-live-editor/copy-rich-text-in-va-xuat-pdf). [^base64]: **Base64** là cách biểu diễn dữ liệu ảnh thành một chuỗi ký tự dài để nhúng trực tiếp vào văn bản. [^templater]: **Templater** là tiện ích phổ biến của Obsidian dùng để tạo tài liệu từ mẫu và chèn nội dung động. --- ## Document: Rà soát Markdown cùng AI trong VS Code # Rà soát và soạn thảo tài liệu Markdown cùng AI Trong quy trình vibe coding[^vibe-coding], tốc độ tạo nội dung thường không còn là trở ngại chính. Công việc khó hơn là **đọc, kiểm tra và phản hồi chính xác**: sơ đồ có phản ánh đúng kiến trúc không, bảng có thiếu trường dữ liệu không, hay một yêu cầu có bị AI diễn giải sai không. Markdown Live Editor biến file Markdown thành nơi rà soát ngay trong VS Code. Bạn có thể đọc tài liệu ở dạng đã định dạng, chọn đúng đoạn cần xử lý và gửi đoạn đó cho AI mà không phải sao chép toàn bộ file. ## Phối hợp giữa người dùng và AI ngay trong tài liệu Một quy trình điển hình gồm năm bước: 1. Bạn hoặc tác nhân AI tạo đề cương, kế hoạch, README hay tài liệu đặc tả. 2. Chế độ trực quan trình bày bảng, mã, Mermaid, LaTeX và khối lưu ý để bạn đọc như một tài liệu hoàn chỉnh. 3. Bạn chỉnh trực tiếp những lỗi nhỏ hoặc thêm ghi chú cho phần cần xem lại. 4. Bạn chọn đúng đoạn liên quan và gửi nó sang AI làm ngữ cảnh. 5. Khi AI cập nhật file qua VS Code, nội dung mới được đồng bộ trở lại trình soạn thảo để tiếp tục rà soát. Quy trình này giữ vai trò của AI và người dùng rõ ràng: AI hỗ trợ tạo và sửa nội dung; bạn chịu trách nhiệm đánh giá ý nghĩa, tính đúng đắn và quyết định cuối cùng. ## Gửi một đoạn sang AI 1. Bôi đen đoạn văn bản trong chế độ trực quan. 2. Chọn **Send to AI Agent Context** (Gửi làm ngữ cảnh cho AI) trên thanh công cụ nổi, hoặc nhấn `Cmd + Shift + L` / `Ctrl + Shift + L`. ![Gửi đoạn văn bản đã chọn vào ngữ cảnh chat của AI Agent](/images/markdown-live-editor/send-to-agent-chat-markdown-live-editor.png) 3. Tiếp tục nhập yêu cầu trong cửa sổ chat, chẳng hạn: * “Đối chiếu đoạn này với implementation hiện tại.” * “Viết lại cho người dùng không có nền tảng kỹ thuật.” * “Tìm giả định chưa được chứng minh trong phần này.” * “Chuyển yêu cầu này thành tiêu chí chấp nhận.” Tiện ích ưu tiên gửi đoạn được chọn qua lệnh tích hợp của Antigravity AI Agent. Nếu lệnh này không khả dụng, nội dung được chép vào bộ nhớ tạm và cửa sổ trò chuyện của VS Code được mở để bạn tiếp tục. ## Vì sao nên gửi đoạn được chọn thay vì toàn bộ file? * Giảm phần ngữ cảnh không liên quan. * Làm rõ chính xác nội dung cần AI xử lý. * Hạn chế AI sửa lan sang những phần đã được duyệt. * Giúp prompt ngắn hơn nhưng vẫn gắn với tài liệu nguồn. * Phù hợp với quá trình rà soát nhiều bước trên tài liệu dài. ## Thêm ghi chú mà không sửa file Markdown Khi chưa muốn thay đổi nội dung ngay, chọn đoạn văn và nhấn **Add Annotation** (Thêm ghi chú). Bạn có thể ghi lại câu hỏi, nhận xét hoặc việc cần xác minh. ![Thêm ghi chú Annotation cho đoạn văn bản và quản lý trên thanh bên](/images/markdown-live-editor/them-va-quan-ly-ghi-chu-annotation-markdown-live-editor.png) Các ghi chú này: * Được xem trong thẻ **Annotations** (Ghi chú) của thanh bên Markdown Live. * Có thể chỉnh sửa hoặc xoá từ giao diện. * Không chèn lời bình vào tài liệu và không làm thay đổi nội dung Markdown gốc. * Được lưu trong `.tmp/bookmarks.json` của thư mục làm việc. Vì ghi chú được lưu ngoài tài liệu, hãy quyết định theo quy ước dự án xem `.tmp/bookmarks.json` nên được chia sẻ qua Git hay thêm vào `.gitignore`. ## Ba cách áp dụng thực tế ### Review kế hoạch triển khai Mở `plan.md`, đọc các bước ở dạng tài liệu, đánh dấu phần còn mơ hồ rồi gửi riêng đoạn đó cho AI để bổ sung phần phụ thuộc, rủi ro và điều kiện hoàn thành. ### Kiểm tra tài liệu kiến trúc Hiển thị Mermaid trực tiếp để kiểm tra luồng hệ thống. Nếu sơ đồ và phần mô tả không khớp, chọn đoạn giải thích liên quan và yêu cầu AI đối chiếu với mã nguồn. ### Biên tập nội dung website Rà soát tiêu đề, bảng và khối lưu ý trong chế độ trực quan; thêm ghi chú cho nhận định cần dẫn nguồn; gửi từng đoạn sang AI để cải thiện giọng văn hoặc SEO mà không viết lại toàn bài. ## Tiếp tục sử dụng Git và VS Code như bình thường Chế độ trực quan là một trình soạn thảo tùy chọn. File vẫn là Markdown thuần, vì vậy bạn có thể: * Mở lại bằng VS Code Text Editor. * Rà soát phần thay đổi bằng Git. * Để AI hoặc công cụ khác chỉnh cùng file. * Dùng formatter, linter và pipeline xuất bản hiện có. Tiếp theo: [Giao diện và Thao tác Điều hướng](/docs/tien-ich/markdown-live-editor/giao-dien-va-thao-tac). [^vibe-coding]: **Vibe coding** là cách phát triển phần mềm bằng cách mô tả mục tiêu cho AI, kiểm tra kết quả và liên tục điều chỉnh qua nhiều vòng trao đổi. --- ## Document: Quản lý Ghi chú, Liên kết, Tags và Properties Các file Markdown riêng lẻ trở nên hữu ích hơn khi bạn nhìn thấy mối quan hệ giữa chúng và quản lý dữ liệu một cách có hệ thống. Markdown Live Editor lập chỉ mục toàn bộ thư mục làm việc để hỗ trợ Wikilink, liên kết ngược (backlinks), đồ thị liên kết và quản lý tập trung siêu dữ liệu (Tags, Properties). Tất cả các tính năng này được gom nhóm trực quan vào **4 thẻ chức năng trên thanh bên (Sidebar)**. ## Thư mục làm việc và kho ghi chú (Vault) Trong Obsidian, Vault[^vault] là thư mục gốc chứa hệ thống ghi chú. Markdown Live Editor sử dụng **thư mục làm việc của VS Code** (Workspace) làm phạm vi tương đương, giúp bạn quản lý tài liệu mà không cần thay đổi cấu trúc kho mã nguồn hay di chuyển file sang một ứng dụng bên ngoài. Bạn có thể giới hạn phạm vi quét tài liệu bằng cấu hình **Sidebar Scan Directory**. Để trống nếu muốn tiện ích quét toàn bộ thư mục làm việc hiện tại. ## Bốn công cụ quản lý trên thanh bên Markdown Live Thanh bên (Sidebar) của tiện ích được chia thành 4 nhóm công cụ chính để phục vụ các nhu cầu quản trị tài liệu khác nhau. ### 1. Quản lý File và Liên kết (Notes) Chức năng **Notes** không chỉ liệt kê các file Markdown mà còn đóng vai trò là trung tâm quản lý liên kết. * **Tạo và mở liên kết nội bộ:** Gõ `[[` trong chế độ soạn thảo trực quan để tìm kiếm và chèn nhanh file khác. Tiện ích sẽ tự động tạo đường dẫn tương đối (Wikilink). Nhấp vào liên kết sẽ mở trực tiếp tài liệu đích trong Editor. * **Liên kết hai chiều (Backlinks & Outlinks):** Khi mở một file, mục **Links** ở thanh bên sẽ thống kê ngay lập tức: * **Incoming Links (Liên kết ngược):** Những ghi chú khác đang trỏ đến file hiện tại. * **Outgoing Links (Liên kết đi):** Những ghi chú mà file hiện tại đang nhắc tới. ### 2. Khám phá ngữ cảnh trực quan (Local Graph) Công cụ **Local Graph** (Đồ thị cục bộ) lấy tài liệu bạn đang mở làm điểm trung tâm, giúp hình dung nhanh các mối quan hệ lân cận. * Đồ thị hiển thị cả liên kết đến (Incoming) lẫn liên kết đi (Outgoing). * Bạn có thể tùy chỉnh độ sâu của đồ thị (số lớp kết nối) thông qua cấu hình **Graph Depth** (mặc định là 2). * Khi bạn chuyển sang đọc file khác, điểm trung tâm và tập liên kết liên quan sẽ tự động cập nhật theo tài liệu mới. Đồ thị cục bộ giúp trả lời nhanh các câu hỏi: *Tài liệu này tham chiếu đến những ghi chú nào? Ai đang trích dẫn nó? Ngữ cảnh gần nhất là gì?* ### 3. Quản lý Thẻ phân loại (Tags) Tiện ích tự động trích xuất các thẻ (tags) từ YAML Frontmatter (ví dụ: `tags: [ai, markdown]`) của toàn bộ file trong Vault. * **Thống kê tổng quan:** Mục **Tags** liệt kê tất cả các nhãn đang được sử dụng trong dự án kèm theo số lượng bài viết tương ứng (Count). * **Sắp xếp linh hoạt:** Hỗ trợ sắp xếp theo Tên (Alphabetical) hoặc theo Số lượng (By Count) thông qua các biểu tượng trên thanh tiêu đề của View. * **Lọc tìm kiếm (Filter):** Nhấn biểu tượng kính lúp để lọc nhanh các thẻ khi số lượng tags quá lớn. Tính năng này giúp bạn dễ dàng theo dõi hệ thống phân loại nội dung, phát hiện các thẻ bị sai chính tả hoặc trùng lặp ý nghĩa để quy hoạch lại cấu trúc blog/tài liệu. ### 4. Chuẩn hóa Siêu dữ liệu (Properties) Tương tự như Tags, công cụ **Properties** (Thuộc tính) quét toàn bộ các khóa (keys) được định nghĩa trong khối YAML Frontmatter (ví dụ: `title`, `description`, `author`, `date`) của mọi file. * Tính năng này thống kê tần suất xuất hiện của từng trường thuộc tính trong toàn bộ dự án. * Tích hợp sẵn các công cụ: Sắp xếp theo Tên, Sắp xếp theo Tần suất và Lọc tìm kiếm (Filter). * **Lợi ích thực tiễn:** Giúp các tác giả hoặc kỹ sư dữ liệu (Data Engineer) kiểm soát cấu trúc siêu dữ liệu. Bạn có thể nhanh chóng phát hiện nếu có bài viết nào đang dùng sai trường `featuredImage` thành `feature_image`. ## Đồ thị toàn cục (Global Graph): Nhìn toàn cảnh hệ thống Bên cạnh đồ thị cục bộ, bạn có thể chạy lệnh **Markdown Live: Show Global Graph** (Hiện đồ thị toàn cục) từ Command Palette (hoặc biểu tượng toàn cầu trên Local Graph) để mở giao diện đồ thị lớn cho toàn bộ thư mục làm việc. Đồ thị toàn cục rất hữu ích để: * Phát hiện các "cụm" (clusters) tài liệu có độ kết nối dày đặc (ví dụ: trung tâm tri thức). * Tìm các ghi chú chưa được kết nối với hệ thống (ghi chú mồ côi) bằng tùy chọn **Show Orphans**. * Quan sát hướng liên kết rõ ràng nhờ các mũi tên chỉ hướng. ## Nhãn và màu sắc điểm trên Đồ thị Để đồ thị dễ hiểu, tiện ích ưu tiên hiển thị nhãn theo thứ tự: 1. Trường thuộc tính YAML `title` (nếu có). 2. Thẻ tiêu đề Heading H1 đầu tiên trong bài. 3. Tên file vật lý. Bạn cũng có thể thêm thuộc tính `color` (mã hex màu) vào YAML Frontmatter để tô màu riêng cho từng điểm tài liệu. Nếu không được chỉ định, đồ thị có thể tự động phân biệt màu sắc dựa trên cấu trúc thư mục chứa file. ## Hiểu đúng vai trò của Đồ thị và Siêu dữ liệu Đồ thị liên kết và bảng thống kê Properties/Tags là các công cụ hỗ trợ khám phá cấu trúc, không tự động đánh giá chất lượng nội dung. Một đồ thị dày đặc chưa chắc đã tốt; điều quan trọng là mỗi liên kết đều mang lại ngữ cảnh hữu ích cho người đọc. Với tài liệu sản phẩm hoặc kho mã nguồn, hãy ưu tiên: * Liên kết từ trang Tổng quan (Overview) đến các hướng dẫn chi tiết. * Liên kết ngược (Backlink) từ trang tra cứu API về quy trình sử dụng chính. * Xây dựng bộ chuẩn Properties đồng nhất (ví dụ: bài viết nào cũng phải có `description` và `author`). * Tránh tạo Wikilink vô tội vạ chỉ để làm đồ thị trông phức tạp hơn. *** Tiếp theo: [Quản lý hình ảnh và mẫu tài liệu Markdown](/docs/tien-ich/markdown-live-editor/quan-ly-hinh-anh-va-template). [^vault]: **Vault** là thuật ngữ Obsidian dùng để gọi thư mục gốc chứa toàn bộ hệ thống ghi chú cá nhân. --- ## Document: Giới thiệu và Cài đặt Smart Data Viewer
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Smart Data Viewer là không gian làm việc dữ liệu (data workspace) tích hợp AI dành cho môi trường VS Code và Antigravity IDE. Tiện ích này giúp bạn mở, phân tích và trích xuất ngữ cảnh trực tiếp từ các file dữ liệu do con người hoặc AI sinh ra mà không cần chuyển sang ứng dụng khác. Tiện ích giải quyết bất cập khi môi trường IDE truyền thống thiếu khả năng tương tác với dữ liệu. Khi làm việc với AI, nếu cần mở các file dữ liệu (như `.parquet`, `.csv`, `.json`), việc dùng phần mềm bên ngoài sẽ làm gián đoạn mạch làm việc [^1] và khiến việc đưa dữ liệu bị lỗi trở lại cho AI phân tích trở nên bất tiện. Quy trình làm việc của Smart Data Viewer được thiết kế theo các bước: Mở dữ liệu -> Khám phá trực quan -> Phân tích -> Trích xuất phần dữ liệu quan trọng -> Gửi cho AI -> Ghi chú kết quả. ## Các định dạng dữ liệu hỗ trợ Smart Data Viewer hỗ trợ nhiều định dạng file thường gặp trong quy trình lập trình có AI hỗ trợ [^2]: * **Bảng dữ liệu & Text:** `.csv`, `.tsv` * **Dữ liệu có cấu trúc:** `.json`, `.jsonl`, `.ndjson` * **Tài liệu văn phòng:** `.xlsx`, `.xls`, `.docx` * **Định dạng dữ liệu lớn:** `.parquet` * **Cơ sở dữ liệu cục bộ:** `.duckdb`, `.sqlite`, `.sqlite3`, `.db` * **Lưu trữ nén:** `.zip` * **Web Preview:** `.html`, `.htm` Tùy theo định dạng, tiện ích sẽ điều chỉnh cách hiển thị phù hợp. Ví dụ: Parquet hiển thị kèm kiểu dữ liệu, JSON hỗ trợ dạng bảng và dạng cây, SQLite và DuckDB cho phép duyệt các bảng dữ liệu bên trong. ## Cài đặt và Khởi chạy ### Cách cài đặt 1. Mở phần quản lý Extensions trong VS Code (phím tắt `Ctrl+Shift+X` trên Windows/Linux hoặc `Cmd+Shift+X` trên macOS). 2. Tìm kiếm từ khoá **Smart Data Viewer** (ID: `vnstock.vscode-smart-data-viewer`). 3. Nhấn **Install** để cài đặt. ### Khởi chạy Sau khi cài đặt, bạn có thể khởi chạy tiện ích qua các cách sau: * **Trong File Explorer:** Nhấp chuột phải vào file được hỗ trợ (như `.csv` hoặc `.json`), chọn **"Open with Smart Data Viewer"**. * **Thanh Activity Bar:** Ở thanh bên trái của VS Code, chọn biểu tượng Smart Data Viewer. Khu vực **Quick Launch & Scratchpad** sẽ hiển thị để mở file nhanh. * **Trình chuyển đổi:** Khi đang mở file bằng Smart Data Viewer, bạn có thể bấm vào biểu tượng `< >` (Open with Text Editor) ở góc phải trên cùng để chuyển sang chế độ xem text thông thường. ## Cấu hình (Settings) Smart Data Viewer cung cấp cấu hình hiển thị: * `smartCsv.rowIndexStart`: Cài đặt số thứ tự bắt đầu cho hàng. * Đặt là `0`: Bắt đầu từ 0 (Chuẩn của Pandas DataFrame - mặc định). * Đặt là `1`: Bắt đầu từ 1 (Chuẩn của ứng dụng Spreadsheet). [^1]: Context switching: Trạng thái ngắt quãng khi phải chuyển đổi liên tục giữa các ngữ cảnh hoặc công cụ làm việc khác nhau. [^2]: Vibe coding: Phương pháp lập trình trong đó người dùng đưa ra chỉ thị để AI tạo và hoàn thiện code. --- ## Document: Khám phá dữ liệu và Phân tích Khám phá
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Khám phá dữ liệu là bước quan trọng trước khi bạn hoặc AI đưa ra các quyết định xử lý code. Smart Data Viewer tích hợp sẵn các công cụ như hiển thị dữ liệu dạng bảng với khả năng Lazy Load [^1], bảng điều khiển Phân tích Khám phá [^2], và tính năng tổng hợp dữ liệu Pivot ngay trong môi trường làm việc. ## DataGrid và xử lý file lớn Một khó khăn khi thao tác với các file dữ liệu lớn (như CSV hoặc TSV) trong IDE là hiện tượng treo ứng dụng. Smart Data Viewer giải quyết vấn đề này qua cơ chế Lazy Loading. * **Lập chỉ mục thông minh:** Thay vì nạp toàn bộ file vào bộ nhớ của giao diện Webview [^3], tiện ích sẽ đọc file trên ổ cứng và tạo chỉ mục (index) theo byte offset. * **Phân trang (Pagination):** Giao diện bảng dữ liệu (DataGrid) chỉ tải và hiển thị 100 dòng cho trang hiện tại. Khi người dùng chuyển trang, tiện ích mới trích xuất dữ liệu tương ứng dựa trên chỉ mục. * **Trải nghiệm mượt mà:** Cơ chế này giúp việc điều hướng qua lại trên các file dữ liệu lớn diễn ra nhanh chóng, giảm thiểu tiêu tốn RAM hoặc tình trạng treo trình soạn thảo. Bạn có thể Lọc (Filter) và Sắp xếp (Sort) dữ liệu trên trang hiện tại trực tiếp tại tiêu đề của các cột. ## Phân tích Khám phá Tự động (Insights) Khi nhấn vào nút **Insights** trên thanh Toolbar, hệ thống Phân tích Khám phá sẽ chạy ngầm (background) và cung cấp tổng quan về cấu trúc dữ liệu cũng như chất lượng dữ liệu. Bảng Insights cung cấp các thông tin: 1. **Metadata tổng quát:** Số lượng dòng (Row count) và thông tin file gốc. 2. **Kiểm tra tính vẹn toàn:** Đếm và tính toán tỷ lệ phần trăm dữ liệu khuyết thiếu (Missing-value percentages) cho từng cột. 3. **Thống kê mô tả:** Tính toán các chỉ số cơ bản cho cột số (Min, Max, Mean, Median, Q1, Q3). 4. **Trích mẫu:** Lấy tối đa 100 giá trị duy nhất (unique values) của một cột để kiểm tra kiểu dữ liệu (categorical) hoặc xác định giá trị dị biệt (outliers). ## Tổng hợp dữ liệu với Pivot Tính năng Pivot trong Smart Data Viewer cho phép tổng hợp dữ liệu ngay trong IDE, tương tự Pivot Table trong Excel. Pivot Panel được hỗ trợ bởi DuckDB WebAssembly [^4], mang lại khả năng tính toán nhanh chóng. ### Cách sử dụng Data Pivot 1. Nhấn nút **Pivot** trên thanh Toolbar (áp dụng với file CSV, TSV, Parquet, DuckDB). 2. Khi giao diện hiện ra, chọn **Load Data & Initialize Engine** để nạp dữ liệu vào DuckDB. 3. Bảng cấu hình xuất hiện, cho phép chọn: * **Table:** Bảng dữ liệu cần thao tác (nếu dùng file DuckDB có nhiều bảng). * **Rows (Group By):** Chọn cột dùng để nhóm dữ liệu. * **Values:** Chọn cột chứa giá trị cần tính toán. * **Aggregation:** Lựa chọn hàm tổng hợp (hỗ trợ `SUM`, `AVG`, `COUNT`, `COUNT_DISTINCT`, `MIN`, `MAX`, `MEDIAN`, `STDDEV`, `VAR`). 4. Nhấn **Generate Pivot**. Kết quả tổng hợp sẽ hiển thị dưới dạng bảng ngay trong panel và được sắp xếp tự động theo giá trị giảm dần. Việc tích hợp DuckDB giúp quá trình nhóm dữ liệu và tính toán đạt hiệu suất cao ngay bên trong giao diện của VS Code. [^1]: Lazy Load: Kỹ thuật lập trình chỉ tải dữ liệu hoặc thành phần khi thực sự cần thiết, giúp tiết kiệm tài nguyên. [^2]: Phân tích Khám phá (Exploratory Data Analysis - EDA): Bước phân tích sơ bộ dữ liệu để nắm bắt các đặc điểm và cấu trúc chính. [^3]: Webview: Thành phần nhúng cho phép hiển thị nội dung web (HTML, CSS, JavaScript) bên trong một ứng dụng desktop hoặc mobile. [^4]: WebAssembly (WASM): Công nghệ cho phép chạy code hiệu năng cao (như C, C++, Rust) trực tiếp trên môi trường web hoặc trình duyệt. --- ## Document: Thao tác với JSON và Scratchpad
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Trong phát triển phần mềm, JSON (và các biến thể như JSONL, NDJSON) là định dạng dữ liệu thường gặp. Việc mở các file JSON lồng nhau (nested objects) bằng các trình soạn thảo code thông thường dưới dạng văn bản có thể làm giảm hiệu suất nắm bắt cấu trúc dữ liệu. Smart Data Viewer hiển thị file JSON thành các đối tượng trực quan, hỗ trợ tương tác, khám phá cấu trúc, và trích xuất một phần dữ liệu nhỏ (nhánh - subtree [^1]) để cung cấp ngữ cảnh cho AI. ## Các chế độ xem dữ liệu JSON Khi mở file `.json`, `.jsonl` hoặc `.ndjson`, tiện ích cung cấp 2 chế độ hiển thị: ### 1. JSON Tree Viewer (Chế độ Cây) Chế độ này phù hợp cho các file JSON có cấu trúc lồng nhau (ví dụ: dữ liệu cấu hình hoặc kết quả từ API). * **Mở rộng/Thu gọn:** Bạn có thể click để đóng hoặc mở các mảng (Array) và đối tượng (Object) để theo dõi cấu trúc. * **Biểu tượng trực quan:** Các giá trị chuỗi (string), số (number), boolean, hoặc null được hiển thị với màu sắc riêng, hỗ trợ phân loại bằng mắt nhanh chóng. * **Trích xuất nhánh dữ liệu:** Khi dùng chế độ Cây, nếu cần chọn một Object hoặc Array quan trọng để gửi cho AI, bạn có thể **chuột phải** (hoặc dùng nút thao tác) để gửi nhánh đó sang AI Context. Tiện ích sẽ đính kèm đường dẫn cấu trúc (object path) để AI nhận diện vị trí dữ liệu trong file gốc. ### 2. JSON Table View (Chế độ Bảng) Đối với các file `.jsonl` (JSON Lines), `.ndjson` hoặc mảng chứa nhiều đối tượng phẳng, chế độ hiển thị Bảng giúp dễ quan sát hơn. * Tính năng này sẽ làm phẳng (flatten [^2]) các khoá cấp 1 của JSON Objects thành cột (Columns), và mỗi Object sẽ hiển thị dưới dạng một hàng (Row). * Tại chế độ Bảng, bạn có thể dùng công cụ Lọc (Filtering), Sắp xếp (Sorting), hay Phân tích Khám phá (EDA) tương tự như với file CSV. * *Lưu ý:* Việc trích xuất Context tại chế độ Bảng sẽ xuất ra dạng Markdown Table, khác với dạng JSON tại chế độ Cây. ## Tính năng JSON Scratchpad Khi làm việc với Terminal hoặc API, bạn có thể nhận được dữ liệu JSON thô và cần phân tích nhanh cấu trúc mà không muốn tạo file mới trên máy tính. Tính năng **JSON Scratchpad** được thiết kế cho nhu cầu này. ### Cách sử dụng Scratchpad: 1. Sao chép đoạn văn bản JSON. 2. Từ VS Code, mở Command Palette (`Cmd+Shift+P` hoặc `Ctrl+Shift+P` trên Windows/Linux) và chạy lệnh: `Smart Data Viewer: New JSON Scratchpad`. 3. Hoặc nhấn biểu tượng **Data Hub Launcher** trên thanh Activity Bar và chọn Paste JSON. 4. Một bảng thông báo tên **PasteJsonModal** sẽ hiển thị. Dán mã JSON vào đó và nhấn xác nhận. 5. Tiện ích sẽ khởi tạo một môi trường xem bằng giao diện JSON Tree Viewer hoặc Table View để bạn khám phá. Tính năng này hỗ trợ quá trình lập trình liền mạch: Thử nghiệm API -> Copy kết quả -> Phân tích bằng Scratchpad -> Trích xuất dữ liệu quan trọng -> Gửi lại cho AI. [^1]: Subtree (Nhánh con): Một phần cấu trúc lồng nhau được trích xuất từ một cấu trúc dữ liệu dạng cây (tree) lớn hơn. [^2]: Flatten: Quá trình làm phẳng cấu trúc dữ liệu lồng nhau thành cấu trúc dữ liệu phẳng (một cấp). --- ## Document: Tích hợp AI Context và Quản lý Ghi chú
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Smart Data Viewer được thiết kế để hoạt động như một không gian làm việc dữ liệu cho AI. Trong quy trình lập trình có AI hỗ trợ, việc chắt lọc thông tin quan trọng từ file dữ liệu lớn để làm ngữ cảnh (context) cho AI là rất cần thiết. Nếu gửi toàn bộ một file lớn cho AI xử lý, quá trình này có thể chậm, tốn nhiều chi phí Token và dễ gây ra hiện tượng ảo giác (hallucination) [^1]. Smart Data Viewer giúp giải quyết vấn đề này bằng cách đóng vai trò như một bộ lọc thông tin. ## Trích xuất ngữ cảnh cho AI (AI Context) Khi xem dữ liệu trên giao diện **DataGrid** hoặc **JSON Tree Viewer**, bạn có thể trích xuất ngữ cảnh thông qua các thao tác: 1. Bôi đen các ô, hàng, cột hoặc một vùng dữ liệu cần làm rõ (hỗ trợ chọn nhiều vùng rời rạc). 2. Nhấp chuột phải và chọn **Send to AI Context**. 3. Smart Data Viewer sẽ tự động: * Lấy tiêu đề cột tương ứng. * Lấy số thứ tự hàng của dữ liệu gốc. * Chuyển đổi thành bảng định dạng Markdown. * Gửi dữ liệu này vào bộ nhớ tạm của AI thông qua API nội bộ `antigravity.addContext` (nếu sử dụng Antigravity IDE). Khi dùng môi trường khác, đoạn Markdown sẽ được lưu vào Clipboard hoặc ghi vào file `.tmp/data_context.md`. *Ví dụ:* Khi kiểm tra dữ liệu mô phỏng, bạn phát hiện một dòng có dữ liệu bất thường. Bạn bôi đen dòng đó, chọn "Send to AI Context" và yêu cầu AI sửa lỗi tương ứng. Cách làm này giúp cung cấp ngữ cảnh rõ ràng và ngắn gọn. ## Quản lý Ghi chú Dữ liệu (Data Annotations) Một yêu cầu khác trong quá trình làm việc là khả năng lưu lại các ghi chú, giả thuyết hoặc từ điển dữ liệu (Data Dictionary) mà không làm thay đổi file gốc (quy trình làm việc không phá huỷ - non-destructive workflow) [^2]. Nếu thêm cột ghi chú trực tiếp vào file CSV như khi dùng phần mềm bảng tính thông thường, cấu trúc dữ liệu sẽ bị thay đổi và có thể gây lỗi cho các đoạn mã xử lý sau này. Smart Data Viewer cung cấp tab **Notes** để giải quyết vấn đề này: * **Lưu trữ độc lập:** Khi tạo ghi chú cho dữ liệu, tiện ích sẽ tạo một file Markdown (.md) ẩn trong thư mục `.tmp/notes/`. * **Tích hợp đồng bộ:** Ghi chú hiển thị ngay cạnh giao diện xem file. Bạn có thể dùng Markdown để soạn thảo, chèn hình ảnh, hoặc lưu lại các đoạn lệnh (prompt). Ở những lần mở file tiếp theo, ghi chú sẽ tự động được tải lại. * **Duy trì bản gốc (Source of truth [^3]):** File dữ liệu gốc (`.csv`, `.parquet`, `.sqlite`...) không bị tác động. Tính năng ghi chú giúp theo dõi quá trình phân tích dữ liệu, thuận tiện cho việc làm việc nhóm hoặc khi làm việc với AI qua nhiều phiên khác nhau. [^1]: Ảo giác (Hallucination): Hiện tượng AI sinh ra thông tin sai lệch, không có thật hoặc không dựa trên dữ liệu đầu vào. [^2]: Non-destructive workflow: Quy trình xử lý không làm thay đổi hoặc phá huỷ dữ liệu gốc. [^3]: Source of truth: Nguồn dữ liệu đáng tin cậy duy nhất và nguyên bản. --- ## Document: Truy vấn SQL trực tiếp với DuckDB
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan SQL là ngôn ngữ phổ biến để thực hiện các phép lọc, kết nối (JOIN) [^1] và tổng hợp dữ liệu. Thay vì phải cài đặt các hệ quản trị cơ sở dữ liệu như PostgreSQL, MySQL hoặc chuyển dữ liệu vào Jupyter Notebook để dùng thư viện phân tích, Smart Data Viewer hỗ trợ sử dụng SQL trực tiếp trong VS Code thông qua DuckDB WebAssembly. ## DuckDB WebAssembly DuckDB là một hệ quản trị cơ sở dữ liệu phân tích nhúng. Việc tích hợp DuckDB WebAssembly vào Smart Data Viewer mang lại các lợi ích: * Truy vấn SQL được thực thi trực tiếp trên trình duyệt nội bộ của VS Code. * Không cần thiết lập máy chủ cơ sở dữ liệu bên ngoài. * Dữ liệu được xử lý cục bộ trên máy của bạn, không gửi qua máy chủ trung gian. Khi mở một file `.csv`, `.tsv`, `.parquet` hoặc `.duckdb`, bạn có thể chuyển sang tab **SQL** trên Toolbar. Tại đây, nút `Initialize Engine` sẽ tải thư viện WebAssembly vào môi trường làm việc. ## Viết truy vấn (SQL Query Panel) Sau khi DuckDB khởi tạo, giao diện **SQL Query Panel** sẽ hiển thị trình soạn thảo SQL. * **Tham chiếu bảng:** File đang mở (CSV, Parquet) tự động được ánh xạ thành một bảng ảo tên là `data` trong DuckDB. Bạn có thể truy vấn trực tiếp, ví dụ: `SELECT * FROM data LIMIT 10;`. * **Thực thi truy vấn:** Hỗ trợ các câu truy vấn phức tạp với `GROUP BY`, `HAVING`, hay hàm cửa sổ (Window functions) [^2]. Khi nhấn **Run Query**, kết quả sẽ được kết xuất dưới dạng bảng lưới ở nửa dưới màn hình. * **Trích xuất dữ liệu cho AI:** Nếu kết quả truy vấn cho thấy điểm dữ liệu bất thường (outlier) [^3], bạn có thể bôi đen kết quả đó và chọn **Send to AI Context**. Thao tác này giúp trích xuất và gửi phần dữ liệu cần thiết cho AI phân tích, thay vì gửi toàn bộ file gốc. ## Hỗ trợ DuckDB và SQLite cục bộ Smart Data Viewer cũng là công cụ xem cơ sở dữ liệu gọn nhẹ cho các định dạng `.duckdb` và họ `.sqlite` (`.sqlite`, `.sqlite3`, `.db`). * **Với file `.duckdb`:** Mở file trực tiếp, hệ thống sẽ tự động quét (scan) tất cả các bảng có trong cơ sở dữ liệu. Bạn có thể xem trước tối đa 1.000 dòng của bất kỳ bảng nào, hoặc chuyển sang tab SQL để viết truy vấn kết nối giữa các bảng. * **Với file `.sqlite`:** Tiện ích sử dụng thư viện `sql.js` để mở file cơ sở dữ liệu ở chế độ chỉ đọc trên bộ nhớ RAM (Read-only in-memory snapshot) [^4]. Bạn có thể duyệt qua các bảng và View, thực hiện phân trang, lọc, và phân tích dữ liệu tương tự như thao tác với file CSV. > [!WARNING] > Lưu ý khi dùng SQLite: Vì cơ sở dữ liệu SQLite được tải toàn bộ vào RAM dưới dạng bản sao chép, lượng RAM tiêu thụ sẽ tương đương với kích thước file `.db`. Ngoài ra, nếu có kết nối khác đang ghi dữ liệu vào file `.db-wal` nhưng chưa đồng bộ (checkpoint), Smart Data Viewer có thể không hiển thị phần dữ liệu mới đó. Điểm lợi là file gốc của bạn không bị khoá hoặc bị chỉnh sửa ngoài ý muốn. [^1]: JOIN: Phép toán trong SQL dùng để kết hợp các hàng từ hai hay nhiều bảng dựa trên cột chung. [^2]: Window functions: Hàm trong SQL thực hiện tính toán trên một tập hợp các hàng có liên quan đến hàng hiện tại. [^3]: Outlier: Giá trị ngoại lai, khác biệt đáng kể so với các quan sát còn lại trong tập dữ liệu. [^4]: Snapshot: Bản sao trạng thái của một hệ thống hoặc cơ sở dữ liệu tại một thời điểm nhất định. --- ## Document: Cấp quyền và xử lý lỗi > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Kiểm tra trạng thái quyền `vq.entitlement()` chạy trên máy, không trừ lượt. Khoá `backtest` là phần riêng của mô-đun này: ```python import vnstock_quant as vq state = vq.entitlement() print(state["tier"], state["features"]) # features gồm bt_basic, bt, bt_portfolio, bt_optimize khi được mở print(state["backtest"]["trial"]) # None nếu cấp của bạn không bị đếm lượt backtest riêng print(state["backtest"]["quota"]) # quy mô tối đa của một lần chạy ``` | Khoá | Ý nghĩa | | :--- | :--- | | `features` | Nhóm tính năng đang mở của cả thư viện; phần backtest là `bt_basic`, `bt`, `bt_portfolio`, `bt_optimize` | | `backtest.trial` | Lượt backtest trong ngày: `daily`, `used`, `remaining`, `max_symbols`, `resets_at` | | `backtest.quota` | Quy mô một lần chạy: `portfolio_symbols`, `sweep_tasks`, `monte_carlo_paths` | | `backtest.budget` | Mã hạn mức riêng của mô-đun backtest trên máy chủ; chỉ dùng để đối chiếu khi cần hỗ trợ | --- ## Bản Cộng đồng và các cấp quyền sử dụng Từ Bronze, bạn dùng được mọi tính năng của mô-đun. Các cấp quyền sử dụng chỉ khác nhau ở số lượt mỗi ngày và quy mô một lần chạy. | | Chưa đăng nhập | Cộng đồng | Bronze | Silver | Golden | Diamond | | :--- | ---: | ---: | ---: | ---: | ---: | ---: | | Backtest một mã, bảng quy tắc, kiểm tra nhìn trước tương lai | có | có | có | có | có | có | | Chỉ báo dùng được trong bảng quy tắc | 10 | 10 | 56 | 56 | 56 | 56 | | Danh mục nhiều mã, dò tham số, walk-forward, Monte Carlo | — | — | có | có | có | có | | Lượt tính mỗi ngày | 3 | 5 | 200 | 1.000 | 5.000 | không đếm riêng | | Số mã mỗi lần chạy danh mục | 1 | 1 | 10 | 30 | 100 | 400 | | Số tổ hợp mỗi lần dò tham số hoặc walk-forward | — | — | 100 | 1.000 | 10.000 | 50.000 | | Số đường mỗi lần chạy Monte Carlo | — | — | 1.000 | 5.000 | 20.000 | 100.000 | Bản Cộng đồng dùng được 10 chỉ báo trong bảng quy tắc, cùng nhóm chỉ báo mở cho bản Cộng đồng của `vnstock_quant`: `sma`, `ema`, `rsi`, `macd`, `stoch`, `bbands`, `atr`, `obv`, `vwap`, `pivots`. Bảng quy tắc dùng chỉ báo khác thì bị từ chối với `QUANT_TIER_REQUIRED` trước khi chạy, và không bị trừ lượt. Tín hiệu bạn tự tính bằng thư viện khác rồi đưa vào qua `signals` hay `entries`/`exits` thì không bị giới hạn này. Cách đếm: - **Số lượt phụ thuộc vào hàm và quy mô lần chạy.** `run` tính một lượt; `run_portfolio` tính một lượt mỗi mã; `sweep` và `walk_forward` tính theo số tổ hợp. Các hàm tính toán khác gồm `monte_carlo`, `eval_rule_dsl`, `check_rule_dsl_causality` và `detect_limit_events`. Xem số lượt còn lại trong `vq.entitlement()["backtest"]` trước khi chạy. - **Các hàm chỉ đọc không trừ lượt:** `list_brokers`, `list_profiles`, `list_presets`, `list_indicators`, `catalog`, `schema`, `vq.entitlement`, `vq.build_info`. - `check_causality` (kiểm tra hàm tín hiệu Python của bạn) và `deflated_sharpe_ratio` không trừ lượt. - Lượt làm mới mỗi ngày theo giờ Việt Nam. `trial["resets_at"]` ghi thời điểm làm mới. - **Lượt backtest là dòng ngân sách riêng** do máy chủ đặt cho mô-đun này, không trừ vào 30 phép tính mỗi ngày của chỉ báo và chỉ số tài chính. Với tài khoản đã đăng nhập, mọi lần chạy còn được tính vào hạn mức sử dụng chung của tài khoản, như các thư viện khác của Vnstock. - Diamond không bị đếm lượt riêng cho mô-đun này, chỉ tính vào hạn mức sử dụng chung. Số lượt mỗi ngày có thể được điều chỉnh mà không cần phát hành lại thư viện. Số đúng cho máy của bạn là số trong `vq.entitlement()["backtest"]`. Khi hết lượt, thư viện báo `QUANT_TRIAL_EXHAUSTED`. Khi một lần chạy vượt quy mô của cấp, thư viện báo `QUANT_QUOTA_LIMIT` kèm cấp chạy được quy mô đó. --- ## Xử lý lỗi Mọi lỗi của mô-đun thuộc cây `VnstockQuantError` của `vnstock_quant` (xem [Cài đặt và thiết lập](/docs/vnstock_quant/bat-dau/cai-dat-va-thiet-lap)). Mỗi lỗi có: - `code`: mã ổn định, dùng để rẽ nhánh trong mã của bạn; - `message`: thông điệp tiếng Việt; - `kind`: nhóm lỗi; - `retryable`: có nên thử lại không; - `action`: việc nên làm tiếp (nếu có). ```python from vnstock_quant import backtest as bt from vnstock_quant.errors import EntitlementError, VnstockQuantError try: res = bt.sweep(df, tasks, symbol="FPT") except EntitlementError as e: # TierRequiredError, QuotaExceededError print(e.code, e.message, e.action) except VnstockQuantError as e: print(e.code, e.message) ``` ## Lớp ngoại lệ | Lớp | Khi nào | | :--- | :--- | | `InputDataError` | Dữ liệu nến, tín hiệu hoặc cột theo phiên sai | | `CausalityViolationError` (con của `InputDataError`) | Bảng quy tắc dùng chỉ báo đọc dữ liệu tương lai | | `InvalidParameterError` | Tham số, hồ sơ, biểu phí, chế độ khớp lệnh không hợp lệ | | `TierRequiredError` | Cấp chưa mở tính năng, hoặc bảng quy tắc dùng chỉ báo ngoài bản Cộng đồng | | `QuotaExceededError` | Hết lượt backtest trong ngày, hoặc một lần chạy vượt quy mô của cấp | | `AuthError`, `UnsupportedError` | Khoá, thiết bị, máy chủ cấp quyền; bản đã hết hạn hoặc bị ngừng | ## Mã lỗi | `code` | Ý nghĩa | Cách xử lý | | :--- | :--- | :--- | | `QUANT_INPUT_DATA` | Dữ liệu thiếu cột ngày, ngày không đọc được, số phần tử tín hiệu hoặc cột theo phiên (`entry_limit`, `entry_stop`, `exit_stop`, `exit_tags`, `target_weights`) khác số phiên, các mã của danh mục lệch ngày | Sửa dữ liệu đầu vào | | `QUANT_INVALID_PARAMETER` | Tham số không hỗ trợ, giá trị không hợp lệ, chọn nhiều cách tính khối lượng, chế độ khớp lệnh đã gỡ (`tradingview`, `amibroker`), khai `corporate_actions` trên giá đã điều chỉnh hoặc thiếu `symbol` trong danh mục nhiều mã, `risk_per_trade_pct` mà không có mức dừng, `rebalance` dùng với hồ sơ phái sinh | Đọc `message`, sửa tham số | | `QUANT_UNKNOWN_PROFILE` | `profile` không có trong `list_profiles()` | Dùng một hồ sơ có sẵn | | `QUANT_UNKNOWN_BROKER` | `broker` không có trong `list_brokers()` | Dùng một mã có sẵn, hoặc khai `fee` | | `QUANT_CAUSALITY_VIOLATION` | Bảng quy tắc dùng `ichimoku` hoặc `vp` | Chọn chỉ báo khác | | `QUANT_TIER_REQUIRED` | Cấp hiện tại chưa mở nhóm tính năng này (ví dụ Cộng đồng gọi `sweep`), hoặc bảng quy tắc dùng chỉ báo ngoài 10 chỉ báo của bản Cộng đồng | Xem cấp cần có trong `message`, hoặc đăng ký gói ở cấp phù hợp | | `QUANT_TRIAL_EXHAUSTED` | Đã dùng hết lượt trong ngày | Chờ tới thời điểm làm mới (`vq.entitlement()["backtest"]["trial"]["resets_at"]`) | | `QUANT_QUOTA_LIMIT` | Một lần chạy vượt quy mô của cấp: số mã, số tổ hợp, số đường Monte Carlo | Giảm quy mô, hoặc dùng cấp ghi trong `message` | Lỗi từ lớp xác thực dùng chung của hệ sinh thái mang mã `VNSTOCK_AUTH_...`, ví dụ khi khoá API không hợp lệ hoặc thiết bị vượt giới hạn. Các lỗi này thuộc `EntitlementError` và có `action` hướng dẫn cụ thể.

Khi gặp QUANT_QUOTA_LIMIT hay QUANT_TRIAL_EXHAUSTED, đừng chia một lần dò tham số thành nhiều lần nhỏ để chạy tiếp. Nếu bạn dùng trợ lý AI, hãy yêu cầu nó báo lại lỗi cho bạn thay vì tự tìm đường vòng.

--- ## Document: Chạy backtest và đọc kết quả > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## `run` ```python bt.run( data, signals=None, *, entries=None, exits=None, short_entries=None, short_exits=None, tags=None, rule_dsl=None, feature_columns=None, entry_limit=None, entry_stop=None, exit_stop=None, exit_tags=None, symbol="SYMBOL", price_unit="auto", benchmark_returns=None, rf_annual=0.0, **config, ) -> BacktestResult ``` Truyền đúng một trong ba dạng tín hiệu: `signals`, `entries`/`exits`, hoặc `rule_dsl` (xem [Dữ liệu và tín hiệu](/docs/vnstock_quant/backtest/du-lieu-va-tin-hieu)). Số phần tử của tín hiệu phải bằng số phiên. `entry_limit`, `entry_stop`, `exit_stop`, `exit_tags` cũng là mảng theo phiên, cùng độ dài; mục "Lệnh giới hạn, lệnh dừng và điểm thoát" ở dưới giải thích từng tham số. | Tham số | Mặc định | Ý nghĩa | | :--- | :--- | :--- | | `symbol` | `"SYMBOL"` | Tên mã, ghi vào kết quả | | `feature_columns` | `None` | `dict` tên cột → danh sách số, dùng được như cột trong `rule_dsl` | | `price_unit` | `"auto"` | `"auto"`, `"vnd"`, `"thousand_vnd"`. Xem [Đơn vị giá](/docs/vnstock_quant/backtest/luat-thi-truong-va-phi) | | `benchmark_returns` | `None` | Lợi suất theo phiên của chỉ số so sánh, để tính các thước đo tương đối | | `rf_annual` | `0.0` | Lãi suất phi rủi ro theo năm, dùng cho Sharpe, Sortino | ### Tham số cấu hình (`**config`) | Tham số | Mặc định | Ý nghĩa | | :--- | :--- | :--- | | `init_cash` | `100_000_000` | Vốn ban đầu, theo đồng | | `profile` | `"vn_hose"` | Hồ sơ thị trường: lô, bước giá, biên độ, chu kỳ thanh toán, thuế bán | | `profile_overrides` | `None` | `dict` ghi đè từng trường của hồ sơ | | `fee` | `0.0015` | Phí mỗi chiều. Một số (cả hai chiều), tuple `(mua, bán)`, hoặc `dict` mô hình phí. Thuế bán lấy theo hồ sơ, không nằm trong `fee` | | `broker` | `None` | Mã biểu phí trong `bt.list_brokers()`, thay cho `fee` | | `execution` | `"vn_realistic"` | Chế độ khớp lệnh. Xem [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/backtest/che-do-khop-lenh) | | `execution_timing` | theo chế độ | `"next_open"`, `"next_close"`, `"same_close"` | | `same_bar_priority` | theo chế độ | `"stop_first"`, `"target_first"`, `"ohlc_path"`. Xem [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/backtest/che-do-khop-lenh) | | `use_unsettled_proceeds` | `False` | Cho phép dùng tiền bán chưa về tài khoản để mua (ứng trước tiền bán) | | `stop_loss_pct` | `None` | Cắt lỗ theo tỷ lệ so với giá vào, ví dụ `0.07` là 7% | | `take_profit_pct` | `None` | Chốt lời theo tỷ lệ | | `trailing_stop_pct` | `None` | Cắt lỗ đuổi theo đỉnh, theo tỷ lệ | | `trail_activation_pct` | `None` | Cắt lỗ đuổi chỉ bật sau khi lãi đạt tỷ lệ này | | `breakeven_trigger_pct` | `None` | Lãi đạt tỷ lệ này thì dời điểm dừng về giá hoà vốn (đã tính phí hai chiều và thuế bán) | | `take_profit_levels` | `None` | Chốt lời từng phần, ví dụ `[{"pct": 0.1, "qty_pct": 0.5}, {"pct": 0.2, "qty_pct": 0.5}]` | | `max_holding_bars` | `None` | Bán ở giá mở cửa sau khi giữ đủ số phiên này | | `pyramiding` | `1` | Số lô tối đa của một vị thế cùng mã | | `order_valid_bars` | `1` | Số phiên một lệnh giới hạn/dừng còn hiệu lực trước khi hết hạn | | `account_guard` | `None` | Ngừng mở vị thế mới khi sụt giảm hoặc chuỗi lệnh lỗ vượt ngưỡng | | `slippage_pct` | `0.0` | Trượt giá bất lợi mỗi lần khớp, theo tỷ lệ | | `slippage_ticks` | `0.0` | Trượt giá bất lợi thêm, theo số bước giá của hồ sơ | | `fee_per_contract` | `None` | Phí cố định mỗi đơn vị (mỗi hợp đồng VN30F) mỗi chiều, cộng thêm vào phí theo tỷ lệ | | `prices_adjusted` | `True` | Dữ liệu là giá đã điều chỉnh. Muốn khai `corporate_actions` thì dùng giá gốc và đặt `False` | | `corporate_actions` | `None` | Cổ tức tiền, cổ phiếu thưởng, quyền mua. Xem [Luật thị trường, phí và sự kiện](/docs/vnstock_quant/backtest/luat-thi-truong-va-phi) | | `shock_events` | `None` | Kịch bản sốc do bạn tự khai | Truyền một tham số không có trong bảng là lỗi `QUANT_INVALID_PARAMETER`. ### Khối lượng mỗi lệnh Chọn tối đa một cách. Không chọn thì mỗi lệnh dùng toàn bộ tiền mặt đang có. | Tham số | Ý nghĩa | | :--- | :--- | | `position_size_pct` | Tỷ lệ tiền mặt đang có, ví dụ `0.5` là một nửa | | `size_equity_pct` | Tỷ lệ tổng tài sản | | `size_value` | Số tiền cố định mỗi lệnh | | `size_qty` | Số cổ phiếu cố định mỗi lệnh | | `risk_per_trade_pct` | Tỷ lệ tài sản sẵn sàng mất nếu giá chạm điểm dừng: khối lượng = `vốn × risk_per_trade_pct / |giá vào − mức dừng|`. Cần có `stop_loss_pct` hoặc cột `exit_stop`; thiếu cả hai là lỗi `QUANT_INVALID_PARAMETER` | Chọn thêm `max_position_pct` để giới hạn giá trị một vị thế theo tỷ lệ tài sản, áp dụng cùng với cách tính khối lượng ở trên. Khối lượng được làm tròn xuống theo lô của hồ sơ (100 cổ phiếu với cổ phiếu Việt Nam). Ở chế độ mặc định, thư viện chừa đủ tiền cho phí; không đủ tiền cho một lô thì lệnh bị ghi vào `rejected_orders` với mã `INSUFFICIENT_CASH`. --- ## Lệnh giới hạn, lệnh dừng và điểm thoát Mặc định, lệnh vào khớp ở giá mở cửa phiên sau tín hiệu (lệnh thị trường). Bốn cột theo phiên dưới đây cho vào lệnh có điều kiện và dừng lỗ đổi theo thời gian, đều là mảng cùng độ dài với dữ liệu, phần tử `None`/`null` nghĩa là không đặt ở phiên đó. ### Lệnh vào có điều kiện ```python res = bt.run( df, sigs, entry_limit=[None, 58_000.0, None, ...], # chỉ mua ở phiên 1, với giá giới hạn 58.000 đ order_valid_bars=3, # lệnh chờ tối đa 3 phiên rồi hết hạn ) ``` - `entry_limit`: giá giới hạn. Lệnh khớp ở giá giới hạn hoặc giá mở cửa tốt hơn, nhưng chỉ khi giá đã **đi qua mức đặt** một số bước giá (`limit_fill_ticks` của hồ sơ, mặc định 1 bước cho cổ phiếu Việt Nam và `vn_futures`, 0 cho các hồ sơ khác) — chạm đúng mức chưa chắc đã tới lượt khớp trong hàng đợi thật. - `entry_stop`: giá dừng (mua khi giá vượt lên, kiểu lệnh breakout). Khớp tại mức dừng, hoặc tại giá mở cửa nếu phiên mở cửa đã vượt qua mức đó. - Đặt cả hai cùng phiên thành lệnh **dừng-giới hạn**: lệnh giới hạn chỉ kích hoạt sau khi giá chạm mức dừng; nếu giá đã vượt qua giới hạn ngay lúc đó, lệnh dừng-giới hạn chuyển thành lệnh giới hạn thường từ phiên sau. - Lệnh chờ tính từ phiên sau tín hiệu, tối đa `order_valid_bars` phiên (mặc định 1, tức chỉ xét đúng phiên kế tiếp). Giá đặt ngoài biên độ của phiên thì chờ ở giá trần/sàn, không bị bỏ ngay. - Một tín hiệu thoát cùng chiều ở phiên sau hủy lệnh chờ chưa khớp. ### Dừng lỗ, chốt lời và chốt lời từng phần ```python res = bt.run( df, sigs, stop_loss_pct=0.07, trailing_stop_pct=0.10, trail_activation_pct=0.05, # cắt lỗ đuổi 10%, chỉ bật khi đã lãi 5% breakeven_trigger_pct=0.08, # lãi 8% thì dời điểm dừng về giá hoà vốn take_profit_levels=[{"pct": 0.10, "qty_pct": 0.5}, {"pct": 0.20, "qty_pct": 0.5}], max_holding_bars=40, ) ``` - Mức dừng ràng buộc là mức **chặt nhất** trong các mức đang bật: `stop_loss_pct`, cắt lỗ đuổi (khi đã kích hoạt), hoà vốn (khi đã kích hoạt), và cột `exit_stop` nếu có. - `exit_stop`: mức dừng lỗ tự tính (ví dụ theo ATR, theo đáy swing), biết tại giá đóng cửa phiên `t`, có hiệu lực từ phiên `t+1`. Cách này tránh nhìn trước tương lai: mức dừng của phiên `t+1` không được tính từ giá cao/thấp của chính phiên `t+1`. - `breakeven_trigger_pct`: giá hoà vốn tính cả phí mua, phí bán và thuế bán 0,1%, không phải đúng giá vào — dời về đúng giá vào vẫn còn lỗ phí và thuế. - `take_profit_levels`: mỗi mức bán `qty_pct` khối lượng **đã mua ban đầu** khi lãi đạt `pct`, làm tròn theo lô; các mức phải xếp theo `pct` tăng dần và tổng `qty_pct` không vượt 1. Mức cuối của một kế hoạch đủ 100% bán hết phần còn lại. Mỗi mức khớp tạo một lệnh riêng, `exit_reason` dạng `take_profit_1`, `take_profit_2`, ... - `max_holding_bars`: thoát ở giá mở cửa ngay sau khi giữ đủ số phiên này, không cần chờ tín hiệu hay chạm mức dừng. - `same_bar_priority` (xem [Chế độ khớp lệnh](/docs/vnstock_quant/backtest/che-do-khop-lenh)) quyết định thứ tự khi một phiên chạm cả mức dừng và mức chốt lời. --- ## Nhiều lô và pyramiding Mặc định mỗi mã chỉ giữ một lô. Đặt `pyramiding` lớn hơn 1 để tín hiệu vào cùng chiều, khi đang giữ vị thế, mở thêm một lô mới thay vì bị bỏ qua: ```python # entries có hai điểm mua (ví dụ bar 10 và bar 40); tags đặt "lan_1"/"lan_2" tương ứng res = bt.run(df, entries=entries, exits=exits, tags=tags, pyramiding=2) # exits ở bar 60 chỉ thoát lô "lan_1", lô còn lại tiếp tục giữ exit_tags = [None] * len(df) exit_tags[60] = "lan_1" res = bt.run(df, entries=entries, exits=exits, tags=tags, exit_tags=exit_tags, pyramiding=2) ``` - Mỗi lô giữ giá vào, phí, khối lượng và lịch thanh toán T+2.5 riêng. Mức dừng lỗ, chốt lời và giá trị tài khoản tính theo **giá vốn bình quân** của các lô đang mở, giống cách công ty chứng khoán hiển thị. - Lệnh thoát bán theo thứ tự **vào trước ra trước (FIFO)**: mỗi lô bán ra một dòng riêng trong `trades`, không gộp chung. - `tags` gắn nhãn cho từng lệnh vào; `exit_tags` cho tín hiệu thoát chỉ bán các lô mang đúng nhãn đó (ví dụ "chỉ thoát lô mua lần hai"), bỏ trống thì thoát theo FIFO trên mọi lô. - `open_positions` có một dòng cho mỗi lô còn mở, không gộp theo mã. --- ## Chặn rủi ro cấp tài khoản ```python res = bt.run( df, sigs, account_guard={"max_drawdown_pct": 0.2, "max_loss_streak": 5, "close_positions": False}, ) print(res.summary()["halted_on"]) ``` `account_guard` xét ở cuối mỗi phiên, trên tài sản tính theo giá đóng cửa và trên các lệnh đã đóng tới phiên đó: - `max_drawdown_pct`: dừng khi tài sản sụt quá tỷ lệ này so với đỉnh. - `max_loss_streak`: dừng khi có đủ số lệnh lỗ liên tiếp. - Khi kích hoạt: hủy mọi lệnh đang chờ, từ chối (`ACCOUNT_HALTED`) mọi lệnh vào sau thời điểm đó, và nếu `close_positions=True` thì xếp lệnh bán hết vị thế đang mở ở giá mở cửa phiên sau (vẫn chịu khóa sàn và chờ T+2.5 như lệnh thường). - Phiên kích hoạt ghi ở `res.summary()["halted_on"]` (`None` nếu chưa từng kích hoạt). --- ## Đọc kết quả `run` trả một `BacktestResult`: | Thuộc tính / hàm | Nội dung | | :--- | :--- | | `summary()` / `tear_sheet` | Bảng tổng hợp: lợi nhuận, rủi ro, thống kê lệnh, bộ đếm lệnh bị chặn, cảnh báo | | `trades` / `trades_df()` | Danh sách lệnh đã đóng, một dòng cho mỗi lô bán ra | | `rejected_orders` | Lệnh không khớp được và lý do | | `open_positions` | Vị thế còn mở ở phiên cuối, một dòng cho mỗi lô | | `equity_curve` / `equity_df()` | Trạng thái tài khoản từng phiên | | `daily_returns` | Lợi suất theo phiên, dùng cho Monte Carlo và Deflated Sharpe | | `final_equity` | Tổng tài sản cuối kỳ | | `warnings` | Cảnh báo về giả định: đơn vị giá, khớp ở giá đóng cửa, phiên giao dịch ngoài biên độ tính từ giá tham chiếu, vị thế còn mở ở phiên cuối | ### Tear sheet | Nhóm | Trường | | :--- | :--- | | Lợi nhuận | `final_equity`, `net_profit`, `total_return_pct`, `cagr_pct`, `buy_hold_return_pct` (mua-giữ chính mã đó, trước phí và cổ tức; `None` với danh mục) | | Rủi ro | `annual_volatility_pct`, `sharpe_ratio`, `sortino_ratio`, `calmar_ratio`, `omega_ratio`, `max_drawdown_pct`, `intrabar_max_drawdown_pct`, `max_runup_pct`, `max_drawdown_duration_bars`, `max_drawdown_recovery_bars`, `ulcer_index`, `recovery_factor` | | Lệnh | `total_trades`, `winning_trades`, `losing_trades`, `win_rate_pct`, `gross_profit`, `gross_loss`, `profit_factor`, `payoff_ratio`, `expectancy`, `sqn`, `avg_holding_bars`, `exposure_pct`, `largest_win`, `largest_loss`, `max_consecutive_wins`, `max_consecutive_losses`, `avg_bars_winning`, `avg_bars_losing`, `avg_mfe_pct`, `avg_mae_pct` | | Chi phí | `total_commission`, `total_tax`, `total_dividends` | | Ma sát thị trường | `limit_up_blocked_buys`, `limit_down_blocked_sells`, `t2_blocked_sells`, `insufficient_cash_entries` | | Khác | `open_positions` (số lô còn mở), `open_unrealized_pnl`, `halted_on`, `rebalance_count`, `warnings`, `quant_risk_metrics` | `quant_risk_metrics` là các thước đo rủi ro tính bằng `vnstock_quant`: `skew`, `kurtosis`, `var_historical`, `var_normal`, `var_cornish_fisher`, `cvar_historical`, `cvar_normal`, `downside_deviation`, `stability`, `limit_hit_ratio`, `zero_return_ratio` và các thước đo ở trên dưới dạng số thập phân. `intrabar_max_drawdown_pct` tính sụt giảm theo giá thấp nhất trong phiên, nên luôn sâu hơn hoặc bằng `max_drawdown_pct` (tính theo giá đóng cửa). `max_runup_pct` là mức tăng lớn nhất của tài sản (theo giá đóng cửa) từ một đáy trước đó. `max_drawdown_duration_bars` là số phiên dài nhất tài sản nằm dưới đỉnh cũ; `max_drawdown_recovery_bars` là số phiên từ đáy sâu nhất quay lại đỉnh cũ (`None` nếu chưa hồi phục).

total_trades, win_rate_pct, profit_factor và các thống kê lệnh khác chỉ tính trên lệnh đã đóng. open_unrealized_pnl (lãi/lỗ của các lô còn mở, tính theo giá đóng cửa cuối) vẫn nằm trong net_profit và đường tài sản, nhưng không vào thống kê lệnh. Một vị thế đang lỗ nặng mà chưa có tín hiệu thoát sẽ không hiện trong total_trades — đọc cả open_positions trước khi kết luận từ thống kê lệnh. Còn vị thế mở ở phiên cuối thì res.warnings có một dòng nhắc.

Ví dụ tear sheet (chạy ngày 15/10/2026) Ví dụ ở trang [Giới thiệu](/docs/vnstock_quant/backtest/gioi-thieu), dữ liệu FPT từ 04/01/2021 tới 30/09/2026 (1.429 phiên, giá đã điều chỉnh), biểu phí `ssi`. Đây là kết quả chạy thử để minh hoạ cấu trúc đầu ra, không phải dự báo. ```text total_return_pct 6.85 max_drawdown_pct -7.15 total_trades 2 win_rate_pct 50.0 total_commission 571657.5 total_tax 194360.0 exposure_pct 4.97 warnings ['Giá có trung vị 61.43 nên được hiểu là nghìn đồng ...'] ```
### Lệnh đã đóng Mỗi phần tử của `trades` là một lô đã bán: `symbol`, `side` (`long`/`short`), `entry_date`, `entry_price`, `exit_date`, `exit_price`, `quantity`, `gross_pnl`, `entry_fee`, `exit_fee`, `exit_tax`, `funding_cost`, `net_pnl`, `return_pct`, `holding_bars`, `holding_days`, `exit_reason`, `tag`, `mfe_pct`, `mae_pct`. `mfe_pct`/`mae_pct` (biên độ thuận lợi/bất lợi, *maximum favourable/adverse excursion*) là mức lãi/lỗ tốt nhất và xấu nhất mà giá đạt được trong lúc giữ lô, tính theo % giá vào — kể cả khi lệnh cuối cùng thoát ở mức khác. `exit_reason`: | Giá trị | Ý nghĩa | | :--- | :--- | | `signal_exit` | Thoát theo tín hiệu | | `stop_loss`, `take_profit`, `trailing_stop` | Chạm điểm dừng | | `breakeven_stop` | Chạm điểm dừng đã dời về giá hoà vốn (`breakeven_trigger_pct`) | | `dynamic_stop` | Chạm mức dừng tự tính ở cột `exit_stop` | | `take_profit_1`, `take_profit_2`, ... | Chạm một mức trong `take_profit_levels` (đánh số theo thứ tự khai) | | `time_exit` | Thoát vì giữ đủ `max_holding_bars` phiên | | `rebalance` | Bán bớt để tái cân bằng về tỷ trọng mục tiêu (xem [Danh mục, tối ưu và chống quá khớp](/docs/vnstock_quant/backtest/danh-muc-va-toi-uu)) | | `account_halt` | Bán hết vì `account_guard` đã kích hoạt (`close_positions=True`) | | `..._delayed_by_floor_lock` | Lệnh thoát bị hoãn vì phiên khóa sàn, khớp ở phiên đầu tiên bán được | | `..._delayed_by_settlement` | Lệnh thoát bị hoãn vì cổ phiếu chưa về tài khoản (T+2.5) | Giá trong lệnh tính theo đồng sau khi quy đổi đơn vị. ### Vị thế còn mở Mỗi phần tử của `open_positions` là một lô chưa bán hết: `symbol`, `side`, `entry_bar`, `entry_date`, `entry_price`, `quantity`, `mark_price`, `mark_date` (giá và ngày đóng cửa phiên cuối, dùng để đánh giá), `holding_bars`, `unrealized_pnl` (đã trừ phí mua, chưa trừ phí bán và thuế bán), `return_pct`. ```python table = res.trades_df(include_open=True) # nối open_positions vào bảng lệnh, cột status="open"/"closed" ``` `trades_df(include_open=True)` thêm các lô còn mở vào cuối bảng, đánh giá ở giá đóng cửa phiên cuối (`exit_reason="open"`), kèm cột `status`. Thống kê trong `summary()` luôn chỉ tính lệnh đã đóng, không đổi theo tham số này. ### Lệnh bị chặn Mỗi phần tử của `rejected_orders`: `symbol`, `date`, `side`, `reason_code`, `message`. | `reason_code` | Ý nghĩa | | :--- | :--- | | `LIMIT_UP_LOCKED` | Lệnh vào vị thế mua rơi vào phiên khóa trần, không có người bán; lệnh bị bỏ, không chuyển sang phiên sau | | `LIMIT_DOWN_LOCKED` | Lệnh bán rơi vào phiên khóa sàn, không có người mua; lệnh được giữ lại cho phiên sau | | `T2_SETTLEMENT_LOCKED` | Cổ phiếu mua chưa về tài khoản; lệnh được giữ lại tới phiên bán được | | `SHARES_NOT_LISTED` | Cổ phiếu thưởng hoặc cổ phiếu mua theo quyền chưa tới ngày niêm yết; lệnh chờ tới ngày đó, không tính vào `t2_blocked_sells` | | `INSUFFICIENT_CASH` | Không đủ tiền cho một lô sau phí | | `NO_STOP_FOR_RISK_SIZING` | Tính khối lượng theo `risk_per_trade_pct` nhưng không có `stop_loss_pct` hay `exit_stop` nằm phía lỗ của giá vào | | `RIGHTS_CASH_LIMITED` | Thực hiện quyền mua nhưng tiền mặt không đủ mua hết số quyền được hưởng; mua được bao nhiêu hay bấy nhiêu | | `ACCOUNT_HALTED` | `account_guard` đã kích hoạt; lệnh vào bị bỏ | --- ## Biểu đồ ```python res.plot(output_path="fpt.png") # ảnh tĩnh: nến, điểm vào/ra, đường vốn, sụt giảm html = res.plot_html(output_html="fpt.html") # trang HTML tương tác (tuỳ chọn) ``` `plot()` cần [`vnstock_chart`](/docs/vnstock-chart) (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) và chỉ có cho backtest một mã. Ảnh tĩnh phù hợp khi trợ lý AI cần đọc lại kết quả, hoặc khi bạn chèn vào báo cáo. --- ## Document: Chế độ khớp lệnh và đối chứng > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Hai thư viện backtest chạy cùng một chiến lược trên cùng dữ liệu vẫn có thể ra hai kết quả khác nhau. Lý do không phải một bên tính sai, mà là mỗi bên chọn một giả định khác nhau cho những câu hỏi như: lệnh khớp ở giá nào, cắt lỗ xét theo giá thấp nhất hay giá đóng cửa, khối lượng tính theo giá nào. `vnstock_quant.backtest` gom mọi lựa chọn đó vào tham số `execution`. Mỗi chế độ là một bộ lựa chọn có tên. ## Các chế độ có sẵn | `execution` | Dùng khi | Luật thị trường VN | | :--- | :--- | :--- | | `vn_realistic` (mặc định) | Backtest cổ phiếu Việt Nam | có | | `frictionless` | Thử nhanh ý tưởng, không lô, không biên độ, không T+ | không | | `backtesting_py` | So kết quả với backtesting.py | không | | `backtrader` | So kết quả với backtrader | không | | `vectorbt` | So kết quả với vectorbt (`Portfolio.from_signals`) | không | | `zipline` | So kết quả với zipline-reloaded | không | | `lean` | Gần với QuantConnect Lean, **chưa đối chứng** | không | `bt.list_presets()` trả đủ các lựa chọn của từng chế độ. Truyền `execution` dạng `dict` để sửa một lựa chọn: ```python res = bt.run(df, sigs, execution={"preset": "vn_realistic", "stop_trigger": "close"}) ``` ## Các lựa chọn | Khoá | Giá trị | Ý nghĩa | | :--- | :--- | :--- | | `timing` | `next_open`, `next_close`, `same_close` | Tín hiệu phiên `t` khớp ở giá mở cửa phiên `t+1`, giá đóng cửa phiên `t+1`, hay giá đóng cửa chính phiên `t`. `same_close` có cảnh báo nhìn trước tương lai | | `market_rules` | `true`, `false` | Áp lô, bước giá, biên độ, khóa trần/sàn, chu kỳ thanh toán | | `stop_trigger` | `intrabar`, `close` | Cắt lỗ kích hoạt khi giá thấp nhất chạm mức, hay khi giá đóng cửa vượt mức | | `stop_fill` | `gap_aware`, `at_level` | Giá khớp của cắt lỗ: tại mức đặt, hoặc tại giá mở cửa nếu phiên mở cửa đã vượt qua mức đó; hay luôn tại mức đặt | | `same_bar_priority` | `stop_first`, `target_first`, `ohlc_path` | Phiên chạm cả mức cắt lỗ và mức chốt lời thì giả định cái nào xảy ra trước. `ohlc_path` suy ra thứ tự từ khoảng cách giá mở cửa tới giá cao/thấp trong phiên (cách TradingView giả định), chỉ nên dùng để so sánh | | `stops_on_entry_bar` | `true`, `false` | Xét cắt lỗ ngay trong phiên vào lệnh | | `trail_reference` | `prior_highs`, `include_current_high`, `prior_closes` | Đỉnh dùng cho cắt lỗ đuổi. `include_current_high` lạc quan: lấy cả giá cao của chính phiên đang xét | | `sizing_price` | `fill_price`, `signal_close` | Tính khối lượng theo giá khớp, hay theo giá đóng cửa phiên phát tín hiệu | | `reserve_fees` | `true`, `false` | Chừa tiền cho phí khi tính khối lượng | | `enforce_cash` | `true`, `false` | Không cho mua vượt tiền mặt | | `check_cash_at_signal` | `true`, `false` | Kiểm tiền cả lúc phát tín hiệu, không chỉ lúc khớp | | `signal_conflict` | `exit_wins`, `ignore_both` | Phiên có cả tín hiệu vào và thoát | | `cash_buffer_pct` | số | Tỷ lệ tiền mặt luôn để dành | | `use_unsettled_proceeds` | `true`, `false` | Dùng tiền bán chưa về để mua | `vn_realistic` chọn hướng thận trọng ở mọi chỗ có thể chọn: khớp ở giá mở cửa phiên sau, cắt lỗ xét theo giá thấp nhất, giá khớp tính cả khoảng trống giá, ưu tiên cắt lỗ khi một phiên chạm cả hai mức, đỉnh của cắt lỗ đuổi chỉ lấy từ các phiên trước, chừa tiền cho phí, không dùng tiền chưa về. ## Những khác biệt đáng biết giữa các thư viện Ba khác biệt dưới đây chỉ lộ ra khi chạy song song các thư viện trên cùng kịch bản: - **zipline** xét cắt lỗ theo giá đóng cửa và khớp ở giá đóng cửa phiên sau. Chiến lược có cắt lỗ chặt thường ra kết quả khác hẳn so với thư viện xét theo giá thấp nhất. - **vectorbt** (`from_signals`) bỏ cả tín hiệu vào lẫn tín hiệu thoát khi hai tín hiệu rơi vào cùng một phiên. Các thư viện khác thường cho tín hiệu thoát thắng. - **backtrader** kiểm tiền hai lần: lúc tạo lệnh theo giá đóng cửa phiên phát tín hiệu, và lúc khớp. Phiên sau mở cửa cao hơn thì lệnh có thể bị từ chối dù lúc phát tín hiệu vẫn đủ tiền. ## Đối chứng Mỗi chế độ đối chứng được kiểm bằng 11 kịch bản chung: - khối lượng cố định, không phí và có phí; - khoảng trống giá xuyên qua mức cắt lỗ, và xuyên qua mức chốt lời; - một phiên chạm cả mức cắt lỗ lẫn mức chốt lời; - cắt lỗ ngay trong phiên vào lệnh; - khối lượng theo tỷ lệ tài sản, có phí và không phí; - tín hiệu vào khi đang giữ vị thế; - cắt lỗ đuổi; - giao cắt đường trung bình trên một chuỗi giá ngẫu nhiên. Mỗi kịch bản chạy trên thư viện gốc, rồi chạy lại bằng `vnstock_quant.backtest` ở chế độ tương ứng với `profile="frictionless"` và cùng mức phí. Kết quả ngày 14/10/2026: | Thư viện tham chiếu | Bản | Kết quả | | :--- | :--- | :--- | | backtesting.py | 0.6.6 | khớp 11/11 | | backtrader | 1.9.78.123 | khớp 11/11 | | vectorbt | 1.1.2 | khớp 11/11 | | zipline-reloaded | 3.1.1 | khớp 11/11 | "Khớp" nghĩa là cùng số lệnh, cùng ngày và giá vào/ra, và đường vốn từng phiên lệch không quá 0,000001. QuantConnect Lean chưa đối chứng, nên chế độ `lean` chỉ là xấp xỉ. Để so với thư viện bạn đang dùng: ```python res = bt.run(df, sigs, profile="frictionless", fee=0.001, execution="backtrader") ``` TradingView và Amibroker chưa có chế độ đối chứng. Kết quả của hai công cụ này phụ thuộc cài đặt trong Strategy Tester và Analysis, không tự động tái tạo được. Gọi `execution="tradingview"` hay `"amibroker"` sẽ báo lỗi `QUANT_INVALID_PARAMETER` kèm danh sách chế độ đã đối chứng. --- ## Document: Danh mục, tối ưu và chống quá khớp > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Các hàm trên trang này mở từ cấp Bronze. deflated_sharpe_ratio mở cho mọi cấp. Xem quy mô mỗi lần chạy ở trang Cấp quyền và xử lý lỗi.

Khi thử nhiều bộ tham số rồi chọn bộ có kết quả cao nhất, bạn cũng chọn cả phần thuận lợi do ngẫu nhiên. Các công cụ dưới đây giúp kiểm tra kết quả ngoài mẫu và đánh giá rủi ro quá khớp. | Hàm | Làm gì | | :--- | :--- | | `run_portfolio` | Backtest nhiều mã chung một tài khoản tiền | | `sweep` | Chạy song song nhiều tổ hợp tham số trên một mã, kèm Deflated Sharpe của bộ tốt nhất | | `walk_forward` | Chọn bộ tốt nhất trong mẫu, chấm điểm ngoài mẫu, cuộn theo thời gian | | `monte_carlo` | Lấy mẫu lại lợi suất để ước lượng phân phối tài sản cuối kỳ và sụt giảm | | `deflated_sharpe_ratio` | Xác suất Sharpe thật sự dương sau khi tính tới số lần thử | --- ## Danh mục nhiều mã ```python res = bt.run_portfolio( [ {"symbol": "FPT", "data": df_fpt, "rule_dsl": dsl, "weight": 1.0}, {"symbol": "VNM", "data": df_vnm, "rule_dsl": dsl, "weight": 1.0}, ], profile="vn_hose", broker="ssi", position_size_pct=0.5, ) print(res.summary()["total_return_pct"]) ``` - Mỗi mã khai `symbol`, `data` và một dạng tín hiệu (`signals`, `entries`/`exits`, hoặc `rule_dsl`). `weight` mặc định `1.0`. - Các mã **dùng chung một tài khoản tiền**: tiền bán của mã này dùng được cho mã khác khi đã về tài khoản. - Khối lượng mỗi lệnh bằng quy tắc khối lượng (`position_size_pct`, ...) nhân với tỷ trọng đã chuẩn hoá của mã. - Mọi mã phải có **cùng các ngày giao dịch**. Lệch ngày là lỗi `QUANT_INPUT_DATA`. - `run_portfolio` nhận cùng tham số cấu hình với `run`, kể cả `pyramiding`, lệnh giới hạn/dừng theo mã (`entry_limit`, `entry_stop`, `exit_stop` khai trong từng phần tử `assets`) và `account_guard` — áp dụng cho cả danh mục. Kết quả là `BacktestResult`, không có biểu đồ nến. - Sự kiện quyền (`corporate_actions`) trong danh mục nhiều mã phải khai `symbol` để áp đúng mã; thiếu `symbol` là lỗi `QUANT_INVALID_PARAMETER`. --- ## Tái cân bằng theo tỷ trọng mục tiêu Thay cho việc tự tính khi nào bán mã này mua mã kia, đặt `rebalance` để thư viện tự đưa tỷ trọng về mục tiêu theo lịch bạn chọn: ```python res = bt.run_portfolio( [ {"symbol": "FPT", "data": df_fpt, "weight": 0.5}, {"symbol": "VNM", "data": df_vnm, "weight": 0.5}, ], profile="vn_hose", broker="ssi", rebalance={"period": "quarter", "threshold": 0.05}, ) print(res.summary()["rebalance_count"]) ``` - Không cần khai tín hiệu vào/ra: khi đã có `rebalance`, mỗi mã chỉ cần `symbol`, `data`, `weight` (hoặc `target_weights` đổi theo thời gian — xem dưới). - `period`: `"month"`, `"quarter"` hoặc `"year"` — tái cân bằng vào phiên cuối của mỗi kỳ. `every_bars`: tái cân bằng theo số phiên cố định, dùng thay hoặc cùng với `period`. `threshold`: tự tái cân bằng ngay khi tỷ trọng một mã lệch quá mức này so với mục tiêu, không cần đợi hết kỳ. - `weight` của mỗi mã là tỷ trọng mục tiêu (tổng ≤ 1 thì phần còn lại là tiền mặt; tổng > 1 thì được chuẩn hoá lại). Muốn đổi tỷ trọng theo thời gian (ví dụ chiến lược luân chuyển ngành), khai `target_weights` theo phiên cho từng mã, giá trị `None` nghĩa là giữ tỷ trọng hiện tại. - Mỗi lần tái cân bằng: **bán trước, mua sau**, khối lượng làm tròn theo lô. Tiền bán cổ phiếu về sau T+2 nên lệnh mua thiếu tiền được **mua bù dần** trong tối đa `catchup_bars` phiên kế tiếp (mặc định 5), hoặc mua đủ ngay nếu bạn bật `use_unsettled_proceeds=True`. - `res.summary()["rebalance_count"]` cho biết đã tái cân bằng bao nhiêu lần. - Chỉ áp dụng cho vị thế mua tài sản cơ sở (cổ phiếu, crypto giao ngay); chưa dùng được với hồ sơ phái sinh hay bán khống. --- ## Dò tham số ```python def dsl(lo, hi): rsi = {"ind": "rsi", "params": {"length": 14}} return {"entry_rules": [{"left": rsi, "op": "cross_above", "right": lo}], "exit_rules": [{"left": rsi, "op": "gt", "right": hi}]} tasks = [ {"param_id": f"rsi_{lo}_{hi}", "params": {"lo": lo, "hi": hi}, "rule_dsl": dsl(lo, hi)} for lo in (25, 30, 35) for hi in (65, 70, 75) ] sweep = bt.sweep(df, tasks, symbol="FPT", broker="ssi") print(sweep["best_param_id"], sweep["deflated_sharpe_ratio"]) ``` Mỗi `task` có `param_id`, `params` (ghi lại để đọc kết quả) và một dạng tín hiệu. `stop_loss_pct`, `take_profit_pct` riêng của từng task thì khai trong task. Các tham số cấu hình khác dùng chung cho mọi task. Kết quả: | Khoá | Nội dung | | :--- | :--- | | `num_trials` | Số tổ hợp đã chạy | | `best_param_id`, `best_sharpe` | Tổ hợp có Sharpe cao nhất | | `deflated_sharpe_ratio` | Deflated Sharpe của tổ hợp tốt nhất, tính với số lần thử bằng `num_trials` và độ lệch chuẩn Sharpe giữa các tổ hợp | | `rows` | Mỗi tổ hợp một dòng: `param_id`, `params`, `total_return_pct`, `cagr_pct`, `sharpe_ratio`, `sortino_ratio`, `max_drawdown_pct`, `calmar_ratio`, `profit_factor`, `win_rate_pct`, `total_trades`, `final_equity` | Một lần `sweep` trừ một lượt mỗi tổ hợp vào dòng ngân sách backtest. Số tổ hợp tối đa mỗi lần theo cấp. --- ## Walk-forward ```python wf = bt.walk_forward(df, tasks, train_bars=252, test_bars=63, symbol="FPT", broker="ssi") for fold in wf["folds"]: print(fold["test_start_date"], fold["best_param_id"], fold["out_of_sample_return_pct"]) print(wf["walk_forward_efficiency"], wf["overfit_warning"]) ``` Mỗi cửa sổ (fold) lấy `train_bars` phiên để chọn tổ hợp tốt nhất, rồi chấm tổ hợp đó trên `test_bars` phiên ngay sau. Cửa sổ cuộn lên `test_bars` phiên mỗi lần. | Khoá | Nội dung | | :--- | :--- | | `folds` | Mỗi cửa sổ: ngày bắt đầu/kết thúc của đoạn trong mẫu và ngoài mẫu, `best_param_id`, Sharpe và lợi suất trong mẫu, ngoài mẫu | | `walk_forward_efficiency` | Lợi suất bình quân mỗi phiên ngoài mẫu chia cho trong mẫu, cộng dồn qua các cửa sổ. Càng thấp thì càng có dấu hiệu quá khớp | | `stitched_oos_return_pct` | Lợi suất của các đoạn ngoài mẫu nối lại | | `overfit_warning` | `True` khi `walk_forward_efficiency` dưới 0,5 | --- ## Monte Carlo ```python res = bt.run(df, rule_dsl=dsl(30, 70), symbol="FPT", broker="ssi") mc = bt.monte_carlo(res.daily_returns, num_paths=1000, ruin_drawdown_threshold_pct=25.0, seed=42) ``` Hàm lấy mẫu lại có hoàn lại lợi suất từng phiên (bootstrap, coi các phiên độc lập với nhau) để dựng `num_paths` đường vốn. Kết quả: `terminal_equity_p5`, `terminal_equity_p50`, `terminal_equity_p95`, `max_drawdown_p50_pct`, `max_drawdown_p95_pct`, và `risk_of_ruin_pct`, tức tỷ lệ đường có sụt giảm vượt `ruin_drawdown_threshold_pct`. Cách lấy mẫu này bỏ qua tính chuỗi của lợi suất: những phiên giảm liên tiếp trong thực tế bị xáo trộn. Hãy đọc kết quả như một khoảng tham khảo, không phải xác suất. --- ## Deflated Sharpe Ratio ```python dsr = bt.deflated_sharpe_ratio(res.daily_returns, periods_per_year=252, num_trials=1, trial_sharpe_std=0.0) ``` Theo Bailey và Lopez de Prado (2014): xác suất Sharpe thật sự lớn hơn 0, sau khi tính tới độ lệch, độ nhọn của lợi suất và số lần bạn đã thử. Thử càng nhiều tổ hợp thì ngưỡng càng cao. Giá trị gần 1 là tốt; dưới 0,95 thì chưa đủ bằng chứng là chiến lược tốt hơn may rủi. - `num_trials`: số tổ hợp bạn đã thử, kể cả những tổ hợp đã bỏ đi trước khi gọi hàm. Khai thiếu số lần thử là cách nhanh nhất để tự đánh lừa mình. - `trial_sharpe_std`: độ lệch chuẩn của Sharpe (đã quy đổi theo năm) giữa các lần thử, ví dụ tính từ cột `sharpe_ratio` trong `rows` của `sweep`. Hàm chỉ trừ hao số lần thử khi có cả hai giá trị. Để `trial_sharpe_std=0` thì `num_trials` không có tác dụng: kết quả là xác suất Sharpe lớn hơn 0 của một lần thử duy nhất. `sweep` tự tính cả hai giá trị này. ```python import statistics # best_returns: lợi suất từng phiên của tổ hợp tốt nhất, lấy từ lần chạy lại bằng bt.run std = statistics.stdev(r["sharpe_ratio"] for r in sweep["rows"]) dsr = bt.deflated_sharpe_ratio(best_returns, num_trials=sweep["num_trials"], trial_sharpe_std=std) ``` --- ## Document: Dữ liệu và tín hiệu > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Thư viện tách phần **sinh tín hiệu** khỏi phần **khớp lệnh**. Bạn quyết định khi nào vào và khi nào thoát; thư viện quyết định lệnh khớp ở giá nào, có khớp được không, và phí bao nhiêu. ## Dữ liệu đầu vào `data` là một `pandas.DataFrame` hoặc danh sách `dict`, mỗi dòng một phiên, xếp từ cũ tới mới. | Cột | Bắt buộc | Ghi chú | | :--- | :--- | :--- | | `time` / `date` / `datetime` | có | Ngày phiên, dạng `YYYY-MM-DD` hoặc kiểu ngày giờ. Nếu ngày nằm ở chỉ mục của DataFrame thì thư viện tự lấy ra | | `open`, `high`, `low`, `close` | có | Giá. Kết quả của `vnstock` (`Market().equity(...).ohlcv(...)`) dùng được ngay | | `volume` | không | Mặc định 0 | | `reference_price` | không | Giá tham chiếu của phiên. Không có thì lấy giá đóng cửa phiên trước để tính biên độ | Thiếu cột ngày là lỗi `QUANT_INPUT_DATA`: thư viện không tự sinh ngày. --- ## Ba cách đưa tín hiệu vào ### 1. Mảng `[-1, 0, 1]` ```python sigs = [0] * len(df) sigs[20], sigs[45] = 1, -1 # vào ở tín hiệu phiên 20, thoát ở tín hiệu phiên 45 res = bt.run(df, sigs, symbol="FPT") ``` `1` là vào vị thế mua, `-1` là thoát. Trên hồ sơ cho phép bán khống (`vn_futures`, `crypto_perp`), `-1` còn mở vị thế bán và `1` đóng nó. ### 2. Cặp `entries` / `exits` ```python ma20 = df["close"].rolling(20).mean() res = bt.run( df, entries=(df["close"] > ma20).tolist(), exits=(df["close"] < ma20).tolist(), symbol="FPT", ) ``` Có thêm `short_entries`, `short_exits` cho hồ sơ cho phép bán khống. `tags` là danh sách nhãn theo phiên; nhãn được chép sang lệnh mở ở phiên đó. Khi đang giữ nhiều lô cùng mã (`pyramiding` > 1), `exit_tags` cho biết tín hiệu thoát ở một phiên chỉ nhắm vào lô mang nhãn nào — xem mục nhiều lô ở trang [Chạy backtest và đọc kết quả](/docs/vnstock_quant/backtest/chay-backtest). Ba cách trên quyết định **khi nào**. Mức giá của lệnh giới hạn, lệnh dừng và mức dừng lỗ đổi theo từng phiên lại là tín hiệu riêng, theo phiên: `entry_limit`, `entry_stop`, `exit_stop`. Chi tiết ở trang [Chạy backtest và đọc kết quả](/docs/vnstock_quant/backtest/chay-backtest). ### 3. Bảng quy tắc `rule_dsl` Bảng quy tắc là một `dict` phẳng, được tính trong lõi Rust với các chỉ báo của `vnstock_quant`. Đây là cách nên dùng khi bạn hay trợ lý AI mô tả chiến lược bằng lời. ```python dsl = { "entry_logic": "all", "entry_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}, {"left": "close", "op": "gt", "right": {"ind": "sma", "params": {"length": 200}}}, ], "exit_logic": "any", "exit_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}, {"left": {"ind": "macd", "output": "MACDh"}, "op": "cross_below", "right": 0}, ], } res = bt.run(df, rule_dsl=dsl, symbol="FPT") ``` **Toán hạng** (`left`, `right`): | Dạng | Ví dụ | Ý nghĩa | | :--- | :--- | :--- | | Số | `30` | Hằng số, theo đúng đơn vị dữ liệu bạn đưa vào (nghìn đồng nếu dữ liệu từ `vnstock`) | | Tên cột | `"close"`, `"volume"` | Một cột của dữ liệu, hoặc cột bạn thêm qua `feature_columns` | | Cột lùi phiên | `{"col": "close", "shift": 1}` | Giá trị của cột ở `shift` phiên trước. `shift` không nhận số âm | | Chỉ báo | `{"ind": "sma", "params": {"length": 50}}` | Một chỉ báo trong `bt.list_indicators()` | | Chỉ báo nhiều cột | `{"ind": "bbands", "params": {"length": 20}, "output": "BBU"}` | Chọn một cột đầu ra theo tên hoặc tiền tố | | Chỉ báo trên cột khác | `{"ind": "sma", "params": {"length": 20}, "source": "volume"}` | Tính chỉ báo trên `volume` thay cho `close` | Chỉ báo cũng nhận `shift`, ví dụ `{"ind": "rsi", "params": {"length": 14}, "shift": 1}`. **Phép so sánh** (`op`): `gt`, `gte`, `lt`, `lte`, `eq`, `cross_above`, `cross_below`. `cross_above` đúng ở phiên `left` vượt lên trên `right`, tức phiên trước `left <= right` và phiên này `left > right`. **Cách gộp điều kiện:** | Khoá | Mặc định | Giá trị | | :--- | :--- | :--- | | `entry_logic`, `short_entry_logic` | `"all"` | `"all"`, `"any"`, hoặc `{"vote_at_least": k}` (ít nhất `k` điều kiện đúng) | | `exit_logic`, `short_exit_logic` | `"any"` | Như trên | Bảng quy tắc cần ít nhất một điều kiện vào lệnh. `short_entry_rules`, `short_exit_rules` chỉ dùng trên hồ sơ cho phép bán khống. Trong giai đoạn chỉ báo chưa đủ dữ liệu khởi động, điều kiện được tính là sai. **Xem trước tín hiệu** mà không chạy backtest: ```python sig = bt.eval_rule_dsl(dsl, df) print(sum(sig["entries"]), sum(sig["exits"])) ``` ### Danh sách chỉ báo `bt.list_indicators()` trả 56 chỉ báo, mỗi mục có `name`, `group`, `inputs`, `params` (tên, kiểu, mặc định), `title` và `access`: - `access: "bt_basic"`: dùng được ở mọi cấp, gồm 10 chỉ báo `sma`, `ema`, `rsi`, `macd`, `stoch`, `bbands`, `atr`, `obv`, `vwap`, `pivots`; - `access: "bt"`: cần cấp Bronze trở lên. Bảng quy tắc dùng một chỉ báo chưa mở cho cấp của bạn thì bị từ chối (`QUANT_TIER_REQUIRED`) trước khi chạy, không bị trừ lượt. | Nhóm | Chỉ báo | | :--- | :--- | | Xu hướng | `sma`, `ema`, `wma`, `hma`, `smma`, `alma`, `vwma`, `adx`, `psar`, `supertrend`, `dm`, `linreg`, `aroon` | | Động lượng | `rsi`, `stoch`, `stochrsi`, `mom`, `roc`, `ao`, `cci`, `willr`, `tsi`, `cmo`, `uo`, `fisher`, `cg`, `kst`, `macd` | | Biến động | `bbands`, `kc`, `atr`, `stdev`, `donchian`, `massi`, `ui`, `squeeze`, `squeeze_pro`, `true_range` | | Khối lượng | `obv`, `cmf`, `ad`, `vwap`, `pvo`, `efi`, `eom`, `nvi`, `mfi` | | Thống kê | `pivots`, `mad`, `variance`, `hl2`, `hlc3`, `ohlc4`, `midprice`, `decreasing`, `increasing` | Hai chỉ báo của `vnstock_quant` không dùng được trong bảng quy tắc: - `ichimoku` dịch đường mây về phía trước, nên giá trị tại phiên `t` đọc dữ liệu sau `t`; - `vp` không trả một giá trị cho mỗi phiên. Gọi chúng thì báo `QUANT_CAUSALITY_VIOLATION`. --- ## Kiểm tra thiên lệch nhìn trước tương lai Một tín hiệu tại phiên `t` chỉ được dùng dữ liệu tới hết phiên `t`. Cách kiểm của thư viện: tính tín hiệu trên toàn bộ dữ liệu, rồi tính lại trên dữ liệu đã cắt ở 5 điểm (50%, 62%, 75%, 87%, 95% số phiên). Nếu tín hiệu ở một phiên trước điểm cắt thay đổi, hàm tín hiệu đã đọc dữ liệu tương lai. **Hàm tín hiệu Python của bạn:** ```python def signal_fn(d): up_tomorrow = d["close"].shift(-1) > d["close"] # đọc giá ngày mai return up_tomorrow.astype(int).where(up_tomorrow, -1).tolist() report = bt.check_causality(signal_fn, df) print(report["passed"], report["mismatch_bars"]) ``` `signal_fn(data)` trả mảng `[-1, 0, 1]`, tuple `(entries, exits)` hoặc `dict`. Kết quả gồm `passed`, `mismatch_bars` (vị trí phiên bị đổi tín hiệu), `cuts` và `message`. Ví dụ trên báo không đạt. Lỗi hay gặp: - `shift(-1)`; - cửa sổ trượt đặt giữa (`center=True`); - chuẩn hoá trên toàn mẫu (trừ trung bình, chia độ lệch chuẩn của cả chuỗi). **Bảng quy tắc:** ```python report = bt.check_rule_dsl_causality(dsl, df) ``` Mặc định `execution="vn_realistic"`: tín hiệu tính ở giá đóng cửa phiên `t` khớp ở giá mở cửa phiên `t+1`. Đổi sang khớp ở giá đóng cửa của chính phiên `t` (`execution_timing="same_close"`) là giả định lạc quan; chỉ dùng khi bạn biết rõ mình đang mô phỏng điều gì. --- ## Document: Chạy thử chiến lược > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.backtest` giúp bạn kiểm thử một ý tưởng nghiên cứu trên dữ liệu giá bạn tự truy xuất, ví dụ bằng `vnstock`. Bạn mô tả khi nào vào và khi nào thoát vị thế. Thư viện mô phỏng lại quá trình khớp lệnh từng phiên rồi trả về lịch sử lệnh, đường vốn và các thước đo rủi ro. Các phép tính backtest chạy trên máy của bạn. Bảng quy tắc hỗ trợ 56 chỉ báo được liệt kê ở trang [Dữ liệu và tín hiệu](/docs/vnstock_quant/backtest/du-lieu-va-tin-hieu); báo cáo kết quả dùng các thước đo rủi ro của `vnstock_quant`. Thư viện khác các công cụ backtest phổ biến ở bốn điểm: - **Không phải viết vòng lặp hay lớp chiến lược.** Bạn đưa vào một mảng tín hiệu `[-1, 0, 1]`, một cặp `entries`/`exits`, hoặc một bảng quy tắc dạng `dict` (`rule_dsl`) dùng các chỉ báo của `vnstock_quant`: 10 chỉ báo ở bản Cộng đồng, 56 chỉ báo từ cấp Bronze. Bảng quy tắc cũng có thể được trợ lý AI tạo từ mô tả bằng lời để bạn kiểm tra và điều chỉnh. - **Luật thị trường Việt Nam là mặc định:** - lô 100 cổ phiếu; - bước giá theo từng sàn; - biên độ ±7%, ±10%, ±15%; - phiên khóa sàn không bán được; - cổ phiếu mua ngày T bán được từ phiên chiều T+2; - thuế bán 0,1% tính riêng, ngoài phí giao dịch. - **Kiểm tra thiên lệch nhìn trước tương lai (lookahead bias).** Thư viện chạy lại tín hiệu trên dữ liệu đã cắt bớt phần sau. Phiên nào có tín hiệu đổi khi bỏ dữ liệu tương lai thì được báo ra. - **Đối chứng được với thư viện khác.** Các chế độ `backtesting_py`, `backtrader`, `vectorbt` và `zipline` cho phép so sánh theo cùng giả định khớp lệnh. Kết quả của 11 kịch bản kiểm thử và điều kiện đối chứng được ghi tại trang [Chế độ khớp lệnh](/docs/vnstock_quant/backtest/che-do-khop-lenh). Mô-đun còn có: - **Nhiều lô trong một vị thế (pyramiding)** và **tái cân bằng danh mục theo tỷ trọng mục tiêu**, cả hai đều tính đúng chu kỳ thanh toán T+2.5 cho từng lô. - **Lệnh giới hạn, lệnh dừng theo từng phiên**, nhiều mức chốt lời từng phần, dừng lỗ về hoà vốn, cắt lỗ đuổi có mức kích hoạt. - **Quyền mua cổ phiếu** (`rights_issue`) bên cạnh cổ tức tiền và cổ phiếu thưởng; giá tham chiếu ngày giao dịch không hưởng quyền tính đúng công thức của sở, không bị hiểu nhầm thành phiên khóa sàn. - **Chặn rủi ro cấp tài khoản**: ngừng mở vị thế mới khi sụt giảm hoặc chuỗi lệnh lỗ vượt ngưỡng bạn đặt. Chi tiết từng tính năng ở các trang tương ứng; mốc thời gian ở [Lịch sử phiên bản](/docs/vnstock_quant/lich-su-phien-ban).

Kết quả backtest chỉ phản ánh dữ liệu và giả định bạn đã dùng: biểu phí, cách khớp lệnh, cách tính khối lượng. Nó không phải lợi nhuận kỳ vọng, và thư viện không đưa ra khuyến nghị đầu tư.

--- ## Bắt đầu trong ba bước **1. Cài đặt.** `vnstock_quant` từ bản 0.5.0 đã có sẵn mô-đun này; xem [Cài đặt và thiết lập](/docs/vnstock_quant/bat-dau/cai-dat-va-thiet-lap). ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[vnstock]" ``` **2. Kiểm tra cấp quyền.** Lệnh này không trừ lượt dùng thử: ```python import vnstock_quant as vq print(vq.entitlement()["tier"], vq.entitlement()["backtest"]) ``` **3. Chạy một backtest.** Ví dụ: vào khi RSI(14) cắt lên 30 và giá đóng cửa trên SMA(200); thoát khi RSI(14) vượt 70; cắt lỗ 7%. ```python from vnstock import Market from vnstock_quant import backtest as bt df = Market().equity("FPT").ohlcv(start="2021-01-01", end="2026-09-30") res = bt.run( df, rule_dsl={ "entry_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}, {"left": "close", "op": "gt", "right": {"ind": "sma", "params": {"length": 200}}}, ], "exit_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}], }, symbol="FPT", profile="vn_hose", broker="ssi", stop_loss_pct=0.07, ) print(res.summary()["total_return_pct"], res.summary()["max_drawdown_pct"]) print(res.trades_df()) ``` `vnstock` báo giá cổ phiếu theo nghìn đồng. Thư viện tự nhận ra và quy về đồng trước khi áp bước giá, biên độ. Việc quy đổi này được ghi trong `res.warnings`. --- ## Đọc theo thứ tự này | Trang | Bạn sẽ làm được | | :--- | :--- | | [Dữ liệu và tín hiệu](/docs/vnstock_quant/backtest/du-lieu-va-tin-hieu) | Đưa dữ liệu vào, viết tín hiệu bằng mảng hoặc bảng quy tắc, kiểm tra nhìn trước tương lai | | [Chạy backtest và đọc kết quả](/docs/vnstock_quant/backtest/chay-backtest) | Gọi `run`, chọn cách tính khối lượng và điểm dừng, đọc tear sheet, vẽ biểu đồ | | [Luật thị trường, phí và sự kiện](/docs/vnstock_quant/backtest/luat-thi-truong-va-phi) | Chọn hồ sơ thị trường, biểu phí, đơn vị giá; khai cổ tức và kịch bản sốc | | [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/backtest/che-do-khop-lenh) | Hiểu khác biệt giữa các thư viện backtest, so kết quả với thư viện bạn đang dùng | | [Danh mục, tối ưu và chống quá khớp](/docs/vnstock_quant/backtest/danh-muc-va-toi-uu) | Chạy nhiều mã chung một tài khoản, tái cân bằng theo tỷ trọng, dò tham số, walk-forward, Monte Carlo, Deflated Sharpe | | [Cấp quyền và xử lý lỗi](/docs/vnstock_quant/backtest/cap-quyen-va-xu-ly-loi) | Biết mỗi cấp chạy được bao nhiêu, đọc mã lỗi và cách xử lý | | [Lịch sử phiên bản](/docs/vnstock_quant/lich-su-phien-ban) | Các mốc cập nhật của `vnstock_quant`, gồm phần backtest | --- ## Thư viện không làm gì - **Không truy xuất dữ liệu.** Bạn tự lấy dữ liệu giá (ví dụ bằng `vnstock`) rồi đưa vào. Thư viện chỉ tính toán trên dữ liệu đó. - **Không kết nối tài khoản, không gửi lệnh tới bất kỳ đâu.** Mọi lệnh trong backtest là lệnh giả lập trên dữ liệu lịch sử. - **Không mô phỏng giao dịch ký quỹ cổ phiếu (margin)** ở bản này. Phái sinh và bán khống crypto vẫn tính ký quỹ ban đầu như tiền đặt cọc hợp đồng. - **Không kèm kịch bản sự kiện nào của doanh nghiệp thật.** Kịch bản sốc do bạn tự khai và chỉ áp khi bạn truyền vào. - **Không cam kết biểu phí.** Biểu phí của các công ty chứng khoán chỉ để tham khảo, mỗi mục ghi rõ đã xác minh hay chưa và mốc thời gian. Mức phí thực tế của bạn có thể khác. - **Không đưa ra khuyến nghị đầu tư.** Kết quả chạy thử không phải dự báo. --- ## Document: Luật thị trường, phí và sự kiện > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Hồ sơ thị trường `profile` quyết định lô, bước giá, biên độ, chu kỳ thanh toán và thuế bán. `bt.list_profiles()` trả đủ trường của từng hồ sơ. | `profile` | Thị trường | Lô | Biên độ | Thanh toán | Thuế bán | Bán khống | | :--- | :--- | ---: | ---: | :--- | ---: | :--- | | `vn_hose` | Cổ phiếu HOSE | 100 | ±7% | T+2.5 | 0,1% | không | | `vn_hnx` | Cổ phiếu HNX | 100 | ±10% | T+2.5 | 0,1% | không | | `vn_upcom` | Cổ phiếu UPCoM | 100 | ±15% | T+2.5 | 0,1% | không | | `vn_futures` | Hợp đồng tương lai VN30F | 1 hợp đồng, hệ số 100.000 | ±7% | T+0 | 0 | có, ký quỹ ban đầu 17% | | `crypto_spot` | Crypto giao ngay | 0,0001 | không | T+0 | 0 | không | | `crypto_perp` | Crypto hợp đồng vĩnh cửu | 0,001 | không | T+0 | 0 | có, ký quỹ ban đầu 10% | | `global_equity` | Cổ phiếu quốc tế | 1 | không | T+0 | 0 | có | | `forex` | Ngoại hối | 0,01 lot, hệ số 100.000 | không | T+0 | 0 | có, ký quỹ 2% | | `frictionless` | Không luật thị trường, dùng để đối chứng | 1 | không | T+0 | 0 | không | Tên ngắn cũng được nhận: `hose`, `hnx`, `upcom`, `vn30f`, `futures`, `crypto`, `perp`, `us_equity`, `fx`. Sửa một trường mà không tạo hồ sơ mới: ```python res = bt.run(df, sigs, profile="vn_hose", profile_overrides={"settlement": "historical_vn"}) ``` --- ## Luật cổ phiếu Việt Nam ### Chu kỳ thanh toán - **`t2_5` (mặc định):** cổ phiếu mua ngày T bán được từ **phiên chiều T+2**. Lệnh bán ở phiên sáng T+2 chưa khớp; lệnh ở phiên đóng cửa T+2 thì khớp. Tiền bán về tài khoản theo cùng chu kỳ. - **`historical_vn`:** theo ngày giao dịch. Lệnh mua trước 25/08/2022 bán được từ mở cửa T+3, lệnh mua từ 25/08/2022 bán được từ phiên chiều T+2 (mốc theo quy định của Tổng công ty Lưu ký và Bù trừ chứng khoán Việt Nam). Dùng khi backtest trải dài qua năm 2022. - Các giá trị khác: `t0`, `t1`, `t2`, `t3`. Lệnh thoát rơi vào lúc cổ phiếu chưa về được giữ lại, khớp ở phiên đầu tiên bán được, và ghi `exit_reason` có đuôi `_delayed_by_settlement`. Mặc định, tiền bán chưa về không được dùng để mua. Muốn mô phỏng dịch vụ ứng trước tiền bán thì đặt `use_unsettled_proceeds=True`. ### Bước giá | Sàn | Giá dưới 10.000 đ | 10.000 đ đến dưới 50.000 đ | Từ 50.000 đ | | :--- | ---: | ---: | ---: | | HOSE | 10 đ | 50 đ | 100 đ | | HNX, UPCoM | 100 đ | 100 đ | 100 đ | Giá khớp được làm tròn theo bước giá về phía bất lợi cho bạn: lệnh mua làm tròn lên, lệnh bán làm tròn xuống. ### Biên độ, khóa trần và khóa sàn - Giá trần, giá sàn tính từ `reference_price` của phiên. Không có cột này thì dùng giá đóng cửa phiên trước. Kết quả làm tròn vào trong biên độ theo bước giá. - Giá khớp không vượt ra ngoài biên độ. - **Khóa sàn:** phiên có giá mở cửa, giá cao nhất và giá đóng cửa đều bằng giá sàn. Lệnh bán ở phiên này không khớp (`LIMIT_DOWN_LOCKED`) và được giữ lại tới phiên đầu tiên bán được, kể cả lệnh cắt lỗ. - **Khóa trần:** tương tự ở giá trần. Lệnh mua vào ở phiên này bị bỏ (`LIMIT_UP_LOCKED`). Khóa sàn là điểm kết quả backtest hay lệch nhất so với thực tế. Một lệnh cắt lỗ 7% gặp ba phiên khóa sàn liên tiếp có thể khớp ở mức lỗ hơn 20%. Thư viện backtest không có luật biên độ thì cho lệnh cắt lỗ đó khớp ngay ở phiên chạm mức đã đặt. Phiên giao dịch không hưởng quyền (GDKHQ) trên giá gốc không bị hiểu nhầm là khóa sàn: giá tham chiếu của phiên đó tính thẳng từ `corporate_actions` theo đúng công thức của sở (`(giá đóng cửa phiên trước − cổ tức tiền + giá phát hành × tỷ lệ quyền) / (1 + tỷ lệ cổ phiếu thưởng + tỷ lệ quyền mua)`), không lấy nguyên giá đóng cửa phiên trước. Nếu một phiên vẫn giao dịch ra ngoài biên độ tính từ giá tham chiếu (ví dụ bạn quên khai sự kiện quyền, hoặc dữ liệu có lỗi), thư viện bỏ áp biên độ và khóa trần/sàn cho đúng phiên đó, kèm cảnh báo trong `res.warnings` nêu rõ các phiên liên quan; `detect_limit_events` cũng bỏ qua các phiên này. **Liệt kê các phiên chạm trần, chạm sàn** trên dữ liệu của bạn: ```python events = bt.detect_limit_events(df, profile="vn_hose") # [{'bar_index': 18, 'date': '2021-01-28', 'reference_price': 24420.0, # 'limit_price': 22750.0, 'kind': 'closed_at_floor', 'volume': 5092400.0}, ...] ``` `kind` gồm `floor_lock` (cả phiên ở giá sàn), `closed_at_floor`, `ceiling_lock` (cả phiên ở giá trần), `closed_at_ceiling`. Giá trả về tính bằng đồng. ### Thuế bán Thuế bán 0,1% trên giá trị bán nằm trong hồ sơ cổ phiếu Việt Nam (`sell_tax_rate`), tính riêng với phí giao dịch. Đổi `fee` hay `broker` không làm mất thuế bán. Tổng thuế ghi ở `total_tax`, từng lệnh ở `exit_tax`. --- ## Đơn vị giá `vnstock` báo giá cổ phiếu theo **nghìn đồng**: `63.1` nghĩa là 63.100 đ. Bước giá và biên độ lại tính bằng đồng. | `price_unit` | Khi nào dùng | | :--- | :--- | | `"auto"` (mặc định) | Với hồ sơ cổ phiếu Việt Nam, nếu trung vị giá đóng cửa dưới 1.000 thì nhân 1.000. Việc quy đổi được ghi trong `res.warnings` | | `"thousand_vnd"` | Dữ liệu chắc chắn theo nghìn đồng | | `"vnd"` | Dữ liệu đã tính bằng đồng, không quy đổi | Tín hiệu luôn tính trên giá bạn đưa vào. Một điều kiện như `close > 50` trong `rule_dsl` vẫn hiểu là 50 nghìn đồng khi dữ liệu theo nghìn đồng. Giá trong `trades`, `equity_curve` và tear sheet tính bằng đồng. --- ## Phí giao dịch Ba cách khai phí: ```python bt.run(df, sigs, fee=0.0015) # 0,15% mỗi chiều bt.run(df, sigs, fee=(0.0015, 0.0020)) # mua 0,15%, bán 0,20% bt.run(df, sigs, broker="vps") # biểu phí tham khảo ``` `bt.list_brokers()` trả các biểu phí tham khảo. Mỗi mục có `id`, `name`, `buy_fee_rate`, `sell_fee_rate`, `min_fee`, `verified` và `as_of`: | `id` | Phí mỗi chiều | `verified` | `as_of` | | :--- | ---: | :--- | :--- | | `vps` | 0,13% | có | 2026 | | `ssi` | 0,15% | có | 2026 | | `vnd` | 0,15% | có | 2026 | | `tcbs` | 0,03% | chưa | 2025 | | `vci`, `hsc`, `mbs`, `kis`, `mas`, `vpbanks`, `fpts` | 0,15% | chưa | 2026 | | `dnse` | 0,03% | chưa | 2026 | | `binance_spot` | 0,10% | chưa | 2026 | | `binance_perp` | 0,05% | chưa | 2026 | | `zero` | 0 | có | — | `verified: false` nghĩa là chưa đối chiếu được với trang biểu phí hoặc hợp đồng chính thức. Mức phí thực tế còn phụ thuộc gói dịch vụ, kênh và chương trình ưu đãi của bạn. Khi biết mức của mình, khai thẳng bằng `fee`. Phái sinh VN30F thường tính phí theo hợp đồng, không theo % giá trị. Thêm `fee_per_contract` (mặc định 0) để cộng một mức phí cố định mỗi đơn vị, mỗi chiều, vào phí theo tỷ lệ đã khai: ```python bt.run(df, sigs, profile="vn_futures", fee=0.0, fee_per_contract=2700) ``` --- ## Sự kiện quyền Dữ liệu `vnstock` mặc định là **giá đã điều chỉnh**: cổ tức và cổ phiếu thưởng đã được phản ánh vào giá, nên không khai thêm sự kiện. Thư viện từ chối khai `corporate_actions` khi `prices_adjusted=True`, để một sự kiện không bị tính hai lần. Với giá gốc (chưa điều chỉnh), đặt `prices_adjusted=False` và khai sự kiện: ```python res = bt.run( raw_df, sigs, prices_adjusted=False, corporate_actions=[ {"kind": "cash_dividend", "ex_date": "2026-06-10", "payment_date": "2026-07-01", "amount_per_share": 2000, "tax_rate": 0.05}, {"kind": "stock_dividend", "ex_date": "2026-08-05", "listing_date": "2026-09-02", "ratio": 0.15}, {"kind": "rights_issue", "ex_date": "2026-10-20", "ratio": 0.2, "subscription_price": 10000, "listing_date": "2026-11-15"}, ], ) ``` - **Cổ tức tiền:** người nắm giữ trước ngày giao dịch không hưởng quyền được nhận. Tiền về tài khoản ở `payment_date`, sau khi trừ thuế thu nhập cá nhân `tax_rate` (mặc định 5%). Thiếu `payment_date` thì ghi nhận ở `ex_date` và có cảnh báo. `amount_per_share` tính bằng đồng, cùng đơn vị với giá dữ liệu sau khi quy đổi. - **Cổ phiếu thưởng, cổ tức bằng cổ phiếu:** `ratio=0.15` là thêm 15%. Cổ phiếu mới bán được từ `listing_date`. Thiếu ngày này thì dùng `ex_date` và có cảnh báo. Phần lẻ dưới một cổ phiếu bị bỏ; với vị thế nhiều lô (`pyramiding` > 1), cổ phiếu thưởng tính trên tổng số đang giữ rồi chia lại cho từng lô. - **Quyền mua cổ phiếu (`rights_issue`):** `ratio=0.2` nghĩa là được mua thêm 20% số đang giữ, ở giá `subscription_price` (đồng). Mặc định (`exercise=True`) thư viện thực hiện quyền ngay ngày GDKHQ, trong phạm vi tiền mặt đang có; số cổ phiếu mua thêm thành một lô riêng, giá vốn bằng giá phát hành, bán được từ `listing_date`. Tiền mặt không đủ mua hết số quyền được hưởng thì mua được bấy nhiêu, ghi `RIGHTS_CASH_LIMITED` vào `rejected_orders`. Đặt `exercise=False` để coi như bỏ quyền: phần giá trị bị pha loãng mất theo, không mô phỏng việc bán lại quyền. - Mức dừng lỗ, chốt lời và đỉnh của cắt lỗ đuổi của các lô đang giữ **dời theo đúng tỷ lệ pha loãng** của từng sự kiện, nên khoảng giảm kỹ thuật ngày GDKHQ không bị tính là lỗ hay kích hoạt cắt lỗ oan. - Mỗi sự kiện có thể thêm `symbol`. Backtest một mã thì không cần; chạy danh mục nhiều mã (`run_portfolio`) thì **bắt buộc** khai `symbol` để sự kiện áp đúng mã. --- ## Kịch bản sốc tự khai Thư viện không kèm kịch bản nào. Bạn tự khai một khoảng ngày để thử chiến lược trong điều kiện thanh khoản xấu hơn dữ liệu cho thấy: ```python res = bt.run( df, sigs, symbol="AAA", shock_events=[{ "event_id": "stress_test_1", "symbol": "AAA", "start_date": "2026-07-01", "end_date": "2026-07-10", "enforce_floor_lock": True, # phiên mở và đóng ở giá sàn được tính là khóa sàn "extra_slippage_pct": 0.01, # trượt giá thêm 1% cho mọi lệnh khớp trong khoảng này "headline": "Giả định thanh khoản cạn", }], ) ``` Bắt buộc: `event_id`, `symbol`, `start_date`, `end_date`. Kịch bản chỉ áp khi bạn truyền vào, và chỉ áp cho đúng `symbol`. Đây là giả định của bạn, không phải dữ liệu thị trường. --- ## Document: Cài đặt và thiết lập `vnstock_quant` có gói cài đặt dựng sẵn cho Python 3.10 trở lên. Bạn cài bằng `pip`; không cần tự biên dịch phần lõi Rust. --- ## Cài đặt gói Cài trong cùng môi trường Python với `vnstock`: `~/.venv` trên macOS và Linux, `$HOME\.venv` trên Windows. Trên Google Colab hoặc GitHub Codespaces, dùng môi trường đang chạy. Xem [Cài đặt vnstock](/docs/vnstock/cai-dat#cai-vao-dau) nếu bạn cần tạo môi trường hoặc vẫn còn bản 4.x. Các lệnh dưới đây giả định môi trường đã được kích hoạt. ```bash # Cài đặt thư viện tính toán vnstock_quant pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant # Hoặc cài đặt kèm luôn thư viện vnstock để tự động tải dữ liệu trực tiếp pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant[vnstock]" ```

Thêm --extra-index-url https://vnstocks.com/api/packages để pip tìm được thư viện trong kho phát hành của Vnstock. Nếu máy đã có vnstock thế hệ 5 và bạn đã chạy vnstock register, bạn cũng có thể cài bằng vnstock install vnstock_quant.

### Yêu cầu môi trường - **Hệ điều hành**: macOS 10.12 trở lên trên chip Intel (x86_64), macOS 11 trở lên trên chip Apple Silicon (arm64); Linux x86_64 và aarch64 dùng glibc 2.17 trở lên (chuẩn manylinux2014). - **Phiên bản Python**: Python 3.10 trở lên (một bản dựng dùng chung cho mọi phiên bản từ 3.10). - **Thư viện nền tảng**: `numpy>=1.24`, `pandas>=2.0` (tự động cài đặt khi chạy pip). --- ## Kiểm tra trạng thái cấp quyền và bản phát hành Sau khi cài, gọi `vq.entitlement()` để xem cấp quyền và nhóm hàm bạn có thể dùng. Việc kiểm tra này chạy trên máy và không trừ lượt tính: ```python import vnstock_quant as vq # Kiểm tra cấp quyền sử dụng, tính năng mở khoá và số lượt dùng thử còn lại status = vq.entitlement() print(status) ``` Ví dụ kết quả với tài khoản gói Diamond: ```python {'tier': 'diamond', 'active': True, 'features': ['ta_basic', 'ta', 'fa_basic', 'fa', 'fa_advanced', 'risk', 'portfolio', 'bt_basic', 'bt', 'bt_portfolio', 'bt_optimize'], 'policy_version': 'quant_entitlement_v3', 'trial': None, 'backtest': {'budget': 'vnstock_bt', 'trial': None, 'quota': {'portfolio_symbols': 400, 'sweep_tasks': 50000, 'monte_carlo_paths': 100000}}, 'error': None, 'release': {'package': 'vnstock_quant', 'version': '0.5.0', 'pre_release': False, 'build_date': '2026-10-27', 'expires_at': '2027-10-27T15:19:01+00:00', 'days_left': 365, 'policy_issued_at': '2026-10-26T08:23:25.699+00:00', 'offline_deadline': '2027-10-31T00:00:00+00:00', 'warning': None, 'error': None}} ``` Kết quả gồm: - `tier`: Cấp quyền sử dụng hiện tại nhận diện được trên máy (`guest` khi chưa đăng nhập, `free`, `bronze`, `silver`, `golden`, `diamond`). Là `None` khi không kiểm tra được quyền; lý do nằm ở `error`. - `active`: `True` khi quyền sử dụng đang còn hiệu lực. - `features`: Danh sách các nhóm tính năng đang được phép sử dụng (`ta_basic`, `ta`, `fa_basic`, `fa`, `fa_advanced`, `risk`, `portfolio`; mô hình định giá dùng chung quyền `portfolio`; `bt_basic`, `bt`, `bt_portfolio`, `bt_optimize` của mô-đun backtest). Ý nghĩa từng nhóm và cấp mở: [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc). - `policy_version`: Phiên bản bộ quy tắc cấp quyền mà bản cài này áp dụng. - `trial`: Với bản Cộng đồng, từ điển này cho biết tổng số lượt dùng thử trong ngày (`daily`), số lượt đã dùng (`used`), số lượt còn lại (`remaining`), số mã tối đa mỗi lần tải (`max_symbols`) và thời điểm làm mới (`resets_at`). Với gói quyền sử dụng không giới hạn lượt, giá trị là `None`. - `backtest`: Phần riêng của mô-đun backtest: `trial` (lượt backtest trong ngày, tách khỏi `trial` ở trên), `quota` (quy mô một lần chạy theo cấp) và `budget` (tên dòng ngân sách trên máy chủ). Xem [Cấp quyền và xử lý lỗi](/docs/vnstock_quant/backtest/cap-quyen-va-xu-ly-loi). - `error`: `None` khi kiểm tra quyền thành công; nếu không, là bộ `(code, kind, message, action)` mô tả lỗi. - `release`: Thông tin hạn dùng của bản đang cài: - `package`, `version`: tên gói và phiên bản. - `pre_release`: có phải bản thử không. - `build_date`, `expires_at`, `days_left`: ngày dựng, ngày hết hạn và số ngày còn lại. - `policy_issued_at`: thời điểm phát hành của chính sách vòng đời mà máy chủ gửi về và đang áp dụng; `None` khi chưa đọc được chính sách nào và hạn dùng được tính theo ngày dựng. - `offline_deadline`: sau thời điểm này, bản cài không đọc được chính sách nào từ máy chủ sẽ ngừng chạy. - `warning`: thông báo về hạn dùng khi gần tới `expires_at`, `None` khi chưa tới lúc thông báo. - `error`: lý do bản phát hành không được chạy (đã hết hạn hoặc đã bị tắt), `None` khi bình thường. Nếu cần biết thông tin bản dựng của phần lõi, gọi: ```python # Xem thông tin biên dịch lõi Rust info = vq.build_info() print(info) # {'version': '0.5.0', 'test_entitlement': False, 'ta_methods': 58, 'fa_ratios': 100, # 'fa_registry': 'fa_v1', 'risk_measures': 33, 'portfolio_functions': 38, 'micro_functions': 5, # 'backtest_tools': 10} ``` --- ## Đọc tiếp - [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc) — Nhóm tính năng nào mở ở cấp nào, lượt dùng thử và quy mô mỗi lần chạy. - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/bat-dau/quy-uoc-du-lieu-va-loi) — Dạng dữ liệu đầu vào, cây ngoại lệ, mã lỗi và quy ước phương pháp luận. - [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/tich-hop/tai-du-lieu-bang-vnstock) — Điểm vào tải dữ liệu cho từng nhóm hàm. - [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) — Bắt đầu tính toán với 58 chỉ báo kỹ thuật. --- ## Document: Quy ước dữ liệu và lỗi Trang này gom những điều đúng với mọi nhóm hàm của `vnstock_quant`: dữ liệu đầu vào trông như thế nào, lỗi được báo ra sao và các quy ước tính toán mà kết quả tuân theo. Từng trang nhóm hàm chỉ nói phần riêng của nhóm đó. --- ## Dữ liệu đầu vào Thư viện nhận dữ liệu dạng `pandas` và trả kết quả căn theo chỉ mục bạn đưa vào. Lớp Python chỉ đổi cột sang mảng số rồi dựng lại bảng có nhãn; mọi phép tính và kiểm tra đầu vào nằm trong lõi Rust, nên thiếu cột hay lệch độ dài được báo bằng `InputDataError` kèm tên cột thiếu. | Nhóm hàm | Dạng dữ liệu | Ghi chú | | :--- | :--- | :--- | | `ta`, `backtest`, `micro.cvd`, `micro.realized` | Bảng nến: cột `open`, `high`, `low`, `close`, `volume` viết thường, chỉ mục thời gian `DatetimeIndex` hoặc cột `time` | `ta` chỉ cần các cột mà chỉ báo dùng; `backtest` nhận thêm `price_unit` để nhận ra bảng tính bằng nghìn đồng hay đồng | | `risk`, `portfolio` | `pandas.Series` hoặc `DataFrame` **lợi suất giản đơn** từng kỳ, chỉ mục `DatetimeIndex` | Tính từ giá đóng cửa đã điều chỉnh bằng `risk.returns(prices)`; hai chuỗi được căn theo ngày giao dịch chung | | `fa` | Báo cáo tài chính dạng long: cột `period`, `id`, `value` với mã chỉ tiêu của `vnstock`, gói trong `fa.Dataset` | Chỉ số dùng mẫu số bình quân cần ít nhất hai kỳ | | `prices` | Bảng phiên của `trade_history()` (giá tham chiếu, trần, sàn, OHLC, khối lượng) và bảng sự kiện của `events()` | Đơn vị đồng; `unit="auto"` nhận ra bảng nghìn đồng của `ohlcv()` | | `micro.bars`, `micro.classify` | Bảng khớp lệnh: `time`, `price`, `volume`, cột bên chủ động nếu nguồn có (`match_type`) | Nguồn không có bên chủ động thì suy bằng tick rule | Kết quả là `DataFrame` hoặc `Series` cùng chỉ mục với đầu vào. Siêu dữ liệu đi kèm nằm trong `attrs` (ví dụ bảng hệ số của `prices.adjust` ở `attrs["factors"]`). Thư viện không tự đổi đơn vị giá trừ khi hàm có tham số `unit` hoặc `price_unit`; hãy dùng một đơn vị nhất quán trong cả phiên làm việc. --- ## Hệ thống phân cấp ngoại lệ Các lỗi của thư viện kế thừa từ `VnstockQuantError`. Mã lỗi giúp bạn phân biệt sai tham số, dữ liệu đầu vào, quyền sử dụng và những trường hợp khác: ```text 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 thư viện phụ trợ, ví dụ chưa cài vnstock (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 ``` Mọi lỗi đều có các thuộc tính `code` (mã lỗi), `kind` (nhóm lỗi), `message` (nội dung tiếng Việt), `retryable` (có nên thử lại không) và `action` (việc nên làm tiếp, có thể là `None`). `str(e)` có dạng `[code] message (action)`. ### Ví dụ bắt lỗi theo nghiệp vụ ```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}") ``` ### Tắt cảnh báo hệ thống Các lưu ý không làm dừng chương trình được phát qua lớp cảnh báo `VnstockQuantWarning` (ví dụ: cảnh báo tự động bỏ qua các chỉ số nâng cao khi chạy tính toán hàng loạt toàn bộ chỉ số ở cấp Cộng đồng). Bạn có thể tắt cảnh báo này nếu muốn: ```python 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 chung Trước khi so sánh kết quả giữa các hàm, hãy chú ý các quy ước sau: | Quy ước | Chi tiết áp dụng | | :--- | :--- | | **Tỷ lệ và phân số** | Mọi tỷ lệ phần trăm được biểu diễn dưới dạng **phân số thập phân** (ví dụ `0.18` đại diện cho 18%). Kết quả tính toán trả về cũng tuân thủ định dạng phân số. | | **Giá và chuỗi lợi suất** | Chuỗi lợi suất giản đơn được tính toán dựa trên **giá đóng cửa đã điều chỉnh** (adjusted close). Việc dùng giá chưa điều chỉnh sẽ tạo ra các phiên thua lỗ giả tạo vào ngày giao dịch không hưởng quyền. | | **Số phiên giao dịch một năm** | Mặc định sử dụng **252 phiên/năm** theo chuẩn quốc tế đối với dữ liệu ngày (52 tuần, 12 tháng). Dữ liệu thực tế tại 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 rủi ro nếu muốn quy đổi chuẩn xác theo năm dựa trên lịch giao dịch Việt Nam. | | **Lãi suất phi rủi ro (`rf`)** | Là lãi suất năm, mặc định là `0`. Bạn có thể chỉ định lãi suất trái phiếu Chính phủ kỳ hạn 1 năm hoặc lãi suất tiết kiệm 12 tháng của nhóm ngân hàng Big 4. | | **Chỉ mục thời gian (`time`)** | Căn cứ vào `DatetimeIndex` của pandas. Khi tính toán tương quan hoặc đo lường so với thị trường (Benchmark), hai chuỗi dữ liệu được căn chỉnh theo **ngày giao dịch chung**, không căn chỉnh theo số thứ tự hàng. | | **Xử lý dữ liệu khuyết thiếu** | Không bao giờ âm thầm điền số 0 vào ô trống. Báo cáo tài chính thiếu chỉ tiêu sẽ được đánh dấu rõ ràng qua cột `reason`. Các hàm danh mục sẽ từ chối tính toán nếu chuỗi lợi suất chứa giá trị NaN. | | **Độ đo rủi ro sụt giảm (VaR/CVaR)** | Trả về **giá trị dương** đại diện cho mức lỗ tiềm tàng tại ngưỡng tin cậy xác định. | | **Ràng buộc bán khống (Short-selling)** | Không cho phép vị thế bán khống trong các bài toán tối ưu danh mục, phù hợp với quy định của thị trường chứng khoán cơ sở Việt Nam. | --- ## Đọc tiếp - [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc) — Khi nào gặp `TierRequiredError` và `QuotaExceededError`. - [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh) — Vì sao chuỗi lợi suất cần giá đã điều chỉnh. - [Đối chiếu kết quả và tốc độ](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) — Các mốc chuẩn mà kết quả được so với. --- ## Document: Quyền dùng và hạn mức `vnstock_quant` cấp quyền theo **nhóm tính năng**, không theo từng hàm. Bộ quy tắc do máy chủ Vnstock quyết định và gửi về máy bạn; thư viện chỉ thi hành. Trang này là bảng tra duy nhất về quyền và hạn mức; các trang nhóm hàm chỉ ghi một dòng "cần cấp nào" và trỏ về đây.

Mọi phép tính của vnstock_quant chạy trên máy bạn và không trừ vào hạn mức chung của tài khoản Vnstock. Chỉ việc tải dữ liệu qua thư viện vnstock (ví dụ Dataset.load(), from_vnstock()) mới tính vào hạn mức, theo quy tắc của vnstock. Xem mức còn lại trên trang tài khoản.

--- ## Nhóm tính năng theo cấp Cấp được nhận diện trên máy: `guest` khi chưa đăng nhập, `free` với tài khoản Cộng đồng, rồi `bronze`, `silver`, `golden`, `diamond` theo gói quyền sử dụng. Hai cấp đầu có cùng quyền. | Nhóm tính năng | Mã trong `features` | Mở gì | Cộng đồng | Bronze | Silver trở lên | | :--- | :--- | :--- | :---: | :---: | :---: | | Chỉ báo kỹ thuật cơ bản | `ta_basic` | 10 chỉ báo: SMA, EMA, RSI, MACD, Stoch, Bollinger Bands, ATR, OBV, VWAP, Pivots | Có, theo lượt thử | Có | Có | | Chỉ báo kỹ thuật đầy đủ | `ta` | Đủ 58 chỉ báo của `vnstock_quant.ta` | Chưa mở | Chưa mở | Có | | Chỉ số tài chính cơ bản | `fa_basic` | 10 chỉ số: P/E, P/B, EPS, BVPS, ROE, ROA, biên lợi nhuận gộp và ròng, D/E, thanh toán hiện hành | Có, theo lượt thử | Có | Có | | Chỉ số tài chính đầy đủ | `fa` | Đủ 100 chỉ số theo bốn mẫu ngành, tra công thức và kỳ dữ liệu | Chưa mở | Có | Có | | Chỉ số tài chính mở rộng | `fa_advanced` | Dòng tiền theo CFA, DuPont, Altman Z, Piotroski F, Beneish M | Chưa mở | Có | Có | | Rủi ro, giá điều chỉnh, vi cấu trúc | `risk` | `vnstock_quant.risk`, `vnstock_quant.prices`, `vnstock_quant.micro` | Chưa mở | Có | Có | | Danh mục và định giá | `portfolio` | `vnstock_quant.portfolio`, `vnstock_quant.valuation` | Chưa mở | Có | Có | | Backtest cơ bản | `bt_basic` | Một mã, bảng quy tắc với 10 chỉ báo cơ bản | Có, theo lượt thử | Có | Có | | Backtest một mã đầy đủ | `bt` | Đủ chỉ báo trong bảng quy tắc, mọi chế độ khớp lệnh | Chưa mở | Có | Có | | Backtest danh mục | `bt_portfolio` | Nhiều mã, tái cân bằng theo tỷ trọng | Chưa mở | Có | Có | | Tối ưu và chống quá khớp | `bt_optimize` | Dò tham số, walk-forward, Monte Carlo | Chưa mở | Có | Có | Các cấp từ Silver trở lên khác nhau ở **quy mô** mỗi lần chạy (bảng bên dưới) và ở hạn mức tải dữ liệu của `vnstock`, không khác ở nhóm tính năng. Kiểm tra cấp và nhóm tính năng của chính bạn mà không trừ lượt: ```python import vnstock_quant as vq status = vq.entitlement() status["tier"], status["features"], status["policy_version"] # ('free', ['ta_basic', 'fa_basic', 'bt_basic'], 'quant_entitlement_v3') ``` --- ## Lượt dùng thử của bản Cộng đồng Bản Cộng đồng có hai bộ đếm lượt thử trong ngày, tách nhau và không liên quan đến hạn mức chung. Lượt được đếm trên máy, không cần khoá API, và làm mới lúc 00:00 giờ Việt Nam. | | Chỉ báo và chỉ số (`vnstock_quant`) | Backtest (`vnstock_quant.backtest`) | | :--- | :--- | :--- | | Lượt mỗi ngày | 30 phép tính, tính chung chỉ báo kỹ thuật và chỉ số tài chính | 3 lần chạy | | Số mã mỗi lần | 3 mã mỗi lần tải dữ liệu qua `vnstock` | 1 mã mỗi lần chạy | | Xem số còn lại | `vq.entitlement()["trial"]` | `vq.entitlement()["backtest"]["trial"]` | | Khi hết | `QuotaExceededError`, mã `QUANT_TRIAL_EXHAUSTED` | như bên trái | Hai bộ đếm tách nhau vì backtest có **hạn mức riêng** do máy chủ đặt, để một lần chạy thử không làm hụt lượt tính chỉ báo trong ngày. Máy chủ có thể đổi số lượt hoặc số mã mà bạn không cần cập nhật thư viện; bảng trên là mức mặc định hiện hành. --- ## Quy mô mỗi lần chạy thử Từng cấp giới hạn độ lớn của **một lần** backtest. Vượt ngưỡng thì thư viện báo `QuotaExceededError` với mã `QUANT_QUOTA_LIMIT` trước khi tính, kèm ngưỡng của cấp bạn trong thông điệp. | Cấp | Mã trong một danh mục | Tổ hợp tham số mỗi lần dò | Đường mô phỏng Monte Carlo | | :--- | ---: | ---: | ---: | | Cộng đồng | 1 | 10 | 200 | | Bronze | 10 | 100 | 1.000 | | Silver | 30 | 1.000 | 5.000 | | Golden | 100 | 10.000 | 20.000 | | Diamond | 400 | 50.000 | 100.000 | Xem các ngưỡng đang áp dụng cho bạn ở `vq.entitlement()["backtest"]["quota"]`. --- ## Số mã mỗi lần tải báo cáo tài chính `fa.Dataset.load()` tải nhiều bảng cho mỗi mã, nên số mã một lần gọi giới hạn theo cấp: Cộng đồng 3, Bronze 100, Silver 400, Golden và Diamond toàn thị trường. Vượt ngưỡng thì gặp `TierRequiredError` với mã `QUANT_SCOPE_LIMIT`. Giá chưa điều chỉnh dùng cho các chỉ số định giá cần cấp quyền sử dụng của `vnstock`; bản Cộng đồng gọi `Dataset.load(..., prices=False)` và các chỉ số P/E, P/B báo `MISSING_MARKET` ở cột `reason`. --- ## Khi quyền không đủ | Tình huống | Ngoại lệ | Mã | | :--- | :--- | :--- | | Nhóm tính năng chưa mở ở cấp hiện tại | `TierRequiredError` | `QUANT_TIER_REQUIRED` | | Quá số mã cho phép của cấp | `TierRequiredError` | `QUANT_SCOPE_LIMIT` | | Hết lượt thử trong ngày | `QuotaExceededError` | `QUANT_TRIAL_EXHAUSTED` | | Một lần chạy thử quá lớn cho cấp | `QuotaExceededError` | `QUANT_QUOTA_LIMIT` | | Không kiểm tra được quyền (khoá, thiết bị, mạng) | `AuthError` | theo `kind` | Thuộc tính `action` của ngoại lệ nói việc nên làm tiếp. Cây ngoại lệ đầy đủ ở [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/bat-dau/quy-uoc-du-lieu-va-loi). Phạm vi từng gói quyền sử dụng: [Bảng giá](/pricing). --- ## Đọc tiếp - [Cài đặt và thiết lập](/docs/vnstock_quant/bat-dau/cai-dat-va-thiet-lap) — Đọc đủ các trường của `vq.entitlement()`. - [Cấp quyền và xử lý lỗi của backtest](/docs/vnstock_quant/backtest/cap-quyen-va-xu-ly-loi) — Ví dụ bắt lỗi quyền khi chạy thử chiến lược. - [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/tich-hop/tai-du-lieu-bang-vnstock) — Phần nào tính vào hạn mức chung. --- ## Document: Từ vnstock_ta ## Tổng quan `vnstock_quant` kế tục `vnstock_ta` từ thế hệ 5. Với mã dùng lớp `Indicator`, bạn đổi tên thư viện trong câu lệnh `import`; tên hàm và phần lớn tên cột vẫn giữ nguyên. Sau đó, hãy chạy lại các phép tính: một số chỉ báo đã đổi công thức hoặc cách khởi tạo, cột `ADXR` của `adx` đổi thành `ADXR_14`, và tham số không hợp lệ nay báo lỗi. --- ## 1. Cài gói mới và đổi import ### Cài đặt gói mới Cài `vnstock_quant` từ kho phát hành của Vnstock. Chỉ gỡ `vnstock_ta` khi môi trường này không còn mã cần dùng gói cũ: ```bash # Cài đặt thư viện định lượng thế hệ mới pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant ``` ### Đổi tên Import trong mã nguồn Đổi câu lệnh `import` trong các tệp đang dùng `Indicator`: ```python # Cách viết cũ (thế hệ 4) from vnstock_ta import Indicator # Cách viết với vnstock_quant from vnstock_quant import Indicator ``` Mọi đoạn mã gọi hàm bên dưới như `ta = Indicator(df)`, `ta.trend.sma()`, `ta.macd()` hay `ta.momentum.rsi()` giữ nguyên cú pháp. Riêng kết quả số của một số chỉ báo sẽ khác bản cũ, xem mục 2. --- ## 2. Những kết quả có thể thay đổi Trong phiên bản 1.x, `vnstock_ta` phụ thuộc vào gói Python `pta_reload` (fork từ `pandas-ta`). Qua quá trình đối chiếu với **TA-Lib C 0.8.1** và nền tảng **QuantConnect LEAN**, dự án phát hiện nhiều chỉ báo trong phiên bản cũ bị sai lệch công thức hoặc khởi tạo sai chu kỳ. Khi so sánh với `vnstock_ta` 1.x, các chỉ báo rơi vào ba nhóm sau: - **32 chỉ báo không đổi**: giá trị trùng `vnstock_ta` 1.x (sai lệch dưới 1e-9), trừ vài trường hợp đặc biệt như phiên có khoảng giá bằng 0 hoặc không có khối lượng: `sma`, `ema`, `wma`, `hma`, `smma`, `alma`, `vwma`, `ichimoku`, `linreg`, `aroon`, `stoch`, `mom`, `roc`, `ao`, `willr`, `uo`, `bbands`, `kc`, `donchian`, `ui`, `true_range`, `cmf`, `ad`, `eom`, `mad`, `vwap`, `hl2`, `hlc3`, `ohlc4`, `midprice`, `increasing`, `decreasing`. - **10 chỉ báo chỉ khác ở giai đoạn khởi động** (warm-up period), sau đó trùng dần: `rsi`, `atr`, `adx`, `stochrsi`, `tsi`, `macd`, `fisher`, `massi`, `pvo`, `efi`. Nguyên nhân là bản cũ khởi tạo đường trung bình khác cách của Wilder và TA-Lib. Ở đầu chuỗi, mức lệch có thể lớn (RSI lệch khoảng 18 điểm), rồi giảm dần: với chu kỳ 14, còn khoảng 1e-6 sau 200 phiên. Riêng `adx`, cột ADXR đổi độ trễ và đổi tên thành `ADXR_14`. - **16 chỉ báo đã sửa lỗi công thức**, nên giá trị khác hẳn bản cũ: - `cci`: bản cũ thiếu ngoặc trong công thức nên giá trị mang độ lớn của giá; mọi ngưỡng ±100/±200 đặt trên CCI cũ cần đặt lại. - `kst`: bản cũ nhân thừa 100. - `cg`: bản cũ đảo ngược trọng số. - `nvi`: bản cũ cộng phần trăm thay vì nhân. - `vp`: bản cũ chia theo thời gian thay vì theo giá. - `pivots`: sửa các kiểu `traditional`, `woodie`, `demark`; mức S3, S4, R3, R4 thay đổi. - `psar`: bản cũ bỏ qua tham số `af` và khởi tạo bằng giá đóng cửa. - `supertrend`: logic dải và hướng nay khớp TradingView. - `dm`: bản cũ trả trung bình Wilder thay vì tổng Wilder (giá trị mới xấp xỉ giá trị cũ nhân chu kỳ). - `cmo`: theo đúng định nghĩa của Chande. - `squeeze`, `squeeze_pro`: cột động lượng khác; cờ ON/OFF/NO không đổi. - `obv`: bản cũ lệch một hằng số bằng khối lượng phiên đầu. - `mfi`: bản cũ tính phiên giá không đổi là dòng tiền âm. - `stdev`, `variance`: nay chia cho n (tổng thể) thay vì n − 1 (mẫu).

Nếu mã phân tích của bạn đang so sánh số liệu với các kết quả xuất ra từ vnstock_ta 1.x, số liệu mới từ vnstock_quant có thể có sự khác biệt ở 16 chỉ báo nêu trên. Số liệu mới từ vnstock_quant đã được đối chiếu với TA-Lib C, dữ liệu kiểm thử LEAN hoặc định nghĩa gốc của tác giả chỉ báo.

--- ## 3. Số đo hiệu năng tham khảo Kiểm thử đo lường tốc độ xử lý toàn bộ 58 chỉ báo kỹ thuật trên chuỗi dữ liệu 5.000 phiên giao dịch: | Tiêu chí đánh giá | vnstock_ta 1.x (Python) | vnstock_quant 0.1.x (Rust Core) | Mức độ cải thiện | | :--- | :--- | :--- | :--- | | **Thời gian xử lý** | 138,5 ms | 5,3 ms | **Nhanh hơn 25,9 lần** | | **Quản lý bộ nhớ** | Tạo nhiều đối tượng DataFrame tạm | Sử dụng Flat Buffer vùng đệm liên tục | Ít đối tượng tạm hơn | | **Đa luồng (Concurrency)** | Bị khoá bởi Python GIL | Nhả GIL trong lõi Rust | Phần dựng kết quả pandas vẫn giữ GIL; chuỗi ngắn chạy nhiều luồng chưa nhanh hơn | | **Độ ổn định tham số** | Âm thầm thay đổi khi sai tham số | Báo lỗi kèm mã lỗi rõ ràng | Tránh lỗi ngầm trong thuật toán | Số đo thời gian là số tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026; máy khác cho số khác. --- ## 4. Chuyển phần vẽ biểu đồ `vnstock_ta` 1.x từng có lớp `Plotter`. `vnstock_quant` tập trung vào tính toán; để vẽ kết quả ở thế hệ 5, dùng thư viện [`vnstock_chart`](/docs/vnstock-chart). Cách gọi hàm vẽ khác `Plotter`, nên hãy xem [các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do) và [ví dụ kết hợp với vnstock thế hệ 5](/docs/vnstock-chart/ket-hop-voi-gen5) trước khi sửa mã. --- ## 5. Danh mục kiểm tra chuyển đổi 1. Cài `vnstock_quant` trong môi trường bạn dùng để kiểm tra mã. 2. Đổi `from vnstock_ta import Indicator` thành `from vnstock_quant import Indicator`. 3. Chạy lại mã và sửa các tham số bị báo không hợp lệ. 4. So sánh kết quả của những chỉ báo đã thay đổi trước khi tiếp tục dùng các ngưỡng cũ. 5. Nếu không còn dùng gói cũ, gỡ `vnstock-ta` khỏi môi trường và tệp phụ thuộc của dự án. --- ## Đọc tiếp - [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) — Hướng dẫn chi tiết 58 chỉ báo kỹ thuật. - [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) — Khám phá 100 chỉ số tài chính BCTC VAS mới được bổ sung. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường rủi ro danh mục và thanh khoản Amihud. - [Kiểm định chất lượng & hiệu năng](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) — Báo cáo đo kiểm hiệu năng và đối chứng số học với TA-Lib C. --- ## Document: Giá điều chỉnh > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. `vnstock_quant.prices` chuyển bảng giá chưa điều chỉnh (dạng `trade_history()` của `vnstock`) sang giá đã điều chỉnh theo sự kiện quyền. Hàm dùng danh sách sự kiện (`events()`) và **kiểm từng sự kiện với giá tham chiếu, giá trần, giá sàn do sàn đặt**, nên bạn biết sự kiện nào khớp với sàn và sự kiện nào cần xem lại. Cần cấp quyền sử dụng từ Bronze, cùng nhóm quyền `risk` ([Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc)). | Hàm | Trả về | | :--- | :--- | | `prices.adjust(prices, events, ...)` | Bảng giá đầu vào với các cột giá đã nhân hệ số; bảng hệ số trong `attrs["factors"]` | | `prices.factors(prices, events, ...)` | Bảng hệ số: mỗi phiên giao dịch không hưởng quyền một dòng, kèm nhân chứng của sàn và trạng thái | | `prices.from_vnstock(symbol, start, end, ...)` | `open, high, low, close, volume` đã điều chỉnh, đơn vị đồng, tải qua `vnstock` | Chuỗi lợi suất cho `risk`, `portfolio` và `backtest` nên tính từ giá đã điều chỉnh: giá chưa điều chỉnh tạo ra phiên thua lỗ giả vào ngày giao dịch không hưởng quyền. --- ## Dữ liệu mẫu Ví dụ dùng bốn phiên có dạng của `trade_history()`, chạy được không cần mạng. Phiên 12/06/2024 là ngày giao dịch không hưởng quyền của FPT: cổ tức tiền 1.000 đồng và cổ phiếu thưởng 15%. ```python import pandas as pd from vnstock_quant import prices tz = "Asia/Ho_Chi_Minh" sessions = pd.DataFrame({ "trading_date": pd.to_datetime(["2024-06-10", "2024-06-11", "2024-06-12", "2024-06-13"]).tz_localize(tz), "reference_price": [144_000.0, 145_000.0, 126_517.0, 132_000.0], "ceiling_price": [154_000.0, 155_100.0, 135_300.0, 141_200.0], "floor_price": [134_000.0, 134_900.0, 117_700.0, 122_800.0], "open": [144_500.0, 145_500.0, 128_000.0, 132_500.0], "high": [146_000.0, 147_000.0, 133_000.0, 134_000.0], "low": [143_500.0, 145_000.0, 127_500.0, 131_500.0], "close": [145_000.0, 146_500.0, 132_000.0, 133_000.0], "matched_volume": [3.1e6, 2.8e6, 6.4e6, 4.0e6], }) events = pd.DataFrame({ "event_code": ["DIV", "ISS", "ISS"], "issue_type": [None, "bonus_share", "esop"], "event_title_vi": ["Cổ tức tiền 1.000đ", "Cổ phiếu thưởng 15%", "ESOP 0,5%"], "exright_date": pd.to_datetime(["2024-06-12", "2024-06-12", "2024-06-13"]).tz_localize(tz), "exercise_ratio": [0.1, 0.15, 0.005], "value_per_share": [1000.0, None, None], }) ``` Với dữ liệu thật: ```python from vnstock import Market, Reference sessions = Market().equity("FPT").trade_history(start="2024-01-01", end="2024-12-31") events = Reference().company("FPT").events() ``` `trade_history()` trả tối đa 1.000 phiên mỗi lần gọi. Cần chuỗi dài thì dùng `prices.from_vnstock`, hàm này tự tải theo từng cửa sổ ba năm. --- ## Điều chỉnh giá ```python adjusted = prices.adjust(sessions, events) adjusted[["trading_date", "close", "reference_price"]] ``` Giá các phiên trước 12/06/2024 được nhân với `(146.500 − 1.000) / (1,15 × 146.500) ≈ 0,8636`. Phiên cuối giữ nguyên. ESOP không làm đổi giá tham chiếu nên không được điều chỉnh. Khối lượng và các cột `*_adjusted` của bảng đầu vào giữ nguyên. --- ## Bảng hệ số và nhân chứng của sàn ```python table = prices.factors(sessions, events) table[["date", "kinds", "cash", "stock", "exchange_factor", "witness", "factor", "status"]] ``` - `factor`: hệ số nhân cho mọi giá trước `date`. - `exchange_factor`: hệ số suy từ giá tham chiếu của sàn (126.517 / 146.500). - `witness = "reference"`: giá tham chiếu và trung điểm trần, sàn cùng xác nhận sự kiện. - `status = "confirmed"`: sự kiện khớp với sàn. Trạng thái khác cho biết mức tin cậy thấp hơn: `implied` khi chỉ suy được từ giá sàn đặt, `inferred` khi danh sách sự kiện không có nhưng giá tham chiếu và biên độ cùng đổi, `unresolved` khi sự kiện và giá sàn không khớp nhau. Trạng thái cần bạn chú ý đều kèm cảnh báo `VnstockQuantWarning`. --- ## Tuỳ chọn ```python split = prices.factors(sessions, events, mode="split") # chỉ sự kiện cổ phiếu exchange = prices.factors(sessions, events, basis="exchange") # theo giá tham chiếu đã làm tròn của sàn split["factor"].iloc[0], exchange["factor"].iloc[0] ``` | Tham số | Giá trị | Dùng khi | | :--- | :--- | :--- | | `mode` | `full` (mặc định) | Lợi suất, rủi ro, backtest: cổ tức tiền được tính như đã tái đầu tư | | | `split` | Chỉ báo kỹ thuật, so đồ thị giá không tính cổ tức tiền | | `basis` | `event` (mặc định) | Giá lý thuyết từ sự kiện, không phụ thuộc cách làm tròn của sàn | | | `exchange` | Đúng giá tham chiếu sàn đã đặt (đã làm tròn bước giá) | | `infer` | `True` (mặc định) | Điều chỉnh cả lần giá tham chiếu và biên độ cùng đổi mà danh sách sự kiện không có | | `unit` | `auto`, `dong`, `thousand` | Đơn vị của bảng giá; `auto` nhận ra bảng nghìn đồng của `ohlcv()` | Quyền mua không có giá phát hành trong `events()`. Thư viện suy giá từ giá tham chiếu. Nếu biết giá chính xác, điền vào cột `value_per_share` của dòng quyền mua: ```python rights = pd.DataFrame({ "event_code": ["ISS"], "issue_type": ["rights_issue"], "event_title_vi": ["Quyền mua 20%"], "exright_date": pd.to_datetime(["2024-06-12"]).tz_localize(tz), "exercise_ratio": [0.2], "value_per_share": [10_000.0], }) prices.factors(sessions[["trading_date", "close"]], rights)[["rights_price", "rights_price_source", "factor"]] ``` --- ## Tải trực tiếp qua vnstock ```python bars = prices.from_vnstock("FPT", start="2019-01-01") bars.tail() pd.DataFrame(bars.attrs["factors"]) # bảng hệ số ``` Bảng trả về có dạng như `Market().equity(s).ohlcv()` (`open, high, low, close, volume`, chỉ mục `time`) nhưng đơn vị là đồng. Dùng thẳng được cho `vnstock_quant.ta`, `risk.returns` và `portfolio`. --- ## Đọc tiếp - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/bat-dau/quy-uoc-du-lieu-va-loi) — Vì sao chuỗi lợi suất cần giá đã điều chỉnh. - [Rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Tính lợi suất và các thước đo từ giá đã điều chỉnh. - [Luật thị trường, phí và sự kiện trong backtest](/docs/vnstock_quant/backtest/luat-thi-truong-va-phi) — Cách mô-đun backtest xử lý cổ tức và quyền mua khi mô phỏng. --- ## Document: Vi cấu trúc thị trường > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. `vnstock_quant.micro` tính trên **dữ liệu khớp lệnh từng lệnh** (tick): gom thành nến theo thời gian, số lệnh, khối lượng hoặc giá trị; xác định bên chủ động; khối lượng mua trừ bán cộng dồn (CVD); VPIN; biến động thực hiện. Cần cấp quyền sử dụng từ Bronze, cùng nhóm quyền `risk` ([Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc)). Hàm không phụ thuộc nguồn. Cùng một cách gọi cho: | Dữ liệu | Cột thường có | Bên chủ động | | :--- | :--- | :--- | | Khớp lệnh trong phiên cổ phiếu Việt Nam (`Market().equity(...).trades()`) | `time, price, volume, match_type, id` | `match_type` là `Buy` hoặc `Sell`; ATO, ATC không có bên | | Hợp đồng tương lai (`Market().futures("VN30F1M").trades()`) | như trên | như trên | | Luồng giao dịch tài sản số lưu bằng `vnstock_pipeline` | `time, price, quantity, buyer_is_maker` | `buyer_is_maker=True` nghĩa là bên bán chủ động | | Nguồn không có bên | `time, price, volume` | suy bằng tick rule | --- ## Dữ liệu mẫu Ví dụ dùng một phiên tổng hợp có hình dạng của dữ liệu khớp lệnh HOSE (bước giá 50 đồng, phiên ATO, nghỉ trưa, ATC), chạy được không cần mạng. ```python import numpy as np import pandas as pd from vnstock_quant import micro rng = np.random.default_rng(7) day = "2026-10-13" tz = "Asia/Ho_Chi_Minh" morning = pd.date_range(f"{day} 09:15:01", f"{day} 11:30", tz=tz, periods=12_000) afternoon = pd.date_range(f"{day} 13:00", f"{day} 14:29:59", tz=tz, periods=8_000) time = pd.DatetimeIndex([pd.Timestamp(f"{day} 09:15", tz=tz), *morning, *afternoon, pd.Timestamp(f"{day} 14:45", tz=tz)]) price = 25_000 + np.cumsum(rng.choice([-50, 0, 0, 50], size=len(time))).astype(float) side = np.where(rng.random(len(time)) < 0.52, "Buy", "Sell").astype(object) side[0], side[-1] = "ATO", "ATC" volume = rng.integers(1, 200, size=len(time)) * 100.0 volume[0], volume[-1] = 250_000.0, 400_000.0 ticks = pd.DataFrame({"time": time, "price": price, "volume": volume, "match_type": side}) len(ticks) ``` Với dữ liệu thật: ```python from vnstock import Market ticks = Market().equity("FPT").trades(limit=1000) # tối đa 1.000 lệnh mỗi lần gọi futures = Market().futures("VN30F1M").trades(limit=1000) ``` Một phiên đầy đủ có vài chục nghìn lệnh. Lấy nhiều trang qua `last_id`, hoặc để [vnstock_pipeline](/docs/vnstock-pipeline) lưu dữ liệu khớp lệnh vào kho rồi đọc lại. --- ## Bên chủ động ```python sign = micro.classify(ticks) # đọc match_type; ATO, ATC cho 0 sign.value_counts() tick_rule = micro.classify(ticks, method="tick_rule") (tick_rule == sign)[sign != 0].mean() # tỷ lệ tick rule khớp với nguồn ``` Khi nguồn có cột bên chủ động thì nên dùng cột đó. Tick rule chỉ là ước lượng; trên dữ liệu ngẫu nhiên như ví dụ này, tỷ lệ khớp gần 50%, nghĩa là ví dụ không nói gì về độ chính xác của tick rule trên dữ liệu thật. --- ## Nến theo thời gian, số lệnh, khối lượng, giá trị ```python m1 = micro.bars(ticks, by="time", size="1min") # tick → nến 1 phút m5 = micro.bars(ticks, by="time", size="5min") tb = micro.bars(ticks, by="tick", size=200) # mỗi nến 200 lệnh vb = micro.bars(ticks, by="volume", size=100_000) # mỗi nến đúng 100.000 cổ phiếu db = micro.bars(ticks, by="value", size=2e9) # mỗi nến đúng 2 tỷ đồng m1[["open", "high", "low", "close", "volume", "vwap", "buy_volume", "sell_volume"]].head() ``` - `vwap` của từng nến là Σ(giá × khối lượng) / Σ khối lượng, giá bình quân thật của nến. Với nến khối lượng hay giá trị, đó là giá bình quân của đúng một lô. - Lệnh vắt qua ranh giới được tách để mỗi nến đủ đúng `size` (`split=True`). `split=False` để lệnh đó đóng nến nguyên vẹn, nến hơi vượt `size`. - Một lệnh lớn hơn `max_split` nến (mặc định 1.000) không bị tách mà thành một nến gắn cờ `oversize`. Ở ví dụ này, ATC 400.000 cổ phiếu với `size=100` là một nến chứ không phải 4.000 nến. - Nến cuối chưa đủ `size` có `complete=False`. - Tổng khối lượng các nến bằng tổng khối lượng khớp: không mất, không đếm trùng. ```python assert vb["volume"].sum() == ticks["volume"].sum() vb[["volume", "complete", "oversize"]].tail(3) ``` Nến dùng thẳng cho chỉ báo kỹ thuật: ```python from vnstock_quant.ta import Indicator Indicator(m1).rsi(length=14).tail() ``` --- ## Khối lượng mua trừ bán (CVD) ```python flow = micro.cvd(m1) # cộng dồn, bắt đầu lại mỗi ngày flow.tail() ``` CVD tăng trong khi giá đi ngang thường được đọc là lực mua chủ động đang bị hấp thụ. Hàm chỉ tính chuỗi số, không đưa tín hiệu. --- ## VPIN ```python v = micro.vpin(vb, window=50) v.describe() ``` VPIN (Easley, López de Prado và O'Hara, 2012) là tỷ lệ mất cân bằng mua bán trên `window` nến khối lượng gần nhất, từ 0 đến 1. Bài gốc chọn kích thước nến khoảng 1/50 khối lượng trung bình ngày và `window` bằng 50. Chỉ số này **còn tranh cãi**: Andersen và Bondarenko (2014) cho rằng nó dự báo kém biến động ngắn hạn khi đã tính đến cường độ giao dịch. Dùng để nghiên cứu, không dùng làm tín hiệu. --- ## Biến động thực hiện ```python rv = micro.realized(m5) # mỗi ngày: rv, bv, jump, jump_share, rvol, rvol_annual, n rv[["rv", "bv", "jump_share", "rvol", "rvol_annual", "n"]] ``` - `rv` là tổng bình phương log-return giữa các nến trong ngày (Andersen, Bollerslev, Diebold và Labys, 2003). - `bv`, biến thiên bipower, ít bị ảnh hưởng bởi một cú nhảy giá (Barndorff-Nielsen và Shephard, 2004); `jump = max(rv − bv, 0)` là phần nhảy. - Lợi suất không nối qua đêm. Giờ nghỉ trưa tính là một lợi suất. - Dùng nến khoảng 5 phút. Nến quá mịn dính nhiễu bước giá (giá nhảy qua lại giữa giá mua và giá bán), làm `rv` cao hơn thật. Với cổ phiếu Việt Nam, bước giá 10 đến 100 đồng là một phần đáng kể của biến động trong phút. - `rvol_annual` nhân với `periods=252`. Muốn theo lịch HOSE thì truyền `periods=250`. --- ## Hiệu năng Phép gom chạy trong lõi Rust; phần còn lại là chuẩn hoá cột bằng pandas. Một lần gọi `bars` gồm cả xác định bên chủ động từ `match_type`, đo trên máy tính xách tay chip Apple Silicon: | Số lệnh | Thời gian | | ---: | :--- | | 20.000 (một phiên như ví dụ) | khoảng 7 ms | | 500.000 | khoảng 85 ms | --- ## Đọc tiếp - [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) — Tính chỉ báo trên nến vừa gom. - [Rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Thước đo độ kém thanh khoản Amihud trên dữ liệu ngày. - [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/tich-hop/tai-du-lieu-bang-vnstock) — Lấy dữ liệu khớp lệnh và các loại dữ liệu khác. --- ## Document: Cấp quyền và xử lý lỗi > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Kiểm tra trạng thái quyền `vq.entitlement()` chạy trên máy, không trừ lượt. Khoá `backtest` là phần riêng của mô-đun này: ```python import vnstock_quant as vq state = vq.entitlement() print(state["tier"], state["features"]) # features gồm bt_basic, bt, bt_portfolio, bt_optimize khi được mở print(state["backtest"]["trial"]) # None nếu cấp của bạn không bị đếm lượt backtest riêng print(state["backtest"]["quota"]) # quy mô tối đa của một lần chạy ``` | Khoá | Ý nghĩa | | :--- | :--- | | `features` | Nhóm tính năng đang mở của cả thư viện; phần backtest là `bt_basic`, `bt`, `bt_portfolio`, `bt_optimize` | | `backtest.trial` | Lượt backtest trong ngày: `daily`, `used`, `remaining`, `max_symbols`, `resets_at` | | `backtest.quota` | Quy mô một lần chạy: `portfolio_symbols`, `sweep_tasks`, `monte_carlo_paths` | | `backtest.budget` | Mã hạn mức riêng của mô-đun backtest trên máy chủ; chỉ dùng để đối chiếu khi cần hỗ trợ | --- ## Bản Cộng đồng và các cấp quyền sử dụng Từ Bronze, bạn dùng được mọi tính năng của mô-đun. Các cấp quyền sử dụng chỉ khác nhau ở số lượt mỗi ngày và quy mô một lần chạy. | | Chưa đăng nhập | Cộng đồng | Bronze | Silver | Golden | Diamond | | :--- | ---: | ---: | ---: | ---: | ---: | ---: | | Backtest một mã, bảng quy tắc, kiểm tra nhìn trước tương lai | có | có | có | có | có | có | | Chỉ báo dùng được trong bảng quy tắc | 10 | 10 | 56 | 56 | 56 | 56 | | Danh mục nhiều mã, dò tham số, walk-forward, Monte Carlo | — | — | có | có | có | có | | Lượt tính mỗi ngày | 3 | 5 | 200 | 1.000 | 5.000 | không đếm riêng | | Số mã mỗi lần chạy danh mục | 1 | 1 | 10 | 30 | 100 | 400 | | Số tổ hợp mỗi lần dò tham số hoặc walk-forward | — | — | 100 | 1.000 | 10.000 | 50.000 | | Số đường mỗi lần chạy Monte Carlo | — | — | 1.000 | 5.000 | 20.000 | 100.000 | Bản Cộng đồng dùng được 10 chỉ báo trong bảng quy tắc, cùng nhóm chỉ báo mở cho bản Cộng đồng của `vnstock_quant`: `sma`, `ema`, `rsi`, `macd`, `stoch`, `bbands`, `atr`, `obv`, `vwap`, `pivots`. Bảng quy tắc dùng chỉ báo khác thì bị từ chối với `QUANT_TIER_REQUIRED` trước khi chạy, và không bị trừ lượt. Tín hiệu bạn tự tính bằng thư viện khác rồi đưa vào qua `signals` hay `entries`/`exits` thì không bị giới hạn này. Cách đếm: - **Số lượt phụ thuộc vào hàm và quy mô lần chạy.** `run` tính một lượt; `run_portfolio` tính một lượt mỗi mã; `sweep` và `walk_forward` tính theo số tổ hợp. Các hàm tính toán khác gồm `monte_carlo`, `eval_rule_dsl`, `check_rule_dsl_causality` và `detect_limit_events`. Xem số lượt còn lại trong `vq.entitlement()["backtest"]` trước khi chạy. - **Các hàm chỉ đọc không trừ lượt:** `list_brokers`, `list_profiles`, `list_presets`, `list_indicators`, `catalog`, `schema`, `vq.entitlement`, `vq.build_info`. - `check_causality` (kiểm tra hàm tín hiệu Python của bạn) và `deflated_sharpe_ratio` không trừ lượt. - Lượt làm mới mỗi ngày theo giờ Việt Nam. `trial["resets_at"]` ghi thời điểm làm mới. - **Lượt backtest là dòng ngân sách riêng** do máy chủ đặt cho mô-đun này, không trừ vào 30 phép tính mỗi ngày của chỉ báo và chỉ số tài chính. Với tài khoản đã đăng nhập, mọi lần chạy còn được tính vào hạn mức sử dụng chung của tài khoản, như các thư viện khác của Vnstock. - Diamond không bị đếm lượt riêng cho mô-đun này, chỉ tính vào hạn mức sử dụng chung. Số lượt mỗi ngày có thể được điều chỉnh mà không cần phát hành lại thư viện. Số đúng cho máy của bạn là số trong `vq.entitlement()["backtest"]`. Khi hết lượt, thư viện báo `QUANT_TRIAL_EXHAUSTED`. Khi một lần chạy vượt quy mô của cấp, thư viện báo `QUANT_QUOTA_LIMIT` kèm cấp chạy được quy mô đó. --- ## Xử lý lỗi Mọi lỗi của mô-đun thuộc cây `VnstockQuantError` của `vnstock_quant` (xem [Cài đặt và thiết lập](/docs/vnstock_quant/free/bat-dau/cai-dat-va-thiet-lap)). Mỗi lỗi có: - `code`: mã ổn định, dùng để rẽ nhánh trong mã của bạn; - `message`: thông điệp tiếng Việt; - `kind`: nhóm lỗi; - `retryable`: có nên thử lại không; - `action`: việc nên làm tiếp (nếu có). ```python from vnstock_quant import backtest as bt from vnstock_quant.errors import EntitlementError, VnstockQuantError try: res = bt.sweep(df, tasks, symbol="FPT") except EntitlementError as e: # TierRequiredError, QuotaExceededError print(e.code, e.message, e.action) except VnstockQuantError as e: print(e.code, e.message) ``` ## Lớp ngoại lệ | Lớp | Khi nào | | :--- | :--- | | `InputDataError` | Dữ liệu nến, tín hiệu hoặc cột theo phiên sai | | `CausalityViolationError` (con của `InputDataError`) | Bảng quy tắc dùng chỉ báo đọc dữ liệu tương lai | | `InvalidParameterError` | Tham số, hồ sơ, biểu phí, chế độ khớp lệnh không hợp lệ | | `TierRequiredError` | Cấp chưa mở tính năng, hoặc bảng quy tắc dùng chỉ báo ngoài bản Cộng đồng | | `QuotaExceededError` | Hết lượt backtest trong ngày, hoặc một lần chạy vượt quy mô của cấp | | `AuthError`, `UnsupportedError` | Khoá, thiết bị, máy chủ cấp quyền; bản đã hết hạn hoặc bị ngừng | ## Mã lỗi | `code` | Ý nghĩa | Cách xử lý | | :--- | :--- | :--- | | `QUANT_INPUT_DATA` | Dữ liệu thiếu cột ngày, ngày không đọc được, số phần tử tín hiệu hoặc cột theo phiên (`entry_limit`, `entry_stop`, `exit_stop`, `exit_tags`, `target_weights`) khác số phiên, các mã của danh mục lệch ngày | Sửa dữ liệu đầu vào | | `QUANT_INVALID_PARAMETER` | Tham số không hỗ trợ, giá trị không hợp lệ, chọn nhiều cách tính khối lượng, chế độ khớp lệnh đã gỡ (`tradingview`, `amibroker`), khai `corporate_actions` trên giá đã điều chỉnh hoặc thiếu `symbol` trong danh mục nhiều mã, `risk_per_trade_pct` mà không có mức dừng, `rebalance` dùng với hồ sơ phái sinh | Đọc `message`, sửa tham số | | `QUANT_UNKNOWN_PROFILE` | `profile` không có trong `list_profiles()` | Dùng một hồ sơ có sẵn | | `QUANT_UNKNOWN_BROKER` | `broker` không có trong `list_brokers()` | Dùng một mã có sẵn, hoặc khai `fee` | | `QUANT_CAUSALITY_VIOLATION` | Bảng quy tắc dùng `ichimoku` hoặc `vp` | Chọn chỉ báo khác | | `QUANT_TIER_REQUIRED` | Cấp hiện tại chưa mở nhóm tính năng này (ví dụ Cộng đồng gọi `sweep`), hoặc bảng quy tắc dùng chỉ báo ngoài 10 chỉ báo của bản Cộng đồng | Xem cấp cần có trong `message`, hoặc đăng ký gói ở cấp phù hợp | | `QUANT_TRIAL_EXHAUSTED` | Đã dùng hết lượt trong ngày | Chờ tới thời điểm làm mới (`vq.entitlement()["backtest"]["trial"]["resets_at"]`) | | `QUANT_QUOTA_LIMIT` | Một lần chạy vượt quy mô của cấp: số mã, số tổ hợp, số đường Monte Carlo | Giảm quy mô, hoặc dùng cấp ghi trong `message` | Lỗi từ lớp xác thực dùng chung của hệ sinh thái mang mã `VNSTOCK_AUTH_...`, ví dụ khi khoá API không hợp lệ hoặc thiết bị vượt giới hạn. Các lỗi này thuộc `EntitlementError` và có `action` hướng dẫn cụ thể.

Khi gặp QUANT_QUOTA_LIMIT hay QUANT_TRIAL_EXHAUSTED, đừng chia một lần dò tham số thành nhiều lần nhỏ để chạy tiếp. Nếu bạn dùng trợ lý AI, hãy yêu cầu nó báo lại lỗi cho bạn thay vì tự tìm đường vòng.

--- ## Document: Chạy backtest và đọc kết quả > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## `run` ```python bt.run( data, signals=None, *, entries=None, exits=None, short_entries=None, short_exits=None, tags=None, rule_dsl=None, feature_columns=None, entry_limit=None, entry_stop=None, exit_stop=None, exit_tags=None, symbol="SYMBOL", price_unit="auto", benchmark_returns=None, rf_annual=0.0, **config, ) -> BacktestResult ``` Truyền đúng một trong ba dạng tín hiệu: `signals`, `entries`/`exits`, hoặc `rule_dsl` (xem [Dữ liệu và tín hiệu](/docs/vnstock_quant/free/backtest/du-lieu-va-tin-hieu)). Số phần tử của tín hiệu phải bằng số phiên. `entry_limit`, `entry_stop`, `exit_stop`, `exit_tags` cũng là mảng theo phiên, cùng độ dài; mục "Lệnh giới hạn, lệnh dừng và điểm thoát" ở dưới giải thích từng tham số. | Tham số | Mặc định | Ý nghĩa | | :--- | :--- | :--- | | `symbol` | `"SYMBOL"` | Tên mã, ghi vào kết quả | | `feature_columns` | `None` | `dict` tên cột → danh sách số, dùng được như cột trong `rule_dsl` | | `price_unit` | `"auto"` | `"auto"`, `"vnd"`, `"thousand_vnd"`. Xem [Đơn vị giá](/docs/vnstock_quant/free/backtest/luat-thi-truong-va-phi) | | `benchmark_returns` | `None` | Lợi suất theo phiên của chỉ số so sánh, để tính các thước đo tương đối | | `rf_annual` | `0.0` | Lãi suất phi rủi ro theo năm, dùng cho Sharpe, Sortino | ### Tham số cấu hình (`**config`) | Tham số | Mặc định | Ý nghĩa | | :--- | :--- | :--- | | `init_cash` | `100_000_000` | Vốn ban đầu, theo đồng | | `profile` | `"vn_hose"` | Hồ sơ thị trường: lô, bước giá, biên độ, chu kỳ thanh toán, thuế bán | | `profile_overrides` | `None` | `dict` ghi đè từng trường của hồ sơ | | `fee` | `0.0015` | Phí mỗi chiều. Một số (cả hai chiều), tuple `(mua, bán)`, hoặc `dict` mô hình phí. Thuế bán lấy theo hồ sơ, không nằm trong `fee` | | `broker` | `None` | Mã biểu phí trong `bt.list_brokers()`, thay cho `fee` | | `execution` | `"vn_realistic"` | Chế độ khớp lệnh. Xem [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/free/backtest/che-do-khop-lenh) | | `execution_timing` | theo chế độ | `"next_open"`, `"next_close"`, `"same_close"` | | `same_bar_priority` | theo chế độ | `"stop_first"`, `"target_first"`, `"ohlc_path"`. Xem [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/free/backtest/che-do-khop-lenh) | | `use_unsettled_proceeds` | `False` | Cho phép dùng tiền bán chưa về tài khoản để mua (ứng trước tiền bán) | | `stop_loss_pct` | `None` | Cắt lỗ theo tỷ lệ so với giá vào, ví dụ `0.07` là 7% | | `take_profit_pct` | `None` | Chốt lời theo tỷ lệ | | `trailing_stop_pct` | `None` | Cắt lỗ đuổi theo đỉnh, theo tỷ lệ | | `trail_activation_pct` | `None` | Cắt lỗ đuổi chỉ bật sau khi lãi đạt tỷ lệ này | | `breakeven_trigger_pct` | `None` | Lãi đạt tỷ lệ này thì dời điểm dừng về giá hoà vốn (đã tính phí hai chiều và thuế bán) | | `take_profit_levels` | `None` | Chốt lời từng phần, ví dụ `[{"pct": 0.1, "qty_pct": 0.5}, {"pct": 0.2, "qty_pct": 0.5}]` | | `max_holding_bars` | `None` | Bán ở giá mở cửa sau khi giữ đủ số phiên này | | `pyramiding` | `1` | Số lô tối đa của một vị thế cùng mã | | `order_valid_bars` | `1` | Số phiên một lệnh giới hạn/dừng còn hiệu lực trước khi hết hạn | | `account_guard` | `None` | Ngừng mở vị thế mới khi sụt giảm hoặc chuỗi lệnh lỗ vượt ngưỡng | | `slippage_pct` | `0.0` | Trượt giá bất lợi mỗi lần khớp, theo tỷ lệ | | `slippage_ticks` | `0.0` | Trượt giá bất lợi thêm, theo số bước giá của hồ sơ | | `fee_per_contract` | `None` | Phí cố định mỗi đơn vị (mỗi hợp đồng VN30F) mỗi chiều, cộng thêm vào phí theo tỷ lệ | | `prices_adjusted` | `True` | Dữ liệu là giá đã điều chỉnh. Muốn khai `corporate_actions` thì dùng giá gốc và đặt `False` | | `corporate_actions` | `None` | Cổ tức tiền, cổ phiếu thưởng, quyền mua. Xem [Luật thị trường, phí và sự kiện](/docs/vnstock_quant/free/backtest/luat-thi-truong-va-phi) | | `shock_events` | `None` | Kịch bản sốc do bạn tự khai | Truyền một tham số không có trong bảng là lỗi `QUANT_INVALID_PARAMETER`. ### Khối lượng mỗi lệnh Chọn tối đa một cách. Không chọn thì mỗi lệnh dùng toàn bộ tiền mặt đang có. | Tham số | Ý nghĩa | | :--- | :--- | | `position_size_pct` | Tỷ lệ tiền mặt đang có, ví dụ `0.5` là một nửa | | `size_equity_pct` | Tỷ lệ tổng tài sản | | `size_value` | Số tiền cố định mỗi lệnh | | `size_qty` | Số cổ phiếu cố định mỗi lệnh | | `risk_per_trade_pct` | Tỷ lệ tài sản sẵn sàng mất nếu giá chạm điểm dừng: khối lượng = `vốn × risk_per_trade_pct / |giá vào − mức dừng|`. Cần có `stop_loss_pct` hoặc cột `exit_stop`; thiếu cả hai là lỗi `QUANT_INVALID_PARAMETER` | Chọn thêm `max_position_pct` để giới hạn giá trị một vị thế theo tỷ lệ tài sản, áp dụng cùng với cách tính khối lượng ở trên. Khối lượng được làm tròn xuống theo lô của hồ sơ (100 cổ phiếu với cổ phiếu Việt Nam). Ở chế độ mặc định, thư viện chừa đủ tiền cho phí; không đủ tiền cho một lô thì lệnh bị ghi vào `rejected_orders` với mã `INSUFFICIENT_CASH`. --- ## Lệnh giới hạn, lệnh dừng và điểm thoát Mặc định, lệnh vào khớp ở giá mở cửa phiên sau tín hiệu (lệnh thị trường). Bốn cột theo phiên dưới đây cho vào lệnh có điều kiện và dừng lỗ đổi theo thời gian, đều là mảng cùng độ dài với dữ liệu, phần tử `None`/`null` nghĩa là không đặt ở phiên đó. ### Lệnh vào có điều kiện ```python res = bt.run( df, sigs, entry_limit=[None, 58_000.0, None, ...], # chỉ mua ở phiên 1, với giá giới hạn 58.000 đ order_valid_bars=3, # lệnh chờ tối đa 3 phiên rồi hết hạn ) ``` - `entry_limit`: giá giới hạn. Lệnh khớp ở giá giới hạn hoặc giá mở cửa tốt hơn, nhưng chỉ khi giá đã **đi qua mức đặt** một số bước giá (`limit_fill_ticks` của hồ sơ, mặc định 1 bước cho cổ phiếu Việt Nam và `vn_futures`, 0 cho các hồ sơ khác) — chạm đúng mức chưa chắc đã tới lượt khớp trong hàng đợi thật. - `entry_stop`: giá dừng (mua khi giá vượt lên, kiểu lệnh breakout). Khớp tại mức dừng, hoặc tại giá mở cửa nếu phiên mở cửa đã vượt qua mức đó. - Đặt cả hai cùng phiên thành lệnh **dừng-giới hạn**: lệnh giới hạn chỉ kích hoạt sau khi giá chạm mức dừng; nếu giá đã vượt qua giới hạn ngay lúc đó, lệnh dừng-giới hạn chuyển thành lệnh giới hạn thường từ phiên sau. - Lệnh chờ tính từ phiên sau tín hiệu, tối đa `order_valid_bars` phiên (mặc định 1, tức chỉ xét đúng phiên kế tiếp). Giá đặt ngoài biên độ của phiên thì chờ ở giá trần/sàn, không bị bỏ ngay. - Một tín hiệu thoát cùng chiều ở phiên sau hủy lệnh chờ chưa khớp. ### Dừng lỗ, chốt lời và chốt lời từng phần ```python res = bt.run( df, sigs, stop_loss_pct=0.07, trailing_stop_pct=0.10, trail_activation_pct=0.05, # cắt lỗ đuổi 10%, chỉ bật khi đã lãi 5% breakeven_trigger_pct=0.08, # lãi 8% thì dời điểm dừng về giá hoà vốn take_profit_levels=[{"pct": 0.10, "qty_pct": 0.5}, {"pct": 0.20, "qty_pct": 0.5}], max_holding_bars=40, ) ``` - Mức dừng ràng buộc là mức **chặt nhất** trong các mức đang bật: `stop_loss_pct`, cắt lỗ đuổi (khi đã kích hoạt), hoà vốn (khi đã kích hoạt), và cột `exit_stop` nếu có. - `exit_stop`: mức dừng lỗ tự tính (ví dụ theo ATR, theo đáy swing), biết tại giá đóng cửa phiên `t`, có hiệu lực từ phiên `t+1`. Cách này tránh nhìn trước tương lai: mức dừng của phiên `t+1` không được tính từ giá cao/thấp của chính phiên `t+1`. - `breakeven_trigger_pct`: giá hoà vốn tính cả phí mua, phí bán và thuế bán 0,1%, không phải đúng giá vào — dời về đúng giá vào vẫn còn lỗ phí và thuế. - `take_profit_levels`: mỗi mức bán `qty_pct` khối lượng **đã mua ban đầu** khi lãi đạt `pct`, làm tròn theo lô; các mức phải xếp theo `pct` tăng dần và tổng `qty_pct` không vượt 1. Mức cuối của một kế hoạch đủ 100% bán hết phần còn lại. Mỗi mức khớp tạo một lệnh riêng, `exit_reason` dạng `take_profit_1`, `take_profit_2`, ... - `max_holding_bars`: thoát ở giá mở cửa ngay sau khi giữ đủ số phiên này, không cần chờ tín hiệu hay chạm mức dừng. - `same_bar_priority` (xem [Chế độ khớp lệnh](/docs/vnstock_quant/free/backtest/che-do-khop-lenh)) quyết định thứ tự khi một phiên chạm cả mức dừng và mức chốt lời. --- ## Nhiều lô và pyramiding Mặc định mỗi mã chỉ giữ một lô. Đặt `pyramiding` lớn hơn 1 để tín hiệu vào cùng chiều, khi đang giữ vị thế, mở thêm một lô mới thay vì bị bỏ qua: ```python # entries có hai điểm mua (ví dụ bar 10 và bar 40); tags đặt "lan_1"/"lan_2" tương ứng res = bt.run(df, entries=entries, exits=exits, tags=tags, pyramiding=2) # exits ở bar 60 chỉ thoát lô "lan_1", lô còn lại tiếp tục giữ exit_tags = [None] * len(df) exit_tags[60] = "lan_1" res = bt.run(df, entries=entries, exits=exits, tags=tags, exit_tags=exit_tags, pyramiding=2) ``` - Mỗi lô giữ giá vào, phí, khối lượng và lịch thanh toán T+2.5 riêng. Mức dừng lỗ, chốt lời và giá trị tài khoản tính theo **giá vốn bình quân** của các lô đang mở, giống cách công ty chứng khoán hiển thị. - Lệnh thoát bán theo thứ tự **vào trước ra trước (FIFO)**: mỗi lô bán ra một dòng riêng trong `trades`, không gộp chung. - `tags` gắn nhãn cho từng lệnh vào; `exit_tags` cho tín hiệu thoát chỉ bán các lô mang đúng nhãn đó (ví dụ "chỉ thoát lô mua lần hai"), bỏ trống thì thoát theo FIFO trên mọi lô. - `open_positions` có một dòng cho mỗi lô còn mở, không gộp theo mã. --- ## Chặn rủi ro cấp tài khoản ```python res = bt.run( df, sigs, account_guard={"max_drawdown_pct": 0.2, "max_loss_streak": 5, "close_positions": False}, ) print(res.summary()["halted_on"]) ``` `account_guard` xét ở cuối mỗi phiên, trên tài sản tính theo giá đóng cửa và trên các lệnh đã đóng tới phiên đó: - `max_drawdown_pct`: dừng khi tài sản sụt quá tỷ lệ này so với đỉnh. - `max_loss_streak`: dừng khi có đủ số lệnh lỗ liên tiếp. - Khi kích hoạt: hủy mọi lệnh đang chờ, từ chối (`ACCOUNT_HALTED`) mọi lệnh vào sau thời điểm đó, và nếu `close_positions=True` thì xếp lệnh bán hết vị thế đang mở ở giá mở cửa phiên sau (vẫn chịu khóa sàn và chờ T+2.5 như lệnh thường). - Phiên kích hoạt ghi ở `res.summary()["halted_on"]` (`None` nếu chưa từng kích hoạt). --- ## Đọc kết quả `run` trả một `BacktestResult`: | Thuộc tính / hàm | Nội dung | | :--- | :--- | | `summary()` / `tear_sheet` | Bảng tổng hợp: lợi nhuận, rủi ro, thống kê lệnh, bộ đếm lệnh bị chặn, cảnh báo | | `trades` / `trades_df()` | Danh sách lệnh đã đóng, một dòng cho mỗi lô bán ra | | `rejected_orders` | Lệnh không khớp được và lý do | | `open_positions` | Vị thế còn mở ở phiên cuối, một dòng cho mỗi lô | | `equity_curve` / `equity_df()` | Trạng thái tài khoản từng phiên | | `daily_returns` | Lợi suất theo phiên, dùng cho Monte Carlo và Deflated Sharpe | | `final_equity` | Tổng tài sản cuối kỳ | | `warnings` | Cảnh báo về giả định: đơn vị giá, khớp ở giá đóng cửa, phiên giao dịch ngoài biên độ tính từ giá tham chiếu, vị thế còn mở ở phiên cuối | ### Tear sheet | Nhóm | Trường | | :--- | :--- | | Lợi nhuận | `final_equity`, `net_profit`, `total_return_pct`, `cagr_pct`, `buy_hold_return_pct` (mua-giữ chính mã đó, trước phí và cổ tức; `None` với danh mục) | | Rủi ro | `annual_volatility_pct`, `sharpe_ratio`, `sortino_ratio`, `calmar_ratio`, `omega_ratio`, `max_drawdown_pct`, `intrabar_max_drawdown_pct`, `max_runup_pct`, `max_drawdown_duration_bars`, `max_drawdown_recovery_bars`, `ulcer_index`, `recovery_factor` | | Lệnh | `total_trades`, `winning_trades`, `losing_trades`, `win_rate_pct`, `gross_profit`, `gross_loss`, `profit_factor`, `payoff_ratio`, `expectancy`, `sqn`, `avg_holding_bars`, `exposure_pct`, `largest_win`, `largest_loss`, `max_consecutive_wins`, `max_consecutive_losses`, `avg_bars_winning`, `avg_bars_losing`, `avg_mfe_pct`, `avg_mae_pct` | | Chi phí | `total_commission`, `total_tax`, `total_dividends` | | Ma sát thị trường | `limit_up_blocked_buys`, `limit_down_blocked_sells`, `t2_blocked_sells`, `insufficient_cash_entries` | | Khác | `open_positions` (số lô còn mở), `open_unrealized_pnl`, `halted_on`, `rebalance_count`, `warnings`, `quant_risk_metrics` | `quant_risk_metrics` là các thước đo rủi ro tính bằng `vnstock_quant`: `skew`, `kurtosis`, `var_historical`, `var_normal`, `var_cornish_fisher`, `cvar_historical`, `cvar_normal`, `downside_deviation`, `stability`, `limit_hit_ratio`, `zero_return_ratio` và các thước đo ở trên dưới dạng số thập phân. `intrabar_max_drawdown_pct` tính sụt giảm theo giá thấp nhất trong phiên, nên luôn sâu hơn hoặc bằng `max_drawdown_pct` (tính theo giá đóng cửa). `max_runup_pct` là mức tăng lớn nhất của tài sản (theo giá đóng cửa) từ một đáy trước đó. `max_drawdown_duration_bars` là số phiên dài nhất tài sản nằm dưới đỉnh cũ; `max_drawdown_recovery_bars` là số phiên từ đáy sâu nhất quay lại đỉnh cũ (`None` nếu chưa hồi phục).

total_trades, win_rate_pct, profit_factor và các thống kê lệnh khác chỉ tính trên lệnh đã đóng. open_unrealized_pnl (lãi/lỗ của các lô còn mở, tính theo giá đóng cửa cuối) vẫn nằm trong net_profit và đường tài sản, nhưng không vào thống kê lệnh. Một vị thế đang lỗ nặng mà chưa có tín hiệu thoát sẽ không hiện trong total_trades — đọc cả open_positions trước khi kết luận từ thống kê lệnh. Còn vị thế mở ở phiên cuối thì res.warnings có một dòng nhắc.

Ví dụ tear sheet (chạy ngày 15/10/2026) Ví dụ ở trang [Giới thiệu](/docs/vnstock_quant/free/backtest/gioi-thieu), dữ liệu FPT từ 04/01/2021 tới 30/09/2026 (1.429 phiên, giá đã điều chỉnh), biểu phí `ssi`. Đây là kết quả chạy thử để minh hoạ cấu trúc đầu ra, không phải dự báo. ```text total_return_pct 6.85 max_drawdown_pct -7.15 total_trades 2 win_rate_pct 50.0 total_commission 571657.5 total_tax 194360.0 exposure_pct 4.97 warnings ['Giá có trung vị 61.43 nên được hiểu là nghìn đồng ...'] ```
### Lệnh đã đóng Mỗi phần tử của `trades` là một lô đã bán: `symbol`, `side` (`long`/`short`), `entry_date`, `entry_price`, `exit_date`, `exit_price`, `quantity`, `gross_pnl`, `entry_fee`, `exit_fee`, `exit_tax`, `funding_cost`, `net_pnl`, `return_pct`, `holding_bars`, `holding_days`, `exit_reason`, `tag`, `mfe_pct`, `mae_pct`. `mfe_pct`/`mae_pct` (biên độ thuận lợi/bất lợi, *maximum favourable/adverse excursion*) là mức lãi/lỗ tốt nhất và xấu nhất mà giá đạt được trong lúc giữ lô, tính theo % giá vào — kể cả khi lệnh cuối cùng thoát ở mức khác. `exit_reason`: | Giá trị | Ý nghĩa | | :--- | :--- | | `signal_exit` | Thoát theo tín hiệu | | `stop_loss`, `take_profit`, `trailing_stop` | Chạm điểm dừng | | `breakeven_stop` | Chạm điểm dừng đã dời về giá hoà vốn (`breakeven_trigger_pct`) | | `dynamic_stop` | Chạm mức dừng tự tính ở cột `exit_stop` | | `take_profit_1`, `take_profit_2`, ... | Chạm một mức trong `take_profit_levels` (đánh số theo thứ tự khai) | | `time_exit` | Thoát vì giữ đủ `max_holding_bars` phiên | | `rebalance` | Bán bớt để tái cân bằng về tỷ trọng mục tiêu (xem [Danh mục, tối ưu và chống quá khớp](/docs/vnstock_quant/backtest/danh-muc-va-toi-uu)) | | `account_halt` | Bán hết vì `account_guard` đã kích hoạt (`close_positions=True`) | | `..._delayed_by_floor_lock` | Lệnh thoát bị hoãn vì phiên khóa sàn, khớp ở phiên đầu tiên bán được | | `..._delayed_by_settlement` | Lệnh thoát bị hoãn vì cổ phiếu chưa về tài khoản (T+2.5) | Giá trong lệnh tính theo đồng sau khi quy đổi đơn vị. ### Vị thế còn mở Mỗi phần tử của `open_positions` là một lô chưa bán hết: `symbol`, `side`, `entry_bar`, `entry_date`, `entry_price`, `quantity`, `mark_price`, `mark_date` (giá và ngày đóng cửa phiên cuối, dùng để đánh giá), `holding_bars`, `unrealized_pnl` (đã trừ phí mua, chưa trừ phí bán và thuế bán), `return_pct`. ```python table = res.trades_df(include_open=True) # nối open_positions vào bảng lệnh, cột status="open"/"closed" ``` `trades_df(include_open=True)` thêm các lô còn mở vào cuối bảng, đánh giá ở giá đóng cửa phiên cuối (`exit_reason="open"`), kèm cột `status`. Thống kê trong `summary()` luôn chỉ tính lệnh đã đóng, không đổi theo tham số này. ### Lệnh bị chặn Mỗi phần tử của `rejected_orders`: `symbol`, `date`, `side`, `reason_code`, `message`. | `reason_code` | Ý nghĩa | | :--- | :--- | | `LIMIT_UP_LOCKED` | Lệnh vào vị thế mua rơi vào phiên khóa trần, không có người bán; lệnh bị bỏ, không chuyển sang phiên sau | | `LIMIT_DOWN_LOCKED` | Lệnh bán rơi vào phiên khóa sàn, không có người mua; lệnh được giữ lại cho phiên sau | | `T2_SETTLEMENT_LOCKED` | Cổ phiếu mua chưa về tài khoản; lệnh được giữ lại tới phiên bán được | | `SHARES_NOT_LISTED` | Cổ phiếu thưởng hoặc cổ phiếu mua theo quyền chưa tới ngày niêm yết; lệnh chờ tới ngày đó, không tính vào `t2_blocked_sells` | | `INSUFFICIENT_CASH` | Không đủ tiền cho một lô sau phí | | `NO_STOP_FOR_RISK_SIZING` | Tính khối lượng theo `risk_per_trade_pct` nhưng không có `stop_loss_pct` hay `exit_stop` nằm phía lỗ của giá vào | | `RIGHTS_CASH_LIMITED` | Thực hiện quyền mua nhưng tiền mặt không đủ mua hết số quyền được hưởng; mua được bao nhiêu hay bấy nhiêu | | `ACCOUNT_HALTED` | `account_guard` đã kích hoạt; lệnh vào bị bỏ | --- ## Biểu đồ ```python res.plot(output_path="fpt.png") # ảnh tĩnh: nến, điểm vào/ra, đường vốn, sụt giảm html = res.plot_html(output_html="fpt.html") # trang HTML tương tác (tuỳ chọn) ``` `plot()` cần [`vnstock_chart`](/docs/vnstock-chart) (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) và chỉ có cho backtest một mã. Ảnh tĩnh phù hợp khi trợ lý AI cần đọc lại kết quả, hoặc khi bạn chèn vào báo cáo. --- ## Document: Chế độ khớp lệnh và đối chứng > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Hai thư viện backtest chạy cùng một chiến lược trên cùng dữ liệu vẫn có thể ra hai kết quả khác nhau. Lý do không phải một bên tính sai, mà là mỗi bên chọn một giả định khác nhau cho những câu hỏi như: lệnh khớp ở giá nào, cắt lỗ xét theo giá thấp nhất hay giá đóng cửa, khối lượng tính theo giá nào. `vnstock_quant.backtest` gom mọi lựa chọn đó vào tham số `execution`. Mỗi chế độ là một bộ lựa chọn có tên. ## Các chế độ có sẵn | `execution` | Dùng khi | Luật thị trường VN | | :--- | :--- | :--- | | `vn_realistic` (mặc định) | Backtest cổ phiếu Việt Nam | có | | `frictionless` | Thử nhanh ý tưởng, không lô, không biên độ, không T+ | không | | `backtesting_py` | So kết quả với backtesting.py | không | | `backtrader` | So kết quả với backtrader | không | | `vectorbt` | So kết quả với vectorbt (`Portfolio.from_signals`) | không | | `zipline` | So kết quả với zipline-reloaded | không | | `lean` | Gần với QuantConnect Lean, **chưa đối chứng** | không | `bt.list_presets()` trả đủ các lựa chọn của từng chế độ. Truyền `execution` dạng `dict` để sửa một lựa chọn: ```python res = bt.run(df, sigs, execution={"preset": "vn_realistic", "stop_trigger": "close"}) ``` ## Các lựa chọn | Khoá | Giá trị | Ý nghĩa | | :--- | :--- | :--- | | `timing` | `next_open`, `next_close`, `same_close` | Tín hiệu phiên `t` khớp ở giá mở cửa phiên `t+1`, giá đóng cửa phiên `t+1`, hay giá đóng cửa chính phiên `t`. `same_close` có cảnh báo nhìn trước tương lai | | `market_rules` | `true`, `false` | Áp lô, bước giá, biên độ, khóa trần/sàn, chu kỳ thanh toán | | `stop_trigger` | `intrabar`, `close` | Cắt lỗ kích hoạt khi giá thấp nhất chạm mức, hay khi giá đóng cửa vượt mức | | `stop_fill` | `gap_aware`, `at_level` | Giá khớp của cắt lỗ: tại mức đặt, hoặc tại giá mở cửa nếu phiên mở cửa đã vượt qua mức đó; hay luôn tại mức đặt | | `same_bar_priority` | `stop_first`, `target_first`, `ohlc_path` | Phiên chạm cả mức cắt lỗ và mức chốt lời thì giả định cái nào xảy ra trước. `ohlc_path` suy ra thứ tự từ khoảng cách giá mở cửa tới giá cao/thấp trong phiên (cách TradingView giả định), chỉ nên dùng để so sánh | | `stops_on_entry_bar` | `true`, `false` | Xét cắt lỗ ngay trong phiên vào lệnh | | `trail_reference` | `prior_highs`, `include_current_high`, `prior_closes` | Đỉnh dùng cho cắt lỗ đuổi. `include_current_high` lạc quan: lấy cả giá cao của chính phiên đang xét | | `sizing_price` | `fill_price`, `signal_close` | Tính khối lượng theo giá khớp, hay theo giá đóng cửa phiên phát tín hiệu | | `reserve_fees` | `true`, `false` | Chừa tiền cho phí khi tính khối lượng | | `enforce_cash` | `true`, `false` | Không cho mua vượt tiền mặt | | `check_cash_at_signal` | `true`, `false` | Kiểm tiền cả lúc phát tín hiệu, không chỉ lúc khớp | | `signal_conflict` | `exit_wins`, `ignore_both` | Phiên có cả tín hiệu vào và thoát | | `cash_buffer_pct` | số | Tỷ lệ tiền mặt luôn để dành | | `use_unsettled_proceeds` | `true`, `false` | Dùng tiền bán chưa về để mua | `vn_realistic` chọn hướng thận trọng ở mọi chỗ có thể chọn: khớp ở giá mở cửa phiên sau, cắt lỗ xét theo giá thấp nhất, giá khớp tính cả khoảng trống giá, ưu tiên cắt lỗ khi một phiên chạm cả hai mức, đỉnh của cắt lỗ đuổi chỉ lấy từ các phiên trước, chừa tiền cho phí, không dùng tiền chưa về. ## Những khác biệt đáng biết giữa các thư viện Ba khác biệt dưới đây chỉ lộ ra khi chạy song song các thư viện trên cùng kịch bản: - **zipline** xét cắt lỗ theo giá đóng cửa và khớp ở giá đóng cửa phiên sau. Chiến lược có cắt lỗ chặt thường ra kết quả khác hẳn so với thư viện xét theo giá thấp nhất. - **vectorbt** (`from_signals`) bỏ cả tín hiệu vào lẫn tín hiệu thoát khi hai tín hiệu rơi vào cùng một phiên. Các thư viện khác thường cho tín hiệu thoát thắng. - **backtrader** kiểm tiền hai lần: lúc tạo lệnh theo giá đóng cửa phiên phát tín hiệu, và lúc khớp. Phiên sau mở cửa cao hơn thì lệnh có thể bị từ chối dù lúc phát tín hiệu vẫn đủ tiền. ## Đối chứng Mỗi chế độ đối chứng được kiểm bằng 11 kịch bản chung: - khối lượng cố định, không phí và có phí; - khoảng trống giá xuyên qua mức cắt lỗ, và xuyên qua mức chốt lời; - một phiên chạm cả mức cắt lỗ lẫn mức chốt lời; - cắt lỗ ngay trong phiên vào lệnh; - khối lượng theo tỷ lệ tài sản, có phí và không phí; - tín hiệu vào khi đang giữ vị thế; - cắt lỗ đuổi; - giao cắt đường trung bình trên một chuỗi giá ngẫu nhiên. Mỗi kịch bản chạy trên thư viện gốc, rồi chạy lại bằng `vnstock_quant.backtest` ở chế độ tương ứng với `profile="frictionless"` và cùng mức phí. Kết quả ngày 14/10/2026: | Thư viện tham chiếu | Bản | Kết quả | | :--- | :--- | :--- | | backtesting.py | 0.6.6 | khớp 11/11 | | backtrader | 1.9.78.123 | khớp 11/11 | | vectorbt | 1.1.2 | khớp 11/11 | | zipline-reloaded | 3.1.1 | khớp 11/11 | "Khớp" nghĩa là cùng số lệnh, cùng ngày và giá vào/ra, và đường vốn từng phiên lệch không quá 0,000001. QuantConnect Lean chưa đối chứng, nên chế độ `lean` chỉ là xấp xỉ. Để so với thư viện bạn đang dùng: ```python res = bt.run(df, sigs, profile="frictionless", fee=0.001, execution="backtrader") ``` TradingView và Amibroker chưa có chế độ đối chứng. Kết quả của hai công cụ này phụ thuộc cài đặt trong Strategy Tester và Analysis, không tự động tái tạo được. Gọi `execution="tradingview"` hay `"amibroker"` sẽ báo lỗi `QUANT_INVALID_PARAMETER` kèm danh sách chế độ đã đối chứng. --- ## Document: Dữ liệu và tín hiệu > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Thư viện tách phần **sinh tín hiệu** khỏi phần **khớp lệnh**. Bạn quyết định khi nào vào và khi nào thoát; thư viện quyết định lệnh khớp ở giá nào, có khớp được không, và phí bao nhiêu. ## Dữ liệu đầu vào `data` là một `pandas.DataFrame` hoặc danh sách `dict`, mỗi dòng một phiên, xếp từ cũ tới mới. | Cột | Bắt buộc | Ghi chú | | :--- | :--- | :--- | | `time` / `date` / `datetime` | có | Ngày phiên, dạng `YYYY-MM-DD` hoặc kiểu ngày giờ. Nếu ngày nằm ở chỉ mục của DataFrame thì thư viện tự lấy ra | | `open`, `high`, `low`, `close` | có | Giá. Kết quả của `vnstock` (`Market().equity(...).ohlcv(...)`) dùng được ngay | | `volume` | không | Mặc định 0 | | `reference_price` | không | Giá tham chiếu của phiên. Không có thì lấy giá đóng cửa phiên trước để tính biên độ | Thiếu cột ngày là lỗi `QUANT_INPUT_DATA`: thư viện không tự sinh ngày. --- ## Ba cách đưa tín hiệu vào ### 1. Mảng `[-1, 0, 1]` ```python sigs = [0] * len(df) sigs[20], sigs[45] = 1, -1 # vào ở tín hiệu phiên 20, thoát ở tín hiệu phiên 45 res = bt.run(df, sigs, symbol="FPT") ``` `1` là vào vị thế mua, `-1` là thoát. Trên hồ sơ cho phép bán khống (`vn_futures`, `crypto_perp`), `-1` còn mở vị thế bán và `1` đóng nó. ### 2. Cặp `entries` / `exits` ```python ma20 = df["close"].rolling(20).mean() res = bt.run( df, entries=(df["close"] > ma20).tolist(), exits=(df["close"] < ma20).tolist(), symbol="FPT", ) ``` Có thêm `short_entries`, `short_exits` cho hồ sơ cho phép bán khống. `tags` là danh sách nhãn theo phiên; nhãn được chép sang lệnh mở ở phiên đó. Khi đang giữ nhiều lô cùng mã (`pyramiding` > 1), `exit_tags` cho biết tín hiệu thoát ở một phiên chỉ nhắm vào lô mang nhãn nào — xem mục nhiều lô ở trang [Chạy backtest và đọc kết quả](/docs/vnstock_quant/free/backtest/chay-backtest). Ba cách trên quyết định **khi nào**. Mức giá của lệnh giới hạn, lệnh dừng và mức dừng lỗ đổi theo từng phiên lại là tín hiệu riêng, theo phiên: `entry_limit`, `entry_stop`, `exit_stop`. Chi tiết ở trang [Chạy backtest và đọc kết quả](/docs/vnstock_quant/free/backtest/chay-backtest). ### 3. Bảng quy tắc `rule_dsl` Bảng quy tắc là một `dict` phẳng, được tính trong lõi Rust với các chỉ báo của `vnstock_quant`. Đây là cách nên dùng khi bạn hay trợ lý AI mô tả chiến lược bằng lời. ```python dsl = { "entry_logic": "all", "entry_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}, {"left": "close", "op": "gt", "right": {"ind": "sma", "params": {"length": 200}}}, ], "exit_logic": "any", "exit_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}, {"left": {"ind": "macd", "output": "MACDh"}, "op": "cross_below", "right": 0}, ], } res = bt.run(df, rule_dsl=dsl, symbol="FPT") ``` **Toán hạng** (`left`, `right`): | Dạng | Ví dụ | Ý nghĩa | | :--- | :--- | :--- | | Số | `30` | Hằng số, theo đúng đơn vị dữ liệu bạn đưa vào (nghìn đồng nếu dữ liệu từ `vnstock`) | | Tên cột | `"close"`, `"volume"` | Một cột của dữ liệu, hoặc cột bạn thêm qua `feature_columns` | | Cột lùi phiên | `{"col": "close", "shift": 1}` | Giá trị của cột ở `shift` phiên trước. `shift` không nhận số âm | | Chỉ báo | `{"ind": "sma", "params": {"length": 50}}` | Một chỉ báo trong `bt.list_indicators()` | | Chỉ báo nhiều cột | `{"ind": "bbands", "params": {"length": 20}, "output": "BBU"}` | Chọn một cột đầu ra theo tên hoặc tiền tố | | Chỉ báo trên cột khác | `{"ind": "sma", "params": {"length": 20}, "source": "volume"}` | Tính chỉ báo trên `volume` thay cho `close` | Chỉ báo cũng nhận `shift`, ví dụ `{"ind": "rsi", "params": {"length": 14}, "shift": 1}`. **Phép so sánh** (`op`): `gt`, `gte`, `lt`, `lte`, `eq`, `cross_above`, `cross_below`. `cross_above` đúng ở phiên `left` vượt lên trên `right`, tức phiên trước `left <= right` và phiên này `left > right`. **Cách gộp điều kiện:** | Khoá | Mặc định | Giá trị | | :--- | :--- | :--- | | `entry_logic`, `short_entry_logic` | `"all"` | `"all"`, `"any"`, hoặc `{"vote_at_least": k}` (ít nhất `k` điều kiện đúng) | | `exit_logic`, `short_exit_logic` | `"any"` | Như trên | Bảng quy tắc cần ít nhất một điều kiện vào lệnh. `short_entry_rules`, `short_exit_rules` chỉ dùng trên hồ sơ cho phép bán khống. Trong giai đoạn chỉ báo chưa đủ dữ liệu khởi động, điều kiện được tính là sai. **Xem trước tín hiệu** mà không chạy backtest: ```python sig = bt.eval_rule_dsl(dsl, df) print(sum(sig["entries"]), sum(sig["exits"])) ``` ### Danh sách chỉ báo `bt.list_indicators()` trả 56 chỉ báo, mỗi mục có `name`, `group`, `inputs`, `params` (tên, kiểu, mặc định), `title` và `access`: - `access: "bt_basic"`: dùng được ở mọi cấp, gồm 10 chỉ báo `sma`, `ema`, `rsi`, `macd`, `stoch`, `bbands`, `atr`, `obv`, `vwap`, `pivots`; - `access: "bt"`: cần cấp Bronze trở lên. Bảng quy tắc dùng một chỉ báo chưa mở cho cấp của bạn thì bị từ chối (`QUANT_TIER_REQUIRED`) trước khi chạy, không bị trừ lượt. | Nhóm | Chỉ báo | | :--- | :--- | | Xu hướng | `sma`, `ema`, `wma`, `hma`, `smma`, `alma`, `vwma`, `adx`, `psar`, `supertrend`, `dm`, `linreg`, `aroon` | | Động lượng | `rsi`, `stoch`, `stochrsi`, `mom`, `roc`, `ao`, `cci`, `willr`, `tsi`, `cmo`, `uo`, `fisher`, `cg`, `kst`, `macd` | | Biến động | `bbands`, `kc`, `atr`, `stdev`, `donchian`, `massi`, `ui`, `squeeze`, `squeeze_pro`, `true_range` | | Khối lượng | `obv`, `cmf`, `ad`, `vwap`, `pvo`, `efi`, `eom`, `nvi`, `mfi` | | Thống kê | `pivots`, `mad`, `variance`, `hl2`, `hlc3`, `ohlc4`, `midprice`, `decreasing`, `increasing` | Hai chỉ báo của `vnstock_quant` không dùng được trong bảng quy tắc: - `ichimoku` dịch đường mây về phía trước, nên giá trị tại phiên `t` đọc dữ liệu sau `t`; - `vp` không trả một giá trị cho mỗi phiên. Gọi chúng thì báo `QUANT_CAUSALITY_VIOLATION`. --- ## Kiểm tra thiên lệch nhìn trước tương lai Một tín hiệu tại phiên `t` chỉ được dùng dữ liệu tới hết phiên `t`. Cách kiểm của thư viện: tính tín hiệu trên toàn bộ dữ liệu, rồi tính lại trên dữ liệu đã cắt ở 5 điểm (50%, 62%, 75%, 87%, 95% số phiên). Nếu tín hiệu ở một phiên trước điểm cắt thay đổi, hàm tín hiệu đã đọc dữ liệu tương lai. **Hàm tín hiệu Python của bạn:** ```python def signal_fn(d): up_tomorrow = d["close"].shift(-1) > d["close"] # đọc giá ngày mai return up_tomorrow.astype(int).where(up_tomorrow, -1).tolist() report = bt.check_causality(signal_fn, df) print(report["passed"], report["mismatch_bars"]) ``` `signal_fn(data)` trả mảng `[-1, 0, 1]`, tuple `(entries, exits)` hoặc `dict`. Kết quả gồm `passed`, `mismatch_bars` (vị trí phiên bị đổi tín hiệu), `cuts` và `message`. Ví dụ trên báo không đạt. Lỗi hay gặp: - `shift(-1)`; - cửa sổ trượt đặt giữa (`center=True`); - chuẩn hoá trên toàn mẫu (trừ trung bình, chia độ lệch chuẩn của cả chuỗi). **Bảng quy tắc:** ```python report = bt.check_rule_dsl_causality(dsl, df) ``` Mặc định `execution="vn_realistic"`: tín hiệu tính ở giá đóng cửa phiên `t` khớp ở giá mở cửa phiên `t+1`. Đổi sang khớp ở giá đóng cửa của chính phiên `t` (`execution_timing="same_close"`) là giả định lạc quan; chỉ dùng khi bạn biết rõ mình đang mô phỏng điều gì. --- ## Document: Chạy thử chiến lược > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.backtest` giúp bạn kiểm thử một ý tưởng nghiên cứu trên dữ liệu giá bạn tự truy xuất, ví dụ bằng `vnstock`. Bạn mô tả khi nào vào và khi nào thoát vị thế. Thư viện mô phỏng lại quá trình khớp lệnh từng phiên rồi trả về lịch sử lệnh, đường vốn và các thước đo rủi ro. Các phép tính backtest chạy trên máy của bạn. Bảng quy tắc hỗ trợ 56 chỉ báo được liệt kê ở trang [Dữ liệu và tín hiệu](/docs/vnstock_quant/free/backtest/du-lieu-va-tin-hieu); báo cáo kết quả dùng các thước đo rủi ro của `vnstock_quant`. Thư viện khác các công cụ backtest phổ biến ở bốn điểm: - **Không phải viết vòng lặp hay lớp chiến lược.** Bạn đưa vào một mảng tín hiệu `[-1, 0, 1]`, một cặp `entries`/`exits`, hoặc một bảng quy tắc dạng `dict` (`rule_dsl`) dùng các chỉ báo của `vnstock_quant`: 10 chỉ báo ở bản Cộng đồng, 56 chỉ báo từ cấp Bronze. Bảng quy tắc cũng có thể được trợ lý AI tạo từ mô tả bằng lời để bạn kiểm tra và điều chỉnh. - **Luật thị trường Việt Nam là mặc định:** - lô 100 cổ phiếu; - bước giá theo từng sàn; - biên độ ±7%, ±10%, ±15%; - phiên khóa sàn không bán được; - cổ phiếu mua ngày T bán được từ phiên chiều T+2; - thuế bán 0,1% tính riêng, ngoài phí giao dịch. - **Kiểm tra thiên lệch nhìn trước tương lai (lookahead bias).** Thư viện chạy lại tín hiệu trên dữ liệu đã cắt bớt phần sau. Phiên nào có tín hiệu đổi khi bỏ dữ liệu tương lai thì được báo ra. - **Đối chứng được với thư viện khác.** Các chế độ `backtesting_py`, `backtrader`, `vectorbt` và `zipline` cho phép so sánh theo cùng giả định khớp lệnh. Kết quả của 11 kịch bản kiểm thử và điều kiện đối chứng được ghi tại trang [Chế độ khớp lệnh](/docs/vnstock_quant/free/backtest/che-do-khop-lenh). Mô-đun còn có: - **Nhiều lô trong một vị thế (pyramiding)** và **tái cân bằng danh mục theo tỷ trọng mục tiêu**, cả hai đều tính đúng chu kỳ thanh toán T+2.5 cho từng lô. - **Lệnh giới hạn, lệnh dừng theo từng phiên**, nhiều mức chốt lời từng phần, dừng lỗ về hoà vốn, cắt lỗ đuổi có mức kích hoạt. - **Quyền mua cổ phiếu** (`rights_issue`) bên cạnh cổ tức tiền và cổ phiếu thưởng; giá tham chiếu ngày giao dịch không hưởng quyền tính đúng công thức của sở, không bị hiểu nhầm thành phiên khóa sàn. - **Chặn rủi ro cấp tài khoản**: ngừng mở vị thế mới khi sụt giảm hoặc chuỗi lệnh lỗ vượt ngưỡng bạn đặt. Chi tiết từng tính năng ở các trang tương ứng; mốc thời gian ở [Lịch sử phiên bản](/docs/vnstock_quant/free/lich-su-phien-ban).

Kết quả backtest chỉ phản ánh dữ liệu và giả định bạn đã dùng: biểu phí, cách khớp lệnh, cách tính khối lượng. Nó không phải lợi nhuận kỳ vọng, và thư viện không đưa ra khuyến nghị đầu tư.

--- ## Bắt đầu trong ba bước **1. Cài đặt.** `vnstock_quant` từ bản 0.5.0 đã có sẵn mô-đun này; xem [Cài đặt và thiết lập](/docs/vnstock_quant/free/bat-dau/cai-dat-va-thiet-lap). ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[vnstock]" ``` **2. Kiểm tra cấp quyền.** Lệnh này không trừ lượt dùng thử: ```python import vnstock_quant as vq print(vq.entitlement()["tier"], vq.entitlement()["backtest"]) ``` **3. Chạy một backtest.** Ví dụ: vào khi RSI(14) cắt lên 30 và giá đóng cửa trên SMA(200); thoát khi RSI(14) vượt 70; cắt lỗ 7%. ```python from vnstock import Market from vnstock_quant import backtest as bt df = Market().equity("FPT").ohlcv(start="2021-01-01", end="2026-09-30") res = bt.run( df, rule_dsl={ "entry_rules": [ {"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}, {"left": "close", "op": "gt", "right": {"ind": "sma", "params": {"length": 200}}}, ], "exit_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}], }, symbol="FPT", profile="vn_hose", broker="ssi", stop_loss_pct=0.07, ) print(res.summary()["total_return_pct"], res.summary()["max_drawdown_pct"]) print(res.trades_df()) ``` `vnstock` báo giá cổ phiếu theo nghìn đồng. Thư viện tự nhận ra và quy về đồng trước khi áp bước giá, biên độ. Việc quy đổi này được ghi trong `res.warnings`. --- ## Đọc theo thứ tự này | Trang | Bạn sẽ làm được | | :--- | :--- | | [Dữ liệu và tín hiệu](/docs/vnstock_quant/free/backtest/du-lieu-va-tin-hieu) | Đưa dữ liệu vào, viết tín hiệu bằng mảng hoặc bảng quy tắc, kiểm tra nhìn trước tương lai | | [Chạy backtest và đọc kết quả](/docs/vnstock_quant/free/backtest/chay-backtest) | Gọi `run`, chọn cách tính khối lượng và điểm dừng, đọc tear sheet, vẽ biểu đồ | | [Luật thị trường, phí và sự kiện](/docs/vnstock_quant/free/backtest/luat-thi-truong-va-phi) | Chọn hồ sơ thị trường, biểu phí, đơn vị giá; khai cổ tức và kịch bản sốc | | [Chế độ khớp lệnh và đối chứng](/docs/vnstock_quant/free/backtest/che-do-khop-lenh) | Hiểu khác biệt giữa các thư viện backtest, so kết quả với thư viện bạn đang dùng | | [Danh mục, tối ưu và chống quá khớp](/docs/vnstock_quant/backtest/danh-muc-va-toi-uu) | Chạy nhiều mã chung một tài khoản, tái cân bằng theo tỷ trọng, dò tham số, walk-forward, Monte Carlo, Deflated Sharpe | | [Cấp quyền và xử lý lỗi](/docs/vnstock_quant/free/backtest/cap-quyen-va-xu-ly-loi) | Biết mỗi cấp chạy được bao nhiêu, đọc mã lỗi và cách xử lý | | [Lịch sử phiên bản](/docs/vnstock_quant/free/lich-su-phien-ban) | Các mốc cập nhật của `vnstock_quant`, gồm phần backtest | --- ## Thư viện không làm gì - **Không truy xuất dữ liệu.** Bạn tự lấy dữ liệu giá (ví dụ bằng `vnstock`) rồi đưa vào. Thư viện chỉ tính toán trên dữ liệu đó. - **Không kết nối tài khoản, không gửi lệnh tới bất kỳ đâu.** Mọi lệnh trong backtest là lệnh giả lập trên dữ liệu lịch sử. - **Không mô phỏng giao dịch ký quỹ cổ phiếu (margin)** ở bản này. Phái sinh và bán khống crypto vẫn tính ký quỹ ban đầu như tiền đặt cọc hợp đồng. - **Không kèm kịch bản sự kiện nào của doanh nghiệp thật.** Kịch bản sốc do bạn tự khai và chỉ áp khi bạn truyền vào. - **Không cam kết biểu phí.** Biểu phí của các công ty chứng khoán chỉ để tham khảo, mỗi mục ghi rõ đã xác minh hay chưa và mốc thời gian. Mức phí thực tế của bạn có thể khác. - **Không đưa ra khuyến nghị đầu tư.** Kết quả chạy thử không phải dự báo. --- ## Document: Luật thị trường, phí và sự kiện > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Hồ sơ thị trường `profile` quyết định lô, bước giá, biên độ, chu kỳ thanh toán và thuế bán. `bt.list_profiles()` trả đủ trường của từng hồ sơ. | `profile` | Thị trường | Lô | Biên độ | Thanh toán | Thuế bán | Bán khống | | :--- | :--- | ---: | ---: | :--- | ---: | :--- | | `vn_hose` | Cổ phiếu HOSE | 100 | ±7% | T+2.5 | 0,1% | không | | `vn_hnx` | Cổ phiếu HNX | 100 | ±10% | T+2.5 | 0,1% | không | | `vn_upcom` | Cổ phiếu UPCoM | 100 | ±15% | T+2.5 | 0,1% | không | | `vn_futures` | Hợp đồng tương lai VN30F | 1 hợp đồng, hệ số 100.000 | ±7% | T+0 | 0 | có, ký quỹ ban đầu 17% | | `crypto_spot` | Crypto giao ngay | 0,0001 | không | T+0 | 0 | không | | `crypto_perp` | Crypto hợp đồng vĩnh cửu | 0,001 | không | T+0 | 0 | có, ký quỹ ban đầu 10% | | `global_equity` | Cổ phiếu quốc tế | 1 | không | T+0 | 0 | có | | `forex` | Ngoại hối | 0,01 lot, hệ số 100.000 | không | T+0 | 0 | có, ký quỹ 2% | | `frictionless` | Không luật thị trường, dùng để đối chứng | 1 | không | T+0 | 0 | không | Tên ngắn cũng được nhận: `hose`, `hnx`, `upcom`, `vn30f`, `futures`, `crypto`, `perp`, `us_equity`, `fx`. Sửa một trường mà không tạo hồ sơ mới: ```python res = bt.run(df, sigs, profile="vn_hose", profile_overrides={"settlement": "historical_vn"}) ``` --- ## Luật cổ phiếu Việt Nam ### Chu kỳ thanh toán - **`t2_5` (mặc định):** cổ phiếu mua ngày T bán được từ **phiên chiều T+2**. Lệnh bán ở phiên sáng T+2 chưa khớp; lệnh ở phiên đóng cửa T+2 thì khớp. Tiền bán về tài khoản theo cùng chu kỳ. - **`historical_vn`:** theo ngày giao dịch. Lệnh mua trước 25/08/2022 bán được từ mở cửa T+3, lệnh mua từ 25/08/2022 bán được từ phiên chiều T+2 (mốc theo quy định của Tổng công ty Lưu ký và Bù trừ chứng khoán Việt Nam). Dùng khi backtest trải dài qua năm 2022. - Các giá trị khác: `t0`, `t1`, `t2`, `t3`. Lệnh thoát rơi vào lúc cổ phiếu chưa về được giữ lại, khớp ở phiên đầu tiên bán được, và ghi `exit_reason` có đuôi `_delayed_by_settlement`. Mặc định, tiền bán chưa về không được dùng để mua. Muốn mô phỏng dịch vụ ứng trước tiền bán thì đặt `use_unsettled_proceeds=True`. ### Bước giá | Sàn | Giá dưới 10.000 đ | 10.000 đ đến dưới 50.000 đ | Từ 50.000 đ | | :--- | ---: | ---: | ---: | | HOSE | 10 đ | 50 đ | 100 đ | | HNX, UPCoM | 100 đ | 100 đ | 100 đ | Giá khớp được làm tròn theo bước giá về phía bất lợi cho bạn: lệnh mua làm tròn lên, lệnh bán làm tròn xuống. ### Biên độ, khóa trần và khóa sàn - Giá trần, giá sàn tính từ `reference_price` của phiên. Không có cột này thì dùng giá đóng cửa phiên trước. Kết quả làm tròn vào trong biên độ theo bước giá. - Giá khớp không vượt ra ngoài biên độ. - **Khóa sàn:** phiên có giá mở cửa, giá cao nhất và giá đóng cửa đều bằng giá sàn. Lệnh bán ở phiên này không khớp (`LIMIT_DOWN_LOCKED`) và được giữ lại tới phiên đầu tiên bán được, kể cả lệnh cắt lỗ. - **Khóa trần:** tương tự ở giá trần. Lệnh mua vào ở phiên này bị bỏ (`LIMIT_UP_LOCKED`). Khóa sàn là điểm kết quả backtest hay lệch nhất so với thực tế. Một lệnh cắt lỗ 7% gặp ba phiên khóa sàn liên tiếp có thể khớp ở mức lỗ hơn 20%. Thư viện backtest không có luật biên độ thì cho lệnh cắt lỗ đó khớp ngay ở phiên chạm mức đã đặt. Phiên giao dịch không hưởng quyền (GDKHQ) trên giá gốc không bị hiểu nhầm là khóa sàn: giá tham chiếu của phiên đó tính thẳng từ `corporate_actions` theo đúng công thức của sở (`(giá đóng cửa phiên trước − cổ tức tiền + giá phát hành × tỷ lệ quyền) / (1 + tỷ lệ cổ phiếu thưởng + tỷ lệ quyền mua)`), không lấy nguyên giá đóng cửa phiên trước. Nếu một phiên vẫn giao dịch ra ngoài biên độ tính từ giá tham chiếu (ví dụ bạn quên khai sự kiện quyền, hoặc dữ liệu có lỗi), thư viện bỏ áp biên độ và khóa trần/sàn cho đúng phiên đó, kèm cảnh báo trong `res.warnings` nêu rõ các phiên liên quan; `detect_limit_events` cũng bỏ qua các phiên này. **Liệt kê các phiên chạm trần, chạm sàn** trên dữ liệu của bạn: ```python events = bt.detect_limit_events(df, profile="vn_hose") # [{'bar_index': 18, 'date': '2021-01-28', 'reference_price': 24420.0, # 'limit_price': 22750.0, 'kind': 'closed_at_floor', 'volume': 5092400.0}, ...] ``` `kind` gồm `floor_lock` (cả phiên ở giá sàn), `closed_at_floor`, `ceiling_lock` (cả phiên ở giá trần), `closed_at_ceiling`. Giá trả về tính bằng đồng. ### Thuế bán Thuế bán 0,1% trên giá trị bán nằm trong hồ sơ cổ phiếu Việt Nam (`sell_tax_rate`), tính riêng với phí giao dịch. Đổi `fee` hay `broker` không làm mất thuế bán. Tổng thuế ghi ở `total_tax`, từng lệnh ở `exit_tax`. --- ## Đơn vị giá `vnstock` báo giá cổ phiếu theo **nghìn đồng**: `63.1` nghĩa là 63.100 đ. Bước giá và biên độ lại tính bằng đồng. | `price_unit` | Khi nào dùng | | :--- | :--- | | `"auto"` (mặc định) | Với hồ sơ cổ phiếu Việt Nam, nếu trung vị giá đóng cửa dưới 1.000 thì nhân 1.000. Việc quy đổi được ghi trong `res.warnings` | | `"thousand_vnd"` | Dữ liệu chắc chắn theo nghìn đồng | | `"vnd"` | Dữ liệu đã tính bằng đồng, không quy đổi | Tín hiệu luôn tính trên giá bạn đưa vào. Một điều kiện như `close > 50` trong `rule_dsl` vẫn hiểu là 50 nghìn đồng khi dữ liệu theo nghìn đồng. Giá trong `trades`, `equity_curve` và tear sheet tính bằng đồng. --- ## Phí giao dịch Ba cách khai phí: ```python bt.run(df, sigs, fee=0.0015) # 0,15% mỗi chiều bt.run(df, sigs, fee=(0.0015, 0.0020)) # mua 0,15%, bán 0,20% bt.run(df, sigs, broker="vps") # biểu phí tham khảo ``` `bt.list_brokers()` trả các biểu phí tham khảo. Mỗi mục có `id`, `name`, `buy_fee_rate`, `sell_fee_rate`, `min_fee`, `verified` và `as_of`: | `id` | Phí mỗi chiều | `verified` | `as_of` | | :--- | ---: | :--- | :--- | | `vps` | 0,13% | có | 2026 | | `ssi` | 0,15% | có | 2026 | | `vnd` | 0,15% | có | 2026 | | `tcbs` | 0,03% | chưa | 2025 | | `vci`, `hsc`, `mbs`, `kis`, `mas`, `vpbanks`, `fpts` | 0,15% | chưa | 2026 | | `dnse` | 0,03% | chưa | 2026 | | `binance_spot` | 0,10% | chưa | 2026 | | `binance_perp` | 0,05% | chưa | 2026 | | `zero` | 0 | có | — | `verified: false` nghĩa là chưa đối chiếu được với trang biểu phí hoặc hợp đồng chính thức. Mức phí thực tế còn phụ thuộc gói dịch vụ, kênh và chương trình ưu đãi của bạn. Khi biết mức của mình, khai thẳng bằng `fee`. Phái sinh VN30F thường tính phí theo hợp đồng, không theo % giá trị. Thêm `fee_per_contract` (mặc định 0) để cộng một mức phí cố định mỗi đơn vị, mỗi chiều, vào phí theo tỷ lệ đã khai: ```python bt.run(df, sigs, profile="vn_futures", fee=0.0, fee_per_contract=2700) ``` --- ## Sự kiện quyền Dữ liệu `vnstock` mặc định là **giá đã điều chỉnh**: cổ tức và cổ phiếu thưởng đã được phản ánh vào giá, nên không khai thêm sự kiện. Thư viện từ chối khai `corporate_actions` khi `prices_adjusted=True`, để một sự kiện không bị tính hai lần. Với giá gốc (chưa điều chỉnh), đặt `prices_adjusted=False` và khai sự kiện: ```python res = bt.run( raw_df, sigs, prices_adjusted=False, corporate_actions=[ {"kind": "cash_dividend", "ex_date": "2026-06-10", "payment_date": "2026-07-01", "amount_per_share": 2000, "tax_rate": 0.05}, {"kind": "stock_dividend", "ex_date": "2026-08-05", "listing_date": "2026-09-02", "ratio": 0.15}, {"kind": "rights_issue", "ex_date": "2026-10-20", "ratio": 0.2, "subscription_price": 10000, "listing_date": "2026-11-15"}, ], ) ``` - **Cổ tức tiền:** người nắm giữ trước ngày giao dịch không hưởng quyền được nhận. Tiền về tài khoản ở `payment_date`, sau khi trừ thuế thu nhập cá nhân `tax_rate` (mặc định 5%). Thiếu `payment_date` thì ghi nhận ở `ex_date` và có cảnh báo. `amount_per_share` tính bằng đồng, cùng đơn vị với giá dữ liệu sau khi quy đổi. - **Cổ phiếu thưởng, cổ tức bằng cổ phiếu:** `ratio=0.15` là thêm 15%. Cổ phiếu mới bán được từ `listing_date`. Thiếu ngày này thì dùng `ex_date` và có cảnh báo. Phần lẻ dưới một cổ phiếu bị bỏ; với vị thế nhiều lô (`pyramiding` > 1), cổ phiếu thưởng tính trên tổng số đang giữ rồi chia lại cho từng lô. - **Quyền mua cổ phiếu (`rights_issue`):** `ratio=0.2` nghĩa là được mua thêm 20% số đang giữ, ở giá `subscription_price` (đồng). Mặc định (`exercise=True`) thư viện thực hiện quyền ngay ngày GDKHQ, trong phạm vi tiền mặt đang có; số cổ phiếu mua thêm thành một lô riêng, giá vốn bằng giá phát hành, bán được từ `listing_date`. Tiền mặt không đủ mua hết số quyền được hưởng thì mua được bấy nhiêu, ghi `RIGHTS_CASH_LIMITED` vào `rejected_orders`. Đặt `exercise=False` để coi như bỏ quyền: phần giá trị bị pha loãng mất theo, không mô phỏng việc bán lại quyền. - Mức dừng lỗ, chốt lời và đỉnh của cắt lỗ đuổi của các lô đang giữ **dời theo đúng tỷ lệ pha loãng** của từng sự kiện, nên khoảng giảm kỹ thuật ngày GDKHQ không bị tính là lỗ hay kích hoạt cắt lỗ oan. - Mỗi sự kiện có thể thêm `symbol`. Backtest một mã thì không cần; chạy danh mục nhiều mã (`run_portfolio`) thì **bắt buộc** khai `symbol` để sự kiện áp đúng mã. --- ## Kịch bản sốc tự khai Thư viện không kèm kịch bản nào. Bạn tự khai một khoảng ngày để thử chiến lược trong điều kiện thanh khoản xấu hơn dữ liệu cho thấy: ```python res = bt.run( df, sigs, symbol="AAA", shock_events=[{ "event_id": "stress_test_1", "symbol": "AAA", "start_date": "2026-07-01", "end_date": "2026-07-10", "enforce_floor_lock": True, # phiên mở và đóng ở giá sàn được tính là khóa sàn "extra_slippage_pct": 0.01, # trượt giá thêm 1% cho mọi lệnh khớp trong khoảng này "headline": "Giả định thanh khoản cạn", }], ) ``` Bắt buộc: `event_id`, `symbol`, `start_date`, `end_date`. Kịch bản chỉ áp khi bạn truyền vào, và chỉ áp cho đúng `symbol`. Đây là giả định của bạn, không phải dữ liệu thị trường. --- ## Document: Cài đặt và thiết lập `vnstock_quant` có gói cài đặt dựng sẵn cho Python 3.10 trở lên. Bạn cài bằng `pip`; không cần tự biên dịch phần lõi Rust. --- ## Cài đặt gói Cài trong cùng môi trường Python với `vnstock`: `~/.venv` trên macOS và Linux, `$HOME\.venv` trên Windows. Trên Google Colab hoặc GitHub Codespaces, dùng môi trường đang chạy. Xem [Cài đặt vnstock](/docs/vnstock/cai-dat#cai-vao-dau) nếu bạn cần tạo môi trường hoặc vẫn còn bản 4.x. Các lệnh dưới đây giả định môi trường đã được kích hoạt. ```bash # Cài đặt thư viện tính toán vnstock_quant pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant # Hoặc cài đặt kèm luôn thư viện vnstock để tự động tải dữ liệu trực tiếp pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant[vnstock]" ```

Thêm --extra-index-url https://vnstocks.com/api/packages để pip tìm được thư viện trong kho phát hành của Vnstock. Nếu máy đã có vnstock thế hệ 5 và bạn đã chạy vnstock register, bạn cũng có thể cài bằng vnstock install vnstock_quant.

### Yêu cầu môi trường - **Hệ điều hành**: macOS 10.12 trở lên trên chip Intel (x86_64), macOS 11 trở lên trên chip Apple Silicon (arm64); Linux x86_64 và aarch64 dùng glibc 2.17 trở lên (chuẩn manylinux2014). - **Phiên bản Python**: Python 3.10 trở lên (một bản dựng dùng chung cho mọi phiên bản từ 3.10). - **Thư viện nền tảng**: `numpy>=1.24`, `pandas>=2.0` (tự động cài đặt khi chạy pip). --- ## Kiểm tra trạng thái cấp quyền và bản phát hành Sau khi cài, gọi `vq.entitlement()` để xem cấp quyền và nhóm hàm bạn có thể dùng. Việc kiểm tra này chạy trên máy và không trừ lượt tính: ```python import vnstock_quant as vq # Kiểm tra cấp quyền sử dụng, tính năng mở khoá và số lượt dùng thử còn lại status = vq.entitlement() print(status) ``` Ví dụ kết quả với tài khoản gói Diamond: ```python {'tier': 'diamond', 'active': True, 'features': ['ta_basic', 'ta', 'fa_basic', 'fa', 'fa_advanced', 'risk', 'portfolio', 'bt_basic', 'bt', 'bt_portfolio', 'bt_optimize'], 'policy_version': 'quant_entitlement_v3', 'trial': None, 'backtest': {'budget': 'vnstock_bt', 'trial': None, 'quota': {'portfolio_symbols': 400, 'sweep_tasks': 50000, 'monte_carlo_paths': 100000}}, 'error': None, 'release': {'package': 'vnstock_quant', 'version': '0.5.0', 'pre_release': False, 'build_date': '2026-10-27', 'expires_at': '2027-10-27T15:19:01+00:00', 'days_left': 365, 'policy_issued_at': '2026-10-26T08:23:25.699+00:00', 'offline_deadline': '2027-10-31T00:00:00+00:00', 'warning': None, 'error': None}} ``` Kết quả gồm: - `tier`: Cấp quyền sử dụng hiện tại nhận diện được trên máy (`guest` khi chưa đăng nhập, `free`, `bronze`, `silver`, `golden`, `diamond`). Là `None` khi không kiểm tra được quyền; lý do nằm ở `error`. - `active`: `True` khi quyền sử dụng đang còn hiệu lực. - `features`: Danh sách các nhóm tính năng đang được phép sử dụng (`ta_basic`, `ta`, `fa_basic`, `fa`, `fa_advanced`, `risk`, `portfolio`; mô hình định giá dùng chung quyền `portfolio`; `bt_basic`, `bt`, `bt_portfolio`, `bt_optimize` của mô-đun backtest). Ý nghĩa từng nhóm và cấp mở: [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc). - `policy_version`: Phiên bản bộ quy tắc cấp quyền mà bản cài này áp dụng. - `trial`: Với bản Cộng đồng, từ điển này cho biết tổng số lượt dùng thử trong ngày (`daily`), số lượt đã dùng (`used`), số lượt còn lại (`remaining`), số mã tối đa mỗi lần tải (`max_symbols`) và thời điểm làm mới (`resets_at`). Với gói quyền sử dụng không giới hạn lượt, giá trị là `None`. - `backtest`: Phần riêng của mô-đun backtest: `trial` (lượt backtest trong ngày, tách khỏi `trial` ở trên), `quota` (quy mô một lần chạy theo cấp) và `budget` (tên dòng ngân sách trên máy chủ). Xem [Cấp quyền và xử lý lỗi](/docs/vnstock_quant/free/backtest/cap-quyen-va-xu-ly-loi). - `error`: `None` khi kiểm tra quyền thành công; nếu không, là bộ `(code, kind, message, action)` mô tả lỗi. - `release`: Thông tin hạn dùng của bản đang cài: - `package`, `version`: tên gói và phiên bản. - `pre_release`: có phải bản thử không. - `build_date`, `expires_at`, `days_left`: ngày dựng, ngày hết hạn và số ngày còn lại. - `policy_issued_at`: thời điểm phát hành của chính sách vòng đời mà máy chủ gửi về và đang áp dụng; `None` khi chưa đọc được chính sách nào và hạn dùng được tính theo ngày dựng. - `offline_deadline`: sau thời điểm này, bản cài không đọc được chính sách nào từ máy chủ sẽ ngừng chạy. - `warning`: thông báo về hạn dùng khi gần tới `expires_at`, `None` khi chưa tới lúc thông báo. - `error`: lý do bản phát hành không được chạy (đã hết hạn hoặc đã bị tắt), `None` khi bình thường. Nếu cần biết thông tin bản dựng của phần lõi, gọi: ```python # Xem thông tin biên dịch lõi Rust info = vq.build_info() print(info) # {'version': '0.5.0', 'test_entitlement': False, 'ta_methods': 58, 'fa_ratios': 100, # 'fa_registry': 'fa_v1', 'risk_measures': 33, 'portfolio_functions': 38, 'micro_functions': 5, # 'backtest_tools': 10} ``` --- ## Đọc tiếp - [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc) — Nhóm tính năng nào mở ở cấp nào, lượt dùng thử và quy mô mỗi lần chạy. - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/free/bat-dau/quy-uoc-du-lieu-va-loi) — Dạng dữ liệu đầu vào, cây ngoại lệ, mã lỗi và quy ước phương pháp luận. - [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/free/tich-hop/tai-du-lieu-bang-vnstock) — Điểm vào tải dữ liệu cho từng nhóm hàm. - [Chỉ báo kỹ thuật](/docs/vnstock_quant/free/tinh-toan/ta) — Bắt đầu tính toán với 58 chỉ báo kỹ thuật. --- ## Document: Quy ước dữ liệu và lỗi Trang này gom những điều đúng với mọi nhóm hàm của `vnstock_quant`: dữ liệu đầu vào trông như thế nào, lỗi được báo ra sao và các quy ước tính toán mà kết quả tuân theo. Từng trang nhóm hàm chỉ nói phần riêng của nhóm đó. --- ## Dữ liệu đầu vào Thư viện nhận dữ liệu dạng `pandas` và trả kết quả căn theo chỉ mục bạn đưa vào. Lớp Python chỉ đổi cột sang mảng số rồi dựng lại bảng có nhãn; mọi phép tính và kiểm tra đầu vào nằm trong lõi Rust, nên thiếu cột hay lệch độ dài được báo bằng `InputDataError` kèm tên cột thiếu. | Nhóm hàm | Dạng dữ liệu | Ghi chú | | :--- | :--- | :--- | | `ta`, `backtest`, `micro.cvd`, `micro.realized` | Bảng nến: cột `open`, `high`, `low`, `close`, `volume` viết thường, chỉ mục thời gian `DatetimeIndex` hoặc cột `time` | `ta` chỉ cần các cột mà chỉ báo dùng; `backtest` nhận thêm `price_unit` để nhận ra bảng tính bằng nghìn đồng hay đồng | | `risk`, `portfolio` | `pandas.Series` hoặc `DataFrame` **lợi suất giản đơn** từng kỳ, chỉ mục `DatetimeIndex` | Tính từ giá đóng cửa đã điều chỉnh bằng `risk.returns(prices)`; hai chuỗi được căn theo ngày giao dịch chung | | `fa` | Báo cáo tài chính dạng long: cột `period`, `id`, `value` với mã chỉ tiêu của `vnstock`, gói trong `fa.Dataset` | Chỉ số dùng mẫu số bình quân cần ít nhất hai kỳ | | `prices` | Bảng phiên của `trade_history()` (giá tham chiếu, trần, sàn, OHLC, khối lượng) và bảng sự kiện của `events()` | Đơn vị đồng; `unit="auto"` nhận ra bảng nghìn đồng của `ohlcv()` | | `micro.bars`, `micro.classify` | Bảng khớp lệnh: `time`, `price`, `volume`, cột bên chủ động nếu nguồn có (`match_type`) | Nguồn không có bên chủ động thì suy bằng tick rule | Kết quả là `DataFrame` hoặc `Series` cùng chỉ mục với đầu vào. Siêu dữ liệu đi kèm nằm trong `attrs` (ví dụ bảng hệ số của `prices.adjust` ở `attrs["factors"]`). Thư viện không tự đổi đơn vị giá trừ khi hàm có tham số `unit` hoặc `price_unit`; hãy dùng một đơn vị nhất quán trong cả phiên làm việc. --- ## Hệ thống phân cấp ngoại lệ Các lỗi của thư viện kế thừa từ `VnstockQuantError`. Mã lỗi giúp bạn phân biệt sai tham số, dữ liệu đầu vào, quyền sử dụng và những trường hợp khác: ```text 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 thư viện phụ trợ, ví dụ chưa cài vnstock (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 ``` Mọi lỗi đều có các thuộc tính `code` (mã lỗi), `kind` (nhóm lỗi), `message` (nội dung tiếng Việt), `retryable` (có nên thử lại không) và `action` (việc nên làm tiếp, có thể là `None`). `str(e)` có dạng `[code] message (action)`. ### Ví dụ bắt lỗi theo nghiệp vụ ```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}") ``` ### Tắt cảnh báo hệ thống Các lưu ý không làm dừng chương trình được phát qua lớp cảnh báo `VnstockQuantWarning` (ví dụ: cảnh báo tự động bỏ qua các chỉ số nâng cao khi chạy tính toán hàng loạt toàn bộ chỉ số ở cấp Cộng đồng). Bạn có thể tắt cảnh báo này nếu muốn: ```python 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 chung Trước khi so sánh kết quả giữa các hàm, hãy chú ý các quy ước sau: | Quy ước | Chi tiết áp dụng | | :--- | :--- | | **Tỷ lệ và phân số** | Mọi tỷ lệ phần trăm được biểu diễn dưới dạng **phân số thập phân** (ví dụ `0.18` đại diện cho 18%). Kết quả tính toán trả về cũng tuân thủ định dạng phân số. | | **Giá và chuỗi lợi suất** | Chuỗi lợi suất giản đơn được tính toán dựa trên **giá đóng cửa đã điều chỉnh** (adjusted close). Việc dùng giá chưa điều chỉnh sẽ tạo ra các phiên thua lỗ giả tạo vào ngày giao dịch không hưởng quyền. | | **Số phiên giao dịch một năm** | Mặc định sử dụng **252 phiên/năm** theo chuẩn quốc tế đối với dữ liệu ngày (52 tuần, 12 tháng). Dữ liệu thực tế tại 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 rủi ro nếu muốn quy đổi chuẩn xác theo năm dựa trên lịch giao dịch Việt Nam. | | **Lãi suất phi rủi ro (`rf`)** | Là lãi suất năm, mặc định là `0`. Bạn có thể chỉ định lãi suất trái phiếu Chính phủ kỳ hạn 1 năm hoặc lãi suất tiết kiệm 12 tháng của nhóm ngân hàng Big 4. | | **Chỉ mục thời gian (`time`)** | Căn cứ vào `DatetimeIndex` của pandas. Khi tính toán tương quan hoặc đo lường so với thị trường (Benchmark), hai chuỗi dữ liệu được căn chỉnh theo **ngày giao dịch chung**, không căn chỉnh theo số thứ tự hàng. | | **Xử lý dữ liệu khuyết thiếu** | Không bao giờ âm thầm điền số 0 vào ô trống. Báo cáo tài chính thiếu chỉ tiêu sẽ được đánh dấu rõ ràng qua cột `reason`. Các hàm danh mục sẽ từ chối tính toán nếu chuỗi lợi suất chứa giá trị NaN. | | **Độ đo rủi ro sụt giảm (VaR/CVaR)** | Trả về **giá trị dương** đại diện cho mức lỗ tiềm tàng tại ngưỡng tin cậy xác định. | | **Ràng buộc bán khống (Short-selling)** | Không cho phép vị thế bán khống trong các bài toán tối ưu danh mục, phù hợp với quy định của thị trường chứng khoán cơ sở Việt Nam. | --- ## Đọc tiếp - [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc) — Khi nào gặp `TierRequiredError` và `QuotaExceededError`. - [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh) — Vì sao chuỗi lợi suất cần giá đã điều chỉnh. - [Đối chiếu kết quả và tốc độ](/docs/vnstock_quant/free/tham-khao/doi-chieu-ket-qua-va-toc-do) — Các mốc chuẩn mà kết quả được so với. --- ## Document: Quyền dùng và hạn mức `vnstock_quant` cấp quyền theo **nhóm tính năng**, không theo từng hàm. Bộ quy tắc do máy chủ Vnstock quyết định và gửi về máy bạn; thư viện chỉ thi hành. Trang này là bảng tra duy nhất về quyền và hạn mức; các trang nhóm hàm chỉ ghi một dòng "cần cấp nào" và trỏ về đây.

Mọi phép tính của vnstock_quant chạy trên máy bạn và không trừ vào hạn mức chung của tài khoản Vnstock. Chỉ việc tải dữ liệu qua thư viện vnstock (ví dụ Dataset.load(), from_vnstock()) mới tính vào hạn mức, theo quy tắc của vnstock. Xem mức còn lại trên trang tài khoản.

--- ## Nhóm tính năng theo cấp Cấp được nhận diện trên máy: `guest` khi chưa đăng nhập, `free` với tài khoản Cộng đồng, rồi `bronze`, `silver`, `golden`, `diamond` theo gói quyền sử dụng. Hai cấp đầu có cùng quyền. | Nhóm tính năng | Mã trong `features` | Mở gì | Cộng đồng | Bronze | Silver trở lên | | :--- | :--- | :--- | :---: | :---: | :---: | | Chỉ báo kỹ thuật cơ bản | `ta_basic` | 10 chỉ báo: SMA, EMA, RSI, MACD, Stoch, Bollinger Bands, ATR, OBV, VWAP, Pivots | Có, theo lượt thử | Có | Có | | Chỉ báo kỹ thuật đầy đủ | `ta` | Đủ 58 chỉ báo của `vnstock_quant.ta` | Chưa mở | Chưa mở | Có | | Chỉ số tài chính cơ bản | `fa_basic` | 10 chỉ số: P/E, P/B, EPS, BVPS, ROE, ROA, biên lợi nhuận gộp và ròng, D/E, thanh toán hiện hành | Có, theo lượt thử | Có | Có | | Chỉ số tài chính đầy đủ | `fa` | Đủ 100 chỉ số theo bốn mẫu ngành, tra công thức và kỳ dữ liệu | Chưa mở | Có | Có | | Chỉ số tài chính mở rộng | `fa_advanced` | Dòng tiền theo CFA, DuPont, Altman Z, Piotroski F, Beneish M | Chưa mở | Có | Có | | Rủi ro, giá điều chỉnh, vi cấu trúc | `risk` | `vnstock_quant.risk`, `vnstock_quant.prices`, `vnstock_quant.micro` | Chưa mở | Có | Có | | Danh mục và định giá | `portfolio` | `vnstock_quant.portfolio`, `vnstock_quant.valuation` | Chưa mở | Có | Có | | Backtest cơ bản | `bt_basic` | Một mã, bảng quy tắc với 10 chỉ báo cơ bản | Có, theo lượt thử | Có | Có | | Backtest một mã đầy đủ | `bt` | Đủ chỉ báo trong bảng quy tắc, mọi chế độ khớp lệnh | Chưa mở | Có | Có | | Backtest danh mục | `bt_portfolio` | Nhiều mã, tái cân bằng theo tỷ trọng | Chưa mở | Có | Có | | Tối ưu và chống quá khớp | `bt_optimize` | Dò tham số, walk-forward, Monte Carlo | Chưa mở | Có | Có | Các cấp từ Silver trở lên khác nhau ở **quy mô** mỗi lần chạy (bảng bên dưới) và ở hạn mức tải dữ liệu của `vnstock`, không khác ở nhóm tính năng. Kiểm tra cấp và nhóm tính năng của chính bạn mà không trừ lượt: ```python import vnstock_quant as vq status = vq.entitlement() status["tier"], status["features"], status["policy_version"] # ('free', ['ta_basic', 'fa_basic', 'bt_basic'], 'quant_entitlement_v3') ``` --- ## Lượt dùng thử của bản Cộng đồng Bản Cộng đồng có hai bộ đếm lượt thử trong ngày, tách nhau và không liên quan đến hạn mức chung. Lượt được đếm trên máy, không cần khoá API, và làm mới lúc 00:00 giờ Việt Nam. | | Chỉ báo và chỉ số (`vnstock_quant`) | Backtest (`vnstock_quant.backtest`) | | :--- | :--- | :--- | | Lượt mỗi ngày | 30 phép tính, tính chung chỉ báo kỹ thuật và chỉ số tài chính | 3 lần chạy | | Số mã mỗi lần | 3 mã mỗi lần tải dữ liệu qua `vnstock` | 1 mã mỗi lần chạy | | Xem số còn lại | `vq.entitlement()["trial"]` | `vq.entitlement()["backtest"]["trial"]` | | Khi hết | `QuotaExceededError`, mã `QUANT_TRIAL_EXHAUSTED` | như bên trái | Hai bộ đếm tách nhau vì backtest có **hạn mức riêng** do máy chủ đặt, để một lần chạy thử không làm hụt lượt tính chỉ báo trong ngày. Máy chủ có thể đổi số lượt hoặc số mã mà bạn không cần cập nhật thư viện; bảng trên là mức mặc định hiện hành. --- ## Quy mô mỗi lần chạy thử Từng cấp giới hạn độ lớn của **một lần** backtest. Vượt ngưỡng thì thư viện báo `QuotaExceededError` với mã `QUANT_QUOTA_LIMIT` trước khi tính, kèm ngưỡng của cấp bạn trong thông điệp. | Cấp | Mã trong một danh mục | Tổ hợp tham số mỗi lần dò | Đường mô phỏng Monte Carlo | | :--- | ---: | ---: | ---: | | Cộng đồng | 1 | 10 | 200 | | Bronze | 10 | 100 | 1.000 | | Silver | 30 | 1.000 | 5.000 | | Golden | 100 | 10.000 | 20.000 | | Diamond | 400 | 50.000 | 100.000 | Xem các ngưỡng đang áp dụng cho bạn ở `vq.entitlement()["backtest"]["quota"]`. --- ## Số mã mỗi lần tải báo cáo tài chính `fa.Dataset.load()` tải nhiều bảng cho mỗi mã, nên số mã một lần gọi giới hạn theo cấp: Cộng đồng 3, Bronze 100, Silver 400, Golden và Diamond toàn thị trường. Vượt ngưỡng thì gặp `TierRequiredError` với mã `QUANT_SCOPE_LIMIT`. Giá chưa điều chỉnh dùng cho các chỉ số định giá cần cấp quyền sử dụng của `vnstock`; bản Cộng đồng gọi `Dataset.load(..., prices=False)` và các chỉ số P/E, P/B báo `MISSING_MARKET` ở cột `reason`. --- ## Khi quyền không đủ | Tình huống | Ngoại lệ | Mã | | :--- | :--- | :--- | | Nhóm tính năng chưa mở ở cấp hiện tại | `TierRequiredError` | `QUANT_TIER_REQUIRED` | | Quá số mã cho phép của cấp | `TierRequiredError` | `QUANT_SCOPE_LIMIT` | | Hết lượt thử trong ngày | `QuotaExceededError` | `QUANT_TRIAL_EXHAUSTED` | | Một lần chạy thử quá lớn cho cấp | `QuotaExceededError` | `QUANT_QUOTA_LIMIT` | | Không kiểm tra được quyền (khoá, thiết bị, mạng) | `AuthError` | theo `kind` | Thuộc tính `action` của ngoại lệ nói việc nên làm tiếp. Cây ngoại lệ đầy đủ ở [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/free/bat-dau/quy-uoc-du-lieu-va-loi). Phạm vi từng gói quyền sử dụng: [Bảng giá](/pricing). --- ## Đọc tiếp - [Cài đặt và thiết lập](/docs/vnstock_quant/free/bat-dau/cai-dat-va-thiet-lap) — Đọc đủ các trường của `vq.entitlement()`. - [Cấp quyền và xử lý lỗi của backtest](/docs/vnstock_quant/free/backtest/cap-quyen-va-xu-ly-loi) — Ví dụ bắt lỗi quyền khi chạy thử chiến lược. - [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/free/tich-hop/tai-du-lieu-bang-vnstock) — Phần nào tính vào hạn mức chung. --- ## Document: Từ vnstock_ta ## Tổng quan `vnstock_quant` kế tục `vnstock_ta` từ thế hệ 5. Với mã dùng lớp `Indicator`, bạn đổi tên thư viện trong câu lệnh `import`; tên hàm và phần lớn tên cột vẫn giữ nguyên. Sau đó, hãy chạy lại các phép tính: một số chỉ báo đã đổi công thức hoặc cách khởi tạo, cột `ADXR` của `adx` đổi thành `ADXR_14`, và tham số không hợp lệ nay báo lỗi. --- ## 1. Cài gói mới và đổi import ### Cài đặt gói mới Cài `vnstock_quant` từ kho phát hành của Vnstock. Chỉ gỡ `vnstock_ta` khi môi trường này không còn mã cần dùng gói cũ: ```bash # Cài đặt thư viện định lượng thế hệ mới pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock_quant ``` ### Đổi tên Import trong mã nguồn Đổi câu lệnh `import` trong các tệp đang dùng `Indicator`: ```python # Cách viết cũ (thế hệ 4) from vnstock_ta import Indicator # Cách viết với vnstock_quant from vnstock_quant import Indicator ``` Mọi đoạn mã gọi hàm bên dưới như `ta = Indicator(df)`, `ta.trend.sma()`, `ta.macd()` hay `ta.momentum.rsi()` giữ nguyên cú pháp. Riêng kết quả số của một số chỉ báo sẽ khác bản cũ, xem mục 2. --- ## 2. Những kết quả có thể thay đổi Trong phiên bản 1.x, `vnstock_ta` phụ thuộc vào gói Python `pta_reload` (fork từ `pandas-ta`). Qua quá trình đối chiếu với **TA-Lib C 0.8.1** và nền tảng **QuantConnect LEAN**, dự án phát hiện nhiều chỉ báo trong phiên bản cũ bị sai lệch công thức hoặc khởi tạo sai chu kỳ. Khi so sánh với `vnstock_ta` 1.x, các chỉ báo rơi vào ba nhóm sau: - **32 chỉ báo không đổi**: giá trị trùng `vnstock_ta` 1.x (sai lệch dưới 1e-9), trừ vài trường hợp đặc biệt như phiên có khoảng giá bằng 0 hoặc không có khối lượng: `sma`, `ema`, `wma`, `hma`, `smma`, `alma`, `vwma`, `ichimoku`, `linreg`, `aroon`, `stoch`, `mom`, `roc`, `ao`, `willr`, `uo`, `bbands`, `kc`, `donchian`, `ui`, `true_range`, `cmf`, `ad`, `eom`, `mad`, `vwap`, `hl2`, `hlc3`, `ohlc4`, `midprice`, `increasing`, `decreasing`. - **10 chỉ báo chỉ khác ở giai đoạn khởi động** (warm-up period), sau đó trùng dần: `rsi`, `atr`, `adx`, `stochrsi`, `tsi`, `macd`, `fisher`, `massi`, `pvo`, `efi`. Nguyên nhân là bản cũ khởi tạo đường trung bình khác cách của Wilder và TA-Lib. Ở đầu chuỗi, mức lệch có thể lớn (RSI lệch khoảng 18 điểm), rồi giảm dần: với chu kỳ 14, còn khoảng 1e-6 sau 200 phiên. Riêng `adx`, cột ADXR đổi độ trễ và đổi tên thành `ADXR_14`. - **16 chỉ báo đã sửa lỗi công thức**, nên giá trị khác hẳn bản cũ: - `cci`: bản cũ thiếu ngoặc trong công thức nên giá trị mang độ lớn của giá; mọi ngưỡng ±100/±200 đặt trên CCI cũ cần đặt lại. - `kst`: bản cũ nhân thừa 100. - `cg`: bản cũ đảo ngược trọng số. - `nvi`: bản cũ cộng phần trăm thay vì nhân. - `vp`: bản cũ chia theo thời gian thay vì theo giá. - `pivots`: sửa các kiểu `traditional`, `woodie`, `demark`; mức S3, S4, R3, R4 thay đổi. - `psar`: bản cũ bỏ qua tham số `af` và khởi tạo bằng giá đóng cửa. - `supertrend`: logic dải và hướng nay khớp TradingView. - `dm`: bản cũ trả trung bình Wilder thay vì tổng Wilder (giá trị mới xấp xỉ giá trị cũ nhân chu kỳ). - `cmo`: theo đúng định nghĩa của Chande. - `squeeze`, `squeeze_pro`: cột động lượng khác; cờ ON/OFF/NO không đổi. - `obv`: bản cũ lệch một hằng số bằng khối lượng phiên đầu. - `mfi`: bản cũ tính phiên giá không đổi là dòng tiền âm. - `stdev`, `variance`: nay chia cho n (tổng thể) thay vì n − 1 (mẫu).

Nếu mã phân tích của bạn đang so sánh số liệu với các kết quả xuất ra từ vnstock_ta 1.x, số liệu mới từ vnstock_quant có thể có sự khác biệt ở 16 chỉ báo nêu trên. Số liệu mới từ vnstock_quant đã được đối chiếu với TA-Lib C, dữ liệu kiểm thử LEAN hoặc định nghĩa gốc của tác giả chỉ báo.

--- ## 3. Số đo hiệu năng tham khảo Kiểm thử đo lường tốc độ xử lý toàn bộ 58 chỉ báo kỹ thuật trên chuỗi dữ liệu 5.000 phiên giao dịch: | Tiêu chí đánh giá | vnstock_ta 1.x (Python) | vnstock_quant 0.1.x (Rust Core) | Mức độ cải thiện | | :--- | :--- | :--- | :--- | | **Thời gian xử lý** | 138,5 ms | 5,3 ms | **Nhanh hơn 25,9 lần** | | **Quản lý bộ nhớ** | Tạo nhiều đối tượng DataFrame tạm | Sử dụng Flat Buffer vùng đệm liên tục | Ít đối tượng tạm hơn | | **Đa luồng (Concurrency)** | Bị khoá bởi Python GIL | Nhả GIL trong lõi Rust | Phần dựng kết quả pandas vẫn giữ GIL; chuỗi ngắn chạy nhiều luồng chưa nhanh hơn | | **Độ ổn định tham số** | Âm thầm thay đổi khi sai tham số | Báo lỗi kèm mã lỗi rõ ràng | Tránh lỗi ngầm trong thuật toán | Số đo thời gian là số tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026; máy khác cho số khác. --- ## 4. Chuyển phần vẽ biểu đồ `vnstock_ta` 1.x từng có lớp `Plotter`. `vnstock_quant` tập trung vào tính toán; để vẽ kết quả ở thế hệ 5, dùng thư viện [`vnstock_chart`](/docs/vnstock-chart). Cách gọi hàm vẽ khác `Plotter`, nên hãy xem [các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do) và [ví dụ kết hợp với vnstock thế hệ 5](/docs/vnstock-chart/ket-hop-voi-gen5) trước khi sửa mã. --- ## 5. Danh mục kiểm tra chuyển đổi 1. Cài `vnstock_quant` trong môi trường bạn dùng để kiểm tra mã. 2. Đổi `from vnstock_ta import Indicator` thành `from vnstock_quant import Indicator`. 3. Chạy lại mã và sửa các tham số bị báo không hợp lệ. 4. So sánh kết quả của những chỉ báo đã thay đổi trước khi tiếp tục dùng các ngưỡng cũ. 5. Nếu không còn dùng gói cũ, gỡ `vnstock-ta` khỏi môi trường và tệp phụ thuộc của dự án. --- ## Đọc tiếp - [Chỉ báo kỹ thuật](/docs/vnstock_quant/free/tinh-toan/ta) — Hướng dẫn chi tiết 58 chỉ báo kỹ thuật. - [Chỉ số tài chính](/docs/vnstock_quant/free/tinh-toan/fa) — Khám phá 100 chỉ số tài chính BCTC VAS mới được bổ sung. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường rủi ro danh mục và thanh khoản Amihud. - [Kiểm định chất lượng & hiệu năng](/docs/vnstock_quant/free/tham-khao/doi-chieu-ket-qua-va-toc-do) — Báo cáo đo kiểm hiệu năng và đối chứng số học với TA-Lib C. --- ## Document: Giới thiệu ## Bạn có thể làm gì? Bản Cộng đồng của `vnstock_quant` cho phép bạn tính chỉ báo kỹ thuật, chỉ số tài chính cơ bản và chạy thử chiến lược trên một mã bằng Python, cho mục đích cá nhân, học tập và nghiên cứu. Các phép tính chạy trên máy của bạn, từ dữ liệu bạn đã chuẩn bị hoặc truy xuất bằng `vnstock`, và không cần khoá API để bắt đầu. Bản Cộng đồng gồm: - **10 chỉ báo kỹ thuật cơ bản**: SMA, EMA, RSI, MACD, Stoch, Bollinger Bands, ATR, OBV, VWAP, Pivots ([Chỉ báo kỹ thuật](/docs/vnstock_quant/free/tinh-toan/ta)). - **10 chỉ số tài chính cơ bản** từ báo cáo tài chính VAS: P/E, P/B, EPS, BVPS, ROE, ROA, biên lợi nhuận gộp và ròng, D/E, thanh toán hiện hành ([Chỉ số tài chính](/docs/vnstock_quant/free/tinh-toan/fa)). - **Backtest một mã** với bảng quy tắc dùng 10 chỉ báo trên, theo luật thị trường Việt Nam: lô 100, bước giá, biên độ, T+2.5, thuế bán ([Chạy thử chiến lược](/docs/vnstock_quant/free/backtest/gioi-thieu)). - **Hỗ trợ trợ lý AI**: mã lỗi ổn định và catalog có JSON Schema để trợ lý viết mã đúng với những hàm mở cho bản Cộng đồng. ### Mức độ ổn định của từng nhóm hàm Ba nhóm trên chưa ổn định như nhau. Chỉ báo kỹ thuật đã **ổn định**: cách gọi và kết quả được giữ nhất quán giữa các bản phát hành. Chỉ số tài chính và backtest đang **thử nghiệm**: dùng được để tìm hiểu và chạy thử, nhưng tên hàm, tham số và cấu trúc kết quả có thể còn đổi giữa các bản, công thức cũng có thể còn được hiệu chỉnh. Hãy đối chiếu kết quả của hai nhóm này trước khi dựa vào chúng, và ghim phiên bản thư viện trong dự án để mã đang chạy không tự đổi theo bản mới. Trang của từng nhóm có nhãn mức ổn định ở đầu trang. ### Dùng cùng trợ lý AI Muốn làm việc cùng trợ lý AI, bạn có thể bắt đầu từ [Agent Guide](/onboard/agent-guide). Nếu dùng công cụ AI trên máy cục bộ, [Vnstock MCP](/vnstock-mcp) giúp trợ lý điều phối công cụ Vnstock để viết mã và thực hiện tác vụ theo yêu cầu. --- ## Lượt dùng thử Bản Cộng đồng có hai bộ đếm lượt thử trong ngày, tách nhau, đếm trên máy và làm mới lúc **00:00 giờ Việt Nam**. Phép tính không trừ vào hạn mức chung của tài khoản; chỉ việc tải dữ liệu qua `vnstock` mới tính vào hạn mức đó. | | Chỉ báo và chỉ số | Backtest | | :--- | :--- | :--- | | Lượt mỗi ngày | **30 phép tính**, tính chung chỉ báo kỹ thuật và chỉ số tài chính | **3 lần chạy** | | Số mã mỗi lần | 3 mã mỗi lần tải dữ liệu qua `vnstock` | 1 mã mỗi lần chạy | | Xem số còn lại | `vq.entitlement()["trial"]` | `vq.entitlement()["backtest"]["trial"]` |

Tính một chỉ báo trên chuỗi nến (ví dụ ta.rsi(length=14)) hay một lần fa.ratios() là 1 lượt; một lần backtest.run() là 1 lượt backtest. Hết lượt thì thư viện báo QuotaExceededError với mã QUANT_TRIAL_EXHAUSTED; lượt làm mới sau 00:00.

Bảng đầy đủ về quyền theo cấp và quy mô mỗi lần chạy: [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc). --- ## So sánh với bản Mở rộng | Nhóm tính năng | Bản Cộng đồng | Bản Mở rộng (gói quyền sử dụng) | | :--- | :---: | :---: | | **Lượt dùng thử riêng** | 30 phép tính và 3 backtest mỗi ngày | Không áp dụng từ Bronze | | **Chỉ báo kỹ thuật** | 10 chỉ báo cơ bản | Đủ 58 chỉ báo từ Silver (Bronze: 10 chỉ báo cơ bản) | | **Chỉ số tài chính** | 10 chỉ số cơ bản | Đủ 100 chỉ số theo bốn mẫu ngành và dòng tiền CFA, từ Bronze | | **Giá điều chỉnh, vi cấu trúc thị trường** | Chưa mở | Từ Bronze | | **Rủi ro và hiệu suất** | Chưa mở | Đủ 33 thước đo, từ Bronze | | **Danh mục, định giá** | Chưa mở | Đủ 38 hàm danh mục, DDM và P/E hợp lý, từ Bronze | | **Backtest** | Một mã, 10 chỉ báo cơ bản, 10 tổ hợp tham số, 200 đường Monte Carlo | Đủ chỉ báo, danh mục nhiều mã, dò tham số, walk-forward; quy mô tăng theo cấp |

Để xem các hàm rủi ro, danh mục, định giá và backtest đầy đủ, hãy chuyển sang tab Gói ở đầu trang. Xem Bảng giá nếu bạn muốn chọn gói phù hợp.

--- ## Đọc tiếp - [Cài đặt và thiết lập](/docs/vnstock_quant/free/bat-dau/cai-dat-va-thiet-lap) — Cài thư viện và kiểm tra số lượt còn lại. - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/free/bat-dau/quy-uoc-du-lieu-va-loi) — Dạng dữ liệu đầu vào và cây ngoại lệ. - [Chỉ báo kỹ thuật](/docs/vnstock_quant/free/tinh-toan/ta) — Cách gọi 10 chỉ báo của bản Cộng đồng. - [Chỉ số tài chính](/docs/vnstock_quant/free/tinh-toan/fa) — Chuẩn bị báo cáo tài chính và tính 10 chỉ số cơ bản. - [Chạy thử chiến lược](/docs/vnstock_quant/free/backtest/gioi-thieu) — Backtest một mã theo luật thị trường Việt Nam. - [Chuyển từ vnstock_ta](/docs/vnstock_quant/free/chuyen-doi/tu-vnstock-ta) — Đổi mã nguồn cũ sang vnstock_quant. - [Lịch sử phiên bản](/docs/vnstock_quant/free/lich-su-phien-ban) — Các bản phát hành. --- ## Document: Lịch sử phiên bản ## 27-10-2026 ### vnstock_quant (v0.5.0) #### Mô-đun mới: chạy thử chiến lược (`backtest`) `vnstock_quant.backtest` chạy thử chiến lược trên dữ liệu giá bạn chuẩn bị, theo luật thị trường Việt Nam, trong cùng lõi Rust với các nhóm hàm khác: bảng quy tắc dùng đúng 58 chỉ báo của `ta`, tear sheet dùng 33 thước đo của `risk`, chung cấp quyền và cây lỗi của thư viện. Tài liệu: [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu). - **Tín hiệu**: mảng `[-1, 0, 1]`, cặp `entries`/`exits` hoặc bảng quy tắc `rule_dsl` dạng JSON; kiểm thiên lệch nhìn trước tương lai cho cả hàm tín hiệu và bảng quy tắc (`check_causality`, `check_rule_dsl_causality`). - **Luật thị trường**: mặc định lô 100, bước giá theo sàn, biên độ, phiên khóa trần và khóa sàn, T+2.5, thuế bán 0,1% tính riêng ngoài phí; hồ sơ phái sinh VN30F, crypto, cổ phiếu quốc tế, ngoại hối; cổ tức tiền, cổ phiếu thưởng và quyền mua trên giá gốc. - **Khớp lệnh**: chế độ `vn_realistic` và bốn chế độ tái tạo hành vi mặc định của backtesting.py, backtrader, vectorbt, zipline, khớp tới từng lệnh trên 11 kịch bản đối chứng; lệnh giới hạn và lệnh dừng theo phiên, nhiều lô trong một vị thế, chốt lời từng phần, dừng lỗ động, chặn rủi ro cấp tài khoản. - **Danh mục và chống quá khớp**: `run_portfolio` cho nhiều mã chung một tài khoản và tái cân bằng theo tỷ trọng; `sweep`, `walk_forward`, `monte_carlo`, `deflated_sharpe_ratio`. - **Gọi bằng JSON**: `catalog()`, `schema()` và `call()` với 10 công cụ dùng được trực tiếp cho trợ lý AI và Vnstock MCP. - **Lỗi và quyền**: lớp lỗi mới `CausalityViolationError` (`QUANT_CAUSALITY_VIOLATION`); mã `QUANT_QUOTA_LIMIT` (`QuotaExceededError`) khi một lần chạy vượt quy mô của cấp; `vq.entitlement()` có thêm khoá `backtest` và bộ quy tắc `quant_entitlement_v3`. - Backtest một mã với 10 chỉ báo cơ bản trong bảng quy tắc, 3 lượt mỗi ngày. Lượt backtest đếm riêng, không trừ vào 30 phép tính chỉ báo và chỉ số; xem `vq.entitlement()["backtest"]`. - Extra `chart` (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) cài [`vnstock_chart`](/docs/vnstock-chart) để vẽ kết quả chạy thử. #### Mô-đun mới: giá điều chỉnh (`prices`) #### Chỉ số tài chính (`fa`) Các chỉ số nêu sau cho số khác bản 0.4.0; những chỉ số không nhắc tới giữ nguyên. Mỗi thay đổi được kiểm trên dữ liệu thị trường tải ngày 27/10/2026 và trên 64 mã của bộ đối chiếu. Cách tính chi tiết xem ở [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa). - **P/E, P/B, P/S, P/CF, EV/EBITDA kỳ năm**: Lấy giá đóng cửa và số cổ phiếu của cùng một phiên, tại ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4 và P/E bằng giá / EPS trong cùng một dòng. Bản trước lấy giá cuối năm sau nhân với số cổ phiếu của năm báo cáo: chỉ số dùng giá của một năm sau kỳ báo cáo, và thấp hơn thực tế khi có chia cổ phiếu trong năm sau (P/E năm 2024 của VCB ra 9,5 thay vì 14,65; FPT ra 17,9 thay vì 22,2). Tham số `overrides={"year_valuation": ...}` không còn dùng được. - **Dòng quý 4 của chuỗi quý**: Mẫu số bình quân (ROE, ROA, vòng quay, số ngày thu tiền...) là bình quân 4 điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán. Bản trước dùng bình quân đầu năm và cuối năm, làm chuỗi quý nhảy ở mỗi quý 4 (ROE quý 4 của ngân hàng cao hơn trung bình hai quý kề 2,2%; nay −0,3%, ngang các quý khác). ROE quý 4/2025 của FPT từ 28,29% thành 27,25%. Dòng năm không đổi. - **Mô tả ROE trong `fa.describe()`**: Bỏ câu nói hồ sơ `vn` đổi mẫu số từ năm 2022; ROE luôn chia cho vốn chủ của cổ đông công ty mẹ bình quân. - **`fa.Dataset.load()` khi chưa tải được giá**: Nếu cấp của `vnstock` chưa mở giá chưa điều chỉnh, thư viện cảnh báo một lần và vẫn tính các chỉ số từ báo cáo tài chính; chỉ số định giá trả `MISSING_MARKET`. Dùng `prices=False` để bỏ qua bước tải giá. #### Thay đổi khác - **Vi cấu trúc (`micro`)**: Mỗi lần gọi một hàm tính là một lượt, kể cả hàm chạy nhiều bước bên trong như `bars` và `cvd`. - **Đo lượt dùng**: Thư viện không còn hỏi đồng ý đo lượt dùng ở lần chạy đầu. Lựa chọn đặt trên vnstocks.com, mục tùy chọn dữ liệu của tài khoản; chưa chọn thì không đo. Tắt riêng trên máy bằng `vnstock_quant.telemetry.disable()` hoặc biến môi trường `VNSTOCK_TELEMETRY=0`. ## 17-10-2026 ### vnstock_quant (v0.4.0) #### Dữ liệu khung phút - **VWAP và pivots**: Đọc được cột thời gian dạng `dd/mm/YYYY HH:MM` và `dd/mm/YYYY HH:MM:SS`. - **Chỉ số tài chính (`fa`)**: Bảng giá theo phút được đọc thành một phiên mỗi ngày, lấy giá của nến cuối ngày (kể cả phiên ATC). Bảng giá ngày không đổi. #### Thay đổi khác - **Thông báo lỗi**: `vwap` với `anchor` không hợp lệ báo `InvalidParameterError` bằng tiếng Việt, giống `micro.cvd`. - **Chú thích hàm**: Chú thích viết bằng tiếng Anh; mô tả ngắn của 58 chỉ báo viết song ngữ (tiếng Anh trước, tiếng Việt sau). Công thức và phương pháp chi tiết xem ở các trang tài liệu. - **Đo lượt dùng**: Câu hỏi đồng ý đo lượt dùng ở lần chạy đầu thống nhất giữa các thư viện thế hệ 5. ## 10-10-2026 ### vnstock_quant (v0.1.3) - **Thư viện xác thực**: Ghim `vnstock-auth` ở bản 0.5.1, thống nhất với các thư viện thế hệ 5 khác. Không đổi cách tính. ## 09-10-2026 ### vnstock_quant (v0.1.2) - **Giữ chỉ mục đầu vào**: Kết quả chỉ báo giữ nguyên chỉ mục của bảng bạn truyền vào. Cột thời gian chỉ được dùng cho `vwap` và `pivots`. - **Nhận cột thời gian**: Với bảng dữ liệu thô, thư viện tự nhận cột thời gian và chuyển thành `DatetimeIndex`. - **Gọi lớp chính gọn hơn**: Các lớp chính nhập được thẳng từ `vnstock_quant`; thông báo lỗi rõ hơn khi thiếu cột. ## 08-10-2026 ### vnstock_quant (v0.1.1) - **Hạn dùng bản phát hành**: Thư viện kiểm tra hạn dùng của bản cài trước khi tính; thông tin hạn dùng xem ở `vq.entitlement()["release"]`. - **Chú thích song ngữ**: Chú thích hàm của các mô-đun `ta`, `fa`, `risk`, `portfolio`, `valuation` có cả tiếng Việt và tiếng Anh. - **Bản hết hạn**: Bản đã hết hạn báo lỗi `VNSTOCK_RELEASE_EXPIRED` kèm lệnh cập nhật. ### vnstock_quant (v0.1.0) #### Bản phát hành đầu tiên của Vnstock Quant thế hệ 5 - **Dùng thử mỗi ngày**: Bản Cộng đồng có 30 lượt dùng thử (30 phép tính) mỗi ngày cho 10 chỉ báo kỹ thuật cơ bản và 10 chỉ số tài chính VAS. Tra cứu số lượt còn lại bằng `vnstock_quant.entitlement()` (khoá `trial`). - **Gói cài đặt dựng sẵn**: Gói nhị phân dựng sẵn (binary wheels) dùng chung cho Python 3.10 trở lên, trên macOS (Intel và Apple Silicon) và Linux x86_64/aarch64 dùng glibc 2.17 trở lên. - **Đối chiếu chỉ báo**: Kết quả 58 chỉ báo kỹ thuật được đối chiếu với TA-Lib C 0.8.1 và QuantConnect LEAN. - **Kiểm tra tham số**: Tham số nến không hợp lệ báo lỗi `InvalidParameterError` thay vì trả kết quả sai lệch. - **Tái cấu trúc từ vnstock_ta sang vnstock_quant**: Gộp và nâng cấp thư viện `vnstock_ta` sang namespace mới `vnstock_quant` với lõi tính toán biên dịch bằng Rust (`_native.abi3.so`). - **58 chỉ báo kỹ thuật hiệu năng cao**: Tính đủ 58 chỉ báo nhanh hơn 25,9 lần so với phiên bản cũ (5.000 phiên, số đo tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026); lõi Rust nhả khoá GIL của Python trong lúc tính. - **Khắc phục lỗi thuật toán**: Sửa 16 chỉ báo bị sai lệch công thức trong phiên bản cũ (bao gồm CCI, KST, PSAR, Supertrend, Squeeze, OBV, MFI). - **Giữ cú pháp gọi hàm**: Lớp `Indicator` giữ nguyên tên 58 phương thức chỉ báo, tên và giá trị mặc định của tham số; chuyển đổi bằng cách đổi tên gói khi import. Một số chỉ báo cho số khác bản cũ, xem [danh sách khác biệt](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta). #### Giao diện gọi hàm JSON cho trợ lý AI - **Chẩn đoán cấp quyền và bản build**: Bổ sung hai hàm chẩn đoán chạy cục bộ `vq.entitlement()` và `vq.build_info()`, hỗ trợ theo dõi lượt dùng thử của bản Cộng đồng và kiểm tra tính toàn vẹn của lõi Rust. --- ## Document: Đối chiếu kết quả và tốc độ Trang này ghi các mốc dùng để đối chiếu kết quả của `vnstock_quant` và điều kiện của những phép đo tốc độ. Khi đọc bảng sai số, hãy xem từng hàm được so với nguồn nào, trên bộ dữ liệu nào và theo quy ước tính nào. Số đo tốc độ chỉ phản ánh môi trường thử nghiệm đã ghi, không dự báo thời gian chạy trên máy của bạn. --- ## 1. Phạm vi kiểm tra ### Các nhóm hàm được kiểm tra Các kết quả dưới đây bao phủ năm nhóm hàm của 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`. - **100 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. ### Điều kiện cài đặt và tính toán - **Gói cài dựng sẵn**: Bạn 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. Bạn không cần cài TA-Lib C để tính chỉ báo. - **Phần lõi Rust**: Các phép tính đi qua cùng một phần lõi, không đổi cách tính theo việc máy có cài TA-Lib C hay không. - **So sánh kết quả**: Muốn kiểm tra một số đo, hãy dùng cùng dữ liệu đầu vào và cùng quy ước về kỳ tính, dữ liệu thiếu và giai đoạn đầu chuỗi. --- ## 2. Hệ thống mốc chuẩn đối chiếu thực nghiệm Các nhóm phép tính được đối chiếu với những nguồn sau: | Mốc kiểm định | Phạm vi đối chiếu | Tiêu chí đánh giá | | :--- | :--- | :--- | | **TA-Lib C Core 0.8.1** | 34 chỉ báo kỹ thuật cổ điển | Thư viện chỉ báo C phổ biến; sai số tương đối $\le 10^{-12}$ | | **QuantConnect LEAN** | 14 chỉ báo kỹ thuật nâng cao & dữ liệu SPY | Bộ dữ liệu kiểm thử chỉ báo của LEAN; sai số $\le 10^{-8}$ | | **CFA® Program Curriculum** | 100 chỉ số BCTC VAS, phân rã rủi ro Euler, MWR | Chuẩn mực phân tích tài chính và quản lý tài sản toàn cầu | | **empyrical-reloaded & QuantStats** | 33 thước đo rủi ro và hiệu suất | Khung định lượng kiểm nghiệm chéo các hệ số Sharpe, Sortino, VaR | | **pyxirr** | Hội tụ lợi suất theo dòng tiền (XIRR/MWR) | Kiểm định nghiệm số hội tụ với thuật toán Newton-Raphson | | **NumPy & SciPy** | Các kiểm định thống kê và phân phối xác suất | Độ lệch chuẩn mẫu, Kurtosis, Skewness | --- ## 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. ### Các mức đối chiếu 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)**: Được đối chiếu với **TA-Lib C core 0.8.1**, với sai số tương đối được ghi nhận từ $0.0\text{e}+00$ đến $10^{-12}$ trên dữ liệu kiểm tra. - **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ũ: | Chỉ báo | Nhóm | Mức tin cậy | Chuẩn đối chiếu | Sai số vs TA-Lib C | Đối chiếu LEAN / Định nghĩa gốc | So với thế hệ cũ | | :--- | :--- | :---: | :--- | :---: | :--- | :--- | | `sma` | Trend | A | TA-Lib SMA | **0.0e+00** | — | Khớp chuẩn (1.2e-15) | | `ema` | Trend | A | TA-Lib EMA | **0.0e+00** | LEAN `spy_ema.csv`: 5.7e-14 | Khớp chuẩn (3.8e-16) | | `wma` | Trend | A | TA-Lib WMA | 4.2e-15 | — | Khớp chuẩn (2.2e-16) | | `hma` | Trend | A | Alan Hull / TA-Lib | 1.5e-14 | LEAN `spy_hma.txt`: 5.0e-08 | Khớp chuẩn (5.0e-16) | | `smma` | Trend | A | J. Welles Wilder RMA | 9.2e-16 | — | Khớp chuẩn (0.0e+00) | | `alma` | Trend | B | Arnaud Legoux / LEAN | — | LEAN `spy_alma.txt`: 5.0e-08 | Khớp chuẩn (3.6e-16) | | `vwma` | Trend | B | LEAN VWMA | — | LEAN `spy_with_vwma.csv`: 2.8e-14 | Khớp chuẩn (5.1e-16) | | `adx` | Trend | A | Wilder ADX/DI | **0.0e+00** | LEAN `spy_with_adx.txt`: hội tụ $\le 0.01$ | Khắc phục lệch khởi động | | `psar` | Trend | A | TA-Lib SAREXT / LEAN | **0.0e+00** | LEAN `spy_sarext.txt`: 5.7e-14 | **Đã sửa lỗi logic** | | `supertrend` | Trend | B | TradingView / LEAN | — | LEAN `dwac_supertrend.txt`: 5.0e-08 | **Đã sửa lỗi logic** | | `dm` | Trend | A | TA-Lib PLUS/MINUS_DM | **0.0e+00** | Wilder sums | **Đã sửa lỗi sai lệch** | | `linreg` | Trend | A | TA-Lib LINEARREG | 6.6e-14 | — | Khớp chuẩn (2.0e-15) | | `aroon` | Trend | A | TA-Lib AROON | **0.0e+00** | — | Khớp chuẩn (1.4e-15) | | `rsi` | Momentum | A | TA-Lib RSI (Wilder) | **0.0e+00** | LEAN `spy_with_indicators.txt`: 5.0e-06 | Khắc phục lệch khởi động | | `stoch` | Momentum | A | TA-Lib STOCH | **0.0e+00** | LEAN `spy_with_stoch12k3.txt`: 3.7e-04 | Khớp chuẩn (1.1e-13) | | `stochrsi` | Momentum | A | TradingView / TA-Lib | **0.0e+00** | LEAN `spy_with_StochRSI.csv`: 3.6e-13 | Khắc phục lệch khởi động | | `mom` | Momentum | A | TA-Lib MOM | **0.0e+00** | — | Khớp chuẩn (0.0e+00) | | `roc` | Momentum | A | TA-Lib ROC | **0.0e+00** | LEAN `spy_with_rocp50.txt`: 1.0e-05 | Khớp chuẩn (1.1e-14) | | `ao` | Momentum | B | Bill Williams / LEAN | — | LEAN `spy_ao.txt`: 4.8e-13 | Khớp chuẩn (3.8e-11) | | `cci` | Momentum | A | Donald Lambert CCI | 1.7e-12 | LEAN `spy_with_cci.txt`: 2.2e-03 | **Đã sửa lỗi Mean Deviation** | | `willr` | Momentum | A | Larry Williams %R | **0.0e+00** | LEAN `spy_with_williamsR14.txt`: 4.0e-04 | Khớp chuẩn (3.4e-15) | | `tsi` | Momentum | B | William Blau / LEAN | — | LEAN `spy_tsi.csv`: 2.1e-14 | Khắc phục lệch khởi động | | `cmo` | Momentum | A | Chande Momentum Osc | 2.7e-16 | Chuẩn Chande unsmoothed | **Đã sửa lỗi logic** | | `uo` | Momentum | A | Larry Williams ULTOSC | **0.0e+00** | LEAN `spy_ultosc.txt`: 5.7e-14 | Khớp chuẩn (2.2e-16) | | `fisher` | Momentum | C | John Ehlers Transform | — | Công thức Ehlers gốc: sai số $\le 10^{-9}$ | Khắc phục lệch khởi động | | `cg` | Momentum | C | Ehlers Center of Gravity | — | Công thức Ehlers gốc: sai số $\le 10^{-9}$ | **Đã sửa lỗi tính toán** | | `kst` | Momentum | B | Martin Pring / LEAN | — | LEAN `spy_with_kst.csv`: 8.5e-14 | **Đã sửa lỗi trọng số** | | `macd` | Momentum | A | Gerald Appel MACD | **0.0e+00** | LEAN `spy_with_macd.txt`: 5.0e-06 | Khắc phục lệch khởi động | | `bbands` | Volatility | A | TA-Lib BBANDS | **0.0e+00** | LEAN `spy_bollinger_bands.txt`: 1.1e-04 | Khớp chuẩn (8.9e-12) | | `kc` | Volatility | B | Chester Keltner / TV | — | Công thức Keltner chuẩn True Range | Khớp chuẩn (3.7e-16) | | `atr` | Volatility | A | TA-Lib ATR (Wilder) | **0.0e+00** | Wilder RMA trên True Range | Khắc phục lệch khởi động | | `stdev` | Volatility | A | TA-Lib STDDEV | **0.0e+00** | Phương sai tổng thể (ddof=0) | **Đã sửa lỗi bậc tự do** | | `donchian` | Volatility | A | Richard Donchian | **0.0e+00** | LEAN `spy_with_don50.txt`: 0.0e+00 | Khớp chuẩn (0.0e+00) | | `true_range` | Volatility | A | TA-Lib TRANGE | **0.0e+00** | LEAN `spy_tr.txt`: 7.1e-15 | Khớp chuẩn (0.0e+00) | | `squeeze` | Volatility | C | John Carter TTM Squeeze | — | LazyBear TTM Squeeze: sai số $\le 10^{-7}$ | **Đã sửa lỗi đảo dải Keltner** | | `squeeze_pro` | Volatility | C | Carter TTM Squeeze Pro | — | Đa ngưỡng Keltner (2.0 / 1.5 / 1.0) | **Đã sửa lỗi momentum** | | `obv` | Volume | A | Joe Granville OBV | **0.0e+00** | LEAN `spy_with_obv.txt`: 1.0e-04 | **Đã sửa lỗi nến đứng giá** | | `cmf` | Volume | B | Marc Chaikin CMF | — | LEAN `spy_cmf.txt`: 1.5e-06 | Khớp chuẩn (2.8e-14) | | `ad` | Volume | A | Chaikin A/D Line | **0.0e+00** | LEAN `spy_ad.txt`: 5.0e-06 | Khớp chuẩn (6.9e-14) | | `vp` | Volume | C | Volume Profile | — | Bất biến bảo toàn tổng khối lượng | **Đã sửa lỗi phân bổ bin** | | `vwap` | Volume | B | Anchored Intraday VWAP | — | Nhóm chu kỳ Ngày / Tuần / Tháng: $\le 10^{-9}$ | Khớp chuẩn (0.0e+00) | | `pvo` | Volume | A | Percentage Volume Osc | **0.0e+00** | TA-Lib PPO trên khối lượng | Khắc phục lệch khởi động | | `mfi` | Volume | A | Money Flow Index | 8.9e-14 | Chuẩn Gene Quong & Avrum Soudack | **Đã sửa lỗi mẫu số 0** | | `pivots` | Statistics | C | Pivot Points Standard | — | Traditional, Woodie, DeMark chuẩn | **Đã sửa lỗi khung thời gian** | | `variance` | Statistics | A | TA-Lib VAR | **0.0e+00** | LEAN `spy_var.txt`: 1.1e-10 | **Đã sửa lỗi bậc tự do** | | `hl2` | Statistics | A | TA-Lib MEDPRICE | **0.0e+00** | $(H + L) / 2$ | Khớp chuẩn (0.0e+00) | | `hlc3` | Statistics | A | TA-Lib TYPPRICE | **0.0e+00** | $(H + L + C) / 3$ | Khớp chuẩn (0.0e+00) | | `ohlc4` | Statistics | A | TA-Lib AVGPRICE | **0.0e+00** | $(O + H + L + C) / 4$ | Khớp chuẩn (3.1e-16) | | `midprice` | Statistics | A | TA-Lib MIDPRICE | **0.0e+00** | LEAN `spy_midprice.txt`: 2.8e-14 | Khớp chuẩn (0.0e+00) | *(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 tốc độ xử lý khi tính toàn bộ 58 chỉ báo cho cùng một mã cổ phiếu (5.000 phiên): | Thư viện thực thi | Thời gian xử lý (58 chỉ báo) | Tương quan tốc độ so với thế hệ cũ | Định dạng đầu ra | | :--- | :---: | :---: | :--- | | **`vnstock_quant` (Lõi Rust)** | **1.79 ms** | **Nhanh hơn 77.4x** | Bộ đệm số nguyên/thực phẳng | | **`vnstock_quant` (API chuẩn)** | **5.34 ms** | **Nhanh hơn 25.9x** | `pandas.DataFrame` có đủ index & tên cột | | `pandas-ta` (Python + Numba) | 127.0 ms | Chậm hơn | `pandas.DataFrame` | | `vnstock_ta` thế hệ cũ | 138.5 ms | Mốc cơ sở (1.0x) | `pandas.DataFrame` |

Ở tốc độ 5.34 ms, phần tính 58 chỉ báo cho một cổ phiếu chiếm rất ít thời gian so với việc tải dữ liệu, nên bạn có thể tính lại chỉ báo cho chuỗi nhiều năm mỗi khi dữ liệu cập nhật.

### 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}$: | Chỉ báo kỹ thuật | `vnstock_quant` (API) | Lõi Rust thuần | `vnstock_ta` thế hệ cũ | Mức tăng tốc độ | | :--- | :---: | :---: | :---: | :---: | | `sma` | 21.4 µs | 7.1 µs | 317.0 µs | **14.8x** | | `ema` | 22.6 µs | 8.4 µs | 92.6 µs | **4.1x** | | `smma` (RMA) | 35.3 µs | 19.8 µs | 20.224.0 µs | **573.0x** | | `adx` | 144.0 µs | 96.5 µs | 2.300.0 µs | **15.9x** | | `supertrend` | 86.2 µs | 38.6 µs | 29.790.0 µs | **346.0x** | | `rsi` | 28.1 µs | 15.2 µs | 366.0 µs | **13.0x** | | `cci` | 57.1 µs | 31.4 µs | 13.088.0 µs | **229.0x** | | `linreg` | 42.0 µs | 31.5 µs | 9.893.0 µs | **235.0x** | | `psar` | 71.0 µs | 16.8 µs | 3.124.0 µs | **44.0x** | | `macd` | 58.8 µs | 29.8 µs | 604.0 µs | **10.3x** | | `bbands` | 67.4 µs | 28.5 µs | 640.0 µs | **9.5x** | | `atr` | 34.7 µs | 9.7 µs | 660.0 µs | **19.0x** | ### 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ớ): | Thư viện thực hiện | Thời gian xử lý toàn bộ 1.600 mã | Thời gian trung bình mỗi mã | | :--- | :---: | :---: | | **`vnstock_quant`** | **1.21 giây** | **0.75 ms / mã** | | `vnstock_ta` thế hệ cũ | 14.01 giây | 8.76 ms / mã | | `pandas-ta` | 12.76 giây | 7.97 ms / mã | 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: ```text 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 Ngoài chỉ báo kỹ thuật, các phần về báo cáo tài chính, danh mục và rủi ro cũng được đối chiếu theo những quy ước nêu dưới đây. ### 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) theo CFA tính trên tài sản và vốn chủ bình quân. `vnstock_quant` dùng bình quân đầu năm và cuối năm cho kỳ năm, và bình quân 4 điểm cuối quý (hồ sơ `cfa`: 5 điểm) cho kỳ quý, kể cả quý 4. 3. **Minh bạch bằng cột `reason`**: Thư viện không tự điền số 0 khi thiếu dữ liệu. Ô không có số mang mã lý do trong cột `reason`, ví dụ `INSUFFICIENT_HISTORY` khi doanh nghiệp chưa đủ 4 quý lịch sử, `MISSING_INPUT:` khi thiếu chỉ tiêu, `NOT_APPLICABLE` khi chỉ số không dành cho mẫu ngành đó, để bộ lọc tự động của bạn nhận biết và bỏ qua. Mẫu số âm (ví dụ vốn chủ âm do lỗ luỹ kế) vẫn cho ra số âm, nên hãy kiểm tra dấu của mẫu số khi sàng lọc theo ROE hay P/B. ### 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í giao dịch $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 | Tiêu chí | `vnstock_ta` 1.x hoặc tự ghép nhiều thư viện | Vnstock Quant thế hệ 5 | | :--- | :--- | :--- | | **Cài đặt & Môi trường** | Một số gói cần trình biên dịch C hoặc TA-Lib C, tuỳ máy | Gói nhị phân dựng sẵn, cài trong 1 lệnh duy nhất | | **Kiến trúc phát triển** | Ghép 4–5 thư viện riêng, mỗi thư viện một quy ước | **Lõi Rust an toàn bộ nhớ kết hợp lớp bọc Python tinh gọn** | | **Thời gian xử lý** | 138.5 ms (58 chỉ báo) | **5.34 ms (Nhanh hơn 25.9 lần)** | | **Xử lý quy mô toàn sàn** | 14.0 giây (1.600 mã) | **1.21 giây (Nhanh hơn 11.6 lần)** | | **Độ tin cậy số học** | `vnstock_ta` 1.x: 16 chỉ báo lệch định nghĩa gốc | 34 chỉ báo khớp **TA-Lib C**, 14 chỉ báo khớp dữ liệu kiểm thử **QuantConnect LEAN** | | **Quy chuẩn tài chính** | Tuỳ thư viện | Chuẩn hoá theo **CFA® Institute Curriculum** | | **Đặc thù thị trường VN** | Thường chưa có sẵn quy ước riêng cho Việt Nam | Tích hợp lô 100, biên độ trần/sàn, thuế phí Việt Nam | | **Hỗ trợ AI Agent** | Tuỳ thư viện | Sẵn sàng tích hợp qua hệ sinh thái kỹ năng vnai | `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](/docs/vnstock_quant/free/tinh-toan/ta) — Tính toán 58 chỉ báo kỹ thuật với lõi Rust. - [Chỉ số tài chính](/docs/vnstock_quant/free/tinh-toan/fa) — Tự tính 100 chỉ số BCTC VAS và mô hình dòng tiền CFA. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — 33 thước đo hiệu suất và rủi ro chuẩn CFA. - [Chuyển đổi từ vnstock_ta](/docs/vnstock_quant/free/chuyen-doi/tu-vnstock-ta) — Hướng dẫn nâng cấp từ vnstock_ta 1.x sang vnstock_quant. --- ## Document: Gọi bằng JSON và MCP > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Các hàm danh mục, định giá và backtest của `vnstock_quant` gọi được bằng **tên hàm cộng một đối tượng JSON tham số**, và trả về JSON. Mỗi hàm có JSON Schema mô tả tham số, nên dùng trực tiếp làm định nghĩa công cụ cho trợ lý AI (MCP, function calling) mà không cần viết lớp chuyển đổi. Lời gọi JSON đi qua cùng lõi Rust và cùng bước kiểm tra quyền như hàm Python, nên một máy chủ MCP chạy trên máy bạn vẫn theo đúng cấp của bạn. | Nhóm | `catalog()` | `schema(name)` | `call(name, **args)` | | :--- | :---: | :---: | :---: | | `portfolio` (gồm các hàm định giá) | Có | Có | Có | | `backtest` | Có | Có | Có | | `ta`, `fa`, `risk`, `micro` | Có | | Dùng hàm Python thường | --- ## Catalog và schema ```python from vnstock_quant import portfolio as pm cat = pm.catalog() # name, group, describe, standard cat.groupby("group").size() # construct, fees, holdings, returns, risk, valuation pm.schema("twr") # {'name': 'twr', 'group': 'returns', 'describe': '...', 'standard': 'CFA L1 QM LM1 p.32–33, Eq.6', # 'parameters': {'type': 'object', 'properties': {...}, 'required': ['dates', 'values']}} ``` Mỗi tham số trong `parameters.properties` có `type`, `description` và `default` nếu có. Trường `standard` ghi chuẩn hoặc tài liệu gốc của phép tính. Định nghĩa công cụ cho mọi hàm danh mục và định giá: ```python tools = [ {"name": s["name"], "description": s["describe"], "input_schema": s["parameters"]} for s in (pm.schema(n) for n in pm.catalog()["name"]) ] len(tools) # 38 ``` Mô-đun backtest có 10 công cụ cùng dạng, schema ghi theo cách MCP đặt tên (`name`, `description`, `input_schema`): ```python from vnstock_quant import backtest as bt list(bt.catalog()["name"]) # ['list_brokers', 'list_profiles', 'list_presets', 'list_indicators', 'eval_rule_dsl', # 'check_rule_dsl_causality', 'detect_limit_events', 'run_backtest', 'run_fixture_demo', 'portfolio_analytics'] bt.schema("run_backtest")["input_schema"]["required"] # ['bars'] ``` --- ## Gọi hàm ```python pm.call("annualize", r=0.20, days=548) # {'value': 0.1290..., 'exponent': 0.666...} pm.call("ddm", r=0.15, d0=5000, stages=[[0.10, 3]], terminal_g=0.05) pm.call( "twr", dates=[19724, 19877, 20090], # số ngày kể từ 1970-01-01 values=[100e6, 112e6, 150e6], flows=[0, 30e6, 0], ) ``` Với backtest, nến đi vào dưới dạng danh sách đối tượng (`date` theo `YYYY-MM-DD`, `open`, `high`, `low`, `close`, `volume`) và bảng quy tắc là đối tượng JSON, đúng dạng trợ lý AI tạo ra từ một câu mô tả: ```python bars = [ {"date": "2024-01-02", "open": 50.0, "high": 50.5, "low": 49.5, "close": 50.2, "volume": 100000}, # ... các phiên tiếp theo, thứ tự thời gian tăng dần ] res = bt.call( "run_backtest", bars=bars, dsl={"entry_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}], "exit_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}]}, stop_loss_pct=0.07, ) res.keys() # tear_sheet, trades, rejected_orders, open_positions, warnings res["tear_sheet"]["total_return_pct"], res["tear_sheet"]["sharpe_ratio"] ``` Quy ước của lời gọi JSON: - Ngày là số ngày kể từ 01/01/1970 với các hàm danh mục, chuỗi `YYYY-MM-DD` với các công cụ backtest. - Mảng là danh sách số; ma trận là danh sách các hàng. - Tỷ lệ là phân số: `0.18` nghĩa là 18%. - Tham số lạ bị từ chối, để trợ lý AI biết mình gọi sai. - Lỗi trả về có mã ổn định (`QUANT_INVALID_PARAMETER`, `QUANT_INPUT_DATA`, `QUANT_UNKNOWN_FUNCTION`, `QUANT_UNKNOWN_TOOL`) và thông điệp nói rõ tham số nào sai, nhờ đó trợ lý AI tự sửa được lời gọi. ```python from vnstock_quant.errors import InvalidParameterError try: pm.call("twr", dates=[0, 1], values=[1, 2], bogus=1) except InvalidParameterError as e: print(e.code, e) # QUANT_INVALID_PARAMETER [QUANT_INVALID_PARAMETER] `twr` không có tham số `bogus` ``` --- ## Catalog đọc được bằng máy của các nhóm còn lại `ta`, `fa`, `risk` và `micro` dùng hàm Python thường, nhưng catalog của chúng cũng là bảng có cấu trúc để trợ lý AI tra tên, đơn vị và chuẩn đối chiếu trước khi viết mã: ```python from vnstock_quant import fa, risk, ta ta.catalog()[["name", "group", "standard", "confidence"]].head() risk.catalog().to_dict("records")[:2] # name, benchmark, unit, describe, standard fa.catalog()[["id", "describe", "unit", "access"]].head() fa.describe("RT_PRT_ROE") # công thức theo mẫu ngành và hồ sơ ``` --- ## Vnstock MCP [Vnstock MCP](/vnstock-mcp) là máy chủ MCP chạy trên máy bạn, đưa các hàm của `vnstock_quant` tới trợ lý AI dưới dạng công cụ: `quant_ta`, `quant_fa`, `quant_risk`, `quant_portfolio`, `quant_valuation`, `quant_backtest`, cùng `quant_catalog(module, name)` để tra tham số và `quant_entitlement` để xem cấp. Dữ liệu đi vào công cụ là bảng đã tải trong phiên làm việc của MCP, nên trợ lý không phải chép số qua lời nhắc. Quyền và lượt thử giống như khi bạn gọi hàm Python. Danh mục công cụ và hồ sơ (profile) nào bật nhóm nào: [Danh mục công cụ Vnstock MCP](/docs/vnstock-mcp/danh-muc-cong-cu). --- ## Quyền `portfolio` và `valuation` cần cấp Bronze; backtest một mã với 10 chỉ báo cơ bản mở cho mọi cấp theo lượt thử, các công cụ còn lại của backtest từ Bronze. Bảng đầy đủ: [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc). --- ## Đọc tiếp - [Danh mục](/docs/vnstock_quant/tinh-toan/portfolio) — Ý nghĩa và cách dùng của 38 hàm trong catalog. - [Dữ liệu và tín hiệu trong backtest](/docs/vnstock_quant/free/backtest/du-lieu-va-tin-hieu) — Cấu trúc bảng quy tắc `rule_dsl`. - [Hướng dẫn cho trợ lý AI](/onboard/agent-guide) — Thiết lập môi trường làm việc với trợ lý AI. --- ## Document: Tải dữ liệu bằng vnstock `vnstock_quant` không truy xuất dữ liệu: bạn đưa bảng `pandas` vào. Khi đã cài `vnstock` thế hệ 5 cùng môi trường, mỗi nhóm hàm có một điểm vào tải dữ liệu đúng dạng cần dùng. Dữ liệu tải qua `vnstock` tính vào hạn mức chung của tài khoản theo quy tắc của `vnstock`; phần tính toán sau đó chạy trên máy và không tốn hạn mức. ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant[vnstock]" ``` Thiếu `vnstock` thế hệ 5 thì các điểm vào dưới đây báo `DependencyError` với lệnh cài trong `action`. --- ## Điểm vào theo nhóm hàm | Cần gì | Gọi | Trả về | Mức | | :--- | :--- | :--- | :--- | | Nến cho chỉ báo kỹ thuật | `ta.from_vnstock(symbol, start, end, interval="1D")` | `Indicator` đã nạp nến, tính ngay được | Ổn định | | Lợi suất của mã và chỉ số tham chiếu | `risk.from_vnstock(symbol, benchmark="VNINDEX", start)` | `DataFrame` hai cột `returns`, `benchmark`, căn theo ngày chung | Thử nghiệm | | Báo cáo tài chính, giá và số cổ phiếu cho chỉ số tài chính | `fa.Dataset.load(symbols, period="both")` | `Dataset` cho `fa.ratios()` | Thử nghiệm | | Giá đã điều chỉnh theo sự kiện quyền | `prices.from_vnstock(symbol, start)` | OHLCV đơn vị đồng, bảng hệ số trong `attrs["factors"]` | Thử nghiệm | | Nến cho backtest | `Market().equity(symbol).ohlcv(start, end)` của `vnstock` | Bảng nến đưa thẳng vào `backtest.run()` | Thử nghiệm | | Dữ liệu khớp lệnh cho vi cấu trúc | `Market().equity(symbol).trades(limit=1000)` của `vnstock` | Bảng tick cho `micro.bars()` | Thử nghiệm | Cột **Mức** là mức ổn định của nhóm hàm nhận dữ liệu đó: nhóm thử nghiệm còn có thể đổi tên hàm, tham số và cấu trúc kết quả giữa các bản phát hành. Xem [mức độ ổn định của từng nhóm hàm](/docs/vnstock_quant/free/gioi-thieu#muc-do-on-dinh-cua-tung-nhom-ham). ```python from vnstock_quant import fa, prices, risk, ta ind = ta.from_vnstock("HPG", start="2024-01-01", end="2024-12-31") rsi = ind.rsi(length=14) data = risk.from_vnstock("FPT", benchmark="VNINDEX", start="2022-01-01") beta = risk.beta(data["returns"], data["benchmark"]) ds = fa.Dataset.load(["FPT", "VCB"]) roe = fa.ratios(ds, ids=["RT_PRT_ROE"]) bars = prices.from_vnstock("FPT", start="2019-01-01") # giá đã điều chỉnh, đơn vị đồng ``` Backtest và vi cấu trúc nhận bảng thô của `vnstock`: ```python from vnstock import Market from vnstock_quant import backtest as bt, micro df = Market().equity("FPT").ohlcv(start="2021-01-01", end="2026-09-30") res = bt.run(df, entries=df["close"] > df["close"].rolling(200).mean(), exits=df["close"] < df["close"].rolling(50).mean()) ticks = Market().equity("FPT").trades(limit=1000) m1 = micro.bars(ticks, by="time", size="1min") ``` --- ## Điều cần biết trước khi tải | Chủ đề | Chi tiết | | :--- | :--- | | **Đơn vị giá** | `ohlcv()` trả giá tính bằng nghìn đồng; `trade_history()` và `prices.from_vnstock` trả đồng. `backtest.run` có `price_unit="auto"` để nhận ra; `prices.adjust` có `unit="auto"`. Trong một phiên làm việc hãy giữ một đơn vị. | | **Chuỗi dài** | `vnstock` trả tối đa 1.000 phiên hoặc 1.000 lệnh mỗi lần gọi. `risk.from_vnstock` và `prices.from_vnstock` tự tải theo cửa sổ ba năm; với `ohlcv()` bạn tự chia khoảng ngày. | | **Số mã mỗi lần tải báo cáo tài chính** | Cộng đồng 3, Bronze 100, Silver 400, Golden và Diamond toàn thị trường; vượt thì `TierRequiredError` với mã `QUANT_SCOPE_LIMIT`. | | **Giá chưa điều chỉnh cho chỉ số định giá** | Cần cấp quyền sử dụng của `vnstock`. Bản Cộng đồng gọi `Dataset.load(..., prices=False)`; P/E, P/B khi đó báo `MISSING_MARKET` ở cột `reason`. | | **Dữ liệu đã điều chỉnh hay chưa** | `ohlcv()` là giá đã điều chỉnh theo nguồn; `trade_history()` là giá thô kèm giá tham chiếu, trần, sàn. Muốn kiểm từng sự kiện quyền thì đi đường `prices`. | | **Hạn mức chung** | Mỗi lần tải là lượt gọi của `vnstock`; `Dataset.load()` tải nhiều bảng cho mỗi mã. Xem mức còn lại ở [trang tài khoản](/account). | Khi làm việc lặp lại trên cùng dữ liệu, lưu bảng ra đĩa hoặc để [vnstock_pipeline](/docs/vnstock-pipeline) lưu vào kho rồi đọc lại; `vnstock_quant` nhận `DataFrame` từ bất kỳ nguồn nào bạn đã chuẩn bị. --- ## Đọc tiếp - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/free/bat-dau/quy-uoc-du-lieu-va-loi) — Dạng dữ liệu mà từng nhóm hàm nhận. - [Quyền dùng và hạn mức](/docs/vnstock_quant/free/bat-dau/quyen-dung-va-han-muc) — Số mã theo cấp và lượt dùng thử. - [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh) — Khi nào cần đi đường `prices` thay cho `ohlcv()`. --- ## Document: Chỉ số tài chính > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.fa` tính 100 chỉ số từ báo cáo tài chính theo bốn mẫu ngành: doanh nghiệp phi tài chính (`dn`), ngân hàng (`tctd`), công ty chứng khoán (`ctck`) và bảo hiểm (`dnpnt`). Mỗi chỉ số chỉ áp dụng cho một số mẫu ngành; chỉ số không áp dụng trả `NaN` kèm lý do `NOT_APPLICABLE`. Bạn có thể tra công thức của từng chỉ số, chọn kỳ quý (TTM) hay kỳ năm, và xem vì sao một ô không có số. Bản Cộng đồng tính được 10 chỉ số cơ bản: `RT_VALUE_PE`, `RT_VALUE_PB`, `RT_VALUE_EPS`, `RT_VALUE_BVPS`, `RT_PRT_ROE`, `RT_PRT_ROA`, `RT_PRT_GROSS_MARGIN`, `RT_PRT_NET_MARGIN`, `RT_LQD_CR`, `RT_LEV_DE`. Các chỉ số còn lại cần gói Bronze trở lên (cột `access` của `fa.catalog()`). --- ## Cách tính kỳ quý (TTM) Với `period="quarter"`, mỗi dòng quý là số liệu 12 tháng gần nhất tính đến cuối quý đó: - **Chỉ tiêu thời kỳ** (doanh thu, lợi nhuận, dòng tiền): cộng 4 quý gần nhất. - **Chỉ tiêu thời điểm dùng làm mẫu số bình quân** (tài sản, vốn chủ, phải thu...): trung bình 4 điểm cuối quý gần nhất với hồ sơ `vn`, 5 điểm với hồ sơ `cfa`. - **Dòng quý 4** lấy số liệu từ BCTC năm của năm đó (đã kiểm toán): chỉ tiêu thời kỳ là số cả năm, giá trị cuối kỳ là số cuối năm. Mẫu số bình quân vẫn là 4 (hoặc 5) điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán, nên chuỗi quý không bị nhảy ở quý 4. - **Các quý đầu tiên** của dữ liệu trả `NaN` với lý do `INSUFFICIENT_HISTORY`: ba quý đầu chưa đủ 4 quý để cộng dồn, và quý 4 của năm đầu tiên chưa có cuối năm trước để tính bình quân. --- ## Chuẩn bị dữ liệu đầu vào với Dataset Lớp `Dataset` gom báo cáo tài chính, giá đóng cửa và số cổ phiếu lưu hành của các mã bạn chọn vào một đối tượng để các hàm tính toán dùng tiếp. ### Cách 1: Tải trực tiếp qua vnstock ```python from vnstock_quant import fa # Tải BCTC năm và quý, giá và số cổ phiếu của FPT và VCB ds = fa.Dataset.load(["FPT", "VCB"]) print(ds) # Dataset(FPT:DN, VCB:TCTD) ``` Mặc định `Dataset.load()` tải cả BCTC năm và quý (`period="both"`). Nên giữ mặc định này: dòng quý 4 cần BCTC năm, và `fa.ratios(..., period="year")` chỉ có số khi đã tải BCTC năm. Mẫu ngành được nhận diện tự động (`DN`, `TCTD`...); bạn có thể chỉ định bằng `com_type`.

Dataset.load() truy xuất nhiều bảng cho mỗi mã, nên có thể dùng nhiều lượt trong hạn mức chung. Bản Cộng đồng cho phép tối đa 3 mã trong một lần gọi và cần prices=False, vì giá chưa điều chỉnh cần cấp quyền sử dụng (xem trang bản Cộng đồng). Nếu cần xử lý nhiều mã, hãy chuẩn bị dữ liệu theo từng nhóm và cân nhắc lưu dữ liệu trên máy để dùng lại.

### Cách 2: Tự nạp từ DataFrame cá nhân Nếu bạn đã có sẵn dữ liệu BCTC, hãy nạp vào `Dataset` ở dạng long (các cột `period`, `id`, `value`), dùng mã chỉ tiêu của `vnstock`. Chỉ số dùng mẫu số bình quân (ROE, ROA...) cần ít nhất hai kỳ: ```python import pandas as pd from vnstock_quant import fa # Dữ liệu BCTC năm mẫu dạng long, hai năm liên tiếp rows = [] for period, revenue, npat, np_parent, equity, assets in [ ("2023", 1000e9, 150e9, 140e9, 1000e9, 1800e9), ("2024", 1200e9, 190e9, 180e9, 1200e9, 2000e9), ]: rows += [ {"period": period, "id": "IS_NET_REVENUE", "value": revenue}, {"period": period, "id": "IS_NET_PROFIT_AFTER_TAX", "value": npat}, {"period": period, "id": "IS_PROFIT_AFTER_TAX_FOR_SHAREHOLDERS_OF_PARENT_COMPANY", "value": np_parent}, {"period": period, "id": "BS_EQUITY", "value": equity}, {"period": period, "id": "BS_TOTAL_ASSETS", "value": assets}, ] ds_own = fa.Dataset.from_frames({"AAA": [pd.DataFrame(rows)]}, com_type="dn") # Dữ liệu chỉ có kỳ năm nên phải tính với period="year" print(fa.ratios(ds_own, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"], period="year")) ``` ```text symbol period id value unit reason 0 AAA 2023 RT_PRT_ROE NaN ratio INSUFFICIENT_HISTORY 1 AAA 2024 RT_PRT_ROE 0.163636 ratio NaN 2 AAA 2023 RT_PRT_ROA NaN ratio INSUFFICIENT_HISTORY 3 AAA 2024 RT_PRT_ROA 0.094737 ratio NaN 4 AAA 2023 RT_PRT_NET_MARGIN 0.150000 ratio NaN 5 AAA 2024 RT_PRT_NET_MARGIN 0.158333 ratio NaN ``` ROE năm 2024 = 180 / ((1.000 + 1.200) / 2) = 16,36%. Năm 2023 không có năm trước để tính vốn chủ bình quân nên trả `INSUFFICIENT_HISTORY`. Nếu gọi với `period="quarter"` (mặc định) trên dữ liệu chỉ có kỳ năm, kết quả là bảng rỗng. Để tính chỉ số định giá (P/E, P/B, EV/EBITDA...), truyền thêm `prices={"AAA": df_gia}` với các cột `time`, `close`, `total_shares`. --- ## Tính toán chỉ số với fa.ratios() ```python # Tính ROE, ROA và biên lợi nhuận ròng theo kỳ quý (TTM) ratios = fa.ratios(ds, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"]) # Xoay các chỉ số thành cột để đọc theo thời gian ts = fa.ratios(ds, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"], format="time_series") print(ts.loc["FPT"].tail(4)) ``` ```text id RT_PRT_NET_MARGIN RT_PRT_ROA RT_PRT_ROE period 2025-Q3 0.1591 0.1156 0.2737 2025-Q4 0.1602 0.1150 0.2725 2026-Q1 0.1670 0.1208 0.2682 2026-Q2 0.1718 0.1278 0.2647 ``` Kết quả dạng long được sắp theo mã, rồi theo chỉ số, rồi theo kỳ. Vì vậy `print(ratios)` thường chỉ hiện vài dòng đầu và cuối, đúng những ô `NaN`: các quý đầu chưa đủ lịch sử để tính TTM, và với VCB thì `RT_PRT_NET_MARGIN` không áp dụng cho ngân hàng (`NOT_APPLICABLE`). Bảng vẫn có số ở các kỳ khác. Để xem nhanh ô nào trống và vì sao: ```python # Đếm số ô trống theo mã, chỉ số và lý do print(ratios[ratios["value"].isna()].groupby(["symbol", "id", "reason"], observed=True).size()) ``` ### Các tham số quan trọng | Tham số | Giá trị lựa chọn | Ý nghĩa | | :--- | :--- | :--- | | `ids` | `["RT_..."]` hoặc `None` | Danh sách mã chỉ số cần tính. `None`: tính mọi chỉ số áp dụng được cho mẫu ngành của từng mã và cấp quyền của bạn; chỉ số cần cấp cao hơn bị bỏ qua kèm cảnh báo. | | `period` | `"quarter"` (mặc định) hoặc `"year"` | `"quarter"`: mỗi dòng là 12 tháng gần nhất (TTM), xem mục Cách tính kỳ quý. `"year"`: tính trên BCTC năm. | | `profile` | `"vn"` (mặc định) hoặc `"cfa"` | Hồ sơ phương pháp luận. `"vn"` theo cách thị trường Việt Nam công bố số liệu; `"cfa"` theo định nghĩa của giáo trình CFA. Xem `fa.profiles()`. | | `overrides` | `{"tên_nút": giá_trị}` | Thay một nút của hồ sơ, ví dụ `{"quarter_avg_points": 5}`. | | `format` | `"long"` (mặc định), `"wide"`, `"time_series"` | Định dạng kết quả. | Hai hồ sơ khác nhau ở các nút sau: | Nút | `vn` | `cfa` | | :--- | :--- | :--- | | `quarter_avg_points` | 4 điểm cuối quý | 5 điểm cuối quý (thêm cuối quý ngay trước cửa sổ 12 tháng) | | Ngày định giá | Phiên cuối cùng trước hoặc bằng ngày cuối quý kế tiếp + 14 ngày | Phiên cuối cùng trước hoặc bằng ngày cuối kỳ | Giá đóng cửa và số cổ phiếu luôn lấy trong cùng một phiên, nên P/E = giá / EPS và P/B = giá / BVPS trong cùng một dòng. Kỳ năm dùng ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4. Một số chỉ số có công thức riêng cho từng hồ sơ (ví dụ `RT_EFF_DIO` dùng tồn kho theo giá gốc với `vn`, giá trị thuần với `cfa`); `fa.describe()` ghi rõ. ### Định dạng đầu ra 1. **`format="long"` (mặc định)**: các cột `symbol`, `period`, `id`, `value`, `unit`, `reason`. Phù hợp để lưu trữ hoặc lọc: ```python ratios.query('symbol == "VCB" and id == "RT_PRT_ROE"').tail(4) ``` 2. **`format="wide"`**: chỉ mục là (`symbol`, `id`), mỗi kỳ là một cột, dễ đọc xu hướng qua các kỳ. 3. **`format="time_series"`**: chỉ mục là (`symbol`, `period`), mỗi chỉ số là một cột, thuận tiện đưa vào mô hình hồi quy hoặc học máy.

Kết quả của fa.ratios() mang từ điển mô tả ở attrs["dictionary"], nên bạn tra được ngay các mã viết tắt như COF, CIR, DIO, NIM.

```python info = ratios.attrs["dictionary"]["RT_BANK_COF"] print(info) # {'name': 'Chi phí vốn', 'name_en': 'Cost of funds', # 'describe': 'Chi phí lãi và tương tự (TTM, mang dấu âm) / nợ chịu lãi bình quân (nợ NHNN, tiền gửi và vay TCTD, tiền gửi khách hàng, giấy tờ có giá).', # 'unit': 'ratio', 'category': 'banking'} ``` --- ## Cột reason: vì sao một ô không có số `vnstock_quant` không tự điền số 0 khi thiếu dữ liệu đầu vào. Khi một ô mang giá trị `NaN`, cột `reason` cho biết nguyên nhân: | Mã `reason` | Giải thích | | :--- | :--- | | `MISSING_INPUT:` | BCTC thiếu chỉ tiêu `` mà công thức cần. Chỉ tiêu bắt đầu bằng `NT_` nằm trong thuyết minh BCTC (ví dụ nợ xấu, CASA của ngân hàng). | | `INSUFFICIENT_HISTORY` | Chưa đủ kỳ trước đó để cộng dồn TTM, tính bình quân hoặc so sánh với kỳ trước. | | `ZERO_DENOMINATOR` | Mẫu số bằng 0. Mẫu số âm (ví dụ vốn chủ âm) vẫn cho ra số âm, không trả `NaN`. | | `NOT_APPLICABLE` | Chỉ số không áp dụng cho mẫu ngành này (ví dụ biên lợi nhuận ròng với ngân hàng, NIM với doanh nghiệp phi tài chính). | | `MISSING_MARKET` | Chỉ số định giá nhưng không có giá đóng cửa hoặc số cổ phiếu tại ngày định giá. | --- ## Quy ước dấu và đơn vị - Tỷ lệ là phân số thập phân (`0.18` là 18%). Cột `unit` cho biết đơn vị: `ratio`, `times` (lần), `days` (ngày), `VND`, `VND/share`, `shares`. - Bốn chỉ số ngân hàng giữ **dấu âm** của chi phí và dự phòng, như cách số liệu thị trường thường hiển thị: `RT_BANK_COF`, `RT_BANK_CIR`, `RT_BANK_NPL_COVERAGE`, `RT_BANK_PROVISION_TO_LOANS`. Ví dụ VCB năm 2025 có `RT_BANK_CIR = -0.348`, tức chi phí hoạt động bằng 34,8% tổng thu nhập hoạt động. Dùng `abs()` nếu bạn cần độ lớn. - EPS, BVPS, doanh thu và dòng tiền mỗi cổ phiếu chia cho số cổ phiếu lưu hành tại ngày định giá của từng kỳ, chưa điều chỉnh theo cổ tức bằng cổ phiếu hay phát hành thêm. Khi so sánh EPS qua nhiều năm, hãy lưu ý các đợt chia cổ phiếu.
  • Dòng quý 4 và dòng năm: các chỉ số dùng mẫu số bình quân (ROE, ROA, NIM, số ngày thu tiền...) ở dòng quý 4 tính theo bình quân 4 điểm cuối quý, còn dòng năm tính theo bình quân đầu năm và cuối năm, nên hai dòng có thể chênh nhẹ. Các chỉ số khác của dòng quý 4 trùng dòng năm.
  • Tăng trưởng tín dụng và huy động (RT_BANK_LOAN_GROWTH, RT_BANK_DEPOSIT_GROWTH): kỳ quý là tăng trưởng một quý so với cuối quý trước (kể cả quý 4), kỳ năm là tăng trưởng so với cuối năm trước.
  • CIR và thu nhập ngoài lãi (RT_BANK_CIR, RT_BANK_NOII) tính trên số riêng của quý, không phải TTM, kể cả quý 4; dòng năm là số cả năm. Ngân hàng thường dồn chi phí vào quý 4, nên CIR quý 4 hay cao hơn các quý khác (VCB quý 4/2025: −0,391, cả năm 2025: −0,348).
  • Chỉ số định giá dùng giá tại ngày định giá của hồ sơ (bảng hồ sơ ở trên), không dùng ngày BCTC được công bố. Với hồ sơ vn, giá đó có thể nằm sau ngày công bố BCTC vài tháng; kỳ gần nhất dùng giá mới nhất cho tới ngày định giá. Nếu dùng chỉ số định giá cho kiểm định chiến lược, hãy tự ghép giá theo ngày công bố BCTC.
--- ## Các nhóm chỉ số tiêu biểu Danh sách đầy đủ 100 chỉ số, kèm công thức và mẫu ngành áp dụng, có trong `fa.catalog()`. Dưới đây là các chỉ số hay dùng. ### 1. Khả năng sinh lợi - `RT_PRT_ROE`: Lợi nhuận cổ đông công ty mẹ (TTM) / vốn chủ của cổ đông công ty mẹ bình quân. Ngân hàng chia cho tổng vốn chủ bình quân; kỳ năm của ngân hàng dùng lợi nhuận sau thuế toàn bộ. - `RT_PRT_ROA`: Lợi nhuận cổ đông công ty mẹ (TTM) / tổng tài sản bình quân. - `RT_PRT_ROCE`: EBIT / (tổng tài sản − nợ ngắn hạn) bình quân. - `RT_PRT_GROSS_MARGIN`: Lợi nhuận gộp / doanh thu thuần. - `RT_PRT_NET_MARGIN`: Lợi nhuận sau thuế toàn bộ (gồm cổ đông không kiểm soát) / doanh thu thuần. Không áp dụng cho ngân hàng. - `RT_PRT_EBITDA_MARGIN`: EBITDA / doanh thu thuần. EBIT trong thư viện là lợi nhuận hoạt động cốt lõi: lợi nhuận gộp − chi phí bán hàng − chi phí quản lý, không gồm thu nhập và chi phí tài chính hay thu nhập khác. EBITDA = EBIT + khấu hao trên báo cáo lưu chuyển tiền tệ. ### 2. Đòn bẩy và khả năng thanh toán - `RT_LEV_DE`: **Tổng nợ phải trả** / vốn chủ sở hữu. Tỷ lệ nợ vay / vốn chủ là `RT_LEV_LOAN_EQUITY`. - `RT_LEV_NET_DEBT`: Vay ngắn và dài hạn − tiền và tương đương tiền − đầu tư tài chính ngắn hạn (VND). - `RT_LEV_NET_DEBT_EBITDA`: Nợ vay ròng / EBITDA (TTM). - `RT_LEV_INTEREST_COVERAGE`: EBIT / chi phí lãi vay (TTM). - `RT_LQD_CR`: Tài sản ngắn hạn / nợ ngắn hạn. - `RT_LQD_QR`: Với hồ sơ `vn`, kỳ quý dùng (tài sản ngắn hạn − tồn kho) / nợ ngắn hạn, kỳ năm dùng (tiền + phải thu ngắn hạn) / nợ ngắn hạn. Hồ sơ `cfa` dùng (tiền + đầu tư ngắn hạn + phải thu ngắn hạn) / nợ ngắn hạn. - `RT_LQD_CASH_RATIO`: Tiền và tương đương tiền / nợ ngắn hạn. ### 3. Hiệu quả hoạt động - `RT_EFF_ATR`: Doanh thu thuần / tổng tài sản bình quân. - `RT_EFF_INVENTORY_TURNOVER`: Giá vốn hàng bán / tồn kho bình quân (hồ sơ `vn` dùng tồn kho theo giá gốc, trước dự phòng). - `RT_EFF_RECEIVABLE_TURNOVER`: Doanh thu thuần / phải thu khách hàng bình quân. - `RT_EFF_DIO`, `RT_EFF_DSO`, `RT_EFF_DPO`: Số ngày tồn kho, thu tiền, thanh toán (365 ngày). - `RT_EFF_CASH_CYCLE`: DSO + DIO − DPO. ### 4. Ngân hàng (mẫu TCTD) - `RT_BANK_NIM`: Thu nhập lãi thuần (TTM) / tài sản sinh lãi bình quân (tiền gửi NHNN, tiền gửi và cho vay TCTD khác, chứng khoán đầu tư, dư nợ gộp). - `RT_BANK_YIEA`: Thu nhập lãi và tương tự (TTM) / tài sản sinh lãi bình quân. - `RT_BANK_COF`: Chi phí lãi (TTM, dấu âm) / nợ chịu lãi bình quân. - `RT_BANK_CIR`: Chi phí hoạt động (dấu âm) / tổng thu nhập hoạt động, số riêng của quý. - `RT_BANK_CASA`: (Tiền gửi không kỳ hạn + ký quỹ + vốn chuyên dùng) / tiền gửi khách hàng. Cần thuyết minh BCTC. - `RT_BANK_LDR`: Dư nợ gộp / tiền gửi khách hàng (tỷ lệ phân tích, không phải tỷ lệ theo quy định của NHNN). - `RT_BANK_NPL`: Nợ nhóm 3–5 / dư nợ gộp. Cần thuyết minh BCTC. - `RT_BANK_NPL_COVERAGE`: Dự phòng rủi ro cho vay (dấu âm) / nợ nhóm 3–5. - `RT_BANK_PROVISION_TO_LOANS`: Chi phí dự phòng rủi ro tín dụng (TTM, dấu âm) / dư nợ gộp bình quân. - `RT_BANK_CAR`: Hệ số an toàn vốn chép từ thuyết minh, không tính lại. `Dataset.load()` tự tải thuyết minh cho ngân hàng (cần gói quyền sử dụng). Nếu không tải được, các chỉ số cần chỉ tiêu `NT_` trả `MISSING_INPUT`. ### 5. Dòng tiền tự do theo CFA - `RT_CF_FCFF`: Lưu chuyển tiền kinh doanh + lãi vay đã trả × (1 − thuế suất hiệu dụng) − (chi mua TSCĐ − thu thanh lý TSCĐ). Theo VAS, lãi vay đã trả nằm trong dòng tiền kinh doanh nên được cộng lại sau thuế. - `RT_CF_FCFE`: Lưu chuyển tiền kinh doanh − đầu tư TSCĐ thuần + vay mới − trả nợ gốc. Các chỉ số dựa trên lưu chuyển tiền thuần từ hoạt động kinh doanh (`RT_VALUE_P_CF`, `RT_VALUE_CFPS`, `RT_CF_CROA`, `RT_CF_CROE`, `RT_CF_INCOME_QUALITY`, `RT_CF_DEBT_COVERAGE`, `RT_CF_DIVIDEND_PAYMENT`, `RT_CF_TO_REVENUE`) không áp dụng cho ngân hàng và công ty chứng khoán (`NOT_APPLICABLE`). Dòng tiền kinh doanh của hai loại hình này chủ yếu là tiền gửi, cho vay và mua bán chứng khoán, nên không đo được khả năng tạo tiền. ### 6. Phân rã DuPont và các điểm số - **DuPont 3 nhân tố**: `RT_DUPONT_NET_MARGIN` × `RT_DUPONT_ASSET_TURNOVER` × `RT_DUPONT_LEVERAGE` = ROE (cùng dùng lợi nhuận và vốn chủ của cổ đông công ty mẹ). - **DuPont 5 nhân tố theo CFA**: `RT_DUPONT_TAX_BURDEN` (lợi nhuận sau thuế / lợi nhuận trước thuế) × `RT_DUPONT_INTEREST_BURDEN` (lợi nhuận trước thuế / EBIT, có thể lớn hơn 1 vì gồm thu nhập tài chính) × `RT_DUPONT_EBIT_MARGIN` × vòng quay tài sản × đòn bẩy. Vì ROE tính trên lợi nhuận của cổ đông công ty mẹ, nhân thêm `RT_DUPONT_PARENT_SHARE` (lợi nhuận cổ đông công ty mẹ / lợi nhuận sau thuế) thì tích sáu thành phần bằng đúng ROE. Ví dụ FPT năm 2025: 0,835 × 0,861 × 1,187 × 0,157 × 0,876 × 2,416 = 0,283. - **Altman Z''** (`RT_SCORE_ALTMAN_Z2`): 6,56·X1 + 3,26·X2 + 6,72·X3 + 1,05·X4, chỉ dùng số liệu BCTC; dưới 1,1 là vùng nguy cơ, trên 2,6 là vùng an toàn. - **Piotroski F-score** (`RT_SCORE_PIOTROSKI_F`): tổng 9 tín hiệu 0/1 so với cùng kỳ năm trước, từ 0 đến 9. - **Beneish M-score** (`RT_SCORE_BENEISH_M`): mô hình 8 biến; trên −1,78 là dấu hiệu có thể điều chỉnh lợi nhuận. Ngưỡng được đề xuất cho mẫu doanh nghiệp Mỹ, chỉ nên dùng để sàng lọc. - **Tỷ lệ dồn tích** (`RT_QUALITY_ACCRUALS_BS`, `RT_QUALITY_ACCRUALS_CF`): theo bảng cân đối và theo lưu chuyển tiền tệ, đo chất lượng lợi nhuận kế toán. Tài sản hoạt động thuần (NOA) loại tiền và đầu tư ngắn hạn; tương ứng, bản theo lưu chuyển tiền tệ loại tiền chi cho vay, gửi có kỳ hạn và tiền thu hồi khỏi dòng tiền đầu tư, nên hai bản đo cùng một khái niệm. Các chỉ số nhóm 5 và 6 cần gói Bronze trở lên (`fa_advanced`). --- ## Tra cứu công thức và catalog ```python # Xem cách tính, công thức theo mẫu ngành và theo hồ sơ của ROE print(fa.describe("RT_PRT_ROE")) # Xem toàn bộ danh mục chỉ số và nhóm quyền catalog_df = fa.catalog() print(catalog_df[["id", "name", "category", "access"]].head(15)) # Lọc các chỉ số áp dụng cho ngân hàng print(catalog_df[catalog_df["templates"].str.contains("TCTD")][["id", "name"]]) # Xem các nút của hồ sơ 'vn' và 'cfa' print(fa.profiles()) ``` --- ## Đọc tiếp - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino, VaR và thanh khoản Amihud. - [Quản lý danh mục đầu tư](/docs/vnstock_quant/tinh-toan/portfolio) — Tối ưu danh mục và mô phỏng chi phí giao dịch Việt Nam. - [Mô hình định giá](/docs/vnstock_quant/tinh-toan/valuation) — Định giá cổ phiếu dựa trên dòng cổ tức và chỉ số P/E. --- ## Document: Chỉ báo kỹ thuật ## Tổng quan `vnstock_quant.ta` gồm 58 chỉ báo kỹ thuật, từ đường trung bình động và RSI đến chỉ báo biến động và khối lượng. Nếu đã dùng `vnstock_ta` 1.x, bạn có thể giữ cách gọi của lớp `Indicator`. Một số kết quả số sẽ khác bản cũ do thay đổi công thức hoặc cách khởi tạo; xem [trang chuyển đổi](/docs/vnstock_quant/free/chuyen-doi/tu-vnstock-ta) để biết chỉ báo nào bị ảnh hưởng. *** ## Chuẩn bị dữ liệu đầu vào Dữ liệu đầu vào là `pandas.DataFrame` có cột giá và, với một số chỉ báo, cột khối lượng: * **Index**: Nên đặt `DatetimeIndex` (cột thời gian `time`). * **Cột giá bắt buộc**: `open`, `high`, `low`, `close` (kiểu số thực `float64`), `volume` (kiểu số nguyên `int64` hoặc `float64`). * Đối với các chỉ báo chỉ dựa trên giá đóng cửa (ví dụ SMA, RSI), DataFrame chỉ cần tối thiểu cột `close`. ```python import pandas as pd from vnstock import Market # Lấy 365 phiên giao dịch gần nhất của cổ phiếu FPT m = Market() df = m.equity("FPT").ohlcv(length=365, interval="1D") df = df.set_index("time") ```

Chỉ báo có chu kỳ 50 hoặc 200 phiên sẽ trả NaN ở đầu chuỗi cho đến khi có đủ dữ liệu để tính. Hãy kiểm tra số phiên đầu vào trước khi dùng kết quả.

*** ## Hai cách gọi chỉ báo kỹ thuật ### Cách 1: Dùng lớp Indicator Với `Indicator`, bạn có thể gọi hàm theo nhóm chỉ báo hoặc gọi trực tiếp tên hàm: ```python from vnstock_quant import Indicator # Khởi tạo đối tượng với dữ liệu nến ta = Indicator(df) # Phong cách 1: Gọi thông qua nhóm danh mục (Phân cấp logic trực quan) sma_20 = ta.trend.sma(length=20) rsi_14 = ta.momentum.rsi(length=14) bbands = ta.volatility.bbands(length=14, std=2.0) obv = ta.volume.obv() pivots = ta.statistics.pivots() # Phong cách 2: Gọi phẳng trực tiếp (giữ cú pháp gọi của vnstock_ta 1.x) macd = ta.macd(fast=12, slow=26, signal=9) st = ta.supertrend(period=10, multiplier=3.0) ``` Kết quả trả về là một `pandas.Series` (đối với chỉ báo đơn đường như SMA, RSI) hoặc một `pandas.DataFrame` (đối với chỉ báo đa đường như MACD, Bollinger Bands, Supertrend) giữ nguyên chỉ mục thời gian của DataFrame gốc. ### Cách 2: Gọi theo tên hàm thông qua compute() Dùng `compute()` khi tên chỉ báo nằm trong tệp cấu hình hoặc được chọn lúc chương trình chạy: ```python from vnstock_quant import compute # Tính RSI theo tên rsi_series = compute(df, "rsi", length=14) # Tính MACD theo tên với bộ tham số tuỳ chỉnh macd_df = compute(df, "macd", fast=12, slow=26, signal=9) ``` *** ## Danh mục 58 chỉ báo theo năm nhóm Các chỉ báo được chia thành năm nhóm: ### 1. Xu hướng (Trend Indicators - 14 chỉ báo) Nhận diện hướng đi chủ đạo của thị trường (tăng giá, giảm giá hoặc tích luỹ đi ngang): | Ký hiệu | Tên đầy đủ | Mô tả | | :----------- | :----------------------------- | :------------------------------------------------------- | | `sma` | Simple Moving Average | Đường trung bình động giản đơn | | `ema` | Exponential Moving Average | Đường trung bình động luỹ thừa | | `wma` | Weighted Moving Average | Đường trung bình động có trọng số | | `hma` | Hull Moving Average | Đường trung bình động Hull giúp giảm độ trễ | | `smma` | Smoothed Moving Average | Đường trung bình động làm mượt | | `alma` | Arnaud Legoux Moving Average | Đường trung bình động Arnaud Legoux dùng phân phối Gauss | | `vwma` | Volume-Weighted Moving Average | Đường trung bình động theo khối lượng | | `adx` | Average Directional Index | Chỉ số định hướng trung bình xác định cường độ xu hướng | | `ichimoku` | Ichimoku Kinko Hyo | Hệ thống đám mây Ichimoku | | `psar` | Parabolic SAR | Chỉ báo điểm dừng và đảo chiều xu hướng | | `supertrend` | Supertrend | Chỉ báo bám sát xu hướng dựa trên độ biến động ATR | | `dm` | Directional Movement | Hệ thống chuyển động định hướng (+DI, -DI) | | `linreg` | Linear Regression | Hồi quy tuyến tính của chuỗi giá | | `aroon` | Aroon Indicator | Đo lường thời gian kể từ đỉnh/đáy gần nhất | ### 2. Động lượng (Momentum Indicators - 15 chỉ báo) Đo lường vận tốc biến động giá và xác định các vùng quá mua (overbought) hoặc quá bán (oversold): | Ký hiệu | Tên đầy đủ | Mô tả | | :--------- | :------------------------------------ | :----------------------------------------------------------- | | `rsi` | Relative Strength Index | Chỉ số sức mạnh tương đối (Wilder RSI) | | `stoch` | Stochastic Oscillator | Dao động ngẫu nhiên đo vị trí giá so với biên độ đỉnh-đáy | | `stochrsi` | Stochastic RSI | Áp dụng công thức Stochastic trên chuỗi giá trị RSI | | `mom` | Momentum | Đo khoảng cách giá hiện tại so với n phiên trước | | `roc` | Rate of Change | Tốc độ thay đổi giá theo tỷ lệ phần trăm | | `ao` | Awesome Oscillator | Dao động Awesome của Bill Williams, đo động lượng thị trường | | `cci` | Commodity Channel Index | Chỉ số kênh hàng hoá đo độ lệch so với trung bình | | `willr` | Williams %R | Chỉ báo phản ánh vị thế tương đối của giá đóng cửa | | `tsi` | True Strength Index | Chỉ số sức mạnh thực sự với 2 tầng làm mượt EMA | | `cmo` | Chande Momentum Oscillator | Dao động động lượng Chande | | `uo` | Ultimate Oscillator | Dao động tối thượng kết hợp 3 khung thời gian | | `fisher` | Fisher Transform | Chuyển đổi phân phối giá về phân phối chuẩn Gauss | | `cg` | Center of Gravity | Chỉ báo trọng tâm của chuỗi giá | | `kst` | Know Sure Thing | Dao động KST tổng hợp 4 chu kỳ ROC | | `macd` | Moving Average Convergence Divergence | Đường trung bình động hội tụ phân kỳ | ### 3. Biến động (Volatility Indicators - 10 chỉ báo) Đo lường mức độ co giãn biên độ giá và nhận diện giai đoạn nén biên độ: | Ký hiệu | Tên đầy đủ | Mô tả | | :------------ | :----------------- | :--------------------------------------------------------------- | | `bbands` | Bollinger Bands | Dải biến động trên/dưới quanh đường trung bình | | `kc` | Keltner Channels | Kênh Keltner dựa trên đường trung bình và ATR | | `atr` | Average True Range | Khoảng biến động thực tế trung bình | | `stdev` | Standard Deviation | Độ lệch chuẩn thống kê của chuỗi giá | | `donchian` | Donchian Channels | Kênh giá đỉnh cao nhất và đáy thấp nhất | | `massi` | Mass Index | Chỉ số khối lượng nhận diện vùng đảo chiều nén biên độ | | `ui` | Ulcer Index | Đo lường độ sâu và thời gian sụt giảm giá | | `squeeze` | TTM Squeeze | Phát hiện trạng thái tích luỹ nén chặt giữa Bollinger và Keltner | | `squeeze_pro` | Squeeze Pro | Bản nâng cấp đo 3 mức độ nén giá (chặt, vừa, lỏng) | | `true_range` | True Range | Biên độ thực tế của từng phiên giao dịch | ### 4. Khối lượng (Volume Indicators - 10 chỉ báo) Kết hợp tương quan giữa biến động giá và thanh khoản giao dịch: | Ký hiệu | Tên đầy đủ | Mô tả | | :------ | :---------------------------- | :---------------------------------------------------------- | | `obv` | On-Balance Volume | Khối lượng cân bằng tích luỹ | | `cmf` | Chaikin Money Flow | Dòng tiền Chaikin đo áp lực mua/bán trong kỳ | | `ad` | Accumulation/Distribution | Đường tích luỹ/phân phối khối lượng | | `vp` | Volume Profile | Phân bổ khối lượng giao dịch theo các vùng giá | | `vwap` | Volume-Weighted Average Price | Giá bình quân gia quyền theo khối lượng trong phiên | | `pvo` | Percentage Volume Oscillator | Dao động tỷ lệ phần trăm khối lượng giữa hai đường EMA | | `efi` | Elder's Force Index | Chỉ số lực giao dịch của Elder | | `eom` | Ease of Movement | Mức độ dễ dàng dịch chuyển của giá theo khối lượng | | `nvi` | Negative Volume Index | Chỉ số khối lượng âm phản ánh hành vi dòng tiền thông minh | | `mfi` | Money Flow Index | Chỉ số dòng tiền kết hợp giá và khối lượng (RSI khối lượng) | ### 5. Thống kê (Statistics Indicators - 9 chỉ báo) Các giá trị thống kê hình học và điểm xoay trục quan trọng: | Ký hiệu | Tên đầy đủ | Mô tả | | :----------- | :---------------------- | :------------------------------------------------------------ | | `pivots` | Pivot Points | Điểm xoay trục và các mức hỗ trợ/kháng cự kinh điển | | `mad` | Mean Absolute Deviation | Độ lệch tuyệt đối trung bình | | `variance` | Variance | Phương sai thống kê của chuỗi giá | | `hl2` | High-Low Median Price | Giá trung vị giữa đỉnh và đáy `(high + low) / 2` | | `hlc3` | Typical Price | Giá điển hình `(high + low + close) / 3` | | `ohlc4` | Average Price | Giá trung bình phiên `(open + high + low + close) / 4` | | `midprice` | Midprice | Giá trung vị giữa đỉnh cao nhất và đáy thấp nhất trong chu kỳ | | `decreasing` | Decreasing Indicator | Chuỗi logic đánh dấu các phiên giá giảm liên tiếp | | `increasing` | Increasing Indicator | Chuỗi logic đánh dấu các phiên giá tăng liên tiếp | *** ## Khám phá danh mục và mức tin cậy Bạn có thể tra cứu danh mục, tham số mặc định và chuẩn đối chiếu của mọi chỉ báo bằng hàm `ta.catalog()`: ```python from vnstock_quant.ta import catalog cat = catalog() print(cat[["name", "group", "standard", "confidence", "access"]].head(10)) ``` Các mức tin cậy (`confidence`) được thẩm định khoa học: * **Mức A**: Khớp hoàn toàn với thư viện C nguyên bản **TA-Lib C 0.8.1** tới sai số dấu phẩy động (34 chỉ báo). * **Mức B**: Khớp trong sai số cho phép với bộ kiểm thử độc lập của **QuantConnect LEAN** hoặc **TradingView Pine Script v6** (Ichimoku, Supertrend, ADX...). * **Mức C**: Kiểm định theo công thức gốc trong bài báo học thuật của tác giả phát minh. *** ## Tải dữ liệu nhanh bằng from_vnstock Nếu đã cài đặt tiện ích `vnstock`, bạn có thể lấy dữ liệu và khởi tạo `Indicator` trong một câu lệnh: ```python from vnstock_quant.ta import from_vnstock # Tải dữ liệu và khởi tạo đối tượng Indicator tự động ta = from_vnstock("HPG", start="2024-01-01", end="2024-12-31") # Bắt đầu tính toán ngay lập tức rsi = ta.rsi(length=14) macd = ta.macd() ``` *** ## Vẽ đồ thị kỹ thuật với vnstock_chart Sau khi tính chỉ báo kỹ thuật, bạn có thể đưa kết quả vào `vnstock_chart`, thư viện vẽ biểu đồ của thế hệ 5, để có biểu đồ nến kèm chỉ báo: ```python from vnstock import Market from vnstock_quant import Indicator from vnstock_chart import Chart df = Market().equity("FPT").ohlcv(length=365, interval="1D").set_index("time") ta = Indicator(df) bb = ta.bbands(length=20, std=2.0) rsi = ta.rsi(length=14) # Bollinger Bands chồng lên khung giá, RSI ở khung riêng bên dưới fig, axes = Chart.candle( df, title="FPT — Bollinger Bands và RSI(14)", volume=False, overlays=[ {"data": bb["BBU_20_2.0"], "color": "#2EA8F0"}, {"data": bb["BBM_20_2.0"], "color": "#FFB31A"}, {"data": bb["BBL_20_2.0"], "color": "#2EA8F0"}, ], subplots=[{"data": rsi, "color": "#8C52FF", "ylabel": "RSI"}], ) fig.savefig("fpt_bbands_rsi.png", dpi=150, bbox_inches="tight") ``` Cài `vnstock_chart` bằng `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart`. Xem thêm các kiểu biểu đồ và cách đặt nhiều chỉ báo trên cùng một hình ở [tài liệu vnstock_chart](/docs/vnstock-chart/ket-hop-voi-gen5). *** ## Đọc tiếp * [Chỉ số tài chính](/docs/vnstock_quant/free/tinh-toan/fa) — Khám phá 100 chỉ số tài chính BCTC VAS và mô hình dòng tiền CFA. * [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino, VaR và thanh khoản Amihud. * [Chuyển đổi từ vnstock_ta](/docs/vnstock_quant/free/chuyen-doi/tu-vnstock-ta) — Chi tiết 16 chỉ báo đã sửa lỗi so với vnstock_ta 1.x. * [Kiểm định chất lượng & hiệu năng](/docs/vnstock_quant/free/tham-khao/doi-chieu-ket-qua-va-toc-do) — Báo cáo chi tiết sai số 58 chỉ báo so với TA-Lib C và kiểm định hiệu năng. --- ## Document: Giới thiệu

Nếu bạn muốn tính chỉ báo, chỉ số tài chính hoặc phân tích danh mục bằng Python, hãy bắt đầu tại đây. Nếu đang dùng vnstock_ta 1.x, xem hướng dẫn chuyển đổi.

## Bạn có thể làm gì với vnstock_quant? `vnstock_quant` là thư viện Python để tính chỉ báo kỹ thuật, chỉ số tài chính, thước đo rủi ro và hiệu suất, kết quả danh mục và các mô hình định giá. Thư viện kế thừa `vnstock_ta` và bổ sung các nhóm chức năng tính toàn mở rộng ngoài chỉ báo kỹ thuật. Bạn đưa vào bảng dữ liệu pandas đã chuẩn bị hoặc truy xuất dữ liệu bằng `vnstock` khi cần. Phần tính toán chạy trên máy của bạn. Kết quả trả về có cấu trúc để bạn tiếp tục kiểm tra, so sánh hoặc dùng trong báo cáo.

Các công cụ, công thức và mô hình tính toán trong vnstock_quant được cung cấp cho mục đích học tập, nghiên cứu và phân tích định lượng độc lập trên môi trường cá nhân của người dùng. Mọi kết quả là đầu ra mô hình dựa trên các giả định và dữ liệu do bạn tự cung cấp, không cấu thành khuyến nghị đầu tư, tư vấn tài chính hay lời mời chào mua bán chứng khoán.

*** ## Dữ liệu đầu vào và phạm vi `vnstock_quant` dùng dữ liệu bạn chọn để tính toán; bản thân thư viện không cung cấp sẵn dữ liệu đầu vào. Bạn có thể chuẩn bị dữ liệu từ tệp trên máy hoặc truy xuất qua `vnstock`. Kết quả tính toán phụ thuộc vào dữ liệu, kỳ quan sát và các giả định bạn đặt. Vì vậy, hãy kiểm tra các yếu tố này trước khi dùng kết quả để nghiên cứu. Thư viện có lõi tính toán bằng Rust và giao diện Python. Bạn cài gói dựng sẵn, không cần tự biên dịch Rust. Nếu cần số đo tốc độ và cách đối chiếu kết quả, xem [Kiểm định chất lượng và hiệu năng](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do). *** ## Bản đồ tài liệu Tài liệu xếp theo luồng làm việc, mỗi bước là một mục trong thanh bên: bắt đầu, chuẩn bị dữ liệu, tính toán, chạy thử chiến lược, rồi tích hợp với trợ lý AI. Trong mục Tính toán, mỗi trang ứng với một không gian tên và đường dẫn kết thúc bằng đúng tên đó: gõ `vq.fa` thì tìm trang `/tinh-toan/fa`. | Mục | Trang | Trong mã | Giúp bạn làm gì? | | :--- | :--- | :--- | :--- | | **Bắt đầu** | [Cài đặt](/docs/vnstock_quant/bat-dau/cai-dat-va-thiet-lap), [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc), [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/bat-dau/quy-uoc-du-lieu-va-loi) | `vq.entitlement()`, `vq.errors` | Cài gói, biết cấp của mình mở nhóm nào, đọc đúng dạng dữ liệu và mã lỗi. | | **Dữ liệu** | [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh) | `vnstock_quant.prices` | Chuyển giá thô sang giá đã điều chỉnh theo sự kiện quyền, kiểm với giá tham chiếu của sàn. | | | [Vi cấu trúc thị trường](/docs/vnstock_quant/du-lieu/vi-cau-truc-thi-truong) | `vnstock_quant.micro` | Gom dữ liệu khớp lệnh thành nến theo thời gian, số lệnh, khối lượng hoặc giá trị; bên chủ động, CVD, VPIN, biến động thực hiện. | | **Tính toán** | [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) | `vnstock_quant.ta` | 58 chỉ báo xu hướng, động lượng, biến động, khối lượng và thống kê từ dữ liệu nến. | | | [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) | `vnstock_quant.fa` | 100 chỉ số từ báo cáo tài chính theo bốn mẫu ngành; tra công thức và kỳ dữ liệu được dùng. | | | [Rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) | `vnstock_quant.risk` | 33 thước đo trên chuỗi lợi suất: biến động, sụt giảm, VaR, so với chỉ số tham chiếu. | | | [Danh mục](/docs/vnstock_quant/tinh-toan/portfolio) | `vnstock_quant.portfolio` | Lợi suất khi có nạp rút tiền, mô phỏng tái cân bằng, phân rã rủi ro, xây dựng danh mục. | | | [Định giá](/docs/vnstock_quant/tinh-toan/valuation) | `vnstock_quant.valuation` | Chiết khấu cổ tức, lợi suất và tăng trưởng ngầm định, P/E hợp lý theo giả định bạn đặt. | | **Backtest** | [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu) | `vnstock_quant.backtest` | Mô phỏng chiến lược theo luật thị trường Việt Nam: lô 100, bước giá, biên độ, T+2.5, thuế bán; danh mục, dò tham số, walk-forward, Monte Carlo. | | **Tích hợp** | [Gọi bằng JSON và MCP](/docs/vnstock_quant/tich-hop/goi-bang-json-va-mcp), [Tải dữ liệu bằng vnstock](/docs/vnstock_quant/tich-hop/tai-du-lieu-bang-vnstock) | `catalog()`, `schema()`, `call()` | Dùng các hàm làm công cụ cho trợ lý AI; biết điểm vào tải dữ liệu của từng nhóm. | | **Tham khảo** | [Đối chiếu kết quả và tốc độ](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) | | Mốc chuẩn đối chiếu kết quả, điều kiện và số đo tốc độ. | | **Chuyển đổi** | [Từ vnstock_ta](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta) | | Đổi import và kiểm tra kết quả khi chuyển mã viết cho `vnstock_ta` 1.x. | *** ## Mức độ ổn định của từng nhóm hàm Các nhóm hàm của `vnstock_quant` phát hành chung một bản nhưng chưa ổn định như nhau. Trang của mỗi nhóm có nhãn ở đầu trang, và mục thuộc nhóm còn thử nghiệm có thêm biểu tượng ống nghiệm màu hổ phách trong thanh bên. | Nhóm hàm | Mức | Bạn có thể dựa vào đến đâu? | | :--- | :--- | :--- | | Chỉ báo kỹ thuật (`ta`) | **Ổn định** | Kế thừa `vnstock_ta`. Cách gọi và kết quả được giữ nhất quán giữa các bản phát hành; thay đổi ảnh hưởng tới mã đang chạy được ghi trong [lịch sử phiên bản](/docs/vnstock_quant/lich-su-phien-ban). | | Chỉ số tài chính (`fa`), rủi ro và hiệu suất (`risk`), danh mục (`portfolio`), định giá (`valuation`), giá điều chỉnh (`prices`), vi cấu trúc thị trường (`micro`), backtest (`backtest`), gọi hàm bằng JSON | **Thử nghiệm** | Đang phát triển, chưa ổn định. Dùng được để tìm hiểu và chạy thử, nhưng tên hàm, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành, công thức cũng có thể còn được hiệu chỉnh. | Khi dùng nhóm thử nghiệm, hãy đối chiếu kết quả với một cách tính độc lập trước khi đưa vào quy trình nghiên cứu, và ghim phiên bản thư viện trong dự án (xem bản đang cài bằng `pip show vnstock_quant`) để mã đang chạy không tự đổi theo bản mới. Khi một nhóm chuyển sang ổn định, nhãn trên trang sẽ đổi và lịch sử phiên bản sẽ ghi lại. *** ## Dùng cùng trợ lý AI Bạn có thể dùng trợ lý AI để viết mã gọi `vnstock_quant` ở cả bản Cộng đồng và bản Mở rộng. Hãy cho trợ lý biết phiên bản đã cài, nhóm hàm muốn dùng và cấu trúc dữ liệu đầu vào. Khi gọi sai tham số, mã lỗi như `QUANT_INVALID_PARAMETER` giúp bạn xác định chỗ cần sửa. Các hàm danh mục, định giá và backtest còn gọi được bằng JSON với JSON Schema sẵn có, xem [Gọi bằng JSON và MCP](/docs/vnstock_quant/tich-hop/goi-bang-json-va-mcp). Xem [hướng dẫn cho trợ lý AI](/onboard/agent-guide) nếu bạn muốn thiết lập môi trường làm việc này. *** ## Quyền dùng hàm và hạn mức theo cấp Quyền được cấp theo **nhóm tính năng**, do máy chủ Vnstock quyết định và thư viện đọc về; phép tính chạy trên máy bạn không tốn hạn mức chung, chỉ việc tải dữ liệu qua `vnstock` mới tính vào hạn mức tài khoản. - **Bản Cộng đồng**: 10 chỉ báo kỹ thuật cơ bản, 10 chỉ số tài chính cơ bản (30 lượt thử mỗi ngày, tính chung) và backtest một mã với 10 chỉ báo đó (3 lượt thử mỗi ngày, tính riêng). - **Từ Bronze**: đủ 100 chỉ số tài chính, rủi ro và hiệu suất, danh mục, định giá, giá điều chỉnh, vi cấu trúc thị trường, backtest đủ chỉ báo, danh mục, dò tham số, walk-forward, Monte Carlo. - **Từ Silver**: đủ 58 chỉ báo kỹ thuật. Bảng đầy đủ theo từng cấp, lượt dùng thử và quy mô mỗi lần chạy thử: [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc). Gọi `vq.entitlement()` để xem cấp và nhóm tính năng của chính bạn. *** ## Đọc tiếp * [Cài đặt và thiết lập](/docs/vnstock_quant/bat-dau/cai-dat-va-thiet-lap) — Cài thư viện và kiểm tra cấp quyền. * [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) — Tính 58 chỉ báo kỹ thuật với `vnstock_quant.ta`. * [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) — 100 chỉ số tài chính từ báo cáo VAS và mô hình dòng tiền CFA. * [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu) — Backtest theo luật thị trường Việt Nam, đối chứng với backtesting.py, backtrader, vectorbt, zipline. * [Chuyển từ vnstock_ta](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta) — Đổi import và kiểm tra kết quả khi chuyển mã cũ. * [Lịch sử phiên bản](/docs/vnstock_quant/lich-su-phien-ban) — Các mốc phát hành của thư viện. --- ## Document: Lịch sử phiên bản Nhãn **[Mở rộng]** đánh dấu phần chỉ có ở bản Mở rộng, nhãn **[Cộng đồng]** đánh dấu phần chỉ đúng với bản Cộng đồng. Phần không gắn nhãn đúng ở cả hai bản. Trang tổng hợp của từng bản lấy thay đổi từ tệp này theo nhãn. ## 27-10-2026 (v0.5.0) ### Mô-đun mới: chạy thử chiến lược (`backtest`) `vnstock_quant.backtest` chạy thử chiến lược trên dữ liệu giá bạn chuẩn bị, theo luật thị trường Việt Nam, trong cùng lõi Rust với các nhóm hàm khác: bảng quy tắc dùng đúng 58 chỉ báo của `ta`, tear sheet dùng 33 thước đo của `risk`, chung cấp quyền và cây lỗi của thư viện. Tài liệu: [Chạy thử chiến lược](/docs/vnstock_quant/backtest/gioi-thieu). - **Tín hiệu**: mảng `[-1, 0, 1]`, cặp `entries`/`exits` hoặc bảng quy tắc `rule_dsl` dạng JSON; kiểm thiên lệch nhìn trước tương lai cho cả hàm tín hiệu và bảng quy tắc (`check_causality`, `check_rule_dsl_causality`). - **Luật thị trường**: mặc định lô 100, bước giá theo sàn, biên độ, phiên khóa trần và khóa sàn, T+2.5, thuế bán 0,1% tính riêng ngoài phí; hồ sơ phái sinh VN30F, crypto, cổ phiếu quốc tế, ngoại hối; cổ tức tiền, cổ phiếu thưởng và quyền mua trên giá gốc. - **Khớp lệnh**: chế độ `vn_realistic` và bốn chế độ tái tạo hành vi mặc định của backtesting.py, backtrader, vectorbt, zipline, khớp tới từng lệnh trên 11 kịch bản đối chứng; lệnh giới hạn và lệnh dừng theo phiên, nhiều lô trong một vị thế, chốt lời từng phần, dừng lỗ động, chặn rủi ro cấp tài khoản. - **Danh mục và chống quá khớp**: `run_portfolio` cho nhiều mã chung một tài khoản và tái cân bằng theo tỷ trọng; `sweep`, `walk_forward`, `monte_carlo`, `deflated_sharpe_ratio`. - **Gọi bằng JSON**: `catalog()`, `schema()` và `call()` với 10 công cụ dùng được trực tiếp cho trợ lý AI và Vnstock MCP. - **Lỗi và quyền**: lớp lỗi mới `CausalityViolationError` (`QUANT_CAUSALITY_VIOLATION`); mã `QUANT_QUOTA_LIMIT` (`QuotaExceededError`) khi một lần chạy vượt quy mô của cấp; `vq.entitlement()` có thêm khoá `backtest` và bộ quy tắc `quant_entitlement_v3`. - **[Cộng đồng]** Backtest một mã với 10 chỉ báo cơ bản trong bảng quy tắc, 3 lượt mỗi ngày. Lượt backtest đếm riêng, không trừ vào 30 phép tính chỉ báo và chỉ số; xem `vq.entitlement()["backtest"]`. - **[Mở rộng]** Từ Bronze mở đủ chỉ báo, danh mục, dò tham số, walk-forward, Monte Carlo; các cấp khác nhau ở quy mô mỗi lần chạy. - Extra `chart` (`pip install --extra-index-url https://vnstocks.com/api/packages "vnstock-quant[chart]"`) cài [`vnstock_chart`](/docs/vnstock-chart) để vẽ kết quả chạy thử. ### Mô-đun mới: giá điều chỉnh (`prices`) - **[Mở rộng]** `vnstock_quant.prices` chuyển giá chưa điều chỉnh sang giá đã điều chỉnh theo cổ tức tiền, cổ phiếu thưởng và quyền mua, kiểm từng sự kiện với giá tham chiếu của sàn: `prices.adjust()`, `prices.factors()` và `prices.from_vnstock()`. Xem [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh). ### Chỉ số tài chính (`fa`) Các chỉ số nêu sau cho số khác bản 0.4.0; những chỉ số không nhắc tới giữ nguyên. Mỗi thay đổi được kiểm trên dữ liệu thị trường tải ngày 27/10/2026 và trên 64 mã của bộ đối chiếu. Cách tính chi tiết xem ở [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa). - **P/E, P/B, P/S, P/CF, EV/EBITDA kỳ năm**: Lấy giá đóng cửa và số cổ phiếu của cùng một phiên, tại ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4 và P/E bằng giá / EPS trong cùng một dòng. Bản trước lấy giá cuối năm sau nhân với số cổ phiếu của năm báo cáo: chỉ số dùng giá của một năm sau kỳ báo cáo, và thấp hơn thực tế khi có chia cổ phiếu trong năm sau (P/E năm 2024 của VCB ra 9,5 thay vì 14,65; FPT ra 17,9 thay vì 22,2). Tham số `overrides={"year_valuation": ...}` không còn dùng được. - **Dòng quý 4 của chuỗi quý**: Mẫu số bình quân (ROE, ROA, vòng quay, số ngày thu tiền...) là bình quân 4 điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán. Bản trước dùng bình quân đầu năm và cuối năm, làm chuỗi quý nhảy ở mỗi quý 4 (ROE quý 4 của ngân hàng cao hơn trung bình hai quý kề 2,2%; nay −0,3%, ngang các quý khác). ROE quý 4/2025 của FPT từ 28,29% thành 27,25%. Dòng năm không đổi. - **[Mở rộng]** **Tăng trưởng tín dụng và huy động theo quý** (`RT_BANK_LOAN_GROWTH`, `RT_BANK_DEPOSIT_GROWTH`): Quý 4 so với cuối quý 3 như các quý khác. Bản trước so quý 4 với cuối năm trước, trộn tăng trưởng một quý với tăng trưởng cả năm (tín dụng VCB quý 4/2025: 15,5% thành 2,7%). Dòng năm không đổi. - **[Mở rộng]** **CIR và thu nhập ngoài lãi theo quý** (`RT_BANK_CIR`, `RT_BANK_NOII`): Quý 4 tính trên số riêng của quý 4, như các quý khác. Bản trước dùng số cả năm. - **[Mở rộng]** **Chỉ số dòng tiền kinh doanh với ngân hàng và công ty chứng khoán**: `RT_VALUE_P_CF`, `RT_VALUE_CFPS`, `RT_CF_CROA`, `RT_CF_CROE`, `RT_CF_INCOME_QUALITY`, `RT_CF_DEBT_COVERAGE`, `RT_CF_DIVIDEND_PAYMENT`, `RT_CF_TO_REVENUE` trả `NOT_APPLICABLE` cho hai loại hình này. Dòng tiền kinh doanh của ngân hàng và công ty chứng khoán chủ yếu là tiền gửi, cho vay và mua bán chứng khoán; P/CF quý của VCB đi từ −13,7 tới 123,3 trong hai năm. - **[Mở rộng]** **Tỷ lệ dồn tích theo lưu chuyển tiền tệ** (`RT_QUALITY_ACCRUALS_CF`): Loại tiền chi cho vay, gửi có kỳ hạn và tiền thu hồi khỏi dòng tiền đầu tư, cho khớp với tài sản hoạt động thuần (đã loại tiền và đầu tư ngắn hạn). Tương quan với bản theo bảng cân đối tăng từ 0,16 lên 0,87 (266 năm-doanh nghiệp); FPT năm 2025 từ 0,575 thành 0,220. - **[Mở rộng]** **DuPont**: `RT_DUPONT_TAX_BURDEN` là lợi nhuận sau thuế / lợi nhuận trước thuế, theo giáo trình CFA (FPT năm 2025: 0,861, bằng 1 − thuế suất hiệu dụng). Chỉ số mới `RT_DUPONT_PARENT_SHARE` (lợi nhuận cổ đông công ty mẹ / lợi nhuận sau thuế) tách phần của cổ đông không kiểm soát; tích sáu thành phần bằng ROE. Thư viện có 100 chỉ số. - **Mô tả ROE trong `fa.describe()`**: Bỏ câu nói hồ sơ `vn` đổi mẫu số từ năm 2022; ROE luôn chia cho vốn chủ của cổ đông công ty mẹ bình quân. - **`fa.Dataset.load()` khi chưa tải được giá**: Nếu cấp của `vnstock` chưa mở giá chưa điều chỉnh, thư viện cảnh báo một lần và vẫn tính các chỉ số từ báo cáo tài chính; chỉ số định giá trả `MISSING_MARKET`. Dùng `prices=False` để bỏ qua bước tải giá. ### Thay đổi khác - **Vi cấu trúc (`micro`)**: Mỗi lần gọi một hàm tính là một lượt, kể cả hàm chạy nhiều bước bên trong như `bars` và `cvd`. - **Đo lượt dùng**: Thư viện không còn hỏi đồng ý đo lượt dùng ở lần chạy đầu. Lựa chọn đặt trên vnstocks.com, mục tùy chọn dữ liệu của tài khoản; chưa chọn thì không đo. Tắt riêng trên máy bằng `vnstock_quant.telemetry.disable()` hoặc biến môi trường `VNSTOCK_TELEMETRY=0`. --- ## 17-10-2026 (v0.4.0) ### Dữ liệu khung phút - **[Mở rộng]** **Ichimoku**: Với nến trong ngày, span tương lai đi tiếp theo nhịp phiên giao dịch có trong dữ liệu (bỏ qua giờ nghỉ trưa, hết phiên thì sang ngày làm việc kế tiếp), thay vì lùi xa 26 ngày. Thị trường giao dịch cả cuối tuần (ví dụ tiền mã hoá) được giữ Thứ 7 và Chủ nhật. Nến ngày không đổi. - **[Mở rộng]** **Ichimoku với cột thời gian**: Bảng có cột `time` (hoặc `date`, `ngay`...) trên chỉ mục số thứ tự, như dữ liệu trả về từ `vnstock`, nay có span tương lai đánh chỉ mục theo thời gian. Bảng chính vẫn giữ chỉ mục của bạn. - **VWAP và pivots**: Đọc được cột thời gian dạng `dd/mm/YYYY HH:MM` và `dd/mm/YYYY HH:MM:SS`. - **[Mở rộng]** **MFI**: Khi dữ liệu có nến thiếu giá trị, chỉ báo trả `NaN` cho các cửa sổ chứa nến đó, không còn dừng chương trình. - **[Mở rộng]** **Rủi ro (`risk`)**: Lợi suất theo phút được gộp thành lợi suất ngày trước khi tính các thước đo quy đổi theo năm, và được ghép với chuỗi đối chiếu theo đúng mốc thời gian (kể cả khi một bên thiếu vài phút). Áp dụng cho các hàm `risk` và `portfolio.risk_decomposition`. Lợi suất ngày cho kết quả như trước. - **Chỉ số tài chính (`fa`)**: Bảng giá theo phút được đọc thành một phiên mỗi ngày, lấy giá của nến cuối ngày (kể cả phiên ATC). Bảng giá ngày không đổi. ### Thay đổi khác - **[Mở rộng]** **`portfolio`**: Bổ sung tham số `flow_dates` cho `twr`, `periods` cho `covariance`, lịch tái cân bằng `M`/`Q`/`Y` cho `portfolio_returns`, và `weights`/`benchmark_weights` cho `ex_ante_tracking_error` (`active_weights` không còn bắt buộc). Cách gọi cũ cho kết quả như cũ. - **[Mở rộng]** **`portfolio.twr`**: Chạy được với chỉ mục ngày có múi giờ. - **[Mở rộng]** **`fa.Dataset.from_frames`**: Bỏ các dòng giá thiếu thời gian; chuỗi thời gian lẫn nhiều múi giờ khác nhau báo `ValueError`. - **Thông báo lỗi**: `vwap` với `anchor` không hợp lệ báo `InvalidParameterError` bằng tiếng Việt, giống `micro.cvd`. - **Chú thích hàm**: Chú thích viết bằng tiếng Anh; mô tả ngắn của 58 chỉ báo viết song ngữ (tiếng Anh trước, tiếng Việt sau). Công thức và phương pháp chi tiết xem ở các trang tài liệu. - **Đo lượt dùng**: Câu hỏi đồng ý đo lượt dùng ở lần chạy đầu thống nhất giữa các thư viện thế hệ 5. --- ## 10-10-2026 (v0.1.3) - **Thư viện xác thực**: Ghim `vnstock-auth` ở bản 0.5.1, thống nhất với các thư viện thế hệ 5 khác. Không đổi cách tính. --- ## 09-10-2026 (v0.1.2) - **Giữ chỉ mục đầu vào**: Kết quả chỉ báo giữ nguyên chỉ mục của bảng bạn truyền vào. Cột thời gian chỉ được dùng cho `vwap` và `pivots`. - **Nhận cột thời gian**: Với bảng dữ liệu thô, thư viện tự nhận cột thời gian và chuyển thành `DatetimeIndex`. - **Gọi lớp chính gọn hơn**: Các lớp chính nhập được thẳng từ `vnstock_quant`; thông báo lỗi rõ hơn khi thiếu cột. --- ## 08-10-2026 (v0.1.1) - **Hạn dùng bản phát hành**: Thư viện kiểm tra hạn dùng của bản cài trước khi tính; thông tin hạn dùng xem ở `vq.entitlement()["release"]`. - **Chú thích song ngữ**: Chú thích hàm của các mô-đun `ta`, `fa`, `risk`, `portfolio`, `valuation` có cả tiếng Việt và tiếng Anh. - **Bản hết hạn**: Bản đã hết hạn báo lỗi `VNSTOCK_RELEASE_EXPIRED` kèm lệnh cập nhật. --- ## 08-10-2026 (v0.1.0) ### Bản phát hành đầu tiên của Vnstock Quant thế hệ 5 - **[Cộng đồng]** **Dùng thử mỗi ngày**: Bản Cộng đồng có 30 lượt dùng thử (30 phép tính) mỗi ngày cho 10 chỉ báo kỹ thuật cơ bản và 10 chỉ số tài chính VAS. Tra cứu số lượt còn lại bằng `vnstock_quant.entitlement()` (khoá `trial`). - **Gói cài đặt dựng sẵn**: Gói nhị phân dựng sẵn (binary wheels) dùng chung cho Python 3.10 trở lên, trên macOS (Intel và Apple Silicon) và Linux x86_64/aarch64 dùng glibc 2.17 trở lên. - **Đối chiếu chỉ báo**: Kết quả 58 chỉ báo kỹ thuật được đối chiếu với TA-Lib C 0.8.1 và QuantConnect LEAN. - **Kiểm tra tham số**: Tham số nến không hợp lệ báo lỗi `InvalidParameterError` thay vì trả kết quả sai lệch. - **Tái cấu trúc từ vnstock_ta sang vnstock_quant**: Gộp và nâng cấp thư viện `vnstock_ta` sang namespace mới `vnstock_quant` với lõi tính toán biên dịch bằng Rust (`_native.abi3.so`). - **58 chỉ báo kỹ thuật hiệu năng cao**: Tính đủ 58 chỉ báo nhanh hơn 25,9 lần so với phiên bản cũ (5.000 phiên, số đo tham khảo, đo trên máy Apple M4 (10 nhân, 16 GB RAM), một luồng, ngày 06/10/2026); lõi Rust nhả khoá GIL của Python trong lúc tính. - **Khắc phục lỗi thuật toán**: Sửa 16 chỉ báo bị sai lệch công thức trong phiên bản cũ (bao gồm CCI, KST, PSAR, Supertrend, Squeeze, OBV, MFI). - **Giữ cú pháp gọi hàm**: Lớp `Indicator` giữ nguyên tên 58 phương thức chỉ báo, tên và giá trị mặc định của tham số; chuyển đổi bằng cách đổi tên gói khi import. Một số chỉ báo cho số khác bản cũ, xem [danh sách khác biệt](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta). ### Mô-đun Chỉ số Tài chính (FA) và Mô hình Điểm số [Mở rộng] - **Tự tính toán 99 chỉ số tài chính**: Tự động tính chỉ số từ hệ thống BCTC chuẩn hoá VAS cho 4 loại hình doanh nghiệp: phi tài chính (`dn`), ngân hàng (`tctd`), chứng khoán (`ctck`) và bảo hiểm (`dnpnt`). - **Chuẩn hoá dòng tiền CFA**: Tích hợp công thức tính toán dòng tiền tự do doanh nghiệp (FCFF) và dòng tiền tự do chủ sở hữu (FCFE). - **Hệ thống mô hình điểm số**: Bổ sung mô hình phân rã DuPont (3 và 5 nhân tố), điểm số dự báo phá sản Altman Z''-score, điểm chất lượng kinh doanh Piotroski F-score và mô hình phát hiện gian lận Beneish M-score. - **Kiểm thử công thức**: Công thức được kiểm thử trên báo cáo tài chính dựng tay theo ví dụ của giáo trình CFA. Cách tính và cách hiệu chỉnh theo chuẩn mực kế toán Việt Nam được ghi ở tài liệu từng chỉ số, để bạn tự tính lại từ báo cáo tài chính. ### Mô-đun Đo lường Rủi ro và Hiệu suất (Risk) [Mở rộng] - **33 thước đo rủi ro chuẩn CFA**: Tích hợp các hàm tính toán Sharpe, Sortino, Treynor, Information Ratio, Alpha, Omega, Ulcer Index và các biến thể VaR / CVaR (lịch sử, phân phối chuẩn, Cornish-Fisher). - **Kiểm định đối chứng quốc tế**: Toàn bộ các thước đo được đối chiếu song song với thư viện `empyrical` và `quantstats` với sai số dấu phẩy động cực nhỏ (≤ 2e-14). - **Thước đo đặc thù cho thị trường Việt Nam**: Bổ sung hệ số đo độ kém thanh khoản Amihud (`risk.amihud`), hệ số Beta hiệu chỉnh Dimson cho cổ phiếu thanh khoản thấp (`risk.dimson_beta`) và các tỷ lệ theo dõi tần suất đứng giá / chạm biên độ trần sàn (`zero_return_ratio`, `limit_hit_ratio`). ### Giao diện gọi hàm JSON cho trợ lý AI - **[Mở rộng]** **Chuẩn hoá JSON Schema cho AI Agent**: Bổ sung hàm `portfolio.schema(name)` và `portfolio.catalog()` xuất schema tự mô tả tham số, hỗ trợ kết nối trực tiếp với các mô hình ngôn ngữ lớn (OpenAI, Claude, Antigravity) và các trợ lý tự động hoá. - **[Mở rộng]** **Thực thi hàm bằng JSON**: Giới thiệu hàm `portfolio.call(name, **kwargs)` cho phép AI kích hoạt các hàm danh mục và định giá bằng payload JSON với quy ước epoch days và phân số thập phân. - **Chẩn đoán cấp quyền và bản build**: Bổ sung hai hàm chẩn đoán chạy cục bộ `vq.entitlement()` và `vq.build_info()`, hỗ trợ theo dõi lượt dùng thử của bản Cộng đồng và kiểm tra tính toàn vẹn của lõi Rust. --- ## Document: Đối chiếu kết quả và tốc độ Trang này ghi các mốc dùng để đối chiếu kết quả của `vnstock_quant` và điều kiện của những phép đo tốc độ. Khi đọc bảng sai số, hãy xem từng hàm được so với nguồn nào, trên bộ dữ liệu nào và theo quy ước tính nào. Số đo tốc độ chỉ phản ánh môi trường thử nghiệm đã ghi, không dự báo thời gian chạy trên máy của bạn. --- ## 1. Phạm vi kiểm tra ### Các nhóm hàm được kiểm tra Các kết quả dưới đây bao phủ năm nhóm hàm của 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`. - **100 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. ### Điều kiện cài đặt và tính toán - **Gói cài dựng sẵn**: Bạn 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. Bạn không cần cài TA-Lib C để tính chỉ báo. - **Phần lõi Rust**: Các phép tính đi qua cùng một phần lõi, không đổi cách tính theo việc máy có cài TA-Lib C hay không. - **So sánh kết quả**: Muốn kiểm tra một số đo, hãy dùng cùng dữ liệu đầu vào và cùng quy ước về kỳ tính, dữ liệu thiếu và giai đoạn đầu chuỗi. --- ## 2. Hệ thống mốc chuẩn đối chiếu thực nghiệm Các nhóm phép tính được đối chiếu với những nguồn sau: | Mốc kiểm định | Phạm vi đối chiếu | Tiêu chí đánh giá | | :--- | :--- | :--- | | **TA-Lib C Core 0.8.1** | 34 chỉ báo kỹ thuật cổ điển | Thư viện chỉ báo C phổ biến; sai số tương đối $\le 10^{-12}$ | | **QuantConnect LEAN** | 14 chỉ báo kỹ thuật nâng cao & dữ liệu SPY | Bộ dữ liệu kiểm thử chỉ báo của LEAN; sai số $\le 10^{-8}$ | | **CFA® Program Curriculum** | 100 chỉ số BCTC VAS, phân rã rủi ro Euler, MWR | Chuẩn mực phân tích tài chính và quản lý tài sản toàn cầu | | **empyrical-reloaded & QuantStats** | 33 thước đo rủi ro và hiệu suất | Khung định lượng kiểm nghiệm chéo các hệ số Sharpe, Sortino, VaR | | **pyxirr** | Hội tụ lợi suất theo dòng tiền (XIRR/MWR) | Kiểm định nghiệm số hội tụ với thuật toán Newton-Raphson | | **NumPy & SciPy** | Các kiểm định thống kê và phân phối xác suất | Độ lệch chuẩn mẫu, Kurtosis, Skewness | --- ## 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. ### Các mức đối chiếu 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)**: Được đối chiếu với **TA-Lib C core 0.8.1**, với sai số tương đối được ghi nhận từ $0.0\text{e}+00$ đến $10^{-12}$ trên dữ liệu kiểm tra. - **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ũ: | Chỉ báo | Nhóm | Mức tin cậy | Chuẩn đối chiếu | Sai số vs TA-Lib C | Đối chiếu LEAN / Định nghĩa gốc | So với thế hệ cũ | | :--- | :--- | :---: | :--- | :---: | :--- | :--- | | `sma` | Trend | A | TA-Lib SMA | **0.0e+00** | — | Khớp chuẩn (1.2e-15) | | `ema` | Trend | A | TA-Lib EMA | **0.0e+00** | LEAN `spy_ema.csv`: 5.7e-14 | Khớp chuẩn (3.8e-16) | | `wma` | Trend | A | TA-Lib WMA | 4.2e-15 | — | Khớp chuẩn (2.2e-16) | | `hma` | Trend | A | Alan Hull / TA-Lib | 1.5e-14 | LEAN `spy_hma.txt`: 5.0e-08 | Khớp chuẩn (5.0e-16) | | `smma` | Trend | A | J. Welles Wilder RMA | 9.2e-16 | — | Khớp chuẩn (0.0e+00) | | `alma` | Trend | B | Arnaud Legoux / LEAN | — | LEAN `spy_alma.txt`: 5.0e-08 | Khớp chuẩn (3.6e-16) | | `vwma` | Trend | B | LEAN VWMA | — | LEAN `spy_with_vwma.csv`: 2.8e-14 | Khớp chuẩn (5.1e-16) | | `adx` | Trend | A | Wilder ADX/DI | **0.0e+00** | LEAN `spy_with_adx.txt`: hội tụ $\le 0.01$ | Khắc phục lệch khởi động | | `psar` | Trend | A | TA-Lib SAREXT / LEAN | **0.0e+00** | LEAN `spy_sarext.txt`: 5.7e-14 | **Đã sửa lỗi logic** | | `supertrend` | Trend | B | TradingView / LEAN | — | LEAN `dwac_supertrend.txt`: 5.0e-08 | **Đã sửa lỗi logic** | | `dm` | Trend | A | TA-Lib PLUS/MINUS_DM | **0.0e+00** | Wilder sums | **Đã sửa lỗi sai lệch** | | `linreg` | Trend | A | TA-Lib LINEARREG | 6.6e-14 | — | Khớp chuẩn (2.0e-15) | | `aroon` | Trend | A | TA-Lib AROON | **0.0e+00** | — | Khớp chuẩn (1.4e-15) | | `rsi` | Momentum | A | TA-Lib RSI (Wilder) | **0.0e+00** | LEAN `spy_with_indicators.txt`: 5.0e-06 | Khắc phục lệch khởi động | | `stoch` | Momentum | A | TA-Lib STOCH | **0.0e+00** | LEAN `spy_with_stoch12k3.txt`: 3.7e-04 | Khớp chuẩn (1.1e-13) | | `stochrsi` | Momentum | A | TradingView / TA-Lib | **0.0e+00** | LEAN `spy_with_StochRSI.csv`: 3.6e-13 | Khắc phục lệch khởi động | | `mom` | Momentum | A | TA-Lib MOM | **0.0e+00** | — | Khớp chuẩn (0.0e+00) | | `roc` | Momentum | A | TA-Lib ROC | **0.0e+00** | LEAN `spy_with_rocp50.txt`: 1.0e-05 | Khớp chuẩn (1.1e-14) | | `ao` | Momentum | B | Bill Williams / LEAN | — | LEAN `spy_ao.txt`: 4.8e-13 | Khớp chuẩn (3.8e-11) | | `cci` | Momentum | A | Donald Lambert CCI | 1.7e-12 | LEAN `spy_with_cci.txt`: 2.2e-03 | **Đã sửa lỗi Mean Deviation** | | `willr` | Momentum | A | Larry Williams %R | **0.0e+00** | LEAN `spy_with_williamsR14.txt`: 4.0e-04 | Khớp chuẩn (3.4e-15) | | `tsi` | Momentum | B | William Blau / LEAN | — | LEAN `spy_tsi.csv`: 2.1e-14 | Khắc phục lệch khởi động | | `cmo` | Momentum | A | Chande Momentum Osc | 2.7e-16 | Chuẩn Chande unsmoothed | **Đã sửa lỗi logic** | | `uo` | Momentum | A | Larry Williams ULTOSC | **0.0e+00** | LEAN `spy_ultosc.txt`: 5.7e-14 | Khớp chuẩn (2.2e-16) | | `fisher` | Momentum | C | John Ehlers Transform | — | Công thức Ehlers gốc: sai số $\le 10^{-9}$ | Khắc phục lệch khởi động | | `cg` | Momentum | C | Ehlers Center of Gravity | — | Công thức Ehlers gốc: sai số $\le 10^{-9}$ | **Đã sửa lỗi tính toán** | | `kst` | Momentum | B | Martin Pring / LEAN | — | LEAN `spy_with_kst.csv`: 8.5e-14 | **Đã sửa lỗi trọng số** | | `macd` | Momentum | A | Gerald Appel MACD | **0.0e+00** | LEAN `spy_with_macd.txt`: 5.0e-06 | Khắc phục lệch khởi động | | `bbands` | Volatility | A | TA-Lib BBANDS | **0.0e+00** | LEAN `spy_bollinger_bands.txt`: 1.1e-04 | Khớp chuẩn (8.9e-12) | | `kc` | Volatility | B | Chester Keltner / TV | — | Công thức Keltner chuẩn True Range | Khớp chuẩn (3.7e-16) | | `atr` | Volatility | A | TA-Lib ATR (Wilder) | **0.0e+00** | Wilder RMA trên True Range | Khắc phục lệch khởi động | | `stdev` | Volatility | A | TA-Lib STDDEV | **0.0e+00** | Phương sai tổng thể (ddof=0) | **Đã sửa lỗi bậc tự do** | | `donchian` | Volatility | A | Richard Donchian | **0.0e+00** | LEAN `spy_with_don50.txt`: 0.0e+00 | Khớp chuẩn (0.0e+00) | | `true_range` | Volatility | A | TA-Lib TRANGE | **0.0e+00** | LEAN `spy_tr.txt`: 7.1e-15 | Khớp chuẩn (0.0e+00) | | `squeeze` | Volatility | C | John Carter TTM Squeeze | — | LazyBear TTM Squeeze: sai số $\le 10^{-7}$ | **Đã sửa lỗi đảo dải Keltner** | | `squeeze_pro` | Volatility | C | Carter TTM Squeeze Pro | — | Đa ngưỡng Keltner (2.0 / 1.5 / 1.0) | **Đã sửa lỗi momentum** | | `obv` | Volume | A | Joe Granville OBV | **0.0e+00** | LEAN `spy_with_obv.txt`: 1.0e-04 | **Đã sửa lỗi nến đứng giá** | | `cmf` | Volume | B | Marc Chaikin CMF | — | LEAN `spy_cmf.txt`: 1.5e-06 | Khớp chuẩn (2.8e-14) | | `ad` | Volume | A | Chaikin A/D Line | **0.0e+00** | LEAN `spy_ad.txt`: 5.0e-06 | Khớp chuẩn (6.9e-14) | | `vp` | Volume | C | Volume Profile | — | Bất biến bảo toàn tổng khối lượng | **Đã sửa lỗi phân bổ bin** | | `vwap` | Volume | B | Anchored Intraday VWAP | — | Nhóm chu kỳ Ngày / Tuần / Tháng: $\le 10^{-9}$ | Khớp chuẩn (0.0e+00) | | `pvo` | Volume | A | Percentage Volume Osc | **0.0e+00** | TA-Lib PPO trên khối lượng | Khắc phục lệch khởi động | | `mfi` | Volume | A | Money Flow Index | 8.9e-14 | Chuẩn Gene Quong & Avrum Soudack | **Đã sửa lỗi mẫu số 0** | | `pivots` | Statistics | C | Pivot Points Standard | — | Traditional, Woodie, DeMark chuẩn | **Đã sửa lỗi khung thời gian** | | `variance` | Statistics | A | TA-Lib VAR | **0.0e+00** | LEAN `spy_var.txt`: 1.1e-10 | **Đã sửa lỗi bậc tự do** | | `hl2` | Statistics | A | TA-Lib MEDPRICE | **0.0e+00** | $(H + L) / 2$ | Khớp chuẩn (0.0e+00) | | `hlc3` | Statistics | A | TA-Lib TYPPRICE | **0.0e+00** | $(H + L + C) / 3$ | Khớp chuẩn (0.0e+00) | | `ohlc4` | Statistics | A | TA-Lib AVGPRICE | **0.0e+00** | $(O + H + L + C) / 4$ | Khớp chuẩn (3.1e-16) | | `midprice` | Statistics | A | TA-Lib MIDPRICE | **0.0e+00** | LEAN `spy_midprice.txt`: 2.8e-14 | Khớp chuẩn (0.0e+00) | *(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 tốc độ xử lý khi tính toàn bộ 58 chỉ báo cho cùng một mã cổ phiếu (5.000 phiên): | Thư viện thực thi | Thời gian xử lý (58 chỉ báo) | Tương quan tốc độ so với thế hệ cũ | Định dạng đầu ra | | :--- | :---: | :---: | :--- | | **`vnstock_quant` (Lõi Rust)** | **1.79 ms** | **Nhanh hơn 77.4x** | Bộ đệm số nguyên/thực phẳng | | **`vnstock_quant` (API chuẩn)** | **5.34 ms** | **Nhanh hơn 25.9x** | `pandas.DataFrame` có đủ index & tên cột | | `pandas-ta` (Python + Numba) | 127.0 ms | Chậm hơn | `pandas.DataFrame` | | `vnstock_ta` thế hệ cũ | 138.5 ms | Mốc cơ sở (1.0x) | `pandas.DataFrame` |

Ở tốc độ 5.34 ms, phần tính 58 chỉ báo cho một cổ phiếu chiếm rất ít thời gian so với việc tải dữ liệu, nên bạn có thể tính lại chỉ báo cho chuỗi nhiều năm mỗi khi dữ liệu cập nhật.

### 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}$: | Chỉ báo kỹ thuật | `vnstock_quant` (API) | Lõi Rust thuần | `vnstock_ta` thế hệ cũ | Mức tăng tốc độ | | :--- | :---: | :---: | :---: | :---: | | `sma` | 21.4 µs | 7.1 µs | 317.0 µs | **14.8x** | | `ema` | 22.6 µs | 8.4 µs | 92.6 µs | **4.1x** | | `smma` (RMA) | 35.3 µs | 19.8 µs | 20.224.0 µs | **573.0x** | | `adx` | 144.0 µs | 96.5 µs | 2.300.0 µs | **15.9x** | | `supertrend` | 86.2 µs | 38.6 µs | 29.790.0 µs | **346.0x** | | `rsi` | 28.1 µs | 15.2 µs | 366.0 µs | **13.0x** | | `cci` | 57.1 µs | 31.4 µs | 13.088.0 µs | **229.0x** | | `linreg` | 42.0 µs | 31.5 µs | 9.893.0 µs | **235.0x** | | `psar` | 71.0 µs | 16.8 µs | 3.124.0 µs | **44.0x** | | `macd` | 58.8 µs | 29.8 µs | 604.0 µs | **10.3x** | | `bbands` | 67.4 µs | 28.5 µs | 640.0 µs | **9.5x** | | `atr` | 34.7 µs | 9.7 µs | 660.0 µs | **19.0x** | ### 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ớ): | Thư viện thực hiện | Thời gian xử lý toàn bộ 1.600 mã | Thời gian trung bình mỗi mã | | :--- | :---: | :---: | | **`vnstock_quant`** | **1.21 giây** | **0.75 ms / mã** | | `vnstock_ta` thế hệ cũ | 14.01 giây | 8.76 ms / mã | | `pandas-ta` | 12.76 giây | 7.97 ms / mã | 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: ```text 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 Ngoài chỉ báo kỹ thuật, các phần về báo cáo tài chính, danh mục và rủi ro cũng được đối chiếu theo những quy ước nêu dưới đây. ### 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) theo CFA tính trên tài sản và vốn chủ bình quân. `vnstock_quant` dùng bình quân đầu năm và cuối năm cho kỳ năm, và bình quân 4 điểm cuối quý (hồ sơ `cfa`: 5 điểm) cho kỳ quý, kể cả quý 4. 3. **Minh bạch bằng cột `reason`**: Thư viện không tự điền số 0 khi thiếu dữ liệu. Ô không có số mang mã lý do trong cột `reason`, ví dụ `INSUFFICIENT_HISTORY` khi doanh nghiệp chưa đủ 4 quý lịch sử, `MISSING_INPUT:` khi thiếu chỉ tiêu, `NOT_APPLICABLE` khi chỉ số không dành cho mẫu ngành đó, để bộ lọc tự động của bạn nhận biết và bỏ qua. Mẫu số âm (ví dụ vốn chủ âm do lỗ luỹ kế) vẫn cho ra số âm, nên hãy kiểm tra dấu của mẫu số khi sàng lọc theo ROE hay P/B. ### 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í giao dịch $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 | Tiêu chí | `vnstock_ta` 1.x hoặc tự ghép nhiều thư viện | Vnstock Quant thế hệ 5 | | :--- | :--- | :--- | | **Cài đặt & Môi trường** | Một số gói cần trình biên dịch C hoặc TA-Lib C, tuỳ máy | Gói nhị phân dựng sẵn, cài trong 1 lệnh duy nhất | | **Kiến trúc phát triển** | Ghép 4–5 thư viện riêng, mỗi thư viện một quy ước | **Lõi Rust an toàn bộ nhớ kết hợp lớp bọc Python tinh gọn** | | **Thời gian xử lý** | 138.5 ms (58 chỉ báo) | **5.34 ms (Nhanh hơn 25.9 lần)** | | **Xử lý quy mô toàn sàn** | 14.0 giây (1.600 mã) | **1.21 giây (Nhanh hơn 11.6 lần)** | | **Độ tin cậy số học** | `vnstock_ta` 1.x: 16 chỉ báo lệch định nghĩa gốc | 34 chỉ báo khớp **TA-Lib C**, 14 chỉ báo khớp dữ liệu kiểm thử **QuantConnect LEAN** | | **Quy chuẩn tài chính** | Tuỳ thư viện | Chuẩn hoá theo **CFA® Institute Curriculum** | | **Đặc thù thị trường VN** | Thường chưa có sẵn quy ước riêng cho Việt Nam | Tích hợp lô 100, biên độ trần/sàn, thuế phí Việt Nam | | **Hỗ trợ AI Agent** | Tuỳ thư viện | Sẵn sàng tích hợp qua hệ sinh thái kỹ năng vnai | `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](/docs/vnstock_quant/tinh-toan/ta) — Tính toán 58 chỉ báo kỹ thuật với lõi Rust. - [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) — Tự tính 100 chỉ số BCTC VAS và mô hình dòng tiền CFA. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — 33 thước đo hiệu suất và rủi ro chuẩn CFA. - [Chuyển đổi từ vnstock_ta](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta) — Hướng dẫn nâng cấp từ vnstock_ta 1.x sang vnstock_quant. --- ## Document: Gọi bằng JSON và MCP > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Các hàm danh mục, định giá và backtest của `vnstock_quant` gọi được bằng **tên hàm cộng một đối tượng JSON tham số**, và trả về JSON. Mỗi hàm có JSON Schema mô tả tham số, nên dùng trực tiếp làm định nghĩa công cụ cho trợ lý AI (MCP, function calling) mà không cần viết lớp chuyển đổi. Lời gọi JSON đi qua cùng lõi Rust và cùng bước kiểm tra quyền như hàm Python, nên một máy chủ MCP chạy trên máy bạn vẫn theo đúng cấp của bạn. | Nhóm | `catalog()` | `schema(name)` | `call(name, **args)` | | :--- | :---: | :---: | :---: | | `portfolio` (gồm các hàm định giá) | Có | Có | Có | | `backtest` | Có | Có | Có | | `ta`, `fa`, `risk`, `micro` | Có | | Dùng hàm Python thường | --- ## Catalog và schema ```python from vnstock_quant import portfolio as pm cat = pm.catalog() # name, group, describe, standard cat.groupby("group").size() # construct, fees, holdings, returns, risk, valuation pm.schema("twr") # {'name': 'twr', 'group': 'returns', 'describe': '...', 'standard': 'CFA L1 QM LM1 p.32–33, Eq.6', # 'parameters': {'type': 'object', 'properties': {...}, 'required': ['dates', 'values']}} ``` Mỗi tham số trong `parameters.properties` có `type`, `description` và `default` nếu có. Trường `standard` ghi chuẩn hoặc tài liệu gốc của phép tính. Định nghĩa công cụ cho mọi hàm danh mục và định giá: ```python tools = [ {"name": s["name"], "description": s["describe"], "input_schema": s["parameters"]} for s in (pm.schema(n) for n in pm.catalog()["name"]) ] len(tools) # 38 ``` Mô-đun backtest có 10 công cụ cùng dạng, schema ghi theo cách MCP đặt tên (`name`, `description`, `input_schema`): ```python from vnstock_quant import backtest as bt list(bt.catalog()["name"]) # ['list_brokers', 'list_profiles', 'list_presets', 'list_indicators', 'eval_rule_dsl', # 'check_rule_dsl_causality', 'detect_limit_events', 'run_backtest', 'run_fixture_demo', 'portfolio_analytics'] bt.schema("run_backtest")["input_schema"]["required"] # ['bars'] ``` --- ## Gọi hàm ```python pm.call("annualize", r=0.20, days=548) # {'value': 0.1290..., 'exponent': 0.666...} pm.call("ddm", r=0.15, d0=5000, stages=[[0.10, 3]], terminal_g=0.05) pm.call( "twr", dates=[19724, 19877, 20090], # số ngày kể từ 1970-01-01 values=[100e6, 112e6, 150e6], flows=[0, 30e6, 0], ) ``` Với backtest, nến đi vào dưới dạng danh sách đối tượng (`date` theo `YYYY-MM-DD`, `open`, `high`, `low`, `close`, `volume`) và bảng quy tắc là đối tượng JSON, đúng dạng trợ lý AI tạo ra từ một câu mô tả: ```python bars = [ {"date": "2024-01-02", "open": 50.0, "high": 50.5, "low": 49.5, "close": 50.2, "volume": 100000}, # ... các phiên tiếp theo, thứ tự thời gian tăng dần ] res = bt.call( "run_backtest", bars=bars, dsl={"entry_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "cross_above", "right": 30}], "exit_rules": [{"left": {"ind": "rsi", "params": {"length": 14}}, "op": "gt", "right": 70}]}, stop_loss_pct=0.07, ) res.keys() # tear_sheet, trades, rejected_orders, open_positions, warnings res["tear_sheet"]["total_return_pct"], res["tear_sheet"]["sharpe_ratio"] ``` Quy ước của lời gọi JSON: - Ngày là số ngày kể từ 01/01/1970 với các hàm danh mục, chuỗi `YYYY-MM-DD` với các công cụ backtest. - Mảng là danh sách số; ma trận là danh sách các hàng. - Tỷ lệ là phân số: `0.18` nghĩa là 18%. - Tham số lạ bị từ chối, để trợ lý AI biết mình gọi sai. - Lỗi trả về có mã ổn định (`QUANT_INVALID_PARAMETER`, `QUANT_INPUT_DATA`, `QUANT_UNKNOWN_FUNCTION`, `QUANT_UNKNOWN_TOOL`) và thông điệp nói rõ tham số nào sai, nhờ đó trợ lý AI tự sửa được lời gọi. ```python from vnstock_quant.errors import InvalidParameterError try: pm.call("twr", dates=[0, 1], values=[1, 2], bogus=1) except InvalidParameterError as e: print(e.code, e) # QUANT_INVALID_PARAMETER [QUANT_INVALID_PARAMETER] `twr` không có tham số `bogus` ``` --- ## Catalog đọc được bằng máy của các nhóm còn lại `ta`, `fa`, `risk` và `micro` dùng hàm Python thường, nhưng catalog của chúng cũng là bảng có cấu trúc để trợ lý AI tra tên, đơn vị và chuẩn đối chiếu trước khi viết mã: ```python from vnstock_quant import fa, risk, ta ta.catalog()[["name", "group", "standard", "confidence"]].head() risk.catalog().to_dict("records")[:2] # name, benchmark, unit, describe, standard fa.catalog()[["id", "describe", "unit", "access"]].head() fa.describe("RT_PRT_ROE") # công thức theo mẫu ngành và hồ sơ ``` --- ## Vnstock MCP [Vnstock MCP](/vnstock-mcp) là máy chủ MCP chạy trên máy bạn, đưa các hàm của `vnstock_quant` tới trợ lý AI dưới dạng công cụ: `quant_ta`, `quant_fa`, `quant_risk`, `quant_portfolio`, `quant_valuation`, `quant_backtest`, cùng `quant_catalog(module, name)` để tra tham số và `quant_entitlement` để xem cấp. Dữ liệu đi vào công cụ là bảng đã tải trong phiên làm việc của MCP, nên trợ lý không phải chép số qua lời nhắc. Quyền và lượt thử giống như khi bạn gọi hàm Python. Danh mục công cụ và hồ sơ (profile) nào bật nhóm nào: [Danh mục công cụ Vnstock MCP](/docs/vnstock-mcp/danh-muc-cong-cu). --- ## Quyền `portfolio` và `valuation` cần cấp Bronze; backtest một mã với 10 chỉ báo cơ bản mở cho mọi cấp theo lượt thử, các công cụ còn lại của backtest từ Bronze. Bảng đầy đủ: [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc). --- ## Đọc tiếp - [Danh mục](/docs/vnstock_quant/tinh-toan/portfolio) — Ý nghĩa và cách dùng của 38 hàm trong catalog. - [Dữ liệu và tín hiệu trong backtest](/docs/vnstock_quant/backtest/du-lieu-va-tin-hieu) — Cấu trúc bảng quy tắc `rule_dsl`. - [Hướng dẫn cho trợ lý AI](/onboard/agent-guide) — Thiết lập môi trường làm việc với trợ lý AI. --- ## Document: Tải dữ liệu bằng vnstock `vnstock_quant` không truy xuất dữ liệu: bạn đưa bảng `pandas` vào. Khi đã cài `vnstock` thế hệ 5 cùng môi trường, mỗi nhóm hàm có một điểm vào tải dữ liệu đúng dạng cần dùng. Dữ liệu tải qua `vnstock` tính vào hạn mức chung của tài khoản theo quy tắc của `vnstock`; phần tính toán sau đó chạy trên máy và không tốn hạn mức. ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant[vnstock]" ``` Thiếu `vnstock` thế hệ 5 thì các điểm vào dưới đây báo `DependencyError` với lệnh cài trong `action`. --- ## Điểm vào theo nhóm hàm | Cần gì | Gọi | Trả về | Mức | | :--- | :--- | :--- | :--- | | Nến cho chỉ báo kỹ thuật | `ta.from_vnstock(symbol, start, end, interval="1D")` | `Indicator` đã nạp nến, tính ngay được | Ổn định | | Lợi suất của mã và chỉ số tham chiếu | `risk.from_vnstock(symbol, benchmark="VNINDEX", start)` | `DataFrame` hai cột `returns`, `benchmark`, căn theo ngày chung | Thử nghiệm | | Báo cáo tài chính, giá và số cổ phiếu cho chỉ số tài chính | `fa.Dataset.load(symbols, period="both")` | `Dataset` cho `fa.ratios()` | Thử nghiệm | | Giá đã điều chỉnh theo sự kiện quyền | `prices.from_vnstock(symbol, start)` | OHLCV đơn vị đồng, bảng hệ số trong `attrs["factors"]` | Thử nghiệm | | Nến cho backtest | `Market().equity(symbol).ohlcv(start, end)` của `vnstock` | Bảng nến đưa thẳng vào `backtest.run()` | Thử nghiệm | | Dữ liệu khớp lệnh cho vi cấu trúc | `Market().equity(symbol).trades(limit=1000)` của `vnstock` | Bảng tick cho `micro.bars()` | Thử nghiệm | Cột **Mức** là mức ổn định của nhóm hàm nhận dữ liệu đó: nhóm thử nghiệm còn có thể đổi tên hàm, tham số và cấu trúc kết quả giữa các bản phát hành. Xem [mức độ ổn định của từng nhóm hàm](/docs/vnstock_quant/gioi-thieu#muc-do-on-dinh-cua-tung-nhom-ham). ```python from vnstock_quant import fa, prices, risk, ta ind = ta.from_vnstock("HPG", start="2024-01-01", end="2024-12-31") rsi = ind.rsi(length=14) data = risk.from_vnstock("FPT", benchmark="VNINDEX", start="2022-01-01") beta = risk.beta(data["returns"], data["benchmark"]) ds = fa.Dataset.load(["FPT", "VCB"]) roe = fa.ratios(ds, ids=["RT_PRT_ROE"]) bars = prices.from_vnstock("FPT", start="2019-01-01") # giá đã điều chỉnh, đơn vị đồng ``` Backtest và vi cấu trúc nhận bảng thô của `vnstock`: ```python from vnstock import Market from vnstock_quant import backtest as bt, micro df = Market().equity("FPT").ohlcv(start="2021-01-01", end="2026-09-30") res = bt.run(df, entries=df["close"] > df["close"].rolling(200).mean(), exits=df["close"] < df["close"].rolling(50).mean()) ticks = Market().equity("FPT").trades(limit=1000) m1 = micro.bars(ticks, by="time", size="1min") ``` --- ## Điều cần biết trước khi tải | Chủ đề | Chi tiết | | :--- | :--- | | **Đơn vị giá** | `ohlcv()` trả giá tính bằng nghìn đồng; `trade_history()` và `prices.from_vnstock` trả đồng. `backtest.run` có `price_unit="auto"` để nhận ra; `prices.adjust` có `unit="auto"`. Trong một phiên làm việc hãy giữ một đơn vị. | | **Chuỗi dài** | `vnstock` trả tối đa 1.000 phiên hoặc 1.000 lệnh mỗi lần gọi. `risk.from_vnstock` và `prices.from_vnstock` tự tải theo cửa sổ ba năm; với `ohlcv()` bạn tự chia khoảng ngày. | | **Số mã mỗi lần tải báo cáo tài chính** | Cộng đồng 3, Bronze 100, Silver 400, Golden và Diamond toàn thị trường; vượt thì `TierRequiredError` với mã `QUANT_SCOPE_LIMIT`. | | **Giá chưa điều chỉnh cho chỉ số định giá** | Cần cấp quyền sử dụng của `vnstock`. Bản Cộng đồng gọi `Dataset.load(..., prices=False)`; P/E, P/B khi đó báo `MISSING_MARKET` ở cột `reason`. | | **Dữ liệu đã điều chỉnh hay chưa** | `ohlcv()` là giá đã điều chỉnh theo nguồn; `trade_history()` là giá thô kèm giá tham chiếu, trần, sàn. Muốn kiểm từng sự kiện quyền thì đi đường `prices`. | | **Hạn mức chung** | Mỗi lần tải là lượt gọi của `vnstock`; `Dataset.load()` tải nhiều bảng cho mỗi mã. Xem mức còn lại ở [trang tài khoản](/account). | Khi làm việc lặp lại trên cùng dữ liệu, lưu bảng ra đĩa hoặc để [vnstock_pipeline](/docs/vnstock-pipeline) lưu vào kho rồi đọc lại; `vnstock_quant` nhận `DataFrame` từ bất kỳ nguồn nào bạn đã chuẩn bị. --- ## Đọc tiếp - [Quy ước dữ liệu và lỗi](/docs/vnstock_quant/bat-dau/quy-uoc-du-lieu-va-loi) — Dạng dữ liệu mà từng nhóm hàm nhận. - [Quyền dùng và hạn mức](/docs/vnstock_quant/bat-dau/quyen-dung-va-han-muc) — Số mã theo cấp và lượt dùng thử. - [Giá điều chỉnh](/docs/vnstock_quant/du-lieu/gia-dieu-chinh) — Khi nào cần đi đường `prices` thay cho `ohlcv()`. --- ## Document: Chỉ số tài chính > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.fa` tính 100 chỉ số từ báo cáo tài chính theo bốn mẫu ngành: doanh nghiệp phi tài chính (`dn`), ngân hàng (`tctd`), công ty chứng khoán (`ctck`) và bảo hiểm (`dnpnt`). Mỗi chỉ số chỉ áp dụng cho một số mẫu ngành; chỉ số không áp dụng trả `NaN` kèm lý do `NOT_APPLICABLE`. Bạn có thể tra công thức của từng chỉ số, chọn kỳ quý (TTM) hay kỳ năm, và xem vì sao một ô không có số. Bản Cộng đồng tính được 10 chỉ số cơ bản: `RT_VALUE_PE`, `RT_VALUE_PB`, `RT_VALUE_EPS`, `RT_VALUE_BVPS`, `RT_PRT_ROE`, `RT_PRT_ROA`, `RT_PRT_GROSS_MARGIN`, `RT_PRT_NET_MARGIN`, `RT_LQD_CR`, `RT_LEV_DE`. Các chỉ số còn lại cần gói Bronze trở lên (cột `access` của `fa.catalog()`). --- ## Cách tính kỳ quý (TTM) Với `period="quarter"`, mỗi dòng quý là số liệu 12 tháng gần nhất tính đến cuối quý đó: - **Chỉ tiêu thời kỳ** (doanh thu, lợi nhuận, dòng tiền): cộng 4 quý gần nhất. - **Chỉ tiêu thời điểm dùng làm mẫu số bình quân** (tài sản, vốn chủ, phải thu...): trung bình 4 điểm cuối quý gần nhất với hồ sơ `vn`, 5 điểm với hồ sơ `cfa`. - **Dòng quý 4** lấy số liệu từ BCTC năm của năm đó (đã kiểm toán): chỉ tiêu thời kỳ là số cả năm, giá trị cuối kỳ là số cuối năm. Mẫu số bình quân vẫn là 4 (hoặc 5) điểm cuối quý như các quý khác, với điểm cuối là số cuối năm đã kiểm toán, nên chuỗi quý không bị nhảy ở quý 4. - **Các quý đầu tiên** của dữ liệu trả `NaN` với lý do `INSUFFICIENT_HISTORY`: ba quý đầu chưa đủ 4 quý để cộng dồn, và quý 4 của năm đầu tiên chưa có cuối năm trước để tính bình quân. --- ## Chuẩn bị dữ liệu đầu vào với Dataset Lớp `Dataset` gom báo cáo tài chính, giá đóng cửa và số cổ phiếu lưu hành của các mã bạn chọn vào một đối tượng để các hàm tính toán dùng tiếp. ### Cách 1: Tải trực tiếp qua vnstock ```python from vnstock_quant import fa # Tải BCTC năm và quý, giá và số cổ phiếu của FPT và VCB ds = fa.Dataset.load(["FPT", "VCB"]) print(ds) # Dataset(FPT:DN, VCB:TCTD) ``` Mặc định `Dataset.load()` tải cả BCTC năm và quý (`period="both"`). Nên giữ mặc định này: dòng quý 4 cần BCTC năm, và `fa.ratios(..., period="year")` chỉ có số khi đã tải BCTC năm. Mẫu ngành được nhận diện tự động (`DN`, `TCTD`...); bạn có thể chỉ định bằng `com_type`.

Dataset.load() truy xuất nhiều bảng cho mỗi mã, nên có thể dùng nhiều lượt trong hạn mức chung. Bản Cộng đồng cho phép tối đa 3 mã trong một lần gọi và cần prices=False, vì giá chưa điều chỉnh cần cấp quyền sử dụng (xem trang bản Cộng đồng). Nếu cần xử lý nhiều mã, hãy chuẩn bị dữ liệu theo từng nhóm và cân nhắc lưu dữ liệu trên máy để dùng lại.

### Cách 2: Tự nạp từ DataFrame cá nhân Nếu bạn đã có sẵn dữ liệu BCTC, hãy nạp vào `Dataset` ở dạng long (các cột `period`, `id`, `value`), dùng mã chỉ tiêu của `vnstock`. Chỉ số dùng mẫu số bình quân (ROE, ROA...) cần ít nhất hai kỳ: ```python import pandas as pd from vnstock_quant import fa # Dữ liệu BCTC năm mẫu dạng long, hai năm liên tiếp rows = [] for period, revenue, npat, np_parent, equity, assets in [ ("2023", 1000e9, 150e9, 140e9, 1000e9, 1800e9), ("2024", 1200e9, 190e9, 180e9, 1200e9, 2000e9), ]: rows += [ {"period": period, "id": "IS_NET_REVENUE", "value": revenue}, {"period": period, "id": "IS_NET_PROFIT_AFTER_TAX", "value": npat}, {"period": period, "id": "IS_PROFIT_AFTER_TAX_FOR_SHAREHOLDERS_OF_PARENT_COMPANY", "value": np_parent}, {"period": period, "id": "BS_EQUITY", "value": equity}, {"period": period, "id": "BS_TOTAL_ASSETS", "value": assets}, ] ds_own = fa.Dataset.from_frames({"AAA": [pd.DataFrame(rows)]}, com_type="dn") # Dữ liệu chỉ có kỳ năm nên phải tính với period="year" print(fa.ratios(ds_own, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"], period="year")) ``` ```text symbol period id value unit reason 0 AAA 2023 RT_PRT_ROE NaN ratio INSUFFICIENT_HISTORY 1 AAA 2024 RT_PRT_ROE 0.163636 ratio NaN 2 AAA 2023 RT_PRT_ROA NaN ratio INSUFFICIENT_HISTORY 3 AAA 2024 RT_PRT_ROA 0.094737 ratio NaN 4 AAA 2023 RT_PRT_NET_MARGIN 0.150000 ratio NaN 5 AAA 2024 RT_PRT_NET_MARGIN 0.158333 ratio NaN ``` ROE năm 2024 = 180 / ((1.000 + 1.200) / 2) = 16,36%. Năm 2023 không có năm trước để tính vốn chủ bình quân nên trả `INSUFFICIENT_HISTORY`. Nếu gọi với `period="quarter"` (mặc định) trên dữ liệu chỉ có kỳ năm, kết quả là bảng rỗng. Để tính chỉ số định giá (P/E, P/B, EV/EBITDA...), truyền thêm `prices={"AAA": df_gia}` với các cột `time`, `close`, `total_shares`. --- ## Tính toán chỉ số với fa.ratios() ```python # Tính ROE, ROA và biên lợi nhuận ròng theo kỳ quý (TTM) ratios = fa.ratios(ds, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"]) # Xoay các chỉ số thành cột để đọc theo thời gian ts = fa.ratios(ds, ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_PRT_NET_MARGIN"], format="time_series") print(ts.loc["FPT"].tail(4)) ``` ```text id RT_PRT_NET_MARGIN RT_PRT_ROA RT_PRT_ROE period 2025-Q3 0.1591 0.1156 0.2737 2025-Q4 0.1602 0.1150 0.2725 2026-Q1 0.1670 0.1208 0.2682 2026-Q2 0.1718 0.1278 0.2647 ``` Kết quả dạng long được sắp theo mã, rồi theo chỉ số, rồi theo kỳ. Vì vậy `print(ratios)` thường chỉ hiện vài dòng đầu và cuối, đúng những ô `NaN`: các quý đầu chưa đủ lịch sử để tính TTM, và với VCB thì `RT_PRT_NET_MARGIN` không áp dụng cho ngân hàng (`NOT_APPLICABLE`). Bảng vẫn có số ở các kỳ khác. Để xem nhanh ô nào trống và vì sao: ```python # Đếm số ô trống theo mã, chỉ số và lý do print(ratios[ratios["value"].isna()].groupby(["symbol", "id", "reason"], observed=True).size()) ``` ### Các tham số quan trọng | Tham số | Giá trị lựa chọn | Ý nghĩa | | :--- | :--- | :--- | | `ids` | `["RT_..."]` hoặc `None` | Danh sách mã chỉ số cần tính. `None`: tính mọi chỉ số áp dụng được cho mẫu ngành của từng mã và cấp quyền của bạn; chỉ số cần cấp cao hơn bị bỏ qua kèm cảnh báo. | | `period` | `"quarter"` (mặc định) hoặc `"year"` | `"quarter"`: mỗi dòng là 12 tháng gần nhất (TTM), xem mục Cách tính kỳ quý. `"year"`: tính trên BCTC năm. | | `profile` | `"vn"` (mặc định) hoặc `"cfa"` | Hồ sơ phương pháp luận. `"vn"` theo cách thị trường Việt Nam công bố số liệu; `"cfa"` theo định nghĩa của giáo trình CFA. Xem `fa.profiles()`. | | `overrides` | `{"tên_nút": giá_trị}` | Thay một nút của hồ sơ, ví dụ `{"quarter_avg_points": 5}`. | | `format` | `"long"` (mặc định), `"wide"`, `"time_series"` | Định dạng kết quả. | Hai hồ sơ khác nhau ở các nút sau: | Nút | `vn` | `cfa` | | :--- | :--- | :--- | | `quarter_avg_points` | 4 điểm cuối quý | 5 điểm cuối quý (thêm cuối quý ngay trước cửa sổ 12 tháng) | | Ngày định giá | Phiên cuối cùng trước hoặc bằng ngày cuối quý kế tiếp + 14 ngày | Phiên cuối cùng trước hoặc bằng ngày cuối kỳ | Giá đóng cửa và số cổ phiếu luôn lấy trong cùng một phiên, nên P/E = giá / EPS và P/B = giá / BVPS trong cùng một dòng. Kỳ năm dùng ngày định giá của quý 4 năm đó, nên dòng năm trùng dòng quý 4. Một số chỉ số có công thức riêng cho từng hồ sơ (ví dụ `RT_EFF_DIO` dùng tồn kho theo giá gốc với `vn`, giá trị thuần với `cfa`); `fa.describe()` ghi rõ. ### Định dạng đầu ra 1. **`format="long"` (mặc định)**: các cột `symbol`, `period`, `id`, `value`, `unit`, `reason`. Phù hợp để lưu trữ hoặc lọc: ```python ratios.query('symbol == "VCB" and id == "RT_PRT_ROE"').tail(4) ``` 2. **`format="wide"`**: chỉ mục là (`symbol`, `id`), mỗi kỳ là một cột, dễ đọc xu hướng qua các kỳ. 3. **`format="time_series"`**: chỉ mục là (`symbol`, `period`), mỗi chỉ số là một cột, thuận tiện đưa vào mô hình hồi quy hoặc học máy.

Kết quả của fa.ratios() mang từ điển mô tả ở attrs["dictionary"], nên bạn tra được ngay các mã viết tắt như COF, CIR, DIO, NIM.

```python info = ratios.attrs["dictionary"]["RT_BANK_COF"] print(info) # {'name': 'Chi phí vốn', 'name_en': 'Cost of funds', # 'describe': 'Chi phí lãi và tương tự (TTM, mang dấu âm) / nợ chịu lãi bình quân (nợ NHNN, tiền gửi và vay TCTD, tiền gửi khách hàng, giấy tờ có giá).', # 'unit': 'ratio', 'category': 'banking'} ``` --- ## Cột reason: vì sao một ô không có số `vnstock_quant` không tự điền số 0 khi thiếu dữ liệu đầu vào. Khi một ô mang giá trị `NaN`, cột `reason` cho biết nguyên nhân: | Mã `reason` | Giải thích | | :--- | :--- | | `MISSING_INPUT:` | BCTC thiếu chỉ tiêu `` mà công thức cần. Chỉ tiêu bắt đầu bằng `NT_` nằm trong thuyết minh BCTC (ví dụ nợ xấu, CASA của ngân hàng). | | `INSUFFICIENT_HISTORY` | Chưa đủ kỳ trước đó để cộng dồn TTM, tính bình quân hoặc so sánh với kỳ trước. | | `ZERO_DENOMINATOR` | Mẫu số bằng 0. Mẫu số âm (ví dụ vốn chủ âm) vẫn cho ra số âm, không trả `NaN`. | | `NOT_APPLICABLE` | Chỉ số không áp dụng cho mẫu ngành này (ví dụ biên lợi nhuận ròng với ngân hàng, NIM với doanh nghiệp phi tài chính). | | `MISSING_MARKET` | Chỉ số định giá nhưng không có giá đóng cửa hoặc số cổ phiếu tại ngày định giá. | --- ## Quy ước dấu và đơn vị - Tỷ lệ là phân số thập phân (`0.18` là 18%). Cột `unit` cho biết đơn vị: `ratio`, `times` (lần), `days` (ngày), `VND`, `VND/share`, `shares`. - Bốn chỉ số ngân hàng giữ **dấu âm** của chi phí và dự phòng, như cách số liệu thị trường thường hiển thị: `RT_BANK_COF`, `RT_BANK_CIR`, `RT_BANK_NPL_COVERAGE`, `RT_BANK_PROVISION_TO_LOANS`. Ví dụ VCB năm 2025 có `RT_BANK_CIR = -0.348`, tức chi phí hoạt động bằng 34,8% tổng thu nhập hoạt động. Dùng `abs()` nếu bạn cần độ lớn. - EPS, BVPS, doanh thu và dòng tiền mỗi cổ phiếu chia cho số cổ phiếu lưu hành tại ngày định giá của từng kỳ, chưa điều chỉnh theo cổ tức bằng cổ phiếu hay phát hành thêm. Khi so sánh EPS qua nhiều năm, hãy lưu ý các đợt chia cổ phiếu.
  • Dòng quý 4 và dòng năm: các chỉ số dùng mẫu số bình quân (ROE, ROA, NIM, số ngày thu tiền...) ở dòng quý 4 tính theo bình quân 4 điểm cuối quý, còn dòng năm tính theo bình quân đầu năm và cuối năm, nên hai dòng có thể chênh nhẹ. Các chỉ số khác của dòng quý 4 trùng dòng năm.
  • Tăng trưởng tín dụng và huy động (RT_BANK_LOAN_GROWTH, RT_BANK_DEPOSIT_GROWTH): kỳ quý là tăng trưởng một quý so với cuối quý trước (kể cả quý 4), kỳ năm là tăng trưởng so với cuối năm trước.
  • CIR và thu nhập ngoài lãi (RT_BANK_CIR, RT_BANK_NOII) tính trên số riêng của quý, không phải TTM, kể cả quý 4; dòng năm là số cả năm. Ngân hàng thường dồn chi phí vào quý 4, nên CIR quý 4 hay cao hơn các quý khác (VCB quý 4/2025: −0,391, cả năm 2025: −0,348).
  • Chỉ số định giá dùng giá tại ngày định giá của hồ sơ (bảng hồ sơ ở trên), không dùng ngày BCTC được công bố. Với hồ sơ vn, giá đó có thể nằm sau ngày công bố BCTC vài tháng; kỳ gần nhất dùng giá mới nhất cho tới ngày định giá. Nếu dùng chỉ số định giá cho kiểm định chiến lược, hãy tự ghép giá theo ngày công bố BCTC.
--- ## Các nhóm chỉ số tiêu biểu Danh sách đầy đủ 100 chỉ số, kèm công thức và mẫu ngành áp dụng, có trong `fa.catalog()`. Dưới đây là các chỉ số hay dùng. ### 1. Khả năng sinh lợi - `RT_PRT_ROE`: Lợi nhuận cổ đông công ty mẹ (TTM) / vốn chủ của cổ đông công ty mẹ bình quân. Ngân hàng chia cho tổng vốn chủ bình quân; kỳ năm của ngân hàng dùng lợi nhuận sau thuế toàn bộ. - `RT_PRT_ROA`: Lợi nhuận cổ đông công ty mẹ (TTM) / tổng tài sản bình quân. - `RT_PRT_ROCE`: EBIT / (tổng tài sản − nợ ngắn hạn) bình quân. - `RT_PRT_GROSS_MARGIN`: Lợi nhuận gộp / doanh thu thuần. - `RT_PRT_NET_MARGIN`: Lợi nhuận sau thuế toàn bộ (gồm cổ đông không kiểm soát) / doanh thu thuần. Không áp dụng cho ngân hàng. - `RT_PRT_EBITDA_MARGIN`: EBITDA / doanh thu thuần. EBIT trong thư viện là lợi nhuận hoạt động cốt lõi: lợi nhuận gộp − chi phí bán hàng − chi phí quản lý, không gồm thu nhập và chi phí tài chính hay thu nhập khác. EBITDA = EBIT + khấu hao trên báo cáo lưu chuyển tiền tệ. ### 2. Đòn bẩy và khả năng thanh toán - `RT_LEV_DE`: **Tổng nợ phải trả** / vốn chủ sở hữu. Tỷ lệ nợ vay / vốn chủ là `RT_LEV_LOAN_EQUITY`. - `RT_LEV_NET_DEBT`: Vay ngắn và dài hạn − tiền và tương đương tiền − đầu tư tài chính ngắn hạn (VND). - `RT_LEV_NET_DEBT_EBITDA`: Nợ vay ròng / EBITDA (TTM). - `RT_LEV_INTEREST_COVERAGE`: EBIT / chi phí lãi vay (TTM). - `RT_LQD_CR`: Tài sản ngắn hạn / nợ ngắn hạn. - `RT_LQD_QR`: Với hồ sơ `vn`, kỳ quý dùng (tài sản ngắn hạn − tồn kho) / nợ ngắn hạn, kỳ năm dùng (tiền + phải thu ngắn hạn) / nợ ngắn hạn. Hồ sơ `cfa` dùng (tiền + đầu tư ngắn hạn + phải thu ngắn hạn) / nợ ngắn hạn. - `RT_LQD_CASH_RATIO`: Tiền và tương đương tiền / nợ ngắn hạn. ### 3. Hiệu quả hoạt động - `RT_EFF_ATR`: Doanh thu thuần / tổng tài sản bình quân. - `RT_EFF_INVENTORY_TURNOVER`: Giá vốn hàng bán / tồn kho bình quân (hồ sơ `vn` dùng tồn kho theo giá gốc, trước dự phòng). - `RT_EFF_RECEIVABLE_TURNOVER`: Doanh thu thuần / phải thu khách hàng bình quân. - `RT_EFF_DIO`, `RT_EFF_DSO`, `RT_EFF_DPO`: Số ngày tồn kho, thu tiền, thanh toán (365 ngày). - `RT_EFF_CASH_CYCLE`: DSO + DIO − DPO. ### 4. Ngân hàng (mẫu TCTD) - `RT_BANK_NIM`: Thu nhập lãi thuần (TTM) / tài sản sinh lãi bình quân (tiền gửi NHNN, tiền gửi và cho vay TCTD khác, chứng khoán đầu tư, dư nợ gộp). - `RT_BANK_YIEA`: Thu nhập lãi và tương tự (TTM) / tài sản sinh lãi bình quân. - `RT_BANK_COF`: Chi phí lãi (TTM, dấu âm) / nợ chịu lãi bình quân. - `RT_BANK_CIR`: Chi phí hoạt động (dấu âm) / tổng thu nhập hoạt động, số riêng của quý. - `RT_BANK_CASA`: (Tiền gửi không kỳ hạn + ký quỹ + vốn chuyên dùng) / tiền gửi khách hàng. Cần thuyết minh BCTC. - `RT_BANK_LDR`: Dư nợ gộp / tiền gửi khách hàng (tỷ lệ phân tích, không phải tỷ lệ theo quy định của NHNN). - `RT_BANK_NPL`: Nợ nhóm 3–5 / dư nợ gộp. Cần thuyết minh BCTC. - `RT_BANK_NPL_COVERAGE`: Dự phòng rủi ro cho vay (dấu âm) / nợ nhóm 3–5. - `RT_BANK_PROVISION_TO_LOANS`: Chi phí dự phòng rủi ro tín dụng (TTM, dấu âm) / dư nợ gộp bình quân. - `RT_BANK_CAR`: Hệ số an toàn vốn chép từ thuyết minh, không tính lại. `Dataset.load()` tự tải thuyết minh cho ngân hàng (cần gói quyền sử dụng). Nếu không tải được, các chỉ số cần chỉ tiêu `NT_` trả `MISSING_INPUT`. ### 5. Dòng tiền tự do theo CFA - `RT_CF_FCFF`: Lưu chuyển tiền kinh doanh + lãi vay đã trả × (1 − thuế suất hiệu dụng) − (chi mua TSCĐ − thu thanh lý TSCĐ). Theo VAS, lãi vay đã trả nằm trong dòng tiền kinh doanh nên được cộng lại sau thuế. - `RT_CF_FCFE`: Lưu chuyển tiền kinh doanh − đầu tư TSCĐ thuần + vay mới − trả nợ gốc. Các chỉ số dựa trên lưu chuyển tiền thuần từ hoạt động kinh doanh (`RT_VALUE_P_CF`, `RT_VALUE_CFPS`, `RT_CF_CROA`, `RT_CF_CROE`, `RT_CF_INCOME_QUALITY`, `RT_CF_DEBT_COVERAGE`, `RT_CF_DIVIDEND_PAYMENT`, `RT_CF_TO_REVENUE`) không áp dụng cho ngân hàng và công ty chứng khoán (`NOT_APPLICABLE`). Dòng tiền kinh doanh của hai loại hình này chủ yếu là tiền gửi, cho vay và mua bán chứng khoán, nên không đo được khả năng tạo tiền. ### 6. Phân rã DuPont và các điểm số - **DuPont 3 nhân tố**: `RT_DUPONT_NET_MARGIN` × `RT_DUPONT_ASSET_TURNOVER` × `RT_DUPONT_LEVERAGE` = ROE (cùng dùng lợi nhuận và vốn chủ của cổ đông công ty mẹ). - **DuPont 5 nhân tố theo CFA**: `RT_DUPONT_TAX_BURDEN` (lợi nhuận sau thuế / lợi nhuận trước thuế) × `RT_DUPONT_INTEREST_BURDEN` (lợi nhuận trước thuế / EBIT, có thể lớn hơn 1 vì gồm thu nhập tài chính) × `RT_DUPONT_EBIT_MARGIN` × vòng quay tài sản × đòn bẩy. Vì ROE tính trên lợi nhuận của cổ đông công ty mẹ, nhân thêm `RT_DUPONT_PARENT_SHARE` (lợi nhuận cổ đông công ty mẹ / lợi nhuận sau thuế) thì tích sáu thành phần bằng đúng ROE. Ví dụ FPT năm 2025: 0,835 × 0,861 × 1,187 × 0,157 × 0,876 × 2,416 = 0,283. - **Altman Z''** (`RT_SCORE_ALTMAN_Z2`): 6,56·X1 + 3,26·X2 + 6,72·X3 + 1,05·X4, chỉ dùng số liệu BCTC; dưới 1,1 là vùng nguy cơ, trên 2,6 là vùng an toàn. - **Piotroski F-score** (`RT_SCORE_PIOTROSKI_F`): tổng 9 tín hiệu 0/1 so với cùng kỳ năm trước, từ 0 đến 9. - **Beneish M-score** (`RT_SCORE_BENEISH_M`): mô hình 8 biến; trên −1,78 là dấu hiệu có thể điều chỉnh lợi nhuận. Ngưỡng được đề xuất cho mẫu doanh nghiệp Mỹ, chỉ nên dùng để sàng lọc. - **Tỷ lệ dồn tích** (`RT_QUALITY_ACCRUALS_BS`, `RT_QUALITY_ACCRUALS_CF`): theo bảng cân đối và theo lưu chuyển tiền tệ, đo chất lượng lợi nhuận kế toán. Tài sản hoạt động thuần (NOA) loại tiền và đầu tư ngắn hạn; tương ứng, bản theo lưu chuyển tiền tệ loại tiền chi cho vay, gửi có kỳ hạn và tiền thu hồi khỏi dòng tiền đầu tư, nên hai bản đo cùng một khái niệm. Các chỉ số nhóm 5 và 6 cần gói Bronze trở lên (`fa_advanced`). --- ## Tra cứu công thức và catalog ```python # Xem cách tính, công thức theo mẫu ngành và theo hồ sơ của ROE print(fa.describe("RT_PRT_ROE")) # Xem toàn bộ danh mục chỉ số và nhóm quyền catalog_df = fa.catalog() print(catalog_df[["id", "name", "category", "access"]].head(15)) # Lọc các chỉ số áp dụng cho ngân hàng print(catalog_df[catalog_df["templates"].str.contains("TCTD")][["id", "name"]]) # Xem các nút của hồ sơ 'vn' và 'cfa' print(fa.profiles()) ``` --- ## Đọc tiếp - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino, VaR và thanh khoản Amihud. - [Quản lý danh mục đầu tư](/docs/vnstock_quant/tinh-toan/portfolio) — Tối ưu danh mục và mô phỏng chi phí giao dịch Việt Nam. - [Mô hình định giá](/docs/vnstock_quant/tinh-toan/valuation) — Định giá cổ phiếu dựa trên dòng cổ tức và chỉ số P/E. --- ## Document: Danh mục > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.portfolio` giúp bạn đo lợi suất khi danh mục có nạp hoặc rút tiền, mô phỏng lịch tái cân bằng và xem mức đóng góp của từng tài sản. Bạn cũng có thể đặt chi phí trong mô phỏng, tính tỷ trọng danh mục và quy đổi tỷ trọng thành số cổ phiếu theo lô.

Các hàm trong mô-đun portfolio yêu cầu tài khoản từ cấp Bronze trở lên. Phép tính vẫn tính vào hạn mức sử dụng chung của tài khoản.

--- ## Đo lường hiệu suất tài khoản: TWR và MWR Khi bạn nạp hoặc rút tiền trong kỳ, chỉ lấy giá trị cuối kỳ chia cho giá trị đầu kỳ sẽ không phản ánh đúng hiệu quả danh mục. Hai cách tính dưới đây xử lý dòng tiền theo hai góc nhìn: 1. **TWR (lợi suất theo thời gian)**: Tách tác động của các lần nạp, rút tiền để so sánh kết quả danh mục qua các giai đoạn hoặc với một chỉ số tham chiếu. 2. **MWR (lợi suất theo dòng tiền)**: Tính cả thời điểm và quy mô của dòng tiền bạn đưa vào hoặc rút ra. Hàm dùng cách tính tỷ suất hoàn vốn nội bộ theo ngày (XIRR, quy ước Actual/365). ```python import pandas as pd from vnstock_quant import portfolio as pm # 1. Tính TWR: Cần giá trị danh mục NGAY TRƯỚC mỗi lần biến động dòng tiền và dòng tiền phát sinh # Ví dụ: Ban đầu có 100 triệu, ngày 03/06 góp thêm 30 triệu (lúc đó danh mục trị giá 112 triệu), cuối năm đạt 150 triệu values = pd.Series([100e6, 112e6, 150e6], index=pd.to_datetime(["2024-01-02", "2024-06-03", "2025-01-02"])) flows = pd.Series([30e6], index=[pd.Timestamp("2024-06-03")]) twr_result = pm.twr(values, flows) print(f"Lợi suất TWR: {twr_result['twr']:.4f} (Quy đổi theo năm: {twr_result['annualized']:.4f})") # 2. Tính MWR (IRR): Dòng tiền đứng ở góc nhìn nhà đầu tư (dòng tiền góp vốn là âm, rút vốn / giá trị cuối kỳ là dương) cash_flows = pd.Series([-100e6, -30e6, 150e6], index=values.index) mwr_return = pm.mwr(cash_flows) print(f"Lợi suất MWR (IRR): {mwr_return:.4f}/năm") ``` --- ## Mô phỏng danh mục và chi phí giao dịch Việt Nam Khi giá từng cổ phiếu thay đổi, tỷ trọng thực tế của chúng cũng thay đổi. `pm.portfolio_returns()` cho phép bạn tính lợi suất trong trường hợp giữ nguyên danh mục hoặc tái cân bằng theo lịch: ```python import numpy as np import pandas as pd from vnstock_quant import portfolio as pm # Giả lập chuỗi lợi suất ngày của 5 cổ phiếu names = ["FPT", "VCB", "HPG", "MWG", "SSI"] returns_df = ... # DataFrame cột là tên cổ phiếu, hàng là chỉ mục ngày target_weights = pd.Series([0.30, 0.25, 0.20, 0.15, 0.10], index=names) # Chiến lược 1: Mua và nắm giữ (Buy & Hold - không tái cân bằng, tỷ trọng tự trôi) held = pm.portfolio_returns(returns_df, target_weights) # Chiến lược 2: Tái cân bằng hàng quý kèm chi phí thực tế Việt Nam quarterly = pm.portfolio_returns( returns_df, target_weights, rebalance="Q", **pm.VN_COSTS # Phí giao dịch 0.15% mỗi chiều + Thuế bán 0.1% ) # Chiến lược 3: Tái cân bằng theo dải hành lang (Corridor) khi tỷ trọng lệch quá 5% corridor = pm.portfolio_returns( returns_df, target_weights, rebalance="corridor", band=0.05, **pm.VN_COSTS ) ``` ### Cấu trúc chi phí pm.VN_COSTS `pm.VN_COSTS` là bộ tham số chi phí được định nghĩa sẵn theo thực tế thị trường chứng khoán Việt Nam: - Phí mua (`buy_cost`): `0.0015` (0,15% giá trị giao dịch). - Phí bán (`sell_cost`): `0.0025` (gồm 0,15% phí giao dịch + 0,1% thuế thu nhập cá nhân từ chuyển nhượng chứng khoán). ### Phân rã đóng góp lợi suất theo Cariño Hàm `pm.contribution()` áp dụng thuật toán liên kết chuỗi Cariño, phân rã chính xác lợi suất luỹ kế của toàn danh mục thành mức đóng góp của từng mã cổ phiếu: ```python # Phân rã đóng góp lợi suất luỹ kế contrib = pm.contribution(held.attrs["weights_bop"], returns_df) print(contrib.attrs["linked"]) # Tổng các giá trị đóng góp bằng đúng 100% lợi suất danh mục ``` ### Làm tròn số lượng cổ phiếu theo lô chẵn 100 Thị trường chứng khoán Việt Nam (HOSE, HNX) quy định giao dịch theo lô chuẩn 100 cổ phiếu. Hàm `pm.lot_round()` tự động quy đổi tỷ trọng lý thuyết thành số lượng cổ phiếu chẵn lô thực tế mà không vượt quá hạn mức vốn: ```python # Giá thị trường hiện tại của các mã current_prices = pd.Series([98500, 61200, 26350, 45600, 33100], index=names) total_capital = 200_000_000 # Vốn phân bổ 200 triệu đồng # Tính toán số lượng cổ phiếu thực tế chẵn lô 100 lots = pm.lot_round(target_weights, current_prices, capital=total_capital) print(lots[["shares", "value", "actual_weight"]]) ``` --- ## Đo lường và phân rã rủi ro danh mục Một cổ phiếu chiếm 20% vốn có thể gánh tới 50% tổng rủi ro của danh mục nếu có độ biến động cao và tương quan thuận chặt chẽ với các cổ phiếu còn lại. `vnstock_quant` cung cấp công cụ phân rã rủi ro thành phần: ```python # 1. Ước lượng ma trận hiệp phương sai quy đổi theo năm (hỗ trợ 'sample', 'ledoit_wolf', 'ewma') cov_matrix = pm.covariance(returns_df, periods=252, method="ledoit_wolf") # 2. Phân rã tỷ lệ đóng góp rủi ro của từng mã rc = pm.risk_contribution(target_weights, cov_matrix) print(rc[["weight", "marginal", "component", "percent"]]) print(f"Độ biến động toàn danh mục: {rc.attrs['volatility']:.4f}") # 3. Đánh giá mức độ tập trung danh mục conc = pm.concentration(target_weights) print(f"Hệ số HHI: {conc['hhi']:.4f}, Số cổ phiếu hiệu dụng: {conc['effective_n']:.2f}") # 4. Tính toán VaR tham số của danh mục với giá trị 1 tỷ đồng daily_cov = pm.covariance(returns_df) port_var = pm.parametric_var(target_weights, daily_cov, level=0.99, value=1e9) print(f"Mức lỗ tiềm tàng 99% trong 1 ngày: {port_var.attrs['amount']:,.0f} VNĐ") ``` --- ## Tối ưu hoá danh mục đầu tư Thư viện tích hợp các thuật toán tối ưu hóa danh mục hiện đại với ràng buộc mặc định không bán khống (tỷ trọng từ 0 đến 1, tổng bằng 1): ```python # 1. Danh mục phương sai tối thiểu (Minimum Variance Portfolio) w_min_var = pm.min_variance(cov_matrix) # 2. Danh mục tối đa hoá tỷ số Sharpe (Tangency Portfolio) w_max_sharpe = pm.max_sharpe(returns_df.mean() * 252, cov_matrix, rf=0.03) # 3. Dựng đường biên hiệu quả Markowitz (Efficient Frontier) frontier = pm.frontier(returns_df.mean() * 252, cov_matrix, points=20) # 4. Danh mục đóng góp rủi ro đồng đều (Risk Parity Portfolio) w_risk_parity = pm.risk_parity(cov_matrix) # 5. Tối ưu hoá Black-Litterman kết hợp quan điểm nhà đầu tư w_bl = pm.black_litterman(market_caps, cov_matrix, views=..., confidences=...) ``` --- ## Đọc tiếp - [Mô hình định giá](/docs/vnstock_quant/tinh-toan/valuation) — Định giá cổ phiếu bằng chiết khấu dòng cổ tức và P/E hợp lý. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino và thanh khoản Amihud. - [Kiểm định chất lượng & hiệu năng](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) — Báo cáo kiểm định chất lượng và hiệu năng tính toán. --- ## Document: Rủi ro và hiệu suất > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.risk` tính các thước đo như Sharpe, Sortino, Beta, VaR, mức sụt giảm từ đỉnh và độ kém thanh khoản Amihud. Một số hàm giúp bạn xem hiện tượng thường gặp ở dữ liệu Việt Nam, chẳng hạn phiên chạm trần hoặc sàn và cổ phiếu giao dịch thưa. Mỗi thước đo trả lời một câu hỏi khác nhau; hãy chọn theo dữ liệu và mục đích so sánh của bạn.

Toàn bộ mô-đun risk mở cho tài khoản từ cấp Bronze trở lên. Giới hạn 30 lượt dùng thử của bản Cộng đồng không áp dụng ở các cấp này; mỗi phép tính vẫn được ghi nhận vào quỹ hạn mức chung của tài khoản Vnstock.

--- ## Chuẩn bị dữ liệu đầu vào Phần lớn hàm nhận `pandas.Series` chứa **lợi suất từng kỳ**, với ngày giao dịch làm chỉ mục (`DatetimeIndex`). Bạn có thể tính chuỗi này từ giá đóng cửa đã điều chỉnh. Khi so sánh với chỉ số thị trường, hãy kiểm tra khoảng ngày của hai chuỗi; thư viện căn chúng theo các ngày giao dịch chung. ```python import pandas as pd from vnstock_quant import risk # Cách 1: Tính chuỗi lợi suất từ chuỗi giá đóng cửa đã điều chỉnh prices = pd.Series([50000, 50800, 49900, 51200, 52000], index=pd.to_datetime([...])) stock_returns = risk.returns(prices) # Cách 2: Tải trực tiếp dữ liệu cổ phiếu và chỉ số VNINDEX qua vnstock data = risk.from_vnstock("FPT", benchmark="VNINDEX", start="2022-01-01") r = data["returns"] # Chuỗi lợi suất FPT m = data["benchmark"] # Chuỗi lợi suất VNINDEX ``` --- ## Các nhóm thước đo rủi ro và hiệu suất Bạn có thể gọi từng hàm hoặc xem nhiều thước đo trong một bảng tổng hợp. ### 1. Lợi suất và biến động tổng thể - `annual_return(r)`: Lợi suất kép quy đổi theo năm (CAGR). - `annual_volatility(r)`: Độ biến động chuẩn hoá theo năm (Độ lệch chuẩn lợi suất nhân căn bậc hai số phiên giao dịch trong năm). - `sharpe_ratio(r, rf=0.03)`: Tỷ số Sharpe đo lường lợi suất vượt trội trên một đơn vị tổng rủi ro. - `skew(r)`: Độ lệch phân phối lợi suất. - `kurtosis(r)`: Độ nhọn phân phối (đo lường hiện tượng đuôi dày). ### 2. Rủi ro khi giá giảm - `downside_deviation(r, mar=0.05)`: Độ lệch chuẩn sụt giảm, chỉ tính các phiên có lợi suất thấp hơn ngưỡng tối thiểu chấp nhận (`mar`). - `sortino_ratio(r, mar=0.05)`: Tỷ số Sortino đo lợi nhuận vượt trội trên rủi ro chiều giảm (không phạt biến động tăng). - `max_drawdown(r)`: Mức sụt giảm tối đa từ đỉnh xuống đáy sâu nhất (trả về số âm). - `calmar_ratio(r)`: Lợi suất quy đổi theo năm chia cho mức sụt giảm tối đa tuyệt đối. - `ulcer_index(r)`: Chỉ số Ulcer đo lường cả độ sâu và thời gian chịu đựng sụt giảm giá. - `omega_ratio(r, mar=0.05)`: Tỷ lệ diện tích phân phối giữa phần lãi và phần lỗ so với ngưỡng mục tiêu. ### 3. Các khoản lỗ ít gặp nhưng lớn - `var(r, level=0.99, method="historical")`: VaR ước tính ngưỡng lỗ tại mức tin cậy 99% trong kỳ dữ liệu đang xét; khoản lỗ thực tế vẫn có thể vượt ngưỡng này. Hỗ trợ `"historical"` (lịch sử), `"normal"` (phân phối chuẩn) và `"cornish_fisher"` (hiệu chỉnh độ lệch và độ nhọn). - `cvar(r, level=0.99)`: Tổn thất kỳ vọng có điều kiện (Conditional VaR / Expected Shortfall) đo lường mức lỗ bình quân khi vượt qua ngưỡng VaR. ### 4. So sánh với chỉ số tham chiếu - `beta(r, m)`: Hệ số Beta đo lường độ nhạy của cổ phiếu so với biến động của chỉ số thị trường. - `dimson_beta(r, m)`: Beta hiệu chỉnh độ trễ Dimson, khắc phục hiện tượng méo mó Beta đối với các mã cổ phiếu thanh khoản thấp hoặc giao dịch thưa. - `down_beta(r, m)` / `up_beta(r, m)`: Hệ số Beta bất đối xứng, đo độ nhạy riêng biệt trong những phiên thị trường giảm giá và tăng giá. - `alpha(r, m, rf=0.03)`: Lợi nhuận vượt trội Alpha Jensen theo mô hình CAPM. - `information_ratio(r, m)`: Tỷ số thông tin đo lường năng lực tạo lợi nhuận chủ động trên độ rủi ro theo dõi (Tracking Error). - `treynor_ratio(r, m, rf=0.03)`: Tỷ số Treynor đo lợi suất vượt trội trên một đơn vị rủi ro hệ thống Beta. - `m2(r, m, rf=0.03)`: Thước đo Modigliani-Modigliani (M²), quy đổi tỷ số Sharpe về cùng mức biến động của thị trường. ### 5. Thước đo đặc thù thị trường chứng khoán Việt Nam - `amihud(r, volume_value)`: Hệ số đo độ kém thanh khoản Amihud (tỷ lệ phần trăm biến động giá trên 1 tỷ đồng giá trị khớp lệnh). - `zero_return_ratio(r)`: Tỷ lệ phần trăm số phiên giao dịch không có biến động giá (đứng giá hoặc mất thanh khoản). - `limit_hit_ratio(r)`: Tỷ lệ phiên chạm trần hoặc sàn (biên độ ±7% HOSE). --- ## Bảng tóm tắt rủi ro Để xem nhiều thước đo trong cùng một bảng, gọi `risk.summary()`: ```python # Tạo bảng tóm tắt toàn bộ 33 chỉ số rủi ro summary_table = risk.summary(r, m, rf=0.03) # Hiển thị các chỉ số cốt lõi core_metrics = ["annual_return", "annual_volatility", "sharpe_ratio", "sortino_ratio", "max_drawdown", "beta", "var"] print(summary_table[core_metrics]) ``` --- ## Thước đo độ kém thanh khoản Amihud Thanh khoản là yếu tố quan trọng khi phân tích danh mục quy mô vốn lớn trên thị trường Việt Nam. Hệ số Amihud đo lường mức độ tác động của giá khi khớp một lượng tiền nhất định: ```python # Chuỗi giá trị giao dịch tính bằng Đồng (VNĐ) volume_value = pd.Series([25e9, 40e9, 15e9, ...], index=r.index) # Tính hệ số Amihud toàn giai đoạn illiquidity = risk.amihud(r, volume_value) print(f"Amihud Ratio: {illiquidity:.6f} (% biến động trên 1 tỷ VNĐ)") # Tính hệ số Amihud dạng trượt 60 phiên (Rolling window) rolling_amihud = risk.amihud(r, volume_value, window=60) ``` --- ## Lưu ý phương pháp luận trên dữ liệu Việt Nam Khi phân tích dữ liệu thị trường chứng khoán Việt Nam, người dùng cần lưu ý các hiện tượng cấu trúc sau: 1. **Biên độ giá trần/sàn bóp méo VaR một ngày**: Do biên độ HOSE bị chặn ở ±7%, giá trị VaR 99% theo ngày của các cổ phiếu biến động mạnh thường bị chặn cứng ở mức sát 7%, che giấu rủi ro thực. Vì vậy, bạn nên chuyển sang tần suất tuần (`frequency="W"`) và kết hợp với `max_drawdown`. 2. **Hiện tượng đuôi dày (Fat Tails)**: Phân phối lợi suất thực tế tại Việt Nam có độ nhọn (`kurtosis`) rất cao. VaR theo phân phối chuẩn sẽ đánh giá thấp các cú sụt giảm mạnh. Bạn nên ưu tiên sử dụng `method="historical"`. 3. **Cổ phiếu giao dịch thưa làm giảm Beta**: Những mã thanh khoản yếu có tỷ lệ `zero_return_ratio` cao (trên 15%) sẽ làm hệ số Beta OLS thông thường bị lệch giảm giả tạo. Hãy so sánh Beta OLS với `dimson_beta` hoặc tính toán theo tần suất tuần. --- ## Đọc tiếp - [Quản lý danh mục đầu tư](/docs/vnstock_quant/tinh-toan/portfolio) — Đo lường TWR/MWR, phân bổ rủi ro và tối ưu hoá danh mục. - [Mô hình định giá](/docs/vnstock_quant/tinh-toan/valuation) — Định giá chiết khấu cổ tức và xác định P/E hợp lý. - [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta) — Sử dụng 58 chỉ báo kỹ thuật với tốc độ cao. --- ## Document: Chỉ báo kỹ thuật ## Tổng quan `vnstock_quant.ta` gồm 58 chỉ báo kỹ thuật, từ đường trung bình động và RSI đến chỉ báo biến động và khối lượng. Nếu đã dùng `vnstock_ta` 1.x, bạn có thể giữ cách gọi của lớp `Indicator`. Một số kết quả số sẽ khác bản cũ do thay đổi công thức hoặc cách khởi tạo; xem [trang chuyển đổi](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta) để biết chỉ báo nào bị ảnh hưởng. *** ## Chuẩn bị dữ liệu đầu vào Dữ liệu đầu vào là `pandas.DataFrame` có cột giá và, với một số chỉ báo, cột khối lượng: * **Index**: Nên đặt `DatetimeIndex` (cột thời gian `time`). * **Cột giá bắt buộc**: `open`, `high`, `low`, `close` (kiểu số thực `float64`), `volume` (kiểu số nguyên `int64` hoặc `float64`). * Đối với các chỉ báo chỉ dựa trên giá đóng cửa (ví dụ SMA, RSI), DataFrame chỉ cần tối thiểu cột `close`. ```python import pandas as pd from vnstock import Market # Lấy 365 phiên giao dịch gần nhất của cổ phiếu FPT m = Market() df = m.equity("FPT").ohlcv(length=365, interval="1D") df = df.set_index("time") ```

Chỉ báo có chu kỳ 50 hoặc 200 phiên sẽ trả NaN ở đầu chuỗi cho đến khi có đủ dữ liệu để tính. Hãy kiểm tra số phiên đầu vào trước khi dùng kết quả.

*** ## Hai cách gọi chỉ báo kỹ thuật ### Cách 1: Dùng lớp Indicator Với `Indicator`, bạn có thể gọi hàm theo nhóm chỉ báo hoặc gọi trực tiếp tên hàm: ```python from vnstock_quant import Indicator # Khởi tạo đối tượng với dữ liệu nến ta = Indicator(df) # Phong cách 1: Gọi thông qua nhóm danh mục (Phân cấp logic trực quan) sma_20 = ta.trend.sma(length=20) rsi_14 = ta.momentum.rsi(length=14) bbands = ta.volatility.bbands(length=14, std=2.0) obv = ta.volume.obv() pivots = ta.statistics.pivots() # Phong cách 2: Gọi phẳng trực tiếp (giữ cú pháp gọi của vnstock_ta 1.x) macd = ta.macd(fast=12, slow=26, signal=9) st = ta.supertrend(period=10, multiplier=3.0) ``` Kết quả trả về là một `pandas.Series` (đối với chỉ báo đơn đường như SMA, RSI) hoặc một `pandas.DataFrame` (đối với chỉ báo đa đường như MACD, Bollinger Bands, Supertrend) giữ nguyên chỉ mục thời gian của DataFrame gốc. ### Cách 2: Gọi theo tên hàm thông qua compute() Dùng `compute()` khi tên chỉ báo nằm trong tệp cấu hình hoặc được chọn lúc chương trình chạy: ```python from vnstock_quant import compute # Tính RSI theo tên rsi_series = compute(df, "rsi", length=14) # Tính MACD theo tên với bộ tham số tuỳ chỉnh macd_df = compute(df, "macd", fast=12, slow=26, signal=9) ``` *** ## Danh mục 58 chỉ báo theo năm nhóm Các chỉ báo được chia thành năm nhóm: ### 1. Xu hướng (Trend Indicators - 14 chỉ báo) Nhận diện hướng đi chủ đạo của thị trường (tăng giá, giảm giá hoặc tích luỹ đi ngang): | Ký hiệu | Tên đầy đủ | Mô tả | | :----------- | :----------------------------- | :------------------------------------------------------- | | `sma` | Simple Moving Average | Đường trung bình động giản đơn | | `ema` | Exponential Moving Average | Đường trung bình động luỹ thừa | | `wma` | Weighted Moving Average | Đường trung bình động có trọng số | | `hma` | Hull Moving Average | Đường trung bình động Hull giúp giảm độ trễ | | `smma` | Smoothed Moving Average | Đường trung bình động làm mượt | | `alma` | Arnaud Legoux Moving Average | Đường trung bình động Arnaud Legoux dùng phân phối Gauss | | `vwma` | Volume-Weighted Moving Average | Đường trung bình động theo khối lượng | | `adx` | Average Directional Index | Chỉ số định hướng trung bình xác định cường độ xu hướng | | `ichimoku` | Ichimoku Kinko Hyo | Hệ thống đám mây Ichimoku | | `psar` | Parabolic SAR | Chỉ báo điểm dừng và đảo chiều xu hướng | | `supertrend` | Supertrend | Chỉ báo bám sát xu hướng dựa trên độ biến động ATR | | `dm` | Directional Movement | Hệ thống chuyển động định hướng (+DI, -DI) | | `linreg` | Linear Regression | Hồi quy tuyến tính của chuỗi giá | | `aroon` | Aroon Indicator | Đo lường thời gian kể từ đỉnh/đáy gần nhất | ### 2. Động lượng (Momentum Indicators - 15 chỉ báo) Đo lường vận tốc biến động giá và xác định các vùng quá mua (overbought) hoặc quá bán (oversold): | Ký hiệu | Tên đầy đủ | Mô tả | | :--------- | :------------------------------------ | :----------------------------------------------------------- | | `rsi` | Relative Strength Index | Chỉ số sức mạnh tương đối (Wilder RSI) | | `stoch` | Stochastic Oscillator | Dao động ngẫu nhiên đo vị trí giá so với biên độ đỉnh-đáy | | `stochrsi` | Stochastic RSI | Áp dụng công thức Stochastic trên chuỗi giá trị RSI | | `mom` | Momentum | Đo khoảng cách giá hiện tại so với n phiên trước | | `roc` | Rate of Change | Tốc độ thay đổi giá theo tỷ lệ phần trăm | | `ao` | Awesome Oscillator | Dao động Awesome của Bill Williams, đo động lượng thị trường | | `cci` | Commodity Channel Index | Chỉ số kênh hàng hoá đo độ lệch so với trung bình | | `willr` | Williams %R | Chỉ báo phản ánh vị thế tương đối của giá đóng cửa | | `tsi` | True Strength Index | Chỉ số sức mạnh thực sự với 2 tầng làm mượt EMA | | `cmo` | Chande Momentum Oscillator | Dao động động lượng Chande | | `uo` | Ultimate Oscillator | Dao động tối thượng kết hợp 3 khung thời gian | | `fisher` | Fisher Transform | Chuyển đổi phân phối giá về phân phối chuẩn Gauss | | `cg` | Center of Gravity | Chỉ báo trọng tâm của chuỗi giá | | `kst` | Know Sure Thing | Dao động KST tổng hợp 4 chu kỳ ROC | | `macd` | Moving Average Convergence Divergence | Đường trung bình động hội tụ phân kỳ | ### 3. Biến động (Volatility Indicators - 10 chỉ báo) Đo lường mức độ co giãn biên độ giá và nhận diện giai đoạn nén biên độ: | Ký hiệu | Tên đầy đủ | Mô tả | | :------------ | :----------------- | :--------------------------------------------------------------- | | `bbands` | Bollinger Bands | Dải biến động trên/dưới quanh đường trung bình | | `kc` | Keltner Channels | Kênh Keltner dựa trên đường trung bình và ATR | | `atr` | Average True Range | Khoảng biến động thực tế trung bình | | `stdev` | Standard Deviation | Độ lệch chuẩn thống kê của chuỗi giá | | `donchian` | Donchian Channels | Kênh giá đỉnh cao nhất và đáy thấp nhất | | `massi` | Mass Index | Chỉ số khối lượng nhận diện vùng đảo chiều nén biên độ | | `ui` | Ulcer Index | Đo lường độ sâu và thời gian sụt giảm giá | | `squeeze` | TTM Squeeze | Phát hiện trạng thái tích luỹ nén chặt giữa Bollinger và Keltner | | `squeeze_pro` | Squeeze Pro | Bản nâng cấp đo 3 mức độ nén giá (chặt, vừa, lỏng) | | `true_range` | True Range | Biên độ thực tế của từng phiên giao dịch | ### 4. Khối lượng (Volume Indicators - 10 chỉ báo) Kết hợp tương quan giữa biến động giá và thanh khoản giao dịch: | Ký hiệu | Tên đầy đủ | Mô tả | | :------ | :---------------------------- | :---------------------------------------------------------- | | `obv` | On-Balance Volume | Khối lượng cân bằng tích luỹ | | `cmf` | Chaikin Money Flow | Dòng tiền Chaikin đo áp lực mua/bán trong kỳ | | `ad` | Accumulation/Distribution | Đường tích luỹ/phân phối khối lượng | | `vp` | Volume Profile | Phân bổ khối lượng giao dịch theo các vùng giá | | `vwap` | Volume-Weighted Average Price | Giá bình quân gia quyền theo khối lượng trong phiên | | `pvo` | Percentage Volume Oscillator | Dao động tỷ lệ phần trăm khối lượng giữa hai đường EMA | | `efi` | Elder's Force Index | Chỉ số lực giao dịch của Elder | | `eom` | Ease of Movement | Mức độ dễ dàng dịch chuyển của giá theo khối lượng | | `nvi` | Negative Volume Index | Chỉ số khối lượng âm phản ánh hành vi dòng tiền thông minh | | `mfi` | Money Flow Index | Chỉ số dòng tiền kết hợp giá và khối lượng (RSI khối lượng) | ### 5. Thống kê (Statistics Indicators - 9 chỉ báo) Các giá trị thống kê hình học và điểm xoay trục quan trọng: | Ký hiệu | Tên đầy đủ | Mô tả | | :----------- | :---------------------- | :------------------------------------------------------------ | | `pivots` | Pivot Points | Điểm xoay trục và các mức hỗ trợ/kháng cự kinh điển | | `mad` | Mean Absolute Deviation | Độ lệch tuyệt đối trung bình | | `variance` | Variance | Phương sai thống kê của chuỗi giá | | `hl2` | High-Low Median Price | Giá trung vị giữa đỉnh và đáy `(high + low) / 2` | | `hlc3` | Typical Price | Giá điển hình `(high + low + close) / 3` | | `ohlc4` | Average Price | Giá trung bình phiên `(open + high + low + close) / 4` | | `midprice` | Midprice | Giá trung vị giữa đỉnh cao nhất và đáy thấp nhất trong chu kỳ | | `decreasing` | Decreasing Indicator | Chuỗi logic đánh dấu các phiên giá giảm liên tiếp | | `increasing` | Increasing Indicator | Chuỗi logic đánh dấu các phiên giá tăng liên tiếp | *** ## Khám phá danh mục và mức tin cậy Bạn có thể tra cứu danh mục, tham số mặc định và chuẩn đối chiếu của mọi chỉ báo bằng hàm `ta.catalog()`: ```python from vnstock_quant.ta import catalog cat = catalog() print(cat[["name", "group", "standard", "confidence", "access"]].head(10)) ``` Các mức tin cậy (`confidence`) được thẩm định khoa học: * **Mức A**: Khớp hoàn toàn với thư viện C nguyên bản **TA-Lib C 0.8.1** tới sai số dấu phẩy động (34 chỉ báo). * **Mức B**: Khớp trong sai số cho phép với bộ kiểm thử độc lập của **QuantConnect LEAN** hoặc **TradingView Pine Script v6** (Ichimoku, Supertrend, ADX...). * **Mức C**: Kiểm định theo công thức gốc trong bài báo học thuật của tác giả phát minh. *** ## Tải dữ liệu nhanh bằng from_vnstock Nếu đã cài đặt tiện ích `vnstock`, bạn có thể lấy dữ liệu và khởi tạo `Indicator` trong một câu lệnh: ```python from vnstock_quant.ta import from_vnstock # Tải dữ liệu và khởi tạo đối tượng Indicator tự động ta = from_vnstock("HPG", start="2024-01-01", end="2024-12-31") # Bắt đầu tính toán ngay lập tức rsi = ta.rsi(length=14) macd = ta.macd() ``` *** ## Vẽ đồ thị kỹ thuật với vnstock_chart Sau khi tính chỉ báo kỹ thuật, bạn có thể đưa kết quả vào `vnstock_chart`, thư viện vẽ biểu đồ của thế hệ 5, để có biểu đồ nến kèm chỉ báo: ```python from vnstock import Market from vnstock_quant import Indicator from vnstock_chart import Chart df = Market().equity("FPT").ohlcv(length=365, interval="1D").set_index("time") ta = Indicator(df) bb = ta.bbands(length=20, std=2.0) rsi = ta.rsi(length=14) # Bollinger Bands chồng lên khung giá, RSI ở khung riêng bên dưới fig, axes = Chart.candle( df, title="FPT — Bollinger Bands và RSI(14)", volume=False, overlays=[ {"data": bb["BBU_20_2.0"], "color": "#2EA8F0"}, {"data": bb["BBM_20_2.0"], "color": "#FFB31A"}, {"data": bb["BBL_20_2.0"], "color": "#2EA8F0"}, ], subplots=[{"data": rsi, "color": "#8C52FF", "ylabel": "RSI"}], ) fig.savefig("fpt_bbands_rsi.png", dpi=150, bbox_inches="tight") ``` Cài `vnstock_chart` bằng `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart`. Xem thêm các kiểu biểu đồ và cách đặt nhiều chỉ báo trên cùng một hình ở [tài liệu vnstock_chart](/docs/vnstock-chart/ket-hop-voi-gen5). *** ## Đọc tiếp * [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) — Khám phá 100 chỉ số tài chính BCTC VAS và mô hình dòng tiền CFA. * [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino, VaR và thanh khoản Amihud. * [Chuyển đổi từ vnstock_ta](/docs/vnstock_quant/chuyen-doi/tu-vnstock-ta) — Chi tiết 16 chỉ báo đã sửa lỗi so với vnstock_ta 1.x. * [Kiểm định chất lượng & hiệu năng](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) — Báo cáo chi tiết sai số 58 chỉ báo so với TA-Lib C và kiểm định hiệu năng. --- ## Document: Định giá > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## Tổng quan `vnstock_quant.valuation` gồm các hàm tính theo mô hình chiết khấu cổ tức (DDM), suy ra giả định tăng trưởng hoặc lợi suất từ thị giá, và tính P/E theo các giả định bạn đặt. Kết quả thay đổi khi cổ tức, tốc độ tăng trưởng hoặc lợi suất yêu cầu thay đổi; vì vậy nên xem nhiều kịch bản thay vì một con số duy nhất.

Mọi kết quả định giá là đầu ra toán học của mô hình dựa trên các giả định đầu vào (lợi suất yêu cầu, tốc độ tăng trưởng, tỷ lệ chi trả) do người dùng thiết lập. Đây không phải là giá mục tiêu hay khuyến nghị đầu tư của Vnstock.

--- ## Mô hình chiết khấu cổ tức (DDM) DDM dùng dòng cổ tức dự kiến để tính giá trị theo mô hình. Trước khi áp dụng, hãy xem doanh nghiệp có lịch sử chi trả cổ tức tiền mặt đủ để bạn xây dựng giả định hay không. ```python from vnstock_quant import valuation as vl # Trường hợp 1: Mô hình tăng trưởng đều Gordon (Gordon Growth Model) # Cổ tức vừa chi trả d0 = 3.700 VNĐ, kỳ vọng tăng trưởng dài hạn g = 5,4%/năm, lợi suất yêu cầu r = 7,5% gordon_val = vl.ddm(r=0.075, d0=3700, terminal_g=0.054) print(f"Giá trị nội tại: {gordon_val['value']:,.0f} VNĐ") # Trường hợp 2: Mô hình DDM hai giai đoạn (Two-stage DDM) # Doanh nghiệp tăng trưởng cao 10%/năm trong 3 năm đầu, sau đó ổn định ở mức 5% multi_stage = vl.ddm( r=0.15, d0=5000, stages=[(0.10, 3)], # [(tốc độ tăng trưởng, số năm)] terminal_g=0.05 ) print(multi_stage[["value", "pv_dividends", "pv_terminal", "terminal_share"]]) # Trường hợp 3: Khai báo dòng cổ tức dự phóng chi tiết (Explicit Dividends) # 4 năm đầu tái đầu tư toàn bộ (cổ tức = 0), từ năm thứ 5 bắt đầu trả 4.000 VNĐ rồi tăng trưởng 6% explicit_val = vl.ddm(r=0.10, dividends=[0, 0, 0, 0, 4000], terminal_g=0.06) print(f"Giá trị nội tại: {explicit_val['value']:,.0f} VNĐ") ``` ### Tham số chi tiết của hàm ddm() | Tham số | Kiểu dữ liệu | Ý nghĩa | | :--- | :--- | :--- | | `r` | `float` | Lợi suất yêu cầu của nhà đầu tư (tính theo năm, dạng phân số). Bắt buộc phải lớn hơn `terminal_g` | | `terminal_g` | `float` | Tốc độ tăng trưởng dài hạn sau khi kết thúc giai đoạn tăng trưởng nhanh | | `d0` / `d1` | `float` | Mức cổ tức tiền mặt vừa chi trả gần nhất (`d0`) hoặc cổ tức dự kiến kỳ tới (`d1`) | | `stages` | `list[tuple]` | Danh sách các giai đoạn tăng trưởng: `[(g1, số_năm1), (g2, số_năm2)]` | | `dividends` | `list[float]` | Danh sách dự phóng cổ tức chi tiết từng năm `[D1, D2, ..., Dn]` |

terminal_share cho biết phần giá trị mô hình đến từ giai đoạn sau thời kỳ dự phóng chi tiết. Nếu phần này lớn, hãy thử nhiều giá trị r và g để xem kết quả thay đổi ra sao.

--- ## Định giá đảo ngược (Reverse Valuation) Với định giá đảo ngược, bạn bắt đầu từ thị giá và một số giả định khác để tính tốc độ tăng trưởng hoặc lợi suất yêu cầu mà mô hình hàm ý. Đây là cách kiểm tra mức độ nhạy của kết quả với những giả định đó. ```python # Cổ phiếu đang giao dịch ở mức giá 63.000 VNĐ, cổ tức năm tới dự kiến 1.760 VNĐ current_price = 63000 expected_d1 = 1760 # 1. Tính tốc độ tăng trưởng ngầm định khi biết lợi suất yêu cầu là 7% implied_g = vl.implied_growth(price=current_price, d1=expected_d1, r=0.07) print(f"Tăng trưởng dài hạn ngầm định: {implied_g * 100:.2f}%/năm") # 2. Tính lợi suất yêu cầu ngầm định khi giả định tốc độ tăng trưởng dài hạn là 4% implied_r = vl.implied_return(price=current_price, d1=expected_d1, g=0.04) print(f"Lợi suất yêu cầu ngầm định: {implied_r * 100:.2f}%/năm") ``` Nếu `implied_g` cao hơn nhiều so với mức tăng trưởng bạn cho là có cơ sở, hãy xem lại dữ liệu và giả định đầu vào trước khi diễn giải kết quả. --- ## Xác định tỷ số P/E hợp lý theo cơ bản (Justified P/E) `vl.justified_pe()` tính P/E theo tỷ lệ chi trả cổ tức (`payout`), lợi suất yêu cầu (`r`) và tốc độ tăng trưởng (`g`). Đây là kết quả của mô hình với các giả định bạn chọn: ```python # Doanh nghiệp chi trả cổ tức 68% lợi nhuận, lợi suất yêu cầu 9%, tăng trưởng 6,9% payout_ratio = 0.68 cost_of_equity = 0.09 growth_rate = 0.069 # 1. P/E dự phóng hợp lý (Forward Justified P/E = payout / (r − g)) pe_forward = vl.justified_pe(payout=payout_ratio, r=cost_of_equity, g=growth_rate) print(f"P/E Forward hợp lý: {pe_forward:.2f}x") # 2. P/E trượt hợp lý (Trailing Justified P/E = payout * (1 + g) / (r − g)) pe_trailing = vl.justified_pe(payout=payout_ratio, r=cost_of_equity, g=growth_rate, kind="trailing") print(f"P/E Trailing hợp lý: {pe_trailing:.2f}x") # 3. Suy ra lợi suất yêu cầu ngầm định từ P/E thị trường đang ở mức 28x implied_cost = vl.pe_implied(pe=28, payout=0.70, g=0.04) print(f"Lợi suất yêu cầu ngầm định từ P/E: {implied_cost * 100:.2f}%") ``` --- ## Đối chiếu công thức Các công thức trong mô-đun `valuation` được đối chiếu với bài toán mẫu của **CFA Program Level I (Equity Investments & Quantitative Methods)**. Xem [phần kiểm định](/docs/vnstock_quant/tham-khao/doi-chieu-ket-qua-va-toc-do) để biết phạm vi đối chiếu. --- ## Đọc tiếp - [Chỉ số tài chính](/docs/vnstock_quant/tinh-toan/fa) — Phân tích dòng tiền tự do FCFF/FCFE. - [Quản lý danh mục đầu tư](/docs/vnstock_quant/tinh-toan/portfolio) — Tối ưu hoá phân bổ tài sản. - [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk) — Đo lường Sharpe, Sortino và Amihud. --- ## Document: Bắt đầu với vnstock_ta 1.x

Các lệnh dưới đây dành cho vnstock_ta 1.x. Nếu bạn dùng vnstock_quant, xem tài liệu hiện hành.

## Cài đặt Nếu bạn đang duy trì môi trường dùng `vnstock_ta` 1.x, xem hướng dẫn cài đặt dành cho phiên bản đó:
Hướng dẫn cài đặt Vnstock
## 1. Chuẩn bị dữ liệu Chuẩn bị dữ liệu giá dạng `pandas.DataFrame`, rồi đặt cột thời gian làm chỉ mục: ```python from vnstock_data import Market # Khởi tạo đối tượng Market m = Market() # Lấy dữ liệu 365 phiên giao dịch gần nhất của VCB df = m.equity("VCB").ohlcv(length=365, interval="1D") df = df.set_index('time') ``` ## 2. Khởi tạo đối tượng Indicator và tính toán chỉ báo Truyền bảng dữ liệu vào `Indicator`. Bạn có thể gọi hàm theo nhóm hoặc gọi trực tiếp tên chỉ báo: ```python from vnstock_ta import Indicator # Khởi tạo class Indicator ta = Indicator(data=df) # Cách 1: Gọi thông qua thuộc tính danh mục tương ứng (Khuyên dùng) sma_20 = ta.trend.sma(length=20) rsi_14 = ta.momentum.rsi(length=14) atr_14 = ta.volatility.atr(length=14) obv = ta.volume.obv() hlc3 = ta.statistics.hlc3() # Cách 2: Gọi trực tiếp (Khả năng tương thích ngược) macd = ta.macd(fast=12, slow=26, signal=9) ``` Kết quả trả về của các chỉ báo thường là một đối tượng `pandas.Series` (ví dụ như `sma`, `rsi`, `atr`) hoặc một đối tượng `pandas.DataFrame` đối với các chỉ báo có nhiều đường giá trị đầu ra (ví dụ như `macd`, `bbands`, `supertrend`). ## 3. Vẽ đồ thị trực quan hóa Để vẽ kết quả tính toán của phiên bản cũ, xem [Hướng dẫn vẽ biểu đồ](/docs/vnstock_quant/vnstock-ta/ve-bieu-do). Với thế hệ 5, xem [`vnstock_chart`](/docs/vnstock-chart). --- ## Document: Danh sách chỉ báo kỹ thuật Trang này liệt kê các chỉ báo trong `vnstock_ta` 1.x theo năm nhóm: xu hướng, động lượng, biến động, khối lượng và thống kê. Nếu bạn dùng `vnstock_quant`, xem [danh mục chỉ báo hiện hành](/docs/vnstock_quant/tinh-toan/ta). ## Cách gọi chỉ báo Tất cả các chỉ báo đều được truy cập thông qua lớp `Indicator`: ```python from vnstock_ta import Indicator # Khởi tạo với DataFrame (yêu cầu các cột: open, high, low, close, volume) ta = Indicator(data=df) ``` Bạn có thể gọi chỉ báo qua thuộc tính danh mục tương ứng: - `ta.trend.[method]()` - `ta.momentum.[method]()` - `ta.volatility.[method]()` - `ta.volume.[method]()` - `ta.statistics.[method]()` --- ## Chỉ báo xu hướng - Trend Indicators ### sma - Simple Moving Average **Mô tả**: Tính toán chỉ báo Simple Moving Average (Đường trung bình động đơn giản). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.sma(length=14) ``` --- ### ema - Exponential Moving Average **Mô tả**: Tính toán chỉ báo Exponential Moving Average (Đường trung bình động lũy thừa). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.ema(length=14) ``` --- ### wma - Weighted Moving Average **Mô tả**: Tính toán chỉ báo Weighted Moving Average (Đường trung bình động có trọng số). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.wma(length=10) ``` --- ### hma - Hull Moving Average **Mô tả**: Tính toán chỉ báo Hull Moving Average (Đường trung bình động Hull). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.hma(length=10) ``` --- ### smma - Smoothed Moving Average **Mô tả**: Tính toán chỉ báo Smoothed Moving Average (Đường trung bình động làm mượt). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.smma(length=7) ``` --- ### alma - Arnaud Legoux Moving Average **Mô tả**: Tính toán chỉ báo Arnaud Legoux Moving Average (Đường trung bình động Arnaud Legoux). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.alma(length=10, sigma=6.0, offset=0.85) ``` --- ### vwma - Volume-Weighted Moving Average **Mô tả**: Tính toán chỉ báo Volume-Weighted Moving Average (Đường trung bình động theo khối lượng). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.vwma(length=20) ``` --- ### adx - Average Directional Index **Mô tả**: Tính toán chỉ báo Average Directional Index (Chỉ số định hướng trung bình). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.adx(length=14) ``` --- ### ichimoku - Ichimoku Cloud **Mô tả**: Tính toán hệ thống chỉ báo Ichimoku Cloud. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.ichimoku(tenkan=9, kijun=26, senkou=52) ``` --- ### psar - Parabolic SAR **Mô tả**: Tính toán chỉ báo Parabolic SAR (Stop and Reverse). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.psar(af0=0.02, af=0.02, max_af=0.2) ``` --- ### supertrend - Supertrend **Mô tả**: Tính toán chỉ báo Supertrend để xác định xu hướng và các mức trailing stop loss. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.supertrend(length=10, multiplier=3.0) ``` --- ### dm - Directional Movement **Mô tả**: Tính toán chỉ báo chuyển động định hướng Directional Movement. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.dm(length=14) ``` --- ### linreg - Linear Regression **Mô tả**: Tính toán chỉ báo Hồi quy tuyến tính Linear Regression. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.linreg(length=14) ``` --- ### aroon - Aroon Indicator **Mô tả**: Tính toán chỉ báo xu hướng Aroon. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.trend.aroon(length=14) ``` --- ## Chỉ báo động lượng - Momentum Indicators ### rsi - Relative Strength Index **Mô tả**: Tính toán chỉ số sức mạnh tương đối Relative Strength Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.rsi(length=14) ``` --- ### stoch - Stochastic Oscillator **Mô tả**: Tính toán chỉ báo dao động ngẫu nhiên Stochastic Oscillator. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.stoch(k=14, d=3, smooth_k=3) ``` --- ### stochrsi - Stochastic RSI **Mô tả**: Tính toán chỉ báo Stochastic RSI. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.stochrsi(length=14, rsi_length=14, k=3, d=3) ``` --- ### roc - Rate of Change **Mô tả**: Tính toán tỷ lệ thay đổi giá Rate of Change. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.roc(length=9) ``` --- ### ao - Awesome Oscillator **Mô tả**: Tính toán chỉ báo dao động Awesome Oscillator. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.ao(fast=5, slow=34) ``` --- ### cci - Commodity Channel Index **Mô tả**: Tính toán chỉ số kênh hàng hóa Commodity Channel Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.cci(length=14, c=0.015) ``` --- ### willr - Williams %R **Mô tả**: Tính toán chỉ báo kỹ thuật Williams %R. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.willr(length=14) ``` --- ### tsi - True Strength Index **Mô tả**: Tính toán chỉ số sức mạnh thực sự True Strength Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.tsi(fast=13, slow=25, signal=13) ``` --- ### cmo - Chande Momentum Oscillator **Mô tả**: Tính toán chỉ báo dao động động lượng Chande Momentum Oscillator. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.cmo(length=9) ``` --- ### uo - Ultimate Oscillator **Mô tả**: Tính toán chỉ báo dao động tối thượng Ultimate Oscillator. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.uo(fast=7, medium=14, slow=28) ``` --- ### fisher - Fisher Transform **Mô tả**: Tính toán chỉ báo Phép biến đổi Fisher. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.fisher(length=9, signal=1) ``` --- ### cg - Center of Gravity **Mô tả**: Tính toán chỉ báo trọng tâm Center of Gravity. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.cg(length=10) ``` --- ### kst - Know Sure Thing **Mô tả**: Tính toán chỉ báo động lượng Know Sure Thing. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.kst(roc1=10, roc2=15, roc3=20, roc4=30) ``` --- ### macd - Moving Average Convergence Divergence **Mô tả**: Tính toán đường trung bình động hội tụ phân kỳ Moving Average Convergence Divergence. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.momentum.macd(fast=12, slow=26, signal=9) ``` --- ## Chỉ báo biến động - Volatility Indicators ### bbands - Bollinger Bands **Mô tả**: Tính toán chỉ báo dải Bollinger Bands. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.bbands(length=14, std=2.0) ``` --- ### kc - Keltner Channels **Mô tả**: Tính toán chỉ báo kênh Keltner Channels. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.kc(length=20, scalar=2.0) ``` --- ### atr - Average True Range **Mô tả**: Tính toán khoảng dao động thực tế trung bình Average True Range. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.atr(length=14) ``` --- ### stdev - Standard Deviation **Mô tả**: Tính toán độ lệch chuẩn Standard Deviation. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.stdev(length=14) ``` --- ### donchian - Donchian Channels **Mô tả**: Tính toán chỉ báo kênh Donchian Channels. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.donchian(lower_length=20, upper_length=20) ``` --- ### massi - Mass Index **Mô tả**: Tính toán chỉ số Mass Index để dự đoán đảo chiều. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.massi(fast=9, slow=25) ``` --- ### ui - Ulcer Index **Mô tả**: Tính toán chỉ số giảm thiểu rủi ro Ulcer Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.ui(length=14) ``` --- ### squeeze - Squeeze Momentum **Mô tả**: Tính toán chỉ báo bóp nghẹt động lượng Squeeze Momentum (kết hợp Bollinger Bands và Keltner Channels). **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.squeeze(bb_length=20, bb_std=2.0, kc_length=20, kc_scalar=1.5) ``` --- ### squeeze_pro - Squeeze Momentum Pro **Mô tả**: Tính toán chỉ báo bóp nghẹt động lượng nâng cao Squeeze Momentum Pro. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.squeeze_pro(bb_length=20, bb_std=2.0, kc_length=20) ``` --- ### true_range - True Range **Mô tả**: Tính toán khoảng dao động thực tế True Range. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volatility.true_range() ``` --- ## Chỉ báo khối lượng - Volume Indicators ### obv - On-Balance Volume **Mô tả**: Tính toán chỉ báo khối lượng cân bằng On-Balance Volume. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.obv() ``` --- ### cmf - Chaikin Money Flow **Mô tả**: Tính toán chỉ báo dòng tiền Chaikin Money Flow. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.cmf(length=20) ``` --- ### ad - Accumulation/Distribution **Mô tả**: Tính toán đường tích lũy/phân phối Accumulation/Distribution. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.ad() ``` --- ### vp - Volume Profile **Mô tả**: Tính toán chỉ báo hồ sơ khối lượng Volume Profile. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.vp(width=10) ``` --- ### vwap - Volume Weighted Average Price **Mô tả**: Tính toán giá trung bình gia quyền theo khối lượng Volume Weighted Average Price. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.vwap(anchor="D") ``` --- ### pvo - Percentage Volume Oscillator **Mô tả**: Tính toán chỉ báo dao động phần trăm khối lượng Percentage Volume Oscillator. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.pvo(fast=12, slow=26, signal=9) ``` --- ### efi - Force Index **Mô tả**: Tính toán chỉ báo lực Force Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.efi(length=13) ``` --- ### eom - Ease of Movement **Mô tả**: Tính toán chỉ báo di chuyển dễ dàng Ease of Movement. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.eom(length=14, divisor=100000000) ``` --- ### nvi - Negative Volume Index **Mô tả**: Tính toán chỉ số khối lượng tiêu cực Negative Volume Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.nvi(length=1) ``` --- ### mfi - Money Flow Index **Mô tả**: Tính toán chỉ số dòng tiền Money Flow Index. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.volume.mfi(length=14) ``` --- ## Chỉ báo thống kê và cấu trúc - Statistics Indicators ### pivots - Pivot Points **Mô tả**: Tính toán các điểm xoay trục Pivot Points. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.pivots(method="traditional") ``` --- ### mad - Mean Absolute Deviation **Mô tả**: Tính toán độ lệch tuyệt đối trung bình Mean Absolute Deviation. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.mad(length=30) ``` --- ### variance - Variance **Mô tả**: Tính toán phương sai Variance của chuỗi dữ liệu. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.variance(length=30) ``` --- ### hl2 - High-Low Average **Mô tả**: Tính toán giá trung bình Cao - Thấp. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.hl2() ``` --- ### hlc3 - High-Low-Close Average **Mô tả**: Tính toán giá trung bình Cao - Thấp - Đóng cửa. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.hlc3() ``` --- ### ohlc4 - Open-High-Low-Close Average **Mô tả**: Tính toán giá trung bình Mở - Cao - Thấp - Đóng cửa. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.ohlc4() ``` --- ### midprice - Midprice **Mô tả**: Tính toán chỉ báo giá trung bình Midprice. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.midprice(length=14) ``` --- ### decreasing - Decreasing Series **Mô tả**: Xác định chuỗi giá trị giảm dần. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.decreasing(length=1) ``` --- ### increasing - Increasing Series **Mô tả**: Xác định chuỗi giá trị tăng dần. **Cách gọi**: ```python # Trả về pd.Series hoặc pd.DataFrame result = ta.statistics.increasing(length=1) ``` --- ## Document: Giới thiệu Vnstock TA

Trang này mô tả vnstock_ta 1.x. Nếu bạn đang dùng vnstock_quant, hãy xem tài liệu hiện hành. Quyền sử dụng và cách cài gói cũ có thể khác bản mới.

## Tổng quan `vnstock_ta` 1.x là thư viện Python để tính chỉ báo kỹ thuật từ dữ liệu giá bạn đã có. Các ví dụ dưới đây dùng giao diện và tên gói của phiên bản cũ. ### Đặc điểm chính - **Chỉ báo kỹ thuật**: Các hàm được chia theo xu hướng, động lượng, biến động, khối lượng và thống kê. - **Cách gọi**: Dùng lớp `Indicator` với bảng dữ liệu pandas. - **Kết quả**: Hàm trả về `Series` hoặc `DataFrame`, tuỳ chỉ báo. - **Biểu đồ**: Tài liệu cũ dùng `vnstock_ezchart`; với thế hệ 5, xem [`vnstock_chart`](/docs/vnstock-chart). --- ## Yêu cầu dữ liệu đầu vào DataFrame đầu vào phải đáp ứng các yêu cầu (tương thích sẵn với `vnstock_data`): 1. **Index**: Tốt nhất là `DatetimeIndex` (tên `'time'`). 2. **Cột bắt buộc**: `'open'`, `'high'`, `'low'`, `'close'` (tất cả là float), `'volume'` (int). Các chỉ báo có giá trị kỳ tính toán (period) lớn (ví dụ: SMA 50 hoặc SMA 200) sẽ có giá trị `NaN` ở đầu dữ liệu do không đủ số lượng phiên để tính toán. Đây là hiện tượng bình thường. --- ## Các nhóm chỉ báo hỗ trợ Các chỉ báo trong tài liệu phiên bản này được chia thành năm nhóm: ### 1. Trend Indicators (Chỉ báo xu hướng) Dùng để xác định xu hướng chính của thị trường (tăng, giảm, hay đi ngang). | Chỉ báo | Ký hiệu | Mô tả | | :--------- | :----------- | :--------------------------------------------------------------------- | | SMA | `sma` | Simple Moving Average (Đường trung bình động đơn giản) | | EMA | `ema` | Exponential Moving Average (Đường trung bình động lũy thừa) | | WMA | `wma` | Weighted Moving Average (Đường trung bình động có trọng số) | | HMA | `hma` | Hull Moving Average (Đường trung bình động Hull) | | SMMA | `smma` | Smoothed Moving Average (Đường trung bình động làm mượt) | | ALMA | `alma` | Arnaud Legoux Moving Average (Đường trung bình động Arnaud Legoux) | | VWMA | `vwma` | Volume-Weighted Moving Average (Đường trung bình động theo khối lượng) | | ADX | `adx` | Average Directional Index (Chỉ số định hướng trung bình) | | ICHIMOKU | `ichimoku` | Ichimoku Cloud (Hệ thống Ichimoku) | | PSAR | `psar` | Parabolic SAR (Chỉ báo Parabolic Stop and Reverse) | | SUPERTREND | `supertrend` | Supertrend (Chỉ báo Supertrend) | | DM | `dm` | Directional Movement (Chỉ số chuyển động định hướng) | | LINREG | `linreg` | Linear Regression (Hồi quy tuyến tính) | | AROON | `aroon` | Aroon Indicator (Chỉ báo Aroon) | ### 2. Momentum Indicators (Chỉ báo động lượng) Dùng để đo lường tốc độ biến động giá và xác định trạng thái quá mua (overbought) hoặc quá bán (oversold). | Chỉ báo | Ký hiệu | Mô tả | | :------- | :--------- | :--------------------------------------------------------------------------- | | RSI | `rsi` | Relative Strength Index (Chỉ số sức mạnh tương đối) | | STOCH | `stoch` | Stochastic Oscillator (Chỉ báo dao động ngẫu nhiên) | | STOCHRSI | `stochrsi` | Stochastic RSI (Chỉ báo Stochastic RSI) | | ROC | `roc` | Rate of Change (Tốc độ thay đổi giá) | | AO | `ao` | Awesome Oscillator (Chỉ báo dao động Awesome) | | CCI | `cci` | Commodity Channel Index (Chỉ số kênh hàng hóa) | | WILLR | `willr` | Williams %R (Chỉ báo Williams %R) | | TSI | `tsi` | True Strength Index (Chỉ số sức mạnh thực sự) | | CMO | `cmo` | Chande Momentum Oscillator (Chỉ báo dao động động lượng Chande) | | UO | `uo` | Ultimate Oscillator (Chỉ báo dao động tối thượng) | | FISHER | `fisher` | Fisher Transform (Phép biến đổi Fisher) | | CG | `cg` | Center of Gravity (Chỉ báo trọng tâm) | | KST | `kst` | Know Sure Thing (Chỉ báo KST) | | MACD | `macd` | Moving Average Convergence Divergence (Đường trung bình động hội tụ phân kỳ) | ### 3. Volatility Indicators (Chỉ báo biến động) Dùng để xác định mức độ dao động hoặc biên độ giá của thị trường. | Chỉ báo | Ký hiệu | Mô tả | | :---------- | :------------ | :----------------------------------------------------------- | | BBANDS | `bbands` | Bollinger Bands (Dải Bollinger) | | KC | `kc` | Keltner Channels (Kênh Keltner) | | ATR | `atr` | Average True Range (Khoảng dao động thực tế trung bình) | | STDEV | `stdev` | Standard Deviation (Độ lệch chuẩn) | | DONCHIAN | `donchian` | Donchian Channels (Kênh Donchian) | | MASSI | `massi` | Mass Index (Chỉ số khối lượng) | | UI | `ui` | Ulcer Index (Chỉ số Ulcer) | | SQUEEZE | `squeeze` | Squeeze Momentum (Chỉ báo bóp nghẹt động lượng) | | SQUEEZE_PRO | `squeeze_pro` | Squeeze Momentum Pro (Chỉ báo bóp nghẹt động lượng nâng cao) | | TRUE_RANGE | `true_range` | True Range (Khoảng dao động thực tế) | ### 4. Volume Indicators (Chỉ báo khối lượng) Dùng để phân tích mối tương quan giữa khối lượng giao dịch và sự thay đổi giá. | Chỉ báo | Ký hiệu | Mô tả | | :------ | :------ | :----------------------------------------------------------------------- | | OBV | `obv` | On-Balance Volume (Khối lượng cân bằng) | | CMF | `cmf` | Chaikin Money Flow (Dòng tiền Chaikin) | | AD | `ad` | Accumulation/Distribution (Đường tích lũy/phân phối) | | VP | `vp` | Volume Profile (Hồ sơ khối lượng) | | VWAP | `vwap` | Volume Weighted Average Price (Giá trung bình gia quyền theo khối lượng) | | PVO | `pvo` | Percentage Volume Oscillator (Chỉ báo dao động phần trăm khối lượng) | | EFI | `efi` | Force Index (Chỉ số lực) | | EOM | `eom` | Ease of Movement (Chỉ số di chuyển dễ dàng) | | NVI | `nvi` | Negative Volume Index (Chỉ số khối lượng tiêu cực) | | MFI | `mfi` | Money Flow Index (Chỉ số dòng tiền) | ### 5. Statistics Indicators (Chỉ báo thống kê và cấu trúc) Các công cụ tính toán thống kê và cấu trúc giá trị trung bình trên thị trường. | Chỉ báo | Ký hiệu | Mô tả | | :--------- | :----------- | :---------------------------------------------------------------------- | | PIVOTS | `pivots` | Pivot Points (Điểm xoay trục) | | MAD | `mad` | Mean Absolute Deviation (Độ lệch tuyệt đối trung bình) | | VARIANCE | `variance` | Variance (Phương sai) | | HL2 | `hl2` | High-Low Average (Trung bình giá Cao - Thấp) | | HLC3 | `hlc3` | High-Low-Close Average (Trung bình giá Cao - Thấp - Đóng cửa) | | OHLC4 | `ohlc4` | Open-High-Low-Close Average (Trung bình giá Mở - Cao - Thấp - Đóng cửa) | | MIDPRICE | `midprice` | Midprice (Giá trung bình) | | DECREASING | `decreasing` | Decreasing Series (Chuỗi giảm dần) | | INCREASING | `increasing` | Increasing Series (Chuỗi tăng dần) | --- ## Document: Lịch sử phiên bản ## 16-05-2026 ### Cập nhật Vnstock Data 3.1.8 - **Chuẩn hoá Báo cáo Tài chính (Unified UI)**: - Đồng bộ Schema báo cáo tài chính cho các nguồn dữ liệu (MAS, VCI), xử lý triệt để lỗi lệch cột và lẫn lộn ngôn ngữ (mixed labels) bằng hệ thống Mapping chỉ số La Mã (Roman numeral). - Bổ sung thông tin kỳ báo cáo (`report_period`) cho nguồn VCI, giúp kết quả tương thích với giao diện Unified UI. - **Thị trường Trái phiếu (Bond Market)**: - Tích hợp lớp domain `bond` vào hệ thống Unified UI, mở rộng khả năng tra cứu dữ liệu thị trường trái phiếu. ### Cập nhật Vnstock TA 1.0.3 > Bản Vnstock TA 1.0.3 cập nhật cách cài đặt và xử lý dữ liệu cho người dùng phiên bản cũ. **✨ Bạn có thể làm gì với bản cập nhật này?** - **Sử dụng kho chỉ báo đa dạng**: Bổ sung nhóm chỉ báo Thống kê (Statistics), chỉ báo sức mạnh xu hướng (Aroon) và mở rộng đáng kể các nhóm chỉ báo Xu hướng (Trend), Biến động (Volatility). - **Vẽ biểu đồ chuyên nghiệp với phong cách hiện đại**: Hệ thống Theme mới giúp biểu đồ có giao diện hiện đại và nhất quán. Các chỉ báo phức tạp nhiều đường (như StochRSI, ADX, PVO...) giờ đây đã có chú thích (legend) và nhãn dữ liệu rõ ràng, dễ đọc. **⚡ Tối ưu trải nghiệm sử dụng** - **Giảm gói phụ thuộc**: Bỏ `pyecharts` và `panel` khỏi phần cài đặt để giảm các thành phần cần cài cùng thư viện. - **Dữ liệu ổn định và nhanh chóng**: Chuyển đổi toàn bộ việc lấy dữ liệu sang giao diện Unified UI của Vnstock, giúp tốc độ tính toán nhanh và độ tin cậy cao hơn. --- ## Document: Vẽ biểu đồ với vnstock_ta 1.x

Ví dụ trên trang này dùng vnstock_ta 1.x và vnstock_ezchart. Nếu bạn đã chuyển sang thế hệ 5, hãy dùng vnstock_chart để vẽ biểu đồ.

## Hướng dẫn chuyển đổi ### Cách dùng Plotter trong bản cũ Trong phiên bản cũ, bạn khởi tạo đối tượng `Plotter` trực tiếp từ `vnstock_ta` và gọi các hàm vẽ tích hợp: ```python from vnstock_ta import Plotter # Cú pháp của vnstock_ta 1.x plotter = Plotter(data=df, theme='light') plotter.sma(length=20, title='SMA 20') ``` ### Cách vẽ bằng vnstock_ezchart ở phiên bản này Trong nhánh tài liệu này, bạn tính chỉ báo bằng `vnstock_ta` rồi đưa kết quả vào `vnstock_ezchart`. Ví dụ dưới đây dành cho hai gói phiên bản cũ; cách vẽ ở thế hệ 5 nằm trong [tài liệu vnstock_chart](/docs/vnstock-chart). Ví dụ vẽ nến và hai chỉ báo: ```python from vnstock_ta import Indicator from vnstock_ezchart import Chart # Bước 1: Tính toán chỉ báo kỹ thuật bằng vnstock_ta ta = Indicator(data=df) df['SMA_20'] = ta.trend.sma(length=20) df['RSI_14'] = ta.momentum.rsi(length=14) # Bước 2: Định nghĩa cấu hình hiển thị (Overlay và Subplots) overlays = [ {"data": df['SMA_20'], "color": "#2563eb", "width": 2} ] subplots = [ [{"data": df['RSI_14'], "color": "#8b5cf6", "ylabel": "RSI"}] ] # Bước 3: Vẽ biểu đồ nến thông qua Chart.candle() fig, ax = Chart.candle( df, title="Biểu đồ với SMA và RSI", figsize=(12, 8), overlays=overlays, subplots=subplots ) ``` Khi dùng `vnstock_ezchart`, bạn có thể lưu hình từ `fig` để đưa vào báo cáo hoặc tài liệu nghiên cứu. Với mã mới, dùng `vnstock_chart` và tra cách gọi hàm theo phiên bản đã cài. --- ## Document: Các loại biểu đồ Các hàm vẽ nằm trên lớp `Chart`. Phần lớn nhận `DataFrame` hoặc `Series` và trả về hình cùng trục vẽ; một số hàm có kiểu trả về khác. Xem [tham chiếu hàm](/docs/vnstock-chart/tham-chieu-ham) trước khi ghép nhiều trục hoặc lưu ảnh. Các ảnh dưới đây vẽ từ giá lịch sử giai đoạn 01/2024–23/10/2026 để bạn chọn kiểu biểu đồ; chúng không phải nhận định về mã nào. Đoạn mã vẽ lại từng hình nằm ở trang [Kết hợp với thư viện thế hệ 5](/docs/vnstock-chart/ket-hop-voi-gen5). ## Xu hướng theo thời gian | Hàm | Dùng khi | Dữ liệu vào | |---|---|---| | `Chart.line(data)` | Theo dõi giá hoặc chỉ số qua thời gian | Series hoặc DataFrame có chỉ mục thời gian | | `Chart.candle(data, volume=True, overlays=[...])` | Xem giá mở cửa, cao nhất, thấp nhất, đóng cửa; có thể thêm khối lượng và đường chỉ báo | DataFrame có `open/high/low/close` | | `Chart.combo(bar_data, line_data)` | Đặt cột và đường trên hai trục tung, chẳng hạn khối lượng và giá | Hai Series/DataFrame có cùng chỉ mục thời gian | ![Chart.line: hiệu suất quy về 100 của bốn mã và VNINDEX](/images/docs/vnstock-chart/line_performance.png) ![Chart.combo: khối lượng tháng dạng cột và giá đóng cửa dạng đường trên hai trục tung](/images/docs/vnstock-chart/combo_volume_price.png) ## Biểu đồ nến và khối lượng Với `Chart.candle`, dùng `overlays` để thêm đường lên khung giá hoặc `subplots` để đặt chỉ báo như RSI, MACD ở khung riêng bên dưới. ![Chart.candle với hai đường trung bình động chồng lên nến và khối lượng ở khung dưới](/images/docs/vnstock-chart/candle_sma.png) ![Chart.candle với dải Bollinger trên khung giá, RSI và MACD ở hai khung phụ](/images/docs/vnstock-chart/candle_rsi_macd.png) ## So sánh giá trị và phân phối | Hàm | Dùng khi | |---|---| | `Chart.bar(data)` | So sánh giá trị giữa các nhóm hoặc kỳ báo cáo | | `Chart.hist(data)` | Xem một biến tập trung ở khoảng giá trị nào | | `Chart.boxplot(data)` | So sánh độ phân tán và các điểm nằm xa phần lớn dữ liệu | | `Chart.table(data)` | Xuất bảng dữ liệu thành hình | ![Chart.bar: cột nhóm so sánh lợi suất, biến động và sụt giảm tối đa của sáu mã](/images/docs/vnstock-chart/bar_risk.png) ![Chart.hist: phân phối lợi suất ngày của HPG](/images/docs/vnstock-chart/hist_returns.png) ![Chart.boxplot: độ phân tán lợi suất ngày của sáu mã](/images/docs/vnstock-chart/boxplot_returns.png) ![Chart.table: bảng chỉ số rủi ro của HPG xuất thành hình](/images/docs/vnstock-chart/table_risk.png) ## Tương quan | Hàm | Dùng khi | |---|---| | `Chart.scatter(data, x=, y=)` | Tương quan hai biến | | `Chart.pairplot(data)` | Xem quan hệ từng cặp biến trong một DataFrame | | `Chart.heatmap(data)` | Ma trận tương quan dạng nhiệt, ví dụ `df.corr()` | ![Chart.scatter: lợi suất ngày của HPG theo VNINDEX, kèm đường có độ dốc bằng beta](/images/docs/vnstock-chart/scatter_beta.png) ![Chart.heatmap: ma trận tương quan lợi suất giữa sáu mã](/images/docs/vnstock-chart/heatmap_corr.png) ## Tỉ lệ | Hàm | Dùng khi | |---|---| | `Chart.pie(data, labels=)` | Tỉ trọng cổ đông, phân bổ tài sản | | `Chart.treemap(values=, labels=)` | So sánh tỉ trọng của nhiều nhóm bằng diện tích ô; cần cài `[all]` | ![Chart.pie: tỉ trọng sáu mã trong danh mục cân bằng rủi ro](/images/docs/vnstock-chart/pie_weights.png) ![Chart.treemap: đóng góp rủi ro của sáu mã khi chia đều vốn](/images/docs/vnstock-chart/treemap_risk.png) ## Trình bày kết quả phân tích | Hàm | Dùng khi | |---|---| | `Chart.equity_curve(data, benchmark=...)` | Đường vốn và mức sụt giảm từ đỉnh; có thể thêm chuỗi đối chiếu | | `Chart.backtest(data, trades=, portfolio=)` | Điểm mua, bán trên nến kèm khung vốn và mức sụt giảm | | `Chart.returns_heatmap(data)` | Lợi suất theo tháng/năm dạng nhiệt | | `Chart.rrg(...)` | So sánh sức mạnh và động lượng tương đối của nhiều mã hoặc ngành | | `Chart.summary_card(ticker=, company_name=, current_price=, ...)` | Tạo hình tóm tắt giá, mức thay đổi và các chỉ số bạn cung cấp | ![Chart.equity_curve: đường vốn của một quy tắc giao dịch so với mua và nắm giữ, kèm mức sụt giảm](/images/docs/vnstock-chart/equity_curve.png) ![Chart.backtest: điểm mua, bán trên nến, khung khối lượng, đường vốn và mức sụt giảm](/images/docs/vnstock-chart/backtest.png) ![Chart.returns_heatmap: lợi suất theo tháng của VNINDEX](/images/docs/vnstock-chart/returns_heatmap.png) ![Chart.rrg: biểu đồ xoay vòng tương đối của sáu mã so với VNINDEX](/images/docs/vnstock-chart/rrg.png) ![Chart.summary_card: thẻ tóm tắt giá và chỉ số của HPG](/images/docs/vnstock-chart/summary_card.png) Một số nhãn tự sinh trong `equity_curve`, `backtest`, `returns_heatmap` và `rrg` (tên trục, chú giải, tên tháng) hiện vẫn in bằng tiếng Anh dù đã đặt `lang='vi'`. Bạn có thể đổi lại trên các trục trả về, ví dụ `ax1.set_ylabel("Lợi suất luỹ kế")`. ## Khác | Hàm | Dùng khi | |---|---| | `Chart.wordcloud(text)` | Trình bày tần suất từ trong đoạn văn bản bạn đưa vào; cần cài `[all]` | ## Tuỳ biến chung Nhiều hàm nhận `title`, `figsize`, `color_palette` và `font_name`. Để dùng chung bảng màu, phông chữ và ngôn ngữ nhãn, gọi `set_theme` trước khi vẽ: ```python Chart.set_theme(theme_name='vnstock', font_name='Inter', lang='vi') ``` Xem [Tham chiếu hàm](/docs/vnstock-chart/tham-chieu-ham) để biết tham số nào áp dụng cho từng biểu đồ. Bạn cũng có thể gọi `help(Chart.candle)` trong Python. --- ## Document: Cài đặt ## Cài bản mặc định `vnstock_chart` được phát hành qua kho phát hành thư viện của Vnstock. Thêm địa chỉ kho phát hành vào lệnh cài: ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-chart ``` Bản mặc định có các biểu đồ đường, nến, cột, phân phối, tương quan và bản đồ nhiệt. ## Cài thêm treemap và word cloud Nếu cần biểu đồ cây (`treemap`) hoặc đám mây từ (`wordcloud`), cài thêm các gói phụ bằng tuỳ chọn `[all]`: ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock-chart[all]" ``` Bạn không cần `[all]` nếu chỉ dùng các biểu đồ còn lại. ## Kiểm tra bản cài ```python from vnstock_chart import Chart print(Chart) ``` ## Yêu cầu - Python 3.10 trở lên. - `vnstock` thế hệ 5 (từ bản 5.0) nếu bạn dùng `Market()` hoặc `Reference()` để truy xuất dữ liệu. Riêng `vnstock_chart` chỉ vẽ từ dữ liệu bạn đưa vào; bản thân thao tác vẽ không cần khoá API. - `numpy>=1.24` và `pandas>=2.0`. ## Lỗi hay gặp | Hiện tượng | Nguyên nhân | Cách xử lý | |---|---|---| | `Could not find a version that satisfies the requirement vnstock-chart` | Thiếu `--extra-index-url` | Thêm `--extra-index-url https://vnstocks.com/api/packages` vào lệnh `pip install` | | `ModuleNotFoundError: No module named 'squarify'` khi gọi `treemap()` | Chưa cài phần mở rộng `[all]` | `pip install "vnstock-chart[all]" --extra-index-url https://vnstocks.com/api/packages` | | Vẫn thấy `vnstock_ezchart` sau khi cài `vnstock_chart` | Đây là hai gói riêng | Nếu không còn dùng gói cũ, chạy `pip uninstall vnstock_ezchart` | --- ## Document: Giới thiệu vnstock_chart `vnstock_chart` giúp bạn vẽ biểu đồ từ `DataFrame` hoặc `Series` trong Python. Bạn có thể dùng dữ liệu đã truy xuất bằng `vnstock`, kết quả tính từ `vnstock_quant` hoặc dữ liệu do mình chuẩn bị. Thư viện cung cấp các hàm vẽ với cấu hình trình bày dùng chung, dựa trên Matplotlib, Seaborn và mplfinance. Bạn hoặc trợ lý AI chọn hàm, đưa dữ liệu vào và chỉnh những tham số cần thiết, thay vì viết lại nhiều dòng mã cho mỗi biểu đồ. Bảng màu, phông chữ và bố cục dùng chung giúp các hình giữ cách trình bày nhất quán, kể cả khi được tạo ở những lần khác nhau. Bạn có thể lưu biểu đồ để đưa vào báo cáo, tài liệu PDF hoặc quy trình tạo báo cáo tự động. Thư viện hỗ trợ biểu đồ nến, đường, cột, phân phối, tương quan và một số biểu đồ cho kết quả phân tích định lượng. ## Một vài hình mẫu Nến kèm chỉ báo kỹ thuật tính bằng `vnstock_quant`, mỗi chỉ báo một khung: ![Biểu đồ nến của HPG với dải Bollinger, RSI và MACD vẽ bằng vnstock_chart](/images/docs/vnstock-chart/candle_rsi_macd.png) Đường vốn của một quy tắc giao dịch so với mua và nắm giữ, kèm mức sụt giảm từ đỉnh: ![Đường vốn và mức sụt giảm từ đỉnh vẽ bằng Chart.equity_curve](/images/docs/vnstock-chart/equity_curve.png) Vị trí của từng mã so với chỉ số chung theo sức mạnh và động lượng tương đối: ![Biểu đồ xoay vòng tương đối của sáu mã vẽ bằng Chart.rrg](/images/docs/vnstock-chart/rrg.png) Các hình mẫu vẽ từ giá lịch sử đến phiên 23/10/2026, chỉ để minh hoạ cách vẽ. Đoạn mã của từng hình nằm ở trang [Kết hợp với thư viện thế hệ 5](/docs/vnstock-chart/ket-hop-voi-gen5); xem thêm hình mẫu ở [Các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do). ## Nếu bạn từng dùng vnstock_ezchart `vnstock_chart` kế tục `vnstock_ezchart`. Nếu đang dùng gói cũ, bạn cần cài gói mới và đổi câu lệnh `import`; các tên hàm vẫn giữ nguyên. Xem [cách chuyển từ vnstock_ezchart](/docs/vnstock-chart/khac-biet-voi-ezchart) trước khi sửa mã. ## Bắt đầu nhanh ```bash pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart ``` ```python from vnstock import Market from vnstock_chart import Chart df = Market().equity("FPT").ohlcv(start="2024-01-01", end="2024-12-31") fig, ax = Chart.candle(df, title="FPT — Nến ngày 2024") fig.savefig("fpt_2024.png", dpi=150, bbox_inches="tight") ``` Đọc [Cài đặt](/docs/vnstock-chart/cai-dat) nếu bạn chưa có thư viện. Sau đó, xem [Các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do) để chọn hàm phù hợp, [Kết hợp với thư viện thế hệ 5](/docs/vnstock-chart/ket-hop-voi-gen5) để chuẩn bị dữ liệu và [Tham chiếu hàm](/docs/vnstock-chart/tham-chieu-ham) khi cần tra tham số. --- ## Document: Kết hợp với thư viện thế hệ 5

vnstock_chart nhận dữ liệu đã có trong DataFrame hoặc Series. Trong các ví dụ dưới đây, bạn truy xuất hoặc tính dữ liệu trước, rồi truyền kết quả vào Chart.

Mỗi mục nêu một cách trình bày dữ liệu, đoạn mã để bạn chạy thử và hình kết quả của chính đoạn mã đó.

Hình được vẽ từ giá lịch sử giai đoạn 01/2024–23/10/2026. Nếu bạn đổi ngày kết thúc hoặc danh sách mã, đường vẽ và con số sẽ khác hình. Các hình chỉ minh hoạ cách đưa dữ liệu vào hàm vẽ; mã cổ phiếu, quy tắc danh mục và kiểm thử trong ví dụ không phải nhận định hay khuyến nghị đầu tư.

## Chuẩn bị dữ liệu dùng chung Chạy đoạn chuẩn bị này một lần trước khi thử các mục bên dưới. Các nhóm hàm rủi ro và danh mục của `vnstock_quant` cần cấp quyền phù hợp; nếu chỉ muốn thử hàm vẽ, bạn có thể bắt đầu từ các mục dùng dữ liệu giá và khối lượng. ```python import pandas as pd import matplotlib.pyplot as plt from vnstock import Market from vnstock_chart import Chart, Utils from vnstock_quant import Indicator, risk, portfolio as pm # Bảng màu: xanh cho chuỗi chính, xám cho chuỗi đối chiếu, # vàng cho phần phụ và đỏ cho mức giảm hoặc sụt giảm. Utils.brand_palettes["vnstock_brand"] = ["#4CAF50", "#8A918A", "#FFB31A", "#F05A5F", "#2EA8F0", "#8C52FF"] # Bảng phân loại cho hình tròn, biểu đồ cây, biểu đồ xoay vòng: màu sáng, không có đỏ. CAT = ["#4CAF50", "#2EA8F0", "#FFB31A", "#8C52FF", "#22C3B4", "#A5DC86"] Utils.brand_palettes["vnstock_brand_cat"] = CAT Chart.set_theme(theme_name="vnstock_brand", font_name="Lexend", lang="vi") def no_grid(): # Biểu đồ nến (mplfinance) bật lưới trong cấu hình chung và để lưới nằm trên cột. # Gọi hàm này trước các hình không phải nến để khỏi có vạch trắng cắt ngang cột. plt.rcParams.update({"axes.grid": False, "axes.axisbelow": True}) m = Market() TICKERS = ["FPT", "VCB", "HPG", "MWG", "SSI", "GAS"] # thay theo danh sách bạn muốn xem BENCH = "VNINDEX" # chỉ số đối chiếu MAIN = "HPG" # mã dùng cho các ví dụ một mã def ohlcv(src, start="2024-01-01", end="2026-10-23"): df = src.ohlcv(start=start, end=end) # Bỏ thông tin múi giờ để nhãn ngày trên trục hiển thị gọn df = df.set_index(df["time"].dt.tz_localize(None)).drop(columns="time") return df[~df.index.duplicated(keep="last")] # phòng khi nguồn trả trùng một phiên df = ohlcv(m.equity(MAIN)) df_1y = df.iloc[-250:] # 12 tháng gần nhất, để vẽ nến bench = ohlcv(m.index(BENCH))["close"].rename(BENCH) prices = pd.DataFrame({t: ohlcv(m.equity(t))["close"] for t in TICKERS}).dropna() rets = prices.pct_change().dropna() # lợi suất ngày của từng mã bench_rets = bench.pct_change().dropna() # Mọi chỉ số rủi ro tính MỘT lần, trên cùng một giai đoạn, rồi dùng lại ở mọi hình. stats = pd.DataFrame({t: risk.summary(rets[t], bench_rets, rf=0.03) for t in TICKERS}).T ``` `stats` là chỗ duy nhất tính lợi suất năm, biến động, sụt giảm tối đa, beta… Bảng ở mục 5, biểu đồ cột ở mục 6 và thẻ tóm tắt ở mục 11 đều đọc từ đây, nên cùng một chỉ số luôn ra cùng một con số. Nếu mỗi hình tự tính trên một khoảng thời gian khác nhau, hai hình của cùng một mã sẽ báo hai mức sụt giảm khác nhau và người đọc không biết tin con số nào. Lưới chỉ nên có khi người xem cần dóng giá trị, như ở biểu đồ đường và cột; khi đó truyền `grid=True, grid_axis="y"` để có lưới ngang mờ. Histogram, hộp phân tán, đồ thị phân tán và bản đồ nhiệt không cần lưới. Chữ Lexend phải có sẵn trên máy (tải ở Google Fonts). Nếu không có, Matplotlib tự dùng phông mặc định và hình vẫn vẽ được. Khi chạy trong script hoặc trên máy chủ không có màn hình, thêm `show=False` vào lệnh vẽ rồi lưu hình bằng `fig.savefig("ten_hinh.png", dpi=150, bbox_inches="tight")`. ## 1. Xem giá cùng đường trung bình động Vẽ nến ngày, chồng hai đường trung bình động và đặt khối lượng ở khung dưới. Hai đường trung bình giúp quan sát vị trí của giá và sự thay đổi xu hướng. Chúng chỉ mô tả dữ liệu đã qua, không tự đưa ra quyết định mua bán. ```python ta = Indicator(df_1y) fig, axes = Chart.candle( df_1y, title=f"{MAIN} — Nến ngày, SMA20 (vàng), SMA50 (xanh trời) và khối lượng", volume=True, overlays=[ {"data": ta.trend.sma(length=20), "color": "#FFB31A", "width": 1.6}, {"data": ta.trend.sma(length=50), "color": "#2EA8F0", "width": 1.6}, ], ) ``` ![Biểu đồ nến của HPG kèm đường SMA20 màu vàng, SMA50 màu xanh trời và khối lượng ở khung dưới](/images/docs/vnstock-chart/candle_sma.png) `overlays` không tự sinh chú giải, nên hãy chọn màu dễ phân biệt và ghi màu ngay trong tiêu đề như trên. ## 2. Đặt nhiều chỉ báo trên cùng biểu đồ nến Đặt dải Bollinger lên khung giá, còn RSI và MACD ở hai khung phụ bên dưới. Mỗi phần tử của `subplots` là một khung; truyền một danh sách các `dict` để nhiều đường dùng chung một khung, như MACD cùng đường tín hiệu và cột chênh lệch. ```python bb = ta.volatility.bbands(length=20, std=2.0) macd = ta.macd(fast=12, slow=26, signal=9) rsi = ta.momentum.rsi(length=14) fig, axes = Chart.candle( df_1y, title=f"{MAIN} — Bollinger Bands, RSI(14) và MACD(12,26,9)", volume=False, overlays=[ {"data": bb["BBU_20_2.0"], "color": "#2EA8F0", "width": 1.0}, {"data": bb["BBM_20_2.0"], "color": "#FFB31A", "width": 1.0}, {"data": bb["BBL_20_2.0"], "color": "#2EA8F0", "width": 1.0}, ], subplots=[ {"data": rsi, "color": "#8C52FF", "ylabel": "RSI"}, [ {"data": macd["MACD_12_26_9"], "color": "#2EA8F0", "ylabel": "MACD"}, {"data": macd["MACDs_12_26_9"], "color": "#FFB31A"}, {"data": macd["MACDh_12_26_9"], "type": "bar", "color": "#D6DBD6"}, ], ], figsize=(12, 9), ) ``` ![Biểu đồ nến của HPG với dải Bollinger, RSI ở khung giữa và MACD ở khung dưới](/images/docs/vnstock-chart/candle_rsi_macd.png) ## 3. So sánh biến động giá giữa các mã Giá của các mã chênh nhau nhiều nên không đặt chung một trục được. Quy tất cả về 100 ở phiên đầu kỳ thì mọi đường xuất phát cùng một điểm, và khoảng cách giữa các đường cho thấy mức tăng giảm tương đối trong kỳ đã chọn. ```python no_grid() base = pd.concat([prices, bench], axis=1).loc["2025-01-01":] norm = base / base.iloc[0] * 100 norm.index.name = None # không in tên chỉ mục "time" dưới trục X fig, ax = Chart.line( norm[[BENCH, *TICKERS[:4]]], title="Hiệu suất từ đầu năm 2025 (quy về 100)", ylabel="Chỉ số (đầu kỳ = 100)", show_legend=True, grid=True, grid_axis="y", color_palette=["#8A918A", "#4CAF50", "#2EA8F0", "#FFB31A", "#8C52FF"], ) ax.get_lines()[0].set_linestyle("--") # chỉ số vẽ nét đứt để tách khỏi các mã ax.legend(frameon=False) # vẽ lại chú giải cho khớp nét đứt ``` ![Đường hiệu suất quy về 100 của FPT, VCB, HPG, MWG và VNINDEX nét đứt từ đầu năm 2025](/images/docs/vnstock-chart/line_performance.png)

Ở bản 1.0.0, line, bar và hist không hiện chú giải nếu bạn không truyền show_legend=True. Biểu đồ nhiều đường mà thiếu chú giải thì người xem không biết đường nào là mã nào.

## 4. Khối lượng thay đổi cùng giá ra sao? `Chart.combo` đặt khối lượng thành cột ở trục trái và giá thành đường ở trục phải. Gộp theo tháng giúp hình đỡ dày khi xem khoảng thời gian dài. Tên của hai `Series` được dùng làm chú giải. ```python mo = df.loc["2025-07-01":].resample("ME").agg({"close": "last", "volume": "sum"}) mo.index = mo.index.strftime("%m/%y") vol = (mo["volume"] / 1e6).rename("Khối lượng tháng (triệu cp)") px = mo["close"].rename("Giá đóng cửa cuối tháng") fig, ax1, ax2 = Chart.combo( vol, px, left_ylabel="Khối lượng (triệu cổ phiếu)", right_ylabel="Giá (nghìn đồng)", title=f"{MAIN} — Khối lượng và giá theo tháng", color_palette=["#A5DC86", "#2EA8F0"], # cột xanh lá nhạt, đường xanh trời ) ``` ![Cột khối lượng tháng và đường giá đóng cửa cuối tháng của HPG trên hai trục tung](/images/docs/vnstock-chart/combo_volume_price.png) Hình trên có thêm vài dòng chỉnh trục sau khi vẽ (`ax1.set_ylim`, `ax2.set_ylim`, `ax1.legend(loc="upper center", ncol=2)`) để chú giải không đè lên đường giá. Bạn có thể chỉnh tiếp trên `ax1`, `ax2` như mọi trục Matplotlib. ## 5. Xem phân bố lợi suất và các thước đo rủi ro Ba cách nhìn bổ sung cho nhau: histogram cho thấy phân bố lợi suất ngày; đồ thị phân tán đặt lợi suất của mã cạnh chỉ số đối chiếu; bảng gom các thước đo đã tính. Độ dốc của đường tham chiếu trên đồ thị phân tán được lấy từ beta trong `stats`. ```python fig, ax = Chart.hist(rets[MAIN] * 100, title=f"{MAIN} — Phân phối lợi suất ngày (%), 01/2024–10/2026", xlabel="Lợi suất ngày (%)", ylabel="Số phiên", bins=40) ``` ![Histogram lợi suất ngày của HPG, tập trung quanh 0](/images/docs/vnstock-chart/hist_returns.png) ```python import numpy as np pair = pd.concat([rets[MAIN], bench_rets], axis=1).dropna() * 100 pair.columns = [f"{MAIN} (%)", f"{BENCH} (%)"] beta = stats.loc[MAIN, "beta"] # lấy từ stats, không tính lại fig, ax = Chart.scatter(pair, x=f"{BENCH} (%)", y=f"{MAIN} (%)", title=f"{MAIN} so với {BENCH} — lợi suất ngày (beta ≈ {beta:.2f})") xs = np.linspace(pair[f"{BENCH} (%)"].min(), pair[f"{BENCH} (%)"].max(), 50) ax.plot(xs, beta * xs, color="#2EA8F0", lw=2) # đường có độ dốc bằng beta ``` ![Đồ thị phân tán lợi suất ngày của HPG theo VNINDEX, kèm đường tham chiếu theo beta](/images/docs/vnstock-chart/scatter_beta.png) ```python def vn(x, fmt): # dấu phẩy thập phân kiểu Việt Nam return fmt.format(x).replace(".", ",") s = stats.loc[MAIN] tbl = pd.DataFrame({ "Chỉ số": ["Lợi suất năm", "Biến động năm", "Sharpe", "Sortino", "Sụt giảm tối đa", "VaR 99% ngày", "Beta"], MAIN: [vn(s["annual_return"], "{:.1%}"), vn(s["annual_volatility"], "{:.1%}"), vn(s["sharpe_ratio"], "{:.2f}"), vn(s["sortino_ratio"], "{:.2f}"), vn(s["max_drawdown"], "{:.1%}"), vn(s["var_historical"], "{:.2%}"), vn(s["beta"], "{:.2f}")], }) fig = Chart.table(tbl, title=f"{MAIN} — Rủi ro và hiệu suất so với {BENCH}, 01/2024–10/2026", figsize=(6, 4)) ``` ![Bảng các chỉ số rủi ro và hiệu suất của HPG so với VNINDEX](/images/docs/vnstock-chart/table_risk.png) `Chart.table` in giá trị đúng như trong `DataFrame`, nên hãy định dạng số thành chuỗi trước khi truyền vào. Hàm này chỉ trả về `fig`. ## 6. So sánh rủi ro giữa nhiều mã Cột nhóm đặt lợi suất, biến động và mức sụt giảm của từng mã cạnh nhau. Hộp phân tán cho thấy biên độ dao động hằng ngày, và ma trận tương quan cho biết những mã nào hay tăng giảm cùng nhau. Hai mã tương quan cao thì nắm cả hai cũng không giảm rủi ro được bao nhiêu. ```python compare = pd.DataFrame({ "Lợi suất năm": stats["annual_return"], "Biến động năm": stats["annual_volatility"], "Sụt giảm tối đa": -stats["max_drawdown"], }) fig, ax = Chart.bar(compare, title="Lợi suất, biến động và sụt giảm tối đa, 01/2024–10/2026", ytick_format="{:.0%}", show_legend=True, rot=0, grid=True, grid_axis="y", color_palette=["#4CAF50", "#2EA8F0", "#F05A5F"]) ``` ![Biểu đồ cột nhóm so sánh lợi suất năm, biến động năm và sụt giảm tối đa của sáu mã](/images/docs/vnstock-chart/bar_risk.png) `rot=0` được chuyển thẳng cho pandas để nhãn trục X nằm ngang. Đừng dùng `tick_rotation=0` vì bản 1.0.0 coi giá trị 0 là chưa đặt. ```python fig, ax = Chart.boxplot(rets * 100, title="Độ phân tán lợi suất ngày theo mã (%), 01/2024–10/2026", ylabel="Lợi suất ngày (%)") ``` ![Hộp phân tán lợi suất ngày của sáu mã](/images/docs/vnstock-chart/boxplot_returns.png) ```python from matplotlib.colors import LinearSegmentedColormap green = LinearSegmentedColormap.from_list("vnstock_green", ["#FFFFFF", "#CDEFC4", "#4CAF50"]) fig, ax = Chart.heatmap(rets.corr(), title="Tương quan lợi suất ngày, 01/2024–10/2026", annot=True, fmt=".2f", cmap=green, vmin=0, vmax=1, linewidths=1, linecolor="white", figsize=(8, 6.5)) ``` ![Ma trận tương quan lợi suất ngày giữa sáu mã, tô từ trắng sang xanh lá](/images/docs/vnstock-chart/heatmap_corr.png) Dải màu dựng bằng `LinearSegmentedColormap.from_list` chuyển dần từ trắng sang xanh. `Utils.create_cmap` của bản 1.0.0 chỉ cho số bậc màu bằng số màu bạn truyền vào, nên 0,35 và 0,45 có thể cùng một màu. ## 7. Phân bổ vốn cho danh mục `vnstock_quant.portfolio` tính tỉ trọng và đóng góp rủi ro; `vnstock_chart` trình bày các kết quả đó. Hình tròn cho thấy tỉ trọng của một danh mục mẫu theo phương pháp cân bằng rủi ro. Biểu đồ cây cho thấy đóng góp rủi ro khi chia đều vốn. Các tỉ trọng chỉ minh hoạ cách vẽ, không phải gợi ý phân bổ vốn. Với hình tròn và biểu đồ cây, dùng bảng phân loại `CAT` đã khai ở đầu trang: màu sáng để chữ đen đọc rõ, và không có đỏ, vì đỏ là màu "giảm", đặt cho một mã bình thường dễ khiến người xem hiểu sai. ```python cov = pm.covariance(rets, periods=252, method="ledoit_wolf") w = pd.Series(pm.risk_parity(cov), index=TICKERS).sort_values(ascending=False).rename(None) fig, ax = Chart.pie(w, labels=list(w.index), title="Tỉ trọng danh mục cân bằng rủi ro", color_palette=CAT, title_fontsize=15) ``` ![Biểu đồ tròn tỉ trọng sáu mã trong danh mục cân bằng rủi ro](/images/docs/vnstock-chart/pie_weights.png) `Chart.pie` cần `data` là `pd.Series`; truyền `list` sẽ báo lỗi `AttributeError` ở bản 1.0.0. Đặt tên `Series` về `None` để không hiện nhãn thừa ở cạnh trái. ```python w_eq = pd.Series(1 / len(TICKERS), index=TICKERS) rc = pm.risk_contribution(w_eq, cov).sort_values("percent", ascending=False) labels = [f"{t}\n{p:.1%}".replace(".", ",") for t, p in rc["percent"].items()] fig, ax = Chart.treemap(values=rc["percent"].values, labels=labels, color_palette="vnstock_brand_cat", title="Đóng góp rủi ro khi chia đều vốn cho 6 mã", fontsize=12) for txt in ax.texts: # thư viện cố định chữ trắng; trên nền sáng đổi sang chữ mực txt.set_color("#141714") ``` ![Biểu đồ cây đóng góp rủi ro của sáu mã khi chia đều vốn](/images/docs/vnstock-chart/treemap_risk.png) `treemap` chỉ nhận tên bảng màu, nên `CAT` được đăng ký thành `"vnstock_brand_cat"` ở đầu trang. `treemap` cần cài thêm `vnstock-chart[all]`, xem [Cài đặt](/docs/vnstock-chart/cai-dat). ## 8. Kiểm thử một quy tắc giao dịch Quy tắc ví dụ: chỉ nắm giữ khi giá đóng cửa trên SMA50. `Chart.equity_curve` vẽ đường vốn của quy tắc so với mua và nắm giữ, kèm mức sụt giảm từ đỉnh ở khung dưới. ```python no_grid() close = df["close"] pos = (close > close.rolling(50).mean()).astype(int).shift(1).fillna(0) # vị thế phiên sau r = close.pct_change().fillna(0) strategy = (1 + r * pos).cumprod() buy_hold = (1 + r).cumprod() fig, ax1, ax2 = Chart.equity_curve(strategy, benchmark=buy_hold, title=f"{MAIN} — Đường vốn và mức sụt giảm từ đỉnh, 01/2024–10/2026") ``` ![Đường vốn của quy tắc giữ khi giá trên SMA50 so với mua và nắm giữ, kèm mức sụt giảm từ đỉnh](/images/docs/vnstock-chart/equity_curve.png) Muốn thấy từng lệnh mua, bán nằm ở đâu trên nến, dùng `Chart.backtest`. Hàm nhận danh sách lệnh (`trades`) và bảng vốn, mức sụt giảm (`portfolio`), rồi tự thêm khung cho từng phần: ```python d = df_1y.copy() # Tính SMA trên cả chuỗi rồi mới cắt, để 50 phiên đầu của khung 12 tháng không bị trống sma20 = df["close"].rolling(20).mean().loc[d.index] sma50 = df["close"].rolling(50).mean().loc[d.index] above = sma20 > sma50 # Ghi lệnh tại phiên SMA20 cắt lên (mua) hoặc cắt xuống (bán) SMA50 cross = above.astype(int).diff() trades = pd.DataFrame([{"time": t, "type": "BUY" if c > 0 else "SELL", "price": d.loc[t, "close"]} for t, c in cross.items() if c in (1, -1)]) eq = (1 + d["close"].pct_change().fillna(0) * above.astype(int).shift(1).fillna(0)).cumprod() portfolio = pd.DataFrame({"equity": eq, "drawdown": eq / eq.cummax() - 1}) fig, axes = Chart.backtest(d, trades=trades, portfolio=portfolio, overlays=[{"data": sma20, "color": "#FFB31A"}, {"data": sma50, "color": "#2EA8F0"}], title=f"{MAIN} — Kiểm thử quy tắc giao cắt SMA20/SMA50, 12 tháng gần nhất", figsize=(13, 10)) ``` ![Biểu đồ kiểm thử của HPG với điểm mua, bán trên nến, khung khối lượng, đường vốn và mức sụt giảm](/images/docs/vnstock-chart/backtest.png) Các đường vốn trong ảnh tính trên giá lịch sử và chưa gồm phí, thuế. Khi chạy với dữ liệu bạn chọn, hãy kiểm tra cách xác định vị thế, thời điểm khớp lệnh, phí và thuế trước khi diễn giải kết quả. Đoạn mã này minh hoạ cách đưa kết quả kiểm thử vào biểu đồ, chưa phải một quy trình đánh giá chiến lược đầy đủ. ## 9. Lợi suất theo tháng được phân bố thế nào? `Chart.returns_heatmap` nhận lợi suất ngày, tự gộp lên tháng và tô màu theo dấu: xanh là tăng, đỏ là giảm. Màu lấy từ vị trí 0 và 3 của bảng màu đang dùng. ```python no_grid() # Chart.backtest ở mục trên cũng vẽ bằng mplfinance fig, *axes = Chart.returns_heatmap(bench_rets, title=f"{BENCH} — Lợi suất theo tháng") ``` ![Bản đồ nhiệt lợi suất theo tháng của VNINDEX từ 01/2024 đến 10/2026](/images/docs/vnstock-chart/returns_heatmap.png) ## 10. Sức mạnh tương đối thay đổi ra sao? Biểu đồ xoay vòng tương đối đặt mỗi mã vào một trong bốn góc theo sức mạnh tương đối so với chỉ số (trục ngang) và động lượng của sức mạnh đó (trục dọc). Vệt đuôi nối các vị trí qua những tuần gần nhất. Vị trí trên hình phụ thuộc cách bạn tính hai chỉ số đầu vào; biểu đồ không đo dòng tiền. `Chart.rrg` chỉ vẽ; bạn tự tính hai chỉ số. Đoạn dưới dùng một cách tính đơn giản để minh hoạ: ```python rows = [] for t in TICKERS: rs = 100 * prices[t] / bench.reindex(prices.index) # sức mạnh thô so với chỉ số rs_ratio = 100 + (rs.rolling(10).mean() / rs.rolling(40).mean() - 1) * 100 rs_mom = 100 + (rs_ratio / rs_ratio.shift(5) - 1) * 100 wk = pd.DataFrame({"rs": rs_ratio, "rm": rs_mom}).resample("W").last().dropna().tail(8) wk["symbol"] = t rows.append(wk.reset_index(names="time")) fig, *axes = Chart.rrg(pd.concat(rows), symbol_col="symbol", time_col="time", rs_col="rs", rm_col="rm", tail_length=6, color_palette="vnstock_brand_cat", title=f"Biểu đồ xoay vòng tương đối so với {BENCH} (theo tuần)") ``` ![Biểu đồ xoay vòng tương đối của sáu mã so với VNINDEX, chia bốn góc tích luỹ, tăng giá, suy yếu, giảm giá](/images/docs/vnstock-chart/rrg.png) Với ngành thay vì mã, bạn thay `prices` bằng chỉ số ngành và giữ nguyên phần còn lại. Màu nền của bốn góc do thư viện cố định, không theo bảng màu bạn chọn. ## 11. Tóm tắt một mã trong một hình `Chart.summary_card` gom giá, mức thay đổi, tối đa sáu chỉ số và đường giá 30 phiên vào một thẻ, hữu ích khi cần đặt nhiều thông tin vào cùng một hình. Bạn tự định dạng các chỉ số; nhãn đánh giá (`signal`) cũng do bạn quyết định. Các chỉ số rủi ro đọc từ `stats` nên khớp với bảng ở mục 5. ```python last, prev = df["close"].iloc[-1], df["close"].iloc[-2] ta_full = Indicator(df) fig, ax = Chart.summary_card( ticker=MAIN, company_name="CTCP Tập đoàn Hòa Phát", current_price=last * 1000, # vnstock trả giá theo nghìn đồng price_change=(last - prev) * 1000, price_change_pct=(last / prev - 1) * 100, metrics={ "RSI(14)": vn(ta_full.momentum.rsi(length=14).iloc[-1], "{:.1f}"), "SMA50": vn(ta_full.trend.sma(length=50).iloc[-1], "{:.1f}"), "Biến động năm": vn(stats.loc[MAIN, "annual_volatility"], "{:.1%}"), "Sụt giảm tối đa": vn(stats.loc[MAIN, "max_drawdown"], "{:.1%}"), "KLGD TB 20 phiên": vn(df["volume"].tail(20).mean() / 1e6, "{:.1f}") + " triệu", "Beta": vn(stats.loc[MAIN, "beta"], "{:.2f}"), }, sparkline_data=df["close"].tail(30), signal="Trung tính", color_palette="vnstock_brand", font_name=["Lexend", "DejaVu Sans"], # Lexend không có ký tự ▲ ▼; DejaVu Sans vẽ thay ) ``` ![Thẻ tóm tắt của HPG gồm giá, mức thay đổi, đường giá 30 phiên và sáu chỉ số](/images/docs/vnstock-chart/summary_card.png) ## Đọc tiếp - [Các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do): chọn hàm theo dữ liệu bạn có. - [Tham chiếu hàm](/docs/vnstock-chart/tham-chieu-ham): đủ tham số và kiểu trả về của từng hàm. - [Chỉ báo kỹ thuật](/docs/vnstock_quant/tinh-toan/ta), [Đo lường rủi ro và hiệu suất](/docs/vnstock_quant/tinh-toan/risk), [Quản lý danh mục đầu tư](/docs/vnstock_quant/tinh-toan/portfolio): cách tính dữ liệu đầu vào bằng `vnstock_quant`. --- ## Document: Khác biệt với vnstock_ezchart

vnstock_chart và vnstock_ezchart là hai gói riêng. Sau khi cài gói mới, bạn cần đổi câu lệnh import. Cài lại gói cũ không tự chuyển mã sang gói mới.

## Hai gói khác nhau ở đâu? `vnstock_chart` kế tục `vnstock_ezchart` và được cài từ kho phát hành thư viện của Vnstock. Với người đã viết mã dùng gói cũ, thay đổi cần chú ý nhất là tên gói trong lệnh cài và câu lệnh `import`. | | `vnstock_ezchart` (cũ) | `vnstock_chart` (mới, thế hệ 5) | |---|---|---| | Nơi cài gói | PyPI | Kho phát hành của Vnstock (`--extra-index-url https://vnstocks.com/api/packages`) | | Bản mới nhất | 1.0.2, không cập nhật thêm | Tiếp tục nhận sửa lỗi, tính năng mới | | `vnstock` yêu cầu | `>=4.0.3` — dùng được cả thế hệ 4 lẫn 5 | `>=5.0` — chỉ nhắm thế hệ 5 | | Import | `from vnstock_ezchart import Chart` | `from vnstock_chart import Chart` | | Cài đặt | `pip install vnstock-ezchart` | `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart` | | Cách gọi hàm | `Chart.*` | Giữ các tên hàm `Chart.*` | ## Nếu bản cũ báo lỗi khi import Các bản `vnstock_ezchart` 1.0.1 và 1.0.2 có thể báo `ModuleNotFoundError` khi import sau khi cài bằng `pip`: gói phát hành thiếu thư mục `static` và `core`. Lỗi đóng gói này đã được sửa trong `vnstock_chart`. Nếu gặp lỗi, cài gói mới và đổi `import` theo các bước dưới đây. ## Chuyển từ `vnstock_ezchart` sang `vnstock_chart` 1. Cài bản mới: ```bash pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart ``` 2. Đổi mọi `import`: ```diff - from vnstock_ezchart import Chart + from vnstock_chart import Chart ``` 3. Nếu không còn dùng gói cũ trong môi trường này, bạn có thể gỡ nó: ```bash pip uninstall vnstock_ezchart ``` Sau khi đổi tên gói, chạy lại những biểu đồ đang dùng để kiểm tra dữ liệu đầu vào và kết quả hiển thị. ## Nếu bạn không dùng vnstock thế hệ 5 `vnstock_chart` yêu cầu `vnstock>=5.0`. Nếu dự án của bạn vẫn dùng `vnstock` 3.x hoặc 4.x, hãy kiểm tra khả năng nâng cấp `vnstock` trước khi chuyển thư viện biểu đồ. --- ## Document: Lịch sử phiên bản Nhãn **[Mở rộng]** đánh dấu phần chỉ có ở bản Mở rộng, nhãn **[Cộng đồng]** đánh dấu phần chỉ đúng với bản Cộng đồng. Phần không gắn nhãn đúng ở cả hai bản. Trang tổng hợp của từng bản lấy thay đổi từ tệp này theo nhãn. ## 18-10-2026 (v1.0.0) ### Phát hành dưới tên vnstock_chart - **Đổi tên**: `vnstock_ezchart` thành `vnstock_chart`. Hai gói được cài riêng; nếu đang dùng gói cũ, xem [cách chuyển sang vnstock_chart](/docs/vnstock-chart/khac-biet-voi-ezchart). - **Kênh phát hành**: Cài từ kho phát hành thư viện của Vnstock bằng `pip install --extra-index-url https://vnstocks.com/api/packages vnstock-chart`. - **Phụ thuộc**: Yêu cầu `vnstock>=5.0`. `squarify` (cho `treemap()`) và `wordcloud` là phụ thuộc tuỳ chọn, cài bằng `vnstock-chart[all]`; thiếu chúng thì các hàm còn lại vẫn chạy. - **Sửa lỗi đóng gói**: Bản cài qua `pip install` có đủ mọi thư mục con, không còn lỗi `ModuleNotFoundError` mà `vnstock_ezchart` 1.0.1 và 1.0.2 gặp. --- ## Document: Tham chiếu hàm Trang này giúp bạn tra tên tham số, giá trị mặc định và kết quả trả về khi viết mã với `vnstock_chart` 1.0.0. Nếu chưa biết nên dùng hàm nào, hãy xem [Các loại biểu đồ](/docs/vnstock-chart/cac-loai-bieu-do) trước. ## Tham số dùng chung Các hàm `bar`, `hist`, `line`, `scatter` và `boxplot` dùng chung nhiều tham số trình bày qua `**kwargs`. Bảng dưới liệt kê các tham số của `apply_chart_style`; phần riêng của từng hàm được ghi ở các mục sau. | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `title` | `str` | `None` | Tiêu đề biểu đồ | | `title_fontsize` | `int` | `14` (hiển thị `16` nếu không đặt) | Cỡ chữ tiêu đề | | `xlabel` | `str` | `None` | Nhãn trục X | | `ylabel` | `str` | `None` | Nhãn trục Y | | `grid` | `bool` | `None` (coi như `False`) | Hiện lưới | | `grid_axis` | `str` | `'both'` | Trục hiện lưới: `'both'`, `'x'`, `'y'` | | `data_labels` | `bool` | `None` | Hiện số trên mỗi cột/điểm | | `data_label_format` | `str` | `'1K'` | Định dạng số viết tắt: `'1K'`, `'1M'`, `'1B'`, `'1T'` | | `data_label_position` | `str` | `'outside'` | Vị trí nhãn số: `'outside'` hoặc `'center'` | | `data_label_color` | `str` | `'#475569'` | Màu chữ nhãn số | | `data_label_fontsize` | `int` | `10` | Cỡ chữ nhãn số | | `label_fontsize` | `int` | `None` (hiển thị `12` nếu không đặt) | Cỡ chữ nhãn trục X/Y | | `legend_title` | `str` | `None` | Tiêu đề chú giải | | `show_legend` | `bool` | `None` (coi như `False`) | Hiện chú giải. Bản 1.0.0 ẩn chú giải nếu bạn không truyền tham số này, nên với biểu đồ nhiều dải dữ liệu hãy truyền `show_legend=True` | | `legend_fontsize` | `int` | `None` | Cỡ chữ chú giải | | `series_names` | `list[str]` | `None` | Tên tuỳ chỉnh cho từng dải dữ liệu, hiện trong chú giải | | `font_name` | `str` | `None` | Font chữ, ví dụ `'Inter'` | | `figsize` | `tuple[float, float]` | `None` | Kích thước hình, ví dụ `(10, 6)` | | `show_xaxis` | `bool` | `True` | Hiện trục X. Đặt `False` để ẩn | | `show_yaxis` | `bool` | `True` | Hiện trục Y. Đặt `False` để ẩn luôn viền trái | | `tick_labelsize` | `int` | `None` (hiển thị `10` nếu không đặt) | Cỡ chữ số trên trục | | `xtick_format` | `str` | `None` | Định dạng số trên trục X, ví dụ `'{:.0f}'` | | `ytick_format` | `str` | `None` | Định dạng số trên trục Y, ví dụ `'{:.0%}'` | | `tick_rotation` | `int` | `None` | Góc xoay nhãn trục (áp cho trục X). Giá trị `0` bị bỏ qua; muốn nhãn nằm ngang ở `bar`, truyền `rot=0` | | `xlim` | `tuple[float, float]` | `None` | Giới hạn trục X | | `ylim` | `tuple[float, float]` | `None` | Giới hạn trục Y | | `background_color` | `str` | `None` (mặc định `'#ffffff'`) | Màu nền biểu đồ | | `bar_edge_color` | `str` | `None` (mặc định `'#ffffff'`) | Màu viền cột (nếu biểu đồ có cột) | Ba tham số điều khiển riêng, không thuộc `apply_chart_style`, nhận ở hầu hết các hàm qua `**kwargs`: | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `color_palette` | `str \| list[str]` | theme hiện tại (`'vnstock'` nếu chưa gọi `set_theme`) | Tên bảng màu có sẵn hoặc danh sách màu hex tự chọn — xem [Bảng màu](#bảng-màu) | | `palette_shuffle` | `bool` | `False` | Xáo trộn thứ tự màu trong bảng | | `show` | `bool` | `True` (`False` ở `table`) | Gọi `plt.show()` sau khi vẽ. Đặt `False` khi chạy không có màn hình (script, server) | | `ax` | `matplotlib.axes.Axes` | `None` | Vẽ lên trục có sẵn thay vì tạo hình mới — dùng khi tự ghép nhiều biểu đồ. Có ở `bar`, `hist`, `line`, `scatter`, `boxplot` | Chỉ một số hàm nhận `savefig`; mục của từng hàm ghi rõ điều đó. Tham số này nhận đường dẫn (`str`) hoặc `dict` tuỳ chọn cho `plt.savefig()`, chẳng hạn `{'fname': 'chart.png', 'dpi': 150, 'bbox_inches': 'tight'}`. Với hàm không nhận `savefig`, hãy lưu hình từ kết quả trả về bằng `fig.savefig(...)`. ## Bảng màu Gọi bằng tên (`color_palette='vnstock'`) hoặc tự truyền một danh sách màu hex. Liệt kê đủ bằng `Utils.brand_palettes.keys()`: | Tên | Số màu | Thứ tự ngữ nghĩa | |---|---|---| | `vnstock` | 6 | Mặc định của thương hiệu | | `percentage` | 6 | Thang màu cho tỉ lệ phần trăm | | `amount` | 10 | Thang xanh nhạt → đậm, cho giá trị tăng dần | | `category` | 10 | Màu tương phản cao, phân loại nhiều nhóm | | `trend` | 11 | Màu cho biểu đồ xu hướng nhiều dải | | `stock` | 4 | Vị trí 0: tăng, 1: giảm, 2: trần, 3: sàn | | `flatui` | 6 | Bảng màu phẳng chung | | `learn_anything` | 4 | Bảng màu tương phản mạnh | | `beach`, `forest` | 5 | Hai bảng màu theo chủ đề | | `academic` | 7 | Thứ tự ngữ nghĩa: 0 tích cực, 1 chính, 2 phụ, 3 tiêu cực — phù hợp báo cáo khoa học | | `minimal` | 6 | Bảng màu trung tính kiểu Nord/Slate | ## Thiết lập chung ### `Chart.set_theme(theme_name='vnstock', logo_path=, font_name=None, lang='vi')` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `theme_name` | `str` | `'vnstock'` | Tên bảng màu áp cho mọi biểu đồ sau đó | | `logo_path` | `str \| None` | logo Vnstock có sẵn trong gói | Đường dẫn hay URL logo chèn vào biểu đồ. Đặt `None` để **tắt hẳn logo** | | `font_name` | `str \| None` | `None` (tự dùng font Inter nhúng sẵn nếu có) | Font chữ áp cho mọi biểu đồ | | `lang` | `str` | `'vi'` | Ngôn ngữ nhãn tự sinh (`'vi'` hoặc `'en'`) — ảnh hưởng `summary_card`, nhãn khối lượng/giá của `candle`/`backtest` | Gọi một lần khi bắt đầu script; không cần gọi lại cho từng biểu đồ. ### `Chart.add_logo(fig, logo_path=, position=(0.44, 0.02, 0.12, 0.06), adjust_bottom=0.18)` Tự gọi bên trong mọi hàm vẽ (qua `_inject_logo`) theo `logo_path` đã đặt ở `set_theme`; gọi tay khi cần chèn logo lên một `fig` tự tạo riêng. | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `fig` | `matplotlib.figure.Figure` | bắt buộc | Hình cần chèn logo | | `logo_path` | `str` | logo Vnstock | Đường dẫn cục bộ hoặc URL (bắt đầu bằng `http` thì tải qua mạng) | | `position` | `tuple[float, float, float, float]` | `(0.44, 0.02, 0.12, 0.06)` | Khung logo `(trái, dưới, rộng, cao)` theo tỉ lệ hình, 0–1 | | `adjust_bottom` | `float` | `0.18` | Chừa khoảng trống phía dưới để logo không chồng lên biểu đồ | ### `chart_instance.help(method_path)` In tài liệu của một hàm theo tên bằng `Chart().help('candle')` hoặc `Chart().help('Chart.candle')`. ## Xu hướng và số lượng (`bar`, `hist`, `line`, `scatter`) Bốn hàm này dùng chung nhiều tham số trình bày trong [bảng ở trên](#tham-số-dùng-chung). Cách chuẩn bị dữ liệu đầu vào khác nhau theo loại biểu đồ. | Hàm | Tham số dữ liệu | |---|---| | `Chart.bar(data, **kwargs)` | `data`: `DataFrame` hoặc `Series` | | `Chart.hist(data, **kwargs)` | `data`: `DataFrame` hoặc `Series` | | `Chart.line(data, **kwargs)` | `data`: `DataFrame` hoặc `Series`, chỉ mục thời gian (datetime index) | | `Chart.scatter(data, x, y, **kwargs)` | `data`: `DataFrame`; `x`, `y` (`str`, bắt buộc): tên cột trục X, Y | Các hàm `bar`, `hist`, `line` và `scatter` nhận `ax` nếu bạn muốn vẽ lên trục đã tạo. `Chart.timeseries(data, **kwargs)` và `Chart.combo_chart(bar_data, line_data, **kwargs)` vẫn gọi được nhưng đã **lỗi thời** (`DeprecationWarning`) — dùng `line`/`combo`. ## `Chart.pie(data, labels, **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.Series` | bắt buộc | Giá trị từng phần. Bản 1.0.0 báo `AttributeError` nếu truyền `list` hay mảng NumPy, nên hãy đổi sang `pd.Series` trước | | `labels` | `list` | bắt buộc | Nhãn từng phần | | `title` | `str` | — | Tiêu đề | | `color_palette` | `str \| list[str]` | theme hiện tại | Bảng màu | | `palette_shuffle` | `bool` | `False` | Xáo trộn màu | | `legend_title` | `str` | — | Tiêu đề chú giải | | `series_names` | `list` | — | Tên tuỳ chỉnh cho chú giải | | `figsize` | `tuple` | — | Kích thước hình | | `font_name` | `str` | — | Font chữ | | `show_legend` | `bool` | `True` | Hiện chú giải | | `title_fontsize` | `int` | — | Cỡ chữ tiêu đề | | `legend_fontsize` | `int` | — | Cỡ chữ chú giải | | `show` | `bool` | `True` | Gọi `plt.show()` | Không nhận `savefig`. ## `Chart.boxplot(data, **kwargs)` Dữ liệu `data: DataFrame`; tham số tạo kiểu giống [bảng dùng chung](#tham-số-dùng-chung) (có `ax`). ## `Chart.pairplot(data, **kwargs)` | Tham số | Kiểu | Ý nghĩa | |---|---|---| | `data` | `pd.DataFrame` | Dữ liệu nhiều cột để vẽ đồ thị phân tán theo từng cặp biến | | `**kwargs` | — | Chuyển thẳng cho `seaborn.pairplot()` — xem [tài liệu seaborn](https://seaborn.pydata.org/generated/seaborn.pairplot.html) cho đủ tham số (`hue`, `vars`, `kind`, `diag_kind`…) | Trả về đối tượng `seaborn.PairGrid` (không phải `(fig, ax)` như các hàm khác) — lấy hình bằng `g.figure`. ## `Chart.combo(bar_data, line_data, left_ylabel='Bar Data', right_ylabel='Line Data', **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `bar_data` | `pd.Series \| pd.DataFrame` | bắt buộc | Dữ liệu vẽ dạng cột (trục Y bên trái) | | `line_data` | `pd.Series \| pd.DataFrame` | bắt buộc | Dữ liệu vẽ dạng đường (trục Y bên phải) | | `left_ylabel` | `str` | `'Bar Data'` | Nhãn trục Y trái | | `right_ylabel` | `str` | `'Line Data'` | Nhãn trục Y phải | | `color_palette` | `str \| list[str]` | theme hiện tại | Lấy màu cột từ vị trí 0, màu đường từ vị trí 2 (hoặc 1 nếu palette tự truyền chỉ có 2 màu) | | `palette_shuffle` | `bool` | `False` | Xáo trộn màu trước khi lấy | | `title`, `xlabel`, `grid`, `data_labels`, `data_label_format`, `legend_title`, `series_names`, `font_name`, `show_legend`, `show_xaxis`, `show_yaxis`, `title_fontsize`, `label_fontsize`, `tick_labelsize`, `legend_fontsize`, `xtick_format`, `ytick_format`, `figsize`, `xlim`, `ylim`, `tick_rotation`, `background_color`, `bar_edge_color` | — | — | Giống [bảng dùng chung](#tham-số-dùng-chung) — `ylabel` không áp dụng, dùng `left_ylabel`/`right_ylabel` | | `show` | `bool` | `True` | Gọi `plt.show()` | Trả về `(fig, ax1, ax2)` — hai trục Y, không phải `(fig, ax)`. ## Biểu đồ nến (`candle`, `backtest`) ### `Chart.candle(data, title='', figsize=(12, 8), volume=True, overlays=None, subplots=None, **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.DataFrame` | bắt buộc | Cột `open/high/low/close` (không phân biệt hoa thường), `volume` tuỳ chọn; chỉ mục thời gian hoặc có cột `time`/`date` | | `title` | `str` | `''` | Tiêu đề | | `figsize` | `tuple[float, float]` | `(12, 8)` | Kích thước hình | | `volume` | `bool` | `True` | Vẽ thêm khung khối lượng | | `overlays` | `list` | `None` | Đường chồng lên khung giá — mỗi phần tử là một `Series`, hoặc `dict` `{'data': Series, 'type': 'line', 'color': None, 'alpha': 0.8, 'width': 1.0}` | | `subplots` | `list` | `None` | Thêm khung phụ dưới khung giá (RSI, MACD…) — mỗi phần tử là một `Series`/`dict` như `overlays`, hoặc một **danh sách** các `dict` để nhiều đường chung một khung; `dict` nhận thêm `secondary_y` (`bool`) và `ylabel` (`str`) | | `color_palette` | `str` | theme hiện tại | **Chỉ nhận tên bảng màu có sẵn** — truyền một danh sách màu hex vào đây sẽ lỗi `TypeError` (khác `bar`/`line`/`combo`…). Màu nến tăng lấy từ vị trí 0, màu giảm từ vị trí 3 | | `font_name` | `str` | font hiện tại của matplotlib | Font cho tiêu đề | | `show` | `bool` | `True` | Gọi `plt.show()` | | `**kwargs` khác | — | — | Chuyển thẳng cho `mplfinance.plot()` — xem [tài liệu mplfinance](https://github.com/matplotlib/mplfinance) cho đủ tham số (`type`, `mav`, `tight_layout`…) | Không nhận `savefig`; tự `fig.savefig(...)` trên kết quả `(fig, axes)`. ### `Chart.backtest(data, trades=None, portfolio=None, title='Backtest Results', figsize=(14, 10), volume=True, overlays=None, **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.DataFrame` | bắt buộc | Giá OHLC(V), như `candle` | | `trades` | `pd.DataFrame \| list[dict] \| np.ndarray \| None` | `None` | Lệnh đã khớp. Cần nhận diện được cột thời gian (`time`/`date`/`trade_date`), loại lệnh (`type`/`trade_type`/`side`, giá trị `'MUA'`/`'BUY'`/`'LONG'`/`'1'` là mua, `'BAN'`/`'SELL'`/`'SHORT'`/`'-1'` là bán), giá khớp (`price`/`exec_price`) | | `portfolio` | `pd.DataFrame \| None` | `None` | Hiệu suất danh mục theo thời gian. Cần cột equity (`equity`/`portfolio_value`/`capital`/`cumulative_return`/`return`) và/hoặc drawdown (`drawdown`/`dd`) | | `title` | `str` | `'Backtest Results'` | Tiêu đề | | `figsize` | `tuple` | `(14, 10)` | Kích thước hình | | `volume` | `bool` | `True` | Vẽ khung khối lượng | | `overlays` | `list` | `None` | Giống `candle` | | `color_palette` | `str` | theme hiện tại | **Chỉ nhận tên bảng màu có sẵn** (truyền list sẽ lỗi `TypeError`). Màu nến, điểm mua/bán, đường vốn, drawdown lấy từ các vị trí 0/3/1/3 | | `font_name` | `str` | font hiện tại | Font tiêu đề | | `show` | `bool` | `True` | Gọi `plt.show()` | | `savefig` | `str \| dict \| None` | `None` | Có nhận — lưu ảnh ngay trong hàm, không cần tự `fig.savefig()` | | `**kwargs` khác | — | — | Chuyển cho `mplfinance.plot()` | Số khung tự tăng theo dữ liệu có: luôn có khung giá; thêm khung khối lượng nếu `volume=True`; thêm khung vốn nếu `portfolio` có cột equity; thêm khung drawdown nếu `portfolio` có cột drawdown. ## `Chart.equity_curve(data, benchmark=None, title='Equity Curve & Drawdown', figsize=(10, 6), **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.Series \| pd.DataFrame` | bắt buộc | Đường vốn tích luỹ (lấy cột đầu nếu là DataFrame) | | `benchmark` | `pd.Series \| pd.DataFrame \| None` | `None` | Đường vốn tích luỹ của benchmark, vẽ chồng để so sánh | | `title` | `str` | `'Equity Curve & Drawdown'` | Tiêu đề | | `figsize` | `tuple` | `(10, 6)` | Kích thước hình | | `color_palette` | `str` | theme hiện tại | **Chỉ nhận tên bảng màu có sẵn** (truyền list sẽ lỗi `TypeError`). Màu đường vốn, benchmark, drawdown lấy từ vị trí 0/1/3 | | Tham số tạo kiểu khác | — | — | Chuyển thẳng cho `apply_chart_style` của khung drawdown (khung vốn đã cố định `show_xaxis=False`, `show_legend=True`, `ylabel='Cumulative Return'` — đừng truyền lại ba tham số này) | Trả về `(fig, ax1, ax2)`: `ax1` là đường vốn, `ax2` là drawdown (đơn vị `%`). ## `Chart.returns_heatmap(data, title='Monthly Returns Heatmap', figsize=(10, 5), **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.Series \| pd.DataFrame` | bắt buộc | Lợi suất theo ngày hoặc theo tháng (tự gộp lên tháng nếu phát hiện dữ liệu ngày) | | `title` | `str` | `'Monthly Returns Heatmap'` | Tiêu đề | | `figsize` | `tuple` | `(10, 5)` | Kích thước hình | | `color_palette` | `str` | theme hiện tại | **Chỉ nhận tên bảng màu có sẵn** (truyền list sẽ lỗi `TypeError`). Màu dương lấy từ vị trí 0, màu âm từ vị trí 3, nội suy qua trắng ở 0% | | `**kwargs` khác | — | — | Chuyển cho `Chart.heatmap` (và từ đó cho `seaborn.heatmap`) | ## `Chart.heatmap(data, **kwargs)` | Tham số | Kiểu | Ý nghĩa | |---|---|---| | `data` | `pd.DataFrame` | Ma trận giá trị, ví dụ `df.corr()` | | `title`, `font_name`, `figsize`, `xlim`, `ylim`, `title_fontsize`, `background_color` | — | Giống [bảng dùng chung](#tham-số-dùng-chung) — **chỉ bảy tham số này** có hiệu lực ở `heatmap`, các tham số khác (`data_labels`, `grid`…) không áp dụng | | `color_palette`, `palette_shuffle` | — | Giống bảng dùng chung | | `show` | `bool` | Gọi `plt.show()`, mặc định `True` | | `**kwargs` khác | — | Chuyển cho `seaborn.heatmap()` — ví dụ `annot=True`, `fmt='.1%'`, `cmap=...`, `center=0`, `linewidths=1`, `linecolor='white'`, `cbar_kws={...}`, `annot_kws={...}` | ## Biểu đồ chuyên biệt ### `Chart.treemap(values, labels, title='', color_palette='vnstock', palette_shuffle=False, figsize=(10, 8), title_fontsize=14, **kwargs)` Cần `pip install "vnstock-chart[all]"` (gói `squarify`). | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `values` | `list \| pd.Series` | bắt buộc | Giá trị từng ô, quyết định diện tích | | `labels` | `list` | bắt buộc | Nhãn từng ô | | `title` | `str` | `''` | Tiêu đề | | `color_palette` | `str` | `'vnstock'` | **Chỉ nhận tên bảng màu có sẵn** (không nhận list màu tự do như các hàm khác) | | `palette_shuffle` | `bool` | `False` | Xáo trộn màu | | `figsize` | `tuple` | `(10, 8)` | Kích thước hình | | `title_fontsize` | `int` | `14` (hiển thị `16` nếu không đặt) | Cỡ chữ tiêu đề | | `fontsize` | `int` | `10` | Cỡ chữ bên trong mỗi ô (qua `**kwargs`, chuyển cho `squarify`) | | `font_name` | `str` | — | Font chữ tiêu đề | ### `Chart.wordcloud(text, title='Word Cloud', color_palette='vnstock', palette_shuffle=False, max_words=100, width=800, height=400, figsize=(10, 8), fontname=None, savefig=None, show=True)` Cần `pip install "vnstock-chart[all]"` (gói `wordcloud`). | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `text` | `str` | bắt buộc | Văn bản nguồn | | `title` | `str` | `'Word Cloud'` | Tiêu đề | | `color_palette` | `str` | `'vnstock'` | **Chỉ nhận tên bảng màu có sẵn**, lấy trực tiếp bằng `brand_palettes[color_palette]` — tên sai báo `KeyError`, không có bảng dự phòng như các hàm khác | | `palette_shuffle` | `bool` | `False` | Xáo trộn màu | | `max_words` | `int` | `100` | Số từ tối đa hiển thị | | `width` | `int` | `800` | Chiều rộng ảnh word cloud (pixel) | | `height` | `int` | `400` | Chiều cao ảnh word cloud (pixel) | | `figsize` | `tuple` | `(10, 8)` | Kích thước hình matplotlib | | `fontname` | `str \| None` | `None` | **Chú ý tên tham số là `fontname`, không phải `font_name`** như các hàm khác | | `savefig` | `str \| dict \| None` | `None` | Lưu ảnh ngay trong hàm | | `show` | `bool` | `True` | Gọi `plt.show()` | Tự tìm font Inter nhúng sẵn trong gói nếu có; nếu không, dùng font hệ thống. ### `Chart.table(data, columns=None, title='', title_loc='left', header=True, colWidths=None, rowLoc='right', colLoc='right', colLabels=None, edges='horizontal', orient='horizontal', figsize=(5.5, 6), savefig=None, show=False)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.DataFrame` | bắt buộc | Dữ liệu hiển thị (giá trị thô qua `.values`, không định dạng thêm) | | `columns` | `list \| None` | `None` | Đổi tên cột trước khi vẽ (`data.columns = columns`) | | `title` | `str` | `''` | Tiêu đề | | `title_loc` | `str` | `'left'` | Vị trí tiêu đề: `'left'`, `'center'`, `'right'` | | `header` | `bool` | `True` | Hiện dòng tiêu đề cột | | `colWidths` | `list \| None` | `None` | Độ rộng từng cột | | `rowLoc` | `str` | `'right'` | Căn lề dữ liệu theo hàng | | `colLoc` | `str` | `'right'` | Căn lề dữ liệu theo cột | | `colLabels` | `list \| None` | `None` | Tên cột hiển thị khi `header=False` cần nhãn riêng | | `edges` | `str` | `'horizontal'` | Kiểu viền ô: `'horizontal'`, `'vertical'`, `'open'`, `'closed'`… (theo `matplotlib.table`) | | `orient` | `str` | `'horizontal'` | Hướng bảng (giữ để tương thích, chưa ảnh hưởng cách vẽ) | | `figsize` | `tuple` | `(5.5, 6)` | Kích thước hình | | `savefig` | `str \| dict \| None` | `None` | Lưu ảnh ngay trong hàm | | `show` | `bool` | `False` | Gọi `plt.show()` — **mặc định tắt**, khác mọi hàm khác | Không có tham số `color_palette` — luôn lấy màu từ theme toàn cục (`set_theme`), không đổi được theo từng lần gọi. Trả về chỉ `fig` (không phải `(fig, ax)`). ### `Chart.summary_card(ticker, company_name, current_price, price_change, price_change_pct, metrics, sparkline_data, signal, **kwargs)` Cả tám tham số nêu trong chữ ký hàm đều **bắt buộc**, không có giá trị mặc định. | Tham số | Kiểu | Ý nghĩa | |---|---|---| | `ticker` | `str` | Mã cổ phiếu, hiện lớn ở góc trái | | `company_name` | `str` | Tên công ty; tự cắt và thêm `...` nếu dài hơn 45 ký tự | | `current_price` | `float` | Giá hiện tại, hiện kèm đơn vị `₫` | | `price_change` | `float` | Thay đổi tuyệt đối (quyết định mũi tên lên/xuống và màu) | | `price_change_pct` | `float` | Thay đổi theo %, đơn vị phần trăm thật (ví dụ `1.5` = 1,5%) | | `metrics` | `dict` | Tối đa 6 cặp khoá/giá trị hiển thị dạng lưới 2×3; khoá là nhãn, giá trị chuyển thẳng sang chuỗi hiển thị | | `sparkline_data` | `pd.Series` | Dữ liệu vẽ đường nhỏ xu hướng (thường 30 phiên gần nhất) | | `signal` | `str` | Một trong `'Tích cực'`, `'Tiêu cực'`, `'Trung tính'` (hay `'Positive'`/`'Negative'`/`'Neutral'`) — quyết định màu và chữ trên nhãn đánh giá; giá trị khác vẫn hiện nguyên văn, màu xám | | `color_palette` (qua `**kwargs`) | `str` | **Chỉ nhận tên bảng màu có sẵn** (truyền list sẽ lỗi `TypeError`). Màu tích cực/tiêu cực/phụ lấy từ vị trí 0/3/2 | | `font_name` (qua `**kwargs`) | `str` | Mặc định `'Inter'` | | `figsize` (qua `**kwargs`) | `tuple` | Mặc định `(9, 5)` | | `lang` (qua `**kwargs`) | `str` | `'vi'` hoặc `'en'` — đổi nhãn "Đánh giá"/"Xu hướng 30 ngày" và chữ trên nhãn đánh giá sang tiếng Anh | Không nhận `savefig`/`show` — tự `fig.savefig(...)` trên kết quả trả về `(fig, ax)`. ### `Chart.rrg(data, symbol_col='industry_name', time_col='time', rs_col='rs_standard_term', rm_col='rm_standard_term', tail_length=5, origin=100.0, title='Relative Rotation Graph (RRG)', figsize=(10, 10), **kwargs)` | Tham số | Kiểu | Mặc định | Ý nghĩa | |---|---|---|---| | `data` | `pd.DataFrame` | bắt buộc | Một dòng mỗi (mã, thời điểm) | | `symbol_col` | `str` | `'industry_name'` | Tên cột chứa mã/tên nhóm so sánh | | `time_col` | `str` | `'time'` | Tên cột thời gian | | `rs_col` | `str` | `'rs_standard_term'` | Tên cột sức mạnh tương đối (trục X) | | `rm_col` | `str` | `'rm_standard_term'` | Tên cột động lượng tương đối (trục Y) | | `tail_length` | `int` | `5` | Số điểm lịch sử vẽ vệt đuôi cho mỗi mã | | `origin` | `float` | `100.0` | Tâm biểu đồ (giao hai trục); tự chuyển về `0.0` nếu phát hiện dữ liệu đã chuẩn hoá quanh 0 | | `title` | `str` | `'Relative Rotation Graph (RRG)'` | Tiêu đề | | `figsize` | `tuple` | `(10, 10)` | Kích thước hình | | `color_palette` | `str` | theme hiện tại | **Chỉ nhận tên bảng màu có sẵn** (truyền list sẽ lỗi `TypeError`). Màu từng mã; nếu số mã nhiều hơn số màu trong bảng, tự chuyển sang colormap `'tab20'` | | `font_name` | `str` | font hiện tại | Font nhãn góc phần tư, tên mã | | `savefig` | `str \| dict \| None` | `None` | Lưu ảnh ngay trong hàm | | `show` | `bool` | `True` | Gọi `plt.show()` | Cần `scipy` để vẽ vệt đuôi mượt (dùng nội suy spline); không có `scipy` thì tự lùi về vẽ đường thẳng nối các điểm, không lỗi. ## `Utils` — tiện ích màu, font Dùng qua `from vnstock_chart.utils import Utils` hoặc `from vnstock_chart import Utils`. | Hàm | Tham số | Ý nghĩa | |---|---|---| | `Utils.apply_palette(color_palette, palette_shuffle=False)` | `color_palette` (`str \| list[str]`), `palette_shuffle` (`bool`) | Áp bảng màu cho ngữ cảnh matplotlib/seaborn hiện tại. Tự gọi bên trong mọi hàm `Chart.*` | | `Utils.readable_format(num, fmt=None)` | `num` (`int \| float`), `fmt` (`str`, tuỳ chọn) | Đổi số lớn thành chuỗi gọn (`1500` → `'1.5K'`). Nếu `fmt` có dấu `%`, giữ số gốc không chia tỉ lệ | | `Utils.list_font()` | — | Trả về `pd.Series` liệt kê mọi font matplotlib đang nhận ra — tiện kiểm trên Colab | | `Utils.download_font(font_family)` | `font_family` (`str`) | Tải một font từ Google Fonts theo đúng tên hiển thị trên đó, đăng ký vào matplotlib | | `Utils.set_font(font_family)` | `font_family` (`str`) | Đặt font toàn cục ngay (không qua `set_theme`) | | `Utils.list_cmap()` | — | Trả về `pd.Series` liệt kê colormap matplotlib có sẵn | | `Utils.create_cmap(color_palette, cmap_name='custom')` | `color_palette` (`str \| list[str]`), `cmap_name` (`str`) | Dựng một `LinearSegmentedColormap` từ bảng màu — dùng cho `cmap=` của `heatmap`/`returns_heatmap` | | `Utils.brand_palettes` | — | `dict` chứa toàn bộ bảng màu, xem [Bảng màu](#bảng-màu) | ## Khi dùng trong chương trình tự động - Kiểm tra kiểu trả về của hàm trước khi tách `fig` và các trục; riêng `table` chỉ trả về `fig`. Khi chạy không có màn hình, đặt `show=False` nếu hàm hỗ trợ rồi gọi `fig.savefig(path, dpi=150, bbox_inches='tight')` nếu bạn cần lưu hình. - Có thể tra docstring ngay trong Python bằng `help(Chart.candle)` hoặc `Chart().help('candle')`. - `color_palette` nhận danh sách màu hex ở `bar`, `hist`, `line`, `scatter`, `boxplot`, `pie`, `heatmap` và `combo`. Với `candle`, `backtest`, `equity_curve`, `returns_heatmap`, `summary_card`, `rrg`, `treemap` và `wordcloud`, hãy dùng tên bảng màu có sẵn. `table` không nhận tham số này. - Hãy dùng đúng tên tham số trong bảng. Một số hàm nhận `**kwargs` nên tham số gõ sai có thể bị bỏ qua hoặc gây lỗi ở thư viện vẽ bên dưới. --- ## Document: Cài đặt và Kết nối > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Nếu bạn chưa cài đặt môi trường lập trình hoặc chưa từng cấu hình MCP trước đây, hãy tham khảo Agent Guide để Trợ lý AI hỗ trợ bạn thiết lập môi trường từng bước thuận tiện.



## Tổng quan Trang này hướng dẫn bạn cài đặt `vnstock-mcp` và cấu hình cầu nối cục bộ vào các ứng dụng Trợ lý AI như **Claude Code**, **Codex**, **Antigravity**, **VS Code**, **Cursor**, **Claude Desktop**, **ChatGPT desktop** và **Gemini Tasks**. Khác với việc đăng nhập vào một dịch vụ MCP trực tuyến phát qua máy chủ từ xa, cấu hình dưới đây chỉ định cho ứng dụng AI khởi chạy trực tiếp tiến trình `vnstock-mcp` từ môi trường Python trên máy cá nhân của bạn. Tiến trình này sẽ gọi bộ thư viện Vnstock đã cài trên máy và lưu trữ phiên làm việc trong không gian nghiên cứu cục bộ (`~/vnstock_research`). Cách nhanh nhất là chạy lệnh `vnstock-mcp --setup`: thư viện tự lấy đúng đường dẫn trên máy của bạn và ghi cấu hình giúp khi thêm cờ `--write`. --- ## Yêu cầu môi trường - **Hệ điều hành**: macOS (Apple Silicon hoặc Intel), Linux x86_64, hoặc Windows 10/11 64-bit. - **Python**: Phiên bản **>= 3.10** (khuyên dùng Python 3.11 hoặc 3.12 trong môi trường ảo `.venv`). - **Bộ thư viện công cụ trên máy**: Cài đặt `vnstock` (v5.x) cùng các thư viện bạn cần gọi qua MCP như `vnstock_quant` (v0.3.x). --- ## Cài đặt thư viện

Tuyệt đối không cài đặt vào môi trường global (system Python) trên Windows vì hệ điều hành sẽ không nhận diện được lệnh CLI vnstock-mcp. Hãy luôn đảm bảo bạn đã tạo và kích hoạt môi trường ảo .venv trước khi chạy lệnh cài đặt dưới đây.

Bạn có thể cài đặt `vnstock-mcp` từ kho phân phối gói chính thức: ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock vnstock-mcp ``` Sau khi cài đặt, kiểm tra đường dẫn thực thi của tệp dòng lệnh: ```bash which vnstock-mcp # Đầu ra mẫu trên macOS/Linux: /Users//.venv/bin/vnstock-mcp # Đầu ra mẫu trên Windows (lệnh 'where'): C:\Users\\.venv\Scripts\vnstock-mcp.exe ``` --- ## Chẩn đoán trạng thái hệ thống Trước khi kết nối vào Trợ lý AI, chạy công cụ chẩn đoán tích hợp sẵn để kiểm tra Python, thư viện, thư mục nghiên cứu, số công cụ theo từng hồ sơ và một lần gọi dữ liệu thử: ```bash vnstock-mcp --doctor ```
Xem kết quả chẩn đoán mẫu ```text [OK ] Python 3.11.14 (cần >= 3.10) [OK ] vnstock 5.0.0 (thế hệ 5) [OK ] vnstock_quant 0.2.1: cấp golden, mở ta_basic, ta, fa_basic, fa, fa_advanced, risk, portfolio [INFO] Tài khoản vnstock: chạy `vnstock status` để xem cấp và hạn mức; `vnstock login` nếu chưa đăng nhập. [OK ] Thư mục nghiên cứu ghi được: ~/vnstock_research (nhật ký bật) [INFO] hồ sơ minimal : 13 tool, schema ≈ 4,042 token [OK ] hồ sơ research: 29 tool, schema ≈ 7,464 token ← đang dùng [INFO] hồ sơ data : 32 tool, schema ≈ 7,299 token [INFO] hồ sơ full : 39 tool, schema ≈ 9,630 token [OK ] Gọi dữ liệu thật Market().equity('FPT').ohlcv: 5 dòng, 0.7s Cấu hình cho ứng dụng AI trên máy (chi tiết: vnstock-mcp --setup): Command : ~/.venv/bin/vnstock-mcp Sandbox — đọc/ghi : ~/.vnstock, ~/vnstock_research Cần truy cập mạng (Internet) để lấy dữ liệu. Môi trường sẵn sàng. ``` Số công cụ trong mẫu là của một tài khoản có gói quyền sử dụng cấp Golden. Với tài khoản khác, con số theo đúng cấp của bạn.
--- ## Thiết lập nhanh bằng `vnstock-mcp --setup` Cách nhanh nhất để thêm `vnstock-mcp` vào ứng dụng AI là để chính thư viện in hoặc ghi cấu hình cho bạn. Lệnh làm theo ba bước: **1. Xem danh sách ứng dụng được hỗ trợ:** ```bash vnstock-mcp --setup ``` | Tên dùng trong lệnh | Ứng dụng | `--write` làm gì | | :--- | :--- | :--- | | `claude-desktop` | Claude Desktop (Chat, Cowork) | Ghép mục `vnstock` vào `claude_desktop_config.json` | | `chatgpt` | ChatGPT desktop (chế độ Codex hoặc Work) | Chạy `codex mcp add vnstock -- …` (dùng chung cấu hình với Codex) | | `gemini` | Gemini Tasks | Ghép mục `vnstock` vào `~/.gemini/settings.json` | | `claude-code` | Claude Code | Chạy `claude mcp add --scope user vnstock -- …` | | `codex` | Codex (CLI, tiện ích IDE trong VS Code/Antigravity) | Chạy `codex mcp add vnstock -- …` | | `antigravity` | Antigravity | Chỉ in, không ghi (đường dẫn tệp đổi theo phiên bản) | | `vscode` | VS Code (Copilot agent) | Ghép mục `vnstock` vào `.vscode/mcp.json` của thư mục đang đứng | | `cursor` | Cursor | Ghép mục `vnstock` vào `~/.cursor/mcp.json` | **2. In cấu hình cho một ứng dụng.** Lệnh này chỉ in ra màn hình, không ghi gì vào máy: ```bash vnstock-mcp --setup claude-code ``` ```text # Claude Code # Chạy lệnh bên dưới (phạm vi user: dùng ở mọi dự án). claude mcp add --scope user vnstock -- /Users//.venv/bin/vnstock-mcp # Chưa thêm gì. Để vnstock-mcp chạy lệnh trên giúp bạn: vnstock-mcp --setup claude-code --write (cần cài sẵn lệnh `claude`) ``` Dòng cuối của bản in luôn cho biết chưa có gì được ghi và lệnh để ghi. **3. Ghi cấu hình khi bạn đã xem và đồng ý:** ```bash vnstock-mcp --setup claude-desktop --write ``` - Với `claude-desktop`, `gemini`, `vscode`, `cursor`: lệnh sao lưu tệp cấu hình hiện có thành `.bak`, rồi ghép thêm mục `vnstock`. Các MCP server khác trong tệp được giữ nguyên. Nếu tệp không phải JSON hợp lệ, lệnh dừng và nhờ bạn sửa tay trước. - Với `claude-code`, `codex`, `chatgpt`: lệnh gọi chính công cụ dòng lệnh của ứng dụng (`claude mcp add`, `codex mcp add`), nên cần cài sẵn lệnh `claude` hoặc `codex`. Nếu đã có server tên `vnstock`, gỡ bằng `claude mcp remove vnstock` (hoặc `codex mcp remove vnstock`) rồi chạy lại. - Với `antigravity`: chỉ in khối cấu hình để bạn dán theo hướng dẫn trong bản in. Ghi xong, **khởi động lại ứng dụng AI** để ứng dụng nạp danh sách công cụ.

Ứng dụng có giao diện (Claude Desktop, Gemini Tasks, ChatGPT desktop) không đọc PATH hay môi trường ảo của terminal. Vì vậy lệnh trong cấu hình là đường dẫn tuyệt đối tới tệp vnstock-mcp trong môi trường Python bạn đang dùng, và có chứa thư mục cá nhân của bạn (ví dụ /Users/<tên-người-dùng>/...). Cấu hình này chỉ nằm trên máy của bạn. Nếu bạn đổi môi trường ảo, chạy lại --setup. Gặp lỗi khi kết nối, chạy vnstock-mcp --doctor.

--- ## Kết nối thủ công vào các Trợ lý AI Nếu muốn tự sửa cấu hình, dùng các đoạn mẫu dưới đây. Thay `` bằng tên thư mục cá nhân trên máy bạn, hoặc dán đúng đường dẫn mà `which vnstock-mcp` (Windows: `where vnstock-mcp`) in ra. Trong tệp JSON, `~` không được tự mở rộng. `vnstock-mcp` giao tiếp qua chuẩn `stdio` của giao thức MCP. Trợ lý AI tự khởi động tiến trình khi bắt đầu phiên làm việc. ### Nhóm 1: Trợ lý lập trình và môi trường dòng lệnh #### 1. Claude Code (CLI) ```bash # macOS & Linux claude mcp add --scope user vnstock -- "$HOME/.venv/bin/vnstock-mcp" ``` Với **Windows PowerShell**: ```powershell claude mcp add --scope user vnstock -- "$env:USERPROFILE\.venv\Scripts\vnstock-mcp.exe" ``` Kiểm tra trạng thái kết nối: ```bash claude mcp list ``` #### 2. Codex (CLI, tiện ích IDE) và ChatGPT desktop Codex CLI, tiện ích Codex trong IDE và ChatGPT desktop (chế độ Codex hoặc Work) dùng chung tệp `~/.codex/config.toml`: ```bash codex mcp add vnstock -- "$HOME/.venv/bin/vnstock-mcp" ``` Hoặc thêm trực tiếp vào `~/.codex/config.toml`: ```toml [mcp_servers.vnstock] command = "/Users//.venv/bin/vnstock-mcp" args = [] ``` Trong ChatGPT desktop, bạn cũng có thể vào **Settings → Plugins → Add MCP server**, chọn Type **STDIO**. Chế độ Chat thường và bản web của ChatGPT chỉ nối được MCP từ xa nên không dùng được với `vnstock-mcp`. #### 3. Antigravity Mở **Agent panel → … → MCP Servers → Manage MCP Servers → View raw config**, dán khối dưới đây vào `mcp_config.json`, rồi bấm **Refresh**: ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` #### 4. VS Code (Copilot agent) và Cursor - **VS Code**: thêm vào `.vscode/mcp.json` của dự án (hoặc lệnh **MCP: Open User Configuration**). Lưu ý khoá gốc là `servers` và có `"type": "stdio"`: ```json { "servers": { "vnstock": { "type": "stdio", "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` - **Cursor**: thêm khối `mcpServers` như mẫu Antigravity vào `~/.cursor/mcp.json`, rồi bật trong **Settings → MCP**. --- ### Nhóm 2: Ứng dụng chat trên máy tính #### 5. Claude Desktop Mở tệp cấu hình (**Settings → Developer → Edit Config**): - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` Sau khi khởi động lại Claude Desktop, danh sách công cụ của `vnstock` hiện trong mục công cụ của ô chat.

Để Claude tự động gọi công cụ ngay cả khi bạn không gõ từ khoá "vnstock", hãy vào Settings → Profile (personal preferences) của Claude và thêm câu sau vào ô hướng dẫn:

"Câu hỏi về chứng khoán, vĩ mô Việt Nam: dùng vnstock-mcp trước."

#### 6. Gemini Tasks Thêm khối `mcpServers` như mẫu Claude Desktop vào `~/.gemini/settings.json`, khởi động lại Gemini Tasks, rồi kiểm tra trong mục tích hợp (Integrations) rằng `vnstock` đã kết nối. --- ## Hồ sơ công cụ (`--profile`) Một số ứng dụng (Claude Desktop, Gemini Tasks) nạp mô tả của mọi công cụ vào ngữ cảnh ở mỗi cuộc trò chuyện. Ít công cụ hơn thì tốn ít token hơn. `vnstock-mcp` có bốn hồ sơ dựng sẵn: | Hồ sơ | Gồm những gì | | :--- | :--- | | `minimal` | Giá, báo cáo tài chính, danh mục mã, chỉ báo, rủi ro, chỉ số tài chính tự tính, `quant_catalog` | | `research` (mặc định) | Bộ cho nghiên cứu cá nhân: dữ liệu cổ phiếu, chỉ số, vĩ mô chính và toàn bộ nhóm quant | | `data` | Mọi công cụ truy xuất qua `vnstock`, không có quant | | `full` | Mọi công cụ | Sáu công cụ `research_*` (lưu bảng, nhật ký, chuẩn hoá, đối chiếu, tra danh mục chỉ tiêu) luôn có trong mọi hồ sơ. Hồ sơ chỉ thu hẹp danh sách; công cụ nào hiện ra vẫn do cấp quyền sử dụng (hoặc quyền hạn bản Cộng đồng) quyết định. `vnstock-mcp --doctor` cho biết số công cụ và lượng token ước tính của từng hồ sơ trên máy bạn. Chọn hồ sơ bằng tham số trong cấu hình, ví dụ `"args": ["--profile", "minimal"]`, hoặc biến môi trường `VNSTOCK_MCP_PROFILE`. Tham số `--layers` (ví dụ `--layers market,quant`) lọc thêm theo tầng; hai bộ lọc giao nhau. --- ## Chạy qua HTTP trên chính máy của bạn Mặc định `vnstock-mcp` chạy qua `stdio`. Với công cụ chạy trên cùng máy cần nối qua HTTP, dùng chế độ `streamable-http`: ```bash vnstock-mcp --transport streamable-http --port 8000 # Địa chỉ: http://127.0.0.1:8000/mcp (đổi đường dẫn bằng --path) ``` - Chỉ nhận địa chỉ loopback (`127.0.0.1`, `::1`, `localhost`). Lệnh từ chối chạy với mọi địa chỉ khác: `vnstock-mcp` phục vụ đúng người cài nó, trên đúng máy đó, theo phạm vi giấy phép cá nhân. - Bearer token tuỳ chọn: đặt qua biến `VNSTOCK_MCP_TOKEN` (tham số `--token` lộ trong danh sách tiến trình). - Giới hạn tần suất: `--rate-limit` (mặc định 120 yêu cầu mỗi phút, `0` để tắt). --- ## Các biến môi trường tùy chỉnh | Biến môi trường | Mặc định | Ý nghĩa | | :--- | :--- | :--- | | `VNSTOCK_MCP_WORKSPACE` | `~/vnstock_research` | Thư mục nghiên cứu: nhật ký phiên (`journal/`), bảng đã lưu (`data/`), script tái lập (`scripts/`). | | `VNSTOCK_MCP_PROFILE` | `research` | Hồ sơ công cụ: `minimal`, `research`, `data` hoặc `full`. | | `VNSTOCK_MCP_LAYERS` | tất cả | Danh sách tầng được bật, phân tách bằng dấu phẩy, ví dụ `reference,market,fundamental`. | | `VNSTOCK_MCP_MAX_ROWS` | `60` | Số dòng tối đa hiện cho Trợ lý AI trong một kết quả. Phép tính tiếp theo vẫn dùng bảng đầy đủ qua `call_id`. | | `VNSTOCK_MCP_FORMAT` | `table` | `table` (gọn token) hoặc `records` (dễ đọc hơn cho mô hình nhỏ). | | `VNSTOCK_MCP_CACHE` | bật | Bộ nhớ đệm trong tiến trình để giảm truy vấn lặp lại. | | `VNSTOCK_MCP_TIMEOUT` | `60` | Thời gian tối đa cho mỗi lần gọi công cụ (giây), `0` là không giới hạn. | | `VNSTOCK_MCP_JOURNAL` | bật | Ghi nhật ký mỗi lần gọi công cụ thành công vào thư mục nghiên cứu. | | `VNSTOCK_MCP_TOKEN` | không có | Bearer token cho chế độ HTTP trên loopback. | Ví dụ đặt biến trong cấu hình JSON: ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": ["--profile", "full"], "env": { "VNSTOCK_MCP_WORKSPACE": "/Users//vnstock_research" } } } } ``` Đăng nhập hoặc đổi cấp quyền sử dụng (`vnstock login`) xong, khởi động lại ứng dụng AI để danh sách công cụ được dựng lại. --- ## Document: Danh mục Công cụ > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Bạn không cần phải nhớ chính xác tên công cụ hay cú pháp JSON. Khi bạn trò chuyện bằng ngôn ngữ tự nhiên, Trợ lý AI sẽ tự động chọn công cụ phù hợp nhất trong danh sách được cấp phép để phục vụ yêu cầu của bạn.



## Tổng quan `vnstock-mcp` cung cấp **39 công cụ** đóng vai trò cầu nối để Trợ lý AI gọi trực tiếp các hàm trong hệ sinh thái Vnstock trên máy cá nhân của bạn: gồm 26 công cụ kết nối và chuẩn hoá dữ liệu (`vnstock`), 7 công cụ tính toán định lượng (`vnstock_quant`), và 6 công cụ điều phối không gian nghiên cứu cục bộ (`research_*`). Trợ lý AI chỉ nhìn thấy những công cụ và giá trị `method` mà tài khoản của bạn được phép sử dụng: | Cấp | Hồ sơ `full` | Hồ sơ `research` (mặc định) | Ghi chú | | :--- | :---: | :---: | :--- | | Guest (chưa đăng nhập) | Ít hơn | Ít hơn | Chế độ chạy thử: chỉ các `method` dữ liệu ghi ở đoạn dưới bảng này; định lượng và nghiên cứu như bản Cộng đồng | | Bản Cộng đồng | 29 | 21 | Dữ liệu: các `method` ở cột "mở từ bản Cộng đồng"; định lượng: 10 chỉ báo và 10 chỉ số tài chính cơ bản, dùng thử theo lượt mỗi ngày (mặc định 30) | | Bronze | 39 | 29 | Mọi `method` dữ liệu; mọi nhóm định lượng trừ bộ chỉ báo kỹ thuật đầy đủ | | Silver, Golden, Diamond | 39 | 29 | Như Bronze, thêm bộ chỉ báo kỹ thuật đầy đủ (58 chỉ báo) | Khi chưa đăng nhập (Guest), trợ lý AI chỉ thấy phần dữ liệu để chạy thử: `reference_company` (`info`), `reference_equity` (`list`, `list_by_group`), `reference_index` (`list`), `market_equity` (`ohlcv`, `quote`), `market_index` (`ohlcv`) và bảng giá nhiều mã. Danh sách này đi theo quy tắc của cấp Khách trong thư viện vnstock, xem [Cấp tài khoản và giới hạn](/docs/vnstock/tham-khao/cap-quyen-va-gioi-han). Muốn dùng các công cụ dữ liệu còn lại, đăng nhập bằng khoá API cấp Cộng đồng. Chọn hồ sơ bằng `--profile` hoặc `VNSTOCK_MCP_PROFILE` (xem [Cài đặt và Kết nối](/docs/vnstock-mcp/cai-dat-va-ket-noi)). Bảng dưới lấy từ danh mục công cụ đi kèm bản phát hành (ngày 13/10/2026, vnstock 5.0.1); số liệu nguồn chịu thêm giới hạn kỳ và số dòng theo cấp. --- ## 1. Tầng Reference (Thông tin Tham chiếu và Danh mục) | Tên công cụ | Cấp tối thiểu | `method` mở từ bản Cộng đồng | Thêm từ Bronze | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :--- | :--- | :--- | :--- | | `reference_company` | Cộng đồng | `info`, `shareholders`, `officers`, `subsidiaries`, `affiliate`, `ownership`, `capital_history`, `insider_trading`, `events` | — | Hồ sơ công ty niêm yết: tổng quan, cổ đông, ban lãnh đạo, công ty con, liên kết, sở hữu, lịch sử vốn, giao dịch nội bộ, sự kiện. | *"Cho tôi xem ban lãnh đạo và các công ty con của VCB."* | | `reference_equity` | Cộng đồng | `list`, `list_by_group`, `list_by_exchange`, `list_by_industry` | — | Danh sách mã cổ phiếu theo sàn, nhóm (VN30…) hoặc ngành ICB. | *"Liệt kê các mã thuộc rổ VN30."* | | `reference_index` | Cộng đồng | `list`, `groups`, `members`, `info` | — | Danh mục chỉ số (VNINDEX, VN30…), nhóm chỉ số và cổ phiếu thành phần. | *"VN30 hiện gồm những mã nào?"* | | `reference_industry` | Cộng đồng | `list`, `sectors` | — | Phân ngành ICB: danh sách ngành, mã thuộc ngành. | *"FPT thuộc ngành ICB nào?"* | | `reference_instrument` | Cộng đồng | `etf.list`, `futures.list`, `warrant.list`, `bond.list` | `futures.info`, `warrant.info`, `bond.info` | Danh sách và thông số ETF, hợp đồng tương lai, chứng quyền, trái phiếu (`kind`). | *"Liệt kê các mã chứng quyền đang lưu hành."* | | `reference_fund` | Bronze | — | `list`, `profile`, `fee_structure`, `reports` | Quỹ mở: danh sách quỹ, hồ sơ, biểu phí, báo cáo. | *"Liệt kê các quỹ mở cổ phiếu và biểu phí của từng quỹ."* | | `reference_events` | Cộng đồng | `calendar`, `market` | — | Lịch sự kiện: chia cổ tức, đại hội cổ đông, niêm yết, ngày nghỉ giao dịch. | *"Tuần tới có những sự kiện chia cổ tức nào?"* | | `reference_market` | Cộng đồng | (không có `method`) | — | Thị trường đang mở hay đóng cửa, phiên hiện tại. | *"Sàn HOSE đang ở phiên nào?"* | | `reference_search` | Cộng đồng | (không có `method`) | — | Tìm mã ngoại tệ, hàng hoá, chỉ số quốc tế theo từ khoá. | *"Tìm mã của giá vàng thế giới."* | --- ## 2. Tầng Market (Giá và Giao dịch) | Tên công cụ | Cấp tối thiểu | `method` mở từ bản Cộng đồng | Thêm từ Bronze | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :--- | :--- | :--- | :--- | | `market_equity` | Cộng đồng | `ohlcv`, `trades`, `quote` | `order_book`, `session_stats`, `foreign_flow`, `proprietary_flow`, `block_trades`, `odd_lot`, `volume_profile`, `trade_history` | Giá cổ phiếu: nến OHLCV, khớp lệnh, giá hiện tại; từ cấp quyền sử dụng thêm sổ lệnh, thống kê phiên, khối ngoại, tự doanh, giao dịch thoả thuận, lô lẻ, phân bố khối lượng, lịch sử khớp. | *"Lấy nến ngày của FPT trong 3 tháng gần nhất."* | | `market_index` | Cộng đồng | `ohlcv` | `quote`, `trades`, `trade_history` | Diễn biến chỉ số VN-Index, VN30, HNX. | *"Vẽ diễn biến VN-Index 1 năm qua."* | | `market_etf` | Cộng đồng | `ohlcv`, `trades`, `quote` | `order_book`, `session_stats`, `foreign_flow` | Giá chứng chỉ quỹ ETF. | *"Lấy nến tuần của E1VFVN30 trong 1 năm."* | | `market_futures` | Cộng đồng | `ohlcv`, `trades`, `quote` | `order_book` | Giá hợp đồng tương lai VN30F. | *"Xem giá khớp của hợp đồng VN30F1M hôm nay."* | | `market_warrant` | Cộng đồng | `ohlcv`, `trades`, `quote` | `order_book` | Giá chứng quyền có bảo đảm. | *"Lấy nến ngày của một mã chứng quyền trên HPG."* | | `market_crypto` | Cộng đồng | `ohlcv` | `trades`, `order_book`, `quote`, `vwap`, `daily_stats`, `last_price`, `rolling_stats`, `reference_price` | Giá tiền mã hoá; từ cấp quyền sử dụng thêm khớp lệnh, sổ lệnh, thống kê ngày và cửa sổ trượt. | *"Lấy nến ngày của BTCUSDT 6 tháng gần nhất."* | | `market_forex` | Cộng đồng | `ohlcv` | `trades` | Tỷ giá quốc tế theo thời gian (EURUSD, USDJPY…). | *"Diễn biến EURUSD trong 3 tháng."* | | `market_commodity` | Cộng đồng | `ohlcv` | `trades` | Giá hàng hoá thế giới: vàng, dầu, kim loại. | *"Giá vàng thế giới 1 năm qua biến động thế nào?"* | | `market_fund` | Bronze | — | `history`, `holdings`, `industry_allocation`, `asset_allocation`, `performance`, `dividends` | Quỹ mở: lịch sử NAV, danh mục nắm giữ, phân bổ ngành và tài sản, hiệu suất, cổ tức. | *"Danh mục nắm giữ hiện tại của một quỹ mở cổ phiếu."* | | `market_board` | Cộng đồng | `quote` | `put_through`, `odd_lot` | Bảng giá nhiều mã cùng lúc: giá trần, sàn, tham chiếu, dư mua bán; từ cấp quyền sử dụng thêm giao dịch thoả thuận trong phiên và lô lẻ. | *"Bảng giá của VCB, BID, CTG."* | --- ## 3. Tầng Fundamental (Báo cáo Tài chính) | Tên công cụ | Cấp tối thiểu | `method` mở từ bản Cộng đồng | Thêm từ Bronze | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :--- | :--- | :--- | :--- | | `fundamental_equity` | Cộng đồng | `income_statement`, `balance_sheet`, `cash_flow` | `ratio`, `financial_health`, `note` | Báo cáo tài chính theo quý/năm: kết quả kinh doanh, cân đối kế toán, lưu chuyển tiền tệ; từ cấp quyền sử dụng thêm chỉ số tài chính, sức khoẻ tài chính, thuyết minh. | *"Lấy báo cáo kết quả kinh doanh 4 quý gần nhất của HPG."* | Chỉ số tài chính tự tính từ báo cáo tài chính có công thức đi kèm thì dùng `quant_fa` (tầng 5); ở mọi cấp có 10 chỉ số cơ bản. --- ## 4. Tầng Macro, Insights và Retail | Tên công cụ | Cấp tối thiểu | `method` mở từ bản Cộng đồng | Thêm từ Bronze | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :--- | :--- | :--- | :--- | | `macro_economy` | Bronze | — | `gdp`, `cpi`, `import_export`, `fdi`, `money_supply`, `credit`, `total_investment`, `state_budget` | Vĩ mô Việt Nam: GDP, CPI, xuất nhập khẩu, FDI, cung tiền, tín dụng, vốn đầu tư, ngân sách. | *"Diễn biến CPI và tăng trưởng tín dụng năm nay."* | | `macro_currency` | Bronze | — | `exchange_rate`, `interbank_rate`, `policy_rate`, `omo`, `deposit_rate` | Tiền tệ: tỷ giá USD/VND, lãi suất liên ngân hàng, lãi suất điều hành, OMO, lãi suất tiền gửi. | *"Lãi suất liên ngân hàng qua đêm tháng này."* | | `macro_global` | Bronze | — | `bond_yield`, `fed_rate`, `index` | Thế giới: lợi suất trái phiếu chính phủ, lãi suất Fed, chỉ số (DXY…). | *"Lợi suất trái phiếu Mỹ 10 năm gần đây."* | | `insights_sentiment` | Bronze | — | `breadth`, `contribution`, `heatmap` | Độ rộng thị trường, mã đóng góp vào chỉ số, bản đồ nhiệt. | *"Độ rộng sàn HOSE hôm nay."* | | `insights_flow` | Bronze | — | `foreign`, `proprietary`, `active` | Dòng tiền toàn thị trường: khối ngoại, tự doanh, mua bán chủ động; theo mã, ngành hoặc nhóm vốn hoá. | *"Khối ngoại mua ròng ngành nào nhiều nhất hôm nay?"* | | `retail_exchange_rate` | Cộng đồng | (không có `method`) | — | Tỷ giá mua bán ngoại tệ niêm yết tại ngân hàng theo ngày. | *"Tỷ giá USD niêm yết tại ngân hàng hôm nay."* | --- ## 5. Tầng Quant (Phân tích Định lượng) | Tên công cụ | Cấp tối thiểu | Loại | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :---: | :--- | :--- | | `quant_catalog` | Guest | Đọc | Tra danh mục chỉ báo, chỉ số, thước đo rủi ro, mô hình danh mục và công thức của `vnstock_quant`. | *"vnstock_quant có những thước đo rủi ro nào?"* | | `quant_entitlement` | Guest | Đọc | Cấp quyền sử dụng và số lượt tính thử còn lại trong ngày. | *"Tôi còn bao nhiêu lượt tính thử hôm nay?"* | | `quant_ta` | Guest | Đọc | Chỉ báo kỹ thuật trên dữ liệu bạn truy xuất qua vnstock (`symbol`) hoặc bảng trong phiên (`data="c1"`). Guest, bản Cộng đồng, Bronze: 10 chỉ báo cơ bản (SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV, VWAP, Pivots); Silver trở lên: đủ 58 chỉ báo. | *"Tính SMA 20 và RSI 14 cho FPT."* | | `quant_fa` | Guest | Đọc | Chỉ số tài chính tính từ báo cáo tài chính gốc, có công thức. Guest, bản Cộng đồng: 10 chỉ số cơ bản (P/E, P/B, EPS, BVPS, ROE, ROA, biên gộp, biên ròng, thanh toán hiện hành, nợ/vốn chủ); Bronze trở lên: đủ bộ chỉ số. | *"Tính ROE và biên lợi nhuận ròng 8 quý của VNM."* | | `quant_risk` | Bronze | Đọc | Rủi ro và hiệu suất: biến động, Sharpe, Sortino, beta, VaR, CVaR, mức sụt giảm tối đa. | *"Tính mức sụt giảm tối đa và Sharpe của HPG trong 1 năm."* | | `quant_portfolio` | Bronze | Đọc | Danh mục: phân bổ tỷ trọng, tối ưu hoá, lợi suất và rủi ro danh mục. | *"Phân bổ tỷ trọng FPT, VNM, HPG theo rủi ro ngang bằng."* | | `quant_valuation` | Bronze | Đọc | Định giá theo mô hình: chiết khấu cổ tức (DDM), P/E hợp lý, lợi suất và tăng trưởng hàm ý. | *"Tính P/E hợp lý theo giả định tăng trưởng 8%."* | Ở cấp Khách và bản Cộng đồng, mỗi lần tính của `quant_ta`, `quant_fa` trừ một lượt dùng thử. Từ Bronze không áp dụng giới hạn dùng thử riêng. Ở mọi cấp, phép tính vẫn được ghi nhận vào quỹ hạn mức chung của tài khoản. Kết quả là gợi ý tính toán, không phải khuyến nghị đầu tư. --- ## 6. Tầng Research (Không gian Nghiên cứu Cá nhân) Sáu công cụ dưới đây có mặt ở mọi hồ sơ công cụ và mọi cấp quyền sử dụng (kể cả bản Cộng đồng). Cách dùng chi tiết: [Nghiên cứu Tái lập và Đa nguồn](/docs/vnstock-mcp/nghien-cuu-tai-lap-va-da-nguon). | Tên công cụ | Cấp tối thiểu | Loại | Mô tả chức năng | Prompt mẫu cho AI | | :--- | :---: | :---: | :--- | :--- | | `research_save` | Guest | Ghi | Ghi toàn bộ một bảng vừa lấy (theo `call_id`) ra thư mục nghiên cứu trên máy, dạng CSV hoặc Parquet, kèm tệp `.meta.json` ghi mã Python tương đương. Tham số: `call_id`, `name`, `format`, `overwrite`. | *"Lưu bảng nến vừa lấy với tên 'fpt_ohlcv_5y'."* | | `research_datasets` | Guest | Đọc | Liệt kê các bảng đã lưu trong thư mục nghiên cứu, kèm mã tạo ra từng bảng. | *"Tôi đã lưu những bảng nào?"* | | `research_journal` | Guest | Ghi | `method="list"`: nhật ký phiên, mỗi lần gọi kèm mã Python tương đương. `method="script"`: ghép cả phiên thành script Python chạy lại được; `save=true` ghi ra `scripts/.py`. | *"Xuất quy trình phân tích vừa rồi thành file script Python."* | | `research_normalize` | Guest | Đọc | Chuyển bảng thô bạn tự lấy từ nguồn khác sang bảng chuẩn của vnstock (`dataset`, ví dụ `fundamental.financial_statement`, `equity.ohlcv_daily`). Báo cáo tài chính: chỉ giữ kỳ quý, tiền về tỷ VNĐ, cột VAS kèm tên ngắn, cột ngoài VAS có `formula`, thêm ROE/ROA tự tính. Các định dạng được hỗ trợ có trong mô tả tool (tham số `provider`). | *"Chuẩn hoá bảng báo cáo tài chính FPT tôi vừa đưa về bảng chuẩn của vnstock."* | | `research_benchmark` | Guest | Đọc | Đối chiếu bảng đó với số liệu tham chiếu bạn truy xuất qua vnstock: nến ngày theo độ lệch giá đóng cửa; báo cáo tài chính, chỉ số theo từng quý (`MATCHED` cần ít nhất 4 quý chung, mọi quý trong ngưỡng). Trạng thái: `VERIFIED`, `PARTIALLY_VERIFIED`, `DEVIATIONS_FOUND`, `INSUFFICIENT_DATA`. | *"Đối chiếu bảng vừa chuẩn hoá với số liệu lấy qua vnstock."* | | `research_universe` | Guest | Đọc | Tra 8 bảng chuẩn và cột của từng bảng (`category="catalog"`), tổng quan từ điển VAS (`"vas"`), hoặc chỉ tiêu một báo cáo theo loại hình `DN`, `TCTD`, `CTCK`, `DNPNT`. | *"Báo cáo kết quả kinh doanh của công ty chứng khoán có những chỉ tiêu nào?"* |

research_benchmark đọc số liệu tham chiếu qua vnstock, nên theo đúng quyền và hạn mức cấp quyền sử dụng của bạn (hoặc bản Cộng đồng). Từ điển chỉ tiêu VAS dùng cho research_normalize, research_benchmark và research_universe được tải về bộ nhớ khi cần, có chữ ký số, không ghi xuống đĩa; tài khoản bản Cộng đồng nhận bộ từ điển rút gọn.

--- ## 7. Prompt mẫu dựng sẵn Ngoài công cụ, `vnstock-mcp` cung cấp bốn prompt MCP. Ứng dụng hỗ trợ prompt MCP (ví dụ Claude Desktop, Claude Code) hiển thị chúng trong danh sách lệnh. Prompt chỉ hiện khi mọi công cụ nó cần đều đang mở cho tài khoản và hồ sơ của bạn. | Prompt | Tham số | Nội dung | | :--- | :--- | :--- | | `study_stock` | `symbol` | Hồ sơ nghiên cứu một cổ phiếu: doanh nghiệp, chỉ số tài chính tự tính, rủi ro, xu hướng giá, sự kiện | | `market_overview` | không có | Tổng quan phiên: trạng thái phiên, chỉ số, độ rộng, dòng tiền khối ngoại theo ngành | | `macro_dashboard` | không có | Bảng tổng hợp vĩ mô Việt Nam và bối cảnh thế giới | | `reproducible_study` | `question` | Biến một câu hỏi nghiên cứu thành quy trình năm bước chạy lại được | Mỗi prompt yêu cầu Trợ lý AI ghi nguồn cho từng con số và kết thúc bằng script tái lập từ `research_journal`. Kết quả là phân tích tham khảo, không phải khuyến nghị đầu tư. --- ## Document: Cài đặt và Kết nối > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Nếu bạn chưa cài đặt Python hoặc chưa từng cấu hình MCP trước đây, hãy tham khảo Trung tâm hướng dẫn Vibe Coding để Trợ lý AI tự động thiết lập toàn bộ môi trường.



## Tổng quan Trang này hướng dẫn bạn cài đặt `vnstock-mcp` và cấu hình cầu nối cục bộ vào các ứng dụng Trợ lý AI như **Claude Code**, **ChatGPT Codex**, **Antigravity**, **Claude Desktop**, **ChatGPT Desktop** và **Gemini Tasks** với **bản Cộng đồng** (miễn phí cho cá nhân, học tập và nghiên cứu). Khác với việc kết nối tới một máy chủ MCP trực tuyến trên mạng, cấu hình bên dưới giúp ứng dụng AI trên máy bạn khởi chạy trực tiếp tiến trình `vnstock-mcp` từ môi trường Python cá nhân (`.venv`) để gọi các thư viện Vnstock và lưu trữ phiên làm việc trong không gian nghiên cứu cục bộ (`~/vnstock_research`). --- ## 1. Yêu cầu môi trường - **Hệ điều hành**: macOS (Apple Silicon hoặc Intel), Windows 10/11 64-bit, hoặc Linux x86_64. - **Python**: Phiên bản **>= 3.10** (khuyên dùng Python 3.11 hoặc 3.12 trong môi trường ảo `~/.venv`). - **Thư viện**: Cài đặt thư viện `vnstock` và `vnstock-mcp`. --- ## 2. Cài đặt thư viện Bạn có thể cài đặt `vnstock-mcp` trực tiếp qua `pip`: ```bash # Cài đặt hoặc cập nhật phiên bản mới nhất từ kho phát hành pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock vnstock-mcp ``` Sau khi cài đặt xong, kiểm tra tệp thực thi `vnstock-mcp`: ```bash which vnstock-mcp # Đầu ra mẫu trên macOS/Linux: /Users//.venv/bin/vnstock-mcp # Đầu ra mẫu trên Windows (lệnh 'where'): C:\Users\\.venv\Scripts\vnstock-mcp.exe ``` --- ## 3. Kiểm tra môi trường và cấp quyền sử dụng ```bash vnstock status # cấp quyền sử dụng và hạn mức; chưa đăng nhập thì chạy: vnstock login vnstock-mcp --doctor # Python, thư viện, thư mục nghiên cứu, số công cụ theo từng hồ sơ ``` Đầu ra mẫu của `vnstock-mcp --doctor` (rút gọn): ```text [OK ] Python 3.11.14 (cần >= 3.10) [OK ] vnstock 5.0.0 (thế hệ 5) [OK ] Thư mục nghiên cứu ghi được: ~/vnstock_research (nhật ký bật) [OK ] hồ sơ research: ... tool, schema ≈ ... token ← đang dùng [OK ] Gọi dữ liệu thật Market().equity('FPT').ohlcv: 5 dòng, 0.7s Môi trường sẵn sàng. ``` Số công cụ trên máy bạn theo đúng cấp quyền tài khoản của bạn. --- ## 4. Thiết lập nhanh bằng `vnstock-mcp --setup` Thư viện in sẵn cấu hình đúng cho máy của bạn, và ghi giúp khi bạn đồng ý: ```bash vnstock-mcp --setup # liệt kê ứng dụng được hỗ trợ vnstock-mcp --setup claude-desktop # chỉ in cấu hình, không ghi gì vnstock-mcp --setup claude-desktop --write # ghi vào tệp cấu hình của ứng dụng ``` Tên ứng dụng: `claude-desktop`, `chatgpt`, `gemini` (Gemini Tasks), `claude-code`, `codex`, `antigravity`, `vscode`, `cursor`. - Lệnh không có `--write` chỉ in ra màn hình; dòng cuối cho biết lệnh để ghi. - Với `claude-desktop`, `gemini`, `vscode` (tệp `.vscode/mcp.json` của thư mục đang đứng), `cursor`: `--write` sao lưu tệp cũ thành `.bak`, ghép thêm mục `vnstock` và giữ nguyên các MCP server khác. - Với `claude-code`, `codex`, `chatgpt`: `--write` chạy lệnh của chính ứng dụng (`claude mcp add --scope user vnstock -- …`, `codex mcp add vnstock -- …`), nên cần cài sẵn lệnh `claude` hoặc `codex`. - Với `antigravity`: chỉ in, vì đường dẫn tệp cấu hình đổi theo phiên bản. Lệnh trong cấu hình là đường dẫn tuyệt đối tới `vnstock-mcp` trong môi trường Python của bạn, vì ứng dụng có giao diện không đọc `PATH` hay môi trường ảo của terminal. Đường dẫn này chứa thư mục cá nhân của bạn và chỉ nằm trên máy của bạn. Ghi xong, **khởi động lại ứng dụng AI**. Gặp lỗi, chạy `vnstock-mcp --doctor`. Chi tiết từng ứng dụng: [Cài đặt và Kết nối](/docs/vnstock-mcp/cai-dat-va-ket-noi). --- ## 5. Kết nối thủ công vào Trợ lý AI

Các câu lệnh terminal dưới đây sử dụng biến môi trường $HOME (trên macOS/Linux) và $env:USERPROFILE (trên Windows) để hệ thống tự động nhận diện thư mục người dùng trên máy của bạn mà không cần chỉnh sửa thủ công.

Trong tệp cấu hình JSON, ~ không được tự mở rộng: thay <tên-người-dùng> bằng tên thư mục cá nhân của bạn, hoặc dán đúng đường dẫn mà lệnh which vnstock-mcp in ra. Cách nhanh hơn là dùng vnstock-mcp --setup ở mục 4.

### Nhóm 1: Chế độ Code (Coding & CLI Agents) #### A. Kết nối với Claude Code (CLI) Chạy lệnh thêm MCP server trực tiếp trong terminal: ```bash # Trên macOS & Linux: Biến môi trường $HOME tự động trỏ về thư mục cá nhân của bạn claude mcp add --scope user vnstock -- "$HOME/.venv/bin/vnstock-mcp" ``` Với người dùng **Windows PowerShell**: ```powershell claude mcp add --scope user vnstock -- "$env:USERPROFILE\.venv\Scripts\vnstock-mcp.exe" ``` #### B. Kết nối với Codex (CLI, tiện ích IDE) và ChatGPT desktop Codex và ChatGPT desktop (chế độ Codex hoặc Work) dùng chung tệp `~/.codex/config.toml`: ```bash codex mcp add vnstock -- "$HOME/.venv/bin/vnstock-mcp" ``` Hoặc thêm vào `~/.codex/config.toml`: ```toml [mcp_servers.vnstock] command = "/Users//.venv/bin/vnstock-mcp" args = [] ``` #### C. Kết nối với Antigravity Mở **Agent panel → … → MCP Servers → Manage MCP Servers → View raw config**, dán khối dưới đây vào `mcp_config.json`, rồi bấm **Refresh**: ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` --- ### Nhóm 2: Chế độ App Desktop (Desktop Applications) #### D. Kết nối với Claude Desktop Mở file cấu hình của Claude Desktop: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` Thêm cấu hình kết nối vnstock-mcp: ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` Khởi động lại Claude Desktop để ứng dụng nạp danh sách công cụ. #### E. Kết nối với ChatGPT desktop & Gemini Tasks - Với **ChatGPT desktop**: dùng chung cấu hình với Codex ở mục B, hoặc vào **Settings → Plugins → Add MCP server**, chọn Type **STDIO**. Chế độ Chat thường và bản web chỉ nối được MCP từ xa nên không dùng được với `vnstock-mcp`. - Với **Gemini Tasks**: thêm khối `mcpServers` như mẫu Claude Desktop vào `~/.gemini/settings.json`, khởi động lại rồi kiểm tra trong mục tích hợp (Integrations). --- #### F. Kết nối với Windsurf Mở file `~/.codeium/windsurf/mcp_config.json` và cấu hình: ```json { "mcpServers": { "vnstock": { "command": "/Users//.venv/bin/vnstock-mcp", "args": [] } } } ``` --- ## 6. Thử nghiệm câu lệnh đầu tiên Sau khi kết nối thành công, bạn mở cửa sổ chat với Trợ lý AI và gửi các câu hỏi mẫu sau: ### Kiểm tra công cụ > *"Chào bạn, hãy kiểm tra danh sách công cụ Vnstock MCP bạn đang có và báo cho tôi biết cấp quyền sử dụng hiện tại (hoặc bản Cộng đồng)."* ### Tra cứu cổ phiếu FPT > *"Hãy dùng Vnstock MCP để tra cứu hồ sơ doanh nghiệp FPT và lấy Báo cáo kết quả kinh doanh 4 quý gần nhất."* ### Dùng thử tính toán kỹ thuật (Quant Trial) > *"Dùng công cụ quant_ta để tính chỉ số RSI và MACD cho cổ phiếu HPG."* Trợ lý AI sẽ tự động kích hoạt công cụ phù hợp, hiển thị bảng kết quả rõ ràng và thông báo số lượt dùng thử còn lại trong ngày. --- ## Tiếp theo - Tìm hiểu chi tiết [Phân quyền và lượt dùng thử](/docs/vnstock-mcp/free/phan-quyen-va-han-muc) của bản Cộng đồng. - Xem [Danh mục 29 Công cụ](/docs/vnstock-mcp/free/danh-muc-cong-cu) để khai thác hiệu quả các công cụ. --- ## Document: Danh mục Công cụ > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Bạn không cần phải nhớ chính xác tên công cụ hay cú pháp lệnh. Trò chuyện bằng tiếng Việt tự nhiên với Trợ lý AI, hệ thống sẽ tự động chọn công cụ thích hợp nhất trong số công cụ được cấp phép.



## Tổng quan Ở **bản Cộng đồng** (miễn phí cho cá nhân, học tập và nghiên cứu), `vnstock-mcp` mở **29 công cụ** ở hồ sơ `full` (và 21 công cụ ở hồ sơ mặc định `research`) để Trợ lý AI gọi các hàm của thư viện `vnstock`, dùng thử công cụ định lượng `vnstock_quant` và điều phối phiên làm việc trên máy cá nhân (`research_*`). Với mỗi công cụ dữ liệu, Trợ lý AI chỉ thấy các giá trị `method` liệt kê dưới đây; các `method` còn lại mở từ cấp Bronze ([Danh mục bản Mở rộng](/docs/vnstock-mcp/danh-muc-cong-cu)). Danh mục theo bản phát hành ngày 13/10/2026 (vnstock 5.0.1). --- ## 1. Tầng Reference (Thông tin Tham chiếu và Danh mục) | Tên công cụ | `method` | Mô tả chức năng | Prompt mẫu cho Trợ lý AI | | :--- | :--- | :--- | :--- | | `reference_company` | `info`, `shareholders`, `officers`, `subsidiaries`, `affiliate`, `ownership`, `capital_history`, `insider_trading`, `events` | Hồ sơ công ty niêm yết: tổng quan, cổ đông, ban lãnh đạo, công ty con, sở hữu, lịch sử vốn, giao dịch nội bộ, sự kiện. | *"Cho tôi xem ban lãnh đạo và các công ty con của VCB."* | | `reference_equity` | `list`, `list_by_group`, `list_by_exchange`, `list_by_industry` | Danh sách mã cổ phiếu theo sàn, nhóm (VN30…) hoặc ngành ICB. | *"Liệt kê các mã thuộc rổ VN30."* | | `reference_index` | `list`, `groups`, `members`, `info` | Danh mục chỉ số, nhóm chỉ số và cổ phiếu thành phần. | *"VN30 hiện gồm những mã nào?"* | | `reference_industry` | `list`, `sectors` | Phân ngành ICB: danh sách ngành, mã thuộc ngành. | *"FPT thuộc ngành ICB nào?"* | | `reference_instrument` | `etf.list`, `futures.list`, `warrant.list`, `bond.list` | Danh sách ETF, hợp đồng tương lai, chứng quyền, trái phiếu (`kind`). | *"Liệt kê các mã chứng quyền đang lưu hành."* | | `reference_events` | `calendar`, `market` | Lịch sự kiện: chia cổ tức, đại hội cổ đông, niêm yết, ngày nghỉ giao dịch. | *"Năm nay thị trường nghỉ lễ những ngày nào?"* | | `reference_market` | (không có `method`) | Thị trường đang mở hay đóng cửa, phiên hiện tại. | *"Sàn HOSE đang ở phiên nào?"* | | `reference_search` | (không có `method`) | Tìm mã ngoại tệ, hàng hoá, chỉ số quốc tế theo từ khoá. | *"Tìm mã của giá vàng thế giới."* | --- ## 2. Tầng Market (Giá và Giao dịch) | Tên công cụ | `method` | Mô tả chức năng | Prompt mẫu cho Trợ lý AI | | :--- | :--- | :--- | :--- | | `market_equity` | `ohlcv`, `trades`, `quote` | Giá cổ phiếu: nến OHLCV, khớp lệnh, giá hiện tại. | *"Lấy nến ngày của FPT trong 3 tháng gần nhất."* | | `market_index` | `ohlcv` | Nến chỉ số VN-Index, VN30, HNX. | *"Vẽ diễn biến VN-Index 1 năm qua."* | | `market_etf` | `ohlcv`, `trades`, `quote` | Giá chứng chỉ quỹ ETF. | *"Lấy nến tuần của E1VFVN30 trong 1 năm."* | | `market_futures` | `ohlcv`, `trades`, `quote` | Giá hợp đồng tương lai VN30F. | *"Xem giá khớp của hợp đồng VN30F1M hôm nay."* | | `market_warrant` | `ohlcv`, `trades`, `quote` | Giá chứng quyền có bảo đảm. | *"Lấy nến ngày của một mã chứng quyền trên HPG."* | | `market_crypto` | `ohlcv` | Nến tiền mã hoá. | *"Lấy nến ngày của BTCUSDT 6 tháng gần nhất."* | | `market_forex` | `ohlcv` | Nến tỷ giá quốc tế (EURUSD, USDJPY…). | *"Diễn biến EURUSD trong 3 tháng."* | | `market_commodity` | `ohlcv` | Nến giá hàng hoá thế giới: vàng, dầu, kim loại. | *"Giá vàng thế giới 1 năm qua biến động thế nào?"* | | `market_board` | `quote` | Bảng giá nhiều mã cùng lúc: giá trần, sàn, tham chiếu, dư mua bán. | *"Bảng giá của VCB, BID, CTG."* | --- ## 3. Tầng Fundamental và Retail | Tên công cụ | `method` | Mô tả chức năng | Prompt mẫu cho Trợ lý AI | | :--- | :--- | :--- | :--- | | `fundamental_equity` | `income_statement`, `balance_sheet`, `cash_flow` | Ba báo cáo tài chính theo quý/năm: kết quả kinh doanh, cân đối kế toán, lưu chuyển tiền tệ (8 kỳ gần nhất). | *"Lấy báo cáo kết quả kinh doanh 4 quý gần nhất của HPG."* | | `retail_exchange_rate` | (không có `method`) | Tỷ giá mua bán ngoại tệ niêm yết tại ngân hàng theo ngày. | *"Tỷ giá USD niêm yết tại ngân hàng hôm nay."* | Chỉ số tài chính (P/E, ROE…) tự tính từ báo cáo tài chính có công thức đi kèm: dùng `quant_fa` ở tầng 6. --- ## 4. Tầng Macro và Insights Vĩ mô (`macro_economy`, `macro_currency`, `macro_global`) và độ rộng, dòng tiền thị trường (`insights_sentiment`, `insights_flow`) mở từ cấp Bronze. --- ## 5. Tầng Research (Không gian Nghiên cứu Cục bộ & Tái lập) Sáu công cụ này có ở mọi cấp quyền sử dụng (kể cả bản Cộng đồng) và mọi hồ sơ công cụ. Cách dùng chi tiết: [Nghiên cứu Tái lập và Đa nguồn](/docs/vnstock-mcp/nghien-cuu-tai-lap-va-da-nguon). | Tên công cụ | Loại | Mô tả chức năng | Prompt mẫu cho Trợ lý AI | | :--- | :---: | :--- | :--- | | `research_save` | Ghi | Ghi toàn bộ một bảng vừa lấy (theo `call_id`) ra thư mục nghiên cứu dạng CSV hoặc Parquet, kèm tệp `.meta.json` ghi mã Python tương đương. | *"Lưu bảng BCTC vừa tải với tên `bctc_hpg`."* | | `research_datasets` | Đọc | Liệt kê các bảng đã lưu trên máy, kèm mã tạo ra từng bảng. | *"Tôi đã lưu những bảng nào?"* | | `research_journal` | Tái lập | Xem nhật ký phiên (`method="list"`) hoặc ghép cả phiên thành script Python độc lập (`method="script"`, thêm `save=true` để ghi ra máy). | *"Hãy xuất toàn bộ quy trình phân tích hôm nay thành file script Python."* | | `research_normalize` | Chuẩn hoá | Chuyển bảng thô bạn tự lấy từ nguồn khác mà bạn có quyền dùng sang bảng chuẩn của vnstock (nến, báo cáo tài chính, chỉ số...). Báo cáo tài chính: chỉ giữ kỳ quý, tiền về tỷ VNĐ, cột VAS kèm tên ngắn. Các định dạng được hỗ trợ có trong mô tả tool (tham số `provider`). | *"Chuẩn hoá bảng nến FPT tôi vừa đưa về bảng chuẩn của vnstock."* | | `research_benchmark` | Đối chiếu | So bảng đó với số liệu tham chiếu bạn truy xuất qua vnstock: nến ngày theo độ lệch giá đóng cửa; báo cáo tài chính theo từng quý. Chỉ đọc được phần dữ liệu bản Cộng đồng được mở. | *"Đối chiếu bảng nến vừa chuẩn hoá với số liệu lấy qua vnstock."* | | `research_universe` | Tra cứu | Tra 8 bảng chuẩn và cột của từng bảng, hoặc chỉ tiêu VAS của một báo cáo theo loại hình `DN`, `TCTD`, `CTCK`, `DNPNT`. | *"Bảng cân đối kế toán của ngân hàng có những chỉ tiêu nào?"* |

Từ điển chỉ tiêu VAS dùng cho research_normalize, research_benchmark và research_universe được tải về bộ nhớ khi cần, có chữ ký số, không ghi xuống đĩa. Việc tải cần API key. Bản Cộng đồng nhận bộ từ điển rút gọn. Khi không tải được, công cụ dùng bộ chỉ tiêu mặc định có sẵn và ghi rõ trong trường vas_config của kết quả. Kết quả đối chiếu cho biết hai nguồn có cho cùng con số hay không, không xác nhận con số đúng với báo cáo tài chính gốc.

--- ## 6. Tầng Quant (Tính toán Định lượng - Dùng thử 30 lượt / ngày)

Người dùng bản Cộng đồng có 30 lượt dùng thử / ngày cho các công cụ tính toán bên dưới (làm mới lúc 00:00 giờ Việt Nam). Phép tính cũng được ghi nhận vào quỹ hạn mức chung của tài khoản Vnstock. Từ Bronze, giới hạn dùng thử riêng không áp dụng nhưng quỹ hạn mức chung vẫn áp dụng; xem phạm vi quyền dùng công cụ theo cấp.

| Tên công cụ | Loại | Mô tả chức năng | Prompt mẫu cho Trợ lý AI | | :--- | :---: | :--- | :--- | | `quant_catalog` | Tra cứu | Tra danh mục chỉ báo, chỉ số và công thức của `vnstock_quant`. | *"Thư viện hỗ trợ những chỉ báo kỹ thuật cơ bản nào?"* | | `quant_entitlement` | Tra cứu | Số lượt tính thử còn lại trong ngày. | *"Tôi còn bao nhiêu lượt tính thử hôm nay?"* | | `quant_ta` | Tính toán | 10 chỉ báo kỹ thuật: SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV, VWAP, Pivots. Tính trên dữ liệu bạn truy xuất qua vnstock (`symbol`) hoặc bảng trong phiên (`data="c1"`). | *"Tính RSI(14) và MACD(12,26,9) cho HPG."* | | `quant_fa` | Tính toán | 10 chỉ số tài chính: P/E, P/B, EPS, BVPS, ROE, ROA, biên gộp, biên ròng, thanh toán hiện hành, nợ/vốn chủ. | *"Tính biên lợi nhuận gộp và ROE 8 quý của MSN."* | Mỗi lần tính của `quant_ta`, `quant_fa` trừ một lượt dùng thử ở bản Cộng đồng (mặc định 30 lượt/ngày) và được ghi nhận vào quỹ hạn mức chung. --- ## Các công cụ thuộc bản Mở rộng Từ cấp Bronze ([Danh mục bản Mở rộng](/docs/vnstock-mcp/danh-muc-cong-cu)): - Mọi `method` còn lại của các công cụ dữ liệu: sổ lệnh, thống kê phiên, khối ngoại, tự doanh, lô lẻ, chỉ số tài chính, thuyết minh báo cáo tài chính. - Quỹ mở (`reference_fund`, `market_fund`), vĩ mô (`macro_*`), độ rộng và dòng tiền thị trường (`insights_*`). - Định lượng: đủ bộ chỉ số tài chính, `quant_risk`, `quant_portfolio`, `quant_valuation`; không áp dụng giới hạn dùng thử riêng nhưng vẫn tính vào hạn mức chung. - Từ cấp Silver: bộ chỉ báo kỹ thuật đầy đủ (58 chỉ báo) của `quant_ta`. --- ## Document: Giới thiệu Vnstock MCP (Local) > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Dành cho cá nhân ưa khám phá công nghệ và AI (Claude Code, Antigravity, ChatGPT Codex, Claude Desktop, ChatGPT Desktop, Gemini Tasks) muốn trang bị cho Trợ lý AI cầu nối gọi trực tiếp bộ thư viện công cụ Vnstock ngay trên máy cá nhân — từ kết nối và chuẩn hoá dữ liệu, đối chiếu đa nguồn, tính toán chỉ báo định lượng đến xuất mã Python tái lập trong bản Cộng đồng (miễn phí cho cá nhân, học tập và nghiên cứu).



## Tổng quan `vnstock-mcp` bản Cộng đồng là **công cụ cầu nối chạy hoàn toàn cục bộ trên máy tính cá nhân (Local Tool Bridge)**, giúp các ứng dụng Trợ lý AI (Claude Code, Antigravity, ChatGPT Codex, Claude Desktop, ChatGPT Desktop, Gemini Tasks) gọi trực tiếp bộ thư viện công cụ Vnstock đã cài trên máy thông qua giao thức **Model Context Protocol (MCP)**. Khác với các dịch vụ MCP trực tuyến (online MCP server) phát từ máy chủ từ xa vốn chỉ làm nhiệm vụ nạp dữ liệu vào khung chat, `vnstock-mcp` vận hành như một tiến trình cục bộ do ứng dụng AI trên máy bạn khởi chạy và điều phối công cụ dựa trên **không gian nghiên cứu thiết lập ngay tại máy cá nhân** (`~/vnstock_research`). Mọi bảng dữ liệu trung gian, nhật ký phiên và tệp mã Python tái lập đều nằm trực tiếp trên ổ cứng của bạn. Ở bản Cộng đồng (miễn phí cho cá nhân, học tập và nghiên cứu), Trợ lý AI thấy **29 công cụ** cùng hạn mức **dùng thử định lượng 30 lượt/ngày** để kết nối dữ liệu đầu vào, chuẩn hoá và đối chiếu bảng số liệu, tính toán chỉ báo kỹ thuật – chỉ số tài chính và xuất kịch bản Python chạy độc lập.

Các công cụ, dữ liệu và mô hình phân tích trong vnstock-mcp được cung cấp cho mục đích nghiên cứu, kiểm thử thuật toán và học tập trong môi trường cá nhân của người dùng. Mọi kết quả do Trợ lý AI xử lý từ công cụ không cấu thành tư vấn đầu tư tài chính hay khuyến nghị đầu tư. Quyết định mua bán và việc đối chiếu dữ liệu là của bạn.

--- ## Năng lực của Bản Cộng đồng Bản Cộng đồng cung cấp môi trường làm việc cục bộ cho Trợ lý AI với 4 trụ cột công cụ: ### 1. Kết nối và Chuẩn hoá Dữ liệu Đầu vào (`vnstock`) - **Hồ sơ niêm yết**: Tra cứu thông tin hơn 1.600 mã cổ phiếu trên 3 sàn (HOSE, HNX, UPCoM), phân loại theo ngành chuẩn ICB 4 cấp, danh sách rổ chỉ số VN30, HNX30. - **Báo cáo tài chính**: Đọc Bảng cân đối kế toán, Kết quả kinh doanh, Lưu chuyển tiền tệ theo quý hoặc năm. - **Chỉ số tài chính cơ bản**: Tra cứu P/E, P/B, EPS, ROE, ROA, biên lợi nhuận qua các kỳ. - **Chỉ số vĩ mô & Tâm lý**: Chỉ số vĩ mô cơ bản, dữ liệu mở tài khoản nhà đầu tư mới, thống kê thị trường. ### 2. Dùng thử Định lượng (30 lượt / ngày) - Tính 10 chỉ báo kỹ thuật phổ biến (**SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV, VWAP, Pivots**) qua `quant_ta`. - Tính 10 chỉ số tài chính cơ bản trực tiếp trên BCTC qua `quant_fa`. - Tính trên dữ liệu nến Vnstock hoặc dữ liệu bảng ngoài do bạn nhập vào. - Lượt dùng thử tự động làm mới vào `00:00:00` hàng ngày (giờ Việt Nam). ### 3. Nghiên cứu Tái lập & Đối chiếu Đa nguồn trên Máy Cá nhân - **Lưu bảng trên máy**: Ghi toàn bộ bảng vừa lấy ra thư mục nghiên cứu dạng CSV hoặc Parquet (`research_save`), xem lại danh sách bảng đã lưu (`research_datasets`). - **Chuẩn hoá bảng từ nguồn khác**: Chuyển bảng thô bạn tự lấy từ công cụ hoặc nguồn khác mà bạn có quyền dùng sang cột chuẩn của vnstock (`research_normalize`). - **Đối chiếu với số liệu tham chiếu**: So bảng đó với số liệu bạn truy xuất qua vnstock, theo từng phiên hoặc từng quý (`research_benchmark`), trong phạm vi dữ liệu bản Cộng đồng được mở. - **Tra danh mục chỉ tiêu**: Xem bảng chuẩn và chỉ tiêu VAS theo loại hình doanh nghiệp (`research_universe`). Bản Cộng đồng dùng bộ từ điển chỉ tiêu rút gọn. - **Tự động sinh mã Python tái lập**: Xuất toàn bộ quy trình mà bạn vừa tương tác với AI thành một script Python độc lập để chạy định kỳ (`research_journal`). ### 4. Cơ chế Lọc danh mục công cụ (Tool Filtering) - Lõi Rust tự động kiểm duyệt và chỉ hiển thị đúng **29 công cụ** (hồ sơ `full`) cùng các giá trị `method` được mở cho Trợ lý AI. - Các công cụ thuộc bản Mở rộng (chỉ báo TA đầy đủ, mô hình danh mục, đo lường rủi ro, vĩ mô, dòng tiền thị trường) được ẩn khỏi danh mục công cụ của AI khi chưa kích hoạt khoá có quyền tương ứng. - Hạn chế tình trạng Trợ lý AI gọi nhầm công cụ vượt cấp quyền, giúp giảm thiểu lỗi gián đoạn trong phiên tương tác. --- ## Đối chiếu Bản Cộng đồng và Bản Mở rộng | Tiêu chí | Bản Cộng đồng | Bản Mở rộng (Cấp Bronze → Diamond) | | :--- | :---: | :---: | | **Số lượng công cụ** | **29 công cụ** | **39 công cụ** | | **Quyền sử dụng** | **Bản Cộng đồng miễn phí cho cá nhân, học tập và nghiên cứu** | Các cấp quyền sử dụng dự án (từ Bronze trở lên) | | **Dữ liệu doanh nghiệp & BCTC** | Đầy đủ 3 sàn | Đầy đủ 3 sàn | | **Lịch sử giá nến & Sổ lệnh** | Nến cơ bản theo phiên | Đầy đủ nến OHLCV sâu, sổ lệnh độ sâu, dòng tiền tự doanh & khối ngoại | | **Giới hạn dùng thử Quant** | **30 phép tính / ngày**, đồng thời tính vào hạn mức chung | Không áp dụng từ Bronze; phép tính vẫn tính vào hạn mức chung | | **Chỉ báo kỹ thuật (TA)** | Chỉ báo cơ bản (SMA, EMA, RSI, MACD...) | Các chỉ báo kỹ thuật chuyên sâu của `vnstock_quant` (Ichimoku, SuperTrend, VWAP, CMF, Keltner...) | | **Mô hình Quản trị Rủi ro** | Chưa hỗ trợ | VaR, CVaR, Max Drawdown, Beta, Sharpe, Sortino | | **Tối ưu hóa Danh mục** | Chưa hỗ trợ | Markowitz Efficient Frontier, Risk Parity, Black-Litterman (Cấp Golden và Diamond) | | **Xuất dữ liệu AmiBroker** | Chưa hỗ trợ | Pipeline tự động hóa xuất dữ liệu cho AmiBroker / Excel | | **Mã Python tái lập** | Có | Có | --- ## Bắt đầu ngay 1. Xem [Hướng dẫn Cài đặt và Kết nối](/docs/vnstock-mcp/free/cai-dat-va-ket-noi) để cấu hình Trợ lý AI trong 2 phút. 2. Nắm rõ [Phân quyền và lượt dùng thử](/docs/vnstock-mcp/free/phan-quyen-va-han-muc) để khai thác hiệu quả 30 lượt tính toán hàng ngày. 3. Tra cứu [Danh mục 29 Công cụ](/docs/vnstock-mcp/free/danh-muc-cong-cu) kèm câu lệnh mẫu dành riêng cho bạn. --- ## Document: Lịch sử phiên bản > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. ## 12-10-2026 ### vnstock_mcp (v0.4.0) #### Bản đầu tiên có tài liệu - **Cầu nối chạy cục bộ**: Trợ lý AI trên máy bạn khởi chạy tiến trình `vnstock-mcp` từ môi trường Python cá nhân; không có máy chủ trung gian đứng giữa. - **Kết nối bằng một lệnh**: `vnstock-mcp --setup <ứng dụng>` in sẵn cấu hình cho Claude Desktop, ChatGPT desktop, Gemini Tasks, Claude Code, Codex, Antigravity, VS Code và Cursor; thêm `--write` để ghi thẳng vào tệp cấu hình. - **Mã tham chiếu và mã Python tái lập**: Mỗi kết quả lưu trong không gian làm việc cục bộ kèm mã `call_id` (`c1`, `c2`...) và ghi vào nhật ký phiên. `research_journal(method="script")` xuất các bước đã chạy thành một tệp Python độc lập. - **Công cụ nghiên cứu**: `research_normalize` chuẩn hoá bảng về cột chuẩn của Vnstock, `research_benchmark` đối chiếu số liệu, `research_universe` tra danh mục chỉ tiêu VAS. Các mô-đun `vnstock_quant` gọi được trên bảng đã chuẩn hoá qua `data="c1"`. - **Lọc công cụ theo hồ sơ và quyền**: Trợ lý AI chỉ thấy công cụ khả dụng với tài khoản và hồ sơ (`--profile`) bạn chọn. - **Số công cụ và dùng thử**: Bản Cộng đồng mở 29 công cụ (hồ sơ `full`) hoặc 21 (hồ sơ `research`), kèm 30 lượt dùng thử định lượng mỗi ngày. --- ## Document: Phân quyền và lượt dùng thử > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Toàn bộ cơ chế thẩm định quyền truy cập của vnstock-mcp được thực hiện trực tiếp bởi lõi Rust nguyên khối, kết nối tĩnh với hệ thống phân quyền chuẩn Gen 5. Không có bất kỳ logic phân quyền nào phụ thuộc vào mã nguồn Python hay có thể bị can thiệp trái phép.



## Tổng quan Vì `vnstock-mcp` là cầu nối cục bộ để Trợ lý AI gọi bộ thư viện Vnstock ngay trên máy cá nhân của bạn, danh mục công cụ hiển thị cho AI đi theo đúng bản phần mềm và quyền sử dụng của tài khoản đối với từng thư viện bên dưới. Với **bản Cộng đồng** (miễn phí cho cá nhân, học tập và nghiên cứu), Trợ lý AI thấy **29 công cụ** (hồ sơ `full`; 21 công cụ ở hồ sơ mặc định `research`) cùng chính sách **dùng thử định lượng 30 lượt/ngày**. --- ## 1. Quyền hạn của Bản Cộng đồng | Nhóm chức năng | Số lượng công cụ | Quyền hạn chi tiết | | :--- | :---: | :--- | | **Tham chiếu và danh mục** | 8 công cụ | Danh sách mã theo sàn, nhóm, ngành ICB; chỉ số và cổ phiếu thành phần; ETF, phái sinh, chứng quyền, trái phiếu; lịch sự kiện và ngày nghỉ; trạng thái phiên; tìm mã quốc tế; hồ sơ doanh nghiệp niêm yết. | | **Giá và giao dịch** | 9 công cụ | Nến, khớp lệnh, giá hiện tại của cổ phiếu, ETF, phái sinh, chứng quyền; nến chỉ số, tiền mã hoá, ngoại tệ, hàng hoá; bảng giá nhiều mã. | | **Báo cáo tài chính và tỷ giá** | 2 công cụ | Ba báo cáo tài chính (8 kỳ gần nhất); tỷ giá ngoại tệ niêm yết tại ngân hàng. | | **Không gian Nghiên cứu Cục bộ** | 6 công cụ | Lưu bảng ra máy (`research_save`), xem bảng đã lưu (`research_datasets`), nhật ký và script Python tái lập (`research_journal`), chuẩn hoá bảng từ nguồn khác (`research_normalize`), đối chiếu với số liệu tham chiếu qua vnstock (`research_benchmark`), tra danh mục chỉ tiêu VAS rút gọn (`research_universe`). Có ở mọi cấp. | | **Dùng thử Định lượng (Quant Trial)** | 4 công cụ | Mặc định **30 lượt / ngày** cho 10 chỉ báo kỹ thuật (`quant_ta`) và 10 chỉ số tài chính (`quant_fa`); tra cứu danh mục (`quant_catalog`) và lượt còn lại (`quant_entitlement`) không tính lượt. | | **Tổng cộng** | **29 công cụ** | **Dành cho cá nhân, học tập và nghiên cứu** | --- ## 2. Chính sách Dùng thử Quant Hàng ngày (30 lượt / ngày) Nhằm khuyến khích cộng đồng tiếp cận phương pháp nghiên cứu và phân tích định lượng khoa học, `vnstock-mcp` cấp quyền dùng thử định lượng hàng ngày cho người dùng bản Cộng đồng: - **Lượt dùng thử**: mặc định **30 lượt tính toán / ngày**, dùng chung cho hai công cụ: - `quant_ta` với 10 chỉ báo cơ bản (SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV, VWAP, Pivots); - `quant_fa` với 10 chỉ số tài chính cơ bản (P/E, P/B, EPS, BVPS, ROE, ROA, biên gộp, biên ròng, thanh toán hiện hành, nợ/vốn chủ). - Số lượt còn lại xem bằng `quant_entitlement`. - **Dữ liệu linh hoạt**: Bạn có thể dùng 30 lượt này để tính trên dữ liệu nến Vnstock **HOẶC** tính trên dữ liệu do bạn tự nhập, dữ liệu file CSV, hay dữ liệu từ nguồn khác bạn có quyền dùng. - **Tự động làm mới**: Bộ đếm lượt dùng thử tự động làm mới vào lúc `00:00:00` hàng ngày theo giờ Việt Nam (UTC+7). --- ## 3. Cơ chế Lọc danh mục công cụ (Tool Filtering) Một trong những hạn chế khi dùng MCP với các Trợ lý AI là hiện tượng AI có thể gọi nhầm các công cụ vượt cấp quyền sử dụng của người dùng, dẫn đến chuỗi lỗi phản hồi và làm gián đoạn trải nghiệm người dùng. `vnstock-mcp` giải quyết vấn đề này bằng cơ chế **Lọc danh mục công cụ (Tool Filtering)** ngay tại tầng Rust: ``` ┌────────────────────────────────┐ │ Cấp quyền người dùng: FREE │ └───────────────┬────────────────┘ │ _native.get_enabled_tools() │ ▼ ┌────────────────────────────────────────────────────────┐ │ Rust Core: Duyệt 39 công cụ theo catalog │ │ • method có route mở cho Free --> CẤP PHÉP │ │ • tool không còn method nào --> ẨN KHỎI DANH MỤC │ └───────────────────────────┬────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ FastMCP server: Mount ĐÚNG 29 CÔNG CỤ vào tools/list │ └───────────────────────────┬────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Trợ lý AI chỉ nhìn thấy 29 công cụ hợp lệ │ │ ==> HẠN CHẾ NGUY CƠ GỌI SAI CÔNG CỤ │ └────────────────────────────────────────────────────────┘ ``` Trợ lý AI chỉ nhận được danh sách 29 công cụ (và đúng các giá trị `method` được mở) thuộc phạm vi cấp quyền, giúp giảm thiểu lỗi gọi nhầm công cụ và tăng độ ổn định của phiên làm việc. --- ## 4. Các cấp quyền sử dụng trong bản Mở rộng Khi nhu cầu nghiên cứu và phân tích của bạn mở rộng ra các bài toán chuyên sâu, bạn có thể tham gia gói quyền sử dụng dự án để kích hoạt thêm các công cụ định lượng: - **Cấp Bronze (39 công cụ)**: - Mọi giá trị `method` của các công cụ dữ liệu: sổ lệnh, thống kê phiên, khối ngoại, tự doanh, chỉ số tài chính, thuyết minh; quỹ mở, vĩ mô, độ rộng và dòng tiền thị trường. - Định lượng không áp dụng giới hạn dùng thử riêng nhưng vẫn tính vào hạn mức chung của tài khoản: đủ bộ chỉ số tài chính, rủi ro (`quant_risk`), danh mục (`quant_portfolio`), định giá (`quant_valuation`). - **Cấp Silver, Golden, Diamond (39 công cụ)**: - Toàn bộ quyền của Bronze, thêm bộ chỉ báo kỹ thuật đầy đủ (58 chỉ báo) của `quant_ta`. Tham khảo chi tiết tại trang [Phân quyền và cấp quyền sử dụng](/docs/vnstock-mcp/phan-quyen-va-cap-tai-tro) hoặc [Bảng giá](/pricing). --- ## Tiếp theo - Khám phá chi tiết [Danh mục 29 Công cụ](/docs/vnstock-mcp/free/danh-muc-cong-cu) dành cho bản Cộng đồng. --- ## Document: Giới thiệu Vnstock MCP > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Dành cho cá nhân ưa khám phá công nghệ và AI, người làm nghiên cứu độc lập và lập trình viên sử dụng các ứng dụng Trợ lý AI (như Claude, ChatGPT, Antigravity) muốn để AI trực tiếp gọi bộ thư viện công cụ Vnstock ngay trên máy tính cá nhân — từ kết nối, chuẩn hoá và đối chiếu dữ liệu, tính toán định lượng đến xuất mã Python tái lập.



## Tổng quan `vnstock-mcp` (bản `0.4.x`, ra mắt trong đợt phát hành Vnstock thế hệ 5) là **công cụ cầu nối chạy hoàn toàn cục bộ trên máy cá nhân (Local Tool Bridge)**, giúp các Trợ lý AI gọi trực tiếp bộ thư viện công cụ của Vnstock đã cài đặt trên máy bạn (`vnstock` v5.x, `vnstock_quant` v0.3.x, `vnstock_pipeline` v3.x, `vnstock_news` v3.x) thông qua chuẩn giao thức Model Context Protocol (MCP). Trên thị trường hiện nay, nhiều dịch vụ MCP tài chính hoặc chứng khoán thường được triển khai dưới dạng **máy chủ trực tuyến (Online/Remote MCP Server)** với vai trò đơn thuần là phát dữ liệu từ máy chủ vào khung chat. `vnstock-mcp` được thiết kế theo hướng tiếp cận hoàn toàn khác: 1. **Vận hành cục bộ (Local), không phát qua máy chủ từ xa**: Ứng dụng AI trên máy bạn trực tiếp khởi chạy tiến trình `vnstock-mcp` từ môi trường Python cá nhân (`.venv`). Không có máy chủ MCP trung gian nào đứng giữa để lưu trữ hay phát lại dữ liệu của bạn. 2. **Gọi trọn bộ thư viện công cụ, không chỉ nạp dữ liệu**: Kết nối dữ liệu đầu vào chỉ là bước khởi đầu. Qua `vnstock-mcp`, Trợ lý AI gọi các hàm chuẩn hoá bảng dữ liệu đa nguồn về cấu trúc chuẩn, đối chiếu số liệu tham chiếu, tính toán chỉ báo kỹ thuật, chỉ số tài chính, rủi ro và danh mục bằng `vnstock_quant`. 3. **Điều phối ngay trong không gian nghiên cứu trên máy cá nhân**: Mọi bảng kết quả được quản lý trong thư mục nghiên cứu cá nhân (`~/vnstock_research`) kèm mã tham chiếu (`call_id`), cho phép AI nối tiếp nhiều bước tính toán trên bảng đầy đủ mà không làm tràn ngữ cảnh trò chuyện, đồng thời kết xuất toàn bộ phiên làm việc thành tệp mã Python chạy độc lập.

Các công cụ, dữ liệu và mô hình phân tích trong vnstock-mcp được cung cấp cho mục đích nghiên cứu, học tập và kiểm thử trong môi trường cá nhân của người dùng. Mọi kết quả do Trợ lý AI xử lý từ công cụ không cấu thành tư vấn đầu tư tài chính hay khuyến nghị đầu tư. Quyết định mua bán và đối chiếu dữ liệu là của bạn.

--- ## Vnstock MCP (Local) là gì và không là gì Bảng đối chiếu dưới đây làm rõ sự khác biệt giữa kiến trúc cầu nối công cụ cục bộ của `vnstock-mcp` và các dịch vụ MCP nạp dữ liệu trực tuyến: | Tiêu chí | Vnstock MCP (Local) là | Vnstock MCP (Local) không phải là | | :--- | :--- | :--- | | **Vai trò cốt lõi** | **Cầu nối công cụ (Tool Bridge)** giúp Trợ lý AI gọi trực tiếp bộ thư viện Vnstock (`vnstock`, `vnstock_quant`...) và bộ công cụ nghiên cứu trên máy bạn | Cổng nạp dữ liệu thụ động chỉ đẩy bảng số liệu từ máy chủ từ xa vào khung chat | | **Mô hình vận hành** | Tiến trình **chạy hoàn toàn cục bộ (Local)** từ môi trường Python cá nhân, gắn với không gian nghiên cứu trên máy bạn (`~/vnstock_research`) | Dịch vụ MCP trực tuyến (Online/Remote MCP Server) phát qua máy chủ đám mây hay chatbot web | | **Xử lý & Tính toán** | Truyền bảng qua mã tham chiếu `call_id` ngay trên máy để AI gọi tiếp các bước chuẩn hoá, đối chiếu và tính toán định lượng (`vnstock_quant`) | Nơi chỉ trả văn bản tóm tắt cuối cùng mà không giữ lại dữ liệu trung gian và công thức | | **Quy trình phân tích** | Ghi nhận từng lệnh gọi hàm trong nhật ký phiên cục bộ và kết xuất thành tệp mã nguồn Python độc lập để kiểm chứng hoặc tự động hoá | Cuộc trò chuyện rời rạc trôi mất sau khi đóng cửa sổ chat | | **Phân quyền công cụ** | Lọc danh mục công cụ hiển thị ngay từ lõi Rust theo đúng hồ sơ và quyền sử dụng của tài khoản trên máy bạn | Danh mục mở tràn lan khiến AI gọi nhầm các hàm ngoài phạm vi quyền | | **Dữ liệu thị trường** | Phần mềm chạy trên máy bạn để tự kết nối và xử lý dữ liệu trong phạm vi được phép; không vận hành kho dữ liệu trung chuyển | Đơn vị lưu trữ tập trung, tái phân phối hay kinh doanh dữ liệu thị trường | --- ## Các đặc điểm kiến trúc và tính năng chính ### 1. Điều phối công cụ trên máy cá nhân và xuất mã Python tái lập Mỗi khi Trợ lý AI gọi một hàm lấy dữ liệu hoặc tính toán, kết quả được lưu giữ trong không gian làm việc cục bộ kèm mã tham chiếu (`call_id`: `c1`, `c2`...) và ghi vào nhật ký phiên (`journal/.jsonl`) cùng dòng lệnh Python tương đương. Khi quy trình phân tích trong phiên trò chuyện đã hoàn chỉnh, bạn có thể yêu cầu Trợ lý AI gọi `research_journal(method="script")` để trích xuất một tệp mã nguồn Python độc lập. Tệp mã này sử dụng trực tiếp các thư viện chuẩn (`vnstock`, `vnstock_quant`, `pandas`), giúp bạn kiểm chứng lại từng bước hoặc đưa vào lịch trình chạy tự động trên máy. ### 2. Chuẩn hoá, đối chiếu đa nguồn và tính toán định lượng Không dừng ở việc đọc dữ liệu từ một nguồn cố định, `vnstock-mcp` cho phép Trợ lý AI phối hợp các công cụ xử lý và định lượng trên cả dữ liệu bạn tự mang vào từ công cụ hoặc nguồn khác mà bạn có quyền dùng: - Chuyển bảng thô sang cấu trúc cột chuẩn của Vnstock (cột VAS, tiền tính bằng tỷ VNĐ, chuẩn hoá kỳ quý với báo cáo tài chính) qua công cụ `research_normalize`. - Đối chiếu từng phiên, từng quý với số liệu tham chiếu bạn truy xuất qua `vnstock` bằng công cụ `research_benchmark` ("khớp" nghĩa là hai nguồn cho cùng con số, không phải lời bảo đảm con số đúng tuyệt đối). - Tra danh mục bảng chuẩn và chỉ tiêu VAS theo loại hình doanh nghiệp qua công cụ `research_universe`. - Gọi các mô-đun của `vnstock_quant` (`quant_ta`, `quant_fa`, `quant_risk`, `quant_portfolio`, `quant_valuation`) trực tiếp trên bảng đã chuẩn hoá thông qua tham số `data="c1"`. Chi tiết: [Nghiên cứu Tái lập và Đa nguồn](/docs/vnstock-mcp/nghien-cuu-tai-lap-va-da-nguon). ### 3. Lọc danh mục công cụ theo hồ sơ và quyền sử dụng Để tránh việc Trợ lý AI nhìn thấy quá nhiều hàm hoặc gọi nhầm các tính năng ngoài phạm vi tài khoản gây gián đoạn phiên làm việc, lõi Rust của `vnstock-mcp` lọc danh mục công cụ ngay tại bước khởi tạo `tools/list`. Trợ lý AI chỉ nhìn thấy đúng những công cụ và phương thức (`method`) khả dụng với tài khoản và hồ sơ (`--profile`) bạn đã chọn trên máy. ### 4. Thiết lập kết nối cục bộ bằng một lệnh Lệnh `vnstock-mcp --setup <ứng dụng>` tự động kiểm tra đường dẫn môi trường ảo trên máy bạn và in sẵn cấu hình chuẩn cho từng ứng dụng (Claude Desktop, ChatGPT desktop, Gemini Tasks, Claude Code, Codex, Antigravity, VS Code, Cursor); thêm cờ `--write` để thư viện tự ghi cấu hình kèm bản sao lưu. Xem [Cài đặt và Kết nối](/docs/vnstock-mcp/cai-dat-va-ket-noi). --- ## Document: Lịch sử phiên bản > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu. Nhãn **[Mở rộng]** đánh dấu phần chỉ có ở bản Mở rộng, nhãn **[Cộng đồng]** đánh dấu phần chỉ đúng với bản Cộng đồng. Phần không gắn nhãn đúng ở cả hai bản. Trang tổng hợp của từng bản lấy thay đổi từ tệp này theo nhãn. ## 12-10-2026 (v0.4.0) ### Bản đầu tiên có tài liệu - **Cầu nối chạy cục bộ**: Trợ lý AI trên máy bạn khởi chạy tiến trình `vnstock-mcp` từ môi trường Python cá nhân; không có máy chủ trung gian đứng giữa. - **Kết nối bằng một lệnh**: `vnstock-mcp --setup <ứng dụng>` in sẵn cấu hình cho Claude Desktop, ChatGPT desktop, Gemini Tasks, Claude Code, Codex, Antigravity, VS Code và Cursor; thêm `--write` để ghi thẳng vào tệp cấu hình. - **Mã tham chiếu và mã Python tái lập**: Mỗi kết quả lưu trong không gian làm việc cục bộ kèm mã `call_id` (`c1`, `c2`...) và ghi vào nhật ký phiên. `research_journal(method="script")` xuất các bước đã chạy thành một tệp Python độc lập. - **Công cụ nghiên cứu**: `research_normalize` chuẩn hoá bảng về cột chuẩn của Vnstock, `research_benchmark` đối chiếu số liệu, `research_universe` tra danh mục chỉ tiêu VAS. Các mô-đun `vnstock_quant` gọi được trên bảng đã chuẩn hoá qua `data="c1"`. - **Lọc công cụ theo hồ sơ và quyền**: Trợ lý AI chỉ thấy công cụ khả dụng với tài khoản và hồ sơ (`--profile`) bạn chọn. - **[Cộng đồng]** **Số công cụ và dùng thử**: Bản Cộng đồng mở 29 công cụ (hồ sơ `full`) hoặc 21 (hồ sơ `research`), kèm 30 lượt dùng thử định lượng mỗi ngày. - **[Mở rộng]** **Số công cụ theo cấp**: Từ cấp Bronze mở 39 công cụ (hồ sơ `full`) hoặc 29 (hồ sơ `research`); bộ 58 chỉ báo kỹ thuật đầy đủ mở từ cấp Silver. Chi tiết ở [phân quyền và cấp quyền sử dụng](/docs/vnstock-mcp/phan-quyen-va-cap-tai-tro). --- ## Document: Nghiên cứu Tái lập và Đa nguồn > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Trong quá trình nghiên cứu dữ liệu, khả năng lưu lại các bước thực thi và chạy lại kết quả giúp bạn dễ dàng kiểm chứng lại các giả định phân tích mà không cần lặp lại toàn bộ các câu lệnh thủ công với Trợ lý AI.



## Tổng quan Điểm khác biệt cốt lõi giữa `vnstock-mcp` và các dịch vụ MCP chỉ nạp dữ liệu vào khung chat nằm ở **không gian nghiên cứu cục bộ thiết lập ngay trên máy cá nhân của bạn**. Thay vì đổ toàn bộ bảng số liệu thô qua lại trong cuộc trò chuyện, `vnstock-mcp` giữ các bảng dữ liệu trong không gian làm việc cục bộ để Trợ lý AI lần lượt gọi các công cụ chuẩn hoá, đối chiếu, tính toán định lượng (`vnstock_quant`) và kết xuất thành tệp mã Python tái lập. Sáu công cụ `research_*` dưới đây cấu thành lớp điều phối phiên nghiên cứu của `vnstock-mcp` và luôn mở ở mọi hồ sơ công cụ cũng như mọi cấp tài khoản (kể cả bản Cộng đồng): | Công cụ | Việc làm | | :------------------- | :--------------------------------------------------------------------------- | | `research_save` | Ghi toàn bộ một bảng vừa lấy (theo `call_id`) ra thư mục nghiên cứu trên máy | | `research_datasets` | Liệt kê các bảng đã lưu, kèm mã Python tạo ra từng bảng | | `research_journal` | Xem nhật ký phiên, hoặc ghép cả phiên thành một script Python chạy lại được | | `research_normalize` | Chuyển bảng thô bạn tự lấy từ nguồn khác sang cột chuẩn của vnstock | | `research_benchmark` | Đối chiếu bảng đó với số liệu tham chiếu bạn truy xuất qua vnstock | | `research_universe` | Tra danh mục bảng chuẩn và chỉ tiêu VAS theo loại hình doanh nghiệp | *** ## Thư mục nghiên cứu và `call_id` Mỗi lần một công cụ trả về bảng, kết quả mang một mã tham chiếu `call_id` (`c1`, `c2`...) và một dòng nhật ký gồm mã Python tương đương, số dòng và nguồn gốc. Bước sau dùng lại bảng của bước trước bằng `data="c1"`, không cần chép số. Trợ lý AI chỉ thấy các dòng gần nhất (mặc định 60 dòng); phép tính luôn chạy trên bảng đầy đủ. Thư mục nghiên cứu mặc định là `~/vnstock_research` (đổi bằng biến `VNSTOCK_MCP_WORKSPACE`): ```text ~/vnstock_research/ ├── journal/.jsonl một dòng cho mỗi lần gọi công cụ thành công ├── data/.csv | .parquet bảng do research_save ghi, kèm .meta.json └── scripts/.py script tái lập do research_journal(save=true) ghi ``` Ở tham số `data`, bạn có thể truyền `call_id` hoặc tên một bảng trong thư mục `data/`. Một tệp CSV bạn tự đặt vào `data/` cũng dùng được theo tên. *** ## Quy trình làm việc đa nguồn ```markdown ┌────────────────────────────────────────────────────────┐ │ Trợ lý AI (Claude Code / Antigravity / Claude) │ └───────┬────────────────────────┬───────────────────────┘ │ 1. Bảng thô │ 2. Số liệu tham chiếu ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ Nguồn khác bạn│ │ vnstock-mcp │ │ có quyền dùng │ │ (qua vnstock) │ └───────┬───────┘ └───────┬───────┘ │ │ ▼ ▼ ┌────────────────────────────────────────────────────────┐ │ vnstock-mcp trên máy bạn │ │ • research_normalize: đưa bảng thô về cột chuẩn │ │ • research_benchmark: đối chiếu từng phiên, từng quý │ │ • quant_* : tính trên bảng qua call_id │ │ • research_journal : sinh script Python tái lập │ └────────────────────────────────────────────────────────┘ ``` *** ## Kịch bản 1: Lưu bảng ra máy **Prompt mẫu cho Trợ lý AI:** > *"Lấy nến ngày 5 năm của FPT rồi lưu toàn bộ bảng ra máy với tên fpt_ohlcv_5y."* Trợ lý AI gọi công cụ dữ liệu (nhận `call_id: "c1"`), rồi gọi `research_save`: ```json { "call_id": "c1", "name": "fpt_ohlcv_5y", "format": "csv" } ``` Bảng được ghi đầy đủ vào `~/vnstock_research/data/fpt_ohlcv_5y.csv`, không bị cắt ở giới hạn số dòng hiển thị. Tệp `fpt_ohlcv_5y.meta.json` đi kèm ghi mã Python tương đương, thời điểm lưu và nguồn gốc. Định dạng `parquet` cần cài thêm `pyarrow`. Lưu trùng tên cần `overwrite: true`. *** ## Kịch bản 2: Chuẩn hoá bảng thô từ nguồn khác Bạn có một bảng thô tự lấy từ công cụ hoặc nguồn khác mà bạn có quyền dùng. `research_normalize` chuyển bảng đó sang cột chuẩn của vnstock để đưa vào các công cụ `quant_*` hoặc đối chiếu ở Kịch bản 3. **Prompt mẫu cho Trợ lý AI:** > *"Đây là báo cáo tài chính theo quý của FPT tôi lấy từ nguồn khác. Chuẩn hoá về bảng chuẩn của vnstock giúp tôi."* ```json { "data": "[{\"year\": 2026, \"quarter\": 2, ...}]", "dataset": "fundamental.financial_statement", "provider": "auto", "symbol": "FPT" } ``` | Tham số | Ý nghĩa | | :--------- | :------------------------------------------------------------------------------------------------------------------------- | | `data` | Bảng thô (chuỗi JSON, object, danh sách) hoặc `call_id`, tên bảng đã lưu | | `dataset` | Bảng chuẩn đích, xem danh sách bên dưới | | `provider` | Định dạng của bảng thô. `auto` (mặc định) tự nhận diện; các định dạng được hỗ trợ có trong mô tả tool (tham số `provider`) | | `symbol` | Mã cổ phiếu, khi bảng thô không có cột mã | **Bảng chuẩn đích (`dataset`):** | Mã bảng | Nội dung | | :-------------------------------- | :------------------------------------------------------- | | `equity.ohlcv_daily` | Nến ngày: `symbol, time, open, high, low, close, volume` | | `equity.ohlcv_intraday` | Nến trong phiên, cùng cột với nến ngày | | `equity.foreign_flow` | Giao dịch khối ngoại: giá trị, khối lượng mua, bán, ròng | | `fundamental.financial_statement` | Báo cáo tài chính theo quý, một dòng mỗi quý | | `fundamental.ratio_quarterly` | Chỉ số tài chính theo quý | | `index.market_breadth` | Độ rộng thị trường: số mã tăng, giảm, đứng giá | | `macro.commodity` | Giá hàng hoá | | `macro.interest_rate` | Lãi suất theo kỳ hạn | **Quy tắc với báo cáo tài chính và chỉ số tài chính:** * **Chỉ giữ kỳ quý.** Dòng luỹ kế 6 tháng, 9 tháng và dòng cả năm bị bỏ, không gán lại thành quý. Số dòng bị bỏ ghi trong phần kiểm tra của kết quả. * **Tiền về tỷ VNĐ.** Đơn vị được quyết định một lần cho cả bảng (bảng ghi bằng đồng hay bằng tỷ đồng), để một dòng giá trị nhỏ không bị quy đổi lệch so với phần còn lại. * **Cột VAS kèm tên gọi ngắn.** Mỗi chỉ tiêu có cột theo mã VAS (ví dụ `bs_short_term_borrowings`) và cột tên ngắn (`short_debt`). Từ điển song ngữ Việt, Anh của từng cột đi kèm kết quả. * **Cột ngoài VAS có `formula`.** Chỉ tiêu không có mã VAS tương ứng mang công thức tính rõ ràng, ví dụ `core_operating_profit` = lợi nhuận gộp − chi phí bán hàng − chi phí quản lý doanh nghiệp. * **Tỷ số "%" là phân số.** ROE 0,2647 nghĩa là 26,47%; từ điển ghi `value_scale: fraction`. **ROE, ROA tự tính theo định nghĩa cố định.** Cùng tên "ROE", các nguồn có thể công bố theo những cách tính khác nhau. Vì vậy tỷ số từ nguồn ngoài được đặt vào cột mang tên định nghĩa của nó, không gán vào mã VAS có định nghĩa khác. Với báo cáo tài chính có đủ chỉ tiêu, `vnstock-mcp` tự tính thêm: | Cột | Định nghĩa | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------- | | `roe_ttm_avg2_parent` | LNST của cổ đông công ty mẹ 4 quý gần nhất / bình quân vốn chủ sở hữu của cổ đông mẹ tại đầu và cuối giai đoạn 4 quý | | `roe_ttm_avg4_parent` | LNST của cổ đông công ty mẹ 4 quý gần nhất / bình quân vốn chủ sở hữu của cổ đông mẹ tại 4 thời điểm cuối quý gần nhất | | `roa_ttm_avg2` | LNST của cổ đông công ty mẹ 4 quý gần nhất / bình quân tổng tài sản tại đầu và cuối giai đoạn 4 quý | Vốn chủ sở hữu của cổ đông mẹ = vốn chủ sở hữu − lợi ích cổ đông không kiểm soát. Kết quả có `call_id` riêng để đưa vào `quant_ta`, `quant_fa`, `quant_risk`, và được ghi vào nhật ký dưới dạng mã Python chạy lại được (`vnstock_mcp.normalize.normalize_dataset(...)`). *** ## Kịch bản 3: Đối chiếu với số liệu tham chiếu `research_benchmark` so bảng của nguồn khác với số liệu tham chiếu bạn truy xuất qua vnstock cho cùng mã. Số liệu tham chiếu này cũng là một nguồn đã công bố, không phải bản báo cáo tài chính nộp cơ quan quản lý. "Khớp" nghĩa là hai nguồn cho cùng con số, không phải bảo đảm con số đúng. **Prompt mẫu cho Trợ lý AI:** > *"Đối chiếu báo cáo tài chính FPT tôi vừa chuẩn hoá với số liệu lấy qua vnstock, xem chỉ tiêu nào lệch."* ```json { "symbol": "FPT", "data": "c2", "dataset": "fundamental.financial_statement", "provider": "auto" } ``` **Với nến ngày (`equity.ohlcv_daily`):** số liệu tham chiếu là nến ngày 1 năm gần nhất. Kết quả so các phiên chung: độ lệch giá đóng cửa trung vị và lớn nhất (kèm ngày), tỷ lệ khối lượng, và ghi chú. | `status` | Nghĩa | | :---------- | :-------------------------------------------------------------------------- | | `OK` | Giá đóng cửa lệch trung vị dưới 0,1% | | `WARNING` | Lệch trung vị từ 0,1% đến dưới 1% | | `DIVERGENT` | Lệch trung vị từ 1% trở lên, nên kiểm tra cách điều chỉnh giá của hai nguồn | | `FAIL` | Không có phiên nào trùng ngày | **Với báo cáo tài chính và chỉ số (`fundamental.*`):** đối soát từng chỉ tiêu, từng quý. * Một chỉ tiêu là `MATCHED` khi có **ít nhất 4 quý chung** và **mọi quý** lệch không quá max(0,5%, nửa đơn vị làm tròn cuối cùng của nguồn). Ví dụ nguồn ghi số tỷ đồng làm tròn đến hàng đơn vị thì sai số làm tròn ±0,5 tỷ được chấp nhận. * Một chỉ tiêu là `DEVIATION` khi có quý vượt ngưỡng. Kết quả có thể kèm `suggested_matches`: mã chỉ tiêu khác **trong cùng báo cáo** thoả cùng quy tắc, để bạn xem lại cách ánh xạ. * Chỉ tiêu ngoài VAS (như các cột ROE, ROA ở trên) được so với chuỗi tính theo đúng công thức đó trên báo cáo tài chính lấy qua vnstock. * Các trạng thái khác của từng chỉ tiêu: `INSUFFICIENT_OVERLAP` (dưới 4 quý chung), `NO_GROUND_TRUTH` (không có số liệu tham chiếu cho mã đó), `NOT_IN_VAS`. | `status` của cả bảng | Nghĩa | | :------------------- | :-------------------------------------------------------- | | `VERIFIED` | Mọi chỉ tiêu kiểm được đều khớp | | `PARTIALLY_VERIFIED` | Có chỉ tiêu khớp, có chỉ tiêu chưa đủ dữ liệu để kết luận | | `DEVIATIONS_FOUND` | Có ít nhất một chỉ tiêu lệch | | `INSUFFICIENT_DATA` | Chưa chỉ tiêu nào đủ dữ liệu để kết luận khớp | Trường `ground_truth_source` cho biết nguồn đứng sau số liệu tham chiếu. Trường `rules` ghi lại ngưỡng đã dùng để bạn kiểm tra lại.
Xem kết quả đối soát mẫu (rút gọn) ```json { "symbol": "FPT", "dataset": "fundamental.financial_statement", "status": "PARTIALLY_VERIFIED", "rules": { "min_quarters": 4, "rel_tolerance_pct": 0.5, "every_quarter_must_match": true, "suggestions_within_same_statement": true }, "counts": { "MATCHED": 18, "INSUFFICIENT_OVERLAP": 2 }, "metrics": [ { "canonical_col": "bs_short_term_borrowings", "overlapping_quarters": 8, "max_diff_pct": 0.0, "verdict": "MATCHED" } ] } ```
Việc đọc số liệu tham chiếu đi qua `vnstock` như mọi lời gọi khác, nên theo đúng quyền và hạn mức cấp quyền sử dụng của bạn (hoặc bản Cộng đồng). *** ## Kịch bản 4: Tra danh mục bảng chuẩn và chỉ tiêu VAS `research_universe` giúp Trợ lý AI biết bảng chuẩn có những cột nào và báo cáo tài chính có những chỉ tiêu nào, trước khi chuẩn hoá hay đối chiếu. | `category` | Trả về | | :-------------------------------------------------------- | :------------------------------------------------------------------------- | | `catalog` (mặc định) | 8 bảng chuẩn ở Kịch bản 2 và cột của từng bảng | | `vas` | Tổng quan từ điển VAS: số chỉ tiêu mỗi báo cáo, các loại hình doanh nghiệp | | `income_statement`, `balance_sheet`, `cash_flow`, `ratio` | Chỉ tiêu của một báo cáo theo thứ bậc, cho một loại hình doanh nghiệp | Tham số `company_type`: `DN` (doanh nghiệp), `TCTD` (ngân hàng), `CTCK` (công ty chứng khoán), `DNPNT` (bảo hiểm). Mỗi lần gọi chỉ trả một phần nhỏ, không trả toàn bộ từ điển. **Prompt mẫu cho Trợ lý AI:** > *"Bảng cân đối kế toán của ngân hàng có những chỉ tiêu nào theo VAS?"* ```json { "category": "balance_sheet", "company_type": "TCTD" } ```

Từ điển chỉ tiêu VAS được tải về bộ nhớ khi cần, có chữ ký số, không ghi xuống đĩa. Việc tải cần API key của tài khoản Vnstock. Tài khoản bản Cộng đồng nhận bộ từ điển rút gọn. Khi không tải được, công cụ dùng bộ chỉ tiêu mặc định có sẵn và ghi rõ trong trường vas_config của kết quả.

*** ## Kịch bản 5: Chạy thuật toán Quant trên dữ liệu ngoài Bảng đã chuẩn hoá (hoặc bảng đã lưu) đưa thẳng vào các công cụ `quant_*` qua tham số `data`: **Prompt mẫu cho Trợ lý AI:** > *"Tính SMA 20 và RSI 14 trên bảng nến tôi vừa chuẩn hoá."* ```json { "indicator": "sma", "data": "c3", "length": 20 } ``` Kết quả có `call_id` mới (ví dụ `c4`) để dùng tiếp. Với tài khoản bản Cộng đồng, phép tính này tính vào lượt dùng thử hằng ngày của `vnstock_quant`; ở mọi cấp, phép tính còn được ghi nhận vào quỹ hạn mức chung của tài khoản Vnstock. *** ## Kịch bản 6: Sinh mã Python tái lập **Prompt mẫu cho Trợ lý AI:** > *"Xuất cho tôi một file Python độc lập tái lập quy trình vừa rồi để tôi tự chạy lại."* Trợ lý AI gọi `research_journal`: ```json { "method": "script", "save": true } ``` `method: "list"` trả nhật ký phiên dạng bảng. `method: "script"` ghép cả phiên thành một script; thêm `save: true` để ghi ra `scripts/.py`.
Xem mẫu script được sinh ra ```python """Tái lập phiên nghiên cứu 20261013_091502. Sinh bởi vnstock-mcp 0.4.0 với vnstock 5.0.0. Mỗi khối là một lần trợ lý AI gọi tool; đọc, sửa và chạy lại như mã của chính bạn. Tham số `length` tính lùi từ ngày chạy: thay bằng start/end nếu cần cố định khung thời gian. Kết quả phụ thuộc cấp quyền sử dụng vnstock (hoặc bản Cộng đồng) và trạng thái nguồn lúc chạy. """ import pandas as pd from vnstock import Market, cite import vnstock_quant as vq # c1 · market_equity · 09:15:10 · 250 dòng fpt_ohlcv_1y = Market().equity("FPT").ohlcv(length="1Y") # c2 · quant_ta · 09:15:42 · 250 dòng c2 = vq.ta.compute(fpt_ohlcv_1y, "sma", length=20) if __name__ == "__main__": print(c2) ```
Script dùng các thư viện chuẩn (`vnstock`, `vnstock_quant`, `pandas`). Bảng đã lưu bằng `research_save` xuất hiện trong script theo tên bạn đặt. Bước chuẩn hoá ghi lại dưới dạng lời gọi `vnstock_mcp.normalize.normalize_dataset(...)`. *** ## Giới hạn * `vnstock-mcp` không cung cấp bảng thô của nguồn khác. Bạn tự lấy bảng đó từ công cụ hoặc nguồn mà bạn có quyền dùng, và tự chịu trách nhiệm về quyền sử dụng của mình. * Kết quả đối chiếu cho biết hai nguồn có cho cùng con số hay không. Nó không xác nhận con số đúng với báo cáo tài chính gốc. * Mọi kết quả phục vụ nghiên cứu cá nhân, không phải khuyến nghị đầu tư. --- ## Document: Phân quyền và Cấp quyền sử dụng > **Mức ổn định: Thử nghiệm.** Tính năng đang phát triển thử nghiệm, chưa ổn định: tên hàm hay công cụ, tham số và cấu trúc kết quả có thể còn đổi giữa các bản phát hành; kết quả cần được đối chiếu độc lập trước khi đưa vào quy trình nghiên cứu.

Cơ chế phân quyền của vnstock-mcp được quản lý tập trung tại lõi Rust, đồng bộ với chính sách phân quyền của hệ sinh thái Vnstock thế hệ 5 (vnstock-auth), đảm bảo tính nhất quán trên toàn bộ môi trường thực thi.



## Tổng quan Vì `vnstock-mcp` đóng vai trò cầu nối cục bộ để Trợ lý AI gọi các thư viện Vnstock trên máy cá nhân của bạn, danh mục công cụ hiển thị cho AI phản ánh trực tiếp quyền sử dụng của tài khoản đối với từng thư viện bên dưới (`vnstock`, `vnstock_quant`...). Hệ thống hỗ trợ cả người dùng bản Cộng đồng (miễn phí cho cá nhân, học tập và nghiên cứu) lẫn người dùng gói quyền sử dụng qua các cấp: **Khách** (`guest`, chưa đăng nhập), **Cộng đồng** (`free`), **Bronze**, **Silver** và **Golden/Diamond** (bản Mở rộng). `vnstock-mcp` không có cấp riêng và không tự đếm lượt: mỗi lần gọi công cụ chỉ bị tính một lần, ở thư viện bên dưới, vào hạn mức chung của năm thư viện Vnstock. Hạn mức được tính theo trọng số của từng lượt gọi công cụ và hành vi sử dụng, nên cùng một số lượt gọi có thể chiếm phần hạn mức khác nhau. Công cụ tin tức (`news_*`) chỉ hiện ra từ cấp Silver. --- ## Ma trận công cụ theo bản Cộng đồng và các cấp quyền sử dụng Dưới đây là bảng tổng hợp phạm vi công cụ theo từng cấp quyền: | Cấp | Công cụ (hồ sơ `full` / `research`) | Dữ liệu | Định lượng (`vnstock_quant`) | | :--- | :---: | :--- | :--- | | **Khách** (chưa đăng nhập) | Ít hơn | Chế độ chạy thử: nến và giá hiện tại của cổ phiếu, nến chỉ số, danh sách mã, danh mục chỉ số, hồ sơ công ty. Lịch sử nến ngày 1 năm, tối đa 1.000 dòng mỗi bảng, không có báo cáo tài chính. | 10 chỉ báo kỹ thuật và 10 chỉ số tài chính cơ bản, dùng thử theo lượt mỗi ngày (mặc định 30); `quant_catalog`, `quant_entitlement`. | | **Cộng đồng** | **29 / 21** | 42 nhóm dữ liệu cơ bản: danh mục mã, chỉ số, ngành, sự kiện, hồ sơ doanh nghiệp, nến và giá hiện tại (cổ phiếu, chỉ số, ETF, phái sinh, chứng quyền, tiền mã hoá, ngoại tệ, hàng hoá), ba báo cáo tài chính (8 kỳ gần nhất), tỷ giá ngân hàng. Tối đa 10.000 dòng mỗi bảng. | Như Khách. | | **Bronze** | **39 / 29** | Mọi nhóm dữ liệu: thêm sổ lệnh, thống kê phiên, khối ngoại, tự doanh, chỉ số tài chính, thuyết minh, quỹ mở, vĩ mô, độ rộng và dòng tiền thị trường. | Đủ bộ chỉ số tài chính, rủi ro (`quant_risk`), danh mục (`quant_portfolio`), định giá (`quant_valuation`); chỉ báo kỹ thuật vẫn là 10 chỉ báo cơ bản. Không áp dụng giới hạn dùng thử riêng. | | **Silver, Golden, Diamond** | **39 / 29** | Như Bronze. | Như Bronze, thêm bộ chỉ báo kỹ thuật đầy đủ (58 chỉ báo). | Hồ sơ `research` là mặc định; đổi bằng `--profile full` hoặc `VNSTOCK_MCP_PROFILE=full`. Sáu công cụ `research_*` có ở mọi cấp. Danh sách `method` mở theo từng cấp: [Danh mục Công cụ](/docs/vnstock-mcp/danh-muc-cong-cu). Số liệu trên theo chính sách máy khách và `vnstock_quant` 0.2.1 ngày 14/10/2026; cấp Khách là chế độ chạy thử từ ngày đó, số công cụ hiện ra tuỳ theo các nhóm dữ liệu mở; hạn mức sử dụng theo cấp xem ở [Bảng giá](/pricing). Các phép tính `vnstock_quant` được ghi nhận vào quỹ hạn mức chung của tài khoản ở mọi cấp, kể cả khi gọi qua `vnstock-mcp`. Giới hạn dùng thử 30 phép tính/ngày là điều kiện bổ sung của cấp Khách và Cộng đồng; từ Bronze trở lên không áp dụng giới hạn riêng này. --- ## Cơ chế lọc danh mục công cụ theo cấp quyền sử dụng Khi Trợ lý AI giao tiếp qua giao thức MCP, nếu toàn bộ công cụ thuộc các cấp quyền sử dụng mở rộng đều hiển thị, AI có thể tự tiện gọi nhầm và nhận lại thông báo lỗi quyền truy cập. `vnstock-mcp` áp dụng cơ chế **Lọc danh mục công cụ (Tool Filtering)** tự động: 1. **Nhận diện cấp quyền**: Hệ thống kiểm tra cấp quyền sử dụng hoặc quyền bản Cộng đồng hiện tại của bạn. 2. **Duyệt danh mục công cụ**: Những công cụ có yêu cầu cấp quyền sử dụng cao hơn quyền hiện tại của bạn sẽ bị loại bỏ khỏi danh sách. 3. **Phân phối cho AI**: Trợ lý AI chỉ nhận được danh sách rút gọn chứa đúng các công cụ mà bạn được phép sử dụng. Trợ lý AI chỉ nhận được danh sách những công cụ mà bạn được phép sử dụng, giúp phiên làm việc diễn ra liền mạch và ổn định. --- ## Chính sách dùng thử Quant cho cấp Cộng đồng Nhằm hỗ trợ người dùng làm quen với phương pháp phân tích định lượng, `vnstock-mcp` cung cấp quyền dùng thử định mức hàng ngày: - **Lượt dùng thử**: mặc định **30 lượt tính toán / ngày**, dùng chung cho hai công cụ: - `quant_ta` với 10 chỉ báo cơ bản (SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV, VWAP, Pivots); - `quant_fa` với 10 chỉ số tài chính cơ bản (P/E, P/B, EPS, BVPS, ROE, ROA, biên gộp, biên ròng, thanh toán hiện hành, nợ/vốn chủ). - Số lượt còn lại xem bằng `quant_entitlement`. - **Nguồn dữ liệu linh hoạt**: Bạn có thể dùng định mức này để tính trên dữ liệu nến Vnstock hoặc tính trên dữ liệu tự cung cấp, tệp CSV/JSON, hay dữ liệu từ nguồn khác bạn có quyền sử dụng. - **Làm mới tự động**: Bộ đếm lượt dùng thử tự động làm mới vào đầu ngày mới theo giờ hệ thống. - **Cấp quyền sử dụng**: Từ cấp Bronze trở lên, quant không bị đếm lượt dùng thử; phép tính tính vào hạn mức chung của tài khoản (chia theo giờ, ngày, tháng, dùng chung cho mọi thư viện Vnstock). --- ## Công cụ nghiên cứu ở mọi cấp Sáu công cụ `research_*` (`research_save`, `research_datasets`, `research_journal`, `research_normalize`, `research_benchmark`, `research_universe`) luôn hiện ra, ở mọi cấp và mọi hồ sơ công cụ. Hai điểm vẫn theo cấp quyền sử dụng hoặc bản phần mềm: - `research_benchmark` đọc số liệu tham chiếu qua `vnstock`, nên chỉ đọc được phần dữ liệu cấp quyền của bạn được mở. - Từ điển chỉ tiêu VAS dùng để chuẩn hoá và đối chiếu được tải về bộ nhớ khi cần, có chữ ký số, không ghi xuống đĩa. Việc tải cần API key; tài khoản bản Cộng đồng nhận bộ từ điển rút gọn. --- ## Tra cứu phân quyền từ dòng lệnh ### 1. Kiểm tra cấp quyền sử dụng và hạn mức ```bash vnstock status ``` Chưa đăng nhập thì chạy `vnstock login`. Đăng nhập hoặc đổi cấp xong, khởi động lại ứng dụng AI để danh sách công cụ được dựng lại. ### 2. Kiểm tra số công cụ đang mở trên máy ```bash vnstock-mcp --doctor ``` Kết quả cho biết cấp và nhóm tính năng của `vnstock_quant`, cùng số công cụ của từng hồ sơ (`minimal`, `research`, `data`, `full`) với đúng tài khoản của bạn: ```text [OK ] vnstock_quant 0.2.1: cấp golden, mở ta_basic, ta, fa_basic, fa, fa_advanced, risk, portfolio [INFO] hồ sơ minimal : 13 tool, schema ≈ 4,042 token [OK ] hồ sơ research: 29 tool, schema ≈ 7,464 token ← đang dùng [INFO] hồ sơ data : 32 tool, schema ≈ 7,299 token [INFO] hồ sơ full : 39 tool, schema ≈ 9,630 token ``` ### 3. Hỏi ngay trong cuộc trò chuyện Công cụ `quant_entitlement` cho biết cấp quyền sử dụng và lượt tính thử còn lại của `vnstock_quant`. Với tài khoản có lượt dùng thử, phần hướng dẫn mà Trợ lý AI nhận được cũng có một dòng ghi số lượt còn lại trong ngày. --- ## Document: Cài đặt và xác thực Thư viện `vnstock_news` bản 3.x (thuộc đợt phát hành Vnstock thế hệ 5) có trên kho phát hành thư viện của Vnstock. Để cài đặt chính xác phiên bản này thay vì các bản cũ trên PyPI, bạn cần thêm tham số `--extra-index-url` vào lệnh pip. ## Yêu cầu môi trường | Thành phần | Yêu cầu | | :--- | :--- | | **Python** | Phiên bản 3.10 trở lên | | **Hệ điều hành** | Windows 10 trở lên, macOS (Apple Silicon và Intel), Linux (Ubuntu, Debian, Google Colab) | | **Thư viện phụ thuộc** | `pandas` (từ 2.0 trở lên, hệ thống tự động cài đặt kèm theo) | ## Cài đặt thư viện Cài vào cùng môi trường cố định với `vnstock`: `~/.venv` trên macOS và Linux, `$HOME\.venv` trên Windows; trên Google Colab hay GitHub Codespaces thì cài thẳng, không tạo môi trường. Cách tạo môi trường và trường hợp máy còn bản 4.x ở trang [Cài đặt vnstock](/docs/vnstock/cai-dat#cai-vao-dau). ```bash ~/.venv/bin/python -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-news ``` ```powershell & "$HOME\.venv\Scripts\python.exe" -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-news ``` Nếu bạn đang sử dụng bộ công cụ dòng lệnh `vnstock`, bạn có thể cài đặt trực tiếp bằng lệnh: ```bash ~/.venv/bin/vnstock install vnstock-news # Windows: & "$HOME\.venv\Scripts\vnstock.exe" install vnstock-news ``` Kiểm tra thư viện đã sẵn sàng trên máy tính của bạn: ```bash ~/.venv/bin/python -c "import vnstock_news; print(vnstock_news.__version__)" ```

Theo quy chuẩn đặt tên của hệ sinh thái Python (PEP 503):

  • Khi cài đặt qua pip: Tên gói phân phối chuẩn là vnstock-news (bạn gõ pip install vnstock-news hoặc pip install vnstock_news đều được vì pip tự động chuẩn hoá dấu gạch nối và gạch dưới như nhau).
  • Khi lập trình trong Python: Tên module bắt buộc dùng dấu gạch dưới: import vnstock_news (vì cú pháp Python không cho phép dấu gạch nối - trong tên định danh).
## Đăng nhập và xác thực quyền sử dụng

Thư viện vnstock_news là tính năng dành riêng cho cấp Silver trở lên (Silver, Golden, Diamond). Nếu tài khoản của bạn ở cấp Khách, Cộng đồng hoặc Bronze, các lệnh lấy tin sẽ nhận thông báo lỗi NEWS_TIER_REQUIRED.

Bạn có thể xác thực tài khoản theo một trong hai cách thuận tiện sau: ### Cách 1: Đăng nhập một lần trên máy tính cá nhân Chạy lệnh đăng nhập trong cửa sổ dòng lệnh Terminal: ```bash vnstock register ``` Nhập khoá API lấy từ [trang tài khoản](/account#api-key). Sau khi đăng nhập thành công, khoá sẽ được lưu an toàn trên máy và bạn không cần phải nhập lại trong các lần chạy sau. ### Cách 2: Thiết lập biến môi trường Nếu bạn sử dụng thư viện trong các kịch bản chạy theo lịch hoặc môi trường kiểm thử, hãy thiết lập biến môi trường: ```bash export VNSTOCK_API_KEY="khoa_api_cua_ban" ``` ## Kiểm tra trạng thái hoạt động Hàm `status()` giúp bạn nhanh chóng kiểm tra xem thư viện đã sẵn sàng tiếp nhận lệnh hay chưa, và đang hỗ trợ bao nhiêu trang tin: ```python import vnstock_news info = vnstock_news.status() print("Trạng thái sẵn sàng:", info["ready"]) print("Số trang tin hỗ trợ:", info["site_count"]) ```
Xem kết quả chi tiết của status() ```python { 'version': '3.1.1', 'ready': True, 'catalog_version': '2026-10-06', 'site_count': 18, 'build_date': '2026-10-09', 'expires_at': None, 'expires_on': None, 'days_left': None, 'expired': False, 'upgrade_action': 'pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-news', 'entitlement_test_build': False } ```
## Vì sao bản cài đặt có hạn sử dụng Các website tin tức thường định kỳ cập nhật cấu trúc trang web và kênh cấp tin. Nếu sử dụng phiên bản phần mềm quá cũ, việc lấy tin có thể bị gián đoạn do không kịp thích ứng với định dạng mới của các trang tin. Vì vậy mỗi bản phát hành có thời hạn hoạt động 365 ngày kể từ ngày phát hành, để bản trên máy bạn không quá cũ so với định dạng của trang tin. Ngày hết hạn xem ở `vnstock_news.status()["expires_on"]`. Khi còn dưới 30 ngày, thư viện sẽ hiển thị một dòng cảnh báo nhẹ `FutureWarning` kèm hướng dẫn nâng cấp. Bạn chỉ cần chạy lại lệnh nâng cấp để tiếp tục sử dụng: ```bash pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-news ``` ## Gỡ cài đặt Khi không còn nhu cầu sử dụng, bạn có thể gỡ bỏ thư viện dễ dàng: ```bash pip uninstall vnstock-news ``` --- ## Document: Chuyển đổi từ bản cũ Nếu bạn đang có các đoạn mã theo dõi tin tức viết cho `vnstock_news` phiên bản 2.x, bản 3.x (thuộc đợt phát hành Vnstock thế hệ 5) hỗ trợ hai lộ trình chuyển đổi linh hoạt tuỳ theo nhu cầu của bạn: 1. **Giữ nguyên mã cũ (Tương thích ngược 1:1)**: Thư viện cung cấp đầy đủ các lớp tương thích (`Crawler()`, `BatchCrawler()`, `AsyncBatchCrawler()`, `EnhancedNewsCrawler()`, `Cache`, `ContentCleaner`, `InputValidator`) chạy trên lõi xử lý mới. Bạn có thể tiếp tục chạy mã nguồn cũ mà không phải viết lại từ đầu. 2. **Rút gọn mã mới (Khuyến nghị)**: Chuyển đổi sang hai hàm tinh gọn `fetch_feeder()` (lấy danh sách tin mới) và `fetch_articles()` (đọc chi tiết bài viết) để mã nguồn đồng bộ, ngắn gọn và dễ bảo trì hơn. --- ## Document: Danh mục nguồn tin Thư viện `vnstock_news` cấu hình sẵn 18 trang báo điện tử và website tin tức tài chính phổ biến tại Việt Nam. Tuỳ theo nhu cầu phân tích (thị trường chứng khoán, vĩ mô chính sách hay tin tức xã hội), bạn có thể chọn nguồn tin phù hợp nhất. ## Danh sách 18 website tin tức được tích hợp sẵn Để chọn nguồn tin, bạn chỉ cần điền mã tương ứng ở cột **Mã (`site_name`)** vào hàm `fetch_feeder()`: ### 1. Nhóm tin tài chính, chứng khoán và doanh nghiệp | Mã (`site_name`) | Tên trang tin / báo điện tử | Tên miền | Chuyên mục chính | | :--- | :--- | :--- | :--- | | `cafef` | Báo điện tử CafeF | `cafef.vn` | Tin tức chứng khoán, thông tin doanh nghiệp niêm yết, phân tích tài chính | | `vietstock` | Báo điện tử Vietstock | `vietstock.vn` | Tin thị trường, báo cáo tài chính, sự kiện doanh nghiệp, giao dịch nội bộ | | `cafebiz` | Báo điện tử CafeBiz | `cafebiz.vn` | Chuyện kinh doanh, đời sống doanh nhân, khởi nghiệp, xu hướng thị trường | | `nguoiquansat` | Tạp chí Người Quan Sát | `nguoiquansat.vn` | Đầu tư, tài chính và doanh nghiệp | ### 2. Nhóm kinh tế vĩ mô, chính sách và đầu tư | Mã (`site_name`) | Tên trang tin / báo điện tử | Tên miền | Chuyên mục chính | | :--- | :--- | :--- | :--- | | `vneconomy` | Tạp chí Kinh tế Việt Nam | `vneconomy.vn` | Tin tức vĩ mô, chính sách tiền tệ, tài khoá và kinh tế quốc tế | | `baodautu` | Báo Đầu tư | `baodautu.vn` | Dự án đầu tư, dòng vốn FDI, bất động sản và các chính sách kinh tế | | `thoibaotaichinhvietnam` | Thời báo Tài chính Việt Nam | `thoibaotaichinhvietnam.vn` | Tài chính công, thuế, hải quan, thị trường trái phiếu | | `dddn` | Tạp chí Diễn đàn Doanh nghiệp | `diendandoanhnghiep.vn` | Doanh nghiệp, chính sách và pháp lý kinh doanh | | `petrotimes` | Tạp chí PetroTimes | `petrotimes.vn` | Năng lượng, dầu khí và công nghiệp | ### 3. Nhóm tin tức thời sự và tổng hợp nhanh | Mã (`site_name`) | Tên trang tin / báo điện tử | Tên miền | Chuyên mục chính | | :--- | :--- | :--- | :--- | | `vnexpress` | Báo điện tử VnExpress | `vnexpress.net` | Thời sự, chuyên mục kinh doanh | | `tuoitre` | Báo Tuổi Trẻ | `tuoitre.vn` | Xã hội, kinh tế đời sống | | `dantri` | Báo điện tử Dân Trí | `dantri.com.vn` | Tin tức kinh doanh, thị trường tiêu dùng, thị trường lao động | | `vietnamnet` | Báo điện tử VietNamNet | `vietnamnet.vn` | Thời sự chính trị, kinh tế, công nghệ và chuyển đổi số | | `thanhnien` | Báo Thanh Niên | `thanhnien.vn` | Kinh tế thị trường, tài chính cá nhân, bất động sản | | `nhandan` | Báo Nhân Dân | `nhandan.vn` | Thời sự, chính sách kinh tế | | `tienphong` | Báo Tiền Phong | `tienphong.vn` | Thời sự, kinh tế xã hội và thị trường tiêu dùng | | `znews` | Tạp chí điện tử Tri thức | `znews.vn` | Công nghệ, lối sống, kinh doanh | | `24h` | Trang tin 24h | `www.24h.com.vn` | Tài chính tiêu dùng, giá vàng, tỷ giá |

Danh mục hiện tại không còn các mã plo, nld, ktsg. Nếu bạn gọi các mã này, thư viện sẽ báo lỗi UNKNOWN_SITE để nhắc bạn đổi sang mã phù hợp.

## Các hàm tiện ích tra cứu danh mục ### 1. `list_supported_sites()` — Tra cứu nhanh mã nguồn tin Khi đang viết mã trong notebook hoặc terminal, bạn có thể in nhanh danh mục để lấy mã viết tắt: ```python import vnstock_news # In bảng danh sách ra màn hình vnstock_news.list_supported_sites() ``` Nếu muốn lấy danh sách dạng biến trong Python để duyệt qua vòng lặp, thêm `display=False`: ```python sites = vnstock_news.list_supported_sites(display=False) for site in sites: print(f"Mã: {site['name']} - Web: {site['domain']}") ``` ### 2. `source_plan(site_name)` — Xem trước đường dẫn nguồn tin Hàm này giúp bạn xem chính xác thư viện sẽ kiểm tra những đường dẫn sitemap hoặc RSS nào đối với một trang báo cụ thể. **Điểm tiện lợi cho bạn**: Hàm chạy hoàn toàn trên máy tính của bạn, không cần gọi mạng và không tiêu tốn bất kỳ lượt gọi API nào: ```python import vnstock_news # Xem trước kế hoạch lấy tin của CafeBiz plan = vnstock_news.source_plan("cafebiz") print("Sitemap chính:", plan["sitemap_url"]) print("Các kênh RSS:", plan["rss_urls"]) ```
Xem kết quả mẫu ```python { 'sitemap_url': 'https://cafebiz.vn/latestnews-sitemap.xml', 'sitemap_index_url': None, 'rss_urls': [ 'https://cafebiz.vn/rss/home.rss', 'https://cafebiz.vn/rss/cau-chuyen-kinh-doanh.rss', 'https://cafebiz.vn/rss/vi-mo.rss', 'https://cafebiz.vn/rss/cong-nghe.rss', 'https://cafebiz.vn/rss/xa-hoi.rss' ], 'rss_index_url': None } ```
## Biến tham chiếu nhanh Bạn cũng có thể truy xuất trực tiếp danh sách mã nguồn tin: ```python import vnstock_news # Danh sách tất cả các mã nguồn tin hỗ trợ print(vnstock_news.SUPPORTED_SITES) ``` --- ## Document: Giới thiệu Việc theo dõi tin tức tài chính từ nhiều kênh thông tin khác nhau thường làm bạn mất nhiều thời gian chuyển đổi qua lại giữa các trang web. Ra mắt trong **đợt phát hành Vnstock thế hệ 5**, thư viện `vnstock_news` (phiên bản 3.x) hỗ trợ bạn đơn giản hoá công việc này: sắp xếp danh sách tin mới từ các trang tin bạn chọn vào một bảng `pandas.DataFrame` trên máy tính của bạn. Bảng nhận về gồm tiêu đề, tóm tắt, thời gian xuất bản và đường dẫn bài viết, giúp bạn lọc thông tin phục vụ nghiên cứu cá nhân, rồi bấm vào liên kết để đọc bài tại trang gốc.

Thư viện vnstock_news hiện chỉ áp dụng cho người dùng bản Mở rộng thuộc gói quyền sử dụng từ cấp Silver trở lên (Silver, Golden, Diamond). Người dùng chưa đăng nhập hoặc thuộc cấp Khách, Cộng đồng và Bronze sẽ nhận thông báo NEWS_TIER_REQUIRED khi gọi hàm.

--- ## Document: Lịch sử phiên bản ## 15-10-2026 (v3.1.1) ### Bản 3.x trên lõi Rust, thuộc đợt phát hành Vnstock thế hệ 5 - **Lõi xử lý mới**: Bản 3.x chạy trên lõi Rust biên dịch sẵn, thay cho lõi Python của bản 2.x. Các lớp cũ (`Crawler`, `BatchCrawler`, `AsyncBatchCrawler`, `EnhancedNewsCrawler`, `Cache`, `ContentCleaner`, `InputValidator`) vẫn dùng được, nên mã viết cho bản 2.x chạy tiếp mà không phải viết lại. - **Hai hàm gọn mới**: `fetch_feeder()` lấy danh sách tin mới, `fetch_articles()` đọc chi tiết bài viết. Bảng đối chiếu mã cũ và mới xem ở [chuyển đổi từ bản cũ](/docs/vnstock-news/chuyen-doi-tu-ban-cu). - **Sửa lỗi lệch giờ**: Lọc `within="1h"` không còn lấy nhầm bài của 8 tiếng trước; thời gian chuẩn hoá theo giờ Việt Nam (UTC+07:00). - **Nhận diện thời gian tiếng Việt**: Các dạng tương đối như `"5 phút trước"`, `"hôm qua"` được đổi về ngày giờ chuẩn. - **Sửa lỗi dính chữ**: Chữ không còn bị nối liền (`Giávàngtăng` nay đọc đúng là `Giá vàng tăng`). - **An toàn kết nối**: Xác thực TLS luôn bật mặc định, chặn các chuyển hướng không an toàn. - **Tiện hơn khi import**: `SITES_CONFIG` và `SUPPORTED_SITES` import thẳng từ `vnstock_news`. - **[Mở rộng]** **Quyền sử dụng**: Thư viện dành cho người dùng bản Mở rộng từ cấp Silver trở lên. ## 28-06-2026 > Phát hành `vnstock_data` phiên bản 3.2.3 hoàn thiện cấu trúc tin tức của công ty niêm yết và chuẩn hoá mô hình dữ liệu. - **Chuẩn hoá mô hình dữ liệu (Unified Schema) cho Tin tức doanh nghiệp:** Giao diện `Reference().company('MÃ_CK').news()` được chuẩn hoá hoàn toàn trên 3 nguồn `vci`, `kbs`, và `cafef` với chung 10 cột dữ liệu thống nhất (`id`, `symbol`, `title`, `summary`, `content`, `publish_time`, `source`, `url`, `category`, `image_url`). - **Nâng cấp tính năng lấy tin tức chi tiết:** Bổ sung tham số `mode='detail'` cho phép đọc nội dung chi tiết bài viết và bóc tách các link đính kèm trực tiếp từ `vci` và `cafef`. - **Hỗ trợ tuỳ chỉnh tham số linh hoạt:** Chuẩn hoá các tham số bộ lọc thời gian (`start`, `end`, `length`, `limit`) và nâng cấp khả năng truyền linh hoạt `**kwargs` xuống hàm của từng nguồn. ## 03-04-2026 > **Phát hành vnstock_news 2.2.0: theo dõi tin tức ổn định hơn** > > Bản phát hành mới khắc phục nhiều lỗi trong quá trình xử lý dữ liệu và cải thiện độ ổn định khi đọc tin từ 21 trang tin tại Việt Nam. ### Nâng cấp nổi bật - **Kiến trúc hợp nhất nguồn tin:** Kết hợp và tự động dự phòng chéo (fallback) giữa luồng RSS và Sitemap, giúp ứng dụng của bạn tiếp tục nhận tin mới khi một trong hai luồng gặp sự cố. - **Trích xuất metadata linh hoạt:** Tăng cường khả năng bắt chính xác Selector qua các thuộc tính linh hoạt (`id`, `data-slot`, `rel`) thay vì phụ thuộc mỗi thẻ `class` theo CSS Selector truyền thống. Chủ động trích xuất thêm thẻ Tags, Lượt xem và Chuyên mục của bài. - **Làm sạch tự động & Xử lý thời gian:** - **Date Parser:** Tự động chuẩn hoá và ép kiểu các định dạng thời gian khác nhau (như *15 phút trước*, *Thứ năm...*) về chuẩn ISO thống nhất. - **Spam/Media Link Filter:** Rà soát và loại bỏ link nhiễu phân trang, hình ảnh, URL rác đính kèm trong RSS. ### Cải tiến độ ổn định - Sửa dứt điểm tình trạng trả về Data nhưng cột Nội dung trống rỗng (Missing Content 100%) gây ra bởi lỗi đọc JSON. - **Bổ sung nguồn tin mới được hỗ trợ:** Bổ sung và tinh chỉnh cấu trúc CSS cho hàng loạt website tin tức mới (Tiền Phong, Người Lao Động, Thanh Niên, Znews, Dân Trí, Đầu Tư, VnEconomy). - Bổ sung bộ kịch bản dùng thử "All-in-one" và tái cấu trúc tài liệu ví dụ, tự động dọn dẹp kết quả xuất file vào phân vùng tĩnh `/output/`.
Nhấp để xem danh sách website tin tức được hỗ trợ sẵn (cập nhật 06/10/2026) | STT | Tên Website / Báo | Tên Config | Loại Hình | RSS | Sitemap | | --- | ------------------------- | ---------------------- | ------------ | --- | ------- | | 1 | **Nhân Dân** | nhandan | Cơ quan TW | ✅ | ✅ | | 2 | **Tiền Phong** | tienphong | Cơ quan TW | ✅ | ✅ | | 3 | **VietNamNet** | vietnamnet | Bộ Ngành | ✅ | ✅ | | 4 | **Dân Trí** | dantri | Bộ Ngành | ✅ | ✅ | | 5 | **VnExpress** | vnexpress | Bộ Ngành | ✅ | ✅ | | 6 | **Báo Đầu Tư** | baodautu | Bộ Ngành | ✅ | ✅ | | 7 | **Thời Báo Tài Chính** | thoibaotaichinhvietnam | Bộ Ngành | ✅ | ✅ | | 8 | **Thanh Niên** | thanhnien | Tổ chức TW | ✅ | ✅ | | 9 | **Tuổi Trẻ** | tuoitre | Địa phương | ✅ | ✅ | | 10 | **VnEconomy** | vneconomy | Chuyên ngành | ✅ | ✅ | | 11 | **Diễn Đàn Doanh Nghiệp** | dddn | Chuyên ngành | ✅ | ✅ | | 12 | **PetroTimes** | petrotimes | Chuyên ngành | ✅ | ✅ | | 13 | **Znews (Tri thức)** | znews | Chuyên ngành | ✅ | ✅ | | 14 | **CafeF** | cafef | Trang tin | ✅ | ✅ | | 15 | **CafeBiz** | cafebiz | Trang tin | ✅ | ✅ | | 16 | **VietStock** | vietstock | Trang tin | ✅ | ✅ | | 17 | **24h** | 24h | Tổng hợp | ✅ | ✅ | | 18 | **Người Quan Sát** | nguoiquansat | Tổng hợp | ✅ | ✅ |
## 31-08-2025 > Phát hành phiên bản Vnstock News 2.1.0 nâng cấp cơ chế tải dữ liệu và cung cấp khả năng tuỳ biến linh hoạt, bổ sung tài liệu hướng dẫn chi tiết.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/legacy/cai-dat-phan-mem). - Thay đổi hoàn toàn cấu trúc chương trình theo hướng chặt chẽ và module hoá - Cung cấp cơ chế tự xử lý link sitemap và rss linh hoạt đối với các website sử dụng cơ chế động ví dụ sitemap theo năm-tháng, sitemap với số đếm tăng dần. - Hỗ trợ 21 trang web trong danh sách định nghĩa sẵn, người dùng có thể tự bổ sung cấu hình để theo dõi tin tức từ các trang khác ngoài danh sách. --- ## Document: Theo dõi và đọc tin tức Thư viện `vnstock_news` bản 3.x tổ chức quy trình theo dõi tin tức thành hai thao tác rõ ràng, phục vụ từng nhu cầu cụ thể của bạn: 1. **Lấy danh sách tin mới (`fetch_feeder`)**: Đọc nhanh nguồn cấp tin RSS hoặc sơ đồ trang XML Sitemap do trang tin công bố để nhận bảng tổng hợp tiêu đề, tóm tắt, thời gian xuất bản và đường dẫn liên kết bài viết. Thao tác này diễn ra rất nhanh, phù hợp để theo dõi diễn biến thị trường theo phiên. 2. **Đọc chi tiết bài viết (`fetch_articles`)**: Mở từng trang bài viết để đọc các trường thông tin như tác giả, chuyên mục, từ khoá (tags), lượt xem, ảnh đại diện, và nội dung bài viết (dạng Markdown) khi bạn tự cung cấp bộ chọn nội dung (`content_selector`) cho nghiên cứu cá nhân.

Cả hai hàm fetch_feeder() và fetch_articles() đều áp dụng cho tài khoản bản Mở rộng từ cấp Silver trở lên (Silver, Golden, Diamond). Tính năng truyền nguồn tự chọn (sources), danh sách liên kết có sẵn (urls) hoặc cấu hình riêng (config) cũng yêu cầu cấp Silver trở lên.

--- ## Document: Tuỳ biến Sitemap và RSS Ngoài các trang tin trong danh mục, bạn có thể tự thêm chuyên mục hay trang tin khác mà bạn quan tâm, nếu trang đó công bố nguồn cấp tin (RSS) hoặc sơ đồ trang và điều kiện sử dụng của trang cho phép. ## Khi nào bạn cần tuỳ biến nguồn tin 1. **Theo dõi chuyên mục chuyên biệt**: Thay vì đọc toàn bộ tin tức kinh doanh chung, bạn chỉ muốn nhận tin về "Bất động sản", "Thị trường hàng hoá" hoặc "Khởi nghiệp" từ kênh RSS riêng của chuyên mục đó. 2. **Thêm trang tin yêu thích ngoài danh mục**: Trang tin có công bố nguồn cấp tin RSS hoặc sơ đồ trang XML Sitemap, bạn có thể đưa vào danh sách theo dõi phục vụ nghiên cứu cá nhân nếu điều kiện sử dụng của trang cho phép. 3. **Mở rộng bóc tách nội dung cho nghiên cứu cá nhân**: Bộ khung của thư viện cho phép bạn chủ động định nghĩa cấu hình bộ chọn (`content_selector`) từ một bài mẫu theo [mục 3](#3-tu-dung-cau-hinh-doc-noi-dung-tu-mot-bai-mau) để trích xuất văn bản phục vụ phân tích chuyên sâu (như xử lý ngôn ngữ tự nhiên) trong phạm vi được phép của trang tin.

Tính năng khai báo nguồn tự chọn qua tham số sources hoặc cấu hình riêng config dành riêng cho người dùng từ cấp Silver trở lên (Silver, Golden, Diamond). Người dùng thuộc cấp thấp hơn khi truyền các tham số này sẽ nhận thông báo lỗi NEWS_TIER_REQUIRED.

--- ## Document: Giới thiệu vnstock_news
vnstock_news là thư viện Python thuộc hệ sinh thái Vnstock, giúp bạn theo dõi tin tức và sắp xếp tiêu đề, thời gian, đường dẫn từ nguồn cấp tin (RSS) và sơ đồ trang (Sitemap XML) do trang tin công bố, với cấu hình sẵn cho các trang tin trong danh mục. Thư viện hỗ trợ công cụ AI Agent và ứng dụng trong nghiên cứu định lượng, xử lý ngôn ngữ tự nhiên và tổng hợp thông tin cá nhân.
## Các tính năng nổi bật * **Sắp xếp thông tin bài viết:** Đọc tiêu đề, mô tả ngắn, thời gian xuất bản, chuyên mục, đường dẫn và tác giả từ các trang tin trong danh mục và các trang tương thích mà bạn tự cấu hình. * **Quản lý nguồn cấp tin linh hoạt:** Hỗ trợ đọc cả RSS feed và Sitemap XML để lấy danh sách bài viết mới nhất hoặc tra cứu theo sơ đồ trang do website công bố. * **Cấu hình dễ dàng:** Đi kèm cấu hình sẵn cho các trang tin trong danh mục, giúp bạn bắt đầu nhanh chóng mà không cần định nghĩa lại bộ chọn (selector). * **Khả năng tùy biến cao:** Cho phép bạn định nghĩa cấu hình tùy chỉnh cho các trang web khác hoặc điều chỉnh các bộ chọn khi trang nguồn thay đổi giao diện. * **Điều phối tần suất truy cập hợp lý:** Hỗ trợ đọc bài theo đợt (batch) có khoảng nghỉ giữa các yêu cầu và giới hạn số kết nối đồng thời nhằm tôn trọng tài nguyên của website nguồn. * **Ghi log chi tiết:** Cung cấp thông tin log rõ ràng giúp theo dõi quá trình xử lý và thuận tiện gỡ lỗi. ## Các nguồn tin được hỗ trợ sẵn **vnstock\_news** có sẵn cấu hình cho các trang tin trong bảng dưới, dùng hai chuẩn công bố thông tin phổ biến là **RSS Feeds** (tin cập nhật mới) và **Sitemap XML** (danh mục bài viết theo thời gian). Bạn cũng có thể bổ sung cấu hình cho các trang web khác ngoài danh sách. | STT | Tên Website / Báo | Tên Config | Loại Hình | RSS | Sitemap | Mô Tả / Đơn Vị Xuất Bản | | --- | ------------------------- | ------------------------ | ------------ | --- | ------- | --------------------------------------------------------- | | 1 | **Nhân Dân** | `nhandan` | Cơ quan TW | ✅ | ✅ | Cơ quan trung ương của Đảng Cộng Sản Việt Nam | | 2 | **Tiền Phong** | `tienphong` | Cơ quan TW | ✅ | ✅ | Cơ quan trung ương của Đoàn TNCS Hồ Chí Minh | | 3 | **VietNamNet** | `vietnamnet` | Bộ Ngành | ✅ | ✅ | Báo điện tử thuộc Bộ Thông tin và Truyền thông | | 4 | **Dân Trí** | `dantri` | Bộ Ngành | ✅ | ✅ | Báo điện tử thuộc Bộ Lao động - Thương binh và Xã hội | | 5 | **VnExpress** | `vnexpress` | Bộ Ngành | ✅ | ✅ | Báo điện tử trực thuộc Bộ Khoa học và Công nghệ | | 6 | **Báo Đầu Tư** | `baodautu` | Bộ Ngành | ✅ | ✅ | Cơ quan của Bộ Kế hoạch và Đầu tư | | 7 | **Thời Báo Tài Chính** | `thoibaotaichinhvietnam` | Bộ Ngành | ✅ | ✅ | Báo điện tử thuộc Bộ Tài Chính | | 8 | **Thanh Niên** | `thanhnien` | Tổ chức TW | ✅ | ✅ | Diễn đàn của Hội Liên hiệp Thanh niên Việt Nam | | 9 | **Tuổi Trẻ** | `tuoitre` | Địa phương | ✅ | ✅ | Cơ quan báo chí của Thành Đoàn TP.HCM | | 10 | **VnEconomy** | `vneconomy` | Chuyên ngành | ✅ | ✅ | Tạp chí của Hội Khoa học Kinh tế Việt Nam | | 11 | **Diễn Đàn Doanh Nghiệp** | `dddn` | Chuyên ngành | ✅ | ✅ | Cơ quan của Liên đoàn Thương mại & Công nghiệp (VCCI) | | 12 | **PetroTimes** | `petrotimes` | Chuyên ngành | ✅ | ✅ | Tạp chí của Hội Dầu khí Việt Nam | | 13 | **Znews (Tri thức)** | `znews` | Chuyên ngành | ✅ | ✅ | Tạp chí điện tử của Hội Xuất bản Việt Nam | | 14 | **CafeF** | `cafef` | Trang tin | ✅ | ✅ | Trang thông tin kinh tế - tài chính khối VCCorp | | 15 | **CafeBiz** | `cafebiz` | Trang tin | ✅ | ✅ | Trang thông tin kinh doanh - khởi nghiệp khối VCCorp | | 16 | **VietStock** | `vietstock` | Trang tin | ✅ | ✅ | Cổng thông tin Tài chính & Chứng khoán Việt Nam | | 17 | **24h** | `24h` | Tổng hợp | ✅ | ✅ | Trang thông tin điện tử tổng hợp 24h | | 18 | **Người Quan Sát** | `nguoiquansat` | Tổng hợp | ✅ | ✅ | Trang thông tin điện tử chuyên sâu về kinh tế chứng khoán | Danh sách chỉ gồm các trang có tệp `robots.txt` cho phép truy cập tại lần rà soát gần nhất (06/10/2026). Khi tự bổ sung một trang ngoài danh sách, hãy kiểm tra `robots.txt` và điều kiện sử dụng của trang đó trước khi dùng. ## Vai trò của thư viện `vnstock_news` hỗ trợ quy trình nghiên cứu cá nhân: * **Theo dõi tin tức định kỳ:** Theo dõi diễn biến vĩ mô và cập nhật thông tin doanh nghiệp phục vụ nhu cầu thông tin cá nhân. * **Xử lý ngôn ngữ tự nhiên:** Phân tích tiêu đề và đoạn tóm tắt làm ghi chú cho nghiên cứu cá nhân, trong phạm vi điều kiện sử dụng của từng trang tin. * **Nghiên cứu định lượng:** Phân loại chỉ số cảm xúc tài chính (sentiment analysis) phục vụ nghiên cứu thị trường.
vnstock_news là công cụ giúp bạn tự đọc và sắp xếp tin bài từ nguồn cấp tin (RSS) và sơ đồ trang (sitemap) do trang tin công bố, phục vụ nghiên cứu và học thuật cá nhân. Bản quyền bài viết và hình ảnh thuộc về đơn vị xuất bản chủ quản. Với phân tích, hãy ưu tiên dùng siêu dữ liệu, tiêu đề và đoạn trích; không sao chép hay đăng lại nội dung bài báo. Người dùng cần tuân thủ điều khoản dịch vụ của từng website nguồn và quy định pháp luật về bản quyền, sở hữu trí tuệ.
Thay vì nghiên cứu cú pháp thư viện một cách thủ công, bạn có thể tham khảo tài liệu **Agent Guide** cung cấp cho trợ lý AI (Claude, ChatGPT, Antigravity) để hỗ trợ viết kịch bản theo dõi tin tức nhanh chóng. --- ## Document: Hướng dẫn Cơ bản
Các hàm và thông số bên dưới cung cấp kiến thức nền tảng về thư viện. Bạn cũng có thể tham khảo tài liệu Agent Guide để hỗ trợ các công cụ AI Agent viết kịch bản theo dõi tin tức theo yêu cầu.
## 1. Chi Tiết Các Lớp Xử Lý & Phương Thức Thư viện `vnstock_news` cung cấp 4 lớp xử lý cho các cách đọc tin khác nhau: ### 1.1 `Crawler` - Giao diện cơ bản Lớp `Crawler` là giao diện cơ bản, phù hợp với nhu cầu lấy bài viết mới từ RSS hoặc kiểm tra cấu hình trang tin: #### Khởi tạo: ```python from vnstock_news import Crawler # Cách 1: Sử dụng cấu hình có sẵn của nguồn tin (ví dụ: vnexpress, tuoitre, cafef) client = Crawler(site_name="vnexpress") # Cách 2: Truyền cấu hình tùy chỉnh cho trang web mới custom_site_config = { "name": "Trang tin mẫu", "domain": "trangtin.example", "rss_urls": ["https://trangtin.example/rss/feed.xml"], "sitemap_url": "https://trangtin.example/sitemap.xml", "config": { "title_selector": {"tag": "h1", "class": "title-detail"} } } client_custom = Crawler(custom_config=custom_site_config) ``` #### Phương thức chính: * **`get_articles_from_feed(limit_per_feed=20)`**: Lấy danh sách bài viết từ các kênh RSS Feed. * **`get_articles(sitemap_url=None, limit=10, limit_per_feed=None)`**: Ưu tiên lấy từ RSS Feed, nếu không có RSS sẽ chuyển sang lấy danh sách URL từ Sitemap. #### Bảng tham số `Crawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :--------------- | :----------- | :------- | :-------------------------------------------------------------------------- | | `site_name` | `str` | `None` | Tên định danh của website trong SITES\_CONFIG (ví dụ: `"vnexpress"`, `"cafef"`) | | `custom_config` | `dict` | `None` | Dictionary chứa cấu hình bộ chọn và nguồn RSS/Sitemap tự định nghĩa | | `limit_per_feed` | `int` | `20` | Số lượng bài viết tối đa cần lấy từ mỗi nguồn RSS feed | | `limit` | `int` | `10` | Tổng số lượng bài viết truy xuất khi gọi `get_articles()` | | `sitemap_url` | `str / list` | `None` | Đường dẫn Sitemap XML tùy chỉnh | *** ### 1.2 `BatchCrawler` - Đọc bài tuần tự có khoảng nghỉ `BatchCrawler` đọc chi tiết từng bài viết lần lượt theo cơ chế đồng bộ, có khoảng nghỉ `request_delay` giữa các yêu cầu, và hỗ trợ lưu dữ liệu tạm để tiếp tục tiến trình nếu bị gián đoạn. #### Ví dụ sử dụng: ```python from vnstock_news import BatchCrawler # Khởi tạo BatchCrawler với khoảng trễ 1.5 giây giữa các yêu cầu client = BatchCrawler( site_name="cafef", request_delay=1.5, output_path="./output_data" ) # Tải nội dung chi tiết của 100 bài viết từ Sitemap df_articles = client.fetch_articles(limit=100) print(f"Tổng số bài viết đã bóc tách: {len(df_articles)}") ``` #### Bảng tham số `BatchCrawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :-------------- | :----------- | :--------- | :------------------------------------------------------ | | `site_name` | `str` | *Bắt buộc* | Tên định danh website trong hệ thống cấu hình | | `request_delay` | `float` | `1.0` | Thời gian tạm dừng (giây) giữa các lần gửi yêu cầu HTTP | | `output_path` | `str` | `"./data"` | Thư mục lưu trữ tập tin tạm | | `limit` | `int` | `10` | Số lượng bài viết tối đa cần bóc tách chi tiết | | `sitemap_url` | `str / list` | `None` | URL sitemap cụ thể cần quét dữ liệu | | `debug` | `bool` | `False` | Bật/tắt chế độ ghi log chi tiết | *** ### 1.3 `AsyncBatchCrawler` - Đọc bài bất đồng bộ `AsyncBatchCrawler` sử dụng thư viện `aiohttp` và `asyncio` để xử lý có kiểm soát số yêu cầu đồng thời, giới hạn bằng tham số `max_concurrency`. Bạn nên giữ mức đồng thời thấp để không gây tải cho trang nguồn. #### Ví dụ sử dụng: ```python import asyncio from vnstock_news import AsyncBatchCrawler async def run_async_pipeline(): client = AsyncBatchCrawler( site_name="tuoitre", max_concurrency=3 # Giới hạn tối đa 3 yêu cầu gửi đi đồng thời ) # Lấy 50 bài viết từ Sitemap của một trang minh hoạ df_result = await client.fetch_articles_async( sources=["https://trangtin.example/news-sitemap.xml"], top_n=50 ) return df_result df_tuoitre = asyncio.run(run_async_pipeline()) print(f"Truy xuất thành công {len(df_tuoitre)} bài viết.") ``` #### Bảng tham số `AsyncBatchCrawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :---------------- | :----------- | :--------- | :------------------------------------------------------ | | `site_name` | `str` | *Bắt buộc* | Tên định danh website nguồn | | `max_concurrency` | `int` | `5` | Số yêu cầu đồng thời tối đa; nên giữ ở mức thấp | | `sources` | `list` | *Bắt buộc* | Danh sách đường dẫn Sitemap XML nguồn | | `top_n` | `int` | `10` | Số lượng bài viết tối đa cần bóc tách từ danh sách URLs | *** ### 1.4 `EnhancedNewsCrawler` - Lớp đọc tin mở rộng `EnhancedNewsCrawler` tích hợp bộ nhớ đệm (Cache), cơ chế làm sạch văn bản, kiểm tra tính hợp lệ dữ liệu và tự động thử lại khi gặp lỗi kết nối tạm thời. #### Ví dụ sử dụng: ```python import asyncio from vnstock_news import EnhancedNewsCrawler async def run_enhanced_pipeline(): client = EnhancedNewsCrawler( cache_enabled=True, cache_ttl=86400, # Thời gian lưu bộ nhớ đệm 24 giờ max_concurrency=3 ) df_data = await client.fetch_articles_async( sources=["https://trangtin.example/latest-news-sitemap.xml"], site_name="example", max_articles=50, clean_content=True # Tự động loại bỏ các thẻ HTML thừa và quảng cáo ) return df_data df_enhanced = asyncio.run(run_enhanced_pipeline()) ``` *** ## 2. So Sánh Hai Kênh Cấp Tin: RSS Feeds và Sitemap XML Việc chọn kênh đọc tin phụ thuộc vào mục đích sử dụng cụ thể: | Tiêu Chí So Sánh | RSS Feeds (Tin Mới) | Sitemap XML (Lịch Sử) | | :------------------- | :-------------------------------------------------- | :------------------------------------------------------ | | **Tốc độ đọc** | Nhanh | Phụ thuộc số bài và thời gian trễ | | **Phạm vi dữ liệu** | Chứa các bài mới phát hành gần đây | Chứa danh sách bài viết theo thời gian lưu trữ của website nguồn | | **Độ sâu thông tin** | Có sẵn thông tin tóm tắt và ngày đăng | Cần gửi thêm yêu cầu HTTP để đọc chi tiết từng bài | | **Mục đích sử dụng** | Cập nhật tin tức mới, nhận thông báo tin bài | Tra lại bài đã đăng cho nghiên cứu cá nhân | | **Cơ chế dự phòng** | Tự động chuyển sang Sitemap nếu RSS không hoạt động | Tự động phân giải các Sitemap động theo tháng/năm | **Gợi ý:** Bạn có thể kết hợp sử dụng **RSS Feeds** để cập nhật bài viết mới định kỳ và đọc **Sitemap XML** để bổ sung các bài viết cần nghiên cứu thêm. *** ## 3. Cấu Trúc Dữ Liệu Trả Về Thông tin bài viết sau khi đọc được trả về dưới dạng **Pandas DataFrame** hoặc `List[Dict]` với **11 trường dữ liệu chuẩn hóa**: | Cột Dữ Liệu | Kiểu Dữ Liệu | Mô Tả Chi Tiết | Ví Dụ Dữ Liệu Mẫu | | :------------------ | :----------- | :--------------------------------- | :------------------------------------------------------ | | `url` | `str` | Đường dẫn URL của bài viết | `"https://trangtin.example/thi-truong-chung-khoan-2026.chn"` | | `title` | `str` | Tiêu đề bài viết | `"Thị trường chứng khoán bật tăng mạnh phiên đầu tuần"` | | `short_description` | `str` | Đoạn tóm tắt / Sapo bài viết | `"Dòng tiền khối ngoại quay trở lại mua ròng..."` | | `content` | `str` | Nội dung văn bản (đã loại bỏ HTML) | `"Nội dung chi tiết các đoạn văn bản trong bài..."` | | `publish_time` | `datetime` | Thời gian xuất bản (dạng ISO) | `2026-04-15 09:30:00` | | `author` | `str` | Tên tác giả hoặc nguồn dẫn | `"Nguyễn Văn A"` / `"Theo CafeF"` | | `category` | `str` | Chuyên mục tin tức | `"Chứng khoán"` / `"Tài chính vĩ mô"` | | `tags` | `str` | Danh sách từ khóa / Tags bài viết | `"VN-Index, Chứng khoán, Lãi suất"` | | `view_counts` | `int` | Số lượt xem (nếu trang tin có hiển thị) | `15200` | | `image_url` | `str` | Đường dẫn ảnh đại diện bài viết | `"https://cdn.trangtin.example.vn/thumb_w/640/image.jpg"` | | `source` | `str` | Tên định danh nguồn tin | `"example"` | Dữ liệu trả về ở dạng Pandas DataFrame giúp bạn dễ dàng thực hiện lọc, nhóm, lưu trữ ra tập tin CSV/Parquet hoặc nạp vào các quy trình xử lý dữ liệu tiếp theo. --- ## Document: Mẫu Chương trình Cập nhật Tin tức
Phần này giới thiệu cách thiết lập quy trình theo dõi và cập nhật tin tức dựa trên thư viện vnstock_news, từ việc kiểm thử nhanh qua dòng lệnh đến việc xây dựng các kịch bản Python ghi log, lọc bài trùng lặp và đọc danh mục bài viết từ sitemap với tần suất hợp lý.
## Sử dụng qua Dòng Lệnh (CLI) Sau khi cài đặt `vnstock_news`, bạn có thể chạy chương trình theo dõi tin tức trực tiếp từ dòng lệnh Terminal để kiểm thử quá trình theo dõi tin và lưu kết quả: ```bash vnstock-news-crawler ``` Bạn có thể xem thêm tài liệu **Agent Guide** bên dưới để hướng dẫn các trợ lý AI (Claude, ChatGPT, Antigravity) viết kịch bản theo dõi tin tức theo yêu cầu. ![Khởi động chương trình Vnstock News từ Terminal của macOS](/images/khoi-dong-vnstock-news-che-do-dong-lenh.png "Khởi động chương trình Vnstock News từ Terminal của macOS") Khi khởi chạy, chương trình đọc nguồn cấp tin (RSS) và sơ đồ trang (sitemap) do các trang tin công bố, lọc bài theo khoảng thời gian yêu cầu và lưu kết quả dưới dạng tập tin CSV tại thư mục `output`. ![Nội dung dữ liệu tin tức được chuẩn hoá từ Vnstock News](/images/bang-tinh-noi-dung-tin-tuc-chuan-hoa-vnstock-news.png "Nội dung dữ liệu tin tức được chuẩn hoá từ Vnstock News") Khung báo cáo sau thống kê sẽ xuất về tệp tĩnh mang tên `news_summary.txt`: ```text News Monitor Report - 2026-04-15 ================================================== STATISTICS -------------------------------------------------- Total articles collected: 580 TRENDING TOPICS -------------------------------------------------- 1. chứng khoán: 107 mentions 2. thị trường: 76 mentions 3. lãi suất: 45 mentions ... ``` Giao diện vận hành thực tế minh họa trên Google Colab: ![Tóm tắt kết quả chương trình khi kết nối và phân tích tin tức trên Google Colab](/images/tom-tat-ket-qua-thuc-thi-vnstock-news.png "Tóm tắt kết quả chương trình khi kết nối và phân tích tin tức trên Google Colab") *** ## Kịch Bản Python 1: Cập Nhật Tin Tức Định Kỳ Qua RSS Feed Kịch bản Python dưới đây vận hành luồng kiểm tra tin mới định kỳ, ghi log quá trình chạy và lọc bài viết trùng lặp để tránh lưu lại bài viết đã nhận trước đó. ```python import os import time import logging from datetime import datetime import pandas as pd from vnstock_news import Crawler # Cấu hình ghi log hệ thống logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s - %(message)s", handlers=[ logging.FileHandler("news_monitor.log", encoding="utf-8"), logging.StreamHandler() ] ) logger = logging.getLogger("PeriodicNewsMonitor") class PeriodicNewsMonitor: def __init__(self, target_sites: list, poll_interval_seconds: int = 900, output_dir: str = "./news_data"): self.target_sites = target_sites self.poll_interval = poll_interval_seconds self.output_dir = output_dir self.seen_urls = set() os.makedirs(self.output_dir, exist_ok=True) logger.info(f"Đã khởi tạo bộ theo dõi tin tức cho các nguồn: {self.target_sites}") def poll_once(self) -> int: """Thực hiện một lượt quét tin mới từ danh sách RSS feeds.""" collected_articles = [] for site in self.target_sites: try: logger.info(f"Đang kiểm tra RSS feed từ: {site}") client = Crawler(site_name=site) articles = client.get_articles_from_feed(limit_per_feed=15) new_in_site = 0 for item in articles: url = item.get("url") if url and url not in self.seen_urls: self.seen_urls.add(url) collected_articles.append(item) new_in_site += 1 logger.info(f"[{site}] Phát hiện {new_in_site} tin bài mới.") except Exception as e: logger.error(f"Lỗi khi truy xuất tin từ site '{site}': {e}", exc_info=True) # Lưu tin bài mới ra file CSV theo ngày nếu có dữ liệu mới if collected_articles: df = pd.DataFrame(collected_articles) today_str = datetime.now().strftime("%Y-%m-%d") filename = os.path.join(self.output_dir, f"daily_news_{today_str}.csv") # Ghi nối tiếp (append) vào file CSV nếu file đã tồn tại file_exists = os.path.exists(filename) df.to_csv(filename, mode="a", index=False, header=not file_exists, encoding="utf-8-sig") logger.info(f"Đã ghi nhận và lưu {len(collected_articles)} bài viết mới vào: {filename}") return len(collected_articles) def start_periodic_monitoring(self): """Khởi chạy vòng lặp cập nhật định kỳ.""" logger.info(f"Khởi chạy vòng lặp cập nhật định kỳ (chu kỳ: {self.poll_interval}s)...") try: while True: total_new = self.poll_once() logger.info(f"Hoàn thành chu kỳ. Tổng tin bài mới truy xuất: {total_new}. Chờ chu kỳ tiếp theo sau {self.poll_interval}s...") time.sleep(self.poll_interval) except KeyboardInterrupt: logger.info("Đã nhận tín hiệu dừng từ người dùng (Ctrl+C). Dừng an toàn.") if __name__ == "__main__": # Khởi tạo monitor cho các nguồn có RSS (VnExpress, Tuổi Trẻ, Thanh Niên) monitor = PeriodicNewsMonitor( target_sites=["vnexpress", "tuoitre", "thanhnien"], poll_interval_seconds=900, # Kiểm tra định kỳ mỗi 15 phút, giữ tần suất hợp lý với website nguồn output_dir="./output_stream" ) # Thực hiện 1 lượt kiểm tra ngay lập tức monitor.poll_once() ``` *** ## Kịch Bản Python 2: Đọc Danh Mục Bài Viết Từ Sitemap Khi cần lập tập dữ liệu bài viết phục vụ nghiên cứu, kịch bản dưới đây dùng `EnhancedNewsCrawler` để đọc dữ liệu từ sitemap, có bộ nhớ đệm để tránh gửi lại yêu cầu cho bài đã có, giới hạn số kết nối đồng thời và làm sạch nội dung văn bản. Hãy chỉ lấy số lượng bài thật sự cần thiết và điều phối tần suất phù hợp: ```python import asyncio import logging from vnstock_news import EnhancedNewsCrawler # Cấu hình logging logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s") logger = logging.getLogger("BatchPipeline") async def run_batch_extraction_pipeline(): logger.info("Khởi động quy trình đọc danh mục bài viết từ sitemap...") # Khởi tạo EnhancedNewsCrawler với bộ nhớ đệm SQLite client = EnhancedNewsCrawler( cache_enabled=True, cache_type="sqlite", cache_ttl=86400, # Đệm dữ liệu trong 24 giờ max_concurrency=3 # Tối đa 3 yêu cầu đồng thời; giữ mức thấp để tôn trọng máy chủ nguồn ) # Danh sách sitemap mục tiêu từ các website tin tức tài chính sitemap_sources = [ "https://cafef.vn/latest-news-sitemap.xml", "https://tuoitre.vn/news-sitemap.xml" ] logger.info("Bắt đầu truy xuất bất đồng bộ từ Sitemap sources...") df_corpus = await client.fetch_articles_async( sources=sitemap_sources, site_name="cafef", max_articles=50, clean_content=True # Tự động loại bỏ HTML thừa, quảng cáo ) if not df_corpus.empty: logger.info(f"Đã trích xuất và chuẩn hóa thành công {len(df_corpus)} bài viết.") # Xem thông tin dữ liệu print("\n--- THÔNG TIN BỘ DỮ LIỆU ---") print(df_corpus.info()) print("\n--- MẪU 3 BÀI VIẾT ĐẦU TIÊN ---") print(df_corpus[["title", "author", "publish_time", "source"]].head(3)) # Xuất dữ liệu ra file CSV output_file = "news_corpus_batch_export.csv" df_corpus.to_csv(output_file, index=False, encoding="utf-8-sig") logger.info(f"Dữ liệu đã được xuất ra file: {output_file}") else: logger.warning("Không truy xuất được dữ liệu bài viết nào từ nguồn sitemap đã cho.") if __name__ == "__main__": asyncio.run(run_batch_extraction_pipeline()) ``` Các kịch bản trên hỗ trợ thiết lập quy trình theo dõi tin tức phục vụ nhu cầu cá nhân. Người dùng nên đặt khoảng cách thời gian hợp lý giữa các yêu cầu, tuân thủ hướng dẫn trong `robots.txt` và điều khoản sử dụng của từng website. Bản quyền nội dung và hình ảnh thuộc về đơn vị xuất bản chủ quản. --- ## Document: Tùy biến Nâng cao
Phần này hướng dẫn tùy chỉnh chi tiết từ cấu trúc SiteConfig, thiết lập danh sách bộ chọn CSS dự phòng đến việc tự bổ sung cấu hình cho các website tin tức mới.
## 1. Cấu Trúc `SiteConfig` và Sitemap Động (`DynamicSitemapResolver`) Cấu hình của từng website nguồn được lưu trữ tại bảng từ điển `SITES_CONFIG` trong `vnstock_news.config.sites`. Mỗi cấu hình bao gồm các thông tin: * **`name`**: Tên hiển thị của website (ví dụ: `"Báo CafeF"`). * **`domain`**: Tên miền chính (ví dụ: `"cafef.vn"`). * **`rss`**: Danh sách đường dẫn RSS Feed (`urls: [...]`). * **`sitemap_url`**: Đường dẫn tới Sitemap XML chính. * **`sitemap`**: Cấu hình Sitemap động khi website chia sitemap theo thời gian (`pattern_type` dạng `"monthly"` hoặc `"incremental"`). * **`config`**: Danh sách bộ chọn CSS/XPath để bóc tách tiêu đề, sapo, nội dung, thời gian xuất bản, tác giả và chuyên mục. ### Xử lý Sitemap Động Một số website tin tức (như Tiền Phong, Nhân Dân) phân chia sitemap theo từng tháng hoặc dạng lũy tiến. Lớp `DynamicSitemapResolver` trong `vnstock_news` hỗ trợ tự động xác định đường dẫn Sitemap theo thời gian: ```python from vnstock_news.config.sitemap_resolver import DynamicSitemapResolver from vnstock_news.config.sites import SITES_CONFIG # 1. Khởi tạo resolver ở chế độ ghi log resolver = DynamicSitemapResolver(debug=True) # 2. Lấy cấu hình của website có sitemap động (ví dụ: Tiền Phong) tienphong_config = SITES_CONFIG["tienphong"] # 3. Tính toán URL sitemap phù hợp với thời điểm hiện tại (năm - tháng) resolved_url = resolver.get_sitemap_url("tienphong", tienphong_config) print(f"Sitemap URL được tạo: {resolved_url}") # Kết quả trả về dạng: https://tienphong.vn/sitemaps/news-2026-10.xml ```
Khi thêm một website mới có đường dẫn sitemap thay đổi theo tháng (như news-2026-08.xml) hoặc theo ngày, bạn có thể thiết lập thuộc tính sitemap với pattern_type: "monthly" hoặc "incremental" cùng chuỗi định dạng format tương ứng.
*** ## 2. Thiết Lập Bộ Chọn CSS Dự Phòng Khi cấu hình giao diện bài viết giữa các chuyên mục không đồng nhất, `vnstock_news` hỗ trợ truyền danh sách nhiều bộ chọn (CSS Selectors) theo thứ tự ưu tiên. Thư viện sẽ lần lượt thử nghiệm các bộ chọn trong danh sách cho đến khi tìm thấy dữ liệu. ### Các bộ chọn chuẩn trong `config` Dictionary `config` hỗ trợ các khóa sau: * `title_selector`: Tiêu đề bài viết. * `short_desc_selector`: Đoạn tóm tắt / Sapo. * `content_selector`: Nội dung chính bài viết. * `publish_time_selector`: Thời gian xuất bản. * `author_selector`: Tên tác giả. * `category_selector`: Chuyên mục. * `tags_selector`: Từ khóa / Tags. * `image_url_selector`: Ảnh đại diện bài viết. ### Cấu hình bộ chọn dự phòng và thuộc tính thẻ Một bộ chọn có thể cấu hình tìm kiếm theo thẻ HTML (`tag`), tên lớp (`class`) hoặc lấy trực tiếp thuộc tính thẻ (`attr` như `content`, `datetime`, `src`): ```python custom_advanced_selectors = { # Tiêu đề: Thử class "detail-title" trước, nếu không có chuyển sang thẻ meta "title_selector": [ {"tag": "h1", "class": "detail-title"}, {"tag": "meta", "attr": "property", "value": "og:title", "extract": "content"} ], # Sapo bài viết (phần tóm tắt ở đầu) "short_desc_selector": [ {"tag": "h2", "class": "sapo-detail"}, {"tag": "div", "class": "sapo"} ], # Thời gian xuất bản: Lấy thuộc tính datetime trong thẻ