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
PostCreateno 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 triggersbefore). - En lote.
create_manyyupsert_manypiden todos los vectores en una sola llamada al encoder, ycreatetambié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,updateyupdate_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.