@happ-integ/vector

Vector Store сервис с автоматическим fallback между провайдерами.

Установка

pnpm add @happ-integ/vector

Провайдеры

Провайдер	Описание
qdrant	Qdrant Vector Database
pinecone	Pinecone
weaviate	Weaviate

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

Базовое использование

import { VectorService } from "@happ-integ/vector";

const vector = new VectorService({
	primary: "qdrant",
	secondary: "pinecone", // fallback при ошибке
	qdrantUrl: env.QDRANT_URL,
	qdrantApiKey: env.QDRANT_API_KEY,
	qdrantCollection: "documents",
	pineconeApiKey: env.PINECONE_API_KEY,
	pineconeIndex: "my-index",
});

Upsert (добавление/обновление векторов)

await vector.upsert({
  vectors: [
    {
      id: "doc-1",
      values: [0.1, 0.2, ...], // embedding вектор
      metadata: {
        text: "Текст документа",
        source: "file.pdf",
      },
    },
    {
      id: "doc-2",
      values: [0.3, 0.4, ...],
      metadata: { text: "..." },
    },
  ],
});

Query (поиск похожих)

const results = await vector.query({
  vector: [0.1, 0.2, ...], // query embedding
  topK: 10,
  filter: {
    source: "file.pdf", // опционально
  },
});

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

Delete

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

// По фильтру
await vector.deleteByFilter({
	filter: {
		source: "old-file.pdf",
	},
});

Автоматический Fallback

При ошибке primary провайдера автоматически используется secondary:

const vector = new VectorService({
	primary: "qdrant",
	secondary: "pinecone",
	// ...
});

// Если Qdrant недоступен → автоматически Pinecone
const results = await vector.query({ vector, topK: 10 });

API

VectorService

new VectorService(config: IVectorServiceConfig)

Config:

Параметр	Тип	Описание
primary	"qdrant" | "pinecone" | "weaviate"	Primary провайдер
secondary	"qdrant" | "pinecone" | "weaviate"	Fallback (опционально)
qdrantUrl	string	Qdrant URL
qdrantApiKey	string	Qdrant API Key
qdrantCollection	string	Qdrant collection name
pineconeApiKey	string	Pinecone API Key
pineconeIndex	string	Pinecone index name
pineconeNamespace	string	Pinecone namespace (опционально)
weaviateUrl	string	Weaviate URL
weaviateApiKey	string	Weaviate API Key
weaviateClass	string	Weaviate class name

Методы

upsert(params): Promise<void>

interface IVectorUpsertParams {
	vectors: Array<{
		id: string;
		values: number[];
		metadata?: Record<string, any>;
	}>;
}

query(params): Promise<IVectorQueryResult[]>

interface IVectorQueryParams {
	vector: number[];
	topK: number;
	filter?: Record<string, any>;
}

interface IVectorQueryResult {
	id: string;
	score: number;
	metadata?: Record<string, any>;
}

deleteByIds(params): Promise<void>

interface IVectorDeleteParams {
	ids: string[];
}

deleteByFilter(params): Promise<void>

interface IVectorFilterParams {
	filter: Record<string, any>;
}

Прямой доступ к провайдерам

import { QdrantService, PineconeService, WeaviateService } from "@happ-integ/vector";

const qdrant = new QdrantService({
	url: "...",
	apiKey: "...",
	collectionName: "documents",
});