Vnstock Logo

Gọi hàm bằng JSON và tích hợp máy chủ MCP

Cộng đồng

Mục lục

Tính năng đang thử nghiệm

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:

  1. Gọi catalog() để tìm đúng tên hàm cần dùng.
  2. Gọi schema(name) để đọc cấu trúc tham số bắt buộc và kiểu dữ liệu.
  3. Gọi call(name, **args) để thực thi phép tính.
  4. Kiểm tra mã lỗi (code) nếu có ngoại lệ và đọc trường warnings trong 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ô-đuncatalog()schema(name)call(name, **args)
portfolio (bao gồm cả nhóm hàm valuation)CóCóCó
backtestCóCóCó
ta, fa, risk, microCó—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ụ:

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

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

Tươ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):

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_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ụ JSONTham số bắt buộcHàm Python tương ứngCấp quyền và giới hạn quy mô
run_portfolioassetsbt.run_portfolioYêu cầu quyền bt_portfolio; số mã tối đa theo cấp tài khoản
sweepbars, tasksbt.sweepYêu cầu quyền bt_optimize; số tổ hợp tham số tối đa theo cấp
walk_forwardbars, tasksbt.walk_forwardYêu cầu quyền bt_optimize
monte_carloreturnsbt.monte_carloYêu cầu quyền bt_optimize; số đường mô phỏng tối đa theo cấp
deflated_sharpe_ratioreturnsbt.deflated_sharpe_ratioKhô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():

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

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, 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 trong portfolio, và là chuỗi "YYYY-MM-DD" đối với các công cụ trong backtest.
  • 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.
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`

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

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")                  # 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