Vnstock Logo

Hướng dẫn bản Mở rộng

Cài bộ thư viện thế hệ 6 cùng trợ lý AI

Lưu khoá tài khoản trên máy, sau đó gửi lời nhắc cho trợ lý AI. Trợ lý cài các thư viện theo cấp quyền của bạn vào môi trường cố định ~/.venv rồi hướng dẫn nhập khoá của nguồn dữ liệu.

01 · Cài đặt

Lưu khoá, rồi gửi lời nhắc

Khoá tài khoản được lưu trên máy và không xuất hiện trong khung chat. Trợ lý cài thế hệ 6 vào môi trường cố định ~/.venv và chỉ chạy sau khi bạn duyệt kế hoạch.

Thế hệ 6 là bản đang phát hành. Dự án viết cho thế hệ 5, vnstock 4.x hay vnstock_data 3.x: xem Chuyển dự án sang thế hệ 6.

Trạng thái gói
Máy của bạn

Lời nhắc và lệnh bên dưới đổi theo máy bạn chọn.

  1. 1

    Mở trợ lý AI bạn đang dùng

    Trên máy tính, bản ứng dụng hay trợ lý dòng lệnh đều được.

    Ứng dụng trò chuyện

    Claude, ChatGPT, Antigravity

    Chạy lệnh trên máy

    Claude Code, Codex, VS Code, Antigravity IDE

  2. 2

    Lưu khoá truy cập vào máy

    Đang tải khoá truy cập của bạn…

  3. 3

    Dán lời nhắc vào trợ lý

    Lời nhắc không chứa khoá. Trợ lý trình bày toàn bộ kế hoạch, chờ bạn duyệt rồi mới bắt đầu cài.

    Lời nhắc · macOS
    Hãy giúp tôi thiết lập thư viện Python vnstock thế hệ 6 cùng các thư viện bổ sung theo cấp quyền sử dụng của tôi, theo mục "Setup (generation 6)" của tài liệu hướng dẫn tại https://vnstocks.com/files/vibe-onboarding.md
    - Đọc trực tiếp toàn bộ tệp đó trước khi lập kế hoạch (ví dụ curl -fsSL https://vnstocks.com/files/vibe-onboarding.md), không thay bằng tìm kiếm web, skill hay ghi nhớ cũ. Không đọc được thì báo tôi, đừng tự đoán lệnh.
    - Trước tiên xác định bạn đang chạy ở đâu, theo mục G1 của tài liệu. Tôi mở trang hướng dẫn trên macOS, nhưng nơi cài là nơi bạn đang chạy.
    - Nếu là máy cá nhân hoặc máy chủ: cài vào môi trường cố định ~/.venv bằng nguyên văn hai lệnh sau (lệnh đầu bỏ qua nếu môi trường đã có; hai lệnh này viết cho macOS). Nếu môi trường đó đang có vnstock thế hệ 5 hoặc 4.x, nêu trong kế hoạch rồi nâng thẳng lên thế hệ 6 theo mục G2, vì các bản cũ đã ngừng xác thực:
      python3 -m venv ~/.venv
      ~/.venv/bin/python -m pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock==6.0.1" "vnstock-oapi==0.1.2"
    - Nếu là Google Colab, GitHub Codespaces hoặc Kaggle: không tạo môi trường ảo, cài thẳng vào Python của phiên đó bằng nguyên văn lệnh sau:
      python3 -m pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock==6.0.1" "vnstock-oapi==0.1.2"
    - Không viết lại các lệnh trên, không bỏ --extra-index-url và số phiên bản.
    - Thư viện bổ sung: chỉ dùng đúng lệnh ở mục G7 của tài liệu, trong phạm vi cấp của tôi. Không cài vnstock_data, vnstock_ta, vnstock_news vào môi trường này.
    - Trước khi chạy bất kỳ lệnh nào, hãy trình bày kế hoạch đầy đủ: các bước theo thứ tự, lệnh sẽ chạy ở từng bước, nơi cài, những tệp sẽ tạo hoặc sửa. Chờ tôi duyệt kế hoạch một lần.
    - Sau khi tôi duyệt, hãy thực hiện trọn kế hoạch mà không hỏi lại từng lệnh, rồi báo kết quả ngắn gọn. Chỉ dừng lại hỏi khi gặp việc ngoài kế hoạch, lỗi cần đổi cách làm, hoặc lệnh có thể làm mất dữ liệu của tôi.
    - Khoá truy cập Vnstock: kiểm tra bằng vnstock status. Tôi đã lưu khoá trên máy cá nhân; trên Colab, Codespaces, Kaggle có thể chưa có, khi đó làm theo mục G4. Không đọc, không in và không yêu cầu tôi gửi khoá qua khung chat.
    - Khoá Open API của nguồn dữ liệu do tôi tự quản lý: hãy hỏi tôi dùng nguồn nào và không tự chọn nguồn. Tôi tự cất khoá theo mục G5 (máy có kho khoá: vnstock keys set; Colab, Codespaces, Kaggle: biến môi trường hoặc tệp .env). Không mở và không in các khoá đó.
    - Đưa vào kế hoạch việc ghi vào AGENTS.md của dự án đúng khối hướng dẫn ở mục G9 của tài liệu, kèm nội dung dự kiến để tôi xem khi duyệt.
  4. 4

    Nhập khoá của nguồn dữ liệu

    Khi trợ lý yêu cầu, chạy lệnh này trong cửa sổ dòng lệnh rồi tự nhập khoá. Ký tự được ẩn khi bạn gõ và không xuất hiện trong khung chat.

    Terminal · macOS
    $  ~/.venv/bin/vnstock keys set <nguồn>

    Gói quyền sử dụng không bao gồm tài khoản hay khoá ở nguồn. Chưa có khoá thì trợ lý vẫn cài xong và dừng trước bước lấy dữ liệu. Xem danh sách nguồn và nơi đăng ký.

Trợ lý sẽ làm

6 bước · duyệt kế hoạch một lần

  1. 01

    Cài vào ~/.venv

    kiểm tra Python 3.10 trở lên, tạo hoặc nâng ~/.venv

  2. 02

    Xác thực quyền

    kiểm tra bằng vnstock status, không đọc và không in khoá

  3. 03

    Hỏi nguồn bạn dùng

    trợ lý không tự chọn nguồn; bạn tự nhập khoá ở bước 4

  4. 04

    Cài thư viện bổ sung

    đúng phiên bản thế hệ 6, trong phạm vi cấp của bạn

  5. 05

    Ghi chỉ dẫn cho AI

    vào AGENTS.md (khuyên dùng, bạn bỏ chọn được)

  6. 06

    Kiểm tra, chạy thử

    vnstock doctor, rồi một truy vấn nhỏ ở nguồn của bạn

Đích đến: Thế hệ 6 chạy được trên máy, lấy được dữ liệu từ nguồn của bạn

Vướng ở bước nào, bạn chạy lệnh vnstock doctor để xem mục chưa ổn và lệnh sửa, hoặc chuyển sang chế độ Tự cài.

02 · Khoá

Thế hệ 6 dùng hai loại khoá

Khác với thế hệ 4 và 5, bạn cần tự đăng ký khoá ở nguồn mình dùng. Hai loại khoá làm hai việc khác nhau và không thay thế được cho nhau.

Hạng mụcKhoá tài khoản VnstockKhoá ở nguồn dữ liệu
Lấy ởTrang quản lý tài khoản, đi cùng tài khoản của bạn.Trang của nguồn bạn chọn, theo điều khoản của nguồn đó. Xem danh sách nguồn.
Dùng đểXác nhận cấp quyền sử dụng: mở bộ chỉ tiêu báo cáo tài chính đầy đủ, thư viện bổ sung và kỹ năng cho trợ lý AI.Đọc dữ liệu từ nguồn bằng tài khoản của chính bạn. Gói quyền sử dụng không bao gồm tài khoản hay khoá này.
Cách lưuvnstock login, lưu mã hoá trên máy của bạn.vnstock keys set <nguồn>, lưu trong kho khoá của hệ điều hành.
Gửi tớivnstocks.com để kiểm tra cấp quyền. Không gửi tới nguồn dữ liệu.Chỉ nguồn đó. Không gửi về vnstocks.com.

Bạn tự nhập cả hai loại khoá trong cửa sổ dòng lệnh của mình. Trợ lý AI không cần thấy khoá nào, và bạn không dán khoá vào khung chat.

03 · Sau khi cài

Mỗi lời gọi cần biết nguồn

Tên lớp và tên hàm giữ như thế hệ 5. Điểm phải đổi là thế hệ 6 không có nguồn mặc định: bạn nêu nguồn trong lời gọi, hoặc đặt một lần cho cả chương trình.

Hàm chưa được nguồn hỗ trợ sẽ báo mã lỗi thay vì trả về bảng rỗng. Với dự án cũ, dùng lời nhắc tại trang chuyển đổi.

Cách chọn nguồn
Thế hệ 5 → Thế hệ 6 · Giữ tên lớp và tên hàm
Market().equity("FPT").ohlcv(start="2026-10-01") (cách gọi thế hệ 5)Market("<nguồn>").equity("FPT").ohlcv(start="2026-10-01") (cách gọi thế hệ 6)# Hoặc đặt nguồn một lần cho cả chương trìnhvnstock.sources.use("<nguồn>")

Tên cột giữ như thế hệ 5 theo mặc định. Bảng nào khác sẽ có cảnh báo và liệt kê trong df.attrs["schema_changes"].

04 · Tra cứu tài liệu

Đổi bản mới và cũ trên trang tài liệu

Tài liệu của thế hệ 6 và các thế hệ trước nằm cùng một chỗ. Mở trang tài liệu của một thư viện, bạn nhìn bộ chọn phiên bản ở đầu trang để chắc mình đang đọc đúng bản thế hệ 6.

  • Dấu hiệu nhận biết: trang bản cũ có nhãn Bản cũ kèm dải thông báo màu hổ phách.
  • Khi đổi phiên bản: trang sẽ mở bài tương ứng ở phiên bản kia thay vì đưa bạn về trang chủ.
  • Thanh bên đồng bộ: mục lục bên trái hiện đúng các hàm của phiên bản đang xem.
Mô phỏng bộ chọn phiên bản
Bấm vào ô phiên bản bên dưới

Vnstock thế hệ 6

Chọn nguồn, dùng khoá Open API của bạn và nhận bảng dữ liệu đã chuẩn hoá ngay trên máy.

Thế hệ 6
Cú pháp của vnstockminh hoạ
1from vnstock import Market
2Market("<nguồn>").equity("FPT").ohlcv(start="2026-10-01")

05 · Hướng dẫn

Cài đặt, vận hành và tra cứu

Tài liệu cài đặt, chọn nguồn và các thư viện thế hệ 6, mỗi thẻ mở đúng bản dành cho thế hệ này.

Cài đặt và vận hành

Thư viện thế hệ 6

06 · Cách hoạt động

Dữ liệu đi thẳng từ nguồn về máy bạn

Gói quyền sử dụng mở các thư viện của bản Mở rộng; quyền lấy dữ liệu vẫn đến từ khoá Open API của nguồn bạn chọn, lưu trong kho bảo mật của máy bạn.

Thế hệ 6 khác gì
Sơ đồ: trên máy của bạn, mã gọi vnstock 6 để chuẩn hoá, vnstock-oapi giữ khoá trong kho bảo mật và gửi yêu cầu tới Open API chính thức của nguồn bạn chọn (công ty chứng khoán, FMP, Binance…), dữ liệu trả về thành DataFrame.

Mới bắt đầu với vnstock?

Trung tâm hướng dẫn chung: cài bản Cộng đồng, Vibe Coding và kho kỹ năng.

Về Trung tâm hướng dẫn

07 · Hỏi đáp

Câu hỏi thường gặp

Những câu người dùng gói hay hỏi khi cài và bắt đầu dùng thế hệ 6.

Chưa thấy câu của bạn?

Hỏi trong nhóm người dùng gói
Gói quyền sử dụng có kèm khoá ở nguồn dữ liệu không? Chưa có khoá thì sao?
Không kèm. Bạn tự đăng ký tài khoản và khoá ở nguồn mình chọn, theo điều khoản của nguồn đó; danh sách nguồn và nơi đăng ký nằm trong tài liệu cài đặt. Chưa có khoá thì trợ lý AI vẫn cài xong thư viện và dừng trước bước lấy dữ liệu.
Khoá truy cập được giữ thế nào?
Khoá tài khoản được lưu mã hoá trên máy, không in ra màn hình. Khoá ở nguồn nằm trong kho khoá của hệ điều hành. Bạn tự nhập cả hai trong cửa sổ dòng lệnh và không dán vào khung chat của trợ lý AI. Cần đổi khoá tài khoản, bạn tạo khoá mới ở trang quản lý tài khoản rồi chạy vnstock login trên từng máy.
Thế hệ 6 cài vào đâu? Máy tôi đã có ~/.venv với bản cũ.
Thế hệ 6 cài vào môi trường cố định ~/.venv (Windows: $HOME\.venv), cùng chỗ với các bản trước. Nếu môi trường đó đang có thế hệ 5 hoặc vnstock 4.x, lệnh cài nâng thẳng lên thế hệ 6, vì các bản cũ đã ngừng xác thực. Cần đối chiếu kết quả của dự án cũ trước khi sửa mã thì làm theo trang chuyển đổi. Trên Google Colab, cài trực tiếp vào phiên đang chạy và lưu khoá trong mục Secrets; xem hướng dẫn cho Colab.
Mỗi bản phát hành dùng được bao lâu, cập nhật thế nào?
Bản chính thức dùng được 365 ngày, bản thử nghiệm (rc) 30 ngày kể từ ngày dựng; vnstock status cho biết ngày hết hạn. Gần hết hạn thư viện cảnh báo một lần, sau đó lời gọi báo VNSTOCK_RELEASE_EXPIRED. Bạn chạy vnstock update để cập nhật mọi thư viện đã cài. Đừng chạy pip install -U vnstock không kèm phiên bản, vì thư viện thế hệ 5 còn sót trên máy có thể kéo vnstock về bản cũ.
Tôi gặp lỗi, nên bắt đầu từ đâu?
Bạn chạy vnstock doctor: lệnh kiểm tra kết nối, hạn dùng của bản đang cài, tài khoản, khoá và phiên của từng nguồn, rồi in cách sửa từng mục. Lỗi khi gọi hàm có mã riêng, bạn tra ở trang mã lỗi. Chưa chạy được lệnh vnstock thì xem trang cài đặt và gỡ lỗi.
Hàm tôi hay dùng báo chưa hỗ trợ thì làm gì?
Bản này chưa có bảng chỉ số do nguồn tính (ratio), thuyết minh, Insights, Analytics và Macro. Chỉ số tài chính bạn tính trên máy bằng vnstock_quant.fa từ ba báo cáo. vnstock_news không có bản thế hệ 6. Cũng có khi nguồn bạn đang dùng chưa đọc được loại dữ liệu đó: trang chọn nguồn chỉ cách kiểm tra.
Cần làm gì khi hệ thống báo vượt quá số lượng thiết bị cho phép?
Bạn vào trang quản lý thiết bị, xoá một máy không còn dùng, rồi chạy lại vnstock login trên máy mới.
Tôi có dự án viết cho vnstock_data 3.x hoặc thế hệ 5, chuyển sang thế hệ 6 thế nào?
Thế hệ 4 và 5 ngừng xác thực từ ngày 10/11/2026. Trang chuyển dự án sang thế hệ 6 có sẵn một lời nhắc: trợ lý AI đối chiếu mã của bạn và liệt kê chỗ cần sửa trước khi sửa trên một bản sao. Mã gốc giữ nguyên cho tới khi bạn đồng ý.