Qdrant Plugin

Self-hosted vector database with advanced filtering and high performance. Built on qdrant-client.

Installation

pip install qdrant-client

Quick Start

from daita import SubstrateAgent
from daita.plugins import qdrant

# Create plugin
vector_db = qdrant(
    url="http://localhost:6333",
    collection="embeddings"
)

# Agent uses vector database tools autonomously
agent = SubstrateAgent(
    name="Vector Search Agent",
    prompt="You are a semantic search assistant. Help users find relevant information.",
    tools=[vector_db]
)

await agent.start()
result = await agent.run("Find documents similar to 'machine learning'")

Direct Usage

The plugin can be used directly without agents for programmatic access. For comprehensive Qdrant API documentation, see the official Qdrant docs. The main value of this plugin is agent integration - enabling LLMs to autonomously perform semantic search operations.

Connection Parameters

qdrant(
    url: str = "http://localhost:6333",
    api_key: Optional[str] = None,
    collection: str = "default",
    **kwargs
)

Parameters

• url (str): Qdrant server URL (default: "http://localhost:6333")
• api_key (str, optional): Optional API key for authentication
• collection (str): Collection name to use (default: "default")
• ****kwargs**: Additional Qdrant configuration

Using with Agents

Qdrant plugin exposes vector operations as tools that agents can use autonomously:

from daita import SubstrateAgent
from daita.plugins import qdrant
import os

# Create Qdrant plugin
vector_db = qdrant(
    url="http://localhost:6333",
    collection="knowledge_base"
)

# Pass plugin to agent - agent can now use Qdrant tools autonomously
agent = SubstrateAgent(
    name="Semantic Search Agent",
    prompt="You are a semantic search assistant. Help users find relevant documents.",
    llm_provider="openai",
    model="gpt-4",
    tools=[vector_db]
)

await agent.start()

# Agent autonomously uses Qdrant tools to answer questions
result = await agent.run("Find documents about machine learning")

# The agent will autonomously:
# 1. Use qdrant_search to find relevant vectors
# 2. Analyze and present results in natural language

await agent.stop()

Available Tools

The Qdrant plugin exposes these tools to LLM agents:

Tool	Description	Parameters
qdrant_search	Search for similar vectors	vector (required), top_k (int), filter (object)
qdrant_upsert	Insert or update vectors	ids (required), vectors (required), metadata (array)
qdrant_delete	Delete vectors	ids (array), filter (object)
qdrant_create_collection	Create new collection	name (required), vector_size (required), distance (string)

Tool Categories: vector_db Tool Source: plugin Filter Format: Simple dict (e.g., {"category": "tech"})

Tool Usage Example

from daita import SubstrateAgent
from daita.plugins import qdrant

# Setup Qdrant with tool integration
vector_db = qdrant(
    url="http://localhost:6333",
    collection="articles"
)

agent = SubstrateAgent(
    name="Research Assistant",
    prompt="You are a research assistant. Help users find and organize information.",
    llm_provider="openai",
    model="gpt-4",
    tools=[vector_db]
)

await agent.start()

# Natural language command - agent uses tools autonomously
result = await agent.run("""
Search for articles about:
1. Neural networks
2. Deep learning
3. Computer vision
Return the top 5 most relevant results.
""")

# Agent orchestrates Qdrant tool calls to fulfill the request
print(result)
await agent.stop()

Distance Metrics

Qdrant supports three distance metrics:

from daita.plugins import qdrant

async with qdrant(url="http://localhost:6333") as db:
    # Cosine similarity (default, range: -1 to 1)
    await db.create_collection(
        name="cosine_collection",
        vector_size=384,
        distance="Cosine"
    )

    # Euclidean distance (range: 0 to ∞)
    await db.create_collection(
        name="euclid_collection",
        vector_size=384,
        distance="Euclid"
    )

    # Dot product (range: -∞ to ∞)
    await db.create_collection(
        name="dot_collection",
        vector_size=384,
        distance="Dot"
    )

Error Handling

try:
    async with qdrant(
        url="http://localhost:6333",
        collection="documents"
    ) as db:
        results = await db.query(
            vector=[0.1, 0.2, 0.3],
            top_k=5
        )
except ImportError as e:
    if "qdrant-client" in str(e):
        print("Install qdrant-client: pip install qdrant-client")
except Exception as e:
    print(f"Qdrant error: {e}")

Best Practices

Connection Management:

• Use context managers (async with) for automatic cleanup
• Use persistent Qdrant instances for production
• Configure authentication for remote deployments
• Monitor collection sizes and performance

Performance:

• Batch upsert operations when inserting multiple vectors
• Use payload filters to narrow search scope
• Limit top_k to only what you need
• Choose appropriate distance metric for your use case

Data Organization:

• Create separate collections for different use cases
• Use meaningful collection names
• Include descriptive metadata (payload) for better filtering
• Ensure consistent vector dimensions within a collection

Security:

• Enable API key authentication for production
• Use HTTPS for remote connections
• Protect Qdrant endpoints with firewall rules
• Store credentials in environment variables

Filtering

Qdrant supports payload filtering with automatic conversion from simple dicts:

async with qdrant(
    url="http://localhost:6333",
    collection="documents"
) as db:
    # Simple equality filter (automatically converted)
    results = await db.query(
        vector=[0.1, 0.2, 0.3],
        top_k=10,
        filter={"category": "tech"}
    )

    # Multiple fields
    results = await db.query(
        vector=[0.1, 0.2, 0.3],
        top_k=10,
        filter={"category": "tech", "year": 2024}
    )

Troubleshooting

Issue	Solution
qdrant-client not installed	pip install qdrant-client
Connection refused	Check Qdrant server is running, verify URL
Collection doesn't exist	Create it with create_collection() or it will auto-create on first upsert warning
Authentication failed	Verify API key is correct
Dimension mismatch	Ensure all vectors match collection's vector_size

Common Patterns

Semantic search with filters:

async with qdrant(
    url="http://localhost:6333",
    collection="docs"
) as db:
    results = await db.query(
        vector=query_embedding,
        top_k=10,
        filter={"category": "tech", "published": "2024"}
    )

Collection setup:

async with qdrant(url="http://localhost:6333") as db:
    # Create collection if needed
    await db.create_collection(
        name="embeddings",
        vector_size=384,
        distance="Cosine"
    )

    # List existing collections
    collections = await db.list_collections()
    print(f"Collections: {collections}")

Bulk operations:

async with qdrant(
    url="http://localhost:6333",
    collection="docs"
) as db:
    # Batch upsert
    await db.upsert(
        ids=[f"doc{i}" for i in range(1000)],
        vectors=[generate_embedding(doc) for doc in documents],
        metadata=[{"source": doc.source} for doc in documents]
    )

Next Steps

• Plugin Overview - All available plugins
• ChromaDB Plugin - Embeddable vector database
• Pinecone Plugin - Managed cloud vector database