RAG 工具

RagTool

描述

RagTool 旨在借助 CrewAI 原生 RAG 系统的检索增强生成（RAG）能力来回答问题。 它提供了一个可以查询的动态知识库，用于从各种数据源中检索相关信息。 这个工具尤其适合需要访问海量信息并提供上下文相关答案的应用场景。

示例

下面的示例展示了如何初始化该工具并将其与不同数据源一起使用：

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]
    )

支持的数据源

RagTool 可与广泛的数据源配合使用，包括：

• 📰 PDF 文件
• 📊 CSV 文件
• 📃 JSON 文件
• 📝 文本
• 📁 目录/文件夹
• 🌐 HTML 网页
• 📽️ YouTube 频道
• 📺 YouTube 视频
• 📚 文档网站
• 📝 MDX 文件
• 📄 DOCX 文件
• 🧾 XML 文件
• 📬 Gmail
• 📝 GitHub repositories
• 🐘 PostgreSQL databases
• 🐬 MySQL databases
• 🤖 Slack conversations
• 💬 Discord messages
• 🗨️ Discourse forums
• 📝 Substack newsletters
• 🐝 Beehiiv content
• 💾 Dropbox files
• 🖼️ 图片
• ⚙️ 自定义数据源

参数

RagTool 接受以下参数：

• summarize：可选。是否对检索到的内容进行总结。默认值为 False。
• adapter：可选。知识库的自定义 adapter。如果未提供，将使用 CrewAIRagAdapter。
• config：可选。底层 CrewAI RAG 系统的配置。接受一个 RagToolConfig TypedDict，其中可选键包括 embedding_model（ProviderSpec）和 vectordb（VectorDbConfig）。通过程序传入的所有配置值优先于环境变量。

添加内容

你可以使用 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 集成示例

下面展示如何将 RagTool 集成到 CrewAI agent 中：

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]
    )

高级配置

你可以通过提供配置字典来自定义 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 模型配置

embedding_model 参数接受一个 crewai.rag.embeddings.types.ProviderSpec 字典，结构如下：

{
    "provider": "provider-name",  # Required
    "config": {                    # Optional
        # Provider-specific configuration
    }
}

支持的提供商

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 key
• model_name (str)：要使用的模型。默认值：text-embedding-ada-002。可选项：text-embedding-3-small、text-embedding-3-large、text-embedding-ada-002
• dimensions (int)：embedding 的维度数量
• organization_id (str)：OpenAI organization ID
• api_base (str)：自定义 API base URL
• api_version (str)：API 版本
• default_headers (dict)：API 请求的自定义 headers

环境变量：

• 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 key
• 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 key
• 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)：输出 embedding 的维度
• 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 endpoint 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 model 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 session 对象

环境变量：

• AWS_ACCESS_KEY_ID：AWS access key
• AWS_SECRET_ACCESS_KEY：AWS secret key
• AWS_REGION：AWS region（例如 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 deployment ID
• api_key (str)：Azure OpenAI API key
• api_base (str)：Azure OpenAI 资源 endpoint
• api_version (str)：API 版本。示例：2024-02-01
• model_name (str)：模型名称。默认值：text-embedding-ada-002
• api_type (str)：API 类型。默认值：azure
• dimensions (int)：输出维度
• default_headers (dict)：自定义 headers

环境变量：

• 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 key
• model_name (str)：模型名称。默认值：gemini-embedding-001。可选项：gemini-embedding-001、text-embedding-005、text-multilingual-embedding-002
• task_type (str)：embedding 的任务类型。默认值：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 project ID。默认值：cloud-large-language-models
• region (str)：Google Cloud region。默认值：us-central1
• api_key (str)：认证用 API key

环境变量：

• GOOGLE_APPLICATION_CREDENTIALS：service account 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 key
• 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 endpoint 的完整 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
• instruction (str)：embedding 的指令前缀

环境变量：

• 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
• normalize_embeddings (bool)：是否规范化 embeddings。默认值：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 执行 providers 列表

环境变量：

• 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)：预训练 checkpoint 名称。默认值：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 key。默认值：""（空字符串）
• 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 model identifier
• url (str)：WatsonX API endpoint
• api_key (str)：IBM Cloud API key
• project_id (str)：WatsonX project ID
• space_id (str)：WatsonX space ID（可替代 project_id）
• batch_size (int)：embedding 批量大小。默认值：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])：自定义 embedding 函数类

注意： 自定义 embedding 函数必须实现 crewai.rag.core.base_embeddings_callable 中定义的 EmbeddingFunction 协议。__call__ 方法应接受输入数据并返回一个 numpy arrays 列表形式的 embeddings（或可兼容格式，系统会进行规范化）。返回的 embeddings 会自动被规范化并验证。

说明

• 除非标记为 Required，否则所有配置字段都是可选的
• API keys 通常可以通过环境变量提供，而不必写进配置
• 适用时会显示默认值

结论

RagTool 提供了一种强大的方式，可从各种数据源创建和查询知识库。借助检索增强生成，它使 agents 能够高效访问并检索相关信息，从而提升其提供准确且符合上下文的响应的能力。