Quick Start

Quick Start#

This guide will help you get started with the vectorstore module in EvoFabric. You will learn how to set up, configure, and use a vector database to meet your application needs.

Prerequisite#

Before using the VectorStore module, please ensure you have:

  • Python 3.11 or later

  • Required dependencies:

    • chromadb>=1.1.0 (for ChromaDB backend)

Install#

Install required packages:

pip install chromadb>=1.1.0

If you plan to use a specific embedding model, please install the corresponding client:

# OpenAI embedding
pip install openai

# HuggingFace embedding
pip install transformers torch

Basic Settings#

Here are the methods for setting up basic vector storage:

from evofabric.core.vectorstore import ChromaDB
from evofabric.core.typing import DBItem
from evofabric.core.clients import OpenAIEmbedClient, SentenceTransformerEmbed

# Option 1: Use OpenAI embedding client
embed_client = OpenAIEmbedClient(
    api_key="your-api-key",
    model="text-embedding-ada-002"
)

# Option 2: Use local SentenceTransformer embedding (recommended for local development)
embed_client = SentenceTransformerEmbed(
    model="/path/to/sentence-transformer-model",  # e.g., "all-MiniLM-L6-v2"
    device="cpu"  # or "cuda" for GPU
)

# Option 3: Use a local model path
embed_client = SentenceTransformerEmbed(
    model="/path/to/sentence-transformers/all-MiniLM-L6-v2",
    device="cpu"
)

# Initialize the vector store
vector_store = ChromaDB(
    collection_name="my_documents",
    persist_directory="./chroma_db",
    embedding=embed_client,
    top_k=5
)

Add Document#

Add document to vector storage:

# Creating documents
documents = [
    DBItem(
        text="EvoFabric is an agent framework.",
        metadata={"category": "AI", "source": "evofabric_docs"}
    ),
    DBItem(
        text="Vector storage enables efficient similarity search",
        metadata={"category": "database", "source": "tech_docs"}
    ),
    DBItem(
        text="ChromaDB offers vector database solutions",
        metadata={"category": "database", "source": "chroma_docs"}
    )
]

# Add documents to vector storage
ids = await vector_store.add_texts(documents)
print(f"Documents updated: ID: {ids}")

Search Documents#

Perform similarity search:

# Search for similar documents
results = await vector_store.similarity_search("What is a vector database?")

for result in results:
    print(f"Score: {result.score}")
    print(f"Text: {result.text}")
    print(f"Metadata: {result.metadata}")
    print("-" * 50)

Complete Example#

Here is a complete working example using SentenceTransformer embeddings:

import asyncio
from evofabric.core.vectorstore import ChromaDB
from evofabric.core.typing import DBItem
from evofabric.core.clients import SentenceTransformerEmbed

async def main():
    # Initialize vector store with local SentenceTransformer embedding
    embed_client = SentenceTransformerEmbed(
        model="all-MiniLM-L6-v2",  # Can use model name or local path
        device="cpu"
    )

    vector_store = ChromaDB(
        collection_name="example_collection",
        persist_directory="./example_database",
        embedding=embed_client,
        top_k=3
    )

    # Add sample documents
    sample_docs = [
        DBItem(
            text="Python is a popular programming language",
            metadata={"language": "Python", "type": "programming"}
        ),
        DBItem(
            text="Machine learning enables computers to learn from data",
            metadata={"field": "ML", "type": "technology"}
        ),
        DBItem(
            text="Vector databases store data as high-dimensional vectors",
            metadata={"database": "vector", "type": "storage"}
        )
    ]

    # Add documents
    doc_ids = await vector_store.add_texts(sample_docs)
    print(f"Added {len(doc_ids)} documents")

    # Search for similar documents
    search_results = await vector_store.similarity_search("machine learning")
    print(f"\nFound {len(search_results)} similar documents:")

    for result in search_results:
        print(f"- {result.text}")
        print(f"  Metadata: {result.metadata}")

    # Get collection information
    info = vector_store.get_collection_info()
    print(f"\nCollection information: {info}")

# Run example
asyncio.run(main())

database management#

Clean up the database#

There are two ways to clean up the vector database:

  1. Clear all documents (recommended): Retain the collection structure, delete only the document content. Call method evofabric.core.vectorstore.VectorDB.clear_db()

Example usage:

# clear all documents and return deleted document number
deleted_count = await vector_store.clear_db()
print(f"Delete {deleted_count} documents")

Configuration Options#

VectorStore supports various configuration options:

  • collection_name: Collection Name (Required)

  • persist_directory: Persistent storage directory (optional). When not set, use in-memory mode; after setting, enable persistent storage

  • embedding: embedding client for text vectorization (required)

  • top_k: default number of results for similarity search

Embedded Client Options#

Embedding parameters accept any client inheriting from EmbedClientBase:

Embedded Adapter#

ChromaDB automatically provides embedding adapter functionality, which can convert custom embedding clients to the interface format expected by ChromaDB. Adapter support:

  • Single Text Embedding: Vectorization of a single text

  • Batch Embedding: Simultaneous vectorization of multiple texts

  • Compatibility: Fully compatible with ChromaDB’s standard interface

  1. SentenceTransformerEmbed local sentence transformer model

    • “model”: Model name (e.g., “all-MiniLM-L6-v2”) or local path

    • “device”: “cpu” or “cuda” for GPU acceleration

  2. OpenAIEmbedClient Embedding based on OpenAI API

    • model: OpenAI embedding model name

    • api_key: OpenAI API key

    • base_url: Custom API endpoint (optional)

Example configuration:

# Local SentenceTransformer with GPU
embed_client = SentenceTransformerEmbed(
    model="all-MiniLM-L6-v2",
    device="cuda"
)

# OpenAI with custom endpoint
embed_client = OpenAIEmbedClient(
    model="text-embedding-3-small",
    api_key="your-api-key",
    base_url="https://your-custom-endpoint/v1"
)

You can customize these options based on specific use cases, performance requirements, and available resources.

Contents