Cài đặt môi trường Python và Weaviate Client trên Ubuntu 24.04
Trước khi viết code, chúng ta cần chuẩn bị môi trường ảo (virtual environment) để cô lập các thư viện Python, tránh xung đột với hệ thống Ubuntu 24.04 mặc định.
Mục đích: Tạo không gian làm việc sạch sẽ, an toàn cho ứng dụng Vector Search.
Kết quả mong đợi: Một thư mục dự án với môi trường ảo đã kích hoạt và thư viện weaviate-client được cài đặt thành công.
Đầu tiên, tạo thư mục dự án và thư mục nguồn code:
mkdir -p ~/projects/weaviate-app/src
cd ~/projects/weaviate-app/src
Tiếp theo, tạo và kích hoạt virtual environment sử dụng Python 3 mặc định của Ubuntu 24.04:
python3 -m venv venv
source venv/bin/activate
Cài đặt thư viện chính thức của Weaviate cho Python. Thư viện này xử lý giao tiếp gRPC và HTTP với Weaviate Server:
pip install weaviate-client
Để tối ưu hóa việc tính toán vector embedding ngay trong Python (nếu cần), cài thêm thư viện hỗ trợ:
pip install numpy sentence-transformers
Verify kết quả bằng cách kiểm tra phiên bản đã cài đặt:
pip show weaviate-client
Viết script kết nối và xác thực với Weaviate
Bước tiếp theo là viết script Python đầu tiên để thiết lập kết nối an toàn với Weaviate Server đang chạy trên Docker.
Mục đích: Tạo đối tượng Client, cấu hình endpoint và kiểm tra trạng thái kết nối (connectivity check).
Kết quả mong đợi: Script chạy không lỗi và in ra thông báo "Connected to Weaviate" cùng phiên bản server.
Tạo file cấu hình kết nối ở đường dẫn: ~/projects/weaviate-app/src/config.py. File này chứa các biến môi trường để quản lý endpoint và API key (nếu có).
WEAVIATE_URL = "http://localhost:8080"
# Nếu chưa bật bảo mật, để trống. Nếu bật, điền API Key vào đây
WEAVIATE_API_KEY = ""
Tạo file script chính: ~/projects/weaviate-app/src/connect.py. Script này sử dụng weaviate.Client để kết nối.
import weaviate
from config import WEAVIATE_URL, WEAVIATE_API_KEY
# Khởi tạo client
if WEAVIATE_API_KEY:
client = weaviate.Client(
url=WEAVIATE_URL,
auth_credentials=weaviate.AuthApiKey(api_key=WEAVIATE_API_KEY)
)
else:
client = weaviate.Client(url=WEAVIATE_URL)
# Kiểm tra kết nối
if client.is_ready():
print("Connected to Weaviate successfully.")
print(f"Weaviate version: {client.get_meta()['version']}")
else:
print("Connection failed. Check if Weaviate Docker container is running.")
Chạy script để verify kết nối:
python3 connect.py
Thực hiện thao tác Insert dữ liệu có Vector Embedding
Bây giờ chúng ta sẽ thêm dữ liệu vào Weaviate. Weaviate có thể tự động tạo vector từ văn bản nếu cấu hình đúng module, hoặc chúng ta có thể đưa vào vector số liệu (float list) đã tính sẵn.
Mục đích: Tạo Collection (Schema mới) và thêm dữ liệu mẫu (documents) vào Collection đó.
Kết quả mong đợi: Một Collection tên "Article" được tạo và 3 bản ghi (objects) chứa văn bản và vector embedding được lưu vào database.
Tạo file: ~/projects/weaviate-app/src/insert_data.py. Trong file này, chúng ta sẽ tạo Collection mới và thêm dữ liệu.
import weaviate
from config import WEAVIATE_URL, WEAVIATE_API_KEY
import numpy as np
# 1. Kết nối
client = weaviate.Client(
url=WEAVIATE_URL,
auth_credentials=weaviate.AuthApiKey(api_key=WEAVIATE_API_KEY) if WEAVIATE_API_KEY else None
)
# 2. Tạo Collection (Schema)
# Sử dụng module 'text2vec-default' để tự động generate vector từ text
collection = client.collections.create(
name="Article",
properties=[
{
"name": "title",
"dataType": "text"
},
{
"name": "content",
"dataType": "text"
}
],
vectorizer_config=[
weaviate.config.ConfigureVectorization(
vectorizer=weaviate.config.Vectorizer.TEXT2VEC_DEFAULT,
model="multi-2023"
)
]
)
# 3. Dữ liệu mẫu
articles = [
{"title": "Giới thiệu về Weaviate", "content": "Weaviate là một vector database mã nguồn mở..."},
{"title": "Python cho AI", "content": "Python là ngôn ngữ phổ biến nhất cho Machine Learning..."},
{"title": "Kubernetes cho DevOps", "content": "Kubernetes giúp tự động hóa deployment và scaling container..."}
]
# 4. Thêm dữ liệu vào Collection
print(f"Adding {len(articles)} documents to 'Article' collection...")
for article in articles:
# Weaviate Client tự động gọi module embedding khi insert
collection.data.insert(
properties=article,
vector=article['content'] # Đưa nội dung vào trường vector để module tự tính
)
print("Insert completed. Data is ready for search.")
Chạy script để insert dữ liệu:
python3 insert_data.py
Verify kết quả bằng cách đếm số lượng object trong Collection:
python3 -c "import weaviate; from config import WEAVIATE_URL; c = weaviate.Client(WEAVIATE_URL); col = c.collections.get('Article'); print(f'Total objects: {col.aggregate.over_all(total_count=True)}')"
Thực hiện thao tác Hybrid Search kết hợp Keyword và Vector
Hybrid Search là điểm mạnh của Weaviate, cho phép tìm kiếm đồng thời dựa trên từ khóa (BM25) và sự tương đồng vector (Vector Search).
Mục đích: Tìm kiếm tài liệu liên quan đến một query cụ thể bằng cách cân bằng giữa tìm kiếm văn bản và ngữ nghĩa.
Kết quả mong đợi: Script trả về danh sách các bài viết có điểm số (score) cao nhất, kết hợp cả yếu tố từ khóa và ngữ nghĩa.
Tạo file: ~/projects/weaviate-app/src/hybrid_search.py. Script này thực hiện tìm kiếm trên Collection "Article" đã tạo ở bước trên.
import weaviate
from config import WEAVIATE_URL, WEAVIATE_API_KEY
# Kết nối
client = weaviate.Client(
url=WEAVIATE_URL,
auth_credentials=weaviate.AuthApiKey(api_key=WEAVIATE_API_KEY) if WEAVIATE_API_KEY else None
)
# Lấy Collection
collection = client.collections.get("Article")
# Query cần tìm kiếm
query = "Machine Learning và Vector Database"
# Thực hiện Hybrid Search
# alpha: cân bằng giữa Vector (0.0) và Keyword (1.0). 0.5 là cân bằng 50/50
# query_properties: chỉ tìm kiếm trong các trường nào (tối ưu hiệu năng)
results = collection.hybrid_search(
query=query,
properties=["title", "content"],
alpha=0.5,
limit=10
)
# Hiển thị kết quả
print(f"Search results for: '{query}'")
print("-" * 40)
for i, obj in enumerate(results.objects):
print(f"Rank {i+1}:")
print(f" Title: {obj.properties['title']}")
print(f" Score: {obj.score}")
print(f" Vector Score: {obj.vector_score}")
print(f" BM25 Score: {obj.bm25_score}")
print("-" * 40)
Chạy script để thực hiện tìm kiếm Hybrid:
python3 hybrid_search.py
Verify kết quả bằng cách thử query khác để xem thứ tự kết quả thay đổi:
python3 -c "import weaviate; from config import WEAVIATE_URL; c = weaviate.Client(WEAVIATE_URL); col = c.collections.get('Article'); res = col.hybrid_search('Kubernetes'); print('Found:', len(res.objects)); print('Top result:', res.objects[0].properties['title'] if res.objects else 'None')"
Điều hướng series:
Mục lục: Series: Triển khai Database Vector với Weaviate và Ubuntu 24.04
« Phần 3: Kết nối và quản lý Weaviate bằng CLI và GraphQL
Phần 5: Cấu hình bảo mật: Xác thực, OAuth2 và HTTPS »