PG-JEV

Vytvořeno: 28.9.2026 | Aktualizováno: 28.09.2026 17:45

PG-JEV je rozšíření pro PostgreSQL, které přidává funkce modelu Jev pro vyhodnocení, filtrování, řazení a klasifikaci řádků přirozeným jazykem. Dotaz nevyžaduje vektorový index, embeddingy ani vektorový sloupec; rozšíření předává celý řádek jako strukturovaný vstup do TypeSafe API.

Podmínka se předává funkci společně s řádkem. Například následující dotaz vybere z tabulky people osoby, jejichž jméno model vyhodnotí jako evropské:

SELECT * FROM people
WHERE jev(people, 'the name is European');

První vyhodnocení konkrétní kombinace tabulky a podmínky spustí read-ahead — rozšíření dopředu načítá řádky a odesílá je ve skupinách do API. U běžných tabulek čte řádky ve fyzickém pořadí pomocí TID rozsahů, u pohledů používá stránkování.

Výchozí dávka obsahuje 20 řádků na API požadavek. Parametr jev.concurrency má ve výchozím nastavení hodnotu 16 a určuje počet souběžných požadavků. Odpovědi ukládá cache v rámci backendové relace podle obsahu řádku.

jev(row, condition [, threshold]) vrací boolean hodnotu pro použití ve WHERE.
jev_prob(row, condition) vrací pravděpodobnost v rozsahu 0 až 1.
jev_score a jev_score_norm vrací skóre podle zadaných uspořádaných úrovní.
jev_choice vybírá nejpravděpodobnější možnost.
jev_confidence a jev_eval zpřístupňují confidence a úplnou odpověď modelu.
jev_stats(), jev_cache_clear() a jev_version() slouží ke kontrole statistik, vymazání cache a zjištění verze rozšíření.

Rozšíření vyžaduje PostgreSQL ve verzích 14 až 17, jazyk plpython3u, oprávnění superuživatele PostgreSQL a API klíč TypeSafe. Na hostovaných PostgreSQL službách bez superuživatele nebo plpython3u, například Supabase, Neon a RDS, jej nelze provozovat.

Na Debianu nebo Ubuntu je podle dokumentace projektu potřeba nejprve nainstalovat balíček postgresql-plpython3-NN, kde NN odpovídá hlavní verzi PostgreSQL.

pip install pgxnclient
pgxn install jev
psql -c "CREATE EXTENSION jev CASCADE"

git clone https://github.com/realZachi/pg-jev.git && cd pg-jev
make install
psql -c "CREATE EXTENSION jev CASCADE"

Projekt obsahuje také Docker image. API klíč se předává proměnnou prostředí TYPESAFE_API_KEY.

docker build -t pg-jev .
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pw \
  -e TYPESAFE_API_KEY=your-key pg-jev

Konfigurace používá PostgreSQL GUC parametry. Lze je proto nastavit pomocí SET, ALTER ROLE, ALTER DATABASE nebo v souboru postgresql.conf.

Důležité parametry zahrnují jev.api_key, jev.model, jev.concurrency, velikost dávky, URL API, timeout a keepalive. Výchozí model je jev-latest; lze použít i připnutou verzi, například jev-1.13.0.

Rozšíření obsahuje limity jev.max_rows_per_statement a jev.max_chars_per_statement. Po překročení omezí počet řádků nebo znaků odesílaných v rámci jednoho SQL příkazu. Tyto limity pomáhají chránit náklady na API.

Přesnou shodu, aritmetiku a práci s daty je vhodné nechat v SQL. Jev má řešit až sémantickou část dotazu. Levné SQL podmínky mají být před jev(), aby se řádky vyřazené databází neposílaly do API.

SELECT * FROM people
WHERE country = 'CZ'
  AND jev(people, 'the person works in a technical role');

Pokud tabulka obsahuje mnoho sloupců, je vhodné vytvořit pohled jen s poli potřebnými pro rozhodnutí. Zmenší se tím vstup odesílaný modelu.

LIMIT může zastavit read-ahead dříve, než rozšíření vyhodnotí celou tabulku. Nejde ale o indexové vyhledávání: rozšíření zpracovává řádky, které PostgreSQL executor vyžádá pro vyhodnocení dotazu.

Obsah vyhodnocovaných řádků odchází do API třetí strany. Před nasazením je proto potřeba vyhodnotit, zda data smějí opustit databázový server.

Cache není sdílená mezi backendovými relacemi. Anonymní typ record, který může vzniknout například z některých poddotazů nebo CTE, neumí read-ahead dávkovat a rozšíření jej vyhodnocuje po jednom řádku.

plpython3u je nedůvěryhodný jazyk PostgreSQL. Rozšíření může vytvořit jen superuživatel a jeho funkce běží s oprávněními operačního systému procesu databázového serveru. Instalace proto vyžaduje stejnou obezřetnost jako jiný kód běžící přímo u PostgreSQL.

Regresní testy projektu používají deterministickou mock API, takže nemají volat živé API.