ydb-qdrant 2.2.0 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +54 -3
  2. package/package.json +6 -2
package/README.md CHANGED
@@ -1,7 +1,11 @@
1
1
  <img src="https://ydb-qdrant.tech/logo.svg" alt="YDB Qdrant logo" height="56">
2
2
 
3
- [![CI](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-ydb-qdrant.yml/badge.svg)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-ydb-qdrant.yml)
3
+ [![Build](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-build.yml?branch=main&label=build)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-build.yml)
4
+ [![Tests](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-tests.yml?branch=main&label=tests)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-tests.yml)
5
+ [![Integration Tests](https://img.shields.io/github/actions/workflow/status/astandrik/ydb-qdrant/ci-integration.yml?branch=main&label=integration%20tests)](https://github.com/astandrik/ydb-qdrant/actions/workflows/ci-integration.yml)
6
+ [![Coverage](https://coveralls.io/repos/github/astandrik/ydb-qdrant/badge.svg?branch=main)](https://coveralls.io/github/astandrik/ydb-qdrant?branch=main)
4
7
  [![npm version](https://img.shields.io/npm/v/ydb-qdrant.svg)](https://www.npmjs.com/package/ydb-qdrant)
8
+ [![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fastandrik%2Fydb--qdrant-blue?logo=docker)](https://github.com/users/astandrik/packages/container/package/ydb-qdrant)
5
9
  [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
6
10
 
7
11
  # YDB Qdrant-compatible Service
@@ -163,6 +167,53 @@ export async function searchDocuments(collection: string, queryEmbedding: number
163
167
 
164
168
  This pattern avoids running a separate HTTP service: vector search is executed directly against YDB via the shared `createYdbQdrantClient` instance, while the rest of your code works with plain TypeScript functions.
165
169
 
170
+ ## Recommended Vector Dimensions
171
+
172
+ When creating a collection, you must specify the vector `size` matching your embedding model. Below are popular models with their dimensions and typical use cases:
173
+
174
+ ### Commercial API Models
175
+
176
+ | Provider | Model | Dimensions | Use Cases |
177
+ |----------|-------|------------|-----------|
178
+ | **OpenAI** | `text-embedding-3-small` | 1536 (default, can reduce to 256-1536) | RAG, semantic search, general-purpose embeddings |
179
+ | **OpenAI** | `text-embedding-3-large` | 3072 (default, can reduce to 256, 512, 1024, 1536, 3072) | High-accuracy RAG, multilingual tasks |
180
+ | **OpenAI** | `text-embedding-ada-002` | 1536 | Legacy model, widely adopted |
181
+ | **OpenAI** (Legacy) | `text-search-curie-doc-001` | 4096 | Legacy GPT-3 model, deprecated |
182
+ | **OpenAI** (Legacy) | `text-search-davinci-doc-001` | 12288 | Legacy GPT-3 model, deprecated |
183
+ | **Cohere** | `embed-v4.0` | 256, 512, 1024, 1536 (default) | Multimodal (text + image), RAG, enterprise search |
184
+ | **Cohere** | `embed-english-v3.0` | 1024 | English text, semantic search, classification |
185
+ | **Cohere** | `embed-multilingual-v3.0` | 1024 | 100+ languages, long-document retrieval, clustering |
186
+ | **Google** | `gemini-embedding-001` | 3072 (configurable) | Multilingual, general-purpose, RAG |
187
+ | **Google** | `text-embedding-004` | 768 | General-purpose text embeddings |
188
+ | **Google** | `text-embedding-005` | 768 | Improved version of text-embedding-004 |
189
+ | **Google** | `text-multilingual-embedding-002` | 768 | Multilingual text embeddings |
190
+
191
+ ### Open-Source Models (HuggingFace)
192
+
193
+ | Model | Dimensions | Use Cases |
194
+ |-------|------------|-----------|
195
+ | `sentence-transformers/all-MiniLM-L6-v2` | 384 | Fast semantic search, low-resource environments |
196
+ | `BAAI/bge-base-en-v1.5` | 768 | RAG, retrieval, English text |
197
+ | `BAAI/bge-large-en-v1.5` | 1024 | High-accuracy RAG, English text |
198
+ | `BAAI/bge-m3` | 1024 | Multilingual, dense/sparse/multi-vector |
199
+ | `intfloat/e5-base-v2` | 768 | General retrieval, English text |
200
+ | `intfloat/e5-large-v2` | 1024 | High-accuracy retrieval, English text |
201
+ | `intfloat/e5-mistral-7b-instruct` | 4096 | High-dimensional embeddings, advanced RAG |
202
+ | `nomic-ai/nomic-embed-text-v1` | 768 | General-purpose, open weights |
203
+
204
+ ### Choosing Dimensions
205
+
206
+ - **Higher dimensions (1024-4096)**: Better semantic fidelity, higher storage/compute costs
207
+ - **Lower dimensions (384-768)**: Faster queries, lower costs, suitable for many use cases
208
+ - **Variable dimensions**: Some models (OpenAI v3, Cohere v4) allow dimension reduction with minimal accuracy loss
209
+ - **Legacy models**: Older OpenAI GPT-3 models (Curie: 4096, Davinci: 12288) are deprecated but may still be in use
210
+
211
+ **References:**
212
+ - [OpenAI Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)
213
+ - [Cohere Embed Models](https://docs.cohere.com/docs/cohere-embed)
214
+ - [Google Gemini Embeddings](https://ai.google.dev/gemini-api/docs/embeddings)
215
+ - [HuggingFace Sentence Transformers](https://huggingface.co/sentence-transformers)
216
+
166
217
  ## Quick Start
167
218
 
168
219
  ### Use with IDE agents (Roo Code, Cline)
@@ -293,8 +344,8 @@ LOG_LEVEL=info
293
344
  - **Updating to a newer image with Compose** (no rebuild):
294
345
  - Pull the latest tag and restart the service:
295
346
  ```bash
296
- docker compose pull ydb-qdrant # or: docker-compose pull ydb-qdrant
297
- docker compose up -d ydb-qdrant # or: docker-compose up -d ydb-qdrant
347
+ docker-compose pull ydb-qdrant
348
+ docker-compose up -d ydb-qdrant
298
349
  ```
299
350
 
300
351
  - **Environment**: uses the same variables as documented in **Configure credentials** (`YDB_ENDPOINT`, `YDB_DATABASE`, one of the `YDB_*_CREDENTIALS` options, optional `PORT`/`LOG_LEVEL`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ydb-qdrant",
3
- "version": "2.2.0",
3
+ "version": "2.2.2",
4
4
  "main": "dist/package/Api.js",
5
5
  "types": "dist/package/Api.d.ts",
6
6
  "exports": {
@@ -14,7 +14,9 @@
14
14
  "logo.svg"
15
15
  ],
16
16
  "scripts": {
17
- "test": "vitest run",
17
+ "test": "vitest run --exclude \"test/integration/**\"",
18
+ "test:coverage": "vitest run --coverage --exclude \"test/integration/**\"",
19
+ "test:integration": "vitest run test/integration/YdbRealIntegration.test.ts",
18
20
  "build": "tsc -p tsconfig.json",
19
21
  "typecheck": "tsc -p tsconfig.json --noEmit",
20
22
  "dev": "tsx watch src/index.ts",
@@ -52,6 +54,7 @@
52
54
  "dependencies": {
53
55
  "@bufbuild/protobuf": "^2.10.0",
54
56
  "@grpc/grpc-js": "^1.14.0",
57
+ "@yandex-cloud/nodejs-sdk": "^2.9.0",
55
58
  "@ydbjs/api": "^6.0.4",
56
59
  "@ydbjs/core": "^6.0.4",
57
60
  "@ydbjs/query": "^6.0.4",
@@ -67,6 +70,7 @@
67
70
  "@eslint/js": "^9.39.1",
68
71
  "@types/express": "^5.0.3",
69
72
  "@types/node": "^24.9.1",
73
+ "@vitest/coverage-v8": "^4.0.12",
70
74
  "docsify-cli": "^4.4.4",
71
75
  "eslint": "^9.39.1",
72
76
  "husky": "^9.1.7",