lakebase_vector

L’extension lakebase_vector ajoute approximativement la recherche vectorielle du voisin le plus proche (ANN) à Lakebase via le type d’index lakebase_ann . Il s’agit d’un compagnon de dépôt pour pgvector : les mêmes types de vecteurs, opérateurs de distance et syntaxe de requête fonctionnent sans modification.

Installer

Tout d’abord, activez La recherche Lakebase dans les paramètres de votre projet. Installez ensuite l’extension :

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

Le CASCADE mot clé s’installe pgvector automatiquement en tant que dépendance.

Mise à niveau de l’extension et des index

Une nouvelle version de Lakebase Search peut ajouter des fonctionnalités, des correctifs et des améliorations de performance. Bien que Lakebase Search soit publié dans le cadre des mises à jour Lakebase, il ne met pas tout à jour automatiquement. Dans lakebase_vector, deux choses sont mises à jour séparément et portent des numéros de version qui ne sont pas liés entre eux :

  • La version extension est la version des objets SQL qui CREATE EXTENSION lakebase_vector crée, y compris ses types de données, fonctions, opérateurs et la méthode d’accès à l’index lakebase_ann . Cette version est rapportée par SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'. ALTER EXTENSION lakebase_vector UPDATE Mise à jour de cette version.
  • Le format de stockage d’index est la disposition sur disque d’un lakebase_ann index. L’extension pourrait introduire des formats de stockage indexés mis à jour dans une mise à jour, débloquant davantage de fonctionnalités et offrant de meilleures performances. Tous les nouveaux index créés utilisent automatiquement le dernier format de stockage, tandis que les index existants peuvent être mis à niveau vers le nouveau format après REINDEX INDEX CONCURRENTLY qu’un nouveau format de stockage soit disponible.

La mise à niveau n’est pas urgente. L’extension est compatible avec les objets SQL et les formats de stockage indexés des versions précédentes, mais rester à jour vous permet de suivre le chemin supporté et le mieux performant et d’éviter une migration plus importante ultérieure, donc mettez à jour quand cela vous convient plutôt que de reporter indéfiniment.

Note

La dernière version d’extension disponible est rapportée par SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.

La dernière version du format de stockage est _2. La requête suivante trouve tous les index utilisant un format de stockage plus ancien. Vous pouvez ensuite les reconstruire dans le dernier format de stockage avec REINDEX INDEX ou REINDEX INDEX CONCURRENTLY:

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 permet de continuer les lectures et écritures, mais cela prend plus de temps.

Démarrage rapide

-- 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;

Peupler à partir de tables synchronisées

Si vous chargez des embeddings depuis Unity Catalog au lieu de les insérer directement, les tables synchronisées peuvent mapper une colonne d’embedding lakehouse directement sur une colonne Postgres vector pendant la synchronisation, au lieu de la correspondance par défaut JSONB . Voir Mappage personnalisé de types pour la recherche Lakebase.

Configurer l’index

Définissez build_mode à la création de l’index pour contrôler la précision/la vitesse de compromis :

  • standard (par défaut) : équilibre le rappel et le temps de construction de l’indice. Utilisez la plupart des charges de travail.
  • quality: améliore le rappel mais prend plus de temps à se construire.
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

Le fast mode de compilation reste pris en charge pour la rétrocompatibilité.

Par défaut, lakebase_ann il choisit les listes en fonction des statistiques du tableau et de la configuration de l’index. Définissez lists pour contrôler explicitement la disposition de la partition :

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

Temps de compilation de l’indice

Plus grand shared_buffers peut réduire significativement le temps de construction de l’index. Lakebase permet cette optimisation uniquement sur des calculs de taille fixe plus grands. Vérifiez la valeur actuelle avant d’optimiser une construction d’indice :

SHOW shared_buffers;

Si shared_buffers est de 1 Go ou moins, envisagez de redimensionner temporairement à un calcul de taille fixe plus grande avant de commencer la compilation de l’index.

Vous pouvez aussi accélérer la création d’indices en augmentant le nombre de travailleurs parallèles.

Le max_parallel_maintenance_workers paramètre de configuration fixe le nombre maximal de travailleurs parallèles pouvant être démarrés par une seule commande utilitaire telle que CREATE INDEX.

Le max_parallel_workers paramètre de configuration fixe le nombre maximal de travailleurs que le calcul peut supporter pour des opérations parallèles. Les valeurs supérieures max_parallel_maintenance_workers à cette limite n’ont aucun effet.

Le max_worker_processes paramètre de configuration fixe le nombre maximal de processus en arrière-plan que le calcul peut supporter. Lakebase gère ce paramètre en fonction de la taille de calcul. Les valeurs supérieures max_parallel_workers à cette limite n’ont aucun effet.

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

Générer des index simultanément

CREATE INDEX CONCURRENTLY et REINDEX INDEX CONCURRENTLY permettent aux lectures et écritures de continuer pendant qu’un index est construit ou reconstruit :

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

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

Ajuster la précision de la recherche

Avant le réglage, appelez lakebase_ann_index_info(index_name) pour obtenir les valeurs et lists les valeurs de default_probesdefault_epsilonl’index.

Utilisez-le lakebase_ann.probes au moment de la requête pour contrôler le nombre de partitions FIV recherchées. Les valeurs plus élevées améliorent le rappel au coût de la vitesse des requêtes. La valeur par défaut est 'auto'. Testez différentes valeurs pour atteindre votre objectif de rappel.

La forme de probes doit correspondre à la forme de lists. Appelez lakebase_ann_index_info pour trouver votre lists tableau, puis définissez une valeur pour un index à un niveau ou deux valeurs séparées par virgules pour un indice à deux niveaux :

lists à partir des informations d’index probes pour définir
[] (vide) ''
[222] '22'
[3333, 33333] '33, 333'

Note

Sur un petit jeu de données, lakebase_ann utilise une recherche exacte (plate) au lieu du partitionnement FIV, et lakebase_ann_index_info retourne vide lists et default_probes. Dans ce cas, laisse probes défini à ''. Lorsque lists n’est pas vide, une probes valeur dont la forme ne correspond lists pas provoque une erreur.

-- 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 contrôle combien de candidats sont reclassés en utilisant des distances en pleine précision. Des valeurs plus élevées font reclasser plus de candidats et prennent plus de temps. La valeur par défaut fonctionne 'auto' bien pour la plupart des charges de travail. Lors d’une recherche plate sur un petit jeu de données, epsilon on contrôle toujours le reclassement en pleine précision.

Préfiltre

Par défaut, Postgres applique des conditions de filtre non vectorielles après que l’indice ANN a rendu les lignes candidates. Permettre lakebase_ann.prefilter d’évaluer ces conditions avant un reclassement de distance en pleine précision :

SET lakebase_ann.prefilter TO on;

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

Le préfiltrage fonctionne mieux lorsque le filtre est peu coûteux à évaluer et enlève la plupart des rangées. Laissez-le désactivé pour les filtres qui correspondent à de nombreuses lignes ou qui nécessitent des calculs coûteux, car évaluer le filtre à l’intérieur de l’index peut ajouter de la surcharge.

Préchauffe un indice

À utiliser lakebase_ann_prewarm après le début du calcul pour charger en mémoire les parties fréquemment consultées d’un index. L’argument scope accepte les valeurs suivantes :

  • search (par défaut) : préchauffe la portion chaude complète utilisée pour la recherche.
  • routing: Préchauffe uniquement les structures de routage. Cette option est plus rapide et offre un meilleur compromis coût-rendement pour les grands indices.
-- 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');

Classes d’opérateurs

Mesure de distance Classe d’opérateur Opérateur de requête
L2 (euclidienne) vector_l2_ops <->
Produit interne négatif vector_ip_ops <#>
Similarité cosinus vector_cosine_ops <=>

Choisissez la classe d’opérateur qui correspond à la façon dont vos incorporations ont été entraînées et utilisez la même métrique pour l’index et la requête :

  • vector_cosine_ops (<=>) est la similarité cosinus. Utilisez-la pour la plupart des incorporations de texte. C’est le choix le plus courant.
  • vector_l2_ops (<->) est la distance euclide (L2). Utilisez-la lorsque la distance spatiale absolue importe et que les vecteurs ne sont pas normalisés.
  • vector_ip_ops (<#>) est un produit intérieur négatif. Utilisez-le lorsque les vecteurs sont prédéfinisés en longueur unitaire. Pour les vecteurs unitaires, le produit interne est égal à la similarité cosinus et est généralement plus rapide.

Informations de référence sur les options d’index

Option Type Default Description
build_mode ficelle 'standard' Contrôle le choix entre précision et vitesse. À utiliser 'quality' pour un meilleur rappel au prix d’une version indexée plus longue. 'fast' reste supporté pour la rétrocompatibilité.
lists ficelle 'auto' Définit la disposition de la partition FIV. Avec 'auto', l’extension choisit une valeur basée sur les statistiques du tableau et la configuration de l’indice. On définit un entier unique comme '1000' pour un indice de niveau un, ou deux entiers croissants séparés par virgules, comme '100, 1000' pour un indice à deux niveaux.

Informations de référence sur GUC

Paramètre Type Default Description
lakebase_ann.probes ficelle 'auto' Nombre de partitions FIV à scanner à chaque niveau. Les valeurs plus élevées améliorent le rappel au coût de la vitesse des requêtes. La forme doit correspondre à l’array lists de .lakebase_ann_index_info
lakebase_ann.epsilon ficelle 'auto' Contrôle combien de candidats sont reclassés en utilisant des distances en pleine précision. Des valeurs plus élevées font reclasser plus de candidats et prennent plus de temps.
lakebase_ann.prefilter enum off Évalue les filtres non vectoriels avant un reclassement de distance en pleine précision. Les valeurs valides sont on et off. C’est idéal pour les filtres bon marché qui suppriment la plupart des lignes candidates.

Fonctions utilitaires

Fonction Returns Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search') void Charge les données d’index fréquemment consultées en mémoire. Les valeurs valides scope sont search et routing.
lakebase_ann_index_info(regclass) text Retourne les métadonnées de l’index sous forme de texte JSON, incluant version, lists, default_probes, et default_epsilon.

Étapes suivantes

  • Last updated on