Gỡ lỗi & Câu hỏi thường gặp

Tổng quan

Quá trình cài đặt và sử dụng đôi khi gặp một số rào cản kỹ thuật phụ thuộc vào hệ điều hành hoặc môi trường lập trình. Tài liệu này giúp bạn tự chẩn đoán và khắc phục nhanh các sự cố phổ biến nhất.

Lưu ý về Môi trường ảo mặc định

Trong toàn bộ hệ sinh thái Vnstock, môi trường ảo (virtual environment) mặc định được khuyến nghị sử dụng có tên là .venv. Đường dẫn lưu trữ tuỳ thuộc vào hệ điều hành của bạn:

macOS / Linux: ~/.venv
Windows: %USERPROFILE%\.venv (hoặc $HOME\.venv trong PowerShell)

Hãy luôn đảm bảo kích hoạt môi trường ảo này trước khi cài đặt hoặc chạy mã nguồn.

1. Lỗi Thiết Lập Cơ Bản

1.1. Khắc phục lỗi "Đã nâng cấp nhưng vẫn báo bản cộng đồng"

Đây là bối rối phổ biến nhất của các thành viên sau khi tham gia gói tài trợ. Mặc dù tài khoản của bạn đã được kích hoạt thành công trên hệ thống, bạn vẫn thấy thông báo sử dụng bản Community và bị giới hạn 60 yêu cầu/phút.

Nguyên nhân cốt lõi Bạn đang chạy code dựa trên thư viện vnstock công khai (cài bằng lệnh pip install vnstock thông thường). Thư viện miễn phí vnstock không thể tự chuyển đổi hoặc mở rộng tính năng của gói tài trợ. Các gói tài trợ sử dụng một bộ thư viện độc lập cần cài đặt riêng nhưng hỗ trợ chuyển đổi code dễ dàng.

Cách xử lý

Cài đặt thư viện tài trợ: Bộ thư viện dành cho nhà tài trợ là các gói mã nguồn riêng (như vnstock_data, vnstock_ta, vnstock_news, vnstock_pipeline), không thể cài đặt qua lệnh pip install vnstock_data thông thường. Bạn bắt buộc phải cài đặt thông qua trình cài đặt riêng tại trang Cài đặt gói tài trợ.
Thay đổi câu lệnh Import trong code: Sau khi cài đặt thành công, hãy cập nhật lại toàn bộ mã nguồn của bạn để import từ thư viện mới:
- Cách cũ (Bản miễn phí):
  Python
```
from vnstock import Quote, Listing
```
- Cách mới (Bản tài trợ):
  Python
```
from vnstock_data import Market, Reference
```

Khi bạn import từ vnstock_data, hệ thống sẽ tự động nhận diện API Key và áp dụng đúng hạn mức truy cập của gói tài trợ (180 đến 600 yêu cầu/phút tương ứng với hạng Bronze, Silver, Golden, Diamond).

1.2. Lỗi vòng lặp xác thực hoặc hệ thống không nhận tài khoản

Dấu hiệu: Hệ thống không nhận diện đúng gói tài trợ hoặc liên tục yêu cầu xác thực.
Khắc phục triệt để: Gỡ cài đặt hoàn toàn và thiết lập lại.
- Bước 1: Gỡ thư viện:
  Shell
```
pip uninstall vnstock vnai vnii vnstock_data vnstock_ta vnstock_news vnstock_pipeline vnstock_installer -y
```
- Bước 2: Xóa cấu hình cũ:
  - Trên macOS/Linux:
    Shell
```
rm -rf ~/.vnstock
```
  - Trên Windows:
    CMD
```
rmdir /S /Q %USERPROFILE%\.vnstock
```
- Bước 3: Cài lại trình cài đặt và chạy:
  Shell
```
vnstock-installer
```

1.3. Nhập sai API Key khi dùng công cụ dòng lệnh

Khắc phục: Thay vì cài lại từ đầu, hãy ghi đè bằng biến môi trường trước khi chạy tập lệnh cài đặt:
Shell
```
export VNSTOCK_API_KEY="KEY_CHUAN_CUA_BAN"
./vnstock-cli-installer.run --non-interactive
```

1.4. Trình cài đặt giao diện báo lỗi thất bại

Dấu hiệu: Giao diện đồ hoạ hiển thị lỗi màu đỏ, cửa sổ dòng lệnh báo thiếu thư viện đi kèm.
Khắc phục: Đóng giao diện, chạy lệnh sau để bổ sung đầy đủ thư viện phụ trợ, sau đó mở lại trình cài đặt vnstock-installer.
Shell
```
pip install -r https://vnstocks.com/files/requirements.txt
```

1.5. Báo thiếu pip

Dấu hiệu: No module named pip.
Khắc phục: Chạy lệnh sau để nâng cấp hoặc cài đặt pip:
Shell
```
python -m ensurepip --upgrade
```
Hoặc nếu bạn dùng uv:
Shell
```
uv pip install vnstock
```

1.6. Thiếu thư viện hệ thống

Dấu hiệu: Hệ thống báo thiếu thư viện vnii làm gián đoạn việc import.

Khắc phục: Cài đặt lại gói này bằng lệnh:

Shell

pip install --extra-index-url https://vnstocks.com/api/simple vnii

2. Lỗi Môi Trường Python (macOS/Linux)

2.1. Lệnh Python nhận nhầm phiên bản

Dấu hiệu: Môi trường ảo dùng Python 3.14 nhưng khi chạy lệnh python lại kích hoạt bản 3.11 của hệ thống máy chủ.
Khắc phục: Đảm bảo luôn kích hoạt môi trường ảo trước. Nếu chạy lệnh trực tiếp, hãy gọi số phiên bản cụ thể như:
Shell
```
python3.14 script.py
```

2.2. Lỗi môi trường bị quản lý bởi hệ thống

Dấu hiệu: Báo lỗi error: externally-managed-environment trên hệ điều hành Linux/macOS phiên bản mới.
Khắc phục: Do hệ điều hành đã khoá cài đặt toàn cục, bạn bắt buộc tạo môi trường ảo và kích hoạt nó, sau đó mới tiến hành cài đặt. Tuyệt đối không cài thư viện ra ngoài môi trường chung.
Shell
```
python3 -m venv .venv
source .venv/bin/activate
```

3. Lỗi Cài Đặt trên Windows

3.1. Xung đột ứng dụng (Mở Microsoft Store thay vì Python)

Dấu hiệu: Bạn đã cài đặt Python nhưng khi mở Terminal và gõ lệnh python, thay vì chạy chương trình, Windows lại tự động mở Microsoft Store hoặc báo lỗi không tìm thấy lệnh.
Nguyên nhân: Đây là do cơ chế "App Execution Aliases" (Biệt danh thực thi ứng dụng) của Windows 10/11. Mặc định, Windows đặt sẵn các file ảo (stubs) có tên python.exe và python3.exe trong hệ thống. Khi bạn tự cài Python nhưng quên chọn "Add Python to PATH" hoặc Windows vẫn ưu tiên Alias của hệ thống, nó sẽ gọi nhầm file ảo của Store thay vì Python bạn vừa cài.
Giải pháp triệt để:
- Bước 1: Gỡ bỏ bản Python từ Microsoft Store (nếu có) Để tránh xung đột đường dẫn và phiên bản, Vnstock khuyến nghị bạn chỉ nên dùng bản bộ cài chính thức từ python.org. Hãy gỡ cài đặt các bản Python tải từ Store.
  Bước 1: Tìm kiếm App Execution Aliases
- Bước 2: Tắt "App Execution Aliases" Đây là bước quan trọng nhất để Windows "quên" lối tắt dẫn tới Store.
  1. Gõ "App Execution Aliases" vào thanh tìm kiếm Windows (hoặc vào Settings > Apps > Advanced app settings > App execution aliases).
  2. Tìm các mục có tên Python, App Installer (python.exe), App Installer (python3.exe).
  3. Gạt công tắc sang OFF.
  Bước 2: Tìm mục Python
- Bước 3: Cài lại Python đúng chuẩn Tải bộ cài từ python.org. Khi chạy file cài đặt, hãy tích vào ô "Add Python.exe to PATH" ở ngay màn hình đầu tiên trước khi nhấn Install.
  Bước 3: Tắt Alias

3.2. Thiếu bộ biên dịch C++ (Lỗi cài đặt gói nâng cao)

Dấu hiệu: Khi cài đặt vnstock_pipeline hoặc vnstock_ta, tiến trình bị treo hoặc báo lỗi không thể biên dịch thành công.
Khắc phục: Tải và cài đặt Microsoft Visual C++ Redistributable mới nhất từ trang chủ Microsoft, sau đó chạy lại lệnh cài đặt.

4. Lỗi Tích Hợp Jupyter & Google Colab

4.1. Jupyter Notebook không nhận thư viện (Local)

Dấu hiệu: Chạy code trên file .ipynb trong IDE (Antigravity, VS Code) ở môi trường Local báo lỗi thiếu thư viện, dù đã cài thành công ở Terminal.
Khắc phục: Bạn cần đăng ký môi trường ảo thành một Kernel cho Jupyter.
1. Kích hoạt môi trường ảo đang dùng.
2. Cài ipykernel:
  Shell
```
python -m pip install ipykernel
```
3. Đăng ký Kernel:
  Shell
```
python -m ipykernel install --user --name=vnstock-venv --display-name "Python (Vnstock)"
```
4. Trong file Notebook, chọn Kernel Python (Vnstock). Khởi động lại IDE nếu không thấy.

4.2. Google Colab không nhận thư viện

Dấu hiệu: Đã cài bằng lệnh !pip install nhưng báo lỗi khi import.
Khắc phục: Khởi động lại phiên làm việc bằng cách vào menu Runtime > Restart Session.

Khởi động lại phiên làm việc trên Google Colab

5. Xác minh cài đặt

Sau khi cài đặt, bạn có thể chạy đoạn mã sau để kiểm tra:

Python

try:
    import vnstock
    print(f"✅ Vnstock phiên bản miễn phí: {vnstock.__version__}")
except ImportError:
    print("❌ Vnstock chưa được cài đặt.")

# Kiểm tra các gói tài trợ
packages = ['vnstock_data', 'vnstock_news', 'vnstock_ta', 'vnstock_pipeline']
for pkg in packages:
    try:
        module = __import__(pkg)
        print(f"✅ {pkg} đã cài đặt thành công")
    except ImportError:
        print(f"⚪ {pkg} chưa cài đặt (Kiểm tra lại gói tài trợ của bạn)")

6. Quy trình cập nhật thư viện

Vnstock thường xuyên phát hành các bản vá lỗi và tính năng mới. Cách an toàn nhất để đảm bảo ổn định khi cập nhật là:

Gỡ bỏ toàn bộ thư viện liên quan:

Shell

pip uninstall vnstock vnai vnii vnstock_installer vnstock_data vnstock_ta vnstock_news vnstock_pipeline -y

Cài lại phần lõi:
Shell
```
pip install vnstock vnai
```

Cài lại nhóm tiện ích:

Shell

pip install --extra-index-url https://vnstocks.com/api/simple vnii vnstock_installer

Cài lại các gói mở rộng chuyên sâu thông qua công cụ Vnstock Installer.

Gỡ lỗi & Câu hỏi thường gặp

Mục lục

Tổng quan

1. Lỗi Thiết Lập Cơ Bản

1.1. Khắc phục lỗi "Đã nâng cấp nhưng vẫn báo bản cộng đồng"

1.2. Lỗi vòng lặp xác thực hoặc hệ thống không nhận tài khoản

1.3. Nhập sai API Key khi dùng công cụ dòng lệnh

1.4. Trình cài đặt giao diện báo lỗi thất bại

1.5. Báo thiếu pip

1.6. Thiếu thư viện hệ thống

2. Lỗi Môi Trường Python (macOS/Linux)

2.1. Lệnh Python nhận nhầm phiên bản

2.2. Lỗi môi trường bị quản lý bởi hệ thống

3. Lỗi Cài Đặt trên Windows

3.1. Xung đột ứng dụng (Mở Microsoft Store thay vì Python)

3.2. Thiếu bộ biên dịch C++ (Lỗi cài đặt gói nâng cao)

4. Lỗi Tích Hợp Jupyter & Google Colab

4.1. Jupyter Notebook không nhận thư viện (Local)

4.2. Google Colab không nhận thư viện

5. Xác minh cài đặt

6. Quy trình cập nhật thư viện

Thảo luận