Tính toán và chạy thử chiến lược

Nhóm tool quant_* gọi vnstock_quant 1.0.0rc1 trên máy bạn. Trợ lý không tự viết mã tính chỉ báo hay vòng lặp backtest: nó gọi đúng hàm của thư viện, và mỗi lần gọi để lại mã Python tương đương. Cần cài vnstock-mcp[quant].

Nhóm tính năng nào mở ở cấp nào, lượt thử của bản Cộng đồng và quy mô mỗi lần chạy thử do vnstock_quant quyết định: Quyền dùng và hạn mức. vnstock-mcp không tự đếm lượt.

Nối bước bằng call_id

Bảng dài không chép qua cuộc trò chuyện. Mỗi kết quả có call_id, và bước sau nhận nó theo hai cách:

• data: một bảng đã có trong phiên ("c3") hoặc bảng đã lưu theo tên ("fpt_1y"), thay cho symbol.
• refs: tham số của hàm lấy từ kết quả trước.

Kết quả mô hình có mảng dài (chuỗi lợi suất, đường tài sản) chỉ hiện phần cuối cho trợ lý; bản đủ nằm trong call_id.

Các tool

Tool không mở ở cấp của bạn thì không xuất hiện; quant_ta chỉ liệt kê chỉ báo bạn dùng được.

Chỉ báo và rủi ro

quant_ta(indicator="rsi", symbol="FPT", lookback="1Y", length=14, source="ssi")
quant_ta(indicator="macd", data="c1")                 # trên bảng giá đã có
quant_risk(method="summary", symbol="FPT", benchmark="VNINDEX", source="ssi")
quant_risk(method="sharpe_ratio", data="c1")          # tính từ cột close

Chỉ số tài chính

quant_fa(symbols="FPT", period="year", source="fhsc", price_source="ssi",
         ids=["RT_PRT_ROE", "RT_VALUE_PE", "RT_VALUE_PB"])

• source là nguồn báo cáo tài chính, price_source là nguồn giá dùng cho chỉ số định giá. Hai nguồn có thể khác nhau.
• Chỉ tải báo cáo của period được hỏi. Lần đầu mỗi mã có thể quá một phút (xem Lời gọi lâu).
• Cột reason nói vì sao một chỉ số thiếu. MISSING_MARKET: thiếu giá hoặc số cổ phiếu. Open API chưa có số cổ phiếu theo ngày, nên P/E, P/B, EPS trả MISSING_MARKET, trừ khi bạn bật estimate_shares=true: thư viện ước số cổ phiếu từ vốn điều lệ. Đó là số ước tính, có thể lệch nhiều sau đợt phát hành; trợ lý được dặn nói rõ điều này, và provenance ghi lại.
• MISSING_INPUT: báo cáo thiếu dòng chi tiết mà công thức cần.
• Công thức từng chỉ số: quant_catalog(module="fa", name="RT_PRT_ROE").

Danh mục nhiều mã

quant_returns(symbols="FPT,VCB,HPG", lookback="1Y", source="ssi")          → c1
quant_portfolio(method="covariance", refs={"returns": "c1"})                → c2
quant_portfolio(method="max_sharpe", args={"rf": 0.0},
                refs={"cov": "c2", "mu": "c1.mean"})                        → c3
quant_portfolio(method="concentration", refs={"weights": "c3.weights"})

Tỷ trọng theo thứ tự cột của bảng lợi suất. Tham số của từng hàm: quant_catalog(module="portfolio", name="max_sharpe"). Kết quả mô hình đúng trên giả định đưa vào; khi mọi mã có lợi suất kỳ vọng không vượt rf, thư viện báo Sharpe tối đa không xác định thay vì trả một tỷ trọng vô nghĩa.

Giá điều chỉnh

quant_prices(method="from_vnstock", symbol="FPT", start="2025-01-01", end="2025-12-31",
             source="ssi", events_source="ssi")
quant_prices(method="adjust", data="c4", events="c5")      # trên bảng phiên và bảng sự kiện đã lấy

from_vnstock đọc hai loại dữ liệu: phiên giao dịch (source) và lịch sự kiện (events_source), mỗi loại một nguồn. Kết quả tính theo VND. warnings cho biết sự kiện nào lệch với giá tham chiếu của sàn và bảng giá có thiếu giá trần, giá sàn không; hãy đọc trước khi dùng. Một năm dữ liệu có thể mất hơn một phút.

Vi cấu trúc trên khớp lệnh

market_equity(symbol="FPT", method="trades", source="dnse")                    → c6
quant_micro(method="bars", data="c6", params={"by": "volume", "size": 50000})  → c7
quant_micro(method="vpin", data="c7")     # VPIN cần nến khối lượng có buy_volume, sell_volume
quant_micro(method="cvd", data="c6")

Chạy thử chiến lược

quant_backtest(tool=..., args=..., refs=..., data=... hoặc symbol=...) gọi một trong các công cụ của vq.backtest:

Luật vào, ra viết bằng bảng quy tắc dsl trên chỉ báo, không phải đếm số phiên để viết danh sách tín hiệu:

quant_backtest(tool="run_backtest", symbol="HPG", lookback="1Y", source="ssi", args={"dsl": {
  "entry_rules": [{"left": {"ind": "sma", "params": {"length": 10}}, "op": "cross_above",
                   "right": {"ind": "sma", "params": {"length": 30}}}],
  "exit_rules":  [{"left": {"ind": "sma", "params": {"length": 10}}, "op": "cross_below",
                   "right": {"ind": "sma", "params": {"length": 30}}}]}})                     → c8
quant_backtest(tool="monte_carlo", refs={"returns": "c8.daily_returns"})
quant_backtest(tool="deflated_sharpe_ratio", refs={"returns": "c8.daily_returns"}, args={"num_trials": 20})

• symbol lấy giá qua vnstock; data dùng bảng giá đã có, kể cả bảng bạn nhập từ tệp. Khi nhiều bước cần cùng một bảng giá (xem tín hiệu bằng eval_rule_dsl rồi mới chạy thử), lấy giá một lần bằng market_equity rồi truyền data cho các bước, để mọi bước tính trên đúng một bảng.
• Tín hiệu tự viết vẫn dùng được: entries, exits trong args, hoặc lấy từ kết quả của eval_rule_dsl qua refs={"entries": "c7.entries", "exits": "c7.exits"}.
• run_portfolio nhận assets: mỗi mục có symbol (hoặc data) và dsl hay entries/exits; có rebalance thì tín hiệu là tuỳ chọn.
• Tham số đầy đủ của từng công cụ: quant_catalog(module="backtest", name="run_backtest").
• warnings của kết quả ghi giả định cần biết, ví dụ biểu phí chưa xác minh.

Lời gọi lâu

Mặc định mỗi tool chờ 60 giây (VNSTOCK_MCP_TIMEOUT). Lời gọi tải nhiều dữ liệu, như quant_fa lần đầu hay quant_prices nhiều năm, có thể lâu hơn. Khi đó trợ lý nhận lỗi StillRunning: phép tính vẫn chạy trên máy và kết quả được giữ lại. Gọi lại đúng tham số đó thì lời gọi mới chờ chính phép tính đang chạy, không gửi thêm yêu cầu tới nguồn, nên không làm bạn vượt giới hạn tần suất của nguồn. Với tool không giữ kết quả, lỗi nói rõ điều đó và gợi ý thu hẹp khoảng thời gian.