메인 콘텐츠로 건너뛰기

개요

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

설치

필수 패키지를 설치하세요:

기본 사용법

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

완전한 작동 예시

아래는 다음과 같은 방법을 보여주는 완전한 예시입니다:
  1. PDF에서 텍스트 추출
  2. OpenAI를 사용하여 임베딩 생성
  3. Qdrant에 저장
  4. CrewAI agentic RAG 워크플로우로 시맨틱 검색 생성

도구 매개변수

필수 파라미터

  • qdrant_config (QdrantConfig): 모든 Qdrant 설정을 포함하는 구성 객체

QdrantConfig 매개변수

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

선택적 도구 매개변수

  • custom_embedding_fn (Callable[[str], list[float]]): 텍스트 벡터화를 위한 사용자 지정 함수
  • qdrant_package (str): Qdrant의 기본 패키지 경로 (기본값: “qdrant_client”)
  • client (Any): 사전 초기화된 Qdrant 클라이언트 (선택 사항)

고급 필터링

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

동적 필터링

검색 시 filter_byfilter_value 매개변수를 사용하여 즉석에서 결과를 필터링할 수 있습니다:

QdrantConfig를 사용한 사전 설정 필터

복잡한 필터링의 경우 구성에서 Qdrant Filter 인스턴스를 사용하세요:

필터 결합

도구는 QdrantConfig의 사전 설정 필터와 filter_byfilter_value의 동적 필터를 자동으로 결합합니다:

검색 매개변수

이 도구는 스키마에서 다음과 같은 매개변수를 허용합니다:
  • query (str): 유사한 문서를 찾기 위한 검색 쿼리
  • filter_by (str, 선택 사항): 필터링할 메타데이터 필드
  • filter_value (Any, 선택 사항): 필터 기준 값

반환 형식

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

기본 임베딩

기본적으로, 이 도구는 벡터화를 위해 OpenAI의 text-embedding-3-large 모델을 사용합니다. 이를 위해서는 다음이 필요합니다:
  • 환경변수에 설정된 OpenAI API 키: OPENAI_API_KEY

커스텀 임베딩

기본 임베딩 모델 대신 다음과 같은 경우에 사용자 정의 임베딩 함수를 사용하고 싶을 수 있습니다:
  1. 다른 임베딩 모델을 사용하고 싶은 경우 (예: Cohere, HuggingFace, Ollama 모델)
  2. 오픈소스 임베딩 모델을 사용하여 비용을 절감해야 하는 경우
  3. 벡터 차원 또는 임베딩 품질에 대한 특정 요구 사항이 있는 경우
  4. 도메인 특화 임베딩을 사용하고 싶은 경우 (예: 의료 또는 법률 텍스트)
다음은 HuggingFace 모델을 사용하는 예시입니다:

오류 처리

이 도구는 다음과 같은 특정 오류를 처리합니다:
  • qdrant-client가 설치되어 있지 않으면 ImportError를 발생시킵니다 (자동 설치 옵션 제공)
  • QDRANT_URL이 설정되어 있지 않으면 ValueError를 발생시킵니다
  • 누락된 경우 uv add qdrant-client를 사용하여 qdrant-client 설치를 안내합니다

환경 변수

필수 환경 변수: