@ragfish/qdrant

Qdrant provider utilities for ragfish.

This package gives you:

• initQdrant() to initialize the shared Qdrant client
• QdrantRetriever (BaseRetriever implementation)
• ingest() to chunk, embed, and upsert text into a Qdrant collection
• chunkText() utility

Install

npm install ragfish @ragfish/qdrant

Quick Start

import { Settings } from 'ragfish';
import { OpenAIEmbedding } from '@ragfish/openai';
import { initQdrant, ingest, QdrantRetriever } from '@ragfish/qdrant';

Settings.embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'text-embedding-3-small',
});

initQdrant({
    url: process.env.QDRANT_URL!,
    apiKey: process.env.QDRANT_API_KEY, // optional
});

await ingest('docs-collection', {
    text: 'Your full document text here',
    payload: {
        documentId: 'doc-123',
        fileName: 'handbook.md',
    },
    chunkSize: 1000,   // optional, default 1000
    chunkOverlap: 200, // optional, default 200
});

const retriever = new QdrantRetriever({
    collectionName: 'docs-collection',
    topK: 5, // optional, default 5
});

const chunks = await retriever.run('refund policy');
console.log(chunks);

API

initQdrant

initQdrant({
  url: string,      // required
  apiKey?: string   // optional
}): void

Must be called before ingest() or QdrantRetriever.run().

ingest

ingest(collectionName: string, {
  text: string,                                     // required
  payload: Record<string, unknown>,                 // required metadata
  chunkSize?: number,                               // optional, default 1000
  chunkOverlap?: number                             // optional, default 200
}): Promise<string[]>

What ingest() does:

1. Splits text into chunks
2. Embeds each chunk using Settings.embedding
3. Upserts points into Qdrant
4. Merges your payload with chunk metadata:
   • text (chunk content)
   • chunkIndex (number)

Returns the created Qdrant point IDs.

QdrantRetriever

new QdrantRetriever({
  collectionName: string,                // required
  filters?: Record<string, unknown>,     // optional Qdrant filter
  topK?: number                          // optional, default 5
})

Implements BaseRetriever:

run(query: string): Promise<RetrievedChunk[]>

It embeds the query via Settings.embedding, runs Qdrant search, and returns:

• documentId
• fileName
• chunkIndex
• text
• score

chunkText

chunkText(text: string, chunkSize: number, chunkOverlap: number): string[]

Notes

• Set Settings.embedding before using ingest() or QdrantRetriever.
• Call initQdrant() once during app startup.
• Ensure your payload includes fields your application needs (for example documentId, fileName).

License

MIT