PDF RAG 검색 도구

PDF RAG 검색 도구 (PDFSearchTool)

CrewAI의 PDFSearchTool은 PDF 콘텐츠 안에서 시맨틱 검색(의미 기반 검색)을 수행하는 RAG 도구예요. 검색 쿼리와 PDF 문서를 입력으로 받아 고급 검색 기법으로 관련 콘텐츠를 효율적으로 찾아내서, 큰 PDF 파일에서 특정 정보를 빠르게 추출할 때 특히 유용하답니다.

출처: 문서

본문

PDFSearchTool은 PDF 콘텐츠 내에서 시맨틱 검색을 수행하도록 설계된 RAG 도구입니다. 검색 쿼리와 PDF 문서를 입력받아, 고급 검색 기법으로 관련 콘텐츠를 효율적으로 찾을 수 있어요. 이 덕분에 큰 PDF 파일에서 특정 정보를 빠르게 추출하는 데 특히 유용합니다.

참고: 아직 도구 개선 작업이 진행 중이라, 예상치 못한 동작이나 향후 변경이 있을 수 있어요.

설치 (Installation)

PDFSearchTool을 시작하려면 먼저 crewai_tools 패키지가 설치되어 있는지 확인하세요. 다음 명령으로 설치할 수 있어요.

pip install 'crewai[tools]'

예시 (Example)

PDFSearchTool을 사용해 PDF 문서 안에서 검색하는 방법은 다음과 같습니다.

from crewai_tools import PDFSearchTool

# 실행 중 경로가 제공되면 어떤 PDF 콘텐츠든 검색할 수 있도록 초기화
tool = PDFSearchTool()

# OR

# 특정 PDF 경로로 초기화하면 해당 문서 안에서만 검색
tool = PDFSearchTool(pdf='path/to/your/document.pdf')

인자 (Arguments)

pdf: 선택(Optional) 검색할 PDF 경로예요. 초기화 시점에 제공하거나 run 메서드의 인자로 제공할 수 있습니다. 초기화 시 제공하면 도구는 지정된 문서 안에서만 검색을 수행해요.

커스텀 모델과 임베딩 (Custom model and embeddings)

기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용해요. 모델을 커스터마이즈하려면 다음과 같이 config 딕셔너리를 사용하면 됩니다. 참고: 생성된 임베딩을 저장하고 조회해야 하므로 벡터 데이터베이스가 필수예요.

from crewai_tools import PDFSearchTool

# - embedding_model (필수): provider + provider별 config 선택
# - vectordb (필수): 벡터 DB 선택 및 config 전달

tool = PDFSearchTool(
    config={
        "embedding_model": {
            # 지원 provider: "openai", "azure", "google-generativeai", "google-vertex",
            # "voyageai", "cohere", "huggingface", "jina", "sentence-transformer",
            # "text2vec", "ollama", "openclip", "instructor", "onnx", "roboflow", "watsonx", "custom"
            "provider": "openai",  # or: "google-generativeai", "cohere", "ollama", ...
            "config": {
                # 선택한 provider의 모델 식별자. "model"은 내부적으로 "model_name"으로 자동 매핑됩니다.
                "model": "text-embedding-3-small",
                # 선택: API 키. 생략하면 도구가 provider별 환경변수를 사용합니다.
                # (예: OpenAI의 경우 OPENAI_API_KEY 또는 EMBEDDINGS_OPENAI_API_KEY).
                # "api_key": "sk-...",

                # Provider별 예시:
                # --- Google Generative AI ---
                # (위에서 provider="google-generativeai"로 설정)
                # "model_name": "gemini-embedding-001",
                # "task_type": "RETRIEVAL_DOCUMENT",
                # "title": "Embeddings",

                # --- Cohere ---
                # (위에서 provider="cohere"로 설정)
                # "model": "embed-english-v3.0",

                # --- Ollama (로컬) ---
                # (위에서 provider="ollama"로 설정)
                # "model": "nomic-embed-text",
            },
        },
        "vectordb": {
                    "provider": "chromadb",  # or "qdrant"
                    "config": {
                        # ChromaDB: "settings"(chromadb.config.Settings) 전달 또는 기본값 사용.
                        # 예시 (주석 해제 후 import):
                        # from chromadb.config import Settings
                        # "settings": Settings(
                        #     persist_directory="/content/chroma",
                        #     allow_reset=True,
                        #     is_persistent=True,
                        # ),

                        # Qdrant: "vectors_config"(qdrant_client.models.VectorParams) 전달.
                        # 예시 (주석 해제 후 import):
                        # from qdrant_client.models import VectorParams, Distance
                        # "vectors_config": VectorParams(size=384, distance=Distance.COSINE),

                        # 참고: 컬렉션 이름은 도구가 관리합니다. (기본값: "rag_tool_collection"), 여기서 설정하지 않음.
                    }
        },
    }
)

보안 (Security)

경로 검증 (Path Validation)

이 도구에 제공된 파일 경로는 현재 작업 디렉터리를 기준으로 검증됩니다. 작업 디렉터리 밖으로 벗어나는 경로는 ValueError로 거부되요.

작업 디렉터리 밖의 경로를 허용하려면(예: 테스트나 신뢰할 수 있는 파이프라인에서) 다음 환경변수를 설정하세요.

CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true

URL 검증 (URL Validation)

URL 입력도 검증됩니다. file:// URI와 비공개/예약 IP 대역을 대상으로 하는 요청은 서버사이드 요청 위조(SSRF) 공격을 막기 위해 차단됩니다.

PDF RAG 검색 도구