Qdrant Vector Search Tool

Qdrant 벡터 데이터베이스를 활용해 CrewAI 에이전트에 시맨틱 검색 기능을 제공하는 도구예요.

출처: 문서

본문

개요 (Overview)

Qdrant Vector Search Tool은 Qdrant(벡터 유사도 검색 엔진)를 활용해 CrewAI 에이전트에 시맨틱 검색 기능을 제공합니다. 이 도구는 에이전트가 Qdrant 컬렉션에 저장된 문서를 시맨틱 유사도를 기반으로 검색할 수 있게 해줍니다.

설치 (Installation)

필요한 패키지를 설치하세요.

uv add qdrant-client

기본 사용법 (Basic Usage)

도구를 사용하는 최소한의 예시입니다:

from crewai import Agent
from crewai_tools import QdrantVectorSearchTool, QdrantConfig

# QdrantConfig로 도구 초기화
qdrant_tool = QdrantVectorSearchTool(
    qdrant_config=QdrantConfig(
        qdrant_url="your_qdrant_url",
        qdrant_api_key="your_qdrant_api_key",
        collection_name="your_collection"
    )
)

# 도구를 사용하는 에이전트 생성
agent = Agent(
    role="Research Assistant",
    goal="Find relevant information in documents",
    tools=[qdrant_tool]
)

# 이 도구는 자동으로 OpenAI 임베딩을 사용하며
# 점수가 0.35를 초과하는 가장 관련성 높은 3개의 결과를 반환합니다

완전한 동작 예시 (Complete Working Example)

다음을 보여주는 완전한 예시입니다:

PDF에서 텍스트 추출
OpenAI를 사용한 임베딩 생성
Qdrant에 저장
시맨틱 검색을 위한 CrewAI 에이전트형 RAG 워크플로우 생성

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

# Environment variables load
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-large"
    )
    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=3072, 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
from crewai_tools import QdrantConfig

qdrant_tool = QdrantVectorSearchTool(
    qdrant_config=QdrantConfig(
        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_config (QdrantConfig): 모든 Qdrant 설정을 담고 있는 구성 객체입니다.

QdrantConfig 매개변수 (QdrantConfig Parameters)

qdrant_url (str): Qdrant 서버의 URL입니다.
qdrant_api_key (str, optional): Qdrant 인증을 위한 API 키입니다.
collection_name (str): 검색할 Qdrant 컬렉션의 이름입니다.
limit (int): 반환할 최대 결과 수입니다 (기본값: 3).
score_threshold (float): 최소 유사도 점수 임계값입니다 (기본값: 0.35).
filter (Any, optional): 고급 필터링을 위한 Qdrant Filter 인스턴스입니다 (기본값: None).

선택적 도구 매개변수 (Optional Tool Parameters)

custom_embedding_fn (Callable[[str], list[float]]): 텍스트 벡터화를 위한 커스텀 함수입니다.
qdrant_package (str): Qdrant의 기본 패키지 경로입니다 (기본값: "qdrant_client").
client (Any): 미리 초기화된 Qdrant 클라이언트입니다 (선택 사항).

고급 필터링 (Advanced Filtering)

QdrantVectorSearchTool은 검색 결과를 세밀하게 다듬을 수 있는 강력한 필터링 기능을 지원합니다.

동적 필터링 (Dynamic Filtering)

검색에서 filter_by와 filter_value 매개변수를 사용해 실시간으로 결과를 필터링할 수 있습니다.

# Agent will use these parameters when calling the tool
# The tool schema accepts filter_by and filter_value
# Example: search with category filter
# Results will be filtered where category == "technology"

QdrantConfig로 사전 필터 설정하기 (Preset Filters with QdrantConfig)

복잡한 필터링을 위해서는 구성에 Qdrant Filter 인스턴스를 사용하세요.

from qdrant_client.http import models as qmodels
from crewai_tools import QdrantVectorSearchTool, QdrantConfig

# Create a filter for specific conditions
preset_filter = qmodels.Filter(
    must=[
        qmodels.FieldCondition(
            key="category",
            match=qmodels.MatchValue(value="research")
        ),
        qmodels.FieldCondition(
            key="year",
            match=qmodels.MatchValue(value=2024)
        )
    ]
)

# Initialize tool with preset filter
qdrant_tool = QdrantVectorSearchTool(
    qdrant_config=QdrantConfig(
        qdrant_url="your_url",
        qdrant_api_key="your_key",
        collection_name="your_collection",
        filter=preset_filter  # Preset filter applied to all searches
    )
)

필터 결합 (Combining Filters)

도구는 QdrantConfig의 사전 필터와 filter_by, filter_value의 동적 필터를 자동으로 결합합니다.

# If QdrantConfig has a preset filter for category="research"
# And the search uses filter_by="year", filter_value=2024
# Both filters will be combined (AND logic)

검색 매개변수 (Search Parameters)

도구는 스키마에서 다음 매개변수를 허용합니다:

query (str): 유사한 문서를 찾기 위한 검색 쿼리입니다.
filter_by (str, optional): 필터링할 메타데이터 필드입니다.
filter_value (Any, optional): 필터링할 값입니다.

반환 형식 (Return Format)

도구는 결과를 JSON 형식으로 반환합니다.

[
  {
    "metadata": {
      // Any metadata stored with the document
    },
    "context": "The actual text content of the document",
    "distance": 0.95  // Similarity score
  }
]

기본 임베딩 (Default Embedding)

기본적으로 도구는 OpenAI의 text-embedding-3-large 모델을 벡터화에 사용합니다. 이를 위해서는 다음이 필요합니다:

환경에 설정된 OpenAI API 키: OPENAI_API_KEY

커스텀 임베딩 (Custom Embeddings)

기본 임베딩 모델 대신 다음 경우에 자체 임베딩 함수를 사용할 수 있습니다:

다른 임베딩 모델을 사용하려는 경우 (예: Cohere, HuggingFace, Ollama 모델)
오픈소스 임베딩 모델로 비용을 줄여야 하는 경우
벡터 차원이나 임베딩 품질에 대한 특정 요구사항이 있는 경우
도메인 특화 임베딩을 사용하려는 경우 (예: 의료나 법률 텍스트)

HuggingFace 모델을 사용하는 예시입니다:

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
from crewai_tools import QdrantConfig

tool = QdrantVectorSearchTool(
    qdrant_config=QdrantConfig(
        qdrant_url="your_url",
        qdrant_api_key="your_key",
        collection_name="your_collection"
    ),
    custom_embedding_fn=custom_embeddings  # Pass your custom function
)

오류 처리 (Error Handling)

도구는 다음과 같은 특정 오류를 처리합니다:

qdrant-client가 설치되어 있지 않으면 ImportError를 발생시킵니다 (자동 설치 옵션 포함).
QDRANT_URL이 설정되어 있지 않으면 ValueError를 발생시킵니다.
qdrant-client가 없으면 uv add qdrant-client를 사용해 설치하라는 안내를 표시합니다.

환경 변수 (Environment Variables)

필요한 환경 변수:

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

Qdrant Vector Search Tool