LanceDB 정의

LanceDB는 벡터 검색을 위한 데이터베이스다. 텍스트, 이미지, 오디오 같은 데이터를 임베딩 벡터로 변환한 뒤 저장하고, 입력 벡터와 의미적으로 가까운 데이터를 검색할 수 있다.

일반적인 데이터베이스가 다음과 같은 정형 데이터를 저장한다면:

id: 1
title: "문서 제목"
content: "문서 내용"

LanceDB는 여기에 vector 필드를 함께 저장한다.

{
  id: 1,
  title: "문서 제목",
  content: "문서 내용",
  vector: [0.12, -0.03, 0.44, ...]
}

여기서 vector는 원문 데이터를 임베딩 모델로 변환한 숫자 배열이다. LanceDB는 이 벡터를 기준으로 유사한 데이터를 찾는다. 공식 문서에서도 벡터 검색을 raw data를 embedding으로 변환한 뒤 유사한 항목을 찾는 방식으로 설명한다.

LanceDB의 핵심 특징

LanceDB는 단순한 벡터 저장소라기보다, 벡터와 원본 데이터, 메타데이터를 함께 관리하는 AI 데이터베이스에 가깝다. LanceDB 공식 문서는 OSS 버전을 embedded library로 설명하며, Python, TypeScript, Rust SDK를 제공한다고 안내한다.

주요 특징은 다음과 같다.

벡터 검색: 임베딩 벡터 기반 유사도 검색
로컬 사용: 로컬 디렉터리에 DB 파일 저장 가능
메타데이터 저장: 텍스트. ID, 타입, 날짜 등 함께 저장 가능
Full-text search: 키워드 기반 검색 지원
Hybrid searh: 벡터검색 + 키워드 검색 조합 가능
JS SDK - Node.js/ts 환경에서 사용 가능

LanceDB JavaScript SDK는 @lancedb/lancedb 패키지로 제공되며, 설치 시 플랫폼에 맞는 native library를 내려받는다. 지원 플랫폼에는 Linux, macOS, Windows가 포함된다.

설치

pnpm install @lancedb/lancedb

DB 연결

LanceDB는 로컬 경로를 지정해서 연결할 수 있다.

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("./data/lancedb");

위 코드는 현재 프로젝트 기준으로 다음 경로에 LanceDB 데이터를 저장한다.

./data/lancedb

LanceDB Quickstart에서도 로컬 경로에 connect한 뒤 테이블 생성과 벡터 검색을 수행하는 흐름을 기본 사용법으로 제시한다.

테이블 생성

LanceDB에서는 데이터를 table 단위로 저장한다.

테이블은 일반 DB의 테이블과 비슷하게 row들을 저장한다.

const table = await db.createTable("documents", [
  {
    id: 1,
    title: "첫 번째 문서",
    content: "LanceDB는 벡터 검색을 위한 데이터베이스입니다.",
    vector: [0.1, 0.2, 0.3],
  },
  {
    id: 2,
    title: "두 번째 문서",
    content: "SQLite는 로컬 파일 기반 관계형 데이터베이스입니다.",
    vector: [0.8, 0.1, 0.4],
  },
]);

여기서 중요한 점은 같은 테이블에 들어가는 벡터의 차원이 같아야 한다는 점이다.

vector: [0.1, 0.2, 0.3] // 3차원

실제 임베딩 모델을 쓰면 보통 384차원, 768차원, 1024차원 같은 더 긴 벡터가 생성된다.

기존 테이블 조회

이미 생성된 테이블은 openTable()로 연다.

const table = await db.openTable("documents");

LanceDB JavaScript API 문서에서도 테이블 생성은 createTable, 기존 테이블 열기는 openTable을 사용한다고 설명한다.

데이터 추가

기존 테이블에 데이터를 추가할 때는 add()를 사용한다.

await table.add([
  {
    id: 3,
    title: "세 번째 문서",
    content: "벡터 검색은 의미가 비슷한 문서를 찾는 데 사용됩니다.",
    vector: [0.2, 0.3, 0.4],
  },
]);

벡터 검색

벡터 검색은 search()를 사용한다.

const queryVector = [0.1, 0.2, 0.25];

const results = await table
  .search(queryVector)
  .limit(2)
  .toArray();

console.log(results);

이 코드는 queryVector와 가까운 벡터를 가진 row 2개를 반환한다.

반환 결과는 대략 이런 형태다.

[
  {
    id: 1,
    title: "첫 번째 문서",
    content: "LanceDB는 벡터 검색을 위한 데이터베이스입니다.",
    vector: [0.1, 0.2, 0.3],
    _distance: 0.0023
  },
  {
    id: 3,
    title: "세 번째 문서",
    content: "벡터 검색은 의미가 비슷한 문서를 찾는 데 사용됩니다.",
    vector: [0.2, 0.3, 0.4],
    _distance: 0.0312
  }
]

_distance는 검색 벡터와 데이터 벡터 사이의 거리다. 일반적으로 거리가 작을수록 더 유사하다고 보면 된다.

메타데이터 필터링

벡터 검색 결과를 특정 조건으로 제한할 수 있다.

예를 들어 type이 "guide"인 문서만 검색하려면 다음처럼 작성한다.

const results = await table
  .search(queryVector)
  .where("type = 'guide'")
  .limit(5)
  .toArray();

이를 위해 데이터 저장 시 메타데이터를 함께 넣는다.

await table.add([
  {
    id: 4,
    type: "guide",
    title: "LanceDB 사용법",
    content: "LanceDB는 로컬에서도 사용할 수 있습니다.",
    vector: [0.3, 0.2, 0.1],
  },
]);

메타데이터 필터링은 실제 앱에서 매우 중요하다. 예를 들어 문서 종류, 사용자 ID, 프로젝트 ID, 작성일 등을 기준으로 검색 범위를 좁힐 수 있다.

문서 청크 방법

긴 문서는 그대로 하나의 벡터로 만들기보다, 여러 개의 작은 조각으로 나누는 것이 좋다. 이 조각을 chunk라고 한다.

예를 들어 긴 문서 하나를 다음처럼 나눈다.

긴 문서
├─ chunk 1
├─ chunk 2
├─ chunk 3
└─ chunk 4

문서를 청크로 나누는 이유는 검색 정확도 때문이다.

긴 문서 전체를 하나의 벡터로 만들면 여러 주제가 하나의 벡터에 섞인다. 반면 문단이나 일정 길이 단위로 나누면, 검색어와 직접 관련 있는 부분을 더 정확히 찾을 수 있다.

글자 수 기준 청크 예시

function chunkText(text, chunkSize = 1000, overlap = 150) {
  const normalized = text
    .replace(/\\r\\n/g, "\\n")
    .replace(/\\n{3,}/g, "\\n\\n")
    .trim();

  const chunks = [];
  let start = 0;

  while (start < normalized.length) {
    const end = Math.min(start + chunkSize, normalized.length);
    const chunk = normalized.slice(start, end).trim();

    if (chunk.length > 0) {
      chunks.push(chunk);
    }

    if (end >= normalized.length) break;

    start = end - overlap;
  }

  return chunks;
}

사용 예시:

const text = `
LanceDB는 벡터 검색을 위한 데이터베이스입니다.

벡터 검색은 키워드가 아니라 의미 유사도를 기준으로 데이터를 찾습니다.

긴 문서는 여러 청크로 나누어 저장하는 것이 좋습니다.
`;

const chunks = chunkText(text, 100, 20);

console.log(chunks);

문단 기준 청크 예시

문서가 자연어 중심이라면 문단 기준으로 먼저 나누는 편이 더 좋다.

function chunkByParagraph(text, maxLength = 1000) {
  const paragraphs = text
    .replace(/\\r\\n/g, "\\n")
    .split(/\\n\\s*\\n/)
    .map((paragraph) => paragraph.trim())
    .filter(Boolean);

  const chunks = [];
  let current = "";

  for (const paragraph of paragraphs) {
    const next = current
      ? `${current}\\n\\n${paragraph}`
      : paragraph;

    if (next.length > maxLength && current) {
      chunks.push(current);
      current = paragraph;
    } else {
      current = next;
    }
  }

  if (current) {
    chunks.push(current);
  }

  return chunks;
}

임베딩 방법

LanceDB는 벡터를 저장하고 검색하는 DB다.

텍스트를 벡터로 바꾸는 임베딩 작업은 별도의 임베딩 모델이 필요하다.

흐름은 다음과 같다.

텍스트
↓
임베딩 모델
↓
벡터
↓
LanceDB 저장

예시로 로컬 Ollama 임베딩 API를 사용하면 다음처럼 작성할 수 있다.

async function embedText(text) {
  const response = await fetch("<http://localhost:11434/api/embeddings>", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "nomic-embed-text",
      prompt: text,
    }),
  });

  if (!response.ok) {
    throw new Error(`Embedding failed: ${response.status}`);
  }

  const data = await response.json();

  return data.embedding;
}

문서를 청크로 나눈 뒤 각 청크를 임베딩해서 LanceDB에 저장한다.

async function addDocument(table, document) {
  const chunks = chunkByParagraph(document.content);

  const rows = [];

  for (let index = 0; index < chunks.length; index++) {
    const content = chunks[index];
    const vector = await embedText(content);

    rows.push({
      id: `${document.id}-${index}`,
      documentId: document.id,
      chunkIndex: index,
      title: document.title,
      content,
      vector,
    });
  }

  await table.add(rows);
}

검색 흐름

검색할 때도 입력 문장을 먼저 임베딩해야 한다.

검색어
↓
임베딩 모델
↓
검색 벡터
↓
LanceDB vector search
↓
유사한 chunk 반환

예시:

async function searchDocuments(table, query) {
  const queryVector = await embedText(query);

  const results = await table
    .search(queryVector)
    .limit(5)
    .toArray();

  return results;
}

사용 예시:

const results = await searchDocuments(
  table,
  "LanceDB는 로컬에서 어떻게 사용할 수 있어?"
);

console.log(results);

전체 예시

아래는 LanceDB 연결, 테이블 생성, 문서 청크, 임베딩, 저장, 검색을 묶은 예시다.

import * as lancedb from "@lancedb/lancedb";

async function embedText(text) {
  const response = await fetch("<http://localhost:11434/api/embeddings>", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "nomic-embed-text",
      prompt: text,
    }),
  });

  if (!response.ok) {
    throw new Error(`Embedding failed: ${response.status}`);
  }

  const data = await response.json();
  return data.embedding;
}

function chunkByParagraph(text, maxLength = 1000) {
  const paragraphs = text
    .replace(/\\r\\n/g, "\\n")
    .split(/\\n\\s*\\n/)
    .map((paragraph) => paragraph.trim())
    .filter(Boolean);

  const chunks = [];
  let current = "";

  for (const paragraph of paragraphs) {
    const next = current
      ? `${current}\\n\\n${paragraph}`
      : paragraph;

    if (next.length > maxLength && current) {
      chunks.push(current);
      current = paragraph;
    } else {
      current = next;
    }
  }

  if (current) {
    chunks.push(current);
  }

  return chunks;
}

async function main() {
  const db = await lancedb.connect("./data/lancedb");

  const tableNames = await db.tableNames();

  let table;

  if (tableNames.includes("documents")) {
    table = await db.openTable("documents");
  } else {
    table = await db.createTable("documents", [
      {
        id: "sample-0",
        documentId: "sample",
        chunkIndex: 0,
        title: "sample",
        content: "sample",
        vector: Array(768).fill(0),
      },
    ]);
  }

  const document = {
    id: "doc-1",
    title: "LanceDB 소개",
    content: `
LanceDB는 벡터 검색을 위한 데이터베이스입니다.

벡터 검색은 텍스트의 키워드가 아니라 의미 유사도를 기준으로 데이터를 찾습니다.

긴 문서는 여러 청크로 나누어 저장하면 검색 정확도를 높일 수 있습니다.
    `,
  };

  const chunks = chunkByParagraph(document.content);

  const rows = [];

  for (let index = 0; index < chunks.length; index++) {
    const content = chunks[index];
    const vector = await embedText(content);

    rows.push({
      id: `${document.id}-${index}`,
      documentId: document.id,
      chunkIndex: index,
      title: document.title,
      content,
      vector,
    });
  }

  await table.add(rows);

  const query = "의미가 비슷한 문서를 검색하는 방법";
  const queryVector = await embedText(query);

  const results = await table
    .search(queryVector)
    .limit(3)
    .toArray();

  console.log(results);
}

main().catch(console.error);

요약

LanceDB 사용 흐름은 단순하게 보면 다음과 같다.

1. LanceDB 설치
2. 로컬 DB 경로에 connect
3. table 생성
4. 문서를 chunk로 분리
5. 각 chunk를 embedding
6. content + vector + metadata 저장
7. 검색어도 embedding
8. table.search(queryVector)로 유사 문서 검색

핵심은 이것이다.

LanceDB = 벡터를 저장하고 검색하는 DB
임베딩 모델 = 텍스트를 벡터로 바꾸는 도구
청크 = 긴 문서를 검색하기 좋게 나눈 조각

LanceDB 자체는 검색 저장소이고, 임베딩 품질은 사용하는 임베딩 모델에 크게 좌우된다.

LanceDB 학습

프로젝트에서 사용하기 위한 LanceDB 정리글