Cài đặt và cấu hình Weaviate CLI trên Ubuntu
Công cụ dòng lệnh Weaviate CLI cho phép bạn quản lý schema, index và metadata mà không cần viết code hay dùng GraphQL Playground trực tiếp. Bước này thiết lập môi trường làm việc ngay trên terminal của Ubuntu.
Tải và cài đặt binary file mới nhất của Weaviate CLI từ kho chính thức của dự án.
curl -L https://github.com/weaviate/weaviate/releases/download/v1.24.0/weaviate-cli_linux_amd64.tar.gz | tar -xzf - -C /usr/local/bin/ weaviate-cli && chmod +x /usr/local/bin/weaviate-cli
File binary được giải nén vào thư mục /usr/local/bin/ và cấp quyền thực thi. Bạn có thể chạy lệnh weaviate-cli từ bất kỳ đâu trên hệ thống.
Khởi động phiên bản CLI để kiểm tra phiên bản và xác nhận cài đặt thành công.
weaviate-cli --version
Hệ thống trả về thông tin phiên bản, ví dụ: "weaviate-cli 1.24.0". Nếu không có lỗi, công cụ đã sẵn sàng sử dụng.
Cấu hình kết nối giữa CLI và Weaviate Instance
CLI cần biết địa chỉ IP và cổng của container Weaviate đang chạy để thực hiện các lệnh. Chúng ta sẽ tạo file cấu hình ~/.weaviate-cli/config.yaml để lưu thông tin này một lần.
Trước tiên, xác minh Weaviate đang chạy và nghe trên cổng mặc định (8080) hoặc cổng bạn đã cấu hình trong Docker Compose.
docker ps | grep weaviate
Đầu ra hiển thị container weaviate đang ở trạng thái "Up". Ghi nhận lại IP của máy chủ (localhost hoặc IP thật nếu remote).
Tạo file cấu hình kết nối tại đường dẫn ~/.weaviate-cli/config.yaml. Nội dung file chỉ định endpoint kết nối.
mkdir -p ~/.weaviate-cli && cat > ~/.weaviate-cli/config.yaml
File cấu hình được tạo thành công. CLI sẽ tự động đọc file này khi thực thi lệnh, không cần gõ lại --host mỗi lần.
Thực hiện lệnh kiểm tra kết nối để đảm bảo CLI giao tiếp được với server.
weaviate-cli schema dump
Lệnh này sẽ trả về một file JSON rỗng hoặc danh sách các class đã tồn tại. Nếu thấy lỗi "Connection refused", hãy kiểm tra lại địa chỉ IP và trạng thái container.
Quản lý Schema thông qua GraphQL Playground
Weaviate cung cấp GraphQL Playground (trình duyệt web) là giao diện trực quan nhất để thao tác với Schema (Class, Property) và thực hiện truy vấn phức tạp. Phần này hướng dẫn tạo Class mới và đưa dữ liệu vào.
Tạo Class mới bằng GraphQL
Mở trình duyệt và truy cập địa chỉ GraphQL Playground của Weaviate. Địa chỉ mặc định là http://localhost:8080/v1/graphql.
Trong khung Query bên trái, dán đoạn mã GraphQL Mutation dưới đây để định nghĩa một Class mới tên là "Product" với các thuộc tính: tên (name), mô tả (description) và giá (price).
mutation {
schema {
class {
name: Product
properties: [
{
name: name
dataType: ["Text"]
},
{
name: description
dataType: ["Text"]
},
{
name: price
dataType: ["Int"]
}
]
}
}
}
Bấm nút Play (mũi tên xanh) để thực thi. Kết quả mong đợi là JSON trả về với trường "data.schema.class" có giá trị "Product", xác nhận Class đã được tạo thành công.
Thêm dữ liệu mẫu (Sample Data) vào Collection
Sau khi có Schema, bạn cần đưa dữ liệu vào. Chúng ta sẽ dùng lệnh GraphQL Mutation để tạo 3 bản ghi (Object) mẫu cho Class "Product" vừa tạo.
Sử dụng cú pháp GraphQL để thêm dữ liệu. Lưu ý: Weaviate tự động tạo ID nếu không cung cấp, và các trường Text cần được đặt trong dấu ngoặc kép.
mutation {
Product {
add {
name: "Laptop Gaming"
description: "High performance laptop for gaming"
price: 1500
},
add {
name: "Wireless Mouse"
description: "Ergonomic wireless mouse"
price: 50
},
add {
name: "Mechanical Keyboard"
description: "RGB mechanical keyboard"
price: 120
}
}
}
Thực thi đoạn code trên. Kết quả trả về sẽ là danh sách các ID (UUID) của các object vừa được tạo. Nếu có lỗi, hãy kiểm tra lại tên Class và kiểu dữ liệu (dataType) trong bước tạo Schema.
Xác minh dữ liệu đã thêm
Để đảm bảo dữ liệu đã được lưu trữ chính xác, thực hiện truy vấn (Query) để lấy lại danh sách các sản phẩm.
Sử dụng cú pháp GraphQL Query với bộ lọc (where) hoặc lấy tất cả để kiểm tra nội dung.
query {
Product(limit: 10) {
_additional {
id
}
name
price
}
}
Khung kết quả bên phải sẽ hiển thị JSON chứa danh sách 3 sản phẩm với ID, tên và giá. Nếu thấy đủ 3 dòng dữ liệu, việc đưa dữ liệu mẫu đã thành công.
So sánh và Kiểm tra chéo giữa CLI và GraphQL
Để khẳng định tính nhất quán của dữ liệu, chúng ta sẽ dùng CLI để kiểm tra lại những gì vừa tạo bằng GraphQL Playground.
Sử dụng lệnh CLI để dump toàn bộ schema hiện tại, xác nhận Class "Product" xuất hiện trong cấu trúc JSON.
weaviate-cli schema dump | jq '.classes[] | select(.class == "Product")'
Trình biên dịch jq lọc và hiển thị cấu trúc của Class "Product". Kết quả phải khớp với định nghĩa trong bước GraphQL (có các properties: name, description, price).
Sử dụng lệnh CLI để liệt kê các object trong Class "Product" (tương đương với Query GraphQL ở trên).
weaviate-cli object list --class Product
CLI sẽ in ra danh sách các object với các trường dữ liệu tương ứng. Nếu thấy 3 object "Laptop Gaming", "Wireless Mouse", "Mechanical Keyboard", hệ thống hoạt động đồng bộ hoàn hảo giữa CLI và GraphQL.
Điều hướng series:
Mục lục: Series: Triển khai Database Vector với Weaviate và Ubuntu 24.04
« Phần 2: Triển khai Weaviate qua Docker Compose với cấu hình cơ bản
Phần 4: Xây dựng ứng dụng Vector Search với Python và Weaviate Client »