> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB 벡터 검색 도구

> MongoDBVectorSearchTool은(는) 선택적인 인덱싱 도우미와 함께 MongoDB Atlas에서 벡터 검색을 수행합니다.

# `MongoDBVectorSearchTool`

## 설명

`MongoDBVectorSearchTool`은 MongoDB Atlas 컬렉션에서 벡터 유사도 쿼리를 수행할 수 있게 해줍니다. MongoDB Atlas는
네이티브 벡터 검색을 지원합니다. 이 도구는 또한 인덱스 생성 도우미와 임베딩된 텍스트의 일괄 삽입을 지원합니다.

MongoDB Vector Search는 시맨틱 검색으로 데이터를 쿼리하거나, 컬렉션 내 다른 필드에 대한 필터 쿼리를 수행하거나,
검색 증강 생성(retrieval-augmented generation, RAG)을 구현하여 AI 애플리케이션과 에이전트 시스템을 강화하려는
애플리케이션에 유용합니다.

더 알아보기: [https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/)

## 설치

MongoDB 추가 기능과 함께 설치하세요:

```shell theme={null}
pip install crewai-tools[mongodb]
```

또는

```shell theme={null}
uv add crewai-tools --extra mongodb
```

## 초기화 매개변수

* `connection_string` (str): 필수. 클러스터에 연결하기 위한 MongoDB Atlas 연결 문자열 자격 증명입니다.
* `database_name` (str): 필수. 사용할 MongoDB 데이터베이스의 이름입니다.
* `collection_name` (str): 필수. 문서와 임베딩이 저장되는 데이터베이스 내 컬렉션입니다.
* `vector_index_name` (str, 기본값: `vector_index`): 선택. 쿼리할 MongoDB Vector Search 인덱스의 이름입니다(Atlas에서
  생성한 인덱스와 일치해야 합니다).
* `text_key` (str, 기본값: `text`): 선택. 원본 텍스트가 저장되는 문서 필드명입니다.
* `embedding_key` (str, 기본값: `embedding`): 선택. 벡터 임베딩이 저장되는 문서 필드명입니다.
* `dimensions` (int, 기본값: `1536`): 선택. 임베딩 모델의 차원 수입니다(사용하는 모델과 일치해야 합니다).
* `query_config` (MongoDBVectorSearchConfig): 선택. `limit`, `oversampling_factor` 등 고급 쿼리 설정을 위한
  `MongoDBVectorSearchConfig` 객체입니다.

## MongoDBVectorSearchTool 메서드

* `run(query=...)`: 쿼리를 임베딩하고 벡터 유사도 검색을 수행하여 일치하는 문서를 반환합니다.
  임베딩하고 검색할 자연어 `query` (`str`) 매개변수를 받습니다.
* `add_texts(list of strings)`: 임베딩하여 MongoDB Atlas 데이터베이스에 문서로 삽입할 문자열 목록을 받습니다.
* `create_vector_search_index(dimensions=...)`: 올바른 차원과 유사도를 가진 MongoDB Vector Search 인덱스를
  프로비저닝합니다. `dimensions` (int) 매개변수를 받습니다.

## 빠른 시작

다음 예시는 도구를 초기화하고 지정된 MongoDB Atlas 컬렉션에 대해 벡터 유사도 검색을 실행하는 방법을 보여줍니다:

```python Code theme={null}
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
  connection_string="mongodb+srv://...",
  database_name="mydb",
  collection_name="docs",
)

print(tool.run(query="how to create vector index"))
```

## 일반적인 문제

* 인증 실패: Atlas IP 액세스 목록에 러너가 허용되어 있는지 확인하고, 연결 문자열에 자격 증명이 포함되어 있는지 확인하세요.
* 인덱스를 찾을 수 없음: 벡터 인덱스를 먼저 생성하세요; 이름이 `vector_index_name`과 일치해야 합니다.
* 차원 불일치: 임베딩 모델의 차원을 `dimensions`와 일치시켜야 합니다.

## 예시

### 데이터베이스 미리 로드 및 인덱스 생성

다음 예시는 MongoDB Atlas 데이터베이스에 문서를 미리 로드하고 컬렉션을 쿼리하기 위한 MongoDB Vector Search
인덱스를 생성하는 방법을 보여줍니다:

```python Code theme={null}
import os
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
    database_name="example_database",
    collection_name="example_collection",
    connection_string="<your_mongodb_connection_string>",
    dimensions=3072,
)

# Load text content from a local folder and add to your MongoDB collection
texts = []
for fname in os.listdir("knowledge"):
    path = os.path.join("knowledge", fname)
    if os.path.isfile(path):
        with open(path, "r", encoding="utf-8") as f:
            texts.append(f.read())

tool.add_texts(texts)

# Create the MongoDB Vector Search index (e.g., 3072 dims for text-embedding-3-large)
tool.create_vector_search_index(dimensions=3072)
```

### 사용자 지정 쿼리 구성 및 에이전트 구성

다음 예시는 `MongoDBVectorSearchTool`에 사용자 지정 쿼리 구성을 제공하고 CrewAI 에이전트와 통합하는 방법을
보여줍니다:

```python Code theme={null}
from crewai_tools import MongoDBVectorSearchConfig, MongoDBVectorSearchTool

query_config = MongoDBVectorSearchConfig(limit=10, oversampling_factor=2)
tool = MongoDBVectorSearchTool(
    database_name="example_database",
    collection_name="example_collection",
    connection_string="<your_mongodb_connection_string>",
    query_config=query_config,
    vector_index_name="my_vector_index",
)

rag_agent = Agent(
    name="rag_agent",
    role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.",
    goal="...",
    backstory="...",
    tools=[tool],
)
```

### CrewAI 워크플로우 실행

다음 예시는 `MongoDBVectorSearchTool`을 Agent, Task, Crew와 통합하여 CrewAI 에이전틱 RAG 워크플로우를
생성하고 실행하는 방법을 보여줍니다:

```python Code theme={null}
from crewai import Agent, Task, Crew
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
    connection_string="mongodb+srv://...",
    database_name="mydb",
    collection_name="docs",
)

agent = Agent(
    role="RAG Agent",
    goal="Answer using MongoDB vector search",
    backstory="Knowledge retrieval specialist",
    tools=[tool],
    verbose=True,
)

task = Task(
    description="Find relevant content for 'indexing guidance'",
    expected_output="A concise answer citing the most relevant matches",
    agent=agent,
)

crew = Crew(
    agents=[agent], 
    tasks=[task],
    verbose=True,
)

result = crew.kickoff()
```

## 더 알아보기

CrewAI와 MongoDB 통합에 대해 더 알아보려면 다음 MongoDB 가이드를 참고하세요:

* [MongoDB와 CrewAI 통합하기](https://www.mongodb.com/docs/atlas/ai-integrations/crewai/)
* [CrewAI와 MongoDB로 에이전틱 RAG 애플리케이션 구축하기](https://www.mongodb.com/docs/atlas/ai-integrations/crewai/build-agents/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.