MongoDB Agno 프레임워크와 통합

MongoDB 멀티모달 AI 에이전트 구축을 위한 오픈 소스 Python 프레임워크 인 Agno와 통합할 수 있습니다. Agno는 두 가지 MongoDB 통합을 제공합니다.

에이전트의 지식창고를 저장하고 MongoDB Vector Search로 검색하는벡터 데이터베이스 입니다.
에이전트 세션, 사용자 메모리, 지표 및 평가 실행을 유지하는 세션및 메모리 데이터베이스 MongoDB 컬렉션에서 실행됩니다.

두 통합 중 하나를 단독으로 사용하거나 동일한 에이전트 에서 둘 다 사용할 수 있습니다.

시작하기

MongoDB 사용하도록 Agno를 구성하는 튜토리얼을 완료하려면 MongoDB Agno 통합 시작하기를 참조하세요.

설치

Agno에는 Python v3.9 이상이 필요합니다. 최신 Agno 및 PyMongo 버전을 설치하려면 다음 명령을 실행 .

pip install agno pymongo

이 페이지의 예제에서는 Agno가 기본값 으로 사용하는 OpenAI 모델을 사용합니다. OpenAI 클라이언트 라이브러리를 설치하려면 다음 명령을 실행 .

pip install openai

이 페이지의 Custom configuration 예시에서는 Voyage AI 임베딩을 사용합니다. Voyage AI 클라이언트 라이브러리를 설치하려면 다음 명령을 실행 .

pip install voyageai

환경 변수

이 페이지의 예제를 실행 전에 다음 환경 변수를 설정하다 .

연결 문자열: MONGODB_URI을(를) MongoDB deployment 의 연결 문자열 로 설정합니다.
모델 API 키: OPENAI_API_KEY 또는 VOYAGE_API_KEY를 모델 제공자 의 API 키로 설정합니다.

벡터 데이터베이스

MongoVectorDb 클래스는 MongoDB Vector Search를 사용하여 Agno 벡터 데이터베이스 인터페이스를 구현합니다. 에이전트 에 문서에 대한 시맨틱 검색 제공하려면 이 클래스의 인스턴스 를 Agno Knowledge 객체 의 vector_db 매개변수에 전달한 다음, 해당 객체 에이전트 의 knowledge 매개변수에 전달합니다.

중요

MongoDB 클래스 이름

Agno는 두 MongoDB 클래스의 이름을 MongoDb으로 지정하지만 다른 모듈에서 가져옵니다. agno.vectordb.mongodb에서 벡터 데이터베이스 클래스를 가져오고 agno.db.mongo에서 데이터베이스 클래스를 가져옵니다. 이름 충돌을 방지하기 위해 Agno는 벡터 데이터베이스 클래스도 MongoVectorDb로 내보냅니다. 이 페이지의 예제에서는 해당 별칭을 사용합니다.

Basic initialization 탭 선택하여 최소 구성 예시 보거나 Custom configuration 탭 선택하여 사용자 지정 설정으로 통합을 구성하는 방법을 확인합니다.

벡터 데이터베이스 초기화하려면 임베딩과 MongoDB 연결 문자열 저장하는 컬렉션 을 지정합니다. 다음 예시 지식창고를 생성하고, 문서 추가하고, 에이전트 에게 데이터에 대한 액세스 부여합니다.

import os
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
vector_db = MongoVectorDb(
    collection_name="agent_knowledge",
    db_url=os.environ["MONGODB_URI"],
    database="agno",
)
knowledge = Knowledge(vector_db=vector_db)
knowledge.insert(
    name="Recipes",
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
)
agent = Agent(knowledge=knowledge, search_knowledge=True)

다음 예시 하이브리드 검색 활성화하고, OpenAI 기본값 대신 Voyage AI 사용하여 임베딩을 생성하고, MongoDB Vector Search 인덱스 이름을 지정합니다.

import os
from agno.agent import Agent
from agno.knowledge.embedder.voyageai import VoyageAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
from agno.vectordb.search import SearchType
embedder = VoyageAIEmbedder(
    id="voyage-4-large",
    dimensions=1024,
    api_key=os.environ["VOYAGE_API_KEY"],
    request_params={"output_dimension": 1024},
)
vector_db = MongoVectorDb(
    collection_name="agent_knowledge",
    db_url=os.environ["MONGODB_URI"],
    database="agno",
    embedder=embedder,
    search_type=SearchType.hybrid,
    hybrid_vector_weight=0.7,
    hybrid_keyword_weight=0.3,
    search_index_name="agno_vector_index",
)
knowledge = Knowledge(vector_db=vector_db)
agent = Agent(knowledge=knowledge, search_knowledge=True)

임베더를 지정하면 Agno는 MongoDB Vector Search 인덱스 생성할 때 임베더가 생성하는 차원 수를 사용합니다. request_params 사전은 제공자별 키워드 인수를 임베딩 호출에 전달합니다. Voyage AI 의 경우 output_dimension은(는) 가변 차원을 지원 모델에 대해 반환되는 벡터의 크기를 제어합니다.

Knowledge 객체 생성하면 Agno는 컬렉션 이미 존재하는지 확인합니다. 그렇지 않은 경우 Agno는 컬렉션 과 MongoDB Vector Search 인덱스 생성합니다. 컬렉션 있는 경우 별도로 삭제했더라도 Agno는 인덱스 존재 여부를 확인하지 않습니다.

인덱스 만든 후 Agno는 인덱스 컬렉션 에 나타날 때까지 기다립니다. 그러나 인덱스 상태를 확인하지 않으므로 직후에 실행되는 쿼리 인덱스 작성이 완료되는 동안 결과를 반환하지 않을 수 있습니다.

벡터 데이터베이스 매개변수

이 매개변수를 사용하여 벡터 데이터베이스 구성합니다.

MongoVectorDb 클래스는 다음 매개변수를 허용합니다:

Parameter	필요성	설명
`collection_name`	필수 사항	문서와 해당 임베딩을 저장하는 컬렉션 의 이름입니다.
`db_url`	옵션	MongoDB deployment 에 대한 연결 문자열 . 기본값은 `mongodb://localhost:27017/` 입니다. 연결 문자열 찾는 방법에 대해 자세히 학습 클라이언트 라이브러리를 통해 클러스터에 연결하기를 참조하세요.
`client`	옵션	기존 `MongoClient` 인스턴스 입니다. 이 매개변수를 지정하면 Agno는 `db_url`을 무시합니다.
`database`	옵션	컬렉션 을 보유하는 데이터베이스 의 이름입니다. 기본값은 `agno`입니다.
`embedder`	옵션	Agno가 문서와 쿼리를 임베드하는 데 사용하는 임베딩 모델입니다. 기본값은 `OpenAIEmbedder()`입니다.
`distance_metric`	옵션	MongoDB Vector Search 인덱스 사용하는 유사성 함수입니다. 현재 기본값 인 `Distance.cosine`만 지원됩니다.
`search_type`	옵션	검색 전략. `SearchType.vector` 또는 `SearchType.hybrid`을 허용합니다. 기본값은 `SearchType.vector`입니다.
`hybrid_vector_weight`	옵션	하이브리드 검색 이 시맨틱 결과에 적용하는 가중치입니다. 기본값은 `0.5`입니다.
`hybrid_keyword_weight`	옵션	하이브리드 검색 이 키워드 결과에 적용되는 가중치입니다. 기본값은 `0.5`입니다.
`hybrid_rank_constant`	옵션	하이브리드 검색 상호 순위 통합 점수를 계산하기 전에 각 순위에 추가하는 상수입니다. 기본값은 `60`입니다.
`search_index_name`	옵션	컬렉션 에 있는 MongoDB Vector Search 인덱스 의 이름입니다. 기본값은 `vector_index_1`입니다.
`wait_until_index_ready_in_seconds`	옵션	Agno가 MongoDB Vector Search 인덱스 생성한 후 인덱스 이름이 컬렉션의 검색 인덱스에 나타날 때까지 기다릴지 여부입니다. 기다리려면 이 매개변수를 양수로 설정하고, 대기를 건너뛰려면 `None`로 설정합니다. 비동기 메서드는 이 값을 초 단위의 시간 제한으로 사용합니다. 기본값은 `3`입니다.
`wait_after_insert_in_seconds`	옵션	Agno가 문서를 삽입한 후 대기하는 시간(초)입니다. 기본값은 `3`입니다.
`max_pool_size`	옵션	운전자 연결 풀 의 최대 연결 수입니다. 기본값은 `100`입니다.
`retry_writes`	옵션	운전자 지원되는 쓰기 (write) 작업을 재시도할지 여부입니다. 기본값은 `True`입니다.
`cosmos_compatibility`	옵션	Agno가 MongoDB Vector Search 형식 대신 Azure Cosmos DB for MongoDB vCore 형식으로 인덱스를 생성할지 여부입니다. 기본값은 `False`입니다.
`name`, `description`, `id`	옵션	벡터 데이터베이스 인스턴스 의 식별 메타데이터 . `id`를 지정하지 않으면 Agno는 연결 문자열, 데이터베이스 이름 및 컬렉션 이름에서 이를 파생합니다.

벡터 데이터베이스 메서드

Knowledge 클래스는 지식창고에 콘텐츠를 추가하거나 에이전트 콘텐츠를 검색할 때 다음 메서드를 호출합니다. Knowledge 객체 외부에서 문서를 관리 경우에만 이러한 메서드를 직접 호출합니다.

쓰기 (write) 또는 검색 작업을 한 사용자의 문서로 제한하려면 작업 메서드에 user_id 값을 전달합니다.

메서드	설명
`search(query, limit, filters, min_score, user_id)`	`query`를 포함하고 일치하는 문서를 최대 `limit`개 반환합니다. `search_type`를 `SearchType.hybrid`로 설정하다 하면 Agno도 키워드 검색 실행하고 두 결과 세트를 병합합니다. `filters` 매개변수는 메타데이터 필터 사전을 허용합니다. 대신 Agno 필터하다 표현식 목록을 전달하면 MongoDB 통합에서 필터를 지원 하지 않기 때문에 Agno에서 경고를 기록하고 필터를 적용하지 않습니다.
`insert(content_hash, documents, filters, user_id)`	각 문서 `documents`에 포함하고 문서를 컬렉션 에 삽입합니다. Agno는 문서 콘텐츠의 해시에서 각 문서의 `_id` 값을 파생합니다.
`upsert(content_hash, documents, filters, user_id)`	`content_hash`를 주식 문서를 대체한 다음 `documents`에 문서를 삽입합니다. 콘텐츠가 변경된 문서 업데이트 하려면 이 메서드를 사용합니다.
`delete()`	컬렉션 에서 모든 문서 삭제하지만 컬렉션 과 해당 MongoDB Vector Search 인덱스 유지합니다.
`delete_by_id(id)`	지정된 `_id` 값을 가진 문서 를 삭제합니다.
`delete_by_name(name)`	지정된 `name` 값을 가진 문서를 삭제합니다.
`delete_by_metadata(metadata)`	`meta_data` 필드 지정된 키-값 쌍과 일치하는 문서를 삭제합니다.
`drop()`	컬렉션 과 해당 MongoDB Vector Search 인덱스 삭제합니다.
`exists()`	컬렉션 이 존재하는 경우 `True`를 반환합니다.
`get_count()`	컬렉션 에 있는 문서 수를 반환합니다.

팁

비동기식 메서드

앞의 표에 설명된 다음 메서드에는 각각 해당하는 비동기 메서드가 있습니다.

search(): 사용 async_search()
insert(): 사용 async_insert()
upsert(): 사용 async_upsert()
drop(): 사용 async_drop()
exists(): 사용 async_exists()

세션 및 메모리 데이터베이스

agno.db.mongo 모듈의 MongoDb 클래스는 Agno 데이터베이스 인터페이스를 구현합니다. 에이전트의 세션, 사용자 메모리, 지표 및 평가 실행을 MongoDB 에서 유지하려면 이 클래스의 인스턴스 Agent, Team 또는 Workflow 객체 의 db 매개변수에 전달합니다.

Basic initialization 탭 선택하여 최소 구성 예시 보거나 Custom configuration 탭 선택하여 사용자 지정 설정으로 통합을 구성하는 방법을 확인합니다.

데이터베이스 초기화하려면 MongoDB 연결 문자열 지정합니다. 다음 예시 MongoDB 에 세션 기록을 저장하고 모델 컨텍스트에 해당 기록을 포함하는 에이전트 만듭니다.

import os
from agno.agent import Agent
from agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)

다음 예시 데이터베이스 이름과 세션, 메모리 및 지표 저장 컬렉션의 이름을 지정합니다.

import os
from agno.agent import Agent
from agno.db.mongo import MongoDb
db = MongoDb(
    db_url=os.environ["MONGODB_URI"],
    db_name="agno_prod",
    session_collection="agent_sessions",
    memory_collection="agent_memories",
    metrics_collection="agent_metrics",
)
agent = Agent(db=db, add_history_to_context=True)

Agno는 사용자가 해당 컬렉션 에 처음 쓸 때 구성하는 각 컬렉션 생성합니다.

Database Parameters

이 매개변수를 사용하여 데이터베이스 구성합니다.

MongoDb 클래스는 다음 매개변수를 허용합니다:

Parameter	필요성	설명
`db_url`	조건부	MongoDB deployment 에 대한 연결 문자열 . `db_client`을(를) 지정하지 않는 경우 필수입니다.
`db_client`	조건부	기존 `MongoClient` 인스턴스 입니다. `db_url`을 지정하지 않는 경우 필수입니다. 둘 다 지정하면 Agno는 `db_url`를 무시합니다.
`db_name`	옵션	컬렉션을 보관하는 데이터베이스 의 이름입니다. 기본값은 `agno`입니다.
`session_collection`	옵션	에이전트, 팀 및 워크플로 세션을 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_sessions`입니다.
`runs_collection`	옵션	실행을 저장하는 컬렉션 의 이름으로, 실행 당 하나의 문서 있습니다. 기본값은 `agno_runs`입니다. 이 매개변수를 지정하지 않고 `session_collection`을 지정하는 경우, Agno는 세션 컬렉션 이름에서 이름(예: `agent_sessions_runs`)을 생성합니다.
`memory_collection`	옵션	사용자 메모리를 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_memories`입니다.
`metrics_collection`	옵션	집계된 사용량 지표 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_metrics`입니다.
`eval_collection`	옵션	평가 실행을 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_eval_runs`입니다.
`knowledge_collection`	옵션	지식 콘텐츠 메타데이터 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_knowledge`입니다.
`traces_collection`, `spans_collection`	옵션	트레이스 및 스팬을 저장 컬렉션의 이름입니다. 기본값은 `agno_traces` 및 `agno_spans`입니다.
`schedules_collection`, `schedule_runs_collection`	옵션	일정 및 예정 실행을 저장 컬렉션의 이름입니다. 기본값은 `agno_schedules` 및 `agno_schedule_runs`입니다.
`learnings_collection`	옵션	학습을 저장하는 컬렉션 의 이름입니다. 기본값은 `agno_learnings`입니다.
`id`	옵션	데이터베이스 인스턴스 의 식별자입니다. 이 매개 변수를 지정하지 않으면 Agno는 연결 문자열 및 데이터베이스 이름에서 매개 변수를 파생합니다.

에이전트 실행되면 Agno는 이 섹션에 설명된 세션, 메모리 및 지표 컬렉션에서 자동으로 읽고 씁니다. Agno는 필요할 때 처음으로 각 컬렉션 생성합니다. 다음과 같이 MongoDb 인스턴스 에서 직접 메서드를 호출할 수도 있습니다.

upsert_session() 및 get_sessions() 읽기 및 쓰기 (write) 세션.
upsert_user_memory() 단일 사용자 메모리를 씁니다.
get_metrics() 집계된 사용량 지표 읽습니다.
upsert_sessions() 기존 세션 기록을 MongoDB 로 마이그레이션 할 때와 같이 upsert_memories()가 한 번의 작업으로 많은 레코드를 쓰기 (write) .
close() 클라이언트 연결을 해제합니다. 애플리케이션 이 종료될 때 이 메서드를 호출합니다.

검색 인덱스

Agno가 벡터 컬렉션 처음 만들면 컬렉션 에 MongoDB Vector Search 인덱스 도 생성됩니다. 인덱스 이름은 search_index_name 매개변수의 값이며, 기본값은 vector_index_1입니다. 이 인덱스 수동으로 생성하거나 검사할 수도 있습니다. 자세한 학습 은 MongoDB 벡터 검색 인덱스 생성을 참조하세요.

인덱스 다음 정의를 사용하며, 여기서 numDimensions은 임베더가 생성하는 차원 수와 일치하고 similarity은 distance_metric 값과 일치합니다.

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    },
    {
      "type": "filter",
      "path": "user_id"
    }
  ]
}

Agno는 검색 범위를 단일 최종 사용자의 문서로 지정할 수 있도록 user_id 필드 필터하다 필드 로 인덱싱합니다.

하이브리드 검색 MongoDB Search 인덱스 필요하지 않습니다. Agno는 content 필드 에서 키워드 검색 정규 표현식 쿼리 로 실행한 다음 역수 순위 통합을 사용하여 해당 결과를 MongoDB Vector Search 결과와 결합합니다.

추가 리소스

MongoDB 와 함께 Agno를 사용하는 방법에 대해 자세히 학습 다음 리소스를 참조하세요.

Agno MongoDB Vector Store 참조
Agno MongoDB 데이터베이스 참조
Agno 지식 문서
Agno GitHub 리포지토리

돌아가기

마스트라

시작하기