Saltar a contenido

Búsqueda vectorial

Solo en PostgreSQL, sobre pgvector, y solo para las columnas declaradas con vector_column().

Un método por columna

Cada vector_column() genera el suyo: find_similar_by_<columna>.

resultados = public_sync_api.post.find_similar_by_embedding(
    text='cómo desplegar en producción',   # se codifica con el encoder declarado
    limit=10,
    metric='cosine',                       # 'l2' | 'cosine' | 'inner_product'
    threshold=0.5,                         # solo resultados por debajo de esa distancia
    includes=['autor'],
)

for r in resultados:
    print(r['distance'], r['record'].titulo)

Devuelve una lista de diccionarios con dos claves:

Clave Qué es
record El DTO <Modelo>Read de la fila
distance La distancia al vector de búsqueda — menor es más parecido

Con un vector ya calculado

resultados = public_sync_api.post.find_similar_by_embedding(
    vector=[0.12, -0.04, ...],   # tantas dimensiones como declare la columna
    limit=5,
)

text y vector son excluyentes: hay que pasar uno, y solo uno.

La métrica

Las funciones de pgvector devuelven distancia, no similitud:

Métrica Rango Lectura
cosine [0, 2] 0 = idénticos, 1 = ortogonales, 2 = opuestos
l2 [0, ∞) Distancia euclídea. Depende de la magnitud de los vectores
inner_product — Producto interno negado: menor valor = más parecido

Con metric='cosine', un threshold=0.5 deja pasar lo que se parezca en torno a un 75 % o más.

Combinar con filtros

El método acepta includes, rls y session. Si además necesitas filtrar por columnas, usa el filtro de la columna vectorial en find_many, que ordena por distancia:

public_sync_api.post.find_many(
    embedding='cómo desplegar en producción',   # búsqueda por similitud
    estado='publicado',                         # y filtro normal
    limit=10,
)

Las columnas vectoriales no se cargan por defecto

Un vector de 768 dimensiones en cada fila de un listado es mucho tráfico para nada, así que se difieren:

posts = public_sync_api.post.find_many(limit=10)                        # sin embedding
posts = public_sync_api.post.find_many(limit=10, include_vectors=True)  # con él

Y lo mismo en lo que devuelven create y create_many: el vector se guarda, pero el registro devuelto lo trae a None salvo con include_vectors=True. Antes lo traían siempre, y mil filas con un vector de 3.072 dimensiones eran unos tres millones de números de vuelta que nadie había pedido. Las filas creadas anidadas salen sin él siempre, como las relaciones de una lectura.

creados = public_sync_api.post.create_many(posts)                         # sin embedding
creados = public_sync_api.post.create_many(posts, include_vectors=True)   # con él

Al escribir

Si la columna declara source, el cliente codifica solo: escribes el texto y el vector se calcula al guardar. Eso implica cargar el modelo de embeddings en el proceso que escribe, así que la primera escritura de un proceso es más lenta.

public_sync_api.post.create_many([
    PostCreate(titulo=t, contenido=c) for t, c in articulos   # ningún vector todavía
])                                                           # una llamada al encoder, para todos
  • Lo calcula el DAO, no el DTO. Construir un PostCreate no llama al encoder: el vector se calcula justo antes de escribir, con lo que haya en ese momento (también lo que hayan cambiado los triggers before).
  • En lote. create_many y upsert_many piden todos los vectores en una sola llamada al encoder, y create también los de las filas anidadas.
  • Sin bloquear. En el DAO asíncrono el encoder se espera con await: una escritura no para el bucle de eventos mientras responde el proveedor.
  • Por todos los caminos: create, create_many, upsert, upsert_many, from_dataframe, update y update_many. Si cambias el texto, el vector se recalcula.
  • Un vector que pasas tú se respeta: si el DTO ya lo trae, no se vuelve a calcular.

deferred() ya no hace falta

PostCreate.deferred(...) existía para que el constructor no codificara, y se conserva por compatibilidad: ahora es lo mismo que PostCreate(...). Hasta la 0.7.19, el constructor llamaba al encoder en el acto —uno a uno y, en código asíncrono, bloqueando—, y deferred() tampoco lo evitaba.