# Бази даних векторів, що самовідтворюються з Qdrant: Глибокий розрив # Вступ **сягаючи до фінішу РАГ:** У цій статті передбачено глибоке занурення у Qdrant, у векторну базу даних, що використовується у: - [Частина 4: Реалізація ONNX і Qdrant](/blog/semantic-search-with-onnx-and-qdrant) - Побудова семантичних пошуків - [Частина 5: Гібридний пошук і автоматичне інексування](/blog/rag-hybrid-search-and-indexing) - Інтеграція з виробництвом [Qdrant](https://qdrant.tech/) (pronected "quadrant") - це база даних з відкритим кодом, вбудована у Rast. У цій статті містяться ключові концепції, клієнт C#, налаштування швидкодії та шаблони виробництва. [TOC] # Що таке "Крант"? А [база даних векторів](https://qdrant.tech/documentation/overview/) зберігає високовимірні вектори (ембарди) і вмикає швидкий пошук подібності. На відміну від традиційних баз даних, які знаходять точний збіг, Qdrant знаходить *семантично подібна* речі. ```mermaid flowchart LR A[Text: 'Docker deployment'] --> B[Embedding Model] B --> C["Vector: [0.12, -0.34, 0.56, ...]"] C --> D[Qdrant] E[Query: 'container setup'] --> F[Embedding Model] F --> G["Vector: [0.11, -0.32, 0.58, ...]"] G --> H[Similarity Search] D --> H H --> I[Similar Results] style B stroke:#6366f1,stroke-width:3px style D stroke:#ef4444,stroke-width:3px style F stroke:#6366f1,stroke-width:3px style H stroke:#10b981,stroke-width:2px ``` **Можливості ключа Qdrant:** - [Індексування HNSW](https://qdrant.tech/documentation/concepts/indexing/) - Підлінійний час пошуку - [Фільтрування](https://qdrant.tech/documentation/concepts/filtering/) - Об' єднати пошук подібності з фільтрами метаданих - [gRPC і REST API](https://qdrant.tech/documentation/interfaces/) - Високоефективний доступ - [Розподілити](https://qdrant.tech/documentation/guides/distributed_deployment/) - Зміна масштабу горизонтально - [Знімки](https://qdrant.tech/documentation/concepts/snapshots/) - Резервування і відновлення # Основні концепції ## Збірки А [збірка](https://qdrant.tech/documentation/concepts/collections/) вона тримає вектори з фіксованим виміром та виміром відстані. ```mermaid flowchart TB subgraph Collection["Collection: blog_posts"] A[Vector Size: 384] B[Distance: Cosine] C[HNSW Index] end subgraph Points D[Point 1: slug=docker-intro] E[Point 2: slug=kubernetes-basics] F[Point N...] end Collection --> Points style A stroke:#6366f1,stroke-width:2px style B stroke:#6366f1,stroke-width:2px style C stroke:#f59e0b,stroke-width:2px style D stroke:#10b981,stroke-width:2px style E stroke:#10b981,stroke-width:2px ``` ```csharp // Create collection - see https://qdrant.tech/documentation/concepts/collections/#create-a-collection await client.CreateCollectionAsync( collectionName: "blog_posts", vectorsConfig: new VectorParams { Size = 384, // Must match your embedding model Distance = Distance.Cosine // Best for text embeddings } ); ``` **Межі відстані** ([docs](https://qdrant.tech/documentation/concepts/collections/#distance-metrics)): - **КосинName** - Вимірює кут між векторами (найкраще для тексту) - **Крапка** - Необроблений внутрішній продукт (для попередньо нормалізованих векторів) - **Евклід** - Геометрична відстань (для просторових даних) ## Точки А [точка](https://qdrant.tech/documentation/concepts/points/) є одним записом, що містить: ```mermaid flowchart LR subgraph Point A[ID: uuid/int] B["Vector: float[384]"] C[Payload: JSON metadata] end style A stroke:#8b5cf6,stroke-width:2px style B stroke:#f59e0b,stroke-width:2px style C stroke:#10b981,stroke-width:2px ``` ```csharp // Upsert points - see https://qdrant.tech/documentation/concepts/points/#upload-points var point = new PointStruct { Id = new PointId { Uuid = Guid.NewGuid().ToString() }, Vectors = embedding, // float[384] Payload = { ["slug"] = "my-post", ["title"] = "Vector Databases", ["language"] = "en", ["categories"] = new[] { "AI", "Databases" }, ["published"] = DateTimeOffset.UtcNow.ToUnixTimeSeconds() } }; await client.UpsertAsync("blog_posts", points: new[] { point }); ``` ## Фільтрування [Фільтрування](https://qdrant.tech/documentation/concepts/filtering/) Виконати *до* пошук подібності - надзвичайно ефективний. ```mermaid flowchart TB A[Search Query] --> B{Apply Filters First} B --> C[Language = 'en'] B --> D[Year >= 2024] C --> E[Filtered Subset] D --> E E --> F[Vector Similarity Search] F --> G[Ranked Results] style B stroke:#ec4899,stroke-width:3px style E stroke:#f59e0b,stroke-width:2px style F stroke:#6366f1,stroke-width:2px style G stroke:#10b981,stroke-width:2px ``` ```csharp // Filter conditions - see https://qdrant.tech/documentation/concepts/filtering/#filtering-conditions var filter = new Filter { Must = // AND conditions { new Condition { Field = new FieldCondition { Key = "language", Match = new Match { Keyword = "en" } }}, new Condition { Field = new FieldCondition { Key = "published", Range = new Range { Gte = 1704067200 } // 2024-01-01 }} }, MustNot = // Exclude conditions { new Condition { Field = new FieldCondition { Key = "slug", Match = new Match { Keyword = "draft-post" } }} } }; ``` **Типи фільтрів** ([docs](https://qdrant.tech/documentation/concepts/filtering/#match)): - `Match.Keyword` - Точний збіг рядка - `Match.Text` - Повнотекстовий збіг - `Match.Any` - Має збігатися з будь- яким масивом - `Range` - Числові діапазони (Gte, Lte, Gt, Lt) - `GeoBoundingBox` / `GeoRadius` - Фільтрування Geo # Клієнт C# Встановити офіційну [Qdrant.Client](https://www.nuget.org/packages/Qdrant.Client) пакунок ([GitHub](https://github.com/qdrant/qdrant-dotnet)): ```bash dotnet add package Qdrant.Client ``` ## Налаштування з' єднання ```csharp using Qdrant.Client; using Qdrant.Client.Grpc; // gRPC client (recommended) - see https://qdrant.tech/documentation/interfaces/#grpc-interface var client = new QdrantClient( host: "localhost", port: 6334, // gRPC port (6333 is REST) https: false ); // With API key - see https://qdrant.tech/documentation/guides/security/ var secureClient = new QdrantClient( host: "your-qdrant.cloud", port: 6334, https: true, apiKey: "your-api-key" ); ``` > **Завжди використовувати gRPC** (порт 6334) для виробництва - 3-5x швидше, ніж REST. ## Виправлення HTTP/ 2 для Windows На Windows, увімкнути незашифрований HTTP/ 2 **до** Створення клієнта: ```csharp AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true); ``` ## Дії з ключами ### Пошук ```csharp // Vector search - see https://qdrant.tech/documentation/concepts/search/ var results = await client.SearchAsync( collectionName: "blog_posts", vector: queryEmbedding, limit: 10, filter: filter, scoreThreshold: 0.5f, // Minimum similarity searchParams: new SearchParams { HnswEf = 128, // Search accuracy (higher = better recall) Exact = false // Use approximate search }, withPayload: true ); foreach (var result in results) { Console.WriteLine($"{result.Payload["title"].StringValue}: {result.Score}"); } ``` ### Пакетна Upsert ```csharp // Batch operations - see https://qdrant.tech/documentation/concepts/points/#batch-update var points = documents.Select(doc => new PointStruct { Id = new PointId { Uuid = doc.Id }, Vectors = doc.Embedding, Payload = { ["slug"] = doc.Slug, ["title"] = doc.Title } }).ToList(); await client.UpsertAsync( collectionName: "blog_posts", points: points, wait: true // Wait for indexing ); ``` ### Вилучити ```csharp // Delete by filter - see https://qdrant.tech/documentation/concepts/points/#delete-points await client.DeleteAsync( collectionName: "blog_posts", filter: new Filter { Must = { new Condition { Field = new FieldCondition { Key = "slug", Match = new Match { Keyword = "old-post" } }}} } ); ``` # Налаштовування індексу HNSW [HNSW](https://qdrant.tech/documentation/concepts/indexing/#vector-index) (Герархічний Нев'янучий Малий Світ) є індексним алгоритмом КДранта. ```mermaid flowchart TB subgraph "HNSW Graph Layers" L2[Layer 2 - Sparse] L1[Layer 1 - Medium] L0[Layer 0 - Dense] end Q[Query] --> L2 L2 --> L1 L1 --> L0 L0 --> R[Nearest Neighbors] style L2 stroke:#8b5cf6,stroke-width:2px style L1 stroke:#6366f1,stroke-width:2px style L0 stroke:#3b82f6,stroke-width:2px style Q stroke:#10b981,stroke-width:2px style R stroke:#ef4444,stroke-width:2px ``` ## Параметри індексу ```csharp // HNSW config - see https://qdrant.tech/documentation/concepts/indexing/#hnsw-index var hnswConfig = new HnswConfigDiff { M = 16, // Edges per node (16-32 recommended) EfConstruct = 100, // Build-time accuracy (100-200) FullScanThreshold = 10000 // Brute force threshold }; await client.UpdateCollectionAsync( collectionName: "blog_posts", hnswConfig: hnswConfig ); ``` **Точність пошуку:** ```csharp var searchParams = new SearchParams { HnswEf = 128 // Higher = better recall, slower (64-256) }; ``` **Настанови щодо налаштування:** Використовує ма́ =М/ ЕфКонструкті * Hnswef} |----------|---|-------------|--------| Д. д. д. д. ст. д. д. д. д. д. д. д. д. д. ст. д. д. ст. 16 * 100 * 128 * * * на на на на на--__ * 32 * 256 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * # Індекси сплати Створити [Індекси вантажу](https://qdrant.tech/documentation/concepts/indexing/#payload-index) для полів, які часто фільтруються: ```csharp // Keyword index - see https://qdrant.tech/documentation/concepts/indexing/#payload-index await client.CreatePayloadIndexAsync( collectionName: "blog_posts", fieldName: "language", schemaType: PayloadSchemaType.Keyword ); // Integer index for ranges await client.CreatePayloadIndexAsync( collectionName: "blog_posts", fieldName: "published", schemaType: PayloadSchemaType.Integer ); ``` **Вплив:** 10-100x швидше фільтрування великих збірок. # Квантація [Квантація](https://qdrant.tech/documentation/guides/quantization/) зменшує використання пам' яті: ```csharp // Scalar quantization - see https://qdrant.tech/documentation/guides/quantization/#scalar-quantization await client.UpdateCollectionAsync( collectionName: "blog_posts", quantizationConfig: new ScalarQuantization { Scalar = new ScalarQuantizationConfig { Type = ScalarType.Int8, // float32 -> int8 Quantile = 0.99f, AlwaysRam = true } } ); ``` **Зменшення торгівлі:** 4x менша пам' ять, ~2% відновлення пам' яті, 1. 5x швидкий пошук. # Деляція Docker ```yaml # docker-compose.yml - see https://qdrant.tech/documentation/guides/installation/ services: qdrant: image: qdrant/qdrant:v1.12.1 # Pin version! ports: - "6333:6333" # REST - "6334:6334" # gRPC volumes: - qdrant_data:/qdrant/storage environment: - QDRANT__SERVICE__GRPC_PORT=6334 - QDRANT__SERVICE__HTTP_PORT=6333 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:6333/health"] interval: 30s timeout: 10s retries: 3 volumes: qdrant_data: ``` ## Безпека Увімкнути [Розпізнавання ключа API](https://qdrant.tech/documentation/guides/security/): ```yaml environment: - QDRANT__SERVICE__API_KEY=your-secret-key ``` # Спостереження ## Метрики Викриття Qdrant [Прометейські виміри](https://qdrant.tech/documentation/guides/monitoring/) на `/metrics`: ```bash curl http://localhost:6333/metrics ``` Фактори ключів: - `qdrant_collections_vector_count` - Всього векторів - `qdrant_rest_responses_duration_seconds` - Запитувати про запізнення - `qdrant_memory_usage_bytes` - Витрати на пам'ять ## Знімки Створити [резервні копії](https://qdrant.tech/documentation/concepts/snapshots/): ```bash # Create snapshot curl -X POST http://localhost:6333/collections/blog_posts/snapshots # List snapshots curl http://localhost:6333/collections/blog_posts/snapshots # Restore (copy snapshot to storage/collections/blog_posts/snapshots/) ``` # Звичайні павичі ## 1. Замішування порту - **6333** = REST API - **6334** = API gRPC (використовуйте це!) ## Невідповідність вектора 2. ``` Error: expected dim: 384, got 768 ``` Відповідність вашої моделі вбудовування і збірки: - `all-MiniLM-L6-v2`: 384 розміри - `nomic-embed-text`: 768 вимірювачів - OpenAI `text-embedding-3-small`: 1536 вимірювачів ## 3. Повільно перший запит Завантаження HNSW у пам' ять. Розігрітися після запуску: ```csharp await client.SearchAsync("blog_posts", new float[384], limit: 1); ``` ## 4. Масивне фільтрування Користування `Match.Any` для полів масиву: ```csharp new Match { Any = new RepeatedStrings { Strings = { "AI", "ML" } } } ``` # Ресурси ## Офіційна документація Qdrant - [Огляд](https://qdrant.tech/documentation/overview/) - Починаємо. - [Принципи](https://qdrant.tech/documentation/concepts/) - Основні концепції - [Збірки](https://qdrant.tech/documentation/concepts/collections/) - Створення і керування збірками - [Точки](https://qdrant.tech/documentation/concepts/points/) - Працювати з векторами - [Пошук](https://qdrant.tech/documentation/concepts/search/) - Операції запитів - [Фільтрування](https://qdrant.tech/documentation/concepts/filtering/) - Стан фільтрування - [Індексування](https://qdrant.tech/documentation/concepts/indexing/) - Індекси HNSW і вантаж - [Квантація](https://qdrant.tech/documentation/guides/quantization/) - Оптимізація пам' яті - [Безпека](https://qdrant.tech/documentation/guides/security/) - Розпізнавання - [Спостереження](https://qdrant.tech/documentation/guides/monitoring/) - Метрика і телеметрія - [Знімки](https://qdrant.tech/documentation/concepts/snapshots/) - Резервування і відновлення ## Бібліотеки клієнта - [Клієнт Qdrant.NET](https://github.com/qdrant/qdrant-dotnet) - Офіційний C# SDK - [Пакунок NuGet](https://www.nuget.org/packages/Qdrant.Client) - Останній випуск. ## Супутні статті - [Частина 4: Реалізація ONNX і Qdrant](/blog/semantic-search-with-onnx-and-qdrant) - [Частина 5: Гібридний пошук і автоматичне інексування](/blog/rag-hybrid-search-and-indexing) - [Огляд послідовностей RAG](/blog/rag-primer) ## Джерельний код Всі коди наявні у: [gitub.com/ scottgal/ methlylucidweb](https://github.com/scottgal/mostlylucidweb) - `Mostlylucid.SemanticSearch/Services/QdrantVectorStoreService.cs` - Інтеграція Qdrant