Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: add Qdrant vector search tool documentation (#2184)
Tony Kipkemboi86825e176900
diff --git a/docs/mint.json b/docs/mint.jsonindex fb0dcfdf5..9b49648aa 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -139,6 +139,7 @@"tools/nl2sqltool","tools/pdfsearchtool","tools/pgsearchtool",+ "tools/qdrantvectorsearchtool","tools/scrapewebsitetool","tools/seleniumscrapingtool","tools/spidertool",diff --git a/docs/tools/qdrantvectorsearchtool.mdx b/docs/tools/qdrantvectorsearchtool.mdxnew file mode 100644index 000000000..da3dcb1a2--- /dev/null+++ b/docs/tools/qdrantvectorsearchtool.mdx@@ -0,0 +1,271 @@+---+title: 'Qdrant Vector Search Tool'+description: 'Semantic search capabilities for CrewAI agents using Qdrant vector database'+icon: magnifying-glass-plus+---++# `QdrantVectorSearchTool`++The Qdrant Vector Search Tool enables semantic search capabilities in your CrewAI agents by leveraging [Qdrant](https://qdrant.tech/), a vector similarity search engine. This tool allows your agents to search through documents stored in a Qdrant collection using semantic similarity.++## Installation++Install the required packages:++```bash+uv pip install 'crewai[tools] qdrant-client'+```++## Basic Usage++Here's a minimal example of how to use the tool:++```python+from crewai import Agent+from crewai_tools import QdrantVectorSearchTool++# Initialize the tool+qdrant_tool = QdrantVectorSearchTool(+ qdrant_url="your_qdrant_url",+ qdrant_api_key="your_qdrant_api_key",+ collection_name="your_collection"+)++# Create an agent that uses the tool+agent = Agent(+ role="Research Assistant",+ goal="Find relevant information in documents",+ tools=[qdrant_tool]+)++# The tool will automatically use OpenAI embeddings+# and return the 3 most relevant results with scores > 0.35+```++## Complete Working Example++Here's a complete example showing how to:+1. Extract text from a PDF+2. Generate embeddings using OpenAI+3. Store in Qdrant+4. Create a CrewAI agentic RAG workflow for semantic search++```python+import os+import uuid+import pdfplumber+from openai import OpenAI+from dotenv import load_dotenv+from crewai import Agent, Task, Crew, Process, LLM+from crewai_tools import QdrantVectorSearchTool+from qdrant_client import QdrantClient+from qdrant_client.models import PointStruct, Distance, VectorParams++# Load environment variables+load_dotenv()++# Initialize OpenAI client+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))++# Extract text from PDF+def extract_text_from_pdf(pdf_path):+ text = []+ with pdfplumber.open(pdf_path) as pdf:+ for page in pdf.pages:+ page_text = page.extract_text()+ if page_text:+ text.append(page_text.strip())+ return text++# Generate OpenAI embeddings+def get_openai_embedding(text):+ response = client.embeddings.create(+ input=text,+ model="text-embedding-3-small"+ )+ return response.data[0].embedding++# Store text and embeddings in Qdrant+def load_pdf_to_qdrant(pdf_path, qdrant, collection_name):+ # Extract text from PDF+ text_chunks = extract_text_from_pdf(pdf_path)++ # Create Qdrant collection+ if qdrant.collection_exists(collection_name):+ qdrant.delete_collection(collection_name)+ qdrant.create_collection(+ collection_name=collection_name,+ vectors_config=VectorParams(size=1536, distance=Distance.COSINE)+ )++ # Store embeddings+ points = []+ for chunk in text_chunks:+ embedding = get_openai_embedding(chunk)+ points.append(PointStruct(+ id=str(uuid.uuid4()),+ vector=embedding,+ payload={"text": chunk}+ ))+ qdrant.upsert(collection_name=collection_name, points=points)++# Initialize Qdrant client and load data+qdrant = QdrantClient(+ url=os.getenv("QDRANT_URL"),+ api_key=os.getenv("QDRANT_API_KEY")+)+collection_name = "example_collection"+pdf_path = "path/to/your/document.pdf"+load_pdf_to_qdrant(pdf_path, qdrant, collection_name)++# Initialize Qdrant search tool+qdrant_tool = QdrantVectorSearchTool(+ qdrant_url=os.getenv("QDRANT_URL"),+ qdrant_api_key=os.getenv("QDRANT_API_KEY"),+ collection_name=collection_name,+ limit=3,+ score_threshold=0.35+)++# Create CrewAI agents+search_agent = Agent(+ role="Senior Semantic Search Agent",+ goal="Find and analyze documents based on semantic search",+ backstory="""You are an expert research assistant who can find relevant+ information using semantic search in a Qdrant database.""",+ tools=[qdrant_tool],+ verbose=True+)++answer_agent = Agent(+ role="Senior Answer Assistant",+ goal="Generate answers to questions based on the context provided",+ backstory="""You are an expert answer assistant who can generate+ answers to questions based on the context provided.""",+ tools=[qdrant_tool],+ verbose=True+)++# Define tasks+search_task = Task(+ description="""Search for relevant documents about the {query}.+ Your final answer should include:+ - The relevant information found+ - The similarity scores of the results+ - The metadata of the relevant documents""",+ agent=search_agent+)++answer_task = Task(+ description="""Given the context and metadata of relevant documents,+ generate a final answer based on the context.""",+ agent=answer_agent+)++# Run CrewAI workflow+crew = Crew(+ agents=[search_agent, answer_agent],+ tasks=[search_task, answer_task],+ process=Process.sequential,+ verbose=True+)++result = crew.kickoff(+ inputs={"query": "What is the role of X in the document?"}+)+print(result)+```++## Tool Parameters++### Required Parameters+- `qdrant_url` (str): The URL of your Qdrant server+- `qdrant_api_key` (str): API key for authentication with Qdrant+- `collection_name` (str): Name of the Qdrant collection to search++### Optional Parameters+- `limit` (int): Maximum number of results to return (default: 3)+- `score_threshold` (float): Minimum similarity score threshold (default: 0.35)+- `custom_embedding_fn` (Callable[[str], list[float]]): Custom function for text vectorization++## Search Parameters++The tool accepts these parameters in its schema:+- `query` (str): The search query to find similar documents+- `filter_by` (str, optional): Metadata field to filter on+- `filter_value` (str, optional): Value to filter by++## Return Format++The tool returns results in JSON format:++```json+[+ {+ "metadata": {+ // Any metadata stored with the document+ },+ "context": "The actual text content of the document",+ "distance": 0.95 // Similarity score+ }+]+```++## Default Embedding++By default, the tool uses OpenAI's `text-embedding-3-small` model for vectorization. This requires:+- OpenAI API key set in environment: `OPENAI_API_KEY`++## Custom Embeddings++Instead of using the default embedding model, you might want to use your own embedding function in cases where you:++1. Want to use a different embedding model (e.g., Cohere, HuggingFace, Ollama models)+2. Need to reduce costs by using open-source embedding models+3. Have specific requirements for vector dimensions or embedding quality+4. Want to use domain-specific embeddings (e.g., for medical or legal text)++Here's an example using a HuggingFace model:++```python+from transformers import AutoTokenizer, AutoModel+import torch++# Load model and tokenizer+tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')+model = AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')++def custom_embeddings(text: str) -> list[float]:+ # Tokenize and get model outputs+ inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)+ outputs = model(**inputs)++ # Use mean pooling to get text embedding+ embeddings = outputs.last_hidden_state.mean(dim=1)++ # Convert to list of floats and return+ return embeddings[0].tolist()++# Use custom embeddings with the tool+tool = QdrantVectorSearchTool(+ qdrant_url="your_url",+ qdrant_api_key="your_key",+ collection_name="your_collection",+ custom_embedding_fn=custom_embeddings # Pass your custom function+)+```++## Error Handling++The tool handles these specific errors:+- Raises ImportError if `qdrant-client` is not installed (with option to auto-install)+- Raises ValueError if `QDRANT_URL` is not set+- Prompts to install `qdrant-client` if missing using `uv add qdrant-client`++## Environment Variables++Required environment variables:+```bash+export QDRANT_URL="your_qdrant_url" # If not provided in constructor+export QDRANT_API_KEY="your_api_key" # If not provided in constructor+export OPENAI_API_KEY="your_openai_key" # If using default embeddings\ No newline at end of file