1. Cấu trúc thư mục và tạo file docker-compose.yml
Bước đầu tiên là thiết lập thư mục dự án để chứa file cấu hình Docker Compose. Chúng ta cần tạo một thư mục mới để cô lập môi trường Weaviate, đảm bảo tính gọn gàng và dễ quản lý.
Tạo thư mục dự án và di chuyển vào thư mục đó:
mkdir -p ~/weaviate-project && cd ~/weaviate-project
Thư mục `weaviate-project` đã được tạo và bạn đang ở trong thư mục này.
2. Tạo file docker-compose.yml
File `docker-compose.yml` là trái tim của việc triển khai. Nó định nghĩa service, image, port mapping, và biến môi trường. Chúng ta sẽ cấu hình Weaviate để chạy với các module cơ bản và bật giao thức gRPC cho hiệu năng cao.
Sử dụng `nano` hoặc `cat` để tạo file cấu hình tại đường dẫn `~/weaviate-project/docker-compose.yml` với nội dung hoàn chỉnh dưới đây:
version: "3.9"
services:
weaviate:
image: semitechnologies/weaviate:1.25.0
command:
- --host
- 0.0.0.0
- --port
- "8080"
- --scheme
- http
ports:
- "8080:8080"
- "50051:50051"
environment:
# Cấu hình bảo mật cơ bản (tắt auth cho môi trường dev)
- AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true
- PERSISTENCE_DATA_PATH=/var/lib/weaviate
# Cấu hình Modules
- DEFAULT_VECTORIZER_MODULE=text2vec-transformers
- MODULES_CONFIG=text2vec-transformers
# Cấu hình gRPC
- GRPC_ENABLED=true
# Cấu hình Cluster (Single node cho bài này)
- CLUSTER_HOSTNAME="node1"
# Log level để debug
- LOG_LEVEL=info
volumes:
- weaviate_data:/var/lib/weaviate
restart: unless-stopped
volumes:
weaviate_data:
File `docker-compose.yml` đã được lưu thành công với đầy đủ cấu hình port 8080 (HTTP) và 50051 (gRPC), cùng module `text2vec-transformers` mặc định.
3. Cấu hình biến môi trường (Environment Variables)
Mặc dù file `docker-compose.yml` đã chứa các biến môi trường cơ bản, việc tách biệt cấu hình nhạy cảm hoặc các biến thay đổi thường xuyên vào file `.env` là best practice. Tuy nhiên, trong cấu hình cơ bản này, chúng ta sẽ giải thích sâu hơn về các biến quan trọng đã được đặt trong file compose để bạn hiểu rõ cơ chế hoạt động.
Các biến môi trường quan trọng đã cấu hình:
- AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true: Cho phép truy cập không cần API Key. Chỉ dùng cho môi trường Dev/Local. Lý do: Giúp bạn test nhanh mà không cần cấu hình Auth phức tạp ở phần này.
- DEFAULT_VECTORIZER_MODULE=text2vec-transformers: Kích hoạt module chuyển đổi văn bản thành vector. Lý do: Đây là module cốt lõi để thực hiện Vector Search cho dữ liệu văn bản.
- GRPC_ENABLED=true: Bật cổng giao thức gRPC. Lý do: Client của Weaviate (Python, JS, Go) ưu tiên dùng gRPC để tốc độ nhanh hơn HTTP.
- PORT_MAPPING: Ánh xạ cổng 8080 cho REST API và 50051 cho gRPC.
Bạn đã hiểu rõ cách các biến môi trường ảnh hưởng đến hành vi của container Weaviate.
4. Cài đặt Weaviate module đầu tiên (Text2Vec-Transformer)
Trong file `docker-compose.yml` ở trên, chúng ta đã khai báo `DEFAULT_VECTORIZER_MODULE=text2vec-transformers`. Điều này có nghĩa là khi container khởi động, Weaviate sẽ tự động tải và khởi tạo module này. Bạn không cần cài đặt thêm package bên ngoài.
Tuy nhiên, để đảm bảo module này hoạt động đúng, Weaviate cần tải model từ HuggingFace Hub vào bộ nhớ đệm (cache) khi xử lý lần đầu. Cấu hình `MODULES_CONFIG` trong file compose đã kích hoạt điều này.
Chúng ta sẽ kiểm tra xem module này đã sẵn sàng chưa sau khi container chạy bằng lệnh kiểm tra health check hoặc list modules.
Cấu hình module đã được tích hợp sẵn trong file `docker-compose.yml` và sẽ được kích hoạt tự động khi container khởi động.
5. Chạy container và kiểm tra trạng thái khởi động
Bây giờ chúng ta sẽ khởi động toàn bộ stack Weaviate bằng Docker Compose. Lệnh này sẽ kéo image, tạo volume, và chạy container trong chế độ detached (chạy nền).
Chạy lệnh khởi động:
docker compose up -d
Container Weaviate đã được khởi động thành công và đang chạy nền. Dòng cuối cùng thường là "Started weaviate_1".
6. Verify kết quả và kiểm tra logs
Để đảm bảo Weaviate khởi động thành công, module đã load và không có lỗi, chúng ta cần xem logs của container.
Thực hiện lệnh xem logs theo thời gian thực:
docker compose logs -f weaviate
Bạn sẽ thấy dòng log cuối cùng chứa thông báo:
Weaviate is ready to serve requests!
Đồng thời, tìm kiếm trong logs các dòng xác nhận module đã được load:
module text2vec-transformers enabled
Trong terminal, hãy nhấn Ctrl + C để thoát khỏi chế độ xem logs. Weaviate vẫn đang chạy nền.
7. Kiểm tra trạng thái dịch vụ bằng lệnh curl
Để chắc chắn 100% rằng dịch vụ đang lắng nghe cổng 8080 và API hoạt động, chúng ta sẽ gọi endpoint health check.
Thực hiện lệnh kiểm tra trạng thái sức khỏe:
curl -s http://localhost:8080/v1/.well-known/ready
Kết quả mong đợi là trả về một object JSON:
{"result":"READY"}
Nếu thấy kết quả này, Weaviate đã sẵn sàng để nhận yêu cầu từ client. Nếu thấy lỗi "Connection refused", hãy đợi thêm 10-20 giây rồi chạy lại lệnh, vì quá trình tải model đầu tiên có thể mất thời gian.
8. Kiểm tra danh sách Modules đã kích hoạt
Cuối cùng, để xác minh module `text2vec-transformers` thực sự đã được đăng ký trong hệ thống, chúng ta sẽ gọi endpoint list modules.
Thực hiện lệnh:
curl -s http://localhost:8080/v1/modules | jq '.modules[] | select(.name=="text2vec-transformers")'
Kết quả mong đợi là một object JSON chứa thông tin của module `text2vec-transformers`. Nếu không có gì trả về, hãy kiểm tra lại biến `MODULES_CONFIG` trong file `docker-compose.yml`.
Quá trình triển khai Weaviate cơ bản với Docker Compose đã hoàn tất. Hệ thống sẵn sàng cho các bước kết nối client trong phần tiếp theo.
Điều hướng series:
Mục lục: Series: Triển khai Database Vector với Weaviate và Ubuntu 24.04
« Phần 1: Chuẩn bị môi trường Ubuntu 24.04 và yêu cầu phần cứng cho Weaviate
Phần 3: Kết nối và quản lý Weaviate bằng CLI và GraphQL »