🧮Configuring your app

Deploying and Configuring Qyver Server

Application Structure and Configuration

The core logic of a Qyver-powered application resides in configuration files, where you define its structure and behavior using the Qyver framework.

By default, all examples in this documentation use an in-memory database, which is ideal for testing and prototyping. For guidance on integrating alternative vector databases, refer to the Vector Database Documentation.

Getting Started

• Begin with a basic example application here.

• Explore a real-world case study in the Amazon example.

• For advanced examples on embedding spaces and queries, check out the Qyver Notebooks.

---

Understanding the Application's Core Components

A functional Qyver application is structured around three key files:

index.py – Defines schemas, spaces, and indices. query.py – Specifies queries for searching and ranking results. api.py – Configures the executor, integrating all components.

---

1. Defining Schema, Spaces, and Index (index.py)

from qyver import framework as sl

class YourSchema(sl.Schema):
    id: sl.IdField
    attribute: sl.String

your_schema = YourSchema()

model_name = "<your model name>"  # Replace with a valid model!
text_space = sl.TextSimilaritySpace(text=your_schema.attribute, model=model_name)

index = sl.Index(text_space)

In this file:

• A schema is defined to structure input data.

• A space is created, mapping an attribute to an embedding model.

• An index is established to store and retrieve embeddings efficiently.

Modifications to this file (e.g., adding new spaces or altering the schema) require re-ingesting data, as previous vectors will no longer be valid.

---

2. Defining Queries (query.py)

from qyver import framework as sl
from .index import index, text_space, your_schema

query = (
    sl.Query(index)
    .find(your_schema)
    .similar(text_space.text, sl.Param("query_text"))
)

This file:

• Defines queries to search within the indexed data.

• Allows customization of weights, limits, radius, and other parameters.

---

3. Configuring API and Executor (api.py)

from qyver import framework as sl
from .index import index, your_schema
from .query import query

your_source: RestSource = sl.RestSource(your_schema)
your_query = sl.RestQuery(sl.RestDescriptor("query"), query)

executor = sl.RestExecutor(
    sources=[your_source],
    indices=[index],
    queries=[your_query],
    vector_database=sl.InMemoryVectorDatabase(),
)

sl.QyverRegistry.register(executor)

This file:

• Sets up data sources to handle incoming data.

• Registers queries as REST API endpoints (e.g., /api/v1/search/query).

• Defines the executor, which connects sources, indices, queries, and vector storage.

For detailed API documentation, check here.

---

Data Loading & Ingestion

Qyver supports loading data from local or remote files instead of requiring manual REST API ingestion.

1. Creating a Data Loader

config = sl.DataLoaderConfig(
    "https://path-to-your-file.csv", 
    DataFormat.CSV, 
    "name_of_your_loader",
    pandas_read_kwargs={"sep": ";"}
)

data_loader_source = sl.DataLoaderSource(your_schema, config)

executor = sl.RestExecutor(
    sources=[your_source, data_loader_source], 
    indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
)

2. Mapping Schema Fields to Columns

data_frame_parser = sl.DataFrameParser(
    your_schema, 
    mapping={your_schema.id: "id_field_name", your_schema.attribute: "custom_field_name"}
)

data_loader_source = sl.DataLoaderSource(your_schema, config, data_frame_parser)

3. Handling Large Datasets with Chunking

# For CSV
config = sl.DataLoaderConfig(
    "https://path-to-your-file.csv", 
    DataFormat.CSV, 
    pandas_read_kwargs={"chunksize": 10000}
)

# For JSONL
config = sl.DataLoaderConfig(
    "https://path-to-your-file.jsonl", 
    DataFormat.JSON, 
    pandas_read_kwargs={"lines": True, "chunksize": 10000}
)

Chunking is essential for efficient memory management when working with large datasets.

---

Customizing API Endpoints

By default, Qyver follows this API structure:

• Query Endpoint: /api/v1/search/<query_name>

• Data Ingestion Endpoint: /api/v1/ingest/<schema_name>

To customize API paths, modify the RestEndpointConfiguration:

rest_endpoint_config = sl.RestEndpointConfiguration(
    query_path_prefix="retrieve",
    ingest_path_prefix="insert",
    api_root_path="/qyver/v3",
)

executor = sl.RestExecutor(
    sources=[your_source],
    indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
    rest_endpoint_config=rest_endpoint_config
)

---

Using Recency Space

Limitations: 1. Recency embeddings are not periodically updated (coming soon!). 2. The server's startup timestamp is fixed at launch.

Workaround for Fixed Timestamps

NOW = int(datetime(year=2024, month=1, day=2, tzinfo=UTC).timestamp())
EXECUTOR_DATA = {CONTEXT_COMMON: {CONTEXT_COMMON_NOW: NOW}}

executor = sl.RestExecutor(
    sources=[source], indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
    context_data=EXECUTOR_DATA
)

Set the DISABLE_RECENCY_SPACE environment variable to false to enable it.

---

Optimizing Performance with GPU Acceleration

Qyver supports GPU acceleration for text and image embeddings, improving performance for large-scale processing.

Enable GPU Acceleration

Set the GPU_EMBEDDING_THRESHOLD environment variable:

export GPU_EMBEDDING_THRESHOLD=5000

• Default: 0 (Disabled)

• Valid range: 1-9999

• Behavior: If the batch size exceeds the threshold, GPU acceleration is activated.

Ensure:

• Your system has an NVIDIA GPU (best performance with PyTorch).

• GPU drivers are up to date.

---

Final Thoughts

Qyver simplifies modular, scalable AI-powered search applications, allowing flexibility in deployment with:

• Seamless integration with REST APIs & Vector Databases

• Efficient data ingestion via REST or file-based sources

• Advanced embedding techniques for structured + unstructured data

• Scalability optimizations, including GPU acceleration

Ready to build?