Nâng cấp từ bản 0.5 lên 1.0
Mục lục
Từ ngày 10/11/2026, các phiên bản thế hệ 5 (vnstock 5.x, vnstock_quant 0.x, vnstock-mcp 0.x) đã ngừng xác thực. Để tiếp tục dùng máy chủ MCP với trợ lý AI, bạn cần nâng lên vnstock-mcp 1.0 chạy cùng vnstock 6 và vnstock_quant 1.0 bản Cộng đồng.
Cách làm việc giữ nguyên: trợ lý gọi đúng hàm của thư viện, nối các bước bằng call_id, ghi mỗi bước thành câu lệnh Python và xuất thành kịch bản chạy độc lập. Điểm đổi lớn nhất là cách lấy dữ liệu: thế hệ 6 gọi thẳng Open API của nguồn bằng khóa bạn tự đăng ký, và bạn chọn nguồn cho từng lời gọi.
1. Các bước nâng cấp
- Cài hoặc nâng môi trường ảo lên
vnstock-mcp1.0 cùngvnstock6 vàvnstock-oapi. - Chạy
vnstock-mcp --setup <ứng_dụng> --writeđể ứng dụng AI trỏ đúng tới bản 1.0, rồi khởi động lại ứng dụng. - Chạy
vnstock-mcp doctor, rồi gọiquant_entitlement()vàresearch_sources()trong ứng dụng AI để xem công cụ đang mở. - Khi cần dữ liệu thị trường: đăng ký khóa ở nguồn, lưu bằng
vnstock keys set <nguồn>, đặt nguồn ưu tiên bằngvnstock-mcp sources use <nguồn_chính> <nguồn_dự_phòng>.
Không có khóa nguồn nào, bạn vẫn dùng được ngay nhóm research_* và năm công cụ quant_* trên tệp có sẵn trên máy.
2. Lệnh cài đặt
python -m venv ~/.venv && source ~/.venv/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages \
"vnstock-mcp[quant]==1.0.0" "vnstock==6.0.1" "vnstock-oapi==0.1.2"
vnstock-mcp --versionNếu trước đây bạn đăng ký vnstock-mcp từ một môi trường ảo khác, chạy lại vnstock-mcp --setup <ứng_dụng> --write trong môi trường mới để tệp cấu hình của ứng dụng AI cập nhật đường dẫn.
3. Những gì giữ nguyên và thay đổi
| Hạng mục | Bản 0.5 (thế hệ 5) | Bản 1.0 (thế hệ 6) |
|---|---|---|
| Thư viện dữ liệu nền | vnstock thế hệ 5, cài rời. | vnstock 6 và vnstock-oapi là phụ thuộc bắt buộc; đầu ra theo compat="v6". |
| Cách lấy dữ liệu | Theo cấp tài khoản Vnstock. | Gọi thẳng Open API của nguồn bằng khóa của bạn; công cụ dữ liệu mở theo khóa có trên máy. |
Chọn nguồn (source) | Thư viện tự gán một nguồn mặc định. | Bạn chọn qua source ở mọi công cụ dữ liệu hoặc lưu quy tắc bằng vnstock-mcp sources use. |
| Công cụ định lượng | Cài riêng vnstock_quant 0.x. | Cài gọn qua [quant]; bản Cộng đồng mở 5 công cụ quant_* với lượt dùng thử trong ngày. |
| Dòng lệnh | Các cờ --doctor, --setup, --profile… | Thêm lệnh con onboard, status, doctor, setup, sources, tools, call, workspace, serve và giao diện tương tác trong Terminal; cờ cũ vẫn dùng được. |
| Kết quả JSON | call_id, code, provenance và các dòng dữ liệu. | Giữ nguyên, thêm warnings. code dài được rút gọn trên khung trò chuyện nhưng giữ đủ trong nhật ký phiên. |
| Phép tính quá thời gian chờ | Báo hết giờ; gọi lại thì gửi thêm yêu cầu trùng. | Trả StillRunning; gọi lại với cùng tham số sẽ chờ đúng phép tính đang chạy. |
| Thư mục nghiên cứu và hồ sơ | ~/vnstock_research; hồ sơ minimal, research, data, full. | Giữ nguyên; thêm biến VNSTOCK_MCP_IMPORT_MB. |
| Thời hạn bản phát hành | — | 30 ngày với bản rc, 365 ngày với bản chính thức. |
4. Công cụ mới dùng được ở bản Cộng đồng
| Công cụ | Công dụng |
|---|---|
research_import | Nạp tệp CSV, Excel, Parquet, JSON có sẵn trên máy vào phiên để tính tiếp. |
research_pdf, research_bctc, research_vas | Đọc, bóc bảng và chuẩn hóa BCTC từ tệp PDF theo từ điển VAS (bản Cộng đồng: chỉ tiêu cấp 1). |
research_sources | Xem nguồn dùng được trên máy và tuyến dữ liệu mỗi nguồn hỗ trợ. |
quant_backtest | Chạy thử chiến lược một mã theo luật thị trường Việt Nam với 10 chỉ báo trong bảng quy tắc dsl. |
market_global_index | Chuỗi lịch sử chỉ số chứng khoán quốc tế, hiện khi máy có khóa của nguồn hỗ trợ. |
quant_ta và quant_fa nhận thêm source; quant_fa thêm price_source và estimate_shares; quant_backtest nhận refs để lấy đầu ra của bước trước.
5. Công cụ đã bỏ hoặc tạm ẩn
Ở bản 0.5 | Ở bản 1.0 | Thay bằng |
|---|---|---|
research_normalize, research_benchmark | Đã bỏ | Chuẩn hóa nay nằm sẵn trong vnstock 6 (compat="v6"). Bảng lấy từ nơi khác thì nạp bằng research_import kèm columns. |
research_universe | Đã thay | research_vas để tra từ điển chỉ tiêu VAS. |
macro_economy, macro_currency, macro_global | Mở theo khóa nguồn | Chỉ hiện khi máy có khóa của nguồn hỗ trợ dữ liệu vĩ mô. |
insights_flow, insights_sentiment | Tạm ẩn | Khối ngoại và tự doanh: market_equity với method="foreign_flow" hoặc "proprietary_flow" (market_index cho chỉ số), khi nguồn đã có khóa hỗ trợ. |
retail_exchange_rate | Tạm ẩn | Chưa có nguồn Open API cho tỷ giá bán lẻ ngân hàng; tỷ giá quốc tế dùng market_forex. |
6. Đổi giá trị method trên một số công cụ dữ liệu
| Công cụ | method đã bỏ | method mới hoặc giữ lại |
|---|---|---|
fundamental_equity | ratio, note, financial_health | Chỉ số tài chính nay tính kèm công thức qua quant_fa. |
reference_company | officers, subsidiaries, affiliate, capital_history | Giữ info, shareholders, ownership, insider_trading, events. |
reference_equity | — | Thêm price_limits, status. |
reference_market | (gọi không kèm method) | Thêm status, sessions, trading_days. |
reference_fund | fee_structure, reports | Giữ list, profile. |
market_equity | odd_lot | Thêm active_flow, expected_price, summary. |
market_index | — | Thêm foreign_flow, proprietary_flow. |
market_etf | — | Thêm summary. |
market_board | odd_lot | Thêm foreign_room. |
market_fund | holdings, asset_allocation, industry_allocation, dividends | Giữ history, performance. |
Công cụ dữ liệu chỉ hiện các method mà nguồn bạn đã lưu khóa hỗ trợ.
7. Mẫu quy trình và dữ liệu đã lưu
MCP Prompts: bản 1.0 thêm mẫu bctc_deep_dive (đọc và kiểm tra chuyên sâu BCTC PDF trên máy), dùng được ngay ở bản Cộng đồng. Mẫu nào cần công cụ chưa mở trên máy thì tự ẩn: market_overview và macro_dashboard hiện khi nguồn bạn đã lưu khóa hỗ trợ đủ các công cụ mà mẫu cần; study_stock và reproducible_study dùng công cụ của bản Mở rộng.
Dữ liệu và kịch bản cũ:
- Bảng đã lưu trong
~/vnstock_research/data/từ bản 0.5 vẫn đọc lại được ở bản 1.0 theo tên (data="ten_bang").research_datasetsnhắc bạn thêmsourcenếu muốn chạy lại câu lệnh tạo bảng trênvnstock6. - Kịch bản
.pyxuất từ bản 0.5 cần sửa cú pháp và thêmsourcetheo Chuyển đổi lên vnstock 6, vìvnstockthế hệ 5 đã ngừng xác thực. Kịch bản xuất từ bản 1.0 luôn ghi sẵnvnstock.compat.use("v6")vàsourceở từng lời gọi. - Nhật ký phiên của cả hai bản cùng nằm trong
~/vnstock_research/journal/, mỗi phiên một tệp, không xung đột.
