Ana içeriğe geç

Django ve MongoDB Otomatik Gömme (Auto-Embeddings) ile Bir Soru-Cevap Asistanı Oluşturma

MongoDB otomatik gömmelerle Django’da anlamsal arama kurun: gömme kodu yok, belgeler değiştiğinde otomatik yeniden eşitleme ve düz metin sorguları.
· 7 dk. oku

Yapay Zeka ile Keşfedin

Otomatik Gömmenin Kolaylaştırdıkları

Tipik bir geri getirme destekli üretim (RAG) kurulumunda, bir belge eklediğinizde gömmeler oluşturur, içerik değiştiğinde yeniden oluşturur ve her sorguyu kendiniz gömersiniz. Otomatik Gömme, MongoDB Atlas’ın gömme oluşturmayı, güncellemeleri ve sorgulamayı yerel olarak ele alması ve Vector Search’ün üretilen vektör gömmelerini kümenizde saklaması sayesinde anlamsal arama oluşturma sürecini basitleştirir.

MongoDB otomatik gömmeyi nasıl yapar

autoEmbed türünde bir vektör arama indeksi oluşturulduğunda, MongoDB seçilen alan için gömmeler üretir, VoyageAI modelini kullanır, belgede değişiklik olduğunda bunları senkronize tutar ve sorgu metnini arama anında aynı modelle gömer. Üretilen gömmeler MongoDB kümesinde ayrı bir dahili veritabanında eşzamansız olarak saklanır.

Bu eğitimde, MongoDB otomatik gömmeleriyle bir S&C Doküman Asistanı (Q&A) oluşturacağız. Modelleri tanımlamak ve belgeleri almak için Django MongoDB arka ucunu kullanacağız; aramalar, gömmelerin otomatik üretilmesi ve senkronizasyonu için MongoDB kullanılacak ve LLM, getirilen sonuçlara göre belgeleri döndürecek.

Bu eğitimin sonunda, bir RAG hattının geri getirme aşamasını oluşturmuş olacaksınız: Otomatik gömmelerin gömme işini sizin için üstlendiği Federal Register belgeleri üzerinde bir anlamsal arama. Belgeler eklediğinizde gömülür, değiştiklerinde yeniden gömülür ve sorgularınız arama anında gömülür; üstelik herhangi bir gömme kodu yazmadan.

Bu eğitimi iki yoldan biriyle takip edebilirsiniz.

Kurulum

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

Bu önkoşullar tamamlandığında, bir sonraki adım proje klasörünüzü oluşturmaktır.

Proje ve sanal ortam oluşturun

Projeniz için boş bir klasör oluşturun ve içine cd ile girin.

mkdir regulations_qa
cd regulations_qa

Burası projenizin kök dizinidir. Daha önce yapmadıysanız sanal ortamınızı burada oluşturup etkinleştirin:

python -m venv .venv

macOS veya Linux’ta sanal ortamı etkinleştirmek için şunu çalıştırın:

source .venv/bin/activate

Windows’ta şunu çalıştırın:

.venv\Scripts\activate

Bağımlılıkları Yükleyin

Aşağıdaki içerikle projenin kökünde bir requirements.txt dosyası oluşturun:

# requirements.txt
django-mongodb-backend
python-dotenv
requests #to fetch documents from the Federal Register API.

Ardından hepsini yükleyin:

pip install -r requirements.txt

Django Projesi ve Uygulaması Oluşturun

Projenizin kök dizininden, yeni bir Django projesi ve uygulaması oluşturmak için aşağıdaki komutu çalıştırın. startproject komutundaki sonda gelen . işaretini ekleyin; bu, Django’ya yeni bir iç içe klasör oluşturmak yerine projeyi mevcut dizine kurmasını söyler.

django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .

documents uygulamasını oluşturun

python manage.py startapp documents

Uygulamayı regulations_qa/settings.py içinde INSTALLED_APPS’e ekleyerek kaydedin:

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',
]

Ortam değişkenlerini yapılandırın

Projenin kökünde kendi değerlerinizle bir .env dosyası oluşturun ve push ettiğinizde commit edilmemesi için .gitignore’a ekleyin.

# .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 içindeki orijinal sabit SECRET_KEY = '...' satırını silin, startproject çalıştırdığınızda Django’nun settings.py’de ürettiği değeri kopyalayın ve .env dosyanıza koyun. Varsayılan olarak orada sabit kodlanmıştır ve biz bunu sürüm kontrolünün dışında tutmak için .env’e taşıyoruz; çünkü Django bunu oturum çerezlerini, CSRF belirteçlerini ve diğer güvenlik açısından hassas verileri imzalamak için kullanır.

regulations_qa/settings.py dosyasını açın ve aşağıdakilerin tamamını içerdiğinden emin olun. İçe aktarma satırları ve load_dotenv() en üste gelir. Mevcut SECRET_KEY ve DATABASES tanımlarını değiştirin ve VECTOR_INDEX_NAME satırını ekleyin:

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"),
    },
}

Yönetim komutları için klasörler oluşturun

Sonraki adımda, yönetim komutları için boş __init__.py dosyalarına sahip klasörler oluşturuyoruz; çünkü Django özel komutları yalnızca bir management/commands/ paketinde keşfeder.

mkdir -p documents/management/commands documents/services && touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.py

Veri kaynağı: Federal Register belgeleri

Bu eğitimde, Federal Register’dan belgeleri indeksleyeceğiz; ABD hükümetinin kural, taslak kural ve bildirimlere ilişkin günlük yayımları. Veri kaynağı, başlık ve kısa bir düzyazı özet içeren ve anlamsal arama ile iyi çalışan belgelerden oluşan bir herkese açık API’dir.

API dokümantasyonu: https://www.federalregister.gov/developers/documentation/api/v1

Kaytlarda title, type, abstract, document_number (benzersiz bir ID), publication_date, html_url ve bir agencies listesi gibi alanlar bulunur.

  • Bazı belgelerde null değerler vardır; bu nedenle bunları atlayacağız.
  • Özetlerde “PM2.5” içindeki <INF>2.5</INF> gibi işaretlemeler bulunur; kaydetmeden önce etiketleri temizleriz.
  • Sonuçlar istek başına en fazla 100 olacak şekilde sayfalanır ve her sayfa takip edilecek bir next_page_url (imleç tabanlı) içerir.

Uç noktayı kabuktan test edin

curl -g "https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"

Not: Bu, gösterim amaçlı kullanılan kamuya açık ABD hükümet verisidir. Hukuki bir kaynak değildir; hukuki araştırmalar için resmi baskıyı kullanın.

Verileri İçe Alın

models.py dosyasında modelleri oluşturarak başlayacağız.

# 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]}"

Ardından, göçleri (migration) oluşturup çalıştırıyoruz.

python manage.py makemigrations documents
python manage.py migrate

Şimdi, içe alma kısmına geçelim.

# 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()}")

Komutu çalıştırın:

python manage.py ingest_federal_register --limit 100

İçe aktarmayı MongoDB Atlas arayüzünde doğrulayabilirsiniz:

MongoDB Atlas Data Explorer, regulations_qa.documents_document koleksiyonunda 100 Federal Register belgesini gösteriyor

Otomatik Gömme İndeksini Tanımlayın

Vektör arama indeksi, MongoDB’ye hangi alan üzerinde gömme yapılacağını ve hangi modelin kullanılacağını söyler. Bundan sonra MongoDB gömmeleri otomatik olarak oluşturur ve saklar.

  1. Atlas arayüzünde kümenizi açın, Search & Vector Search’e gidin ve Create Search Index’e tıklayın.

MongoDB Atlas’ta Create Search Index düğmesiyle Search & Vector Search sayfası

  1. Arama türü olarak Vector Search’ü ve vektör verinizi kurma yöntemi olarak Automated Embedding’i seçin.

Vector Search ve Automated Embedding seçili Atlas indeks yapılandırması

  1. JSON düzenleyiciyi seçin, veritabanınızı ve documents_document koleksiyonunu işaretleyin ve indeksi autoembed_index olarak adlandırın (ad, .env dosyanızdaki VECTOR_INDEX_NAME ile eşleşmelidir). Şu tanımı yapıştırın:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

voyage-4-lite kullanarak abstract alanı için autoEmbed indeks tanımıyla Atlas JSON düzenleyicisi

Tanımı gözden geçirin ve ardından indeksi oluşturun.

regulations_qa.documents_document üzerinde autoembed_index vektör arama indeksinin inceleme adımı

  1. Gömmeler arka planda oluşturulduğu için indeks durumu sorgulanmaya hazır görünene kadar bekleyin.

Atlas Search & Vector Search listesi autoembed_index’i READY ve sorgulanabilir durumda gösteriyor

Düz Metinle Sorgulama

Otomatik gömmeler için, düz metin bir sorguyla $vectorSearch aşamasını kullanır ve soruyu indeksin kullandığı aynı modelle gömeriz; böylece kodumuzda herhangi bir gömme çağrısı olmaz.

Bunu gerçekleştirmek için bir servis modülü oluşturacağız.

# 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 bağlantısını bir kez oluşturur ve yeniden kullanır. lru_cache, ilk çağrının sonucunu hatırlar; böylece her arama her seferinde yeni bir bağlantı açmak yerine tek bir istemciyi paylaşır.
  • _get_collection(), Django’nun kullandığı aynı ayarlarla regulations_qa veritabanını ve documents_document koleksiyonunu seçer.
  • _get_index_name(), indeks adını ayarlardan okur ve eksikse net bir hata verir.
  • semantic_search(), soruyu query alanında metin olarak gönderir. İkinci aşama, çıktıyı ihtiyaç duyduğumuz alanlara kırpar ve benzerlik skorunu ekler.

Ardından belgelere arama yapmak için bir yardımcı ekliyoruz:

# 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]}"
            )

Şimdi test etmek için şunu çalıştırın:

python manage.py search_docs "limits on pollution from factories"

Örnekte, özetlerle ortak anahtar kelimeleri paylaşmayan soruları seçiyoruz. “limits on pollution from factories” hakkında bir soru, emisyon standartlarıyla ilgili belgeleri getirmelidir.

Not: Ödeme yöntemi olmayan ücretsiz (M0) bir kümede, sorgu gömme istekleri hız sınırına takılabilir.

Demo: Bir Belgeyi Düzenleyin ve Yeniden Senkronizasyonu İzleyin

Demo için, ya MongoDB Atlas’taki Search Tester’ı kullanabiliriz (önceden regulations_qa.documents_document koleksiyonu üzerinde oluşturduğumuz autoembed_index’e bağlıdır) ya da Python kabuğunu kullanabiliriz.

regulations_qa.documents_document üzerinde autoembed_index için Atlas Search Tester

Adım 1: MongoDB Atlas ve kabuk üzerinden arayın

Bunu MongoDB Atlas arayüzünde test etmek için şu sorguyu girin:

which states need to clean up their air

which states need to clean up their air sorgusu için benzerlik skorlarıyla Search Tester sonuçları

Kabuk üzerinden test etmek için:

python manage.py shell ile kabuğu açın, ardından şunu çalıştırın:

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 kabuğu çıktısı, ilk 10 anlamsal arama sonucunu ve skorlarını listeliyor

Çıktı, GUI üzerinden gördüklerimizle aynı olmalıdır.

Adım 2: Belgeyi düzenleyin

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 kabuğu, 2026-16515 numaralı belgenin özetine bir cümle ekleyip kaydediyor

Adım 3: Yeniden arayın

Otomatik gömmeler eşzamansız oluşturulur; bu nedenle 30–60 saniye bekleyin ve ardından sorguyu tekrar çalıştırın:

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

Düzenlemeden sonraki arama sonuçları; 2026-16515 belgesi 10.’dan 5.’liğe yükselmiş

Şimdi, düzenlenen belgenin öncekine göre daha üst sıralarda çıktığını görmeyi beklemeliyiz.

Aynı sorguyu Search Tester’da çalıştırarak sonuçları GUI üzerinden de görün.

Olan şu: MongoDB, indekslenen alanın değiştiğini fark edip o belgenin gömmesini yeniden oluşturdu; böylece örnekte 10. sırada olan 2026-16515 numaralı belge, düzenleme ve senkronizasyon sonrasında daha yüksek puanlanarak 5. sıraya yerleşti.

Kapanış

Buraya kadar geldiğiniz için tebrikler! Gömme iş akışını MongoDB’nin yönettiği verilerle bir doküman S&C asistanımız var. Bunu şu adımlarla başardık:

  • Ekleme: belgeler Django ORM üzerinden yüklendi
  • İndeks: alan ve modeli belirten tek bir indeks tanımı, Atlas arayüzünde oluşturuldu.
  • Sorgu: ayrı bir gömme çağrısı eklemeden küçük bir servis aracılığıyla düz metin sorular.
  • Düzenleme: indekslenen alandaki değişiklikler, yeniden gömme betiğine gerek kalmadan yeniden senkronize edilir.

Not: Bu eğitimdeki veriler, ABD hükümeti belgelerini yayımlayan Federal Register’dan gelmektedir. Bu eğitim bağımsızdır ve Federal Register ile ilişkili veya onun tarafından onaylanmış değildir.

Kaynaklar

Afi Gbadago

Yazar

Afi Gbadago

Afi, MongoDB'de geliştiriciler için savunuculuk yaparak Django ve Python'a odaklanır; eğitimler, konuşmalar ve topluluk etkileşimi aracılığıyla mühendislerin modern veri teknolojileriyle geliştirme yapmalarına yardımcı olur. Python ve Web alanında tanınmış bir Microsoft MVP'sidir; Django Software Foundation yönetim kurulunda görev yapar ve DjangoCon US 2025 için Program Başkanıdır. Afi ayrıca Black Python Devs için Bölgesel Yürütücüdür ve aktif bir açık kaynak katkıcısı ile uluslararası konuşmacıdır.

Konular

İlgili