lakebase_vector
L'extension lakebase_vector ajoute la recherche vectorielle de plus proche voisin approximatif (ANN) à Lakebase via le type d'index lakebase_ann. C'est un complément direct à 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. Puis installez l'extension :
CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
Le mot-clé CASCADE installe automatiquement pgvector en tant que dépendance.
Mettre à jour l'extension et les index
Une nouvelle version de Lakebase Search peut ajouter des fonctionnalités, des correctifs et des améliorations des performances. Bien que Lakebase Search soit publié dans le cadre des mises à jour de Lakebase, il ne met pas tout à niveau automatiquement. Dans lakebase_vector, deux éléments se mettent à niveau séparément et comportent des numéros de version qui n’ont aucun rapport entre eux :
- La version de l'extension est la version des objets SQL créés par
CREATE EXTENSION lakebase_vector, y compris ses types de données, ses fonctions, ses opérateurs et la méthode d'accès aux indexlakebase_ann. Cette version est signalée parSELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.ALTER EXTENSION lakebase_vector UPDATEmet à jour cette version. - Le format de stockage de l'index correspond au Layout sur disque d'un index
lakebase_ann. L'extension peut introduire de nouveaux formats de stockage d'index lors d'une mise à jour, ce qui permet de débloquer de nouvelles fonctionnalités et d'offrir de meilleures performances. Tous les index nouvellement créés utilisent automatiquement le dernier format de stockage, tandis que les index existants peuvent être mis à niveau vers le nouveau format à l'aide deREINDEX INDEX CONCURRENTLYune fois qu'un format de stockage plus récent est disponible.
La mise à niveau n’est pas urgente. L’extension est compatible avec les objets SQL et les formats de stockage d’index des anciennes versions, mais rester à jour vous permet de conserver un parcours pris en charge offrant les meilleures performances et d’éviter une migration plus importante ultérieurement ; par conséquent, effectuez la mise à niveau dès que cela vous arrange plutôt que de la reporter indéfiniment.
La dernière version d’extension disponible est signalée par SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.
La dernière version du format de stockage est _2. La query suivante trouve tous les index qui utilisent un ancien format de stockage. 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';
REINDEX INDEX CONCURRENTLY permet de continuer les lectures et les écritures, mais cela prend plus de temps.
Quick start
-- 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;
Remplir à partir de tables synchronisées
Si vous chargez des intégrations depuis Unity Catalog plutôt que de les insérer directement, les tables synchronisées peuvent mapper une colonne d’intégration lakehouse directement vers une colonne Postgres vector lors de la synchronisation, au lieu du mappage JSONB par default. Voir Mappage de type personnalisé pour Lakebase Search.
Configurez l'index
Définissez build_mode lors de la création de l'index pour contrôler le compromis précision/vitesse :
standard(default) : équilibre le rappel et le temps de construction de l’index. À utiliser pour la plupart des charges de travail.quality: améliore le rappel, mais prend beaucoup plus de temps à construire. Utilisez-le uniquement pour les tables contenant jusqu’à 50 millions de vecteurs.
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'standard');
Le mode de construction fast reste pris en charge pour des raisons de rétrocompatibilité.
By default, lakebase_ann choisit les listes en fonction des statistiques de la table et de la configuration de l’index. Définissez lists pour contrôler explicitement le layout de partition :
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');
Temps de construction de l’index
Des shared_buffers plus grands peuvent réduire considérablement le temps de construction de l’index. Lakebase active cette optimisation uniquement sur les computes de taille fixe plus grands. Vérifiez la valeur actuelle avant d’optimiser la construction d’un index :
SHOW shared_buffers;
Si shared_buffers est égal ou inférieur à 1 Go, envisagez de redimensionner temporairement vers un compute de taille fixe plus grande avant de lancer la création de l’index.
Vous pouvez également accélérer la création de l’index en augmentant le nombre de worker parallèles.
Le max_parallel_maintenance_workers parameter de configuration définit le nombre maximal de Worker parallèles qui peuvent être start par une seule infrastructure publique command telle que CREATE INDEX.
Le max_parallel_workers configuration parameter définit le nombre maximal de Worker que le compute peut prendre en charge pour les Opérations parallèles. Les valeurs de max_parallel_maintenance_workers supérieures à cette limite n’ont aucun effet.
Le paramètre de configuration max_worker_processes définit le nombre maximal de processus d’arrière-plan pris en charge par le compute. Lakebase gère ce paramètre en fonction de la taille du compute. Les valeurs de max_parallel_workers situées au-dessus de 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;
Créer des index simultanément
CREATE INDEX CONCURRENTLY et REINDEX INDEX CONCURRENTLY permettent de continuer à effectuer des lectures et des écritures pendant la création ou la reconstruction d'un index :
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 lists, default_probes et default_epsilon de l'index.
Utilisez lakebase_ann.probes au moment de la query pour contrôler le nombre de partitions de fichier inversé (IVF) recherchées. Des valeurs plus élevées améliorent le rappel au prix de la latence. La valeur default 'auto' offre un compromis équilibré entre les deux. Pour un contrôle plus fin, utilisez lakebase_ann_advise pour obtenir des valeurs de probes recommandées.
La forme de probes doit correspondre à la forme de lists. Appelez lakebase_ann_index_info pour trouver votre tableau lists, puis définissez une valeur pour un index à un niveau ou deux valeurs séparées par des virgules pour un index à deux niveaux :
|
|
|---|---|
|
|
|
|
|
|
Sur un petit dataset, lakebase_ann utilise une recherche exacte (plate) au lieu du partitionnement IVF, et lakebase_ann_index_info renvoie des lists et default_probes vides. Dans ce cas, laissez probes défini sur ''. Lorsque lists n’est pas vide, une valeur probes dont la forme ne correspond pas à lists 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 le nombre de candidats réorganisés à l’aide de distances en précision totale. Des valeurs plus élevées permettent de réorganiser davantage de candidats et prennent plus de temps. La valeur default de 'auto' convient à la plupart des charges de travail. Lors d’une recherche à plat sur un petit dataset, epsilon contrôle toujours la réorganisation en précision totale.
Obtenir les valeurs de sondes recommandées
lakebase_ann_advise, lakebase_ann_tune, lakebase_ann_latency et lakebase_ann_sample nécessitent lakebase_vector 1.1.2 et plus. Pour vérifier la version installée et mettre à jour l’extension, consultez Mettre à niveau l’extension et les index.
lakebase_ann_advise retourne probes valeurs candidates par ordre croissant de rappel, de 0,5 à 0,9 par incréments de 0,1 et de 0,91 à 0,99 par incréments de 0,01. Chaque ligne inclut le rappel estimé et la latence de la query mesurée après le préchauffage. Utilisez des queries réelles de votre charge de travail de recherche comme entrée. S’ils sont indisponibles, échantillonnez des vecteurs à partir de la table indexée avec lakebase_ann_sample. Les exemples suivants montrent les deux options :
-- Option 1: real queries in a separate table
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM queries
WHERE embedding IS NOT NULL
LIMIT 512
)
);
-- Option 2: sampled from the indexed table
-- NULL::items specifies items as the table to sample from.
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM lakebase_ann_sample(NULL::items, 512)
WHERE embedding IS NOT NULL
)
);
Colonne | Description |
|---|---|
| Une valeur |
| Rappel@10 estimé pour les query d’échantillon. |
| Latence moyenne, médiane et du 95e centile d’une seule query en millisecondes. |
Choisissez la ligne la plus rapide qui répond à votre objectif de rappel, puis appliquez sa valeur probes :
SET lakebase_ann.probes TO '10';
Le rappel et la latence sont estimés pour les 10 premières queries avec lakebase_ann.epsilon défini sur 1.9, ce qui peut différer de vos queries réelles. Avant d’utiliser une valeur probes en production, vérifiez son rappel et sa latence sur votre charge de travail si possible.
Si l'index possède des lists vides, lakebase_ann_advise ne renvoie aucune ligne car il n'y a rien à régler.
Sur les grands indexes, un appel lakebase_ann_advise peut prendre plus de 20 minutes. Plus de vecteurs de query ralentissent l’appel. start avec 512 vecteurs de query pour équilibrer la précision du rappel et le temps d’exécution.
lakebase_ann_advise appelle lakebase_ann_tune pour obtenir les valeurs probes recommandées, puis lakebase_ann_latency pour mesurer leur latence. Vous pouvez également utiliser lakebase_ann_tune ou lakebase_ann_latency seul. Voir Fonctions utilitaires.
lakebase_ann_advise et lakebase_ann_tune nécessitent SELECT au niveau de la table sur la table indexée et retournent une erreur si la sécurité au niveau des lignes (RLS) s'applique à votre rôle sur cette table. lakebase_ann_sample et lakebase_ann_latency appliquent des politiques RLS et ne lisent que les lignes que votre rôle peut voir.
Préfiltre
By default, Postgres applique des conditions de filtrage non vectorielles après que l'index ANN a renvoyé les lignes candidates. Activez lakebase_ann.prefilter pour évaluer ces conditions avant le reclassement par distance en précision totale :
SET lakebase_ann.prefilter TO on;
SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;
Le préfiltrage est plus efficace lorsque le filtre est peu coûteux à évaluer et supprime la plupart des lignes. Désactivez-le pour les filtres qui correspondent à un grand nombre de lignes ou qui nécessitent des calculs coûteux, car l’évaluation du filtre au sein de l’index peut ajouter une surcharge.
Préchauffer un index
Utilisez lakebase_ann_prewarm après le start d'un compute pour charger en mémoire les parties d'un index fréquemment consultées. L'argument scope accepte les valeurs suivantes :
search(default) : préchauffe l'intégralité de la portion chaude 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-performance pour les grands index.
-- 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
Métrique de distance | Classe d'opérateur | Opérateur de query |
|---|---|---|
L2 (euclidien) |
|
|
Produit interne négatif |
|
|
Similarité cosinus |
|
|
Choisissez la classe d’opérateur qui correspond à la façon dont vos intégrations ont été entraînées, et utilisez la même métrique pour l’index et la query :
vector_cosine_ops(<=>) est la similarité cosinus. Utilisez-le pour la plupart des intégrations de texte. C'est le choix le plus courant.vector_l2_ops(<->) est la distance euclidienne (L2). Utilisez-le lorsque la distance spatiale absolue importe et que les vecteurs ne sont pas normalisés.vector_ip_ops(<#>) est un produit interne négatif. Utilisez-le lorsque les vecteurs sont pré-normalisés à une longueur unitaire. Pour les vecteurs unitaires, le produit interne est égal à la similarité cosinus et est généralement plus rapide.
Référence des options d'index
Option | Type | Par défaut | Description |
|---|---|---|---|
| chaîne |
| Contrôle le compromis précision/vitesse. Utilisez |
| chaîne |
| Définit le layout de partition IVF. Avec |
Référence GUC
parameter | Type | Par défaut | Description |
|---|---|---|---|
| chaîne |
| Nombre de partitions IVF à scanner à chaque niveau. Des valeurs plus élevées améliorent le rappel au prix de la latence. La forme doit correspondre au tableau |
| chaîne |
| Contrôle le nombre de candidats réorganisés à l’aide de distances en précision totale. Des valeurs plus élevées permettent de réorganiser davantage de candidats et prennent plus de temps. |
| énumération |
| Évalue les filtres non vectoriels avant la réorganisation par distance en précision totale. Les valeurs valides sont |
Fonctions utilitaires
Fonction | Renvoie | Description |
|---|---|---|
| vide | Charge les données d'index fréquemment consultées en mémoire. Les valeurs |
| Texte | Renvoie les métadonnées d'index sous forme de texte JSON, y compris |
|
| Recommande des valeurs |
|
| Recommande |
|
| Mesure la latence moyenne, médiane et du 95e centile des query de l’index pour chaque valeur |
|
| Échantillonne jusqu’à |