Phân tích và xử lý các lỗi thường gặp trong log Qdrant
Trước khi xử lý sự cố, cần xác định vị trí log file của container Qdrant đang chạy để thu thập thông tin.
Log file giúp nhận diện nguyên nhân từ lỗi cấu hình, thiếu tài nguyên hoặc xung đột port.
Thực hiện lệnh sau để xem log thời gian thực:
docker logs -f --tail 100 qdrant-container
Kết quả mong đợi: Dòng log hiện ra, hiển thị các lỗi gần nhất như "Out of memory", "Bind error", hoặc "Index not found".
Xử lý lỗi "Address already in use"
Lỗi này xảy ra khi port 6333 (REST API) hoặc 6334 (gRPC) đã bị tiến trình khác chiếm dụng trên Ubuntu 24.04.
Nguyên nhân thường là do container cũ chưa tắt hoàn toàn hoặc một dịch vụ khác đang chạy trên port đó.
Thực hiện kiểm tra tiến trình đang giữ port:
sudo lsof -i :6333
Nếu có kết quả trả về, cần kill tiến trình đó hoặc thay đổi port trong file config của Qdrant.
Để thay đổi port, chỉnh sửa file `qdrant_config.yaml` trong container hoặc mount từ host.
sudo nano /opt/qdrant/qdrant_config.yaml
Sửa phần `http_port` và `grpc_port` thành port khác (ví dụ 6335, 6336).
http_port: 6335
grpc_port: 6336
Khởi động lại container sau khi lưu file:
docker restart qdrant-container
Kết quả mong đợi: Container khởi động thành công, không còn lỗi bind port.
Xử lý lỗi "Out of memory" (OOM)
Lỗi này xảy ra khi bộ nhớ RAM của máy chủ không đủ để load toàn bộ index vào RAM hoặc xử lý query lớn.
Qdrant lưu trữ vector trong RAM để đạt tốc độ cao, nếu vượt quá giới hạn, container sẽ bị kill.
Thực hiện kiểm tra giới hạn bộ nhớ hiện tại của container:
docker inspect qdrant-container | grep -i "memory"
Để khắc phục, cần tăng giới hạn RAM cho container hoặc giảm số lượng shard/vector.
Cập nhật giới hạn RAM khi khởi động lại container (ví dụ 8GB):
docker update --memory=8g qdrant-container
Kết quả mong đợi: Container hoạt động ổn định, không bị restart do OOM killer.
Cấu hình giám sát hiệu năng với Prometheus và Grafana
Qdrant có sẵn endpoint metrics hỗ trợ Prometheus, cần cấu hình để thu thập dữ liệu hiệu năng.
Giám sát giúp phát hiện sớm tình trạng quá tải CPU, I/O bottleneck hoặc latency cao.
Cấu hình Prometheus để scrape metrics Qdrant
Tạo file cấu hình Prometheus để định nghĩa target là địa chỉ IP của container Qdrant.
Endpoint metrics mặc định của Qdrant là `/metrics` trên port 6333.
Chạy container Prometheus với file config tùy chỉnh:
mkdir -p /etc/prometheus
nano /etc/prometheus/prometheus.yml
Nội dung file `/etc/prometheus/prometheus.yml`:
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'qdrant'
static_configs:
- targets: ['host.docker.internal:6333']
metrics_path: '/metrics'
Khởi động Prometheus:
docker run -d --name prometheus -p 9090:9090 -v /etc/prometheus:/etc/prometheus prom/prometheus --config.file=/etc/prometheus/prometheus.yml
Kết quả mong đợi: Truy cập `http://localhost:9090/targets` thấy trạng thái "UP" cho job 'qdrant'.
Cấu hình Grafana để hiển thị Dashboard
Grafana cần được kết nối với Prometheus để vẽ biểu đồ từ các metrics đã thu thập.
Chạy container Grafana và cấu hình Data Source.
docker run -d --name grafana -p 3000:3000 grafana/grafana
Truy cập `http://localhost:3000` (default admin/password), thêm Data Source mới.
Trong phần Data Source, chọn Prometheus và nhập URL:
http://prometheus:9090
Nội dung URL này giả định bạn chạy trên cùng một network Docker. Nếu chạy trên host, dùng IP của Prometheus.
Click "Save & Test" để xác nhận kết nối.
Sau đó, import Dashboard mẫu của Qdrant (ID: 14645 hoặc tìm kiếm "Qdrant" trong Template).
curl -X POST http://localhost:3000/api/search -H "Content-Type: application/json" -d '{"query":"qdrant","type":"dashboard"}'
Kết quả mong đợi: Dashboard hiển thị các biểu đồ về Request Rate, Latency, Memory Usage, và Disk I/O.
Xử lý tình trạng đầy bộ nhớ và Disk I/O bottleneck
Trong môi trường production, Qdrant có thể gặp vấn đề khi lượng vector tăng đột biến gây nghẽn I/O.
Cần điều chỉnh tham số lưu trữ để cân bằng giữa hiệu năng và tài nguyên.
Giảm tải Disk I/O bằng bộ nhớ đệm (Cache)
Tăng kích thước cache của Qdrant để giảm số lần đọc trực tiếp từ disk.
Tham số này được cấu hình trong file `qdrant_config.yaml`.
Sửa file cấu hình:
sudo nano /opt/qdrant/qdrant_config.yaml
Cập nhật phần `storage` với tham số `cache_size_mb`:
storage:
storage_path: "storage"
cache_size_mb: 4096
max_search_threads: 4
Giá trị `cache_size_mb` nên chiếm khoảng 20-30% tổng RAM của server.
Khởi động lại Qdrant để áp dụng:
docker restart qdrant-container
Kết quả mong đợi: Latency giảm, số lần I/O read trên disk giảm (kiểm tra qua Grafana).
Quản lý điểm đầy Disk (Disk Full)
Khi disk đầy, Qdrant sẽ ngừng chấp nhận write mới và có thể treo các request hiện tại.
Nguyên nhân là do snapshot tự động hoặc log file quá lớn.
Thực hiện kiểm tra dung lượng disk đang sử dụng:
df -h /var/lib/qdrant
Xóa các snapshot cũ không cần thiết qua API hoặc trực tiếp trong thư mục.
Danh sách snapshot nằm trong thư mục `storage/snapshots`.
ls -lh /var/lib/qdrant/storage/snapshots/
Xóa snapshot cũ (ví dụ file có timestamp cũ hơn 7 ngày):
find /var/lib/qdrant/storage/snapshots/ -name "*.snapshot" -mtime +7 -delete
Cũng cần giới hạn kích thước log để tránh tràn disk:
sudo nano /etc/logrotate.d/qdrant
Nội dung file logrotate (nếu dùng systemd journal hoặc log file riêng):
/var/log/qdrant/*.log {
daily
rotate 7
compress
missingok
notifempty
}
Kết quả mong đợi: Dung lượng disk được giải phóng, Qdrant quay lại trạng thái chấp nhận write.
Các mẹo bảo mật nâng cao: HTTPS và Authentication
Trong môi trường production, việc truyền tải vector và metadata qua HTTP không an toàn.
Cần cấu hình HTTPS và cơ chế xác thực (Authentication) để bảo vệ dữ liệu.
Cấu hình HTTPS với chứng chỉ tự tạo (Self-signed)
Qdrant hỗ trợ HTTPS thông qua file chứng chỉ và private key.
Tạo thư mục chứa chứng chỉ và sinh cặp key mới trên Ubuntu:
mkdir -p /opt/qdrant/certs
cd /opt/qdrant/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout qdrant.key -out qdrant.crt -subj "/C=VN/ST=HCM/CN=localhost"
Công lệnh này tạo file `qdrant.key` (private key) và `qdrant.crt` (public certificate).
Cấu hình Qdrant sử dụng chứng chỉ này trong `qdrant_config.yaml`:
sudo nano /opt/qdrant/qdrant_config.yaml
Thêm phần `https` vào file config:
https:
enabled: true
certificate_path: "/opt/qdrant/certs/qdrant.crt"
key_path: "/opt/qdrant/certs/qdrant.key"
port: 6443
Khởi động lại container và mount thư mục certs vào container:
docker stop qdrant-container && docker rm qdrant-container
docker run -d --name qdrant-container -p 6443:6443 -v /opt/qdrant/certs:/opt/qdrant/certs qdrant/qdrant
Kết quả mong đợi: Truy cập `https://localhost:6443` thấy thông báo chứng chỉ an toàn (bỏ qua warning tự tạo).
Cấu hình Authentication (API Key)
Bật tính năng xác thực yêu cầu API Key cho mọi request để ngăn truy cập trái phép.
Qdrant sử dụng header `X-Api-Key` để xác thực.
Tạo file chứa API Key (nên dùng một chuỗi ngẫu nhiên dài):
echo "my-super-secret-api-key-12345" > /opt/qdrant/api_key
Cập nhật `qdrant_config.yaml` để kích hoạt authentication:
sudo nano /opt/qdrant/qdrant_config.yaml
Thêm phần `api_key` vào config:
api_key: "my-super-secret-api-key-12345"
Khởi động lại container và mount file api_key (nếu cần) hoặc dùng biến môi trường.
Để test, thực hiện request curl có header API Key:
curl -k -H "X-Api-Key: my-super-secret-api-key-12345" https://localhost:6443/collections
Kết quả mong đợi: Trả về danh sách collections (JSON). Nếu thiếu header hoặc key sai, trả về lỗi `401 Unauthorized`.
Verify kết quả bảo mật tổng thể
Thực hiện kiểm tra cuối cùng để đảm bảo HTTPS và Authentication hoạt động đồng thời.
Thử truy cập mà không có key:
curl -k https://localhost:6443/collections
Kết quả mong đợi: Lỗi 401 Unauthorized.
Thử truy cập với key đúng:
curl -k -H "X-Api-Key: my-super-secret-api-key-12345" https://localhost:6443/collections
Kết quả mong đợi: Trả về JSON chứa danh sách collections.
Thử truy cập qua HTTP port cũ (6333) nếu đã tắt:
curl http://localhost:6333/collections
Kết quả mong đợi: Kết nối bị từ chối (Connection refused) hoặc lỗi, chứng tỏ HTTP đã bị vô hiệu hóa.
Đ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 4: Tối ưu hiệu năng với bộ nhớ đệm và lập chỉ mục