MongoDB를 멀티모달 AI 에이전트 구축을 위한 오픈 소스 Python 프레임워크인 Agno와 통합할 수 있습니다. Agno는 두 가지 MongoDB 통합을 제공합니다.
에이전트의 지식 기반을 저장하고 MongoDB Vector Search로 조회하는 벡터 데이터베이스 입니다.
에이전트 세션, 사용자 메모리, 지표 및 평가 실행을 MongoDB 컬렉션에 유지하는 세션 및 메모리 데이터베이스 입니다.
각 통합을 단독으로 사용하거나 동일한 에이전트에서 두 통합을 모두 사용할 수 있습니다.
시작하기
Agno가 MongoDB를 사용하도록 구성하는 튜토리얼을 완료하려면 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 배포서버의 연결 문자열로 설정합니다.모델 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 osfrom agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom 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 벡터 검색 인덱스 이름을 지정합니다.
import osfrom agno.agent import Agentfrom agno.knowledge.embedder.voyageai import VoyageAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDbfrom 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 벡터 검색 인덱스를 생성할 때 임베더가 생성하는 차원 수를 사용합니다. request_params 사전은 제공자별 키워드 인수를 임베딩 호출에 전달합니다. Voyage AI의 경우 output_dimension은 가변 차원을 지원하는 모델에 대해 반환된 벡터의 크기를 제어합니다.
Knowledge 객체를 만들 때 Agno가 컬렉션이 이미 존재하는지 확인합니다. 그렇지 않은 경우, Agno가 컬렉션및 MongoDB 벡터 검색 인덱스를 만듭니다. 컬렉션이 존재하는 경우, Agno는 인덱스를 별도로 삭제했더라도 인덱스의 존재 여부를 확인하지 않습니다.
인덱스를 만든 후, Agno는 컬렉션에 인덱스가 표시될 때까지 기다립니다. 하지만 인덱스 상태를 확인하지 않습니다. 따라서 바로 다음에 실행되는 쿼리는 인덱스 생성이 완료되는 동안 결과가 반환되지 않을 수 있습니다.
벡터 데이터베이스 메서드
Knowledge 클래스는 지식 기반에 콘텐츠를 추가하거나 에이전트가 지식 기반을 검색할 때 다음 메서드를 호출합니다. Knowledge 객체 외부에서 문서를 관리하는 경우에만 이러한 메서드를 직접 호출하다.
한 사용자의 문서로 쓰기 (write) 또는 검색 작업을 제한하려면 작업 메서드에 user_id 값을 전달합니다.
메서드 | 설명 |
|---|---|
|
|
|
|
|
|
| 컬렉션에서 모든 문서를 삭제하지만 컬렉션과 해당 MongoDB 벡터 검색 인덱스는 유지합니다. |
| 지정된 |
| 지정된 |
|
|
| 컬렉션과 해당 MongoDB 벡터 검색 인덱스를 제거합니다. |
| 컬렉션이 있는 경우 |
| 컬렉션의 문서 수를 반환합니다. |
팁
비동기식 메서드
앞의 표에 설명된 각 메서드에는 해당 비동기 메서드가 있습니다.
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 osfrom agno.agent import Agentfrom agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)다음 예시는 데이터베이스 이름과 세션, 메모리, 지표를 저장하는 컬렉션의 이름을 지정합니다.
import osfrom agno.agent import Agentfrom 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는 구성한 각 컬렉션에 처음 쓰기 (write)할 때 해당 컬렉션을 생성합니다.
에이전트가 실행되면 Agno는 이 섹션에 설명된 세션, 메모리 및 지표 컬렉션을 자동으로 읽고 쓰기 (write)합니다. Agno는 각 컬렉션이 처음 필요할 때 생성합니다. 다음과 같이 MongoDb 인스턴스에서 직접 메서드를 호출할 수도 있습니다.
upsert_session()및get_sessions()읽기 및 쓰기 (write) 세션.upsert_user_memory()단일 사용자 메모리에 쓰기 (write)합니다.get_metrics()집계된 사용량 지표를 읽습니다.upsert_sessions()기존 세션 기록을 MongoDB로 마이그레이션할 때와 같이 단일 작업으로 많은 기록을upsert_memories()쓰기 (write)할 때 사용합니다.close()클라이언트 연결을 해제합니다. 애플리케이션이 종료될 때 이 메서드를 호출하십시오.
검색 인덱스
Agno가 벡터 컬렉션을 처음 생성할 때, 컬렉션에 MongoDB 벡터 검색 인덱스도 생성합니다. 인덱스 이름은 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 벡터 검색 결과와 결합합니다.
추가 리소스
Agno와 MongoDB를 함께 사용하는 방법에 대해 자세히 학습하려면 다음 리소스를 참조하세요.
Agno GitHub 리포지토리