Vector Stores

Overview

Vector Stores in LlmTornado provide a powerful way to store and search through document embeddings for use with assistants and retrieval-augmented generation (RAG) applications. They enable semantic search capabilities, allowing assistants to find relevant information from large document collections efficiently.

Quick Start

using LlmTornado;
using LlmTornado.VectorStores;
using LlmTornado.Files;

TornadoApi api = new TornadoApi("your-api-key");

// Create a vector store
HttpCallResult<VectorStore> store = await api.VectorStores.Create(
    new CreateVectorStoreRequest
    {
        Name = "Knowledge Base"
    });

Console.WriteLine($"Vector store created: {store.Data.Id}");

Prerequisites

• The LlmTornado package installed
• A valid API key with vector store access
• Understanding of Embeddings
• Familiarity with Files and Assistants

Basic Usage

Create a Vector Store

HttpCallResult<VectorStore> createResult = await api.VectorStores.Create(
    new CreateVectorStoreRequest
    {
        Name = "Product Documentation",
        Metadata = new Dictionary<string, string>
        {
            {"category", "documentation"},
            {"version", "1.0"}
        }
    });

VectorStore vectorStore = createResult.Data;
Console.WriteLine($"Created: {vectorStore.Id}");

List Vector Stores

HttpCallResult<ListResponse<VectorStore>> listResult = 
    await api.VectorStores.List();

foreach (VectorStore store in listResult.Data.Items)
{
    Console.WriteLine($"{store.Id}: {store.Name} ({store.FileCounts.Total} files)");
}

Retrieve a Vector Store

HttpCallResult<VectorStore> retrieveResult = 
    await api.VectorStores.Retrieve("vector_store_id");

VectorStore store = retrieveResult.Data;
Console.WriteLine($"Name: {store.Name}");
Console.WriteLine($"Status: {store.Status}");
Console.WriteLine($"Files: {store.FileCounts.Total}");

Modify a Vector Store

HttpCallResult<VectorStore> modifyResult = await api.VectorStores.Modify(
    "vector_store_id",
    new VectorStoreModifyRequest
    {
        Name = "Updated Documentation",
        Metadata = new Dictionary<string, string>
        {
            {"version", "2.0"}
        }
    });

Delete a Vector Store

HttpCallResult<bool> deleteResult = 
    await api.VectorStores.Delete("vector_store_id");

Console.WriteLine($"Deleted: {deleteResult.Data}");

Working with Files

Add a File to Vector Store

// First, upload the file
HttpCallResult<TornadoFile> uploadResult = await api.Files.Upload(
    "document.pdf", 
    FilePurpose.Assistants);

// Then add it to the vector store
HttpCallResult<VectorStoreFile> addResult = await api.VectorStores.CreateFile(
    "vector_store_id",
    new CreateVectorStoreFileRequest
    {
        FileId = uploadResult.Data.Id
    });

Console.WriteLine($"File added: {addResult.Data.Id}");

Custom Chunking Strategy

Control how documents are split for embedding:

HttpCallResult<TornadoFile> file = await api.Files.Upload(
    "long_document.pdf", 
    FilePurpose.Assistants);

HttpCallResult<VectorStoreFile> result = await api.VectorStores.CreateFile(
    "vector_store_id",
    new CreateVectorStoreFileRequest
    {
        FileId = file.Data.Id,
        ChunkingStrategy = new StaticChunkingStrategy
        {
            Static = new StaticChunkingConfig
            {
                MaxChunkSizeTokens = 500,
                ChunkOverlapTokens = 100
            }
        }
    });

List Files in Vector Store

HttpCallResult<ListResponse<VectorStoreFile>> listResult = 
    await api.VectorStores.ListFiles("vector_store_id");

foreach (VectorStoreFile file in listResult.Data.Items)
{
    Console.WriteLine($"{file.Id}: Status = {file.Status}");
}

Retrieve File from Vector Store

HttpCallResult<VectorStoreFile> retrieveResult = 
    await api.VectorStores.RetrieveFiles("vector_store_id", "file_id");

VectorStoreFile file = retrieveResult.Data;
Console.WriteLine($"File status: {file.Status}");
Console.WriteLine($"Created: {file.CreatedAt}");

Delete File from Vector Store

HttpCallResult<bool> deleteResult = await api.VectorStores.DeleteFile(
    "vector_store_id", 
    "file_id");

Console.WriteLine($"File deleted: {deleteResult.Data}");

Advanced Usage

Create Vector Store with Files

Create and populate in one operation:

// Upload files first
List<string> fileIds = [];
string[] documents = ["doc1.pdf", "doc2.pdf", "doc3.pdf"];

foreach (string doc in documents)
{
    HttpCallResult<TornadoFile> uploaded = await api.Files.Upload(
        doc, 
        FilePurpose.Assistants);
    fileIds.Add(uploaded.Data.Id);
}

// Create vector store with files
HttpCallResult<VectorStore> result = await api.VectorStores.Create(
    new CreateVectorStoreRequest
    {
        Name = "Document Collection",
        FileIds = fileIds
    });

Using with Assistants

Attach vector store to assistant for file search:

// Create vector store
HttpCallResult<VectorStore> vectorStore = await api.VectorStores.Create(
    new CreateVectorStoreRequest { Name = "KB" });

// Add files to vector store
HttpCallResult<TornadoFile> file = await api.Files.Upload(
    "knowledge.pdf", 
    FilePurpose.Assistants);

await api.VectorStores.CreateFile(
    vectorStore.Data.Id,
    new CreateVectorStoreFileRequest { FileId = file.Data.Id });

// Create assistant with vector store
HttpCallResult<Assistant> assistant = await api.Assistants.CreateAssistantAsync(
    new CreateAssistantRequest(
        ChatModel.OpenAi.Gpt4.O241120,
        "Knowledge Assistant",
        "Answers from documents",
        "You search and answer from uploaded documents.")
    {
        Tools = new List<AssistantTool>
        {
            new AssistantToolFileSearch()
        },
        ToolResources = new ToolResources
        {
            FileSearch = new FileSearchToolResources
            {
                VectorStoreIds = new List<string> { vectorStore.Data.Id }
            }
        }
    });

Batch File Upload

Add multiple files efficiently:

HttpCallResult<VectorStoreFileBatch> batchResult = 
    await api.VectorStores.CreateFileBatch(
        "vector_store_id",
        new CreateVectorStoreFileBatchRequest
        {
            FileIds = new List<string> 
            { 
                "file_id_1", 
                "file_id_2", 
                "file_id_3" 
            }
        });

// Monitor batch status
while (batchResult.Data.Status == "in_progress")
{
    await Task.Delay(1000);
    batchResult = await api.VectorStores.RetrieveFileBatch(
        "vector_store_id", 
        batchResult.Data.Id);
}

Console.WriteLine($"Batch complete: {batchResult.Data.FileCounts.Completed} files");

Best Practices

1. Optimize Chunking - Balance chunk size for context vs granularity
2. Monitor Status - Check file processing status before use
3. Clean Up - Remove old files and stores regularly
4. Metadata Usage - Tag stores for organization
5. Batch Operations - Use batch uploads for multiple files

Common Issues

File Processing Failed

• Solution: Check file format and size limits
• Prevention: Validate files before upload

Slow Search Results

• Solution: Optimize chunk sizes and file count
• Prevention: Monitor store size and performance

Vector Store Full

• Solution: Delete old files or create new store
• Prevention: Implement file rotation policy

API Reference

VectorStore

• string Id - Unique identifier
• string Name - Store name
• string Status - Processing status
• FileCounts FileCounts - File statistics
• Dictionary<string, string> Metadata - Custom metadata

CreateVectorStoreRequest

• string Name - Store name
• List<string> FileIds - Initial files
• ExpiresAfter ExpiresAfter - Expiration policy
• Dictionary<string, string> Metadata - Custom metadata

VectorStoreFile

• string Id - File identifier
• string VectorStoreId - Parent store
• string Status - Processing status
• long CreatedAt - Addition timestamp

ChunkingStrategy

• StaticChunkingStrategy - Fixed chunk sizes
• AutoChunkingStrategy - Automatic optimization

Related Topics

• Embeddings - Understanding embeddings
• Assistants - Using with assistants
• Files - File management
• Vector Databases - External vector databases