RAG Tool

RAG Tool

RagTool은 Retrieval-Augmented Generation을 사용해 질문에 답하는 동적 지식 베이스 도구예요.

출처: 문서

본문

RagTool

설명 (Description)

RagTool은 CrewAI의 네이티브 RAG 시스템을 통해 Retrieval-Augmented Generation(RAG)의 힘을 활용해 질문에 답하도록 설계되었어요. 다양한 데이터 소스에서 관련 정보를 검색하기 위해 질의할 수 있는 동적 지식 베이스를 제공합니다. 방대한 정보에 접근해야 하고 맥락에 맞는 답변을 제공해야 하는 애플리케이션에 특히 유용합니다.

예제 (Example)

다음 예제는 도구를 초기화하고 다양한 데이터 소스와 함께 사용하는 방법을 보여줍니다:

from crewai_tools import RagTool

# Create a RAG tool with default settings
rag_tool = RagTool()

# Add content from a file
rag_tool.add(data_type="file", path="path/to/your/document.pdf")

# Add content from a web page
rag_tool.add(data_type="web_page", url="https://example.com")

# Define an agent with the RagTool
@agent
def knowledge_expert(self) -> Agent:
    '''
    This agent uses the RagTool to answer questions about the knowledge base.
    '''
    return Agent(
        config=self.agents_config["knowledge_expert"],
        allow_delegation=False,
        tools=[rag_tool]
    )

지원 데이터 소스 (Supported Data Sources)

RagTool은 매우 다양한 데이터 소스와 함께 사용할 수 있습니다:

  • 📰 PDF 파일
  • 📊 CSV 파일
  • 📃 JSON 파일
  • 📝 텍스트
  • 📁 디렉터리/폴더
  • 🌐 HTML 웹 페이지
  • 📽️ YouTube 채널
  • 📺 YouTube 동영상
  • 📚 문서 웹사이트
  • 📝 MDX 파일
  • 📄 DOCX 파일
  • 🧾 XML 파일
  • 📬 Gmail
  • 📝 GitHub 저장소
  • 🐘 PostgreSQL 데이터베이스
  • 🐬 MySQL 데이터베이스
  • 🤖 Slack 대화
  • 💬 Discord 메시지
  • 🗨️ Discourse 포럼
  • 📝 Substack 뉴스레터
  • 🐝 Beehiiv 콘텐츠
  • 💾 Dropbox 파일
  • 🖼️ 이미지
  • ⚙️ 커스텀 데이터 소스

파라미터 (Parameters)

RagTool은 다음 파라미터를 받습니다:

  • summarize: 선택. 검색된 콘텐츠를 요약할지 여부. 기본값은 False.
  • adapter: 선택. 지식 베이스용 커스텀 어댑터. 제공되지 않으면 CrewAIRagAdapter가 사용됩니다.
  • config: 선택. 내부 CrewAI RAG 시스템 설정. 선택적 embedding_model(ProviderSpec)과 vectordb(VectorDbConfig) 키를 가진 RagToolConfig TypedDict를 받습니다. 프로그래밍 방식으로 제공된 모든 설정 값이 환경 변수보다 우선합니다.

콘텐츠 추가하기 (Adding Content)

add 메서드를 사용해 지식 베이스에 콘텐츠를 추가할 수 있어요:

# Add a PDF file
rag_tool.add(data_type="file", path="path/to/your/document.pdf")

# Add a web page
rag_tool.add(data_type="web_page", url="https://example.com")

# Add a YouTube video
rag_tool.add(data_type="youtube_video", url="https://www.youtube.com/watch?v=VIDEO_ID")

# Add a directory of files
rag_tool.add(data_type="directory", path="path/to/your/directory")

에이전트 통합 예제 (Agent Integration Example)

RagTool을 CrewAI 에이전트와 통합하는 방법은 다음과 같습니다:

from crewai import Agent
from crewai.project import agent
from crewai_tools import RagTool

# Initialize the tool and add content
rag_tool = RagTool()
rag_tool.add(data_type="web_page", url="https://docs.crewai.com")
rag_tool.add(data_type="file", path="company_data.pdf")

# Define an agent with the RagTool
@agent
def knowledge_expert(self) -> Agent:
    return Agent(
        config=self.agents_config["knowledge_expert"],
        allow_delegation=False,
        tools=[rag_tool]
    )

고급 설정 (Advanced Configuration)

설정 딕셔너리를 제공해 RagTool의 동작을 커스터마이즈할 수 있어요:

from crewai_tools import RagTool
from crewai_tools.tools.rag import RagToolConfig, VectorDbConfig, ProviderSpec

# Create a RAG tool with custom configuration

vectordb: VectorDbConfig = {
    "provider": "qdrant",
    "config": {
        "collection_name": "my-collection"
    }
}

embedding_model: ProviderSpec = {
    "provider": "openai",
    "config": {
        "model_name": "text-embedding-3-small"
    }
}

config: RagToolConfig = {
    "vectordb": vectordb,
    "embedding_model": embedding_model
}

rag_tool = RagTool(config=config, summarize=True)

임베딩 모델 설정 (Embedding Model Configuration)

embedding_model 파라미터는 다음 구조의 crewai.rag.embeddings.types.ProviderSpec 딕셔너리를 받습니다:

{
    "provider": "provider-name",  # Required
    "config": {                    # Optional
        # Provider-specific configuration
    }
}
지원 프로바이더 (Supported Providers)

OpenAI

from crewai.rag.embeddings.providers.openai.types import OpenAIProviderSpec

embedding_model: OpenAIProviderSpec = {
    "provider": "openai",
    "config": {
        "api_key": "your-api-key",
        "model_name": "text-embedding-ada-002",
        "dimensions": 1536,
        "organization_id": "your-org-id",
        "api_base": "https://api.openai.com/v1",
        "api_version": "v1",
        "default_headers": {"Custom-Header": "value"}
    }
}

설정 옵션:

  • api_key (str): OpenAI API 키
  • model_name (str): 사용할 모델. 기본값: text-embedding-ada-002. 옵션: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
  • dimensions (int): 임베딩 차원 수
  • organization_id (str): OpenAI 조직 ID
  • api_base (str): 커스텀 API 기본 URL
  • api_version (str): API 버전
  • default_headers (dict): API 요청용 커스텀 헤더

환경 변수:

  • OPENAI_API_KEY 또는 EMBEDDINGS_OPENAI_API_KEY: api_key
  • OPENAI_ORGANIZATION_ID 또는 EMBEDDINGS_OPENAI_ORGANIZATION_ID: organization_id
  • OPENAI_MODEL_NAME 또는 EMBEDDINGS_OPENAI_MODEL_NAME: model_name
  • OPENAI_API_BASE 또는 EMBEDDINGS_OPENAI_API_BASE: api_base
  • OPENAI_API_VERSION 또는 EMBEDDINGS_OPENAI_API_VERSION: api_version
  • OPENAI_DIMENSIONS 또는 EMBEDDINGS_OPENAI_DIMENSIONS: dimensions

Cohere

from crewai.rag.embeddings.providers.cohere.types import CohereProviderSpec

embedding_model: CohereProviderSpec = {
    "provider": "cohere",
    "config": {
        "api_key": "your-api-key",
        "model_name": "embed-english-v3.0"
    }
}

설정 옵션:

  • api_key (str): Cohere API 키
  • model_name (str): 사용할 모델. 기본값: large. 옵션: embed-english-v3.0, embed-multilingual-v3.0, large, small

환경 변수:

  • COHERE_API_KEY 또는 EMBEDDINGS_COHERE_API_KEY: api_key
  • EMBEDDINGS_COHERE_MODEL_NAME: model_name

VoyageAI

from crewai.rag.embeddings.providers.voyageai.types import VoyageAIProviderSpec

embedding_model: VoyageAIProviderSpec = {
    "provider": "voyageai",
    "config": {
        "api_key": "your-api-key",
        "model": "voyage-3",
        "input_type": "document",
        "truncation": True,
        "output_dtype": "float32",
        "output_dimension": 1024,
        "max_retries": 3,
        "timeout": 60.0
    }
}

설정 옵션:

  • api_key (str): VoyageAI API 키
  • model (str): 사용할 모델. 기본값: voyage-2. 옵션: voyage-3, voyage-3-lite, voyage-code-3, voyage-large-2
  • input_type (str): 입력 유형. 옵션: document(저장용), query(검색용)
  • truncation (bool): 최대 길이를 초과하는 입력을 잘라낼지 여부. 기본값: True
  • output_dtype (str): 출력 데이터 타입
  • output_dimension (int): 출력 임베딩의 차원
  • max_retries (int): 최대 재시도 횟수. 기본값: 0
  • timeout (float): 요청 타임아웃(초)

환경 변수:

  • VOYAGEAI_API_KEY 또는 EMBEDDINGS_VOYAGEAI_API_KEY: api_key
  • VOYAGEAI_MODEL 또는 EMBEDDINGS_VOYAGEAI_MODEL: model
  • VOYAGEAI_INPUT_TYPE 또는 EMBEDDINGS_VOYAGEAI_INPUT_TYPE: input_type
  • VOYAGEAI_TRUNCATION 또는 EMBEDDINGS_VOYAGEAI_TRUNCATION: truncation
  • VOYAGEAI_OUTPUT_DTYPE 또는 EMBEDDINGS_VOYAGEAI_OUTPUT_DTYPE: output_dtype
  • VOYAGEAI_OUTPUT_DIMENSION 또는 EMBEDDINGS_VOYAGEAI_OUTPUT_DIMENSION: output_dimension
  • VOYAGEAI_MAX_RETRIES 또는 EMBEDDINGS_VOYAGEAI_MAX_RETRIES: max_retries
  • VOYAGEAI_TIMEOUT 또는 EMBEDDINGS_VOYAGEAI_TIMEOUT: timeout

Ollama

from crewai.rag.embeddings.providers.ollama.types import OllamaProviderSpec

embedding_model: OllamaProviderSpec = {
    "provider": "ollama",
    "config": {
        "model_name": "llama2",
        "url": "http://localhost:11434/api/embeddings"
    }
}

설정 옵션:

  • model_name (str): Ollama 모델 이름 (예: llama2, mistral, nomic-embed-text)
  • url (str): Ollama API 엔드포인트 URL. 기본값: http://localhost:11434/api/embeddings

환경 변수:

  • OLLAMA_MODEL 또는 EMBEDDINGS_OLLAMA_MODEL: model_name
  • OLLAMA_URL 또는 EMBEDDINGS_OLLAMA_URL: url

Amazon Bedrock

from crewai.rag.embeddings.providers.aws.types import BedrockProviderSpec

embedding_model: BedrockProviderSpec = {
    "provider": "amazon-bedrock",
    "config": {
        "model_name": "amazon.titan-embed-text-v2:0",
        "session": boto3_session
    }
}

설정 옵션:

  • model_name (str): Bedrock 모델 ID. 기본값: amazon.titan-embed-text-v1. 옵션: amazon.titan-embed-text-v1, amazon.titan-embed-text-v2:0, cohere.embed-english-v3, cohere.embed-multilingual-v3
  • session (Any): AWS 인증용 Boto3 세션 객체

환경 변수:

  • AWS_ACCESS_KEY_ID: AWS 액세스 키
  • AWS_SECRET_ACCESS_KEY: AWS 시크릿 키
  • AWS_REGION: AWS 리전 (예: us-east-1)

Azure OpenAI

from crewai.rag.embeddings.providers.microsoft.types import AzureProviderSpec

embedding_model: AzureProviderSpec = {
    "provider": "azure",
    "config": {
        "deployment_id": "your-deployment-id",
        "api_key": "your-api-key",
        "api_base": "https://your-resource.openai.azure.com",
        "api_version": "2024-02-01",
        "model_name": "text-embedding-ada-002",
        "api_type": "azure"
    }
}

설정 옵션:

  • deployment_id (str): 필수 — Azure OpenAI 배포 ID
  • api_key (str): Azure OpenAI API 키
  • api_base (str): Azure OpenAI 리소스 엔드포인트
  • api_version (str): API 버전. 예: 2024-02-01
  • model_name (str): 모델 이름. 기본값: text-embedding-ada-002
  • api_type (str): API 유형. 기본값: azure
  • dimensions (int): 출력 차원
  • default_headers (dict): 커스텀 헤더

환경 변수:

  • AZURE_OPENAI_API_KEY 또는 EMBEDDINGS_AZURE_API_KEY: api_key
  • AZURE_OPENAI_ENDPOINT 또는 EMBEDDINGS_AZURE_API_BASE: api_base
  • EMBEDDINGS_AZURE_DEPLOYMENT_ID: deployment_id
  • EMBEDDINGS_AZURE_API_VERSION: api_version
  • EMBEDDINGS_AZURE_MODEL_NAME: model_name
  • EMBEDDINGS_AZURE_API_TYPE: api_type
  • EMBEDDINGS_AZURE_DIMENSIONS: dimensions

Google Generative AI

from crewai.rag.embeddings.providers.google.types import GenerativeAiProviderSpec

embedding_model: GenerativeAiProviderSpec = {
    "provider": "google-generativeai",
    "config": {
        "api_key": "your-api-key",
        "model_name": "gemini-embedding-001",
        "task_type": "RETRIEVAL_DOCUMENT"
    }
}

설정 옵션:

  • api_key (str): Google AI API 키
  • model_name (str): 모델 이름. 기본값: gemini-embedding-001. 옵션: gemini-embedding-001, text-embedding-005, text-multilingual-embedding-002
  • task_type (str): 임베딩용 태스크 유형. 기본값: RETRIEVAL_DOCUMENT. 옵션: RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY

환경 변수:

  • GOOGLE_API_KEY, GEMINI_API_KEY 또는 EMBEDDINGS_GOOGLE_API_KEY: api_key
  • EMBEDDINGS_GOOGLE_GENERATIVE_AI_MODEL_NAME: model_name
  • EMBEDDINGS_GOOGLE_GENERATIVE_AI_TASK_TYPE: task_type

Google Vertex AI

from crewai.rag.embeddings.providers.google.types import VertexAIProviderSpec

embedding_model: VertexAIProviderSpec = {
    "provider": "google-vertex",
    "config": {
        "model_name": "text-embedding-004",
        "project_id": "your-project-id",
        "region": "us-central1",
        "api_key": "your-api-key"
    }
}

설정 옵션:

  • model_name (str): 모델 이름. 기본값: textembedding-gecko. 옵션: text-embedding-004, textembedding-gecko, textembedding-gecko-multilingual
  • project_id (str): Google Cloud 프로젝트 ID. 기본값: cloud-large-language-models
  • region (str): Google Cloud 리전. 기본값: us-central1
  • api_key (str): 인증용 API 키

환경 변수:

  • GOOGLE_APPLICATION_CREDENTIALS: 서비스 계정 JSON 파일 경로
  • GOOGLE_CLOUD_PROJECT 또는 EMBEDDINGS_GOOGLE_VERTEX_PROJECT_ID: project_id
  • EMBEDDINGS_GOOGLE_VERTEX_MODEL_NAME: model_name
  • EMBEDDINGS_GOOGLE_VERTEX_REGION: region
  • EMBEDDINGS_GOOGLE_VERTEX_API_KEY: api_key

Jina AI

from crewai.rag.embeddings.providers.jina.types import JinaProviderSpec

embedding_model: JinaProviderSpec = {
    "provider": "jina",
    "config": {
        "api_key": "your-api-key",
        "model_name": "jina-embeddings-v3"
    }
}

설정 옵션:

  • api_key (str): Jina AI API 키
  • model_name (str): 모델 이름. 기본값: jina-embeddings-v2-base-en. 옵션: jina-embeddings-v3, jina-embeddings-v2-base-en, jina-embeddings-v2-small-en

환경 변수:

  • JINA_API_KEY 또는 EMBEDDINGS_JINA_API_KEY: api_key
  • EMBEDDINGS_JINA_MODEL_NAME: model_name

HuggingFace

from crewai.rag.embeddings.providers.huggingface.types import HuggingFaceProviderSpec

embedding_model: HuggingFaceProviderSpec = {
    "provider": "huggingface",
    "config": {
        "url": "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2"
    }
}

설정 옵션:

  • url (str): HuggingFace inference API 엔드포인트 전체 URL

환경 변수:

  • HUGGINGFACE_URL 또는 EMBEDDINGS_HUGGINGFACE_URL: url

Instructor

from crewai.rag.embeddings.providers.instructor.types import InstructorProviderSpec

embedding_model: InstructorProviderSpec = {
    "provider": "instructor",
    "config": {
        "model_name": "hkunlp/instructor-xl",
        "device": "cuda",
        "instruction": "Represent the document"
    }
}

설정 옵션:

  • model_name (str): HuggingFace 모델 ID. 기본값: hkunlp/instructor-base. 옵션: hkunlp/instructor-xl, hkunlp/instructor-large, hkunlp/instructor-base
  • device (str): 실행할 디바이스. 기본값: cpu. 옵션: cpu, cuda, mps, xpu
  • instruction (str): 임베딩용 인스트럭션 접두사

환경 변수:

  • EMBEDDINGS_INSTRUCTOR_MODEL_NAME: model_name
  • EMBEDDINGS_INSTRUCTOR_DEVICE: device
  • EMBEDDINGS_INSTRUCTOR_INSTRUCTION: instruction

Sentence Transformer

from crewai.rag.embeddings.providers.sentence_transformer.types import SentenceTransformerProviderSpec

embedding_model: SentenceTransformerProviderSpec = {
    "provider": "sentence-transformer",
    "config": {
        "model_name": "all-mpnet-base-v2",
        "device": "cuda",
        "normalize_embeddings": True
    }
}

설정 옵션:

  • model_name (str): Sentence Transformers 모델 이름. 기본값: all-MiniLM-L6-v2. 옵션: all-mpnet-base-v2, all-MiniLM-L6-v2, paraphrase-multilingual-MiniLM-L12-v2
  • device (str): 실행할 디바이스. 기본값: cpu. 옵션: cpu, cuda, mps, xpu
  • normalize_embeddings (bool): 임베딩을 정규화할지 여부. 기본값: False

환경 변수:

  • EMBEDDINGS_SENTENCE_TRANSFORMER_MODEL_NAME: model_name
  • EMBEDDINGS_SENTENCE_TRANSFORMER_DEVICE: device
  • EMBEDDINGS_SENTENCE_TRANSFORMER_NORMALIZE_EMBEDDINGS: normalize_embeddings

ONNX

from crewai.rag.embeddings.providers.onnx.types import ONNXProviderSpec

embedding_model: ONNXProviderSpec = {
    "provider": "onnx",
    "config": {
        "preferred_providers": ["CUDAExecutionProvider", "CPUExecutionProvider"]
    }
}

설정 옵션:

  • preferred_providers (list[str]): 선호 순서대로 정렬된 ONNX 실행 프로바이더 목록

환경 변수:

  • EMBEDDINGS_ONNX_PREFERRED_PROVIDERS: preferred_providers (쉼표로 구분된 목록)

OpenCLIP

from crewai.rag.embeddings.providers.openclip.types import OpenCLIPProviderSpec

embedding_model: OpenCLIPProviderSpec = {
    "provider": "openclip",
    "config": {
        "model_name": "ViT-B-32",
        "checkpoint": "laion2b_s34b_b79k",
        "device": "cuda"
    }
}

설정 옵션:

  • model_name (str): OpenCLIP 모델 아키텍처. 기본값: ViT-B-32. 옵션: ViT-B-32, ViT-B-16, ViT-L-14
  • checkpoint (str): 사전학습 체크포인트 이름. 기본값: laion2b_s34b_b79k. 옵션: laion2b_s34b_b79k, laion400m_e32, openai
  • device (str): 실행할 디바이스. 기본값: cpu. 옵션: cpu, cuda

환경 변수:

  • EMBEDDINGS_OPENCLIP_MODEL_NAME: model_name
  • EMBEDDINGS_OPENCLIP_CHECKPOINT: checkpoint
  • EMBEDDINGS_OPENCLIP_DEVICE: device

Text2Vec

from crewai.rag.embeddings.providers.text2vec.types import Text2VecProviderSpec

embedding_model: Text2VecProviderSpec = {
    "provider": "text2vec",
    "config": {
        "model_name": "shibing624/text2vec-base-multilingual"
    }
}

설정 옵션:

  • model_name (str): HuggingFace의 Text2Vec 모델 이름. 기본값: shibing624/text2vec-base-chinese. 옵션: shibing624/text2vec-base-multilingual, shibing624/text2vec-base-chinese

환경 변수:

  • EMBEDDINGS_TEXT2VEC_MODEL_NAME: model_name

Roboflow

from crewai.rag.embeddings.providers.roboflow.types import RoboflowProviderSpec

embedding_model: RoboflowProviderSpec = {
    "provider": "roboflow",
    "config": {
        "api_key": "your-api-key",
        "api_url": "https://infer.roboflow.com"
    }
}

설정 옵션:

  • api_key (str): Roboflow API 키. 기본값: "" (빈 문자열)
  • api_url (str): Roboflow inference API URL. 기본값: https://infer.roboflow.com

환경 변수:

  • ROBOFLOW_API_KEY 또는 EMBEDDINGS_ROBOFLOW_API_KEY: api_key
  • ROBOFLOW_API_URL 또는 EMBEDDINGS_ROBOFLOW_API_URL: api_url

WatsonX (IBM)

from crewai.rag.embeddings.providers.ibm.types import WatsonXProviderSpec

embedding_model: WatsonXProviderSpec = {
    "provider": "watsonx",
    "config": {
        "model_id": "ibm/slate-125m-english-rtrvr",
        "url": "https://us-south.ml.cloud.ibm.com",
        "api_key": "your-api-key",
        "project_id": "your-project-id",
        "batch_size": 100,
        "concurrency_limit": 10,
        "persistent_connection": True
    }
}

설정 옵션:

  • model_id (str): WatsonX 모델 식별자
  • url (str): WatsonX API 엔드포인트
  • api_key (str): IBM Cloud API 키
  • project_id (str): WatsonX 프로젝트 ID
  • space_id (str): WatsonX 스페이스 ID (project_id의 대안)
  • batch_size (int): 임베딩 배치 크기. 기본값: 100
  • concurrency_limit (int): 최대 동시 요청 수. 기본값: 10
  • persistent_connection (bool): 영구 연결 사용. 기본값: True
  • 그 외 20개 이상의 추가 인증·설정 옵션

환경 변수:

  • WATSONX_API_KEY 또는 EMBEDDINGS_WATSONX_API_KEY: api_key
  • WATSONX_URL 또는 EMBEDDINGS_WATSONX_URL: url
  • WATSONX_PROJECT_ID 또는 EMBEDDINGS_WATSONX_PROJECT_ID: project_id
  • EMBEDDINGS_WATSONX_MODEL_ID: model_id
  • EMBEDDINGS_WATSONX_SPACE_ID: space_id
  • EMBEDDINGS_WATSONX_BATCH_SIZE: batch_size
  • EMBEDDINGS_WATSONX_CONCURRENCY_LIMIT: concurrency_limit
  • EMBEDDINGS_WATSONX_PERSISTENT_CONNECTION: persistent_connection

Custom

from crewai.rag.core.base_embeddings_callable import EmbeddingFunction
from crewai.rag.embeddings.providers.custom.types import CustomProviderSpec

class MyEmbeddingFunction(EmbeddingFunction):
    def __call__(self, input):
        # Your custom embedding logic
        return embeddings

embedding_model: CustomProviderSpec = {
    "provider": "custom",
    "config": {
        "embedding_callable": MyEmbeddingFunction
    }
}

설정 옵션:

  • embedding_callable (type[EmbeddingFunction]): 커스텀 임베딩 함수 클래스

참고: 커스텀 임베딩 함수는 crewai.rag.core.base_embeddings_callable에 정의된 EmbeddingFunction 프로토콜을 구현해야 합니다. __call__ 메서드는 입력 데이터를 받고 임베딩을 numpy 배열 리스트(또는 정규화될 호환 형식)로 반환해야 합니다. 반환된 임베딩은 자동으로 정규화되고 검증됩니다.

참고 사항 (Notes)
  • 필수로 표시되지 않은 한 모든 설정 필드는 선택 사항입니다
  • API 키는 일반적으로 config 대신 환경 변수로 제공할 수 있습니다
  • 적용 가능한 경우 기본값이 표시됩니다

결론 (Conclusion)

RagTool은 다양한 데이터 소스에서 지식 베이스를 만들고 질의하는 강력한 방법을 제공합니다. Retrieval-Augmented Generation을 활용해 에이전트가 관련 정보에 효율적으로 접근하고 검색할 수 있게 하며, 정확하고 맥락에 맞는 응답을 제공하는 능력을 향상시킵니다.

더 알아보기 (Learn more)