Stocker et rechercher des embeddings Ollama dans PostgreSQL avec pgvector

Le README de pgvector le décrit comme une recherche par similarité de vecteurs open source pour Postgres. Il prend en charge la recherche exacte et approximative des plus proches voisins ; les vecteurs en simple précision, en demi-précision, binaires et creux ; ainsi que la distance L2, le produit scalaire, la distance cosinus, la distance L1, la distance de Hamming et la distance de Jaccard. Comme les vecteurs sont de simples colonnes PostgreSQL, ils bénéficient aussi de la conformité ACID, de la restauration à un instant donné et des JOIN.

Pour une recherche dans vos documents, vous stockez une ligne par fragment avec son texte et son vecteur, vous calculez l'embedding de la question avec le même modèle, puis vous triez les lignes selon leur distance au vecteur de la question.

pgvector prend en charge PostgreSQL 13 et les versions suivantes. Le README énumère plusieurs façons de l'installer, dont celles-ci :

Une colonne de type vector(n) contient des vecteurs d'exactement n dimensions, et n doit être la longueur des vecteurs de votre modèle d'embeddings. Un vecteur d'une autre longueur est rejeté : quand nous avons inséré un vecteur de 2 dimensions dans une colonne vector(3), PostgreSQL a renvoyé "expected 3 dimensions, not 2". all-minilm renvoie 384 dimensions, donc sa colonne est vector(384).

Le README indique que chaque vecteur occupe 4 × dimensions + 8 octets, chaque élément étant un nombre à virgule flottante en simple précision, et autorise jusqu'à 16,000 dimensions dans une colonne. Un index prend en charge moins de dimensions, comme indiqué plus bas. Le type halfvec stocke des valeurs en demi-précision sur 2 × dimensions + 8 octets.

pgvector lit un vecteur sous forme de texte entre crochets, comme '[1,2,3]', et le README précise que tous les éléments doivent être finis (ni NaN, ni Infinity, ni -Infinity). Chaque tableau du champ embeddings d'une réponse de /api/embed a déjà cette forme, et la réponse conserve l'ordre de l'entrée, donc le premier texte correspond au premier vecteur.

Le README présente INSERT pour quelques lignes, INSERT … ON CONFLICT pour les upserts et COPY pour le chargement en masse. Le convertisseur ci-dessous associe vos textes à la réponse et écrit des instructions INSERT avec les guillemets échappés. Nous avons exécuté sa sortie avec des textes contenant des guillemets, des barres obliques inverses, des sauts de ligne et des emoji, et ils sont ressortis inchangés.

La documentation d'Ollama recommande la similarité cosinus pour la plupart des cas de recherche sémantique et indique que /api/embed renvoie des vecteurs de longueur 1. Pour de tels vecteurs, la distance cosinus, la distance L2 et le produit scalaire classent les lignes dans le même ordre, car le carré de la distance L2 vaut 2 moins 2 fois la similarité cosinus. Dans notre test avec all-minilm, les trois premières lignes étaient les mêmes avec les trois, et la distance L2 de 0.931 correspondait à la similarité cosinus de 0.566.

Chaque distance a son propre opérateur. Une recherche trie selon l'opérateur et prend les premières lignes avec LIMIT, et un index est créé pour une classe d'opérateurs.

Sans index, pgvector effectue une recherche exacte des plus proches voisins, qui offre selon le README un rappel (recall) parfait. Un index approximatif sacrifie un peu de rappel pour gagner en vitesse, et le README prévient que les requêtes peuvent renvoyer des résultats différents après l'ajout d'un index.

Un index n'est utilisé que si la requête contient ORDER BY et LIMIT et si l'ORDER BY est l'opérateur de distance lui-même, en ordre croissant. ORDER BY embedding <=> $1 LIMIT 5 peut utiliser l'index ; ORDER BY 1 - (embedding <=> $1) DESC ne le peut pas. Le README note aussi qu'un parcours de la table peut être plus rapide quand la table est petite.

Avec HNSW, les résultats sont limités par hnsw.ef_search, qui vaut 40 par défaut. Sur une table de test de 200 lignes avec un index HNSW, LIMIT 100 a renvoyé 40 lignes ; après SET hnsw.ef_search = 100, il en a renvoyé 100. Réglez hnsw.ef_search à au moins le nombre de lignes dont vous avez besoin. SET LOCAL dans une transaction ne le modifie que pour une seule requête.

Le filtrage réduit aussi les résultats. Avec les index approximatifs, le README indique que la condition WHERE est appliquée après le parcours de l'index : si une condition correspond à 10% des lignes, HNSW avec la valeur par défaut de hnsw.ef_search, 40, ne renvoie en moyenne que 4 lignes. Depuis la version 0.8.0, les parcours itératifs de l'index (SET hnsw.iterative_scan = strict_order, ou relaxed_order) parcourent une plus grande partie de l'index jusqu'à trouver assez de lignes, dans la limite de hnsw.max_scan_tuples (20,000 par défaut).

Quand la recherche renvoie les lignes les plus proches, le modèle en a besoin dans son prompt. /api/chat d'Ollama prend une liste de messages, chacun avec un rôle (system, user, assistant ou tool) et son content. Une organisation simple consiste en un message system contenant les règles et un message user qui énumère les lignes, chacune avec un numéro, comme [1] et [2], suivies de la question. Avec des numéros, la réponse peut indiquer quelles lignes elle a utilisées, et vous pouvez associer chaque numéro à sa ligne.

Pour obtenir les citations sous une forme fixe, donnez au champ format un JSON Schema avec la réponse et une liste de citations, chacune avec le numéro de la source et un court extrait cité. La page sur les sorties structurées d'Ollama recommande d'écrire aussi le schéma dans le prompt, et de baisser la température (temperature), par exemple à 0, pour une sortie plus déterministe. Dans psql, la fonction json_agg rassemble les lignes d'une requête dans un tableau JSON, que l'outil ci-dessous lit directement.

Les règles, les lignes et la question doivent tenir dans la longueur de contexte. La page sur la longueur de contexte d'Ollama donne une valeur par défaut de 4k tokens avec moins de 24 GiB de VRAM, et sa FAQ indique 4096 tokens ; ollama ps sur notre machine de test affichait 4096. num_ctx dans options ou la variable d'environnement OLLAMA_CONTEXT_LENGTH la modifie.

Quand le prompt est plus long, /api/chat ne renvoie pas d'erreur par défaut. Dans le code source d'Ollama (0.40.11), le serveur commence par supprimer des messages antérieurs entiers, en conservant les messages system et le dernier message. Si le prompt restant est encore trop long, il conserve les premiers tokens (num_keep, 4 par défaut) et la fin du prompt, et supprime la partie intermédiaire. Dans notre test avec qwen2.5:7b et num_ctx 1024, un prompt de 2,068 tokens a été ramené à 514. Le message system et les premières sources ont été perdus : avec la réponse dans la source [1], le modèle a répondu par un mot de code qui ne figurait dans aucune source, et avec la réponse dans la dernière source, il a répondu correctement mais sans le numéro de source que demandait le message system. La réponse ne contenait aucune erreur ; le journal du serveur contenait l'avertissement "truncating input prompt".

Le code source d'Ollama comporte aussi un champ truncate pour les requêtes de chat, qui ne figure pas sur la page de /api/chat. Avec "truncate": false, la même requête a renvoyé HTTP 400 avec l'erreur "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Le champ prompt_eval_count d'une réponse indique le nombre de tokens du prompt ; dans le test avec coupure, il valait 514, et non 2,068.

Une citation peut être vérifiée mécaniquement : le numéro doit renvoyer à une source qui a été envoyée, et l'extrait cité devrait apparaître dans cette source. Dans notre test avec quatre sources et qwen2.5:7b, les extraits cités des réponses en JSON correspondaient mot pour mot aux sources. Cela ne prouve pas que la réponse est correcte : interrogé sur la taille d'un vecteur de 384 dimensions, le modèle a cité la bonne règle (4 fois les dimensions plus 8 octets) et a pourtant répondu 1552 octets au lieu de 1,544.

Examinez aussi les réponses sans citations. Quand les sources ne contenaient pas la réponse, le modèle a une fois répondu à partir de ses propres connaissances sans citations, et une fois dit qu'il ne savait pas tout en citant quand même une source sans rapport. Si done_reason dans la réponse vaut "length", la réponse a été coupée par num_predict et il peut manquer ses citations.

Le README indique qu'un index HNSW se construit nettement plus vite quand le graphe tient dans maintenance_work_mem, affiche un avis quand il n'y tient plus, et prévient de ne pas fixer maintenance_work_mem si haut qu'il épuise la mémoire du serveur. Comme pour les autres index, il est plus rapide de créer l'index après le chargement des données initiales. Les index n'ont pas besoin de tenir en mémoire, mais vous obtiendrez probablement de meilleures performances s'ils y tiennent ; SELECT pg_size_pretty(pg_relation_size('index_name')) affiche la taille d'un index.

Pour un ensemble de travail et des index plus petits, le README suggère halfvec, l'indexation en demi-précision ou la quantification binaire. Si Ollama tourne sur le même serveur, PostgreSQL et les modèles se partagent la même mémoire ; notre article sur la surveillance de la mémoire d'Ollama explique ce qui détermine la quantité utilisée par les modèles.