Integ Docs

Appearance

@happ-integ/qdrant ​

Клиент для Qdrant Vector Database.

Установка ​

bash
pnpm add @happ-integ/qdrant

Использование ​

Инициализация ​

typescript
import { QdrantClient } from "@happ-integ/qdrant";

const qdrant = new QdrantClient({
	url: "http://localhost:6333", // или облачный URL
	apiKey: env.QDRANT_API_KEY, // опционально
});

Создание коллекции ​

typescript
await qdrant.createCollection("documents");

Добавление векторов ​

typescript
// Один вектор
await qdrant.upsert({
  collectionName: "documents",
  vectors: [
    {
      id: "doc-1",
      vector: [0.1, 0.2, 0.3, ...], // embedding 1536 элементов
      payload: {
        text: "Текст документа",
        source: "file.pdf",
      },
    },
  ],
});

// Несколько векторов
await qdrant.upsert({
  collectionName: "documents",
  vectors: [
    { id: "doc-1", vector: [...], payload: {...} },
    { id: "doc-2", vector: [...], payload: {...} },
  ],
});

Поиск похожих ​

typescript
const results = await qdrant.search({
  collectionName: "documents",
  vector: [0.15, 0.25, ...], // query embedding
  limit: 10,
});

// results = [
//   { id: "doc-1", score: 0.95, payload: { text: "...", source: "..." } },
//   { id: "doc-2", score: 0.87, payload: { ... } },
// ]

Поиск с фильтром ​

typescript
const results = await qdrant.search({
  collectionName: "documents",
  vector: [...],
  limit: 10,
  filter: {
    must: [
      {
        key: "source",
        match: { value: "file.pdf" },
      },
    ],
  },
});

Удаление ​

typescript
// По ID
await qdrant.deleteByIds({
	collectionName: "documents",
	ids: ["doc-1", "doc-2"],
});

// По фильтру
await qdrant.deleteByFilter({
	collectionName: "documents",
	filter: {
		must: [
			{
				key: "source",
				match: { value: "old-file.pdf" },
			},
		],
	},
});

Health Check ​

typescript
const isHealthy = await qdrant.healthCheck();

API ​

QdrantClient ​

typescript
new QdrantClient(config: IQdrantConfig)

Config:

ПараметрТипОписание
urlstringQdrant URL (localhost или облако)
apiKeystringAPI Key (опционально)

Методы ​

createCollection(name): Promise<void> ​

Создать коллекцию.

upsert(params): Promise<void> ​

typescript
interface IQdrantUpsertParams {
	collectionName: string;
	vectors: Array<{
		id: string | number;
		vector: number[];
		payload?: Record<string, any>;
	}>;
}

search(params): Promise<IQdrantQueryResult[]> ​

typescript
interface IQdrantQueryParams {
	collectionName: string;
	vector: number[];
	limit?: number;
	filter?: any;
}

// результаты:
// [
//   { id: string, score: number, payload?: any },
// ]

deleteByIds(params): Promise<void> ​

deleteByFilter(params): Promise<void> ​

healthCheck(): Promise<boolean> ​

Локальная разработка ​

Запустить локально через Docker:

bash
docker run -p 6333:6333 qdrant/qdrant

Затем:

typescript
const qdrant = new QdrantClient({
	url: "http://localhost:6333",
});

Облачный Qdrant ​

  1. Регистрация: https://qdrant.io/cloud
  2. Создать кластер
  3. Скопировать URL и API Key
  4. Добавить в Doppler / env
typescript
const qdrant = new QdrantClient({
	url: env.QDRANT_URL,
	apiKey: env.QDRANT_API_KEY,
});

Когда использовать ​

  • ✅ Semantic search
  • ✅ RAG (Retrieval Augmented Generation)
  • ✅ Similarity matching
  • ✅ Продакшен (облачный вариант)
  • ❌ Простая搜索 — используйте полнотекстовый поиск БД