メインコンテンツにスキップ

Django と MongoDB の自動埋め込みで Q&A アシスタントを構築する

MongoDB の自動埋め込みで Django にセマンティック検索を実装:埋め込みコード不要、ドキュメント変更時に自動再同期、プレーンテキストでのクエリ。
· 7 分 読む

AIで探求

自動埋め込みが簡素化すること

一般的な 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 つの進め方があります。

  • オプション A: 完成済みコードを含む GitHub リポジトリをクローンし、README に従ってセットアップして自由に探索する。GitHub プロジェクトへのリンク: https://github.com/mongodb-developer/django-mongodb-regulations-qa
  • オプション B: 以下の手順に従ってゼロからプロジェクトを構築する。

セットアップ

開始前に以下を用意してください。

前提条件が整ったら、次はプロジェクトフォルダを作成します。

プロジェクトと仮想環境を作成

空のフォルダを作成し、その中に 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 ファイルにモデルを作成します。

# documents/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

次に、取り込み処理に移ります。

# documents/management/commands/ingest_federal_register.py

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 でインポートを確認できます。

regulations_qa.documents_document コレクションに Federal Register の 100 件のドキュメントがあることを示す MongoDB Atlas Data Explorer

自動埋め込みインデックスを定義

ベクトル検索インデックスでは、どのフィールドに埋め込みを行うか、どのモデルを使うかを指定します。それ以降、MongoDB が自動的に埋め込みを生成・保存します。

  1. Atlas UI でクラスタを開き、Search & Vector Search に進み、Create Search Index をクリックします。

MongoDB Atlas の Search & Vector Search ページ。Create Search Index ボタンが表示されている

  1. Vector Search を検索タイプに、Automated Embedding をベクトルデータの設定方法に選択します。

Vector Search と Automated Embedding を選択した Atlas のインデックス設定画面

  1. JSON エディタを選び、データベースと documents_document コレクションを選択し、インデックス名を autoembed_index にします(.env の VECTOR_INDEX_NAME と一致させる必要があります)。次の定義を貼り付けます。
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

abstract フィールドに対する voyage-4-lite を用いた autoEmbed インデックス定義を記述した Atlas の JSON エディタ

定義を確認し、インデックスを作成します。

regulations_qa.documents_document 上の autoembed_index ベクトル検索インデックスのレビュー画面

  1. インデックスのステータスがクエリ可能になるまで待ちます。バックグラウンドで埋め込みが生成されています。

Atlas の Search & Vector Search 一覧に、ステータス READY でクエリ可能な autoembed_index が表示されている

プレーンテキストでクエリする

自動埋め込みでは、$vectorSearch ステージにプレーンテキストのクエリを渡し、インデックスと同じモデルで質問を埋め込みます。つまりコード側に埋め込み呼び出しは不要です。

これを実現するため、サービスモジュールを作成します。

# documents/services/search_service.py
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)  # create the client once and reuse it
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 つ目のステージで必要なフィールドに出力を絞り、類似度スコアを追加します。

続いて、ドキュメント検索用のヘルパーを追加します。

# documents/management/commands/search_docs.py
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 シェルのどちらかを使用します。

regulations_qa.documents_document 上の autoembed_index に対する Atlas Search Tester

ステップ 1: MongoDB Atlas とシェルで検索

MongoDB Atlas の UI では、次のクエリを入力します。

which states need to clean up their air

which states need to clean up their air というクエリに対する Search Tester の結果と類似度スコア

シェルでテストするには:

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)))

Django シェル出力。上位 10 件のセマンティック検索結果とスコアを一覧表示

出力は 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")

Django シェルでドキュメント 2026-16515 の abstract に文を追記して保存

ステップ 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)))

編集後の検索結果。ドキュメント 2026-16515 が 10 位から 5 位へ上昇

編集したドキュメントが以前より上位にランクされるはずです。

同じクエリを Search Tester でも実行し、GUI で結果を確認してください。

ここで起きたのは、MongoDB がインデックス対象フィールドの変更を検知して、そのドキュメントの埋め込みを再生成したことです。サンプルで 10 位だったドキュメント 2026-16515 が、編集と同期の後、5 位に上がりました。

まとめ

ここまでお疲れさまでした。MongoDB が埋め込みのワークフローを処理する、ドキュメント Q&A アシスタントが完成しました。以下のステップで実現しました。

  • 挿入: Django ORM を通じてドキュメントを読み込み
  • インデックス: フィールドとモデルを指定するインデックス定義を Atlas UI で 1 つ作成
  • 検索: 埋め込み呼び出しを別途追加せず、小さなサービスからプレーンテキストの質問でクエリ
  • 編集: インデックス対象フィールドの変更は、再埋め込みスクリプトなしで自動再同期

注: 本チュートリアルのデータは米国政府の文書を公開する Federal Register に由来します。本チュートリアルは独立しており、Federal Register による提携・承認は受けていません。

参考資料

トピック