Kiểm tra yêu cầu phần cứng cho Qdrant
Trước khi cài đặt, hãy xác minh tài nguyên hệ thống để đảm bảo Qdrant chạy ổn định, đặc biệt là bộ nhớ RAM cho vector embedding.
Qdrant yêu cầu tối thiểu 2GB RAM cho môi trường phát triển, nhưng khuyến nghị 4GB trở lên cho production. CPU cần ít nhất 2 nhân. Disk cần hỗ trợ SSD để tối ưu hóa tốc độ I/O khi index vector.
free -h
Kết quả mong đợi: Dòng "Mem:" hiển thị tổng RAM >= 4G. Nếu thấp hơn 2G, Qdrant có thể bị crash khi tải dữ liệu lớn.
nproc
Kết quả mong đợi: Số nguyên >= 2. Đây là số lượng logical CPU cores khả dụng.
df -h /
Kết quả mong đợi: Cột "Avail" (Dung lượng trống) >= 10G. Qdrant cần không gian để lưu trữ data directory và logs.
Cài đặt Docker Engine và Docker Compose trên Ubuntu 24.04
Cài đặt Docker Engine chính thức từ kho của Docker, không dùng gói Docker cũ trong Ubuntu repository mặc định để đảm bảo tính tương thích.
Bước 1: Cài đặt các gói phụ thuộc
Cập nhật repository và cài đặt các gói cần thiết để thêm key GPG và repository của Docker.
sudo apt update
sudo apt install ca-certificates curl gnupg
Kết quả mong đợi: Không có lỗi, các gói được cài đặt thành công.
Bước 2: Thêm GPG Key và Repository Docker
Thêm key ký mã hóa chính thức của Docker vào hệ thống để xác minh nguồn gốc gói cài đặt.
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
Kết quả mong đợi: File key được tạo tại /etc/apt/keyrings/docker.gpg.
Thêm repository Docker vào danh sách nguồn apt của Ubuntu 24.04 (code name: noble).
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Kết quả mong đợi: File docker.list được tạo tại /etc/apt/sources.list.d/.
Bước 3: Cài đặt Docker Engine
Cài đặt docker-ce, docker-ce-cli, containerd.io và docker-buildx-plugin.
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Kết quả mong đợi: Quá trình cài đặt hoàn tất, không báo lỗi "package not found".
Bước 4: Cấu hình Docker chạy với quyền non-root
Thêm user hiện tại vào nhóm docker để chạy lệnh docker mà không cần sudo.
sudo usermod -aG docker $USER
Kết quả mong đợi: Không có lỗi. Cần đăng xuất và đăng nhập lại (hoặc chạy newgrp docker) để áp dụng quyền mới.
newgrp docker
Kết quả mong đợi: Prompt shell thay đổi, bạn có thể chạy lệnh docker mà không cần sudo.
Bước 5: Kiểm tra Docker và Docker Compose
Verify rằng Docker Engine và plugin Docker Compose đã hoạt động.
docker version
Kết quả mong đợi: Hiển thị thông tin Client và Server version, cả hai đều phải khớp (ví dụ: Docker version 27.x.x).
docker compose version
Kết quả mong đợi: Hiển thị "Docker Compose version v2.x.x". Nếu thấy lệnh "compose: command not found" thì cần kiểm tra lại bước cài đặt plugin.
Tải file docker-compose.yml mẫu từ kho Qdrant chính thức
Tạo thư mục dự án để chứa cấu hình và tải file docker-compose.yml chuẩn từ GitHub của Qdrant để đảm bảo cấu hình tối ưu nhất.
Bước 1: Tạo thư mục dự án
Tạo thư mục riêng cho dự án vector database để quản lý file cấu hình.
mkdir -p ~/qdrant-deploy
cd ~/qdrant-deploy
Kết quả mong đợi: Thư mục được tạo và bạn đã chuyển vào thư mục đó.
Bước 2: Tải file docker-compose.yml
Sử dụng curl để tải file cấu hình từ nhánh main của repository Qdrant chính thức.
curl -o docker-compose.yml https://raw.githubusercontent.com/qdrant/qdrant/main/docker-compose.yml
Kết quả mong đợi: File docker-compose.yml được tải về, không có lỗi 404.
Bước 3: Kiểm tra nội dung file cấu hình
Mở file để xác minh đường dẫn volume và cổng (port) mặc định. File này thường định nghĩa service qdrant và volume qdrant_data.
cat docker-compose.yml
Kết quả mong đợi: Bạn thấy nội dung YAML với service name "qdrant", image "qdrant/qdrant", port mapping "6333:6333" và "6334:6334", cùng volume mapping cho dữ liệu.
Đảm bảo file docker-compose.yml ở đường dẫn đầy đủ ~/qdrant-deploy/docker-compose.yml có nội dung hoàn chỉnh như sau (nếu file tải về bị lỗi hoặc trống, hãy tạo thủ công nội dung chuẩn sau):
version: '3.8'
services:
qdrant:
image: qdrant/qdrant:latest
restart: always
ports:
- 6333:6333
- 6334:6334
volumes:
- ./qdrant_storage:/qdrant/storage
environment:
- QDRANT__SERVICE__GRPC_PORT=6334
- QDRANT__SERVICE__HTTP_PORT=6333
- QDRANT__LOG_LEVEL=INFO
Kết quả mong đợi: File được lưu, nội dung khớp với cấu hình tiêu chuẩn của Qdrant, bao gồm mapping volume ./qdrant_storage sang /qdrant/storage bên trong container.
Khởi động container Qdrant và xác minh trạng thái
Khởi động Qdrant bằng Docker Compose ở chế độ nền (detached mode) và xác minh container đã chạy cũng như API đã sẵn sàng.
Bước 1: Khởi động Qdrant
Chạy lệnh docker compose up để build (nếu cần) và start container.
docker compose up -d
Kết quả mong đợi: Xuất hiện thông báo "qdrant Started" hoặc "Container qdrant is running". Không có lỗi lỗi về port conflict.
Bước 2: Kiểm tra trạng thái container
Xác minh container đang chạy (status: Up) và không bị crash.
docker compose ps
Kết quả mong đợi: Bảng hiển thị service "qdrant" có trạng thái "running" và time up (ví dụ: Up 30 seconds).
Bước 3: Xác minh API Qdrant
Sử dụng curl để gọi API health check của Qdrant trên cổng 6333 (HTTP).
curl http://localhost:6333/
Kết quả mong đợi: Trả về JSON: {"title": "Qdrant", "version": "x.x.x"}. Nếu thấy lỗi "Connection refused", container chưa khởi động xong, hãy đợi thêm 10-20 giây và chạy lại lệnh.
Bước 4: Kiểm tra log (nếu có sự cố)
Trường hợp API không phản hồi, kiểm tra log để tìm nguyên nhân (thường là lỗi disk permission hoặc OOM).
docker compose logs -f qdrant
Kết quả mong đợi: Log hiển thị dòng "Qdrant server started" và các thông báo "Listening on 6333/6334". Nhấn Ctrl+C để thoát xem log.
Bước 5: Tạo thư mục storage (nếu chưa có)
Docker compose đã tự động tạo thư mục volume, nhưng hãy xác minh quyền truy cập để tránh lỗi ghi dữ liệu sau này.
ls -la ./qdrant_storage
Kết quả mong đợi: Thư mục qdrant_storage tồn tại với các thư mục con như "collections", "snapshots", "snapshots".
Điều hướng series:
Mục lục: Series: Triển khai Database Vector đa mô hình với Qdrant trên Ubuntu 24.04
Phần 2: Cấu hình cơ bản và quản lý Collection trong Qdrant »