Qdrant Vector Database Add-on

High-performance vector database designed for AI applications, providing both REST and gRPC APIs for vector search and storage.

Features

• 🚀 High Performance: Optimized for vector similarity search
• 🔍 Semantic Search: Build search engines that understand meaning
• 📊 REST & gRPC APIs: Flexible integration options
• 🎯 Filtering Support: Combine vector search with metadata filters
• 🌐 Web UI: Built-in dashboard for monitoring and management
• 💾 Persistent Storage: Data survives restarts and updates
• 🔒 Optional Authentication: API key protection available

Use Cases

1. Semantic Search

Build search systems that understand context and meaning rather than just keywords.

2. Recommendation Systems

Create personalized recommendations based on user preferences and behavior patterns.

3. RAG Applications

Retrieval-Augmented Generation for enhancing LLM responses with relevant context.

4. Image Similarity Search

Find similar images based on visual features using image embeddings.

5. Anomaly Detection

Identify outliers in your data by finding vectors that are dissimilar to the norm.

Installation

1. Add the J0rsa repository to your Home Assistant
2. Search for “Qdrant” in the Add-on Store
3. Click Install and wait for the download to complete
4. Configure the add-on (see Configuration below)
5. Start the add-on

Configuration

# Example configuration
web_ui_enabled: true           # Enable web dashboard
api_key: ""                    # Optional API key for authentication
read_only_api_key: ""          # Optional read-only API key
read_only: false               # Enable read-only mode
log_level: "INFO"              # Logging level
max_request_size_mb: 32        # Maximum request size in MB

Configuration Options

Usage

Accessing the Services

After starting the add-on, you can access:

• REST API: http://homeassistant.local:6333
• gRPC API: homeassistant.local:6334
• Web Dashboard: http://homeassistant.local:6333/dashboard

API Examples

Create a Collection

Collections are the primary way to organize vectors in Qdrant:

curl -X PUT 'http://homeassistant.local:6333/collections/my_collection' \
  -H 'Content-Type: application/json' \
  -H 'api-key: your-api-key' \
  -d '{
    "vectors": {
      "size": 384,
      "distance": "Cosine"
    }
  }'

Distance metrics available:

• Cosine - Cosine similarity (recommended for normalized vectors)
• Euclid - Euclidean distance
• Dot - Dot product (for non-normalized vectors)

Insert Vectors

Add vectors with associated metadata:

curl -X PUT 'http://homeassistant.local:6333/collections/my_collection/points' \
  -H 'Content-Type: application/json' \
  -H 'api-key: your-api-key' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.1, 0.2, 0.3, ...],
        "payload": {
          "text": "Example document",
          "category": "tutorial",
          "timestamp": 1700000000
        }
      }
    ]
  }'

Search for Similar Vectors

Find the most similar vectors:

curl -X POST 'http://homeassistant.local:6333/collections/my_collection/points/search' \
  -H 'Content-Type: application/json' \
  -H 'api-key: your-api-key' \
  -d '{
    "vector": [0.1, 0.2, 0.3, ...],
    "limit": 5,
    "filter": {
      "must": [
        {
          "key": "category",
          "match": {
            "value": "tutorial"
          }
        }
      ]
    }
  }'

List Collections

View all collections in your database:

curl -X GET 'http://homeassistant.local:6333/collections' \
  -H 'api-key: your-api-key'

Integration with Home Assistant

REST Sensor Example

Monitor collection statistics:

sensor:
  - platform: rest
    name: "Qdrant Collection Count"
    resource: http://localhost:6333/collections
    method: GET
    headers:
      api-key: "your-api-key"
    value_template: ""
    scan_interval: 300

REST Command Example

Create a service to search vectors:

rest_command:
  search_qdrant:
    url: "http://localhost:6333/collections//points/search"
    method: POST
    headers:
      Content-Type: "application/json"
      api-key: "your-api-key"
    payload: '{"vector": , "limit": }'

Python Integration Example

from qdrant_client import QdrantClient
from qdrant_client.http.models import Distance, VectorParams, PointStruct

# Connect to Qdrant
client = QdrantClient(
    host="homeassistant.local",
    port=6333,
    api_key="your-api-key"
)

# Create collection
client.create_collection(
    collection_name="test_collection",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
)

# Insert points
points = [
    PointStruct(
        id=1,
        vector=[0.1] * 384,
        payload={"text": "Hello world"}
    )
]
client.upsert(collection_name="test_collection", points=points)

# Search
search_result = client.search(
    collection_name="test_collection",
    query_vector=[0.1] * 384,
    limit=5
)

Hardware Requirements

Minimum Requirements

• CPU: 2 cores
• RAM: 2GB (more for larger datasets)
• Storage: 1GB + space for vectors

Recommended for Production

• CPU: 4+ cores
• RAM: 8GB+
• Storage: SSD with sufficient space for your data

Memory Guidelines by Dataset Size

• 10K vectors (384 dims): ~100MB RAM
• 100K vectors (384 dims): ~1GB RAM
• 1M vectors (384 dims): ~10GB RAM

Performance Optimization

1. Index Configuration

• Use appropriate distance metrics for your use case
• Consider quantization for large datasets

2. Batch Operations

• Insert/update vectors in batches for better performance
• Use the max_request_size_mb setting appropriately

3. Filtering

• Create indexes on frequently filtered fields
• Use pre-filtering when possible

4. Memory Management

• Monitor RAM usage via the dashboard
• Consider mmap storage for very large collections

Data Persistence

• Storage Location: /config/qdrant/storage
• Backup: Regular backups recommended for production
• Snapshots: Available via the API for point-in-time backups

Creating a Snapshot

curl -X POST 'http://homeassistant.local:6333/collections/my_collection/snapshots' \
  -H 'api-key: your-api-key'

Security Best Practices

1. Always use API keys in production environments
2. Use read-only keys for query-only applications
3. Limit network exposure - only expose ports if needed
4. Regular backups of your vector data
5. Monitor logs for unauthorized access attempts

Troubleshooting

Add-on Won’t Start

• Check logs for error messages
• Ensure ports 6333 and 6334 are not in use
• Verify sufficient disk space and RAM

Connection Refused

• Ensure the add-on is running
• Check if API key is required but not provided
• Verify network connectivity

Slow Performance

• Check RAM usage - Qdrant loads indexes into memory
• Consider optimizing vector dimensions
• Review batch sizes for bulk operations
• Enable quantization for large datasets

Web UI Not Loading

• Ensure web_ui_enabled is set to true
• Clear browser cache
• Check console for JavaScript errors

Advanced Features

Quantization

Reduce memory usage with scalar quantization:

{
  "vectors": {
    "size": 384,
    "distance": "Cosine"
  },
  "quantization_config": {
    "scalar": {
      "type": "int8",
      "quantile": 0.99,
      "always_ram": true
    }
  }
}

Payload Indexing

Create indexes for faster filtering:

curl -X PUT 'http://homeassistant.local:6333/collections/my_collection/index' \
  -H 'Content-Type: application/json' \
  -H 'api-key: your-api-key' \
  -d '{
    "field_name": "category",
    "field_schema": "keyword"
  }'

Support

• GitHub Issues
• Qdrant Documentation
• Qdrant API Reference
• Community Forum