جستجوی معنایی با pgvector در PostgreSQL؛ از نصب تا ایندکس HNSW


چرا جستجوی معنایی داخل PostgreSQL؟ #

وقتی صحبت از جستجوی معنایی و embedding می‌شود، خیلی‌ها فوراً به سراغ دیتابیس‌های برداری اختصاصی می‌روند. اما اگر داده‌های اصلی شما همین حالا در PostgreSQL است، اضافه کردن یک سرویس جدید یعنی همگام‌سازی داده بین دو سیستم، دو نسخهٔ پشتیبان، دو مدل امنیتی و یک نقطهٔ شکست بیشتر.

pgvector یک افزونهٔ متن‌باز برای PostgreSQL است که نوع دادهٔ برداری، عملگرهای فاصله و ایندکس‌های جستجوی تقریبی را مستقیماً به دیتابیس اضافه می‌کند. یعنی می‌توانید بردارها را کنار داده‌های معمولی‌تان نگه دارید و در یک کوئری SQL هم فیلتر معمولی بزنید، هم JOIN کنید و هم بر اساس شباهت معنایی مرتب کنید. طبق صفحهٔ پروژه، pgvector از جستجوی دقیق و تقریبی، فاصله‌های L2، inner product، cosine، L1، Hamming و Jaccard پشتیبانی می‌کند و همهٔ مزایای Postgres مثل ACID، بازیابی point-in-time و JOIN را حفظ می‌کند.

نصب و راه‌اندازی #

ساده‌ترین راه استفاده از ایمیج Docker آماده است:

bash
docker run -d --name pg-vector \
    -e POSTGRES_PASSWORD=secret \
    -p 5432:5432 \
    pgvector/pgvector:pg18

روی سیستم‌عامل‌های لینوکسی معمولاً بستهٔ آماده هم وجود دارد (مثلاً postgresql-18-pgvector در مخزن PGDG). بعد از نصب، افزونه را در هر دیتابیسی که لازم دارید فعال کنید:

sql
CREATE EXTENSION IF NOT EXISTS vector;

یادداشت

نام افزونه در SQL vector است، نه pgvector. این یکی از رایج‌ترین اشتباه‌های اولین استفاده است.

نوع دادهٔ vector #

بعد از فعال‌سازی، یک نوع دادهٔ جدید به نام vector(n) دارید که n تعداد ابعاد است:

schema.sqlsql
CREATE TABLE articles (
    id          bigserial PRIMARY KEY,
    title       text NOT NULL,
    body        text NOT NULL,
    category    text,
    published   boolean DEFAULT true,
    embedding   vector(1536)
);

تعداد ابعاد باید دقیقاً با خروجی مدل embedding شما برابر باشد. اگر مدل شما بردار ۱۰۲۴ بُعدی تولید می‌کند، ستون را vector(1024) تعریف کنید.

درج داده با یک رشتهٔ ساده انجام می‌شود:

sql
INSERT INTO articles (title, body, embedding)
VALUES ('سلام', 'متن نمونه', '[0.12, -0.03, 0.88, ...]');

عملگرهای فاصله #

بردارهای متن در فضای چندبعدی؛ متن‌های هم‌معنا کنار هم قرار می‌گیرند

pgvector چند عملگر فاصله دارد که باید با معیار مدل embedding خود هماهنگ کنید:

عملگر معیار کلاس عملگر ایندکس
<-> فاصلهٔ اقلیدسی (L2) vector_l2_ops
<#> ضرب داخلی منفی vector_ip_ops
<=> فاصلهٔ کسینوسی vector_cosine_ops
<+> فاصلهٔ L1 (منهتن) vector_l1_ops

یک کوئری جستجوی ساده:

sql
SELECT id, title, embedding <=> '[0.11, -0.02, 0.91, ...]' AS distance
FROM articles
ORDER BY embedding <=> '[0.11, -0.02, 0.91, ...]'
LIMIT 5;

نکته

عملگر <#> ضرب داخلی را منفی برمی‌گرداند، چون Postgres فقط از اسکن ایندکس با ترتیب صعودی پشتیبانی می‌کند. برای گرفتن شباهت واقعی آن را در -1 ضرب کنید. برای cosine هم شباهت برابر 1 - (a <=> b) است.

اگر بردارهای مدل شما نرمال‌شده هستند (طول ۱ دارند)، که در بیشتر مدل‌های embedding مدرن این‌طور است، inner product سریع‌ترین گزینه است و نتیجه‌ای معادل cosine می‌دهد.

ایندکس‌گذاری: HNSW یا IVFFlat #

بدون ایندکس، pgvector جستجوی دقیق انجام می‌دهد؛ یعنی فاصلهٔ بردار پرسش را با تک‌تک ردیف‌ها حساب می‌کند. این برای چند ده هزار ردیف قابل قبول است، اما برای میلیون‌ها ردیف کند می‌شود. اینجا ایندکس‌های تقریبی (Approximate Nearest Neighbor) وارد می‌شوند که کمی دقت (recall) را با سرعت بسیار بیشتر معاوضه می‌کنند.

ساختار لایه‌ای گراف HNSW برای جستجوی سریع نزدیک‌ترین همسایه

HNSW #

HNSW یک گراف چندلایه می‌سازد که جستجو از لایه‌های بالایی (با یال‌های بلند) شروع شده و به لایه‌های پایین‌تر (با جزئیات بیشتر) می‌رسد:

sql
CREATE INDEX ON articles USING hnsw (embedding vector_cosine_ops);

پارامترهای ساخت:

sql
CREATE INDEX ON articles USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
  • m: حداکثر تعداد اتصال هر گره در هر لایه (پیش‌فرض ۱۶).
  • ef_construction: اندازهٔ لیست کاندیدها هنگام ساخت گراف (پیش‌فرض ۶۴). عدد بالاتر یعنی گراف باکیفیت‌تر اما ساخت کندتر.

و پارامتر زمان جستجو:

sql
SET hnsw.ef_search = 100;

مقدار پیش‌فرض ef_search برابر ۴۰ است. افزایش آن recall را بالا می‌برد و جستجو را کمی کندتر می‌کند. می‌توانید آن را فقط برای یک تراکنش تنظیم کنید:

sql
BEGIN;
SET LOCAL hnsw.ef_search = 200;
SELECT ... ;
COMMIT;

IVFFlat #

IVFFlat بردارها را به تعدادی خوشه (list) تقسیم می‌کند و هنگام جستجو فقط چند خوشهٔ نزدیک را بررسی می‌کند:

sql
CREATE INDEX ON articles USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

SET ivfflat.probes = 10;

مهم

ایندکس IVFFlat را بعد از پر کردن جدول بسازید. این ایندکس خوشه‌ها را بر اساس داده‌های موجود تعیین می‌کند و ساختن آن روی جدول خالی نتیجهٔ بدی می‌دهد. HNSW چنین محدودیتی ندارد.

معیار HNSW IVFFlat
سرعت جستجو و recall بهتر متوسط
زمان ساخت کندتر سریع‌تر
مصرف حافظه بیشتر کمتر
ساخت روی جدول خالی مشکلی ندارد توصیه نمی‌شود

برای بیشتر پروژه‌ها HNSW انتخاب پیش‌فرض خوبی است.

محدودیت ابعاد و halfvec #

طبق مستندات pgvector، ایندکس‌گذاری روی نوع vector تا ۲۰۰۰ بُعد پشتیبانی می‌شود. اگر مدل شما بردار بزرگ‌تری تولید می‌کند، می‌توانید از نوع halfvec (اعداد اعشاری نیم‌دقت) استفاده کنید که تا ۴۰۰۰ بُعد قابل ایندکس است و نصف فضا را هم می‌گیرد:

sql
CREATE INDEX ON articles
USING hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops);

SELECT id, title FROM articles
ORDER BY embedding::halfvec(3072) <=> '[...]'::halfvec(3072)
LIMIT 5;

پیاده‌سازی با پایتون #

کتابخانهٔ pgvector برای پایتون، آداپتورهای psycopg، SQLAlchemy و Django را فراهم می‌کند:

bash
uv add "psycopg[binary]" pgvector numpy
search.pypython
import numpy as np
import psycopg
from pgvector.psycopg import register_vector

conn = psycopg.connect("postgresql://postgres:secret@localhost/postgres", autocommit=True)
conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
register_vector(conn)

def add_article(title: str, body: str, embedding: np.ndarray):
    conn.execute(
        "INSERT INTO articles (title, body, embedding) VALUES (%s, %s, %s)",
        (title, body, embedding),
    )

def semantic_search(query_vec: np.ndarray, category: str | None = None, k: int = 5):
    sql = """
        SELECT id, title, 1 - (embedding <=> %(q)s) AS similarity
        FROM articles
        WHERE published AND (%(cat)s::text IS NULL OR category = %(cat)s)
        ORDER BY embedding <=> %(q)s
        LIMIT %(k)s
    """
    return conn.execute(sql, {"q": query_vec, "cat": category, "k": k}).fetchall()

در Django #

models.pypython
from django.db import models
from pgvector.django import VectorField, HnswIndex, CosineDistance

class Article(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField()
    embedding = VectorField(dimensions=1536)

    class Meta:
        indexes = [
            HnswIndex(
                name="article_embedding_hnsw",
                fields=["embedding"],
                m=16,
                ef_construction=64,
                opclasses=["vector_cosine_ops"],
            )
        ]

# جستجو
# Article.objects.order_by(CosineDistance("embedding", query_vec))[:5]

برای فعال‌سازی افزونه در Django یک مایگریشن با VectorExtension() از pgvector.django بسازید.

فیلتر و ایندکس تقریبی: یک دام رایج #

وقتی WHERE را با ORDER BY ... LIMIT روی ایندکس تقریبی ترکیب می‌کنید، Postgres ابتدا از ایندکس نزدیک‌ترین کاندیدها را می‌گیرد و سپس فیلتر را اعمال می‌کند. اگر فیلتر شما بیشتر ردیف‌ها را حذف کند، ممکن است کمتر از تعداد درخواستی نتیجه بگیرید.

راه‌حل‌ها:

  • برای فیلترهای پرکاربرد با تعداد مقادیر کم، ایندکس جزئی (partial index) بسازید: CREATE INDEX ... WHERE category = 'news'.
  • ef_search را بالا ببرید.
  • از قابلیت iterative index scan در نسخه‌های جدید pgvector استفاده کنید که در صورت کم بودن نتایج، اسکن ایندکس را ادامه می‌دهد (SET hnsw.iterative_scan = relaxed_order;).
  • همیشه با EXPLAIN ANALYZE بررسی کنید که ایندکس واقعاً استفاده می‌شود. اگر با این دستور آشنا نیستید، راهنمای EXPLAIN ANALYZE در PostgreSQL را بخوانید.

چک‌لیست راه‌اندازی در production #

  • ابعاد ستون با مدل embedding یکسان است.
  • کلاس عملگر ایندکس با عملگر کوئری هماهنگ است (vector_cosine_ops با <=>).
  • maintenance_work_mem برای ساخت سریع‌تر HNSW به‌اندازهٔ کافی بزرگ است.
  • ساخت ایندکس روی جدول بزرگ با CREATE INDEX CONCURRENTLY انجام می‌شود.
  • ef_search با یک مجموعهٔ ارزیابی recall تنظیم شده است.
  • برای ستون‌های بسیار بزرگ استفاده از halfvec بررسی شده است.
آیا pgvector برای میلیون‌ها بردار مناسب است؟

بله، با ایندکس HNSW و حافظهٔ کافی، میلیون‌ها بردار در یک سرور قابل مدیریت است. برای مقیاس‌های بسیار بزرگ‌تر، partitioning یا sharding (مثلاً با Citus) هم پشتیبانی می‌شود.

آیا می‌توانم جستجوی متنی و برداری را ترکیب کنم؟

بله. می‌توانید نتایج full-text search خود Postgres (tsvector) را با نتایج برداری با روشی مثل Reciprocal Rank Fusion ترکیب کنید و یک جستجوی ترکیبی (hybrid) داشته باشید.

جمع‌بندی #

pgvector به شما اجازه می‌دهد جستجوی معنایی و پایه‌های یک سیستم RAG را بدون اضافه کردن زیرساخت جدید، داخل همان PostgreSQL آشنا بسازید. با انتخاب درست عملگر فاصله، ایندکس HNSW و تنظیم ef_search، به عملکردی می‌رسید که برای اکثر محصولات کافی است. اگر هنوز با مفهوم RAG آشنا نیستید، مطلب RAG چیست را بخوانید.

این پست چطور بود؟

پست‌های مرتبط