EzyVector là plugin cơ sở dữ liệu vector dành cho EzyPlatform, giúp website có thể lưu trữ embedding và tìm kiếm ngữ nghĩa ngay trong hệ sinh thái sẵn có. Thay vì phải triển khai thêm một dịch vụ vector database riêng như Qdrant, Pinecone hay Weaviate, EzyVector cung cấp một lớp lưu trữ và tìm kiếm vector tích hợp với EzyPlatform, MySQL và hệ thống quản trị hiện có.

Kiến Trúc Tổng Quan

EzyVector được thiết kế theo hướng nhẹ, dễ vận hành và phù hợp với các ứng dụng AI native trên EzyPlatform. Dữ liệu metadata được lưu trong MySQL, còn vector và chỉ mục tìm kiếm được lưu trên filesystem của server.
flowchart TD
    A[Ứng dụng / AI Agent / RAG Service] --> B[EzyVector API]
    B --> C[Web Plugin]
    C --> D[Vector Service]

    D --> E[(MySQL)]
    D --> F[Vector File Storage]
    D --> G[HNSW Index]

    E --> E1[Collection metadata]
    E --> E2[Point metadata]
    E --> E3[Payload]
    E --> E4[Segment metadata]

    F --> F1[Vector data]
    F --> F2[Point id mapping]
    F --> F3[Backfill progress]

    G --> G1[Approximate nearest neighbor search]
    G --> G2[Persistent index file]

    D --> H[Admin Plugin]
    H --> I[Quản trị collection, point, segment]
Cách phân chia này giúp MySQL đảm nhiệm phần dữ liệu có cấu trúc, transaction và metadata, trong khi phần vector nặng hơn được đưa ra file storage để giảm áp lực lên Java heap.

Thành Phần Chính

EzyVector gồm ba phần chính:
  • SDK lõi: chứa mô hình collection, point, segment, service xử lý upsert/search, lưu trữ vector và chỉ mục HNSW.
  • Web plugin: cung cấp API để tạo collection, thêm/cập nhật point và tìm kiếm vector.
  • Admin plugin: cung cấp màn hình quản trị để theo dõi collection, point, segment, trạng thái, số lượng điểm, loại chỉ mục và cấu hình liên quan.
Một collection đại diện cho một không gian vector. Mỗi collection có tên riêng, kích thước vector, distance metric, loại chỉ mục và trạng thái hoạt động. Một point là một vector cụ thể, có id, vector embedding và payload dạng dữ liệu bổ sung. Segment dùng để tổ chức dữ liệu vector theo vòng đời lưu trữ và indexing.

Luồng Ghi Dữ Liệu

Khi ứng dụng gửi danh sách vector vào EzyVector, hệ thống sẽ:
  1. Kiểm tra collection đã tồn tại và đúng cấu hình vector.
  2. Lưu hoặc cập nhật point metadata trong MySQL.
  3. Ghi vector đã chuẩn hóa xuống file storage.
  4. Cập nhật chỉ mục HNSW nếu chỉ mục đã sẵn sàng.
  5. Lưu payload để kết quả tìm kiếm có thể trả về dữ liệu ngữ cảnh.
sequenceDiagram
    participant App as Ứng dụng
    participant API as EzyVector API
    participant Service as Vector Service
    participant DB as MySQL
    participant File as File Storage
    participant HNSW as HNSW Index

    App->>API: Upsert points
    API->>Service: Validate và chuyển request
    Service->>DB: Lưu metadata, payload, version
    Service->>File: Ghi vector vào segment file
    Service->>HNSW: Cập nhật index nếu sẵn sàng
    API-->>App: status = ok
Thiết kế này cho phép EzyVector giữ dữ liệu có thể truy vấn và quản trị trong MySQL, đồng thời tối ưu phần vector search bằng cơ chế lưu trữ riêng.

Luồng Tìm Kiếm

Khi nhận một vector truy vấn, EzyVector ưu tiên dùng HNSW index nếu chỉ mục đã sẵn sàng. HNSW giúp tìm kiếm gần đúng với tốc độ nhanh hơn trên tập dữ liệu lớn.
Nếu HNSW chưa được xây dựng xong hoặc chưa load được từ file, hệ thống vẫn có thể tìm kiếm bằng cách scan dữ liệu vector trong file storage. Điều này giúp tính năng tìm kiếm không bị gián đoạn trong lúc hệ thống đang backfill hoặc rebuild index.
flowchart TD
    A[Search request] --> B[Kiểm tra collection]
    B --> C[Khởi động backfill nếu cần]
    C --> D[Khởi động build HNSW nếu cần]
    D --> E{HNSW đã sẵn sàng?}

    E -->|Có| F[Search bằng HNSW]
    E -->|Không| G[Search tuần tự trên file storage]

    F --> H[Lấy metadata/payload từ MySQL]
    G --> H
    H --> I[Trả về id, score, payload]
Ở phiên bản hiện tại, EzyVector tập trung vào cosine similarity. Vector được chuẩn hóa trước khi lưu và khi tìm kiếm, giúp score phản ánh độ tương đồng giữa query vector và vector đã lưu.

HNSW Index

HNSW, viết tắt của Hierarchical Navigable Small World, là cấu trúc chỉ mục phổ biến cho bài toán approximate nearest neighbor search. EzyVector sử dụng HNSW để tăng tốc tìm kiếm vector khi số lượng point lớn.
Chỉ mục HNSW có thể được xây dựng ở nền. Sau khi build xong, index được lưu xuống file để những lần khởi động sau có thể load lại thay vì rebuild từ đầu. Nếu file index không khớp cấu hình vector size, hệ thống sẽ bỏ qua file đó và xây dựng lại.
Cách làm này tạo ra sự cân bằng giữa tốc độ, độ bền dữ liệu và khả năng phục hồi sau restart.

Backfill Dữ Liệu

Một điểm quan trọng của EzyVector là cơ chế backfill. Khi collection đã có dữ liệu trong MySQL nhưng vector file storage hoặc HNSW index chưa hoàn chỉnh, hệ thống có thể tự đọc lại các point theo từng lô và ghi xuống storage.
Backfill chạy ở nền, có lưu tiến độ, và không yêu cầu người vận hành phải thao tác thủ công. Điều này hữu ích khi bật index cho collection đã có dữ liệu, hoặc khi hệ thống cần phục hồi lại phần file storage/index từ nguồn dữ liệu trong MySQL.

Bảo Mật API

API vector collection được bảo vệ bằng API key. Client có thể gửi key qua query parameter, bearer token hoặc header x-api-key.
Ngoài API key, EzyVector còn hỗ trợ danh sách IP được phép truy cập. Danh sách này có thể chứa IP đơn lẻ, CIDR hoặc range IPv4. Nếu cấu hình allowlist IP, request từ IP không hợp lệ sẽ bị từ chối trước khi xử lý dữ liệu.

Quản Trị Trên EzyPlatform

EzyVector có admin plugin để quản trị ngay trong EzyPlatform. Người vận hành có thể theo dõi:
  • danh sách collection,
  • kích thước vector,
  • distance metric,
  • loại chỉ mục,
  • số lượng point,
  • danh sách point và payload,
  • danh sách segment,
  • trạng thái segment và phiên bản index.
Nhờ đó, EzyVector không chỉ là một API lưu trữ vector, mà còn có bề mặt vận hành rõ ràng cho website dùng EzyPlatform.

Trường Hợp Sử Dụng

EzyVector phù hợp cho các bài toán như:
  • tìm kiếm ngữ nghĩa trong bài viết, tài liệu, sản phẩm hoặc khóa học,
  • xây dựng hệ thống gợi ý nội dung,
  • lưu embedding cho chatbot hoặc trợ lý AI,
  • làm nền tảng retrieval cho RAG,
  • triển khai tính năng AI trực tiếp trong website mà không cần thêm dịch vụ vector database độc lập.

Kết Luận

EzyVector mang vector database vào trong EzyPlatform theo cách gọn nhẹ và thực dụng: MySQL giữ metadata và payload, filesystem giữ vector/index, HNSW tăng tốc tìm kiếm, admin plugin hỗ trợ vận hành, còn API được bảo vệ bằng key và allowlist IP.
Với thiết kế này, các website trên EzyPlatform có thể bắt đầu xây dựng tính năng AI native như semantic search, recommendation và RAG mà không phải vận hành thêm một hạ tầng vector database riêng.