pgvector 2026: Biến PostgreSQL thành Cơ sở dữ liệu Vector Hiệu năng cao — Hướng dẫn Thiết lập, Tối ưu & Tích hợp RAG

-- Chỉ mục HNSW (khuyến nghị cho hầu hết các khối lượng công việc)
CREATE INDEX ON documents
  USING hnsw (embedding vector_l2_ops)
  WITH (m = 16, ef_construction = 64);

-- Chỉ mục IVFFlat (xây dựng nhanh hơn, độ chính xác thấp hơn)
CREATE INDEX ON documents
  USING ivfflat (embedding vector_l2_ops)
  WITH (lists = 100);

-- Khoảng cách L2 (nhỏ hơn = tương tự hơn)
SELECT id, embedding <-> query_vec AS distance
FROM documents ORDER BY distance LIMIT 10;

-- Khoảng cách Cosine (cho embedding đã chuẩn hóa)
SELECT id, embedding <=> query_vec AS distance
FROM documents ORDER BY distance LIMIT 10;

docker run -d \
  --name pgvector-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=vectordb \
  -p 5432:5432 \
  pgvector/pgvector:0.8.2-pg18

# Xác minh
docker exec pgvector-demo psql -U postgres -d vectordb -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

# Cài đặt phụ thuộc build (Ubuntu/Debian)
sudo apt-get install postgresql-server-dev-18 build-essential git

# Clone và build pgvector
git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

-- Kích hoạt extension trong cơ sở dữ liệu
psql -U postgres -d mydb -c "CREATE EXTENSION IF NOT EXISTS vector;"

-- pgvector được cài sẵn trên Supabase. Chỉ cần kích hoạt:
CREATE EXTENSION IF NOT EXISTS vector;

-- Xác minh phiên bản
SELECT extversion FROM pg_extension WHERE extname = 'vector';
-- Trả về: 0.8.2

-- Trên RDS PostgreSQL 18, pgvector có sẵn như một extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Kiểm tra các extension khả dụng nếu cần
SELECT * FROM pg_available_extensions WHERE name = 'vector';

-- Kiểm tra phiên bản pgvector
SELECT extversion FROM pg_extension WHERE extname = 'vector';
-- Mong đợi: 0.8.2

-- Kiểm tra kiểu vector
SELECT '[1,2,3]'::vector(3) <-> '[4,5,6]'::vector(3) AS l2_distance;
-- Mong đợi: ~5.196

-- Tạo bảng với cột vector (1536 chiều = OpenAI embeddings)
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       VARCHAR(512) NOT NULL,
    content     TEXT,
    embedding   vector(1536),
    metadata    JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    tenant_id   INTEGER NOT NULL DEFAULT 0
);

-- Thêm chỉ mục cho các cột filter thường dùng
CREATE INDEX idx_docs_tenant ON documents(tenant_id);
CREATE INDEX idx_docs_created ON documents(created_at);

-- Chèn một tài liệu đơn với embedding
INSERT INTO documents (title, content, embedding, metadata, tenant_id)
VALUES (
    'Introduction to pgvector',
    'pgvector adds vector support to PostgreSQL...',
    ARRAY_FILL(0.0::real, ARRAY[1536])::vector(1536),  -- placeholder
    '{"author": "dibi8", "category": "database"}',
    1
);

-- Chèn với OpenAI embedding thực (từ Python)
-- Xem phần Tích hợp RAG bên dưới cho ví dụ đầy đủ

# Chèn vector hàng loạt từ Python
import psycopg2
import numpy as np

conn = psycopg2.connect("dbname=vectordb user=postgres password=mysecretpassword host=localhost")
cur = conn.cursor()

# Tạo 10K vector ngẫu nhiên làm mẫu
batch_size = 10000
titles = [f"document_{i}" for i in range(batch_size)]
contents = [f"Content for document {i}" for i in range(batch_size)]
embeddings = np.random.randn(batch_size, 1536).astype(np.float32)
tenant_ids = [i % 10 for i in range(batch_size)]

# Dùng executemany để chèn hàng loạt
args = [(titles[i], contents[i], embeddings[i].tolist(), tenant_ids[i]) for i in range(batch_size)]
cur.executemany(
    "INSERT INTO documents (title, content, embedding, tenant_id) VALUES (%s, %s, %s::vector, %s)",
    args
)
conn.commit()
print(f"Đã chèn {batch_size} tài liệu")

-- Đặt tham số cho xây dựng chỉ mục song song
SET maintenance_work_mem = '8GB';
SET max_parallel_maintenance_workers = 4;

-- Xây dựng chỉ mục HNSW với tham số được tối ưu
CREATE INDEX idx_docs_embedding_hnsw ON documents
  USING hnsw (embedding vector_l2_ops)
  WITH (
    m = 16,              -- Số kết nối mỗi lớp (mặc định: 16)
    ef_construction = 128  -- Kích thước danh sách ứng viên động (mặc định: 64)
  );

-- Kiểm tra kích thước chỉ mục
SELECT pg_size_pretty(pg_relation_size('idx_docs_embedding_hnsw'));
-- Điển hình: ~450 MB cho 100K vector 1536 chiều

-- Tìm kiếm ANN cơ bản
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
ORDER BY embedding <-> $1::vector
LIMIT 10;

-- Tìm kiếm vector có lọc (pattern sản xuất phổ biến nhất)
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
WHERE tenant_id = 42
  AND created_at > NOW() - INTERVAL '30 days'
  AND metadata->>'category' = 'tech'
ORDER BY embedding <-> $1::vector
LIMIT 20;

-- Bật pg_trgm cho tìm kiếm văn bản
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- Kết hợp vector similarity + text relevance
SELECT
    d.id,
    d.title,
    d.embedding <-> $1::vector AS vec_distance,
    similarity(d.title, $2) AS text_similarity
FROM documents d
WHERE d.title % $2  -- trigram similarity filter
ORDER BY
    (d.embedding <-> $1::vector) * 0.7 + (1 - similarity(d.title, $2)) * 0.3
LIMIT 10;

-- Tinh chỉnh ef_search cho độ chính xác so với độ trễ
-- Cao hơn = độ chính xác tốt hơn, truy vấn chậm hơn
SET hnsw.ef_search = 100;  -- Mặc định là 40; 64-128 là điển hình cho sản xuất

-- Kiểm tra kế hoạch truy vấn thực tế
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
ORDER BY embedding <-> $1::vector
LIMIT 10;
-- Tìm: Index Scan using idx_docs_embedding_hnsw

-- Thêm cột halfvec cho lưu trữ lượng tử
ALTER TABLE documents ADD COLUMN embedding_half halfvec(1536);

-- Chuyển đổi từ độ chính xác đầy đủ
UPDATE documents SET embedding_half = embedding::halfvec;

-- Tạo chỉ mục HNSW trên halfvec
CREATE INDEX idx_docs_embedding_half_hnsw ON documents
  USING hnsw (embedding_half halfvec_l2_ops);

-- Truy vấn sử dụng halfvec (kết quả gần như giống hệt)
SELECT id, title, embedding_half <-> $1::halfvec AS distance
FROM documents
ORDER BY embedding_half <-> $1::halfvec
LIMIT 10;

-- Kiểm tra tiết kiệm không gian
SELECT
    pg_size_pretty(pg_relation_size('idx_docs_embedding_hnsw')) AS full_size,
    pg_size_pretty(pg_relation_size('idx_docs_embedding_half_hnsw')) AS half_size;
-- half_size thường là ~45-50% của full_size

; pgbouncer.ini cho khối lượng công việc pgvector
[databases]
vectordb = host=localhost port=5432 dbname=vectordb

[pgbouncer]
pool_mode = transaction
max_client_conn = 10000
default_pool_size = 50
reserve_pool_size = 10

pip install langchain-postgres==0.0.13 langchain-openai==0.3.0

from langchain_postgres import PGVector
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

vector_store = PGVector(
    connection="postgresql://postgres:mysecretpassword@localhost:5432/vectordb",
    embeddings=embeddings,
    collection_name="documents",
    use_jsonb=True,
)

# Thêm tài liệu
from langchain_core.documents import Document
docs = [
    Document(page_content="pgvector turns PostgreSQL into a vector database", metadata={"source": "blog"}),
    Document(page_content="HNSW indexes provide fast ANN search", metadata={"source": "docs"}),
]
vector_store.add_documents(docs)

# Tìm kiếm tương tự có lọc
results = vector_store.similarity_search(
    "vector database for RAG",
    k=5,
    filter={"source": "blog"}
)
for doc in results:
    print(f"Content: {doc.page_content}")

pip install llama-index-vector-stores-postgres==0.4.2

from llama_index.vector_stores.postgres import PGVectorStore
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding

vector_store = PGVectorStore.from_params(
    host="localhost",
    port=5432,
    database="vectordb",
    user="postgres",
    password="mysecretpassword",
    table_name="llama_index_docs",
    embed_dim=1536,
    hnsw_kwargs={
        "hnsw_m": 16,
        "hnsw_ef_construction": 128,
        "hnsw_ef_search": 100,
        "hnsw_dist_method": "vector_l2_ops",
    },
)

# Tải tài liệu
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents, vector_store=vector_store)

# Truy vấn
query_engine = index.as_query_engine()
response = query_engine.query("How does pgvector work?")
print(response)

import psycopg2
from openai import OpenAI
import numpy as np

client = OpenAI()
conn = psycopg2.connect("dbname=vectordb user=postgres password=mysecretpassword host=localhost")

def get_embedding(text: str) -> list[float]:
    resp = client.embeddings.create(
        model="text-embedding-3-large", input=text, dimensions=1536
    )
    return resp.data[0].embedding

def retrieve_documents(query: str, top_k: int = 5, tenant_id: int = 1):
    query_vec = get_embedding(query)
    cur = conn.cursor()
    cur.execute("""
        SELECT title, content, embedding <=> %s::vector AS distance
        FROM documents
        WHERE tenant_id = %s
        ORDER BY embedding <=> %s::vector
        LIMIT %s
    """, (query_vec, tenant_id, query_vec, top_k))
    return cur.fetchall()

# Pipeline RAG đầy đủ
def rag_query(user_question: str) -> str:
    docs = retrieve_documents(user_question, top_k=5)
    context = "\n\n".join([f"Title: {d[0]}\n{d[1]}" for d in docs])
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer based on the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {user_question}"}
        ]
    )
    return response.choices[0].message.content

print(rag_query("What is pgvector used for?"))

-- Bật RLS
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- Chính sách: tenant chỉ có thể xem tài liệu của mình
CREATE POLICY tenant_isolation ON documents
    USING (tenant_id = current_setting('app.current_tenant')::INTEGER);

-- Đặt tenant cho mỗi phiên
SET app.current_tenant = '42';

-- Giờ mọi truy vấn tự động lọc theo tenant
SELECT * FROM documents;  -- Chỉ hiển thị tài liệu của tenant 42

-- Theo dõi truy vấn vector chậm
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Tìm top truy vấn vector theo độ trễ
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
WHERE query LIKE '%<->%'
ORDER BY mean_exec_time DESC
LIMIT 10;

# Bật pg_stat_statements trong postgresql.conf
shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all
pg_stat_statements.max = 10000

# Sao lưu đầy đủ bao gồm dữ liệu vector
pg_dump -h localhost -U postgres -d vectordb -Fc > vectordb_backup.dump

# Khôi phục
pg_restore -h localhost -U postgres -d vectordb_restore vectordb_backup.dump

# Vector được sao lưu dưới dạng mảng văn bản và được khôi phục chính xác

# Sử dụng connection pooling cho khối lượng công việc sản xuất
from psycopg2 import pool

conn_pool = pool.ThreadedConnectionPool(
    minconn=5,
    maxconn=50,
    host="localhost",
    database="vectordb",
    user="postgres",
    password="mysecretpassword"
)

def search_with_pool(query_vec, limit=10):
    conn = conn_pool.getconn()
    try:
        cur = conn.cursor()
        cur.execute(
            "SELECT id, title FROM documents ORDER BY embedding <-> %s::vector LIMIT %s",
            (query_vec, limit)
        )
        return cur.fetchall()
    finally:
        conn_pool.putconn(conn)

SELECT title, embedding <-> $1::vector AS distance
FROM documents
WHERE tenant_id = 42
  AND created_at > NOW() - INTERVAL '7 days'
  AND metadata @> '{"status": "published"}'
ORDER BY embedding <-> $1::vector
LIMIT 10;

-- Đánh giá các giá trị ef_search
SET hnsw.ef_search = 64;
EXPLAIN ANALYZE SELECT ... ORDER BY embedding <-> $1 LIMIT 10;

SET hnsw.ef_search = 128;
EXPLAIN ANALYZE SELECT ... ORDER BY embedding <-> $1 LIMIT 10;