일반적인 RAG(검색 증강 생성) 구성에서는 문서를 삽입할 때 임베딩을 생성하고, 콘텐츠가 바뀌면 다시 생성하며, 모든 질의를 직접 임베딩합니다. Automated Embedding을 사용하면 MongoDB Atlas가 임베딩 생성, 업데이트, 질의를 네이티브로 처리하고 Vector Search가 생성된 벡터 임베딩을 클러스터에 저장하므로 시맨틱 검색 구축 과정을 단순화할 수 있습니다.
MongoDB의 자동 임베딩 방식
autoEmbed 유형의 벡터 검색 인덱스를 만들면, MongoDB가 선택한 필드에 대해 임베딩을 생성하고 VoyageAI 모델을 사용하며, 문서 변경 시 동기화를 유지하고, 검색 시 동일한 모델로 질의 텍스트를 임베딩합니다. 생성된 임베딩은 MongoDB 클러스터의 별도 내부 데이터베이스에 비동기적으로 저장됩니다.
이 튜토리얼에서는 MongoDB 자동 임베딩으로 Q&A Docs Assistant를 만들어 보겠습니다. Django MongoDB 백엔드로 모델을 정의하고 문서를 적재하며, 조회·임베딩 생성·동기화는 MongoDB가 자동으로 처리하고, LLM이 검색 결과를 바탕으로 문서를 반환하도록 합니다.
이 튜토리얼을 마치면 RAG 파이프라인의 검색 단계를 구축하게 됩니다. 자동 임베딩이 임베딩 작업을 대신 처리하는 Federal Register 문서에 대한 시맨틱 검색입니다. 문서를 삽입하면 임베딩되고, 변경 시 재임베딩되며, 질의는 검색 시점에 임베딩됩니다. 임베딩 코드를 작성할 필요가 없습니다.
settings.py에 하드코딩된 기존 SECRET_KEY = '...' 줄을 삭제한 후, startproject 실행 시 settings.py에 생성된 값을 복사해 .env 파일에 넣으세요. 기본으로 하드코딩되어 있는데, 세션 쿠키, CSRF 토큰 등 보안에 민감한 데이터를 서명할 때 사용되므로 버전 관리에서 제외하기 위해 .env로 옮기는 것입니다.
regulations_qa/settings.py를 열고 다음 내용이 모두 포함되어 있는지 확인하세요. import 줄과 load_dotenv()는 상단에 추가합니다. 기존 SECRET_KEY와 DATABASES 정의를 교체하고, VECTOR_INDEX_NAME 줄을 추가합니다:
import os
from dotenv import load_dotenv
load_dotenv()
SECRET_KEY = os.getenv("SECRET_KEY")
VECTOR_INDEX_NAME = os.getenv("VECTOR_INDEX_NAME")
DATABASES ={'default':{'ENGINE':'django_mongodb_backend','HOST': os.getenv("MONGODB_URI"),'NAME': os.getenv("DB_NAME"),},}제공
관리 명령을 위한 폴더 생성
다음으로 관리 명령용 폴더와 빈 __init__.py 파일을 만듭니다. Django는 management/commands/ 패키지에서만 커스텀 명령을 검색합니다.
임베딩이 백그라운드에서 생성되는 동안, 인덱스 상태가 질의 가능하다고 표시될 때까지 기다리세요.
일반 텍스트로 질의하기
자동 임베딩에서는 $vectorSearch 스테이지에서 일반 텍스트 질의를 사용하고, 인덱스가 쓰는 것과 동일한 모델로 질문을 임베딩하므로 코드에 별도의 임베딩 호출이 없습니다.
이를 위해 서비스 모듈을 만들겠습니다.
# documents/services/search_service.pyfrom functools import lru_cache
from django.conf import settings
from pymongo import MongoClient
from documents.models import Document
DEFAULT_LIMIT =5@lru_cache(maxsize=1)# create the client once and reuse itdef_get_client():return MongoClient(settings.DATABASES["default"]["HOST"])def_get_collection():
db_name = settings.DATABASES["default"]["NAME"]return _get_client()[db_name][Document._meta.db_table]def_get_index_name():
index_name = settings.VECTOR_INDEX_NAME
ifnot index_name:raise ValueError("VECTOR_INDEX_NAME is not set. Add it to your .env file.")return index_name
defsemantic_search(question:str, limit:int= DEFAULT_LIMIT)->list:"""Search with a plain-text question.
There is no query vector to pass in: MongoDB embeds the question
with the index's model.
"""
pipeline =[{"$vectorSearch":{"index": _get_index_name(),"path":"abstract","query": question,"numCandidates": limit *20,"limit": limit,}},{"$project":{"_id":0,"document_number":1,"title":1,"abstract":1,"source_url":1,"score":{"$meta":"vectorSearchScore"},}},]returnlist(_get_collection().aggregate(pipeline))제공
_get_client()는 MongoDB 연결을 한 번 생성해 재사용합니다. lru_cache는 첫 호출의 결과를 기억하여, 매 검색마다 새 연결을 여는 대신 하나의 클라이언트를 공유합니다.
_get_collection()은 Django 설정을 사용해 regulations_qa 데이터베이스와 documents_document 컬렉션을 선택합니다.
_get_index_name()은 설정에서 인덱스 이름을 읽고, 누락 시 명확한 오류를 제공합니다.
semantic_search()는 query 필드에 텍스트로 질문을 보냅니다. 두 번째 스테이지는 필요한 필드로 출력 범위를 줄이고 유사도 점수를 추가합니다.
이제 문서를 검색하는 헬퍼를 추가합니다:
# documents/management/commands/search_docs.pyfrom django.core.management.base import BaseCommand
from documents.services.search_service import semantic_search
classCommand(BaseCommand):help="Run a plain-text search."defadd_arguments(self, parser):
parser.add_argument("question")defhandle(self,*args,**options):for hit in semantic_search(options["question"]):
self.stdout.write(f"{hit['score']:.3f}{hit['document_number']}{hit['title'][:80]}")제공
테스트하려면 다음을 실행하세요:
python manage.py search_docs "limits on pollution from factories"제공
예시에서는 요약과 키워드를 공유하지 않는 질문을 선택합니다. “limits on pollution from factories(공장 오염물질 배출 한도)”에 대한 질문은 배출 기준 관련 문서를 검색해야 합니다.
참고: 결제 수단이 없는 무료(M0) 클러스터에서는 질의 임베딩 요청이 레이트 리밋될 수 있습니다.
데모: 문서를 편집하고 재동기화를 확인하기
데모는 이전에 regulations_qa.documents_document 컬렉션에 만든 autoembed_index와 연결된 MongoDB Atlas의 Search Tester나 Python 셸 중 하나를 사용해 진행할 수 있습니다.
from documents.models import Document
from documents.services.search_service import semantic_search
Q ="which states need to clean up their air"
hits = semantic_search(Q, limit=10)print("\n".join(f"{i}{h['score']:.3f}{h['document_number']}{h['title'][:70]}"for i, h inenumerate(hits,1)))제공
출력은 GUI에서 본 것과 동일해야 합니다.
2단계: 문서 편집
target = hits[-1]
doc = Document.objects.get(document_number=target["document_number"])
original = doc.abstract
doc.abstract = original +" This action also identifies which states and areas must clean up their air to meet health-based standards."
doc.save()print(target["document_number"],"edited")제공
3단계: 다시 검색
자동 임베딩은 비동기적으로 생성되므로 30–60초 정도 기다린 후, 다시 질의를 실행하세요:
hits = semantic_search(Q, limit=10)print("\n".join(f"{i}{h['score']:.3f}{h['document_number']}{h['title'][:70]}"for i, h inenumerate(hits,1)))제공
이제 편집된 문서의 순위가 이전보다 높아진 것을 확인할 수 있어야 합니다.
동일한 질의를 Search Tester에서도 실행해 GUI로 결과를 확인하세요.
MongoDB가 인덱싱된 필드가 변경되었음을 감지하고 해당 문서의 임베딩을 재생성했기 때문에, 샘플에서 10번째였던 문서 2026-16515가 편집 및 동기화 후 5번째로 올라갔습니다.
마무리
여기까지 오신 것을 축하드립니다! 이제 MongoDB가 임베딩 워크플로를 처리하는 데이터 기반 문서 Q&A 어시스턴트를 갖추게 되었습니다. 다음 단계로 이를 구현했습니다:
삽입: Django ORM을 통해 문서를 적재
인덱스: 필드와 모델을 지정하는 단일 인덱스 정의를 Atlas UI에서 생성
질의: 별도의 임베딩 호출 없이 소규모 서비스로 일반 텍스트 질문 실행
편집: 인덱싱된 필드의 변경 사항이 재임베딩 스크립트 없이 재동기화
참고: 본 튜토리얼의 데이터는 미국 정부 문서를 발행하는 Federal Register에서 가져왔습니다. 이 튜토리얼은 Federal Register와 무관하며, 그 승인 또는 보증을 받지 않았습니다.
자동 임베딩이 단순화하는 것
일반적인 RAG(검색 증강 생성) 구성에서는 문서를 삽입할 때 임베딩을 생성하고, 콘텐츠가 바뀌면 다시 생성하며, 모든 질의를 직접 임베딩합니다. Automated Embedding을 사용하면 MongoDB Atlas가 임베딩 생성, 업데이트, 질의를 네이티브로 처리하고 Vector Search가 생성된 벡터 임베딩을 클러스터에 저장하므로 시맨틱 검색 구축 과정을 단순화할 수 있습니다.
MongoDB의 자동 임베딩 방식
autoEmbed유형의 벡터 검색 인덱스를 만들면, MongoDB가 선택한 필드에 대해 임베딩을 생성하고VoyageAI모델을 사용하며, 문서 변경 시 동기화를 유지하고, 검색 시 동일한 모델로 질의 텍스트를 임베딩합니다. 생성된 임베딩은 MongoDB 클러스터의 별도 내부 데이터베이스에 비동기적으로 저장됩니다.이 튜토리얼에서는 MongoDB 자동 임베딩으로 Q&A Docs Assistant를 만들어 보겠습니다. Django MongoDB 백엔드로 모델을 정의하고 문서를 적재하며, 조회·임베딩 생성·동기화는 MongoDB가 자동으로 처리하고, LLM이 검색 결과를 바탕으로 문서를 반환하도록 합니다.
이 튜토리얼을 마치면 RAG 파이프라인의 검색 단계를 구축하게 됩니다. 자동 임베딩이 임베딩 작업을 대신 처리하는 Federal Register 문서에 대한 시맨틱 검색입니다. 문서를 삽입하면 임베딩되고, 변경 시 재임베딩되며, 질의는 검색 시점에 임베딩됩니다. 임베딩 코드를 작성할 필요가 없습니다.
이 튜토리얼을 따르는 방법은 두 가지입니다.
설정
시작하기 전에 다음이 준비되어 있어야 합니다:
필수 요소를 갖췄다면, 다음 단계는 프로젝트 폴더를 만드는 것입니다.
프로젝트 및 가상 환경 만들기
프로젝트용 빈 폴더를 만들고 해당 폴더로
cd하세요.여기가 프로젝트의 루트 디렉터리입니다. 아직이라면 여기에서 가상 환경을 생성하고 활성화하세요:
macOS 또는 Linux에서 가상 환경을 활성화하려면:
Windows에서는 다음을 실행하세요:
의존성 설치
프로젝트 루트에 다음 내용을 담은
requirements.txt파일을 만드세요:그다음 모두 설치합니다:
Django 프로젝트와 앱 생성
프로젝트 루트 디렉터리에서 다음 명령을 실행해 새 Django 프로젝트와 앱을 생성합니다.
startproject명령의 끝에.를 추가하면, 새 중첩 폴더를 만들지 않고 현재 디렉터리에 프로젝트를 설치하라는 의미가 됩니다.documents앱 생성regulations_qa/settings.py에서INSTALLED_APPS에 추가해 앱을 등록하세요:환경 변수 구성
프로젝트 루트에
.env파일을 만들고 본인 값으로 채운 뒤,.gitignore에 추가해 푸시 시 커밋되지 않도록 하세요.settings.py에 하드코딩된 기존SECRET_KEY = '...'줄을 삭제한 후,startproject실행 시settings.py에 생성된 값을 복사해.env파일에 넣으세요. 기본으로 하드코딩되어 있는데, 세션 쿠키, CSRF 토큰 등 보안에 민감한 데이터를 서명할 때 사용되므로 버전 관리에서 제외하기 위해.env로 옮기는 것입니다.regulations_qa/settings.py를 열고 다음 내용이 모두 포함되어 있는지 확인하세요. import 줄과load_dotenv()는 상단에 추가합니다. 기존SECRET_KEY와DATABASES정의를 교체하고,VECTOR_INDEX_NAME줄을 추가합니다:관리 명령을 위한 폴더 생성
다음으로 관리 명령용 폴더와 빈
__init__.py파일을 만듭니다. Django는management/commands/패키지에서만 커스텀 명령을 검색합니다.데이터 소스: Federal Register 문서
이 튜토리얼에서는 Federal Register(미국 정부의 규칙, 제안 규칙, 공지를 매일 발행)에서 문서를 색인화합니다. 데이터 소스는 제목과 짧은 산문 요약을 가진 문서로 구성된 공개 API이며, 시맨틱 검색에 잘 맞습니다.
API 문서: https://www.federalregister.gov/developers/documentation/api/v1
레코드에는
title,type,abstract,document_number(고유 ID),publication_date,html_url,agencies목록 등의 필드가 있습니다.<INF>2.5</INF>같은 마크업이 포함되어 있어 저장 전에 태그를 제거합니다.next_page_url(커서 기반)이 포함됩니다.셸에서 엔드포인트 테스트
참고: 이는 데모용 공공 미국 정부 데이터입니다. 법적 근거 자료가 아니므로, 법률 연구에는 공식 판본을 사용하세요.
데이터 적재
models.py파일에 모델을 만드는 것부터 시작합니다.다음으로 마이그레이션을 생성하고 적용합니다.
이제 적재 단계로 넘어가겠습니다.
명령을 실행합니다:
MongoDB Atlas UI에서 가져온 결과를 확인할 수 있습니다:
자동 임베드 인덱스 정의
벡터 검색 인덱스는 어떤 필드에 임베딩을 수행할지와 사용할 모델을 지정합니다. 이후 MongoDB가 자동으로 임베딩을 생성·저장합니다.
documents_document컬렉션을 지정한 뒤, 인덱스 이름을autoembed_index로 설정합니다(이 이름은.env의VECTOR_INDEX_NAME과 일치해야 합니다). 다음 정의를 붙여넣습니다:정의를 검토한 후 인덱스를 생성하세요.
일반 텍스트로 질의하기
자동 임베딩에서는
$vectorSearch스테이지에서 일반 텍스트 질의를 사용하고, 인덱스가 쓰는 것과 동일한 모델로 질문을 임베딩하므로 코드에 별도의 임베딩 호출이 없습니다.이를 위해 서비스 모듈을 만들겠습니다.
_get_client()는 MongoDB 연결을 한 번 생성해 재사용합니다.lru_cache는 첫 호출의 결과를 기억하여, 매 검색마다 새 연결을 여는 대신 하나의 클라이언트를 공유합니다._get_collection()은 Django 설정을 사용해regulations_qa데이터베이스와documents_document컬렉션을 선택합니다._get_index_name()은 설정에서 인덱스 이름을 읽고, 누락 시 명확한 오류를 제공합니다.semantic_search()는query필드에 텍스트로 질문을 보냅니다. 두 번째 스테이지는 필요한 필드로 출력 범위를 줄이고 유사도 점수를 추가합니다.이제 문서를 검색하는 헬퍼를 추가합니다:
테스트하려면 다음을 실행하세요:
예시에서는 요약과 키워드를 공유하지 않는 질문을 선택합니다. “limits on pollution from factories(공장 오염물질 배출 한도)”에 대한 질문은 배출 기준 관련 문서를 검색해야 합니다.
참고: 결제 수단이 없는 무료(M0) 클러스터에서는 질의 임베딩 요청이 레이트 리밋될 수 있습니다.
데모: 문서를 편집하고 재동기화를 확인하기
데모는 이전에
regulations_qa.documents_document컬렉션에 만든autoembed_index와 연결된 MongoDB Atlas의Search Tester나 Python 셸 중 하나를 사용해 진행할 수 있습니다.1단계: MongoDB Atlas와 셸에서 검색
MongoDB Atlas UI에서 다음 질의를 입력해 테스트하세요:
셸에서 테스트하려면:
python manage.py shell로 셸을 연 뒤 다음을 실행합니다:출력은 GUI에서 본 것과 동일해야 합니다.
2단계: 문서 편집
3단계: 다시 검색
자동 임베딩은 비동기적으로 생성되므로 30–60초 정도 기다린 후, 다시 질의를 실행하세요:
이제 편집된 문서의 순위가 이전보다 높아진 것을 확인할 수 있어야 합니다.
동일한 질의를 Search Tester에서도 실행해 GUI로 결과를 확인하세요.
MongoDB가 인덱싱된 필드가 변경되었음을 감지하고 해당 문서의 임베딩을 재생성했기 때문에, 샘플에서 10번째였던 문서
2026-16515가 편집 및 동기화 후 5번째로 올라갔습니다.마무리
여기까지 오신 것을 축하드립니다! 이제 MongoDB가 임베딩 워크플로를 처리하는 데이터 기반 문서 Q&A 어시스턴트를 갖추게 되었습니다. 다음 단계로 이를 구현했습니다:
참고: 본 튜토리얼의 데이터는 미국 정부 문서를 발행하는 Federal Register에서 가져왔습니다. 이 튜토리얼은 Federal Register와 무관하며, 그 승인 또는 보증을 받지 않았습니다.
참고 자료