Use Qdrant as a vector database with DSPy, or connect any vector DB (Pinecone, ChromaDB, Weaviate) with custom retrievers. Use when you want to set up Qdrant, QdrantRM, dspy-qdrant, vector database for DSPy, vector search, hybrid search, or build custom retrievers for Pinecone, ChromaDB, or Weaviate. Also used for qdrant, dspy-qdrant, QdrantRM, vector database, vector search, pinecone DSPy, chromadb DSPy, weaviate DSPy, vector DB for DSPy, pip install dspy-qdrant, qdrant docker, qdrant cloud, hybrid search DSPy, sparse dense vectors, custom dspy.Retrieve, which vector DB for DSPy, DSPy 3.0 retriever removed.
Use Qdrant as a vector database with DSPy, or connect any vector DB (Pinecone, ChromaDB, Weaviate) with custom retrievers. Use when you want to set up Qdrant, QdrantRM, dspy-qdrant, vector database for DSPy, vector search, hybrid search, or build custom retrievers for Pinecone, ChromaDB, or Weaviate. Also used for qdrant, dspy-qdrant, QdrantRM, vector database, vector search, pinecone DSPy, chromadb DSPy, weaviate DSPy, vector DB for DSPy, pip install dspy-qdrant, qdrant docker, qdrant cloud, hybrid search DSPy, sparse dense vectors, custom dspy.Retrieve, which vector DB for DSPy, DSPy 3.0 retriever removed.
Qdrant — Vector Database Integration for DSPy
Guide the user through setting up Qdrant with DSPy using the official dspy-qdrant package, plus custom retriever patterns for Pinecone, ChromaDB, and Weaviate.
Step 1 — Gather context
Ask before generating setup code:
Vector DB — Qdrant, Pinecone, ChromaDB, Weaviate, or something else?
Qdrant deployment (if Qdrant) — Docker locally, Qdrant Cloud, or in-memory for testing?
Index state — indexing documents from scratch, or connecting to an existing collection?
Search mode — standard dense search, or hybrid (keyword + semantic combined)?
Then jump to the relevant section.
What is Qdrant
Qdrant is an open-source vector search engine written in Rust. It's the only vector database with an official DSPy integration package (dspy-qdrant). Features: hybrid search (dense + sparse), payload filtering, multi-tenancy, and horizontal scaling.
Why Qdrant for DSPy
DSPy 3.0 removed all community-contributed retriever modules (ChromadbRM, PineconeRM, WeaviateRM, QdrantRM from the main repo). The package is the official replacement — maintained separately with full DSPy compatibility.
dspy-qdrant
For other vector databases, you write a short custom dspy.Retrieve subclass (~15 lines). This skill covers that pattern too.
Setup
Install
pip install dspy-qdrant
This installs both the Qdrant client and the DSPy retriever module.
Start Qdrant
Option 1: Docker (local development)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
from qdrant_client import QdrantClient
client = QdrantClient(":memory:") # no server needed
Using QdrantRM in DSPy
Basic setup
import dspy
from qdrant_client import QdrantClient
from dspy_qdrant import QdrantRM
client = QdrantClient("http://localhost:6333")
retriever = QdrantRM(
qdrant_collection_name="my_docs",
qdrant_client=client,
k=5,
document_field="document", # payload field containing document text (default)
)
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"), rm=retriever) # or "anthropic/claude-sonnet-4-5-20250929", etc.# Now dspy.Retrieve() uses Qdrant
search = dspy.Retrieve(k=5)
result = search("How do refunds work?")
print(result.passages)
QdrantRM constructor
QdrantRM(
qdrant_collection_name: str, # required — collection name in Qdrant
qdrant_client: QdrantClient, # required — initialized client instance
k: int = 3, # top passages to retrieve
document_field: str = "document", # payload field with document text
vectorizer=None, # BaseSentenceVectorizer (default: FastEmbedVectorizer)
vector_name: str = None, # named vector to search (default: first available)
)
By default, QdrantRM uses FastEmbed (BAAI/bge-small-en-v1.5) for query vectorization. To use a different embedder, pass a custom vectorizer.
Using Qdrant Cloud
import os
from qdrant_client import QdrantClient
from dspy_qdrant import QdrantRM
client = QdrantClient(
url=os.environ["QDRANT_URL"],
api_key=os.environ["QDRANT_API_KEY"],
)
retriever = QdrantRM(
qdrant_collection_name="my_docs",
qdrant_client=client,
k=5,
)
Indexing documents into Qdrant
Before you can search, you need to populate your Qdrant collection:
from qdrant_client import QdrantClient, models
import dspy
client = QdrantClient("http://localhost:6333")
embedder = dspy.Embedder("openai/text-embedding-3-small", dimensions=512)
# Your documents
docs = [
{"id": 1, "document": "Refunds are processed within 5-7 business days.", "category": "billing"},
{"id": 2, "document": "Reset your password at Settings > Security.", "category": "account"},
{"id": 3, "document": "Enterprise plans include SSO and dedicated support.", "category": "plans"},
]
# Create collection
client.create_collection(
collection_name="my_docs",
vectors_config=models.VectorParams(size=512, distance=models.Distance.COSINE),
)
# Upsert with embeddings
vectors = embedder([d["document"] for d in docs])
client.upsert(
collection_name="my_docs",
points=[
models.PointStruct(
id=d["id"],
vector=v,
payload={"document": d["document"], "category": d["category"]},
)
for d, v inzip(docs, vectors)
],
)
RAG pipeline with Qdrant
import dspy
from qdrant_client import QdrantClient
from dspy_qdrant import QdrantRM
dspy.configure(lm=dspy.LM("openai/gpt-4o-mini")) # or "anthropic/claude-sonnet-4-5-20250929", etc.
retriever = QdrantRM(
qdrant_collection_name="my_docs",
qdrant_client=QdrantClient("http://localhost:6333"),
k=5,
)
classRAG(dspy.Module):
def__init__(self):
self.retrieve = retriever
self.answer = dspy.ChainOfThought("context, question -> answer")
defforward(self, question):
context = self.retrieve(question).passages
returnself.answer(context=context, question=question)
rag = RAG()
result = rag(question="How do refunds work?")
print(result.answer)
Verify retrieval is working
Before wiring retrieval into a RAG pipeline, run a sanity check:
result = retriever("your test query here")
assertlen(result.passages) > 0, "Empty results — check document_field matches your payload schema"print(result.passages[0][:300]) # Top passage should be semantically relevant to the query
Empty results: likely a document_field mismatch (gotcha #2). Irrelevant results: query vectorizer does not match the model used when indexing (gotcha #4).
Hybrid search (dense + sparse)
Qdrant supports hybrid search combining dense (semantic) and sparse (keyword) vectors in the same collection. This improves recall for queries that need both semantic understanding and exact keyword matching.
from qdrant_client import QdrantClient, models
client = QdrantClient("http://localhost:6333")
# Create collection with both dense and sparse vectors
client.create_collection(
collection_name="hybrid_docs",
vectors_config=models.VectorParams(size=512, distance=models.Distance.COSINE),
sparse_vectors_config={
"keywords": models.SparseVectorParams(
modifier=models.Modifier.IDF,
),
},
)
Starting a new DSPy project?
→ Qdrant (official DSPy package, easiest setup)
Prototyping locally, smallest footprint?
→ ChromaDB (pip install, in-memory or persistent, no server)
Already using Pinecone/Weaviate in production?
→ Write a custom retriever (15 lines, shown above)
Need hybrid search (keyword + semantic)?
→ Qdrant or Weaviate
Gotchas
Claude fabricates QdrantRM constructor parameters. Claude invents params like qdrant_client_url, qdrant_client_api_key, embedding_model, and embedding_dimensions. These do not exist. QdrantRM takes a qdrant_client (an initialized QdrantClient instance) and a vectorizer (a BaseSentenceVectorizer). Always construct the QdrantClient separately, then pass it.
Claude uses document_field="text" but the default is "document". When indexing, store content in a payload field named document (the default), or explicitly set document_field="text" if your payload uses text. Mismatched field names silently return empty passages.
DSPy 3.0 removed community retrievers — from dspy.retrieve.chromadb_rm import ChromadbRM no longer works. Use dspy-qdrant or write a custom dspy.Retrieve subclass.
QdrantRM uses FastEmbed by default, not OpenAI embeddings. The default vectorizer is FastEmbedVectorizer using BAAI/bge-small-en-v1.5. Your indexed vectors must match this model. If you indexed with OpenAI embeddings, pass a custom vectorizer that uses the same model.
dspy.Embeddings is simpler for in-memory retrieval. If you just need to search a small corpus (under ~100k passages) without a vector DB, use dspy.Embeddings(corpus=docs, embedder=embedder) instead. It handles indexing and search in one class. Use Qdrant when you need persistence, filtering, hybrid search, or scale.
Install /ai-do if you do not have it — it routes any AI problem to the right skill and is the fastest way to work: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill ai-do
