Vnstock Logo

Câu Lệnh Mẫu

Cập nhật lần cuối:

Thảo luận

Mục lục

Giới thiệu

Trang này cung cấp các lệnh và đoạn mã mẫu sẵn sàng sử dụng cho các tác vụ thường gặp. Kể từ phiên bản v2.3.1, vnstock_pipeline cung cấp giao diện dòng lệnh (CLI) mạnh mẽ, thay thế cho việc viết script Python khởi tạo các lớp dữ liệu thủ công như trước đây.

Mẹo

Hai chế độ tải dữ liệu:

  • Chế độ dòng lệnh (CLI) - Chạy trực tiếp từ Terminal/Command Prompt. Phù hợp cho kiểm thử nhanh hoặc các tác vụ lập lịch đơn giản.
  • Chế độ chạy script (Python) - Dùng Python (subprocess + sys.executable) để điều phối chạy liên tiếp nhiều lệnh CLI, bắt lỗi và ghi nhật ký tự động. Phù hợp cho vận hành thực tế.
Lưu ý

Dữ liệu tải về sẽ được tự động lưu trữ tại vị trí do bạn thiết lập trong Config Hub (pipeline.toml). Mặc định là thư mục ~/stock_db/ (trên Mac/Linux) hoặc %USERPROFILE%\stock_db\ (trên Windows). Xem hướng dẫn Lưu trữ dữ liệu tối ưu để cấu hình.

1. Cơ Chế Tải Dữ Liệu Thông Minh

Trước khi đi vào các lệnh cụ thể, hệ thống tích hợp sẵn hai cơ chế quan trọng giúp bạn an tâm khi tải dữ liệu:

  • Nguồn dữ liệu dự phòng (Fallback Sources): Khi tải dữ liệu (ví dụ: giá lịch sử OHLCV), hệ thống tự động thiết lập danh sách các nguồn cấp dữ liệu ưu tiên (ví dụ: VCI, KBS, VND). Nếu nguồn đầu tiên bị lỗi mạng hoặc trả về dữ liệu rỗng, chương trình sẽ tự động chuyển sang nguồn tiếp theo cho đến khi tải thành công. Điều này đảm bảo chuỗi dữ liệu của bạn không bị đứt gãy.
  • Tải nối tiếp thông minh (Smart Append): Với các loại dữ liệu cập nhật liên tục (như Giá lịch sử, Báo cáo tài chính), chương trình sẽ tự động đọc tệp cũ, tìm ra ngày hoặc quý gần nhất và chỉ tải phần dữ liệu mới để nối vào. Dữ liệu trùng lặp sẽ tự động bị loại bỏ, giúp tiết kiệm thời gian chờ.

2. Dữ liệu Giá Lịch Sử (OHLCV)

Tải dữ liệu giá cổ phiếu theo ngày (kết thúc phiên). Bao gồm giá mở cửa, cao nhất, thấp nhất, đóng cửa và khối lượng.

Shell
# Tải nối tiếp dữ liệu ngày mới nhất cho sàn HOSE
python -m vnstock_pipeline.cli run ohlcv --group HOSE --mode daily

# Khởi tạo dữ liệu lịch sử cực dài (bù lấp khoảng trống nếu có)
python -m vnstock_pipeline.cli run ohlcv --group VN30 --mode init

# Chỉ tải lại các mã bị lỗi (ví dụ: đứt mạng) ở lần chạy trước
python -m vnstock_pipeline.cli run ohlcv --retry-errors

3. Dữ liệu Khớp Lệnh (Trades)

Dữ liệu giao dịch thực tế trong phiên (từng lệnh khớp, thời gian, mức giá, khối lượng).

Shell
# Tải dữ liệu khớp lệnh cuối ngày cho các mã tự chọn
python -m vnstock_pipeline.cli run trades --tickers ACB,FPT,TCB --mode daily

4. Bảng Giá (Quote)

Theo dõi trạng thái giá hiện tại của các mã chứng khoán (các bước giá, khối lượng chờ mua/bán).

Shell
# Chạy một lần để lấy trạng thái giá hiện tại chốt ngày
python -m vnstock_pipeline.cli run quote --group VN100 --mode eod

5. Dữ liệu Báo Cáo Tài Chính & Thống Kê Giao Dịch

Bao gồm 5 bảng Báo cáo tài chính hoặc các thống kê về dòng tiền của khối ngoại, tự doanh.

Shell
# Tải Báo cáo tài chính mới nhất cho rổ VN30
python -m vnstock_pipeline.cli run financial --group VN30

# Tải thống kê giao dịch (khối ngoại, tự doanh) cuối ngày cho sàn HOSE
python -m vnstock_pipeline.cli run session-stats --group HOSE

6. Dữ liệu Tham Chiếu & Công Ty

Shell
# Tải toàn bộ danh sách mã chứng khoán trên thị trường (Tham chiếu)
python -m vnstock_pipeline.cli run reference

# Tải hồ sơ công ty, danh sách cổ đông, ban lãnh đạo của VN30
python -m vnstock_pipeline.cli run company --group VN30

7. Dữ liệu Tin Tức & Sự Kiện

Thu thập dữ liệu báo chí (đã lọc trùng lặp) và lịch sự kiện doanh nghiệp (ví dụ: trả cổ tức, họp ĐHĐCĐ).

Shell
# Tải tin tức thị trường từ các nguồn mặc định
python -m vnstock_pipeline.cli run news

# Tải và cập nhật sự kiện doanh nghiệp hàng ngày
python -m vnstock_pipeline.cli run events --mode daily

8. Tích Hợp AmiBroker

Dành cho người dùng sử dụng phần mềm AmiBroker. Do tính năng nạp dữ liệu tự động qua giao thức OLE và các cơ chế xử lý phức tạp, hướng dẫn đã được chuyển sang chuyên mục riêng biệt.

Hướng dẫn chi tiết

9. Mẫu Kịch Bản Điều Phối Tự Động

Khi bạn muốn kết hợp chạy tự động tất cả các luồng dữ liệu theo thứ tự hằng ngày một cách an toàn và tự ghi nhận lỗi, hãy lưu đoạn mã sau thành tệp sync_market_data.py. Bạn có thể thiết lập công cụ như Crontab (trên Linux/VPS) hoặc Task Scheduler (Windows) để chạy tệp này tự động (ví dụ: 16:00 mỗi ngày).

Python
"""
Kịch bản điều phối - Chạy tự động nhiều tác vụ tải dữ liệu hằng ngày.
Cách chạy: python sync_market_data.py
"""
import sys
import subprocess
import logging

# Thiết lập ghi nhật ký
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

# Danh sách các tác vụ cần chạy cuối ngày
TASKS = [
    ("Build Rổ Thanh Khoản", ["universe", "build-liquidity", "--days", "50", "--top", "300"]),
    ("Đồng bộ Giá OHLCV", ["run", "ohlcv", "--watchlist", "liquidity_auto", "--mode", "daily"]),
    ("Đồng bộ Khớp Lệnh Tick", ["run", "trades", "--watchlist", "liquidity_auto", "--mode", "daily"]),
    ("Đồng bộ Thống kê Giao dịch", ["run", "session-stats", "--watchlist", "liquidity_auto", "--mode", "daily"])
]

def run_cli_command(task_name: str, args: list):
    """Sử dụng subprocess để gọi lệnh qua sys.executable nhằm giữ nguyên môi trường ảo (virtual environment)"""
    cmd = [sys.executable, "-m", "vnstock_pipeline.cli"] + args
    logger.info(f"Đang chạy tác vụ: {task_name}")
    logger.info(f"Lệnh: {' '.join(cmd)}")
    
    try:
        # Chạy lệnh
        subprocess.run(cmd, check=True, capture_output=True, text=True)
        logger.info(f"✅ Hoàn thành: {task_name}")
        return True
    except subprocess.CalledProcessError as e:
        logger.error(f"❌ Lỗi ở tác vụ {task_name} (Mã thoát: {e.returncode})")
        logger.error(f"Nhật ký lỗi: {e.stderr}")
        return False

if __name__ == "__main__":
    logger.info("=== BẮT ĐẦU ĐỒNG BỘ DỮ LIỆU CUỐI NGÀY ===")
    
    success_count = 0
    for name, args in TASKS:
        if run_cli_command(name, args):
            success_count += 1
            
    logger.info("=== TỔNG KẾT ĐỒNG BỘ ===")
    logger.info(f"Thành công: {success_count}/{len(TASKS)}")
    
    if success_count < len(TASKS):
        # Tùy chọn: Tự động chạy lại cho các tác vụ lỗi (ví dụ tải giá OHLCV)
        logger.info("Đang kích hoạt chạy tải bù dữ liệu lỗi...")
        run_cli_command("Tải Bù Giá OHLCV", ["run", "ohlcv", "--retry-errors"])
Mẹo Triển Khai

Chỉ cần cấu hình tiện ích Crontab (trên Linux/VPS) chạy file sync_market_data.py trên vào lúc 16:00 mỗi ngày để tự động chạy tiến trình cập nhật dữ liệu.

Thảo luận

Đang tải bình luận...