pgvector: tipul vector și operatorii de distanță în PostgreSQL

CREATE EXTENSION vector;
coloana vector(dimensiuni)
vector1 <-> vector2   -- distanța euclidiană (L2)
vector1 <=> vector2   -- distanța cosinus
vector1 <#> vector2   -- produsul scalar, cu semn minus
vector1 <+> vector2   -- distanța L1 (Manhattan)

Ce face pgvector: tipul vector și operatorii de distanță

Un model de embedding transformă un text (sau o imagine) într-un vector de numere, de exemplu 768 sau 1536 de valori. Texte cu sens apropiat au vectori apropiați. Cu pgvector salvezi acești vectori într-o coloană vector(n) și cauți rândurile cele mai apropiate de vectorul unei întrebări.

Operatorii măsoară distanța: <-> distanța euclidiană (L2), <=> distanța cosinus (1 − similaritatea cosinus, între 0 și 2), <#> produsul scalar cu semn minus (ca valorile mai mici să fie „mai aproape”) și <+> distanța L1. Căutarea tipică este ORDER BY embedding <=> :intrebare LIMIT 5.

Folosește aceeași măsură de distanță pentru care a fost antrenat modelul (pentru majoritatea modelelor de text: cosinus). Fără index, căutarea compară vectorul cu fiecare rând; pe tabele mari adaugă un index HNSW sau IVFFlat.

Parametri

Parametru	Descriere
vector(n)	Vector cu n dimensiuni (max. 16.000; indexabil până la 2.000). halfvec(n) folosește jumătate din spațiu.
<->	Distanța euclidiană (L2).
<=>	Distanța cosinus.
<#>	Produsul scalar înmulțit cu -1.
vector_dims(v), l2_normalize(v)	Numărul de dimensiuni, respectiv vectorul normalizat la lungimea 1.

Ce returnează

Operatorii de distanță returnează double precision.

Exemple

Exemplele de pe această pagină pornesc de la datele de mai jos. Rulează mai întâi acest cod, apoi exemplul.

CREATE EXTENSION vector;

CREATE TABLE articole (
    id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    titlu      text NOT NULL,
    embedding  vector(3)
);

INSERT INTO articole (titlu, embedding) VALUES
    ('Rețete cu dovleac', '[3,1,0]'),
    ('Ciorbă de legume', '[2,2,0]'),
    ('Laptop pentru programare', '[0,1,3]'),
    ('Tastatură mecanică', '[0,0,2]');

Exemplul 1: Cele mai apropiate articole (distanța L2)

Vectorii au doar 3 dimensiuni ca să poți urmări calculul; un model real produce sute de dimensiuni.

SELECT titlu, embedding <-> '[3,1,1]' AS distanta
FROM articole
ORDER BY embedding <-> '[3,1,1]'
LIMIT 3;

Rezultat în psql

       titlu        |      distanta      
--------------------+--------------------
 Rețete cu dovleac  |                  1
 Ciorbă de legume   | 1.7320508075688772
 Tastatură mecanică |    3.3166247903554
(3 rows)

Exemplul 2: Distanța cosinus, folosită pentru text

SELECT titlu, round((embedding <=> '[3,1,1]')::numeric, 4) AS distanta_cosinus
FROM articole
ORDER BY embedding <=> '[3,1,1]'
LIMIT 2;

Rezultat în psql

       titlu       | distanta_cosinus 
-------------------+------------------
 Rețete cu dovleac |           0.0465
 Ciorbă de legume  |           0.1472
(2 rows)

Exemplul 3: Vector cu alt număr de dimensiuni

INSERT INTO articole (titlu, embedding) VALUES ('Test', '[1,2]');

Rezultat în psql

ERROR:  expected 3 dimensions, not 2

Greșeli frecvente

• Amesteci embedding-uri generate cu modele diferite în aceeași coloană. Distanțele dintre ele nu au sens; folosește un singur model și aceeași versiune.
• Ordonezi după un operator și indexul este creat pentru altul (de exemplu ORDER BY embedding <-> ... cu un index vector_cosine_ops): indexul nu este folosit.
• Calculezi distanța în ORDER BY cu o expresie diferită de cea din SELECT sau cu un vector convertit altfel: păstrează exact forma coloana <=> valoare, ca planificatorul să poată folosi indexul.

Comenzi înrudite

• pgvector: indecși HNSW și IVFFlat: Indecși pentru căutarea aproximativă a celor mai apropiați vectori: HNSW (mai precis, construcție mai lentă) și IVFFlat (construcție rapidă).
• CREATE EXTENSION: Activează o extensie (pg_trgm, pgcrypto, vector, postgis) în baza de date curentă: tipuri, funcții și operatori noi.