AI

BM25 검색

Table별 bm25 엔드포인트로 키워드(BM25) 검색과 모델 재정렬(Rerank)을 함께 사용하는 방법을 설명합니다.

BM25 검색은 Table별 bm25 엔드포인트로 키워드 기반 검색을 실행하고, 그 결과를 모델이 질문과의 관련도로 다시 정렬(Rerank)하는 기능입니다. 이 가이드를 완료하면 정확한 이름·코드·용어가 들어간 쿼리로 Contents를 점수와 함께 조회하고, 재정렬 여부와 후보 수를 직접 제어할 수 있습니다.

사전 조건:

  • 검색할 Table의 Vector 동기화가 완료되어 있어야 합니다. BM25는 동기화 과정에서 만들어진 텍스트 조각을 검색합니다.
  • 시크릿 Project API Key(sk-proj_…)가 필요합니다. 검색은 POST 요청이라 게시용 키로는 호출할 수 없습니다. 브라우저가 아닌 서버에서 호출하세요.
  • 쿼리를 임베딩하지 않으므로 API.EMBEDDINGS.TOKENS는 소비되지 않습니다. 재정렬(rerank: true)에 사용된 모델 토큰은 AI.ASK.TOKENS로 집계됩니다.

동작 방식

  1. BM25 점수 계산 — 쿼리를 단어 단위로 나눕니다. 한국어 단어는 글자 2개 단위(bigram)도 함께 사용하므로 "환불정책"으로 "환불 정책이 어떻게 되나요"를 찾을 수 있습니다. 각 텍스트 조각은 쿼리 단어가 얼마나 들어 있는지(빈도), 그 단어가 전체에서 얼마나 희귀한지(IDF), 조각이 얼마나 긴지(길이 정규화)를 바탕으로 점수를 받습니다. Contents의 점수는 조각 점수 중 최댓값이며, 가장 높은 Contents가 1이 되도록 정규화합니다(bm25_score).
  2. 재정렬(Rerank) — 상위 candidates개의 Contents를 모델에 전달해 각 항목이 쿼리에 실제로 답하는 정도를 0–1로 평가합니다. 이 값이 최종 score입니다. rerank: false이면 이 단계를 건너뛰고 bm25_score가 그대로 score가 됩니다.
  3. 결과 선택 — threshold 미만을 제외하고 score가 높은 순으로 최대 count개를 반환합니다.

어떤 검색을 써야 할까요?

상황 추천
상품명, 모델 번호, 고유 명사, 오류 코드 검색 BM25 검색
표현이 달라도 뜻이 같은 내용을 찾아야 할 때 Embeddings 검색
키워드는 맞지만 답이 아닌 결과를 걸러야 할 때 BM25 검색 + rerank: true (기본값)
비용을 최소화한 빠른 키워드 검색 BM25 검색 + rerank: false

엔드포인트

POST /v1/{projectId}/tables/{tableSlug}/bm25

{tableSlug}에는 Table의 slug를 사용합니다. slug가 없는 Table은 Table ID를 사용합니다.

요청 본문

필드 타입 필수 기본값 설명
query string 필수 - 검색 쿼리 텍스트. 단어와 한글 bigram을 동기화된 텍스트와 대조합니다
count integer - 5 반환할 최대 결과 개수 (1–100)
threshold number - 0 결과에 포함할 최소 score (0–1). rerank가 켜져 있으면 재정렬 점수, 꺼져 있으면 정규화된 BM25 점수에 적용됩니다
rerank boolean - true BM25 후보를 모델로 재정렬합니다. false이면 AI 토큰을 사용하지 않습니다
candidates integer - 20 재정렬에 넘길 BM25 상위 Contents 수 (1–100). rerank: false이면 무시됩니다
k1 number - 1.2 BM25 단어 빈도 포화 계수 (0–3). 클수록 쿼리 단어가 반복된 텍스트에 더 높은 점수를 줍니다
b number - 0.75 BM25 길이 정규화 계수 (0–1). 0이면 길이를 무시하고, 1이면 긴 텍스트를 최대로 불리하게 평가합니다

k1과 b는 대부분 기본값으로 충분합니다. 짧은 제목 위주의 Table이면 b를 낮추고, 긴 본문 위주라면 기본값을 유지하세요.


요청 예제

curl -X POST "https://api.onttle.com/v1/{projectId}/tables/products/bm25" \
  -H "Authorization: Bearer $ONTTLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "에어팟 프로 2세대 케이스",
    "count": 5,
    "rerank": true,
    "candidates": 20
  }'

재정렬 없이 키워드만 검색

curl -X POST "https://api.onttle.com/v1/{projectId}/tables/products/bm25" \
  -H "Authorization: Bearer $ONTTLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SKU-20481",
    "count": 3,
    "rerank": false
  }'

TypeScript 예제

const res = await fetch(
  'https://api.onttle.com/v1/{projectId}/tables/products/bm25',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ONTTLE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: '에어팟 프로 2세대 케이스',
      count: 5,
      threshold: 0.5,
    }),
  },
)

const { list, reranked } = await res.json()
// list: score 순으로 정렬된 Contents 목록 (score, bm25_score 포함)
// reranked: 재정렬이 실제로 실행되었는지 여부

응답 형식

결과는 score가 높은 순으로 정렬된 list 배열로 반환됩니다. 각 항목에는 Contents 필드와 함께 두 가지 점수가 포함됩니다.

{
  "list": [
    {
      "id": "cnt_01hxk2",
      "slug": "airpods-pro-2-case",
      "score": 0.92,
      "bm25_score": 1,
      "data": {
        "name": "AirPods Pro 2세대 실리콘 케이스"
      }
    }
  ],
  "reranked": true
}
필드 타입 설명
list object[] 일치하는 Contents 목록
score number 최종 점수 (0–1). 재정렬 관련도이며, rerank: false이면 bm25_score와 같습니다
bm25_score number 정규화된 BM25 점수 (0–1). 키워드가 가장 잘 일치하는 항목이 1입니다
reranked boolean 재정렬 실행 여부. rerank: false이거나 재정렬이 실패해 BM25 점수로 응답한 경우 false입니다

엔드포인트 활성화 관리

Table을 생성하면 bm25 엔드포인트는 기본으로 활성화됩니다. Project 좌측 메뉴의 API에서 해당 Table의 키워드(BM25)로 검색 페이지로 이동해 우측 상단 토글로 활성/비활성을 변경할 수 있습니다. Table 설정의 API 엔드포인트 목록에서도 같은 토글을 제공합니다.


문제 해결

증상 확인 사항
검색 결과가 없음 Vector 동기화 상태가 SUCCESS인지 확인, 쿼리에 동기화된 텍스트에 실제로 들어 있는 단어가 있는지 확인, threshold를 낮춤
키워드는 맞지만 답이 아님 rerank: true인지 확인하고 candidates를 늘려 재정렬 대상에 더 많은 후보를 포함
응답이 느림 candidates를 줄이거나 rerank: false로 재정렬 생략
reranked가 false rerank: false로 요청했거나 재정렬 모델 호출이 실패한 경우입니다. 후자는 BM25 점수로 자동 대체되며 서버 로그에 기록됩니다
요청이 거부됨 엔드포인트 활성화 토글과 시크릿 키(sk-proj_…) 사용 여부 확인

다음 단계

  • Embeddings 검색 — 의미 기반 검색을 사용합니다.
  • Chats — search_type: "bm25"로 채팅의 근거 콘텐츠를 BM25 + Rerank로 검색합니다.
  • 사용량 및 과금 — 재정렬 토큰이 기록되는 AI.ASK.TOKENS 메트릭을 확인합니다.