Vector Operations Guide

This guide provides detailed information on using the vector storage and retrieval capabilities of the LLM Platform Model Context Protocol (LLM-MCP). Vector operations allow you to store, retrieve, and search high-dimensional vector embeddings, enabling semantic search, recommendation systems, and other AI-powered features.

Vector Storage Overview

LLM-MCP provides built-in vector database functionality with two storage options:

1. MongoDB with Vector Extensions: Uses MongoDB's vector search capabilities
2. Qdrant Integration: Uses the specialized Qdrant vector database

You can configure which vector storage backend to use in your LLM-MCP configuration.

Configuration

MongoDB Vector Storage Configuration

{
  "storage": {
    "type": "mongodb",
    "uri": "mongodb://localhost:27017/llm-mcp",
    "options": {
      "useNewUrlParser": true,
      "useUnifiedTopology": true
    },
    "vector": {
      "indexType": "hnsw",
      "dimensions": 1536,
      "similarity": "cosine"
    }
  }
}

Qdrant Vector Storage Configuration

{
  "storage": {
    "type": "qdrant",
    "uri": "http://localhost:6333",
    "apiKey": "your-api-key", // Optional
    "vector": {
      "dimensions": 1536,
      "similarity": "cosine"
    }
  }
}

Basic Vector Operations

Storing Vectors

You can store vectors with associated metadata using the storeVector method:

const [BfmcpClient] = require('@bluefly/llm-mcp/client');

// Initialize client
const client = new BfmcpClient({
  serverUrl: 'http://localhost:3001'
});

// Store a vector
await client.storeVector({
  // Required: Unique identifier for the vector
  id: "doc-123",
  
  // Required: The embedding vector array
  vector: [0.1, 0.2, 0.3, 0.4, /* ... more dimensions */],
  
  // Optional: Associated metadata
  metadata: {
    title: "Important Document",
    content: "This is an important document about artificial intelligence...",
    url: "https://example.com/docs/123",
    tags: ["ai", "machine-learning", "documentation"],
    timestamp: new Date().toISOString()
  },
  
  // Optional: Collection/namespace (defaults to "default")
  collection: "documents"
});

Retrieving Vectors by ID

To retrieve a specific vector by its ID:

// Get vector by ID
const vectorData = await client.getVector({
  id: "doc-123",
  collection: "documents" // Optional, defaults to "default"
});

console.log("Vector:", vectorData.vector);
console.log("Metadata:", vectorData.metadata);

Deleting Vectors

To delete vectors from storage:

// Delete a single vector
await client.deleteVector({
  id: "doc-123",
  collection: "documents" // Optional, defaults to "default"
});

// Delete multiple vectors
await client.deleteVectors({
  ids: ["doc-123", "doc-456", "doc-789"],
  collection: "documents" // Optional, defaults to "default"
});

Vector Search Operations

Finding Similar Vectors

The most common vector operation is finding vectors similar to a query vector:

// Find similar vectors to a query vector
const results = await client.findSimilarVectors({
  // Required: Query vector
  vector: [0.15, 0.22, 0.28, 0.35, /* ... more dimensions */],
  
  // Optional: Collection/namespace (defaults to "default")
  collection: "documents",
  
  // Optional: Number of results to return (defaults to 10)
  limit: 5,
  
  // Optional: Minimum similarity score (0-1, defaults to 0.7)
  scoreThreshold: 0.75,
  
  // Optional: Filter based on metadata
  filter: {
    tags: { $in: ["ai", "machine-learning"] },
    timestamp: { $gt: "2023-01-01T00:00:00Z" }
  },
  
  // Optional: Include vectors in response (defaults to false)
  includeVectors: false,
  
  // Optional: Include metadata in response (defaults to true)
  includeMetadata: true
});

// Process results
results.forEach(result => {
  console.log(`ID: [result.id], Score: [result.score]`);
  console.log("Metadata:", result.metadata);
  // result.vector is also available if includeVectors: true
});

Advanced Vector Filtering

You can use complex filters to narrow your vector search:

// Find vectors with complex filtering
const results = await client.findSimilarVectors({
  vector: queryVector,
  filter: {
    // Filter on multiple metadata fields
    $and: [
      { tags: { $in: ["ai", "nlp"] } },
      { timestamp: { $gte: "2023-01-01T00:00:00Z" } },
      { timestamp: { $lte: "2023-12-31T23:59:59Z" } },
      { "user.role": "admin" }
    ]
  },
  limit: 20
});

Batch Operations

For improved performance with multiple vectors, use batch operations:

Batch Vector Storage

// Store multiple vectors in one operation
await client.storeVectors({
  vectors: [
    {
      id: "doc-123",
      vector: [/* vector 1 */],
      metadata: { title: "Document 1" }
    },
    {
      id: "doc-456",
      vector: [/* vector 2 */],
      metadata: { title: "Document 2" }
    },
    {
      id: "doc-789",
      vector: [/* vector 3 */],
      metadata: { title: "Document 3" }
    }
  ],
  collection: "documents" // Optional, defaults to "default"
});

Batch Vector Retrieval

// Get multiple vectors by IDs
const vectorsData = await client.getVectors({
  ids: ["doc-123", "doc-456", "doc-789"],
  collection: "documents" // Optional, defaults to "default"
});

vectorsData.forEach(data => {
  console.log(`ID: [data.id]`);
  console.log("Metadata:", data.metadata);
  console.log("Vector dimensions:", data.vector.length);
});

Collection Management

LLM-MCP provides methods to manage vector collections:

Creating Collections

// Create a new vector collection
await client.createVectorCollection({
  name: "product_embeddings",
  dimensions: 1536,
  similarity: "cosine", // or "euclidean", "dot"
  indexType: "hnsw", // Optional, defaults to "hnsw"
  indexParams: { // Optional, advanced index parameters
    m: 16,
    efConstruction: 100
  }
});

Listing Collections

// List all vector collections
const collections = await client.listVectorCollections();
collections.forEach(collection => {
  console.log(`Collection: [collection.name]`);
  console.log(`Vector dimensions: [collection.dimensions]`);
  console.log(`Vector count: [collection.count]`);
});

Deleting Collections

// Delete a vector collection
await client.deleteVectorCollection({
  name: "product_embeddings"
});

Integration with AI Models

Vector operations are often used with AI models for generating embeddings:

const [BfmcpClient] = require('@bluefly/llm-mcp/client');
const [BfllmClient] = require('@bluefly/bfllm');

// Initialize clients
const mcpClient = new BfmcpClient({ serverUrl: 'http://localhost:3001' });
const llmClient = new BfllmClient({ serverUrl: 'http://localhost:3002' });

// Generate embedding using BFLLM
const text = "This is a sample document about artificial intelligence.";
const embedding = await llmClient.generateEmbedding({
  model: "text-embedding-ada-002",
  text: text
});

// Store in LLM-MCP vector database
await mcpClient.storeVector({
  id: `doc-[Date.now()]`,
  vector: embedding.data[0].embedding,
  metadata: {
    text: text,
    timestamp: new Date().toISOString()
  },
  collection: "semantic_search"
});

Semantic Search Implementation

Here's a complete example of implementing semantic search:

// Step 1: Initialize clients
const mcpClient = new BfmcpClient({ serverUrl: 'http://localhost:3001' });
const llmClient = new BfllmClient({ serverUrl: 'http://localhost:3002' });

// Step 2: Define a function to generate embeddings
async function generateEmbedding(text) {
  const response = await llmClient.generateEmbedding({
    model: "text-embedding-ada-002",
    text: text
  });
  return response.data[0].embedding;
}

// Step 3: Create a semantic search function
async function semanticSearch(query, limit = 5) {
  // Generate embedding for the query
  const queryEmbedding = await generateEmbedding(query);
  
  // Search for similar vectors
  const results = await mcpClient.findSimilarVectors({
    vector: queryEmbedding,
    collection: "knowledge_base",
    limit: limit,
    includeMetadata: true
  });
  
  // Return formatted results
  return results.map(result => ({
    id: result.id,
    text: result.metadata.text,
    title: result.metadata.title,
    url: result.metadata.url,
    similarity: result.score
  }));
}

// Step 4: Use the semantic search
const searchResults = await semanticSearch("How does artificial intelligence work?");
console.log("Search results:", searchResults);

Advanced Topics

Vector Namespace Management

For multi-tenant applications, you can use different collections:

// Create vectors for different customers
await client.storeVector({
  id: "doc-123",
  vector: [/* vector */],
  metadata: { customer: "customer1" },
  collection: "customer1_documents"
});

// Search within a specific customer's collection
const results = await client.findSimilarVectors({
  vector: queryVector,
  collection: "customer1_documents"
});

Vector Upsert Operations

To update or insert vectors:

// Update if exists, insert if not
await client.upsertVector({
  id: "doc-123",
  vector: [/* updated vector */],
  metadata: { 
    title: "Updated Document",
    version: 2
  },
  collection: "documents"
});

Vector Metadata Updates

Update just the metadata without changing the vector:

// Update metadata only
await client.updateVectorMetadata({
  id: "doc-123",
  metadata: {
    views: 100,
    lastAccessed: new Date().toISOString()
  },
  collection: "documents"
});

Hybrid Search

Combine vector similarity search with traditional text search:

// Hybrid search using both vector similarity and keyword matching
const results = await client.hybridSearch({
  // Vector query component
  vector: queryVector,
  
  // Text query component
  text: "artificial intelligence applications",
  
  // Fields to search in for text
  fields: ["title", "content"],
  
  // Weights for vector vs text search (defaults to 0.5 each)
  weights: {
    vector: 0.7,
    text: 0.3
  },
  
  // Standard options
  collection: "documents",
  limit: 10
});

Performance Optimization

Index Optimization

For large vector collections, properly configuring indexes is crucial:

// Create a collection with optimized index parameters
await client.createVectorCollection({
  name: "optimized_vectors",
  dimensions: 1536,
  similarity: "cosine",
  indexType: "hnsw",
  indexParams: {
    m: 16,             // Connections per node (higher = more accurate but slower)
    efConstruction: 200, // Construction time quality (higher = better index but slower build)
    efRuntime: 50      // Query time quality (higher = more accurate but slower queries)
  }
});

Payload Optimization

Limit metadata size for better performance:

// Best practice: Keep metadata compact
await client.storeVector({
  id: "doc-123",
  vector: [/* vector */],
  metadata: {
    // Store minimal data needed for filtering/display
    title: "Document Title",
    summary: "Brief summary...", // Not the full content
    tags: ["tag1", "tag2"],
    // Store external reference instead of full content
    contentRef: "s3://bucket/doc-123.txt"
  }
});

Monitoring and Metrics

LLM-MCP provides vector operation metrics:

// Get vector storage metrics
const metrics = await client.getVectorMetrics();

console.log("Vector counts by collection:");
console.log(metrics.counts);

console.log("Vector storage size:");
console.log(metrics.storageSize);

console.log("Index performance metrics:");
console.log(metrics.performance);

Troubleshooting

Common Vector Operation Issues

1. Dimension Mismatch

   Problem: Vector dimensions don't match collection configuration

   Solution: Ensure all vectors match the configured dimensions:

   // Check collection configuration
   const collections = await client.listVectorCollections();
   const targetCollection = collections.find(c => c.name === "your_collection");
   console.log(`Required dimensions: [targetCollection.dimensions]`);

2. Low Similarity Scores

   Problem: Similar content returns low similarity scores

   Solution: Check embedding model and similarity metric:

   // Test with different similarity metrics
   await client.createVectorCollection({
     name: "test_cosine",
     dimensions: 1536,
     similarity: "cosine"
   });
   
   await client.createVectorCollection({
     name: "test_dot",
     dimensions: 1536,
     similarity: "dot"
   });
   
   // Compare results with the same vectors

3. Slow Query Performance

   Problem: Vector searches are too slow

   Solution: Optimize index parameters and limit result count:

   // Reduce the number of results
   const results = await client.findSimilarVectors({
     vector: queryVector,
     limit: 10, // Lower value = faster queries
     scoreThreshold: 0.8 // Higher threshold = fewer results to process
   });

Conclusion

LLM-MCP's vector operations provide a powerful foundation for building AI-powered applications with semantic search, recommendation systems, and other vector-based features. The flexibility to use either MongoDB or Qdrant as the backend allows for optimizing performance and cost based on your specific requirements.

For more information:

• See the API Reference for detailed endpoint documentation
• Review the Architecture Overview for system design
• Check the Configuration Guide for storage configuration options

For troubleshooting vector storage issues, refer to our Troubleshooting Guide.