Arkitektura e Kërkimit Hibrid Semantik dhe Leksikal me PostgreSQL pgvector dhe Next.js 16: Përshtatja për Gjuhën Shqipe dhe E-Commerce me Shpejtësi Nën-50ms

---

title: "Arkitektura e Kërkimit Hibrid Semantik dhe Leksikal me PostgreSQL pgvector dhe Next.js 16: Përshtatja për Gjuhën Shqipe dhe E-Commerce me Shpejtësi Nën-50ms" description: "Si të ndërtohet një motor kërkimi hibrid nën-50ms me pgvector, BM25 dhe Reciprocal Rank Fusion (RRF) në Next.js 16, i optimizuar për specifikat morfologjike të gjuhës shqipe dhe katalogët e-commerce në Kosovë." publishedAt: "2026-10-02" author: "Postieri XYZ Team" tags: ["PostgreSQL", "pgvector", "Next.js 16", "Hybrid Search", "AI Engineering", "E-Commerce", "Kosovo Business"] category: "Software Engineering" featured: true heroImage: "/images/posts/arkitektura-kerkimit-hibrid-semantik-pgvector-nextjs-16.jpg"

Në tregtinë elektronike moderne dhe platformat B2B në Kosovë, Shqipëri dhe rajon, kërkimi i produkteve (Search & Discovery) është faktori numër një që përcakton normën e konvertimit (conversion rate). Nëse një klient nuk e gjen produktin brenda dy sekondave të para, transaksioni humbet.

Megjithatë, ndërtimi i një motori kërkimi efikas për tregun shqipfolës paraqet sfida unike gjuhësore dhe inxhinierike:

1. Mungesa e shkronjave specifike në tastierë mobile: Përdoruesit shpesh shkruajnë kemishe në vend të këmishë, ose cader në vend të çadër.
2. Variantet dialektore dhe zhargoni tregtar: Një klient kërkon trenerka, një tjetër tutit, ndërsa katalogu zyrtar e ka të regjistruar si pantallona sportive pambuku.
3. Kërkimet teknike me SKU dhe kode: Kur kërkohet iPhone 16 Pro Max 256GB ose Bosch GSB-18V, modeli vektorial shpesh dështon të bëjë përputhje ekzakte, ndërsa kërkimi leksikal shkëlqen.

Zgjidhja inxhinierike standarde për vitin 2026 nuk është instalimi i kllasterave të rëndë dhe të shtrenjtë të Elasticsearch, por Kërkimi Hibrid (Hybrid Search) i integruar direkt në PostgreSQL (pgvector + pg_trgm) dhe i shërbyer në kohë reale me Next.js 16.

Në këtë udhëzues teknik, Ekipi i Postieri XYZ L.L.C. paraqet arkitekturën e plotë të një motori kërkimi hibrid me latencë nën-50ms, bazuar në algoritmin Reciprocal Rank Fusion (RRF).

---

1. Topologjia e Arkitekturës: Hybrid Search me RRF

Kërkimi Hibrid kombinon dy botë paralele:

• Kërkimi Leksikal (Sparse/BM25 + Trigram): Përputhje e saktë fjalë-për-fjalë, kode produktesh (SKU), emra markash dhe tolerancë ndaj gabimeve ortografike (fuzzy search).
• Kërkimi Vektorial (Dense/pgvector): Kuptimi semantik i qëllimit të përdoruesit (intent), sinonimeve dhe kontekstit tematik.

┌─────────────────────────────────────────────────────────────────────────┐
│              Arkitektura e Kërkimit Hibrid (Next.js 16 + pgvector)      │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │    Përdoruesi / Mobile UI   │
                    │   "trenerka te zeza per vrap"│
                    └──────────────┬──────────────┘
                                   │ (Instant Stream / Debounced Input)
                    ┌──────────────▼──────────────┐
                    │     Next.js 16 App Router   │
                    │     (Edge Search Handler)   │
                    └──────────────┬──────────────┘
                                   │
                 ┌─────────────────┴─────────────────┐
                 ▼                                   ▼
      ┌─────────────────────┐             ┌─────────────────────┐
      │  Tekst Normalizimi  │             │   Vector Embedder   │
      │ (Fuzzy / Trigram)   │             │  (Fast AI Embedding)│
      └──────────┬──────────┘             └──────────┬──────────┘
                 │                                   │
                 │ [Sparse Query]                    │ [Dense Vector 768d]
                 ▼                                   ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      PostgreSQL Database Engine                         │
│                                                                         │
│   ┌──────────────────────────────┐    ┌─────────────────────────────┐   │
│   │   GIN Index (pg_trgm/BM25)   │    │     HNSW Index (pgvector)   │   │
│   │   Përputhje Leksikale & SKU  │    │     Distancë Semantike      │   │
│   └──────────────┬───────────────┘    └──────────────┬──────────────┘   │
│                  │                                   │                  │
│                  └─────────────────┬─────────────────┘                  │
│                                    │                                    │
│                     ┌──────────────▼──────────────┐                     │
│                     │  Reciprocal Rank Fusion     │                     │
│                     │  Score = 1/(60+r_lex) +     │                     │
│                     │          1/(60+r_sem)       │                     │
│                     └──────────────┬──────────────┘                     │
└────────────────────────────────────┼────────────────────────────────────┘
                                     │
                      ┌──────────────▼──────────────┐
                      │  Rezultatet e Renditura     │
                      │  (Latenca Totale: < 45ms)   │
                      └─────────────────────────────┘

---

2. Përgatitja e PostgreSQL: Indekset HNSW dhe Normalizimi Shqip

Për të arritur performancë maksimale, aktivizojmë shtesat vector dhe pg_trgm në PostgreSQL dhe krijojmë një funksion për heqjen e diakritikave specifike të shqipes gjatë indeksimit leksikal.

sql
-- 1. Aktivizimi i shtesave të nevojshme
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS unaccent;

-- 2. Tabela e produkteve me mbështetje vektoriale
CREATE TABLE IF NOT EXISTS public.products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    sku VARCHAR(64) NOT NULL UNIQUE,
    title VARCHAR(255) NOT NULL,
    description TEXT NOT NULL,
    category VARCHAR(100) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock_quantity INT NOT NULL DEFAULT 0,
    is_active BOOLEAN NOT NULL DEFAULT true,
    
    -- Embedding semantik (p.sh. model 768-dimensional)
    embedding vector(768),
    
    -- Fushë e gjeneruar për kërkim leksikal të plotë
    search_vector tsvector GENERATED ALWAYS AS (
        to_tsvector('simple', unaccent(title || ' ' || description || ' ' || category || ' ' || sku))
    ) STORED,
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 3. Indeksi HNSW për kërkim vektorial ultra-të-shpejtë (Hierarchical Navigable Small World)
CREATE INDEX IF NOT EXISTS idx_products_embedding_hnsw 
ON public.products 
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- 4. Indeksi GIN për kërkim leksikal dhe përputhje pjesore (Trigram)
CREATE INDEX IF NOT EXISTS idx_products_search_vector_gin 
ON public.products 
USING gin (search_vector);

CREATE INDEX IF NOT EXISTS idx_products_title_trgm 
ON public.products 
USING gin (unaccent(title) gin_trgm_ops);

---

3. Zbatimi i Algoritmit Reciprocal Rank Fusion (RRF) në SQL

Reciprocal Rank Fusion (RRF) është standardi i artë për kombinimin e rezultateve nga motorë kërkimi të ndryshëm pa pasur nevojë për normalizim manual të pikëve (score calibration).

Formula e RRF: $$RRF(d) = \sum_{m \in M} \frac{1}{k + r_m(d)}$$

Ku:

• $M$ është bashkësia e metodave të kërkimit (Leksikal dhe Vektorial).
• $r_m(d)$ është pozicioni i renditjes (rank) së dokumentit $d$ në metodën $m$.
• $k$ është një konstante zbutëse (zakonisht $k = 60$).

Ja query-ja e optimizuar në PostgreSQL me CTEs (Common Table Expressions):

sql
WITH 
-- Hapi 1: Kërkimi Leksikal (Full-Text + Trigram)
lexical_search AS (
    SELECT 
        id,
        ROW_NUMBER() OVER (
            ORDER BY ts_rank_cd(search_vector, to_tsquery('simple', $1)) DESC,
                     similarity(unaccent(title), unaccent($2)) DESC
        ) AS rank
    FROM public.products
    WHERE is_active = true
      AND (
          search_vector @@ to_tsquery('simple', $1)
          OR unaccent(title) % unaccent($2)
          OR sku ILIKE $3
      )
    LIMIT 30
),

-- Hapi 2: Kërkimi Semantik Vektorial (pgvector HNSW)
vector_search AS (
    SELECT 
        id,
        ROW_NUMBER() OVER (ORDER BY embedding <=> $4::vector) AS rank
    FROM public.products
    WHERE is_active = true
      AND embedding IS NOT NULL
    LIMIT 30
),

-- Hapi 3: Bashkimi dhe Renditja sipas RRF
rrf_scores AS (
    SELECT 
        COALESCE(l.id, v.id) AS product_id,
        COALESCE(1.0 / (60 + l.rank), 0.0) +
        COALESCE(1.0 / (60 + v.rank), 0.0) AS score
    FROM lexical_search l
    FULL OUTER JOIN vector_search v ON l.id = v.id
)

-- Hapi 4: Tërheqja e të Dhënave Finale të Produktit
SELECT 
    p.id,
    p.sku,
    p.title,
    p.description,
    p.category,
    p.price,
    p.stock_quantity,
    r.score AS match_relevance
FROM rrf_scores r
JOIN public.products p ON p.id = r.product_id
ORDER BY r.score DESC
LIMIT $5;

---

4. Implementimi në Next.js 16 me Server Actions

Në Next.js 16, ekzekutojmë logjikën e kërkimit në Server Action me latency të minimizuar duke përdorur connection pool dhe paralelizim asinkron.

typescript
// app/actions/search-products.ts
"use server";

import { getDbPool } from "@/lib/db";

interface ProductResult {
  id: string;
  sku: string;
  title: string;
  description: string;
  category: string;
  price: number;
  stock_quantity: number;
  match_relevance: number;
}

// Funksion ndihmës për normalizimin e pyetjes në shqip
function sanitizeQueryAlbanian(raw: string): string {
  return raw
    .toLowerCase()
    .replace(/[ëË]/g, "e")
    .replace(/[çÇ]/g, "c")
    .trim();
}

export async function searchProductsHybrid(
  query: string,
  limit: number = 12
): Promise<{ success: boolean; data: ProductResult[]; latencyMs: number }> {
  const startTime = performance.now();

  if (!query || query.trim().length === 0) {
    return { success: true, data: [], latencyMs: 0 };
  }

  const pool = getDbPool();
  const sanitized = sanitizeQueryAlbanian(query);
  const tsFormatted = sanitized
    .split(/\s+/)
    .filter(Boolean)
    .map((word) => `${word}:*`)
    .join(" & ");

  try {
    // 1. Gjenerimi i Vector Embedding (Edge/Fast Embedder)
    const embeddingResponse = await fetch("http://127.0.0.1:20129/v1/embeddings", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: "antigravity/text-embedding-004",
        input: query,
      }),
      // Cache-ojmë embeddings e query-ve identike
      next: { revalidate: 3600 },
    });

    const embeddingData = await embeddingResponse.json();
    const vectorArray = embeddingData?.data?.[0]?.embedding;
    const vectorString = vectorArray ? `[${vectorArray.join(",")}]` : null;

    // 2. Ekzekutimi i RRF SQL Query në PostgreSQL
    const sqlQuery = `
      WITH lexical_search AS (
          SELECT id, ROW_NUMBER() OVER (
              ORDER BY ts_rank_cd(search_vector, to_tsquery('simple', $1)) DESC
          ) AS rank
          FROM public.products
          WHERE is_active = true AND search_vector @@ to_tsquery('simple', $1)
          LIMIT 25
      ),
      vector_search AS (
          SELECT id, ROW_NUMBER() OVER (
              ORDER BY embedding <=> $2::vector
          ) AS rank
          FROM public.products
          WHERE is_active = true AND embedding IS NOT NULL
          LIMIT 25
      ),
      rrf_scores AS (
          SELECT 
              COALESCE(l.id, v.id) AS product_id,
              COALESCE(1.0 / (60 + l.rank), 0.0) +
              COALESCE(1.0 / (60 + v.rank), 0.0) AS score
          FROM lexical_search l
          FULL OUTER JOIN vector_search v ON l.id = v.id
      )
      SELECT 
          p.id, p.sku, p.title, p.description, p.category, 
          p.price, p.stock_quantity, r.score AS match_relevance
      FROM rrf_scores r
      JOIN public.products p ON p.id = r.product_id
      ORDER BY r.score DESC
      LIMIT $3;
    `;

    const result = await pool.query(sqlQuery, [
      tsFormatted,
      vectorString || "[]",
      limit,
    ]);

    const latencyMs = Math.round(performance.now() - startTime);

    return {
      success: true,
      data: result.rows,
      latencyMs,
    };
  } catch (error) {
    console.error("[Hybrid Search Error]:", error);
    return { success: false, data: [], latencyMs: 0 };
  }
}

---

5. Krahasimi i Performancës: SQL Tradicional vs. Kërkimi Hibrid

Në testimet inxhinierike të kryera në katalogje me mbi 150,000 artikuj (SKU), diferenca midis qasjes klasike dhe Kërkimit Hibrid RRF është e jashtëzakonshme:

---

6. Përfundimi dhe Hapat e Zbatimit

Kalimi në Kërkim Hibrid me pgvector dhe Next.js 16 heq nevojën për sisteme të ndërlikuara të jashtme, ul kostot operative të serverëve në zero dollarë shtesë përtej bazës ekzistuese të të dhënave, dhe rrit menjëherë konvertimin e shitjeve online.

Për bizneset dhe platformat e-commerce në Kosovë që synojnë performancë të lartë:

1. Strukturoni të dhënat: Shtoni vektorët e indeksuar në çdo ndryshim apo shtim produkti përmes background queue workers.
2. Normalizoni shqipen: Përdorni filtra unaccent dhe trajtim të personalizuar të shkronjave ë dhe ç.
3. Optimizoni indekset: Zgjidhni indeksin HNSW mbi IVFFlat për shpejtësi konstante nën ngarkesë të lartë transaksionale.

---

Ekipi inxhinierik i Postieri XYZ L.L.C. ndërton dhe mirëmban sisteme enterprise të tregtisë elektronike, integrime ERP dhe arkitektura të avancuara të inteligjencës artificiale. Për konsulencë teknike apo implementim në platformën tuaj, kontaktoni zyrën tonë në Gjakovë ose na shkruani në postieri.xyz/contact.