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