Embeddings

Embeddings

Модуль wippy/embeddings предоставляет хранилище векторных эмбеддингов и поиск по сходству для PostgreSQL (pgvector) и SQLite (sqlite-vec). Он оборачивает wippy/llm для генерации эмбеддингов и сохраняет их в базе данных приложения.

Настройка

Добавьте модуль в проект:

wippy add wippy/embeddings
wippy install

Объявите зависимость и укажите в требовании target_db базу данных вашего приложения:

version: "1.0"
namespace: app

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

  - name: dep.embeddings
    kind: ns.dependency
    component: wippy/embeddings
    version: "*"

  - name: target_db
    kind: registry.entry
    meta:
      wippy.embeddings.target_db: app:app_db

При запуске wippy/migration подхватывает миграцию 01_create_embeddings_table и создаёт таблицу embeddings с соответствующим векторным индексом для вашего драйвера базы данных.

Константы конфигурации

Конфигурация по умолчанию встроена в модуль:

Константа	Значение по умолчанию	Описание
EMBEDDING_MODEL	text-embedding-3-small	Модель LLM для генерации векторов
EMBEDDING_DIMENSIONS	512	Размер вектора, передаваемый в модель
MAX_TOKENS_PER_REQUEST	8000	Бюджет токенов на вызов; крупные батчи разбиваются
DEFAULT_SEARCH_LIMIT	10	Количество результатов, возвращаемых search по умолчанию

Токены оцениваются как #text / 4. Батчи, превышающие бюджет, разбиваются автоматически.

Импорт

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

local embeddings = require("embeddings")

Высокоуровневый API (wippy.embeddings:embeddings)

add

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

Генерирует эмбеддинг для content и сохраняет его.

Параметр	Тип	Обязательный	Описание
content	string	да	Текст для встраивания
content_type	string	да	Произвольная метка, например "document_chunk", "question"
origin_id	string	да	Идентификатор исходного документа или записи
context_id	string	нет	Дополнительный ключ области (раздел, чат, арендатор)
meta	table	нет	Произвольные метаданные, сериализуемые в JSON

Возвращает { id, content, content_type, origin_id, context_id, meta } или nil, err.

add_batch

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" },
})

Встраивает и сохраняет множество элементов за один вызов. Если оценённое общее количество токенов превышает MAX_TOKENS_PER_REQUEST, батч разбивается и обрабатывается частями. Возвращает { count, items = { ... } }.

search

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

Встраивает строку запроса и выполняет поиск по сходству среди сохранённых векторов. Все фильтры опциональны; совпавшие записи упорядочиваются по сходству.

find_by_type

local hits, err = embeddings.find_by_type(query, content_type, { limit = 10 })

Удобная обёртка над search с областью одного content_type.

find_by_origin

local hits, err = embeddings.find_by_origin(query, origin_id, {
    content_type = "document_chunk",
    context_id   = "section-2",
    limit        = 5,
})

Удобная обёртка с областью одного origin_id, опционально с дополнительным сужением.

API репозитория (wippy.embeddings:embedding_repo)

Используйте репозиторий напрямую, когда у вас уже есть вектор и нужно пропустить генерацию эмбеддинга:

Функция	Описание
embedding_repo.add(content, content_type, origin_id, context_id, meta, embedding)	Вставить предвычисленный вектор
embedding_repo.add_batch(batch)	Вставить множество предвычисленных векторов одним запросом
embedding_repo.get_by_origin(origin_id)	Получить все записи по заданному origin
embedding_repo.delete_by_origin(origin_id)	Удалить все записи по заданному origin
embedding_repo.delete_by_entry(entry_id)	Удалить одну запись по её идентификатору строки
embedding_repo.search_by_embedding(vector, options)	Поиск по сходству с сырым вектором

search_by_embedding принимает { content_type, origin_id, context_id, limit }.

Поддержка баз данных

Миграция создаёт схему, соответствующую драйверу базы данных в target_db:

• PostgreSQL — таблица embeddings со столбцом vector(512) и индексом IVFFlat. Требуется расширение pgvector.
• SQLite — таблица embeddings с вектором, хранящимся как текст, плюс сопутствующая виртуальная таблица sqlite-vec для KNN-поиска.

Векторы на уровне API всегда передаются через обычный JSON-массив.

См. также

• LLM — llm.embed(...) для прямой генерации эмбеддингов
• Migrations — Запуск миграций, создающий таблицу
• Обзор фреймворка — Использование модулей фреймворка