임베딩

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 = { ... } }를 반환합니다.

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

단일 content_type으로 범위가 지정된 search의 편의 래퍼입니다.

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) 행 id로 단일 레코드 제거
embedding_repo.search_by_embedding(vector, options) 원시 벡터에 대한 유사도 검색

search_by_embedding은 { content_type, origin_id, context_id, limit }을 받습니다.

데이터베이스 지원

마이그레이션은 target_db의 데이터베이스 드라이버에 적합한 스키마를 생성합니다:

  • PostgreSQL - vector(512) 컬럼과 IVFFlat 인덱스가 있는 embeddings 테이블. pgvector 확장이 필요합니다.
  • SQLite - 텍스트로 저장된 벡터와 KNN 검색을 위한 동반 sqlite-vec 가상 테이블이 있는 embeddings 테이블.

벡터는 API 레이어에서 항상 일반 JSON 배열을 통해 왕복됩니다.

참고 항목