Chuyển từ bản 3.x
Mục lục
Trang này viết cho vnstock_pipeline v6.0.0rc1, bản thử nghiệm. Tên hàm, tham số và cột dữ liệu có thể còn đổi trước ngày phát hành; khi cài, ghi rõ số phiên bản như ở trang Cài đặt. Bản đang phát hành chính thức là v3.1.1, xem tài liệu bản đó.
Trang này dành cho người đang dùng vnstock_pipeline bản 3.x, thuộc đợt phát hành Vnstock thế hệ 5. Thế hệ 6 viết lại
từ đầu trên dữ liệu bạn lấy bằng khoá của mình. Ý tưởng cốt lõi giữ nguyên: tải theo lô, lưu có tổ chức, kiểm chất
lượng, xuất AmiBroker. Tên lệnh, bố cục thư mục và lớp Python thì đổi.
Thứ tự nên làm
- Cài thế hệ 6 vào một môi trường ảo riêng, cạnh môi trường đang chạy bản 3.x.
- Đăng ký khoá ở nguồn bạn định dùng, lưu bằng
vnstock-oapi keys set …(Cài đặt và tài khoản). - Giữ tệp
pipeline.tomlđang có; thêm bảng[sources]cho nguồn bạn có khoá. - Chạy thử
migrate-legacy --dry-run, rồi chuyển dữ liệu đã lưu. - Chạy lại các lệnh hằng ngày theo bảng đối chiếu bên dưới; sửa lịch chạy.
- Đối chiếu vài mã giữa hai thư mục trước khi bỏ bản 3.x.
Cài cạnh bản 3.x
Gói thế hệ 6 cùng tên vnstock-pipeline, chỉ đổi số phiên bản, và kéo theo vnstock 6. Cài vào môi trường đang
có bản 3.x sẽ thay cả pipeline lẫn vnstock thế hệ 5 ở đó.
# môi trường mới cho thế hệ 6
python -m venv ~/.venv_pipeline6 && source ~/.venv_pipeline6/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock==6.0.0rc2" "vnstock-oapi==0.1.0rc1"
vnstock install "vnstock-pipeline[rest,stream]==6.0.0rc1"
# môi trường cũ: ghim bản 3.x để không bị nâng nhầm
pip install "vnstock-pipeline<6"Đăng nhập tài khoản Vnstock dùng chung. Nếu đã đăng nhập cho bản 3.x thì thế hệ 6 dùng được ngay; kiểm bằng
vnstock-pipeline account status.
Điều gì giữ, điều gì đổi
| Bản 3.x | Thế hệ 6 | |
|---|---|---|
| Dữ liệu vào | Qua vnstock thế hệ 5 | Qua vnstock 6 và vnstock-oapi, bằng khoá bạn đăng ký ở từng nguồn |
| Tệp cấu hình | ~/.vnstock/config/pipeline.toml | Cùng tệp. Bảng [storage], [metadata] cũ vẫn đọc được; bảng mới là [store], [sources], [reference], [calendar], [watchlists], [stream] |
| Thư mục | ~/stock_db/ohlcv/<MÃ>.parquet, intraday/<khung>/…, session_stats/foreign_flow/… (bố cục flat) hoặc dưới processed/market/ (nested) | ~/stock_db/market/ohlcv/<khung>/<MÃ>.parquet, market/trades/<ngày>/…, reference/…, stream/… |
| Định dạng | Parquet hoặc CSV | Chỉ Parquet; CSV qua export csv |
| Đơn vị | Theo nguồn | Giá cổ phiếu nghìn đồng, chỉ số và phái sinh điểm, khối lượng cổ phiếu, giá trị đồng, giờ Việt Nam có múi giờ |
| Lệnh | vnstock_pipeline … | vnstock-pipeline … |
| Chất lượng | Cấu trúc chuẩn, cách ly, kiểm toàn vẹn | Giữ nguyên cách làm, thêm mã kiểm theo lịch giao dịch |
| AmiBroker | CSV kiểu CafeF và tệp .format | Giữ nguyên cột và tệp .format |
| Streaming | Khung kết nối, bạn tự mang cấu hình; mẫu Binance | Kênh khai sẵn của bốn nguồn; sự kiện chuẩn chung bộ cột; nến dựng trong lõi Rust |
| Tài khoản | Cấp Golden trở lên; mỗi lượt chạy trừ một đơn vị hạn mức | Cấp Golden trở lên; kiểm giấy phép, không trừ hạn mức |
Chuyển dữ liệu đã lưu
vnstock-pipeline migrate-legacy ~/stock_db --dry-run # đếm tệp và dòng sẽ chuyển, không ghi
vnstock-pipeline migrate-legacy ~/stock_dbLệnh đọc dữ liệu bản 3.x ở cả hai bố cục flat và nested:
| Dữ liệu bản 3.x | Ghi vào |
|---|---|
ohlcv/<MÃ> (nến ngày) | market/ohlcv/1D/<MÃ>.parquet |
intraday/<khung>/<MÃ>, ohlcv/<khung>/<MÃ> với khung 1m, 5m, 15m, 30m, 1H | market/ohlcv/<khung>/<MÃ>.parquet |
session_stats/foreign_flow/<MÃ> | market/foreign_flow/<MÃ>.parquet |
Lệnh xử lý từng tệp như sau:
- gắn múi giờ Việt Nam cho mốc giờ;
- đổi tên cột sang tên của thế hệ 6, ví dụ
tickerthànhsymbol,buy_volthànhforeign_buy_volume; - ghi qua luật gộp như mọi lần ghi khác, nên chạy lại không tạo dòng trùng.
Tệp đã chuyển mang nguồn legacy_v5 trong metadata. Lệnh không xoá tệp cũ, và in JSON gồm số tệp, số dòng, tệp bỏ
qua (không nhận ra cột), tệp lỗi.
Dữ liệu khác của bản 3.x không được chuyển, gồm báo cáo tài chính, tin tức, khớp lệnh trong ngày và hồ sơ doanh nghiệp. Nạp lại bằng tác vụ của thế hệ 6 nếu nguồn có, hoặc giữ nguyên trong thư mục cũ.
Sau khi chuyển, chạy vnstock-pipeline run ohlcv --group VN30. Pipeline đọc lại 10 nến cuối và tự tải lại lịch sử của
mã nào có giá đã bị điều chỉnh, nên dữ liệu cũ và mới khớp nhau về sau.
Đối chiếu lệnh
| Việc | Bản 3.x | Thế hệ 6 |
|---|---|---|
| Tạo cấu hình | storage init-config | config init |
| Tạo thư mục lưu trữ | storage init | store init |
| Xem thư mục | storage tree, storage report, storage audit | store tree, store report, store audit |
| Mục lục | storage build-catalog | store catalog --rebuild |
| Gộp tệp stream | (không có) | store compact; phiên tự gộp khi kết thúc |
| Dọn dữ liệu cũ | storage cleanup | Chưa có |
| Đổi định dạng, bố cục | storage set-format, set-layout | Không mang sang (chỉ Parquet, một bố cục) |
| Chuyển dữ liệu cũ | storage migrate-legacy | migrate-legacy <thư mục> |
| Nến ngày | run ohlcv --group VN30 | run ohlcv --group VN30 |
| Nến phút | run ohlcv --interval 1m | run ohlcv --interval 1m |
| Nến chỉ số | run ohlcv --universe index | run ohlcv --group INDEX |
| Khớp lệnh | run trades | run trades --dates 2026-10-30 |
| Bảng giá | run quote | run quote (bảng giá và sổ lệnh) |
| Chỉ số trong phiên | (qua mã Python) | run index |
| Khối ngoại, thống kê phiên | run session-stats | run foreign, run session-stats |
| Thoả thuận | (không có) | run block-trades |
| Danh mục, sự kiện | run reference, run events | run reference (danh mục, thành phần chỉ số, trần sàn, ngày giao dịch, sự kiện) |
| Doanh nghiệp | run company | run company --parts info,shareholders,ownership,insider_trading |
| Báo cáo tài chính, tin tức | run financial, run news | Chưa có |
| Tải bù mã lỗi | --retry-errors | Chạy lại cùng lệnh; mã đã mới được bỏ qua |
| Nhóm thanh khoản | universe build-liquidity | universe build-liquidity; xem nhóm: universe show --group LIQUIDITY |
| Tra tệp | inspect, head, tail, stats, schema | Giữ nguyên |
| Truy vấn SQL | query | Chưa có |
| Cách ly | quarantine list, adopt, discard | Giữ nguyên |
| AmiBroker | export amibroker --export-types adjusted,index | export amibroker --kinds ohlcv,index,foreign |
| AmiBroker trong phiên | run live_amibroker | Chưa có |
| CSV, Excel | Qua mã Python | export csv, export parquet, export excel |
| Stream | Mã Python với tệp hồ sơ TOML | stream run <nguồn> <kênh…>, stream record, stream replay |
| Đăng nhập | Qua vnstock hoặc thư viện khác | account login, hoặc dùng lần đăng nhập sẵn có |
| Xem giấy phép | vnstock_pipeline.license_status() | account status; license_status() vẫn có |
| Đo lượt dùng | vnstock_pipeline.telemetry.disable() | account telemetry off; telemetry.disable() vẫn có |
Mọi lệnh thế hệ 6 in JSON, trừ store tree, head, tail, stats.
Đối chiếu mã Python
| Bản 3.x | Thế hệ 6 |
|---|---|
DataManager().load_ohlcv("FPT", start_date=..., end_date=...) | Store().read("ohlcv", "FPT", interval="1D", start=..., end=...) |
DataManager(base_path=...) | Store("...") |
PathBuilder, StorageConfig | Store().layout.path(...), PipelineConfig.load() |
| Tác vụ tải theo lô trong mã | Runner().ohlcv(group="VN30"), Runner().trades(...)… |
run_profile(...), ProfileClient(...) với tệp hồ sơ TOML | Session(store, "<nguồn>", ["<kênh>"], ["<mã>"]).run(seconds=...) |
# bản 3.x
from vnstock_pipeline.core.storage import DataManager
df = DataManager().load_ohlcv("VNM", start_date="2026-01-01", end_date="2026-03-01")
# thế hệ 6
from vnstock_pipeline import Store
df = Store().read("ohlcv", "VNM", interval="1D", start="2026-01-01", end="2026-03-01")Tên cột theo thế hệ 6: time (có múi giờ Việt Nam), open, high, low, close, volume, symbol. Giá cổ phiếu
tính bằng nghìn đồng. Mã cũ đọc cột ticker cần đổi sang symbol.
Chuyển quy trình streaming
Ở bản 3.x, bạn tự viết tệp hồ sơ TOML: địa chỉ kết nối, cách đăng ký kênh, quy tắc bóc tách. Thế hệ 6 bỏ cách làm đó. Kênh của từng nguồn đã khai sẵn trong phần kết nối, và chỉ kênh khai sẵn mới được đăng ký.
| Bản 3.x | Thế hệ 6 |
|---|---|
Hồ sơ Binance mẫu (<mã>@trade, <mã>@kline_1m…) | vnstock-pipeline stream run binance trade kline.1m --symbols BTCUSDT |
aggTrade, miniTicker, ticker, bookTicker, depth | agg_trade, mini_ticker, ticker, book_ticker, depth.{levels} |
| Tự dựng nến từ tệp tick bằng mã riêng | Nến dựng sẵn trong phiên (--intervals 1m,5m), hoặc replay_bars("phien.jsonl", "1m") |
| Tệp tick tự đặt tên | stream/trades/source=<nguồn>/date=<ngày>/, cùng bộ cột cho mọi nguồn |
Danh sách kênh của từng nguồn ở Dữ liệu trong phiên.
AmiBroker
Cột CSV, tệp .format và cách chia tệp theo sàn giữ như bản 3.x, nên quy trình Import ASCII trong AmiBroker không đổi.
Tên tham số đổi từ --export-types sang --kinds: adjusted thành ohlcv, index và foreign giữ tên. Hai loại raw (giá chưa điều chỉnh) và proprietary (tự doanh) của bản 3.x chưa có. Cập nhật trong phiên (live_amibroker) và nạp qua OLE chưa có ở bản
này (Mức hoàn thiện).
Sửa lịch chạy
Đổi tên lệnh trong cron hay Task Scheduler theo bảng đối chiếu, và trỏ tới vnstock-pipeline của môi trường mới.
Lưu ý:
- Mã thoát: lệnh
runthoát với mã 1 khi có mã lỗi hoặc bị cách ly. Lịch chạy nào kiểm mã thoát sẽ báo những lần cần xem lại. - Thứ tự chạy: chạy
run referencetrước các tác vụ khác mỗi sáng, vì nhóm mã và lịch giao dịch đọc từ đây. - Nguồn cần OTP: nguồn
tcbscần mở phiên bằng OTP mỗi 24 giờ. Lịch chạy tự động nên đặt nguồn không cần OTP trước trong[sources].