Ollama-Embeddings in PostgreSQL mit pgvector speichern und durchsuchen

Die pgvector-README beschreibt die Erweiterung als Open-Source-Ähnlichkeitssuche für Vektoren in Postgres. Sie unterstützt die exakte und die approximative Suche nach nächsten Nachbarn; Vektoren mit einfacher Genauigkeit, halber Genauigkeit sowie binäre und dünnbesetzte Vektoren; und L2-Abstand, Skalarprodukt, Kosinus-Abstand, L1-Abstand, Hamming-Abstand und Jaccard-Abstand. Da die Vektoren gewöhnliche PostgreSQL-Spalten sind, profitieren sie auch von ACID-Konformität, Point-in-Time-Recovery und JOINs.

Für eine Suche in Ihren Dokumenten speichern Sie pro Textabschnitt eine Zeile mit dem Text und seinem Vektor, erzeugen das Embedding der Frage mit demselben Modell und sortieren die Zeilen nach ihrem Abstand zum Vektor der Frage.

pgvector unterstützt PostgreSQL 13 und neuer. Die README nennt mehrere Installationswege, darunter diese:

Eine Spalte vom Typ vector(n) enthält Vektoren mit genau n Dimensionen, und n muss der Länge der Vektoren Ihres Embedding-Modells entsprechen. Ein Vektor mit anderer Länge wird abgelehnt: Als wir einen Vektor mit 2 Dimensionen in eine Spalte vector(3) einfügten, gab PostgreSQL "expected 3 dimensions, not 2" zurück. all-minilm liefert 384 Dimensionen, seine Spalte ist also vector(384).

Die README gibt den Speicherbedarf jedes Vektors mit 4 × Dimensionen + 8 Bytes an, wobei jedes Element eine Gleitkommazahl mit einfacher Genauigkeit ist, und erlaubt bis zu 16,000 Dimensionen in einer Spalte. Ein Index unterstützt weniger Dimensionen, wie unten gezeigt. Der Typ halfvec speichert Werte mit halber Genauigkeit in 2 × Dimensionen + 8 Bytes.

pgvector liest einen Vektor als Text in eckigen Klammern, etwa '[1,2,3]', und die README sagt, dass alle Elemente endlich sein müssen (kein NaN, Infinity oder -Infinity). Jedes Array im Feld embeddings einer Antwort von /api/embed hat bereits diese Form, und die Antwort behält die Reihenfolge der Eingabe bei, der erste Text gehört also zum ersten Vektor.

Die README zeigt INSERT für einige Zeilen, INSERT … ON CONFLICT für Upserts und COPY für das Massenladen. Der Konverter unten ordnet Ihre Texte der Antwort zu und schreibt INSERT-Anweisungen mit maskierten Anführungszeichen. Wir haben seine Ausgabe mit Texten ausgeführt, die Anführungszeichen, Backslashes, Zeilenumbrüche und Emoji enthielten, und sie kamen unverändert zurück.

Die Dokumentation von Ollama empfiehlt für die meisten Anwendungsfälle der semantischen Suche die Kosinus-Ähnlichkeit und sagt, dass /api/embed Vektoren mit der Länge 1 zurückgibt. Für solche Vektoren bringen Kosinus-Abstand, L2-Abstand und Skalarprodukt die Zeilen in dieselbe Reihenfolge, weil der quadrierte L2-Abstand 2 minus 2 mal die Kosinus-Ähnlichkeit ist. In unserem Test mit all-minilm waren die obersten drei Zeilen bei allen dreien gleich, und der L2-Abstand von 0.931 passte zur Kosinus-Ähnlichkeit von 0.566.

Jeder Abstand hat seinen eigenen Operator. Eine Suche sortiert nach dem Operator und nimmt mit LIMIT die ersten Zeilen, und ein Index wird für eine Operatorklasse gebaut.

Ohne Index führt pgvector eine exakte Suche nach nächsten Nachbarn durch, die laut README einen perfekten Recall liefert. Ein approximativer Index tauscht etwas Recall gegen Geschwindigkeit, und die README warnt, dass Abfragen nach dem Hinzufügen eines Index andere Ergebnisse liefern können.

Ein Index wird nur verwendet, wenn die Abfrage ORDER BY und LIMIT enthält und das ORDER BY der Abstandsoperator selbst in aufsteigender Reihenfolge ist. ORDER BY embedding <=> $1 LIMIT 5 kann den Index nutzen; ORDER BY 1 - (embedding <=> $1) DESC kann es nicht. Die README merkt außerdem an, dass ein Table Scan bei kleinen Tabellen schneller sein kann.

Bei HNSW werden die Ergebnisse durch hnsw.ef_search begrenzt, standardmäßig 40. Auf einer Testtabelle mit 200 Zeilen und einem HNSW-Index lieferte LIMIT 100 nur 40 Zeilen; nach SET hnsw.ef_search = 100 waren es 100. Setzen Sie hnsw.ef_search mindestens auf die Anzahl der Zeilen, die Sie brauchen. SET LOCAL innerhalb einer Transaktion ändert den Wert nur für eine einzelne Abfrage.

Auch Filter verringern die Ergebnisse. Bei approximativen Indizes wird laut README die WHERE-Bedingung angewendet, nachdem der Index durchsucht wurde: Wenn eine Bedingung auf 10% der Zeilen zutrifft, liefert HNSW mit dem Standardwert 40 für hnsw.ef_search im Durchschnitt nur 4 Zeilen. Seit Version 0.8.0 durchsuchen iterative Indexscans (SET hnsw.iterative_scan = strict_order oder relaxed_order) mehr vom Index, bis genug Zeilen gefunden sind, höchstens jedoch hnsw.max_scan_tuples (standardmäßig 20,000).

Wenn die Suche die nächsten Zeilen liefert, braucht das Modell sie in seinem Prompt. /api/chat von Ollama nimmt eine Liste von Nachrichten entgegen, jede mit einer Rolle (system, user, assistant oder tool) und ihrem content. Ein einfacher Aufbau ist eine system-Nachricht mit den Regeln und eine user-Nachricht, die die Zeilen mit jeweils einer Nummer auflistet, etwa [1] und [2], gefolgt von der Frage. Mit Nummern kann die Antwort angeben, welche Zeilen sie verwendet hat, und Sie können jede Nummer wieder ihrer Zeile zuordnen.

Um die Zitate in einer festen Form zu erhalten, geben Sie dem Feld format ein JSON Schema mit der Antwort und einer Liste von Zitaten, jedes mit der Nummer der Quelle und einer kurzen zitierten Textstelle. Die Seite zu strukturierten Ausgaben von Ollama empfiehlt, das Schema zusätzlich in den Prompt zu schreiben und die Temperatur (temperature) zu senken, zum Beispiel auf 0, damit die Ausgabe deterministischer wird. In psql sammelt die Funktion json_agg die Zeilen einer Abfrage in einem JSON-Array, das das Tool unten direkt liest.

Die Regeln, die Zeilen und die Frage müssen alle in die Kontextlänge passen. Die Seite zur Kontextlänge von Ollama nennt einen Standardwert von 4k Tokens bei weniger als 24 GiB VRAM, und die FAQ nennt 4096 Tokens; ollama ps zeigte auf unserer Testmaschine 4096. num_ctx in options oder die Umgebungsvariable OLLAMA_CONTEXT_LENGTH ändert den Wert.

Wenn der Prompt länger ist, gibt /api/chat standardmäßig keinen Fehler zurück. Im Quellcode von Ollama (0.40.11) verwirft der Server zuerst ganze frühere Nachrichten und behält dabei die system-Nachrichten und die letzte Nachricht. Ist der verbleibende Prompt immer noch zu lang, behält er die ersten Tokens (num_keep, standardmäßig 4) und das Ende des Prompts und verwirft den Teil dazwischen. In unserem Test mit qwen2.5:7b und num_ctx 1024 wurde ein Prompt von 2,068 Tokens auf 514 gekürzt. Die system-Nachricht und die ersten Quellen gingen verloren: Stand die Antwort in Quelle [1], antwortete das Modell mit einem Codewort, das in keiner Quelle stand, und stand die Antwort in der letzten Quelle, antwortete es richtig, aber ohne die Quellennummer, die die system-Nachricht verlangt hatte. Die Antwort enthielt keinen Fehler; im Serverlog stand die Warnung "truncating input prompt".

Der Quellcode von Ollama hat für Chat-Anfragen außerdem ein Feld truncate, das auf der Seite zu /api/chat nicht aufgeführt ist. Mit "truncate": false lieferte dieselbe Anfrage HTTP 400 mit der Fehlermeldung "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Das Feld prompt_eval_count einer Antwort ist die Anzahl der Tokens im Prompt; im Test mit der Kürzung betrug sie 514, nicht 2,068.

Ein Zitat lässt sich maschinell prüfen: Die Nummer muss sich auf eine gesendete Quelle beziehen, und die zitierte Textstelle sollte in dieser Quelle vorkommen. In unserem Test mit vier Quellen und qwen2.5:7b stimmten die zitierten Textstellen in den JSON-Antworten Wort für Wort mit den Quellen überein. Das beweist nicht, dass die Antwort stimmt: Auf die Frage nach der Größe eines Vektors mit 384 Dimensionen zitierte das Modell die richtige Regel (4 mal die Dimensionen plus 8 Bytes) und antwortete trotzdem 1552 Bytes statt 1,544.

Sehen Sie sich auch Antworten ohne Zitate an. Als die Quellen die Antwort nicht enthielten, antwortete das Modell einmal aus eigenem Wissen ohne Zitate und sagte ein anderes Mal, es wisse es nicht, zitierte aber trotzdem eine Quelle ohne Bezug. Wenn done_reason in der Antwort "length" ist, wurde die Antwort durch num_predict abgeschnitten, und ihr fehlen möglicherweise die Zitate.

Laut README baut sich ein HNSW-Index deutlich schneller auf, wenn der Graph in maintenance_work_mem passt; sie zeigt einen Hinweis an, wenn er nicht mehr hineinpasst, und warnt davor, maintenance_work_mem so hoch zu setzen, dass der Arbeitsspeicher des Servers erschöpft wird. Wie bei anderen Indizes ist es schneller, den Index nach dem Laden der Anfangsdaten anzulegen. Indizes müssen nicht in den Arbeitsspeicher passen, aber die Leistung ist wahrscheinlich besser, wenn sie es tun; SELECT pg_size_pretty(pg_relation_size('index_name')) zeigt die Größe eines Index.

Für eine kleinere Arbeitsmenge und kleinere Indizes schlägt die README halfvec, Indizierung mit halber Genauigkeit oder binäre Quantisierung vor. Wenn Ollama auf demselben Server läuft, teilen sich PostgreSQL und die Modelle denselben Arbeitsspeicher; unser Artikel über die Überwachung des Ollama-Speichers erklärt, wovon der Speicherbedarf der Modelle abhängt.