buun-stack/qdrant/README.md

Qdrant

High-performance vector database for AI/ML applications:

• Vector Search: Fast similarity search with multiple distance metrics (Cosine, Euclidean, Dot Product)
• Rich Filtering: Combine vector similarity with payload-based filtering
• Scalable: Horizontal scaling for large-scale vector collections
• RESTful API: Simple HTTP API for vector operations
• Secure Authentication: API key-based authentication with Vault integration
• High Availability: Built-in replication and fault tolerance

Installation

just qdrant::install

During installation, you will be prompted for:

• Qdrant host (FQDN): The domain name for accessing Qdrant (e.g., qdrant.yourdomain.com)

The installation automatically:

• Generates API keys (read-write and read-only)
• Stores keys in Vault (if External Secrets is available) or Kubernetes Secrets
• Configures Traefik ingress with TLS

Access

Access Qdrant at https://qdrant.yourdomain.com using the API keys.

Get API Keys

# Get read-write API key
just qdrant::get-api-key

# Get read-only API key
just qdrant::get-readonly-api-key

Testing & Health Check

Qdrant includes built-in testing recipes that use telepresence to access the service from your local machine.

Prerequisites

Ensure telepresence is connected:

telepresence connect

Health Check

just qdrant::health-check

Checks if Qdrant is running and responding to requests.

Vector Operations Test

just qdrant::test

Runs a complete test suite that:

1. Creates a test collection with 4-dimensional vectors
2. Adds sample points (cities with vector embeddings)
3. Performs similarity search
4. Cleans up the test collection

Example output:

Testing Qdrant at http://qdrant.qdrant.svc.cluster.local:6333
Using collection: test_collection_1760245249

1. Creating collection...
{
  "result": true,
  "status": "ok"
}

2. Adding test points...
{
  "result": {
    "operation_id": 0,
    "status": "completed"
  },
  "status": "ok"
}

3. Searching for similar vectors...
{
  "result": [
    {
      "id": 2,
      "score": 0.99,
      "payload": {"city": "London"}
    }
  ],
  "status": "ok"
}

Test completed successfully!

Using Qdrant

REST API

Qdrant provides a RESTful API for all operations. Here are some common examples:

Create a Collection

curl -X PUT "https://qdrant.yourdomain.com/collections/my_collection" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 384,
      "distance": "Cosine"
    }
  }'

Insert Vectors

curl -X PUT "https://qdrant.yourdomain.com/collections/my_collection/points" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.1, 0.2, ...],
        "payload": {"text": "example document"}
      }
    ]
  }'

Search Similar Vectors

curl -X POST "https://qdrant.yourdomain.com/collections/my_collection/points/search" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, ...],
    "limit": 10
  }'

Python Client

from qdrant_client import QdrantClient

# Connect to Qdrant
client = QdrantClient(
    url="https://qdrant.yourdomain.com",
    api_key="YOUR_API_KEY"
)

# Create collection
client.create_collection(
    collection_name="my_collection",
    vectors_config={"size": 384, "distance": "Cosine"}
)

# Insert vectors
client.upsert(
    collection_name="my_collection",
    points=[
        {
            "id": 1,
            "vector": [0.1, 0.2, ...],
            "payload": {"text": "example document"}
        }
    ]
)

# Search
results = client.search(
    collection_name="my_collection",
    query_vector=[0.15, 0.25, ...],
    limit=10
)

JupyterHub Integration

Store your API key securely in Vault using the buunstack package:

from buunstack import SecretStore

secrets = SecretStore()
secrets.put('qdrant', api_key='YOUR_API_KEY')

# Later, retrieve it
api_key = secrets.get('qdrant', field='api_key')

Use Cases

Vector Embeddings Search

Store and search document, image, or audio embeddings for:

• Semantic search
• Recommendation systems
• Duplicate detection
• Content-based filtering

RAG (Retrieval-Augmented Generation)

Use Qdrant as the vector store for LLM applications:

• Store document chunks with embeddings
• Retrieve relevant context for LLM prompts
• Build knowledge bases with semantic search

Similarity Matching

Find similar items based on learned representations:

• Image similarity search
• Product recommendations
• Anomaly detection
• Clustering and classification

Cleanup

To remove all Qdrant resources and secrets from Vault:

just qdrant::cleanup

This will prompt for confirmation before deleting the Vault secrets.

Uninstallation

just qdrant::uninstall

This will:

• Uninstall the Qdrant Helm release
• Delete API keys secrets
• Remove the Qdrant namespace

Documentation

For more information, see the official Qdrant documentation:

• Qdrant Documentation
• REST API Reference
• Python Client