Gọi hàm bằng JSON và tích hợp máy chủ MCP
Mục lục
Tính năng trên trang này đang trong giai đoạn phát triển thử nghiệm và chưa ổn định. Bạn dùng được để tìm hiểu và chạy thử, nhưng 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, cách tính và cách xử lý cũng có thể còn được hiệu chỉnh.
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 để mã đang chạy không tự đổi theo bản mới.
Toàn bộ các hàm phân tích danh mục, định giá và chạy thử chiến lược của vnstock_quant đều hỗ trợ cơ chế gọi qua tên hàm kèm một đối tượng tham số JSON và trả kết quả về dưới dạng JSON thuần. Mỗi hàm cung cấp sẵn một bản mô tả JSON Schema chuẩn, cho phép bạn đăng ký trực tiếp làm định nghĩa công cụ (tool definition / function calling) cho trợ lý AI hoặc máy chủ MCP mà không cần viết thêm lớp chuyển đổi trung gian. Mọi lời gọi qua JSON đều đi qua chính lõi Rust và tầng kiểm tra cấp quyền giống hệt như khi gọi hàm Python thông thường.
Quy trình gọi hàm an toàn dành cho AI Agent
Khi thiết lập luồng làm việc cho AI Agent, hãy hướng dẫn Agent tuân thủ trình tự 4 bước cố định:
- Gọi
catalog()để tìm đúng tên hàm cần dùng. - Gọi
schema(name)để đọc cấu trúc tham số bắt buộc và kiểu dữ liệu. - Gọi
call(name, **args)để thực thi phép tính. - Kiểm tra mã lỗi (
code) nếu có ngoại lệ và đọc trườngwarningstrong kết quả trả về.
AI Agent không được tự đoán tên tham số từ tên hàm, không tự ý chọn nguồn dữ liệu, không tự điền giá trị giả định vào chỗ thiếu và không diễn giải kết quả mô phỏng thành dữ kiện thị trường. Trong trường hợp nội dung ví dụ mẫu khác với JSON Schema, hãy luôn lấy kết quả từ schema(name) của phiên bản đang cài làm chuẩn. Nếu gặp lỗi thiếu quyền sử dụng, Agent cần báo lại cho người dùng kèm mã code và hướng dẫn trong action, tuyệt đối không chuyển đổi sang giao diện gọi khác để thử vượt giới hạn.
Bảng hỗ trợ giao diện JSON theo từng mô-đun
| Mô-đun | catalog() | schema(name) | call(name, **args) |
|---|---|---|---|
portfolio (bao gồm cả nhóm hàm valuation) | Có | Có | Có |
backtest | Có | Có | Có |
ta, fa, risk, micro | Có | — | Gọi trực tiếp qua hàm Python hoặc qua Vnstock MCP |
Tra cứu danh mục công cụ và lấy JSON Schema
Bạn sử dụng cặp hàm catalog() và schema(name) để lấy siêu dữ liệu của từng công cụ:
from vnstock_quant import portfolio as pm
cat = pm.catalog() # gồm các cột: name, group, describe, standard
cat.groupby("group").size() # các nhóm: 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 thuộc tính bên trong parameters.properties đều ghi rõ kiểu dữ liệu (type), mô tả ý nghĩa (description) và giá trị mặc định (default nếu có). Trường standard trích dẫn tài liệu học thuật hoặc giáo trình gốc của công thức.
Chỉ với một vòng lặp ngắn, bạn có thể xuất toàn bộ 38 hàm danh mục và định giá thành danh sách công cụ chuẩn cho LLM:
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) # 38Tương tự, mô-đun backtest cung cấp 15 công cụ với cấu trúc khoá tuân theo chuẩn MCP (name, description, input_schema):
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_portfolio', 'sweep',
# 'walk_forward', 'monte_carlo', 'deflated_sharpe_ratio', 'run_fixture_demo', 'portfolio_analytics']
bt.schema("run_backtest")["input_schema"]["required"] # ['bars']Từ bản 1.0, mô-đun backtest bổ sung thêm 5 công cụ JSON mới để đưa toàn bộ tính năng kiểm thử danh mục và kiểm định chống quá khớp ra giao diện JSON (nhận cùng bộ tham số với hàm Python tương ứng):
| Tên công cụ JSON | Tham số bắt buộc | Hàm Python tương ứng | Cấp quyền và giới hạn quy mô |
|---|---|---|---|
run_portfolio | assets | bt.run_portfolio | Yêu cầu quyền bt_portfolio; số mã tối đa theo cấp tài khoản |
sweep | bars, tasks | bt.sweep | Yêu cầu quyền bt_optimize; số tổ hợp tham số tối đa theo cấp |
walk_forward | bars, tasks | bt.walk_forward | Yêu cầu quyền bt_optimize |
monte_carlo | returns | bt.monte_carlo | Yêu cầu quyền bt_optimize; số đường mô phỏng tối đa theo cấp |
deflated_sharpe_ratio | returns | bt.deflated_sharpe_ratio | Không yêu cầu quyền riêng |
Kết quả trả về của công cụ run_backtest cũng có thêm trường daily_returns, giúp bạn truyền thẳng chuỗi lợi suất ngày sang monte_carlo hoặc deflated_sharpe_ratio mà không cần tự tính lại.
Thực thi phép tính qua hàm call()
Ví dụ gọi các hàm danh mục và định giá qua pm.call():
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 tính từ mốc 1970-01-01 (epoch days)
values=[100e6, 112e6, 150e6],
flows=[0, 30e6, 0],
)Đối với mô-đun backtest, dữ liệu nến truyền vào là một danh sách các từ điển (date theo định dạng YYYY-MM-DD, cùng open, high, low, close, volume) và quy tắc giao dịch dsl là một đối tượng JSON — rất thuận tiện để trợ lý AI khởi tạo trực tiếp từ yêu cầu bằng ngôn ngữ tự nhiên:
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, daily_returns
res["tear_sheet"]["total_return_pct"], res["tear_sheet"]["sharpe_ratio"]Các quy ước dữ liệu chuẩn khi gọi qua giao diện JSON:
- Định dạng ngày tháng: Là số nguyên biểu thị số ngày kể từ mốc
1970-01-01đối với các hàm trongportfolio, và là chuỗi"YYYY-MM-DD"đối với các công cụ trongbacktest. - Mảng và ma trận: Mảng một chiều truyền dưới dạng danh sách số (
list); ma trận hai chiều truyền dưới dạng danh sách của các hàng. - Biểu diễn tỷ lệ: Luôn dùng phân số thập phân (ví dụ
0.18đại diện cho 18%). - Kiểm tra nghiêm ngặt tên tham số: Mọi tham số lạ không có trong schema đều bị từ chối ngay lập tức để trợ lý AI phát hiện lỗi cú pháp.
- Mã lỗi nhất quán: Khi xảy ra lỗi, ngoại lệ ném ra luôn có mã
codeổn định (QUANT_INVALID_PARAMETER,QUANT_INPUT_DATA,QUANT_UNKNOWN_FUNCTION,QUANT_UNKNOWN_TOOL) kèm thông báo chỉ rõ tên tham số bị sai để AI Agent tự động sửa lại lời gọi.
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`Tra cứu catalog có cấu trúc ở các mô-đun còn lại
Mặc dù các mô-đun ta, fa, risk và micro nhận đầu vào là pandas.DataFrame thông qua hàm Python, tất cả đều cung cấp hàm catalog() trả về bảng siêu dữ liệu chuẩn để trợ lý AI tra cứu tên hàm, đơn vị đo và tài liệu đối chiếu trước khi sinh mã:
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") # xem công thức chi tiết theo từng mẫu ngành và hồ sơBạn cũng có thể tra cứu và gọi thử trực tiếp từ terminal bằng công cụ dòng lệnh: chạy vnstock-quant tools twr để xem tham số, vnstock-quant call list_profiles để gọi thử công cụ, vnstock-quant catalog fa RT_PRT_ROE để xem công thức chỉ số, hoặc vnstock-quant onboard --json để xuất toàn bộ trạng thái máy và quy tắc an toàn cho trợ lý AI. Xem thêm tại trang Công cụ dòng lệnh vnstock-quant.
Kết nối với trợ lý AI qua máy chủ Vnstock MCP
Vnstock MCP là máy chủ giao thức MCP chạy cục bộ ngay trên máy cá nhân của bạn, đóng vai trò cầu nối đưa các mô-đun của vnstock_quant tới các ứng dụng AI (như Claude Desktop, Cursor, Antigravity...).
Phiên bản vnstock-mcp 1.0 (hiện ở nhánh thử nghiệm) hoạt động đồng bộ với vnstock_quant 1.0 và vnstock 6, cung cấp đầy đủ các nhóm công cụ: quant_ta, quant_fa, quant_risk, quant_returns, quant_portfolio, quant_prices, quant_micro, quant_backtest (bao gồm cả backtest danh mục, dò tham số, walk-forward, Monte Carlo, Deflated Sharpe) và quant_catalog. Nhờ cơ chế truyền bảng dữ liệu trực tiếp bên trong bộ nhớ phiên làm việc của MCP, trợ lý AI không cần phải sao chép hàng nghìn con số qua cửa sổ trò chuyện. Mọi quy tắc phân quyền, đếm lượt thử và cảnh báo đều hoạt động giống hệt như khi gọi hàm Python, với danh sách cảnh báo nằm trong trường warnings của kết quả.
Xem danh sách chi tiết các công cụ MCP tại trang Danh mục công cụ Vnstock MCP v1.
Quy tắc kiểm tra quyền sử dụng khi gọi qua JSON
Các hàm trong portfolio và valuation yêu cầu gói tài khoản từ Bronze trở lên; tính năng backtest 1 mã với 10 chỉ báo cơ bản được mở cho mọi cấp tài khoản (theo lượt thử ở bản Cộng đồng), còn các công cụ backtest nâng cao yêu cầu từ gói Bronze. Toàn bộ lời gọi qua call() đều đi qua cùng cổng kiểm tra cấp quyền, cùng bộ đếm lượt thử và cùng ngưỡng quy mô như khi gọi hàm Python. Xem bảng phân quyền đầy đủ tại trang Quyền dùng và hạn mức theo cấp tài khoản.
Tài liệu đọc tiếp
- Phân tích và tối ưu danh mục — Ý nghĩa và hướng dẫn sử dụng chi tiết cho 38 hàm trong danh mục
portfolio. - Dữ liệu đầu vào và cách tạo tín hiệu trong backtest — Quy ước viết bảng quy tắc giao dịch
rule_dslbằng JSON. - Hướng dẫn tích hợp trợ lý AI — Cách thiết lập môi trường làm việc kết hợp giữa Vnstock và AI Agent.
