@reaatech/llm-cache-adapters-qdrant

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Qdrant vector database adapter for llm-cache semantic search. Implements VectorStorageAdapter with HNSW approximate nearest neighbor search, metadata filtering, and deterministic UUID-based point IDs for keyspace isolation.

Installation

npm install @reaatech/llm-cache-adapters-qdrant
# or
pnpm add @reaatech/llm-cache-adapters-qdrant

Feature Overview

• HNSW search — low-latency cosine similarity search via Qdrant’s approximate nearest neighbor engine
• Auto-provisioning — connect() creates the collection and five payload indexes on first run
• Metadata filtering — findSimilar filters by useCase, modelVersion, generationConfigHash, and embeddingModel
• Deterministic point IDs — UUID v5 from cache keys for stable point identity across processes
• Paginated invalidation — invalidateByCriteria scrolls with configurable page size, deletes in batches
• Hybrid search — vector similarity combined with filter conditions in a single Qdrant query

Quick Start

import { CacheEngine, InMemoryAdapter, OpenAIEmbedder } from "@reaatech/llm-cache";
import { QdrantAdapter } from "@reaatech/llm-cache-adapters-qdrant";
 
const vectorStorage = new QdrantAdapter({
  url: "http://localhost:6333",
  collectionName: "llm-cache",
  vectorSize: 1536,
});
await vectorStorage.connect();
 
const cache = new CacheEngine({
  storage: new InMemoryAdapter(), // or RedisAdapter / DynamoDBAdapter
  vectorStorage,
  embedder: new OpenAIEmbedder({
    provider: "openai",
    model: "text-embedding-3-small",
    dimensions: 1536,
    apiKey: process.env.OPENAI_API_KEY,
  }),
  config: { /* ... */ },
});

API Reference

QdrantAdapter (class)

Implements VectorStorageAdapter from @reaatech/llm-cache.

import { QdrantAdapter } from "@reaatech/llm-cache-adapters-qdrant";
 
const adapter = new QdrantAdapter({
  url: "http://localhost:6333",
  collectionName: "llm-cache",
  vectorSize: 1536,
});
await adapter.connect();

QdrantAdapterConfig

Methods

VectorSearchFilters

Pass to findSimilar() to narrow semantic search results:

Usage Patterns

Semantic Search with Filters

const results = await adapter.findSimilar(
  embedding,           // query vector
  0.8,                 // cosine similarity threshold
  {
    useCase: "qa",
    modelVersion: "gpt-4-0613",
  },
  10                   // max results
);
 
for (const { entry, similarity } of results) {
  console.log(`Match (${similarity.toFixed(3)}): ${entry.prompt}`);
}

API Key Authentication

const adapter = new QdrantAdapter({
  url: "https://qdrant.example.com",
  collectionName: "llm-cache",
  vectorSize: 1536,
  apiKey: process.env.QDRANT_API_KEY,
});

Custom Distance Metric

const adapter = new QdrantAdapter({
  url: "http://localhost:6333",
  collectionName: "llm-cache",
  vectorSize: 1536,
  distance: "Dot", // Cosine | Euclid | Dot
});

Periodic Cleanup

The adapter does not auto-evict expired points. Schedule cleanup:

const removed = await adapter.invalidateByCriteria({
  olderThan: new Date(Date.now() - 24 * 3600_000), // older than 24 hours
});
console.log(`Cleaned ${removed} expired points`);

Notes

• Auto-created payload indexes: useCase, modelVersion, generationConfigHash, embeddingModel, createdAtMs.
• invalidateByCriteria refuses to delete the entire collection — at least one criterion must be specified.
• Point IDs are deterministic UUID v5 from cache keys using a stable namespace UUID. The same key always maps to the same point.
• Metadata queries (findByUseCase, findByModelVersion) use scroll with payload decoding and expiry filtering.

Related Packages

• @reaatech/llm-cache — Core caching engine and types
• @reaatech/llm-cache-adapters-redis — Redis storage adapter (exact-match metadata)

License

MIT