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.
Lời nhắc và lệnh bên dưới đổi theo máy bạn chọn.
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
Lưu khoá truy cập vào máy
Đang tải khoá truy cập của bạn…
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 · macOSHã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
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
- 01
Cài vào ~/.venv
kiểm tra Python 3.10 trở lên, tạo hoặc nâng ~/.venv
- 02
Xác thực quyền
kiểm tra bằng vnstock status, không đọc và không in khoá
- 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
- 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
- 05
Ghi chỉ dẫn cho AI
vào AGENTS.md (khuyên dùng, bạn bỏ chọn được)
- 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ục | Khoá tài khoản Vnstock | Khoá ở 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ưu | vnstock 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ới | vnstocks.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-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.
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.
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
- Thư viện chính
vnstockChuẩn hoá phản hồi từ vnstock-oapi hoặc tệp của bạn thành bảng thống nhất. Cổng kết nối vnstock-oapi thuộc bản Cộng đồng; Gói quyền sử dụng mở đủ năng lực xử lý của vnstock, gồm cây chỉ tiêu báo cáo tài chính đầy đủ.Bản Mở rộng - Cổng kết nối
vnstock-oapiQuản lý khoá, mở phiên và kết nối Open API của nguồn bằng tài khoản của chính bạn.Bản Cộng đồng - Định lượng
vnstock_quantChỉ báo kỹ thuật, chỉ số tài chính, rủi ro và danh mục. Bronze mở phần nâng cao, Silver mở đủ chỉ báo.Dùng thử từ Cộng đồng - Quy trình dữ liệu
vnstock_pipelineKiểm tra, tổ chức và lưu dữ liệu trên máy, chạy theo lịch, xuất sang định dạng phần mềm phân tích.Từ Golden - Công cụ cho trợ lý AI
vnstock_mcpCho trợ lý AI gọi công cụ Vnstock trên máy bạn và để lại mã Python cho từng bước. Có bản dựng sẵn cho macOS, Linux và Windows.Không có cấp riêng - Biểu đồ
vnstock_chartVẽ biểu đồ từ bảng dữ liệu bạn đã có và lưu thành ảnh cho báo cáo. Thay cho vnstock_ezchart, giữ tên hàm.Thư viện bổ sung
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.

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óiGói quyền sử dụng có kèm khoá ở nguồn dữ liệu không? Chưa có khoá thì sao?
Khoá truy cập được giữ thế nào?
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ũ.
~/.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?
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?
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ì?
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?
vnstock login trên máy mới.