Guarda y busca embeddings de Ollama en PostgreSQL con pgvector

El README de pgvector lo describe como búsqueda por similitud de vectores de código abierto para Postgres. Admite búsqueda exacta y aproximada de vecinos más cercanos; vectores de precisión simple, media precisión, binarios y dispersos; y distancia L2, producto interno, distancia del coseno, distancia L1, distancia de Hamming y distancia de Jaccard. Como los vectores son columnas normales de PostgreSQL, también cuentan con cumplimiento ACID, recuperación en un punto en el tiempo y JOINs.

Para una búsqueda en tus documentos, guardas una fila por fragmento con su texto y su vector, conviertes la pregunta en un embedding con el mismo modelo y ordenas las filas por su distancia al vector de la pregunta.

pgvector admite PostgreSQL 13 y posteriores. El README enumera varias formas de instalarlo, entre ellas estas:

Una columna de tipo vector(n) guarda vectores con exactamente n dimensiones, y n debe ser la longitud de los vectores de tu modelo de embeddings. Un vector con otra longitud se rechaza: cuando insertamos un vector de 2 dimensiones en una columna vector(3), PostgreSQL devolvió "expected 3 dimensions, not 2". all-minilm devuelve 384 dimensiones, así que su columna es vector(384).

El README indica que cada vector ocupa 4 × dimensiones + 8 bytes, con cada elemento como un número de coma flotante de precisión simple, y permite hasta 16,000 dimensiones en una columna. Un índice admite menos dimensiones, como se ve más abajo. El tipo halfvec guarda valores de media precisión en 2 × dimensiones + 8 bytes.

pgvector lee un vector como texto entre corchetes, como '[1,2,3]', y el README dice que todos los elementos deben ser finitos (sin NaN, Infinity ni -Infinity). Cada array del campo embeddings de una respuesta de /api/embed ya tiene esa forma, y la respuesta conserva el orden de la entrada, así que el primer texto corresponde al primer vector.

El README muestra INSERT para unas pocas filas, INSERT … ON CONFLICT para upserts y COPY para cargas masivas. El conversor de abajo empareja tus textos con la respuesta y escribe sentencias INSERT con las comillas escapadas. Ejecutamos su resultado con textos que contenían comillas, barras invertidas, saltos de línea y emoji, y volvieron sin cambios.

La documentación de Ollama recomienda la similitud del coseno para la mayoría de los casos de búsqueda semántica y dice que /api/embed devuelve vectores de longitud 1. Para esos vectores, la distancia del coseno, la distancia L2 y el producto interno ordenan las filas igual, porque la distancia L2 al cuadrado es 2 menos 2 veces la similitud del coseno. En nuestra prueba con all-minilm, las tres primeras filas fueron las mismas con las tres, y la distancia L2 de 0.931 coincidió con la similitud del coseno de 0.566.

Cada distancia tiene su propio operador. Una búsqueda ordena por el operador y toma las primeras filas con LIMIT, y un índice se crea para una clase de operador.

Sin índice, pgvector hace una búsqueda exacta de vecinos más cercanos, que según el README ofrece una exhaustividad (recall) perfecta. Un índice aproximado cambia algo de exhaustividad por velocidad, y el README advierte de que las consultas pueden devolver resultados distintos después de añadir uno.

Un índice solo se usa cuando la consulta tiene ORDER BY y LIMIT y el ORDER BY es el propio operador de distancia en orden ascendente. ORDER BY embedding <=> $1 LIMIT 5 puede usar el índice; ORDER BY 1 - (embedding <=> $1) DESC no puede. El README también señala que un escaneo de la tabla puede ser más rápido cuando la tabla es pequeña.

Con HNSW, los resultados están limitados por hnsw.ef_search, que es 40 por defecto. En una tabla de prueba de 200 filas con un índice HNSW, LIMIT 100 devolvió 40 filas; tras SET hnsw.ef_search = 100, devolvió 100. Fija hnsw.ef_search en al menos el número de filas que necesitas. SET LOCAL dentro de una transacción lo cambia solo para una consulta.

El filtrado también reduce los resultados. Con los índices aproximados, el README dice que la condición WHERE se aplica después de recorrer el índice: si una condición coincide con el 10% de las filas, HNSW con el hnsw.ef_search predeterminado de 40 devuelve solo 4 filas de media. Desde la versión 0.8.0, los escaneos iterativos del índice (SET hnsw.iterative_scan = strict_order, o relaxed_order) recorren más parte del índice hasta encontrar suficientes filas, hasta hnsw.max_scan_tuples (20,000 por defecto).

Cuando la búsqueda devuelve las filas más cercanas, el modelo las necesita en su prompt. /api/chat de Ollama recibe una lista de mensajes, cada uno con un rol (system, user, assistant o tool) y su content. Una disposición sencilla es un mensaje system con las reglas y un mensaje user que enumera las filas con un número cada una, como [1] y [2], seguido de la pregunta. Con números, la respuesta puede decir qué filas ha usado, y puedes asociar cada número a su fila.

Para obtener las citas con una forma fija, da al campo format un JSON Schema con la respuesta y una lista de citas, cada una con el número de la fuente y un fragmento citado corto. La página de salidas estructuradas de Ollama recomienda escribir también el esquema en el prompt y bajar la temperatura (temperature), por ejemplo a 0, para obtener una salida más determinista. En psql, la función json_agg reúne las filas de una consulta en un array JSON, que la herramienta de abajo lee directamente.

Las reglas, las filas y la pregunta tienen que caber en la longitud de contexto. La página de longitud de contexto de Ollama indica un valor por defecto de 4k tokens con menos de 24 GiB de VRAM, y sus preguntas frecuentes indican 4096 tokens; ollama ps en nuestra máquina de prueba mostró 4096. num_ctx en options o la variable de entorno OLLAMA_CONTEXT_LENGTH lo cambian.

Cuando el prompt es más largo, /api/chat no devuelve un error por defecto. En el código fuente de Ollama (0.40.11), el servidor primero descarta mensajes anteriores completos, conservando los mensajes system y el último mensaje. Si el prompt restante sigue siendo demasiado largo, conserva los primeros tokens (num_keep, 4 por defecto) y el final del prompt, y descarta la parte intermedia. En nuestra prueba con qwen2.5:7b y num_ctx 1024, un prompt de 2,068 tokens se recortó a 514. Se perdieron el mensaje system y las primeras fuentes: con la respuesta en la fuente [1], el modelo contestó con una palabra en clave que no estaba en ninguna fuente, y con la respuesta en la última fuente, contestó correctamente pero sin el número de fuente que pedía el mensaje system. La respuesta no contenía ningún error; el registro del servidor tenía el aviso "truncating input prompt".

El código fuente de Ollama también tiene un campo truncate para las peticiones de chat, que no figura en la página de /api/chat. Con "truncate": false, la misma petición devolvió HTTP 400 con el error "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". El campo prompt_eval_count de una respuesta es el número de tokens del prompt; en la prueba con recorte fue 514, no 2,068.

Una cita se puede comprobar de forma mecánica: el número debe corresponder a una fuente que se envió, y el fragmento citado debería aparecer en esa fuente. En nuestra prueba con cuatro fuentes y qwen2.5:7b, los fragmentos citados de las respuestas en JSON coincidían palabra por palabra con las fuentes. Eso no demuestra que la respuesta sea correcta: al preguntar por el tamaño de un vector de 384 dimensiones, el modelo citó la regla correcta (4 veces las dimensiones más 8 bytes) y aun así respondió 1552 bytes en lugar de 1,544.

Mira también las respuestas sin citas. Cuando las fuentes no contenían la respuesta, el modelo una vez contestó con su propio conocimiento y sin citas, y otra vez dijo que no lo sabía pero citó igualmente una fuente sin relación. Si done_reason en la respuesta es "length", la respuesta se cortó por num_predict y puede que le falten las citas.

El README dice que un índice HNSW se construye mucho más rápido cuando el grafo cabe en maintenance_work_mem, muestra un aviso cuando ya no cabe y advierte de que no se fije maintenance_work_mem tan alto que agote la memoria del servidor. Como con otros índices, es más rápido crear el índice después de cargar los datos iniciales. Los índices no tienen que caber en memoria, pero probablemente verás mejor rendimiento si caben; SELECT pg_size_pretty(pg_relation_size('index_name')) muestra el tamaño de un índice.

Para un conjunto de trabajo más pequeño y índices más pequeños, el README sugiere halfvec, la indexación de media precisión o la cuantización binaria. Si Ollama se ejecuta en el mismo servidor, PostgreSQL y los modelos comparten la misma memoria; nuestro artículo sobre cómo vigilar la memoria de Ollama explica qué determina cuánta usan los modelos.