Chạy backtest và đọc kết quả

run

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). 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ố cấu hình (**config)

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ó.

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

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

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) 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:

# 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

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:

Tear sheet

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_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á 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.

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.

Biểu đồ

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 (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.