lakebase_vector

Die lakebase_vector Erweiterung fügt über den lakebase_ann Indextyp eine ungefähre Ann-Vektorsuche zu Lakebase hinzu. Es ist ein Drop-In-Begleiter für pgvector: Die gleichen Vektortypen, Entfernungsoperatoren und Abfragesyntax funktionieren ohne Änderung.

Install

Aktivieren Sie zunächst die Lakebase-Suche in Ihren Projekteinstellungen. Installieren Sie dann die Erweiterung:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

Das CASCADE Schlüsselwort wird automatisch als Abhängigkeit installiert pgvector .

Upgrade der Erweiterung und der Indizes

Eine neue Lakebase Search-Version kann Funktionen, Korrekturen und Leistungsverbesserungen hinzufügen. Obwohl Lakebase Search im Rahmen von Lakebase-Updates veröffentlicht wird, wird nicht alles automatisch aktualisiert. In lakebase_vector, werden zwei Dinge separat aufgerüstet und tragen Versionsnummern, die nicht zueinander zusammenhängen:

• Die Erweiterungsversion ist die Version der SQL-Objekte, die CREATE EXTENSION lakebase_vector erstellt werden, einschließlich ihrer Datentypen, Funktionen, Operatoren und der lakebase_ann Indexzugriffsmethode. Diese Version wird von SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'berichtet. ALTER EXTENSION lakebase_vector UPDATE Aktualisiert diese Version.
• Das Index-Speicherformat ist das Festplattenlayout eines lakebase_ann Indexes. Die Erweiterung könnte in einem Update aktualisierte Indexspeicherformate einführen, mehr Funktionen freischalten und eine bessere Leistung liefern. Alle neu erstellten Indizes verwenden automatisch das neueste Speicherformat, während bestehende Indizes auf das neue Format REINDEX INDEX CONCURRENTLY aufgerüstet werden können, nachdem ein neueres Speicherformat verfügbar ist.

Ein Upgrade ist nicht dringend. Die Erweiterung ist kompatibel mit SQL-Objekten und Indexspeicherformaten älterer Versionen, aber aktuell zu bleiben, hält Sie auf dem unterstützten, leistungsfähigsten Weg und vermeidet eine größere Migration später, daher sollten Sie bei Bequemlichkeit upgraden und nicht unbegrenzt verschieben.

Note

Die aktuellste verfügbare Erweiterungsversion wird von SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'berichtet.

Die neueste Version des Speicherformats ist _2. Die folgende Abfrage findet alle Indexe, die ein älteres Speicherformat verwenden. Sie können sie dann in das neueste Speicherformat REINDEX INDEX mit oder REINDEX INDEX CONCURRENTLYneu aufbauen:

SELECT oid::regclass AS index, lakebase_ann_index_info(oid::regclass)::json ->> 'version' AS storage_format_version
FROM pg_class
WHERE relam = (SELECT oid FROM pg_am WHERE amname = 'lakebase_ann') AND relkind = 'i';

Note

REINDEX INDEX CONCURRENTLY Lesen und Schreiben erlaubt es, weiterzulesen, aber es dauert länger.

Schnellstart

-- Create a table with a vector column
CREATE TABLE items (id BIGSERIAL PRIMARY KEY, embedding VECTOR(3));

-- Insert sample data
INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

-- Create a lakebase_ann index
CREATE INDEX items_embedding_idx ON items
  USING lakebase_ann (embedding vector_l2_ops);

-- Query using standard pgvector distance operators
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Aus synchronisierten Tabellen befüllen

Wenn du Embeddings aus Unity Catalog lädst, anstatt sie direkt einzufügen, können synchronisierte Tabellen eine Lakehouse-Embedding-Spalte während der Synchronisation direkt auf eine Postgres-Spalte vector abbilden, anstatt wie standardmäßig JSONB zuzuordnen. Siehe Benutzerdefinierte Typzuordnung für Lakebase Search.

Konfigurieren des Index

Legen Sie build_mode bei der Indexerstellung fest, um den Genauigkeits-/Geschwindigkeitskonflikt zu steuern:

• standard (Standard): Gleichgewichte für Rückruf und Index-Bauzeit. Wird für die meisten Workloads verwendet.
• quality: verbessert den Rückruf, dauert aber länger zum Aufbau.

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

Der Build-Modus fast wird weiterhin für Abwärtskompatibilität unterstützt.

Standardmäßig wählt er lakebase_ann Listen basierend auf den Statistiken der Tabelle und der Konfiguration des Indexes. So eingestellt lists , dass das Partitionslayout explizit gesteuert wird:

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');

Index-Aufbauzeit

Größer kann die Index-Aufbauzeit shared_buffers deutlich reduzieren. Lakebase ermöglicht diese Optimierung nur bei größeren Berechnungen mit fester Größe. Überprüfen Sie den aktuellen Wert, bevor Sie einen Indexaufbau optimieren:

SHOW shared_buffers;

Wenn shared_buffers 1 GB oder weniger ist, sollten Sie vorübergehend auf eine größere, feste Berechnung umstellen, bevor Sie mit dem Indexaufbau beginnen.

Du kannst auch die Erstellung von Indexen beschleunigen, indem du die Anzahl der parallelen Arbeiter erhöhst.

Der Konfigurationsparameter max_parallel_maintenance_workers legt die maximale Anzahl paralleler Arbeiter fest, die mit einem einzelnen Utility-Befehl wie CREATE INDEXgestartet werden können.

Der Konfigurationsparameter max_parallel_workers legt die maximale Anzahl von Arbeitern fest, die der Compute für parallele Operationen unterstützen kann. Werte über max_parallel_maintenance_workers diesem Grenzwert haben keine Auswirkung.

Der Konfigurationsparameter max_worker_processes legt die maximale Anzahl der Hintergrundprozesse fest, die der Computer unterstützen kann. Lakebase verwaltet diese Einstellung basierend auf der Rechengröße. Werte über max_parallel_workers diesem Grenzwert haben keine Auswirkung.

SHOW max_worker_processes;
-- Set both values to the desired parallelism minus one.
SET max_parallel_workers = 15;
SET max_parallel_maintenance_workers = 15;

Erstellen von Indizes gleichzeitig

CREATE INDEX CONCURRENTLY und REINDEX INDEX CONCURRENTLY erlauben es, dass Lese- und Schreibvorgänge fortgesetzt werden, während ein Index erstellt oder neu aufgebaut wird:

CREATE INDEX CONCURRENTLY items_embedding_idx_concurrent ON items
  USING lakebase_ann (embedding vector_l2_ops);

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

Optimieren der Suchgenauigkeit

Rufen Sie lakebase_ann_index_info(index_name) vor der Optimierung auf, um die Werte und lists Werte des Indexes default_probesdefault_epsilonabzurufen.

Verwenden Sie lakebase_ann.probes zur Abfragezeit, um zu steuern, wie viele IVF-Partitionen durchsucht werden. Höhere Werte verbessern den Rückruf zu den Kosten der Abfragegeschwindigkeit. Der Standardwert lautet 'auto'. Teste verschiedene Werte, um dein Rückrufziel zu erreichen.

Die Form von probes muss mit der Form von listsübereinstimmen. Ruf auf, lakebase_ann_index_info um dein lists Array zu finden, und setze dann einen Wert für einen einstufigen Index oder zwei kommagetrennte Werte für einen zweistufigen Index:

lists aus Indexinformationen	probes so legen Sie fest
[] (leer)	''
[222]	'22'
[3333, 33333]	'33, 333'

Note

Bei einem kleinen Datensatz lakebase_ann verwendet exakte (flache) Suche statt IVF-Partitionierung und lakebase_ann_index_info liefert leer lists und default_probes. In diesem Fall lassen probes Sie auf ''. Wenn lists nicht leer ist, verursacht ein probes Wert, dessen Form nicht übereinstimmt lists , einen Fehler.

-- Check your index's lists array first
SELECT lakebase_ann_index_info('items_embedding_idx');

-- Then set probes to match the shape of lists.
-- One-level index (single-value lists): set one value.
SET lakebase_ann.probes TO '10';

-- Two-level index: set two ascending comma-separated values, for example '10, 20'.
-- Flat index (empty lists): leave probes set to ''.

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

lakebase_ann.epsilon kontrolliert, wie viele Kandidaten mittels Vollpräzisionsdistanzen neu eingestuft werden. Höhere Werte rangieren mehr Kandidaten neu und brauchen länger. Der Standardwert eignet 'auto' sich gut für die meisten Workloads. Während der Flat Search auf einem kleinen Datensatz kontrolliert weiterhin epsilon eine vollständige Präzisionsreranking.

Vorfilter

Standardmäßig wendet Postgres Nicht-Vektorfilterbedingungen an, nachdem der ANN-Index Kandidatenzeilen zurückgegeben hat. Ermöglichen Sie lakebase_ann.prefilter es, diese Bedingungen vor einer Vollpräzisions-Entfernungsreranking zu bewerten:

SET lakebase_ann.prefilter TO on;

SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;

Vorfiltern funktioniert am besten, wenn der Filter günstig zu bewerten ist und die meisten Zeilen entfernt. Lassen Sie es bei Filtern weg, die viele Zeilen übereinstimmen oder teure Berechnungen erfordern, da die Berechnung des Filters im Index zusätzlichen Overhead verursachen kann.

Einen Vorwärmindex

Nachdem lakebase_ann_prewarm eine Berechnung begonnen hat, die häufig abgerufenen Teile eines Index in den Speicher zu laden. Das Argument scope akzeptiert folgende Werte:

• search (Standard): Vorwärmt den vollständigen heißen Teil, der für die Suche verwendet wird.
• routing: Vorwarmt nur die Routing-Strukturen. Diese Option ist schneller und bietet einen besseren Kosten-Performance-Kompromiss für große Indizes.

-- Prewarm the full search scope
SELECT lakebase_ann_prewarm('items_embedding_idx');

-- Prewarm only routing structures
SELECT lakebase_ann_prewarm('items_embedding_idx', scope => 'routing');

Operatorklassen

Abstandsmetrik	Operatorklasse	Abfrageoperator
L2 (Euklidan)	vector_l2_ops	<->
Negatives inneres Produkt	vector_ip_ops	<#>
Kosinus-Ähnlichkeit	vector_cosine_ops	<=>

Wählen Sie die Operatorklasse aus, die der Schulung Ihrer Einbettungen entspricht, und verwenden Sie die gleiche Metrik für den Index und die Abfrage:

• vector_cosine_ops (<=>) ist kosinusgleichheit. Verwenden Sie sie für die meisten Texteinbettungen. Dies ist die häufigste Wahl.
• vector_l2_ops (<->) der Abstand zwischen Euklidan (L2) ist. Verwenden Sie sie, wenn absolute räumliche Entfernung wichtig ist und Vektoren nicht normalisiert sind.
• vector_ip_ops (<#>) ist ein negatives inneres Produkt. Verwenden Sie sie, wenn Vektoren für die Länge der Einheit vornormiert sind. Bei Einheitsvektoren entspricht das innere Produkt der Kosinusgleichheit und ist in der Regel schneller.

Referenz zu Indexoptionen

Auswahl	Typ	Standard	Description
build_mode	string	'standard'	Kontrolliert den Kompromiss zwischen Genauigkeit und Geschwindigkeit. Nutze 'quality' es für besseren Rückruf auf Kosten eines längeren Index-Builds. 'fast' bleibt für Abwärtskompatibilität unterstützt.
lists	string	'auto'	Legt das IVF-Partitionslayout fest. Mit 'auto'wählt die Erweiterung einen Wert basierend auf den Statistiken der Tabelle und der Konfiguration des Indexes. Setze eine einzelne Ganzzahl, zum Beispiel '1000' für einen Ein-Ebenen-Index, oder zwei aufsteigende, komma-getrennte ganze Zahlen, wie zum Beispiel '100, 1000' für einen Zwei-Ebenen-Index.

GUC-Referenz

Parameter	Typ	Standard	Description
lakebase_ann.probes	string	'auto'	Anzahl der IVF-Partitionen, die auf jeder Ebene gescannt werden müssen. Höhere Werte verbessern den Rückruf zu den Kosten der Abfragegeschwindigkeit. Die Form muss mit dem Array von lakebase_ann_index_infoübereinstimmenlists.
lakebase_ann.epsilon	string	'auto'	Kontrolliert, wie viele Kandidaten mit Distanzen mit voller Genauigkeit neu eingestuft werden. Höhere Werte rangieren mehr Kandidaten neu und brauchen länger.
lakebase_ann.prefilter	enum	off	Bewertet Nicht-Vektorfilter vor der vollständigen Genauigkeits-Entfernungsreranking. Gültige Werte sind on und off. Am besten für günstige Filter, die die meisten Kandidatenzeilen entfernen.

Hilfsprogrammfunktionen

Function	Rückkehr	Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')	void	Lädt häufig abgerufene Indexdaten in den Speicher. Gültige Werte scope sind search und routing.
lakebase_ann_index_info(regclass)	text	Liefert Indexmetadaten als JSON-Text, einschließlich version, lists, , default_probesund default_epsilon.

Nächste Schritte

• lakebase_text
• Seebasissuche