Embeddings

El módulo wippy/embeddings genera embeddings mediante wippy/llm, los almacena en una base de datos de la aplicación y realiza búsquedas vectoriales por similitud. Admite PostgreSQL con pgvector y SQLite con sqlite-vec.

Esta página es una introducción a la API con fragmentos de referencia, no un tutorial independiente. Los fragmentos suponen un proyecto Wippy existente, una base de datos configurada y el modelo de embeddings, provider y credenciales descritos a continuación. Las llamadas remotas de embeddings pueden generar cargos del provider. Para una aplicación completa que indexa y busca contenido, siga Construir un pipeline RAG.

Configuracion

Agrega el modulo a tu proyecto:

wippy add wippy/embeddings
wippy install

Declara la dependencia y apunta el requisito target_db a tu base de datos de aplicacion mediante los parameters de la dependencia:

version: "1.0"
namespace: app

entries:
  - name: app_db
    kind: db.sql.sqlite
    file: ./data/app.db

  - name: dep.embeddings
    kind: ns.dependency
    component: wippy/embeddings
    version: "*"
    parameters:
      - name: target_db
        value: app:app_db

Al iniciar, wippy/migration toma la migracion 01_create_embeddings_table y crea la tabla embeddings_512 con el indice vectorial apropiado para tu driver de base de datos.

Si usa la ruta relativa de SQLite mostrada arriba, cree el directorio data antes de iniciar la aplicación.

Constantes fijas actuales

El módulo define actualmente estas constantes privadas; no son parámetros de la dependencia:

Los tokens se estiman como ceil(#text / 4). Los lotes demasiado grandes se dividen entre elementos. Un elemento individual mayor que el presupuesto no se divide y hace que ese sublote falle antes de la llamada LLM.

Importacion

entries:
  - name: my_app
    kind: library.lua
    source: file://my_app.lua
    imports:
      embeddings: wippy.embeddings:embeddings

local embeddings = require("embeddings")

API de Alto Nivel (wippy.embeddings:embeddings)

add

local result, err = embeddings.add(content, content_type, origin_id, context_id, meta)

Genera un embedding para content y lo persiste.

Retorna { entry_id, origin_id, content_type, context_id } o nil, err.

add_batch

El ejemplo siguiente usa ID de aplicación compatibles con SQLite. Para PostgreSQL, sustituya doc-1 por un UUID porque el esquema PostgreSQL almacena origin_id como UUID.

local result, err = embeddings.add_batch({
    { content = "...", content_type = "chunk", origin_id = "doc-1" },
    { content = "...", content_type = "chunk", origin_id = "doc-1", context_id = "s1" },
})

Genera y almacena embeddings para varios elementos en una sola llamada. Si el recuento total estimado de tokens supera MAX_TOKENS_PER_REQUEST, el método divide el lote en fragmentos. Cada fragmento del repositorio es transaccional, pero un lote de alto nivel dividido no es atómico entre fragmentos: los anteriores permanecen almacenados si falla uno posterior. Retorna { count, items = { ... } }.

Para eliminar registros creados durante las pruebas, use el método delete_by_origin(origin_id) de la API del repositorio para cada origen de ejemplo.

search

local hits, err = embeddings.search("how do migrations work?", {
    content_type = "document_chunk",
    origin_id    = "doc-1",
    context_id   = "section-2",
    limit        = 10,
})

Incrusta la cadena de consulta y realiza una busqueda por similitud contra los vectores almacenados. Todos los filtros son opcionales; los registros coincidentes se ordenan por similitud.

origin_id puede ser un string o un array no vacío de strings. Cada resultado contiene entry_id, origin_id, content_type, context_id, content, meta decodificado, timestamps y similarity.

find_by_type

local hits, err = embeddings.find_by_type(
    "how do migrations work?",
    "document_chunk",
    { limit = 10 }
)

Llama a search con un único content_type. El límite predeterminado es 10.

find_by_origin

local hits, err = embeddings.find_by_origin("how do migrations work?", "doc-1", {
    content_type = "document_chunk",
    context_id   = "section-2",
    limit        = 5,
})

Llama a search con un único origin_id y filtros opcionales de content_type y context_id. El límite predeterminado es 5.

API del Repositorio (wippy.embeddings:embedding_repo)

Use el repositorio directamente cuando ya tenga un vector y quiera omitir la generación del embedding. Los embeddings raw deben contener exactamente 512 valores numéricos:

search_by_embedding acepta { content_type, origin_id, context_id, limit }.

Soporte de Bases de Datos

La migracion crea el esquema apropiado para el driver de base de datos en target_db:

• PostgreSQL - Tabla embeddings_512 con una columna vector(512) y un indice IVFFlat. Requiere la extension pgvector.
• SQLite - Tabla virtual vec0 embeddings_512 que contiene la columna vectorial embedding float[512] junto con las columnas de metadatos y contenido para busqueda KNN.

Los vectores siempre se transportan como un array JSON plano en la capa de API.

Ver Tambien

• LLM — llm.embed(...) para generación raw de embeddings
• Migraciones — Ejecutor de migraciones que aprovisiona la tabla
• Visión general del framework — Uso de módulos del framework