自動埋め込みが簡素化すること
一般的な RAG(Retrieval-Augmented Generation)構成では、ドキュメント挿入時に埋め込みを生成し、内容が変われば再生成し、クエリごとに自分で埋め込みを行います。Automated Embedding(自動埋め込み)を使うと、MongoDB Atlas がネイティブに埋め込みの生成・更新・クエリ処理を担い、Vector Search がクラスタ上にベクトル埋め込みを保存するため、セマンティック検索の構築が簡単になります。
MongoDB による自動埋め込みの仕組み
autoEmbed タイプのベクトル検索インデックスを作成すると、MongoDB は選択したフィールドに対して埋め込みを生成し、VoyageAI モデルを使用して、ドキュメントの変更時に同期を維持し、検索時には同じモデルでクエリテキストを埋め込みます。生成された埋め込みは、MongoDB クラスタ上の内部データベースに非同期で保存されます。
このチュートリアルでは、MongoDB の自動埋め込みを使って Q&A ドキュメントアシスタントを作成します。Django MongoDB backend でモデル定義とドキュメント取り込みを行い、MongoDB で検索、埋め込みの生成と同期を自動化し、取得結果に基づいて LLM がドキュメントを返します。
チュートリアルの最後には、RAG パイプラインの取得段階を構築します。自動埋め込みが埋め込み作業を担う、Federal Register ドキュメントに対するセマンティック検索です。ドキュメントは挿入時に埋め込まれ、変更時に再埋め込みされ、クエリは検索時に埋め込まれます。埋め込み用コードは一切不要です。
本チュートリアルには 2 つの進め方があります。
セットアップ
開始前に以下を用意してください。
前提条件が整ったら、次はプロジェクトフォルダを作成します。
プロジェクトと仮想環境を作成
空のフォルダを作成し、その中に cd で移動します。
mkdir regulations_qa
cd regulations_qa提供:
ここがプロジェクトのルートディレクトリです。まだであれば、ここで仮想環境を作成・有効化してください。
python -m venv .venv提供:
macOS または Linux では次を実行して有効化します。
source .venv/bin/activate提供:
Windows では次を実行します。
.venv\ Scripts\ activate提供:
依存関係をインストール
プロジェクトのルートに requirements.txt を作成し、以下の内容を記述します。
# requirements.txt
django-mongodb-backend
python-dotenv
requests #to fetch documents from the Federal Register API.提供:
次にインストールします。
pip install -r requirements.txt提供:
Django プロジェクトとアプリを作成
プロジェクトのルートディレクトリから、以下のコマンドで新しい Django プロジェクトとアプリを作成します。startproject コマンドの末尾にある . を忘れずに。これにより、Django は新しい入れ子フォルダではなく現在のディレクトリにプロジェクトを作成します。
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip . 提供:
documents アプリを作成
python manage.py startapp documents提供:
regulations_qa/settings.py の INSTALLED_APPS に追加してアプリを登録します。
INSTALLED_APPS = [
'regulations_qa.apps.MongoAdminConfig' ,
'regulations_qa.apps.MongoAuthConfig' ,
'regulations_qa.apps.MongoContentTypesConfig' ,
'django.contrib.sessions' ,
'django.contrib.messages' ,
'django.contrib.staticfiles' ,
'django_mongodb_backend' ,
'documents' ,
] 提供:
環境変数を設定
プロジェクトのルートに .env ファイルを作成し、各自の値を設定してください。.gitignore にも記載して、プッシュ時にコミットされないようにします。
# .env
SECRET_KEY=[REPLACE_WITH_YOUR_SECRET_KEY]
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority"
DB_NAME=regulations_qa
VECTOR_INDEX_NAME=autoembed_index提供:
元の settings.py にハードコードされている SECRET_KEY = '...' 行を削除し、startproject 実行時に settings.py に生成された値をコピーして .env に置き換えてください。デフォルトではハードコードされていますが、Django はセッションクッキー、CSRF トークンなどのセキュリティ関連データの署名に使用するため、バージョン管理から外す目的で .env に移します。
regulations_qa/settings.py を開き、以下がすべて含まれていることを確認します。インポート行と 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/ パッケージ内のみでカスタムコマンドを検出するためです。
mkdir -p documents/management/commands documents/services && touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.py提供:
データソース: Federal Register ドキュメント
このチュートリアルでは、Federal Register(米国政府の規則・案規則・通知の官報)からドキュメントをインデックス化します。データソースはパブリック API で、タイトルと短い要約(prose abstract)を含むドキュメントで構成され、セマンティック検索に向いています。
API ドキュメント: https://www.federalregister.gov/developers/documentation/api/v1
レコードには、title、type、abstract、document_number(一意 ID)、publication_date、html_url、agencies リストといったフィールドがあります。
一部のドキュメントには null 値が含まれるため、省きます。
要約には「PM2.5」の <INF>2.5</INF> のようなマークアップが含まれるため、保存前にタグを除去します。
結果は 1 リクエスト最大 100 件のページングで、各ページに次を辿るための next_page_url(カーソルベース)が含まれます。
シェルからエンドポイントをテスト
curl -g "https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2" 提供:
注: これはデモ用途の米国政府の公開データです。法的な情報源ではありません。法的な調査には公式版を使用してください。
データの取り込み
まずは models.py ファイルにモデルを作成します。
from django. db import models
class Document ( models. Model) :
document_number = models. CharField( max_length= 32 , unique= True )
title = models. TextField( )
doc_type = models. CharField( max_length= 32 )
agency = models. CharField( max_length= 128 )
publication_date = models. DateField( )
abstract = models. TextField( )
source_url = models. URLField( max_length= 500 )
def __str__ ( self) :
return f" { self. document_number} : { self. title[ : 60] } " 提供:
続いて、マイグレーションを作成・実行します。
python manage.py makemigrations documents
python manage.py migrate提供:
次に、取り込み処理に移ります。
import re
import time
import requests
from django. core. management. base import BaseCommand
from documents. models import Document
API_URL = "https://www.federalregister.gov/api/v1/documents.json"
TAG_PATTERN = re. compile ( r"<[^>]+>" )
class Command ( BaseCommand) :
help = "Load Federal Register documents into MongoDB."
def add_arguments ( self, parser) :
parser. add_argument( "--agency" , default= "environmental-protection-agency" )
parser. add_argument( "--limit" , type = int , default= 300 )
def handle ( self, * args, ** options) :
params = [
( "conditions[agencies][]" , options[ "agency" ] ) ,
( "conditions[type][]" , "RULE" ) ,
( "conditions[type][]" , "PRORULE" ) ,
( "per_page" , "100" ) ,
]
headers = { "User-Agent" : "regulations-qa-tutorial" }
url, processed = API_URL, 0
while url and processed < options[ "limit" ] :
response = requests. get(
url,
params= params if url == API_URL else None ,
headers= headers,
timeout= 30 ,
)
response. raise_for_status( )
page = response. json( )
for item in page[ "results" ] :
abstract = TAG_PATTERN. sub( "" , item. get( "abstract" ) or "" ) . strip( )
if not abstract:
continue
agencies = item. get( "agencies" ) or [ { } ]
Document. objects. update_or_create(
document_number= item[ "document_number" ] ,
defaults= {
"title" : TAG_PATTERN. sub( "" , item[ "title" ] ) ,
"doc_type" : item[ "type" ] ,
"agency" : agencies[ 0 ] . get( "name" , "" ) ,
"publication_date" : item[ "publication_date" ] ,
"abstract" : abstract,
"source_url" : item[ "html_url" ] ,
} ,
)
processed += 1
if processed >= options[ "limit" ] :
break
url = page. get( "next_page_url" )
time. sleep( 1 )
self. stdout. write( f"Documents in database: { Document. objects. count( ) } " ) 提供:
コマンドを実行します。
python manage.py ingest_federal_register --limit 100 提供:
MongoDB Atlas の UI でインポートを確認できます。
自動埋め込みインデックスを定義
ベクトル検索インデックスでは、どのフィールドに埋め込みを行うか、どのモデルを使うかを指定します。それ以降、MongoDB が自動的に埋め込みを生成・保存します。
Atlas UI でクラスタを開き、Search & Vector Search に進み、Create Search Index をクリックします。
Vector Search を検索タイプに、Automated Embedding をベクトルデータの設定方法に選択します。
JSON エディタを選び、データベースと documents_document コレクションを選択し、インデックス名を autoembed_index にします(.env の VECTOR_INDEX_NAME と一致させる必要があります)。次の定義を貼り付けます。
{
"fields" : [
{
"type" : "autoEmbed" ,
"modality" : "text" ,
"path" : "abstract" ,
"model" : "voyage-4-lite"
}
]
} 提供:
定義を確認し、インデックスを作成します。
インデックスのステータスがクエリ可能になるまで待ちます。バックグラウンドで埋め込みが生成されています。
プレーンテキストでクエリする
自動埋め込みでは、$vectorSearch ステージにプレーンテキストのクエリを渡し、インデックスと同じモデルで質問を埋め込みます。つまりコード側に埋め込み呼び出しは不要です。
これを実現するため、サービスモジュールを作成します。
from 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 )
def _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
if not index_name:
raise ValueError( "VECTOR_INDEX_NAME is not set. Add it to your .env file." )
return index_name
def semantic_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" } ,
}
} ,
]
return list ( _get_collection( ) . aggregate( pipeline) ) 提供:
_get_client() は MongoDB への接続を 1 度だけ作成し再利用します。lru_cache により最初の呼び出し結果が記憶され、毎回新規接続を開く代わりに 1 つのクライアントを共有します。
_get_collection() は、Django と同じ設定を使って regulations_qa データベースと documents_document コレクションを選択します。
_get_index_name() は設定からインデックス名を読み取り、未設定の場合は明確なエラーを出します。
semantic_search() は query フィールドにテキストとして質問を送ります。2 つ目のステージで必要なフィールドに出力を絞り、類似度スコアを追加します。
続いて、ドキュメント検索用のヘルパーを追加します。
from django. core. management. base import BaseCommand
from documents. services. search_service import semantic_search
class Command ( BaseCommand) :
help = "Run a plain-text search."
def add_arguments ( self, parser) :
parser. add_argument( "question" )
def handle ( 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)クラスタでは、クエリの埋め込みリクエストがレート制限される場合があります。
デモ: ドキュメントを編集し、再同期を確認
デモでは、MongoDB Atlas の Search Tester(先ほど regulations_qa.documents_document に作成した autoembed_index に紐付く)か、Python シェルのどちらかを使用します。
ステップ 1: MongoDB Atlas とシェルで検索
MongoDB Atlas の UI では、次のクエリを入力します。
which states need to clean up their air提供:
シェルでテストするには:
python manage.py shell でシェルを開き、次を実行します。
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 in enumerate ( 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 in enumerate ( hits, 1 ) ) ) 提供:
編集したドキュメントが以前より上位にランクされるはずです。
同じクエリを Search Tester でも実行し、GUI で結果を確認してください。
ここで起きたのは、MongoDB がインデックス対象フィールドの変更を検知して、そのドキュメントの埋め込みを再生成したことです。サンプルで 10 位だったドキュメント 2026-16515 が、編集と同期の後、5 位に上がりました。
まとめ
ここまでお疲れさまでした。MongoDB が埋め込みのワークフローを処理する、ドキュメント Q&A アシスタントが完成しました。以下のステップで実現しました。
挿入: Django ORM を通じてドキュメントを読み込み
インデックス: フィールドとモデルを指定するインデックス定義を Atlas UI で 1 つ作成
検索: 埋め込み呼び出しを別途追加せず、小さなサービスからプレーンテキストの質問でクエリ
編集: インデックス対象フィールドの変更は、再埋め込みスクリプトなしで自動再同期
注: 本チュートリアルのデータは米国政府の文書を公開する Federal Register に由来します。本チュートリアルは独立しており、Federal Register による提携・承認は受けていません。
参考資料
自動埋め込みが簡素化すること
一般的な RAG(Retrieval-Augmented Generation)構成では、ドキュメント挿入時に埋め込みを生成し、内容が変われば再生成し、クエリごとに自分で埋め込みを行います。Automated Embedding(自動埋め込み)を使うと、MongoDB Atlas がネイティブに埋め込みの生成・更新・クエリ処理を担い、Vector Search がクラスタ上にベクトル埋め込みを保存するため、セマンティック検索の構築が簡単になります。
MongoDB による自動埋め込みの仕組み
autoEmbedタイプのベクトル検索インデックスを作成すると、MongoDB は選択したフィールドに対して埋め込みを生成し、VoyageAIモデルを使用して、ドキュメントの変更時に同期を維持し、検索時には同じモデルでクエリテキストを埋め込みます。生成された埋め込みは、MongoDB クラスタ上の内部データベースに非同期で保存されます。このチュートリアルでは、MongoDB の自動埋め込みを使って Q&A ドキュメントアシスタントを作成します。Django MongoDB backend でモデル定義とドキュメント取り込みを行い、MongoDB で検索、埋め込みの生成と同期を自動化し、取得結果に基づいて LLM がドキュメントを返します。
チュートリアルの最後には、RAG パイプラインの取得段階を構築します。自動埋め込みが埋め込み作業を担う、Federal Register ドキュメントに対するセマンティック検索です。ドキュメントは挿入時に埋め込まれ、変更時に再埋め込みされ、クエリは検索時に埋め込まれます。埋め込み用コードは一切不要です。
本チュートリアルには 2 つの進め方があります。
セットアップ
開始前に以下を用意してください。
前提条件が整ったら、次はプロジェクトフォルダを作成します。
プロジェクトと仮想環境を作成
空のフォルダを作成し、その中に
cdで移動します。ここがプロジェクトのルートディレクトリです。まだであれば、ここで仮想環境を作成・有効化してください。
macOS または Linux では次を実行して有効化します。
Windows では次を実行します。
依存関係をインストール
プロジェクトのルートに
requirements.txtを作成し、以下の内容を記述します。次にインストールします。
Django プロジェクトとアプリを作成
プロジェクトのルートディレクトリから、以下のコマンドで新しい Django プロジェクトとアプリを作成します。
startprojectコマンドの末尾にある.を忘れずに。これにより、Django は新しい入れ子フォルダではなく現在のディレクトリにプロジェクトを作成します。documentsアプリを作成regulations_qa/settings.pyのINSTALLED_APPSに追加してアプリを登録します。環境変数を設定
プロジェクトのルートに
.envファイルを作成し、各自の値を設定してください。.gitignoreにも記載して、プッシュ時にコミットされないようにします。元の
settings.pyにハードコードされているSECRET_KEY = '...'行を削除し、startproject実行時にsettings.pyに生成された値をコピーして.envに置き換えてください。デフォルトではハードコードされていますが、Django はセッションクッキー、CSRF トークンなどのセキュリティ関連データの署名に使用するため、バージョン管理から外す目的で.envに移します。regulations_qa/settings.pyを開き、以下がすべて含まれていることを確認します。インポート行とload_dotenv()は先頭に追加します。既存のSECRET_KEYとDATABASESを置き換え、VECTOR_INDEX_NAME行を追加します。管理コマンド用のフォルダを作成
次に、管理コマンド用のフォルダと空の
__init__.pyを作成します。Django はmanagement/commands/パッケージ内のみでカスタムコマンドを検出するためです。データソース: Federal Register ドキュメント
このチュートリアルでは、Federal Register(米国政府の規則・案規則・通知の官報)からドキュメントをインデックス化します。データソースはパブリック API で、タイトルと短い要約(prose abstract)を含むドキュメントで構成され、セマンティック検索に向いています。
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 への接続を 1 度だけ作成し再利用します。lru_cacheにより最初の呼び出し結果が記憶され、毎回新規接続を開く代わりに 1 つのクライアントを共有します。_get_collection()は、Django と同じ設定を使ってregulations_qaデータベースとdocuments_documentコレクションを選択します。_get_index_name()は設定からインデックス名を読み取り、未設定の場合は明確なエラーを出します。semantic_search()はqueryフィールドにテキストとして質問を送ります。2 つ目のステージで必要なフィールドに出力を絞り、類似度スコアを追加します。続いて、ドキュメント検索用のヘルパーを追加します。
テストのため、次を実行します。
例では、要約とキーワードが一致しない質問を選んでいます。「limits on pollution from factories(工場による汚染の上限)」という質問なら、排出基準に関するドキュメントが検索されるはずです。
注: 支払い方法未登録の無料(M0)クラスタでは、クエリの埋め込みリクエストがレート制限される場合があります。
デモ: ドキュメントを編集し、再同期を確認
デモでは、MongoDB Atlas の
Search Tester(先ほどregulations_qa.documents_documentに作成したautoembed_indexに紐付く)か、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 による提携・承認は受けていません。
参考資料