Vnstock Logo

Gọi bằng JSON và MCP

Mở rộ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.

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ómcatalog()schema(name)call(name, **args)
portfolio (gồm các hàm định giá)CóCóCó
backtestCóCóCó
ta, fa, risk, microCó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 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.

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.

Đọc tiếp

Tags

vnstock_quant
json
mcp