Cài đặt Python 3.12 và tạo môi trường ảo
Ubuntu 24.04 mặc định đi kèm Python 3.12, tuy nhiên để đảm bảo môi trường sạch sẽ và tránh xung đột với hệ thống, ta sẽ tạo một virtual environment (venv) riêng biệt cho dự án LlamaIndex.
Mục đích: Cô lập các thư viện của dự án, đảm bảo phiên bản Python và các gói không ảnh hưởng đến hệ điều hành.
Đầu tiên, kiểm tra phiên bản Python hiện có trên hệ thống để xác nhận.
python3 --version
Kết quả mong đợi: Hiển thị dòng chữ "Python 3.12.x" (với x là bản vá cụ thể).
Tiếp theo, tạo thư mục dự án và vào thư mục đó. Sau đó khởi tạo môi trường ảo với tên ".venv".
mkdir -p ~/projects/llama-rag && cd ~/projects/llama-rag
python3 -m venv .venv
Kết quả mong đợi: Không có lỗi, xuất hiện thư mục .venv trong thư mục hiện tại.
Kích hoạt môi trường ảo để chuyển shell sang sử dụng Python của venv. Bạn sẽ thấy dấu ngoặc đơn (.venv) xuất hiện ở đầu dòng lệnh.
source .venv/bin/activate
Kết quả mong đợi: Dòng lệnh bắt đầu bằng "(.venv) user@host:~/projects/llama-rag$".
Cập nhật pip, setuptools và wheel để đảm bảo quá trình cài đặt các gói sau này diễn ra mượt mà nhất.
pip install --upgrade pip setuptools wheel
Kết quả mong đợi: Hiển thị thông báo "Successfully installed" hoặc "Requirement already satisfied".
Cài đặt các thư viện LlamaIndex, LangChain và pgvector
Bây giờ ta sẽ cài đặt các thành phần cốt lõi. LlamaIndex là framework chính, LangChain hỗ trợ orchestration, và pgvector là driver để giao tiếp với PostgreSQL vector store.
Mục đích: Cài đặt đầy đủ các dependencies cần thiết để xây dựng hệ thống RAG.
Cài đặt các gói chính. Lưu ý: ta sẽ dùng các flag để cài đặt các gói con cần thiết cho PostgreSQL và LangChain.
pip install llama-index-core llama-index-llms-langchain llama-index-readers-file llama-index-vector-stores-postgres langchain langchain-community pgvector psycopg[binary]
Kết quả mong đợi: Quá trình tải về và cài đặt hoàn tất, không báo lỗi "No matching distribution found".
Để đảm bảo tính tương thích, ta kiểm tra lại phiên bản của các gói đã cài. Điều này quan trọng vì LlamaIndex thay đổi API khá nhanh.
pip list | grep -E "llama-index|langchain|pgvector|psycopg"
Kết quả mong đợi: Danh sách các gói xuất hiện với phiên bản mới nhất (ví dụ: llama-index-core>=0.10.x, langchain>=0.1.x, pgvector>=0.2.x).
Cấu hình biến môi trường cho API Key
Để mô hình LLM hoạt động (ví dụ: OpenAI, Anthropic, hoặc HuggingFace), bạn cần lưu trữ API Key một cách an toàn thông qua biến môi trường (Environment Variable) thay vì hardcode trong script.
Mục đích: Bảo mật thông tin nhạy cảm và chuẩn hóa cấu hình cho các script Python sau này.
Tạo file cấu hình môi trường `.env` trong thư mục dự án. File này sẽ chứa các key cần thiết. Trong ví dụ này, ta giả định sử dụng OpenAI, nhưng bạn có thể thay đổi theo mô hình thực tế.
cat > .env
Kết quả mong đợi: File `.env` được tạo ra với nội dung như trên. Bạn cần thay thế "sk-proj-..." và "your_secure_password" bằng giá trị thực tế.
Để Python có thể đọc file `.env`, ta cần cài đặt thư viện `python-dotenv` và thêm đoạn code khởi tạo vào script của bạn. Đây là bước chuẩn bị trước khi chạy code.
pip install python-dotenv
Kết quả mong đợi: Thư viện `python-dotenv` được cài đặt thành công.
Tạo file Python mẫu để kiểm tra việc đọc biến môi trường. File này sẽ nằm tại đường dẫn `~/projects/llama-rag/config_check.py`.
cat > config_check.py
Kết quả mong đợi: File `config_check.py` được tạo thành công.
Kiểm tra phiên bản và tính tương thích
Bước cuối cùng là chạy file kiểm tra vừa tạo để đảm bảo toàn bộ môi trường Python, thư viện và biến môi trường đã đồng bộ và hoạt động.
Mục đích: Xác nhận không có xung đột phiên bản (dependency conflict) và API Key đã được nạp đúng.
Chạy file kiểm tra trong môi trường ảo đã kích hoạt.
python config_check.py
Kết quả mong đợi:
- Dòng "OpenAI API Key loaded: Yes" (nếu bạn đã điền key vào file .env).
- Dòng "DB Host loaded: localhost".
- Dòng "All libraries imported successfully."
- Không xuất hiện bất kỳ lỗi Traceback hay ImportError nào.
Nếu bạn thấy lỗi "ImportError: No module named 'llama_index'", hãy đảm bảo bạn đã kích hoạt venv bằng lệnh `source .venv/bin/activate` trước khi chạy lệnh python.
Để kiểm tra sâu hơn về tính tương thích giữa LlamaIndex và LangChain, ta chạy một lệnh đơn giản để in thông tin phiên bản chi tiết.
python -c "import llama_index; print(llama_index.__version__); import langchain; print(langchain.__version__)"
Kết quả mong đợi: In ra 2 dòng số phiên bản, ví dụ "0.10.x" và "0.1.x", xác nhận cả hai thư viện cùng tồn tại và có thể import được.
Điều hướng series:
Mục lục: Series: Triển khai Database AI với LlamaIndex và PostgreSQL trên Ubuntu 24.04
« Phần 2: Cấu hình PostgreSQL cho vector search với pgvector
Phần 4: Xử lý dữ liệu và tạo vector index với LlamaIndex »