Skip to content

Qdrant 페이로드와 필터링 (Payload)

벡터만 저장하면 "가장 가까운 문서"는 찾을 수 있지만, "회사 A 문서 중에서"처럼 조건을 좁혀 검색하긴 어려워요. Qdrant는 벡터 옆에 페이로드(Payload) 라고 부르는 메타데이터를 JSON으로 함께 저장하고, 그 값으로 검색 범위를 미리 좁히는 필터링을 지원합니다. 이 페이지는 소스 문서 Qdrant Payload 를 바탕으로 설명해요.

개요

기능적으로 보면 페이로드는 "벡터와 함께 저장되는 보조 정보"에요. JSON으로 표현할 수 있는 값이라면 무엇이든 담을 수 있고, 그 값들은 검색 시 조건으로 사용돼 의미 유사도 위에 나만의 규칙을 얹을 수 있어요. 예를 들어 "이 채팅방에서, 이 태그가 붙은 문서만"처럼 말이죠.

핵심 개념

페이로드 타입

Qdrant는 필터링에서 쓸 수 있는 값 타입을 구분해요. 저장된 값의 타입이 필터 조건 타입과 맞지 않으면 그 조건은 만족하지 않은 것으로 처리됩니다.

  • integer — 64비트 정수 (-9223372036854775808 ~ 9223372036854775807)
  • float — 64비트 부동소수점
  • bool — true / false
  • keyword — 문자열
  • geo — 위도·경도 좌표 (lon, lat 두 필드를 가진 객체)
  • datetime — RFC 3339 형식의 날짜·시간 (버전 1.8.0부터)
  • uuid — UUID 값. 내부적으로 숫자(128비트)로 저장해 RAM을 아끼고 검색을 빠르게 합니다 (버전 1.11.0부터)

주의할 점이 하나 있어요. 배열(같은 타입의 여러 값)에 필터를 걸면 배열 안의 값 중 하나라도 조건을 만족하면 통과됩니다.

페이로드가 있는 점 만들기

페이로드는 점(point)을 저장(upsert)할 때 벡터와 함께 넣습니다.

{
  "points": [
    { "id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": { "city": "Berlin", "price": 1.99 } },
    { "id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": { "city": ["Berlin", "London"], "price": 1.99 } }
  ]
}

필터링 동작

검색 시 filter로 조건을 주면, 벡터 계산 전에 이 조건을 통과한 점들로 범위를 좁힌 뒤 유사도 검색을 수행합니다. 문자열에 범위(range) 조건을 거는 식으로 타입이 안 맞으면 결과가 비어 나오는 걸 볼 수 있어요.

실제 적용 (데이터스케쳐스)

  • 테넌트 필터 — 페이로드에 테넌트(회사·팀) 식별자를 담고, 검색 시 그것으로 범위를 한정해 멀티테넌트 격리를 지킵니다.
  • 문서 메타데이터 — 문서 id·종류·태그·날짜·출처 위치를 페이로드에 저장해, "정책 문서 중 최근 것"처럼 조건을 좁혀 검색합니다.
  • 비용·지연 절감 — 벡터 계산 전에 필터로 후보를 줄여, 검색 비용과 지연을 낮춥니다.
  • 근거 추적 — 검색 결과 점의 페이로드에서 원본 문서 위치를 꺼내, 답의 근거를 추적 가능하게 합니다.

더 알아보기