txtai Embeddings API

txtai의 Embeddings 클래스는 시맨틱 검색 엔진 자체예요. 데이터를 벡터로 변환하고, 색인한 뒤 비슷한 의미를 가진 결과를 찾아주는 일을 담당해요.

출처: txtai Methods

Embeddings는 시맨틱 검색을 제공하는 엔진이에요. 데이터가 임베딩 벡터로 변환되면서, '비슷한 개념'이 '비슷한 벡터'를 만들게 돼요. 이 벡터들로 크고 작은 인덱스를 만들고, 그 인덱스는 '같은 의미(not necessarily the same keywords)'를 가진 결과를 찾는 데 쓰여요.

Embeddings 클래스의 생성 시그니처를 보면 설정과 모델 캐시를 받아요.

class Embeddings:
    def __init__(self, config=None, models=None, **kwargs):

인덱스는 읽기 연산엔 스레드 안전하지만, 쓰기 연산은 동기화가 필요하다는 점을 기억해 두면 좋아요. 주요 메서드를 살펴볼게요.

index(documents, ...) — 문서를 벡터로 변환하고 ANN(근사 최근접 이웃) 인덱스를 만들어요. Faiss가 기본 백엔드예요.
upsert(documents, ...) — 인덱스가 있으면 새 데이터를 추가하고, 같은 데이터는 갱신해요.
search(query, limit=None, ...) — 입력 쿼리와 가장 비슷한 문서를 찾아요. 인덱스 검색, 인덱스+DB 검색, 그래프 검색 중 설정에 따라 동작해요.
batchsearch(queries, ...) — 검색을 여러 쿼리로 배치 처리해요.
transform(document, ...) / batchtransform(...) — 문서를 임베딩 벡터로 변환해요.
load(path, ...) — 기존 인덱스를 설정·클라우드 저장소에서 불러와요.

search의 반환은 설정에 따라 달라져요. 인덱스만 있으면 (id, score) 목록, 인덱스+DB면 dict 목록, 그래프 검색이면 그래프 결과를 반환해요. 임베딩 저장을 켜면(content) 입력 콘텐츠가 벡터 옆 데이터베이스에 저장돼, 추가 필드 필터링이나 콘텐츠 검색이 가능해져요.