Chẩn đoán lỗi khởi động container và phân tích log Weaviate
Khi container Weaviate không thể vào trạng thái running, nguyên nhân thường nằm ở xung đột cổng, lỗi cấu hình môi trường hoặc thiếu tài nguyên hệ thống.
1. Kiểm tra trạng thái và lấy log thời gian thực
Sử dụng lệnh docker logs với cờ --tail để xem 100 dòng cuối cùng và -f để follow log theo thời gian thực.
docker logs --tail 100 -f weaviate-server
Kết quả mong đợi: Xuất hiện dòng "Weaviate is ready" nếu thành công, hoặc dòng "error starting up" kèm thông báo lỗi cụ thể (ví dụ: port 8080 is already in use).
2. Xử lý lỗi xung đột cổng (Port Conflict)
Nếu log báo lỗi bind: address already in use, nghĩa là cổng 8080 (REST API) hoặc 50051 (gRPC) đã bị tiến trình khác chiếm dụng.
sudo lsof -i :8080 && sudo lsof -i :50051
Kết quả mong đợi: Danh sách các tiến trình đang chiếm dụng cổng. Nếu có tiến trình lạ, dùng lệnh sudo kill -9 <PID> để giải phóng, sau đó khởi động lại container.
3. Chẩn đoán lỗi cấu hình Schema
Weaviate có cơ chế strict schema validation. Nếu file schema.json có cấu trúc sai (ví dụ: thiếu dataType), container sẽ crash ngay khi khởi động.
docker exec -it weaviate-server curl -X POST http://localhost:8080/v1/schema -H "Content-Type: application/json" -d @/weaviate-schema.json
Kết quả mong đợi: Nếu lỗi, bạn sẽ nhận được JSON trả về chứa "code": "validation failed" và "details" chỉ rõ field nào bị sai. Sửa file schema và reload lại.
Xử lý lỗi OOM (Out of Memory) khi tải dữ liệu lớn
Đặc thù của Vector Database là tốn RAM lớn để lưu trữ chỉ mục (index) và vector embedding trong bộ nhớ. Lỗi OOM Killer thường xảy ra khi RAM bị hết và Linux giết chết container.
1. Xác nhận lỗi OOM Killer
Kiểm tra log hệ thống của host Ubuntu để xem container có bị killed bởi OOM Killer không.
grep -i "out of memory" /var/log/syslog | grep weaviate
Kết quả mong đợi: Dòng log hiển thị "Out of memory: Kill process ... (weaviate) score ..." xác nhận container bị giết do thiếu RAM.
2. Cấu hình giới hạn tài nguyên Docker (Resource Limits)
Thay vì để Docker tự động giết container, hãy chủ động giới hạn RAM của container trong file docker-compose.yml để Weaviate tự động giảm bộ nhớ cache hoặc từ chối viết nếu vượt ngưỡng an toàn.
Chỉnh sửa file /opt/weaviate/docker-compose.yml, thêm phần deploy.resources vào service weaviate:
version: '3.8'
services:
weaviate:
image: semitechnologies/weaviate:1.24.0
ports:
- "8080:8080"
- "50051:50051"
environment:
QUERY_DEFAULTS_LIMIT: 25
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
DEFAULT_VECTORIZER_MODULE: 'none'
CLUSTER_HOSTNAME: 'node1'
volumes:
- weaviate_data:/var/lib/weaviate
deploy:
resources:
limits:
memory: 8G
reservations:
memory: 2G
restart: unless-stopped
volumes:
weaviate_data:
Kết quả mong đợi: Khi reload compose, container sẽ chạy với giới hạn RAM 8GB. Nếu vượt quá, Weaviate sẽ báo lỗi memory limit reached thay vì bị hệ điều hành giết đột ngột.
3. Tối ưu hóa Weaviate để giảm RAM
Để giảm tải RAM, cần tắt các module vectorizer không cần thiết và điều chỉnh tham số MaxConnections.
Cập nhật biến môi trường trong docker-compose.yml:
environment:
- DEFAULT_VECTORIZER_MODULE=none
- MAX_IMPORT_OBJECTS_PER_SECOND=100
- MAX_BATCH_SIZE=100
Kết quả mong đợi: Giảm đáng kể lượng RAM tiêu thụ khi import dữ liệu hàng loạt. Lưu ý: Cần cấu hình vectorize trong code ứng dụng Python thay vì trên Weaviate.
Cấu hình Persistence (Volume) để giữ dữ liệu khi restart
Dữ liệu vector nếu không được lưu vào Volume sẽ bị mất hoàn toàn khi container bị xóa hoặc restart. Cần cấu hình binding đúng để đảm bảo tính nhất quán (consistency).
1. Tạo thư mục dữ liệu trên Host
Tạo thư mục chuyên dụng trên Ubuntu để lưu trữ dữ liệu Weaviate, đảm bảo quyền truy cập đúng với user chạy Docker (thường là root hoặc 1000).
sudo mkdir -p /var/lib/weaviate-data
sudo chown -R 1000:1000 /var/lib/weaviate-data
ls -ld /var/lib/weaviate-data
Kết quả mong đợi: Thư mục được tạo với quyền sở hữu của user 1000 (user mặc định của image Weaviate), tránh lỗi Permission denied khi container cố ghi dữ liệu.
2. Cấu hình Volume Binding trong Docker Compose
Sửa file /opt/weaviate/docker-compose.yml để map thư mục host vào container.
version: '3.8'
services:
weaviate:
image: semitechnologies/weaviate:1.24.0
ports:
- "8080:8080"
environment:
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
volumes:
- /var/lib/weaviate-data:/var/lib/weaviate
restart: unless-stopped
Kết quả mong đợi: Khi chạy docker-compose up -d, dữ liệu sẽ được ghi trực tiếp vào thư mục /var/lib/weaviate-data trên host. Thử restart container bằng docker-compose restart, dữ liệu vẫn còn nguyên.
3. Verify tính toàn vẹn dữ liệu sau Restart
Thực hiện kiểm tra xem dữ liệu đã lưu trước đó còn tồn tại hay không.
curl -X GET "http://localhost:8080/v1/schema" | jq
Kết quả mong đợi: Trả về danh sách Class (Schema) đã được tạo trước khi restart. Nếu danh sách rỗng, volume mapping chưa đúng hoặc quyền truy cập bị sai.
Mẹo tối ưu hóa truy vấn cho tìm kiếm tương tự phức tạp
Trong môi trường Production, hiệu năng truy vấn (Query Performance) quan trọng hơn tốc độ ghi. Cần tinh chỉnh tham số Search Depth và Vector Distance Metric.
1. Tinh chỉnh HNSW Index cho Search
Tham số ef (search depth) trong HNSW index quyết định độ chính xác so với tốc độ. Giá trị mặc định là 100, có thể tăng để tìm kết quả chính xác hơn cho các bài toán phức tạp.
Cấu hình module hnsw trong schema của Class (ví dụ: Product):
{
"class": "Product",
"vectorIndexConfig": {
"ef": 512,
"maxConnections": 16
},
"vectorIndexType": "hnsw",
"vectorDistanceMetric": "cosine"
}
Kết quả mong đợi: Truy vấn tìm kiếm tương tự (Similarity Search) sẽ trả về kết quả chính xác hơn (Recall cao hơn) nhưng thời gian phản hồi (Latency) có thể tăng nhẹ. Tham số ef nên đặt >= số lượng kết quả mong muốn (limit).
2. Sử dụng Filter để giảm không gian tìm kiếm
Đừng tìm kiếm vector trên toàn bộ dataset nếu không cần thiết. Hãy dùng WhereClause để lọc giảm số lượng vector cần so sánh trước khi tính toán khoảng cách.
Ví dụ truy vấn GraphQL với filter:
query {
Get {
Product(
where: {
path: ["category"],
operator: Equal,
valueText: "electronics"
},
limit: 10
) {
_additional {
distance
}
}
}
}
Kết quả mong đợi: Weaviate chỉ tính toán khoảng cách vector cho các object thuộc nhóm electronics, giảm thời gian phản hồi xuống hàng chục lần so với quét toàn bộ.
3. Tối ưu hóa Batch Import trong Production
Để tránh tắc nghẽn CPU/RAM khi import hàng triệu vector, sử dụng Batch API với kích thước batch động và tốc độ giới hạn.
curl -X POST "http://localhost:8080/v1/batch/objects" \
-H "Content-Type: application/json" \
-d '{
"batch": [
{
"class": "Product",
"id": "1",
"vector": [0.1, 0.2, 0.3],
"properties": {"name": "Laptop"}
}
]
}'
Kết quả mong đợi: Trả về 200 OK với danh sách ID được chấp nhận. Nếu quá tải, Weaviate sẽ trả về 429 Too Many Requests, lúc này cần giảm kích thước batch hoặc giảm tốc độ gửi trong code ứng dụng.
Điều hướng series:
Mục lục: Series: Triển khai Database Vector với Weaviate và Ubuntu 24.04
« Phần 6: Tối ưu hóa hiệu năng: Sharding, Indexing và Backup