역색인
역색인 (Inverted index)
Weaviate의 **역색인(Inverted index)**은 텍스트 검색과 필터링을 효율적으로 만들어주는 핵심 자료 구조예요. 역색인은 용어(토큰)로부터 그 용어를 담고 있는 객체로 되돌아가는 매핑을 만듭니다. 덕분에 Weaviate는 검색 쿼리에서 특정 용어를 가진 객체가 무엇인지, 어떤 조건에 맞는지 빠르게 찾아낼 수 있어요.
역색인은 키워드 검색과 필터링, 범위 쿼리 같은 검색 기능을 지원합니다. 속성에 역색인을 켜고 인덱싱 동작과 토큰화 전략을 제어하는 여러 파라미터를 조정할 수 있어요. 이 파라미터를 잘 설정하는 게 검색 성능과 저장 효율을 모두 최적화하는 관건입니다.
속성 수준에서 역색인 켜기
역색인은 속성 수준의 파라미터로 켜고 끌 수 있습니다.
index_filterable— 속성이 where 필터에 사용될 수 있는지 제어합니다.true면 필터링을 위해 속성 값을 인덱싱해 효율적인 필터링을 지원해요. 필터링이 필요 없는 속성은 꺼서 저장 공간을 아낄 수 있습니다.index_searchable— 속성이 키워드 검색 쿼리에 참여하는지 결정합니다.true면 속성 텍스트를 토큰화·인덱싱해 검색에 사용할 수 있어요. 검색에 쓰이지 않아도 되는 속성은false로 두면 성능이 좋아집니다.index_range_filters— 숫자·날짜 속성에 대해 초과·미만 같은 범위 필터링을 가능하게 합니다. 켜면 효율적인 범위 쿼리를 위한 추가 인덱스 구조가 만들어집니다.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
"Article",
# 다른 설정은 생략
properties=[
Property(
name="title",
data_type=DataType.TEXT,
index_filterable=True,
index_searchable=True,
),
Property(
name="chunk",
data_type=DataType.TEXT,
index_filterable=True,
index_searchable=True,
),
Property(
name="chunk_number",
data_type=DataType.INT,
index_range_filters=True,
),
],
)
컬렉션 수준의 역색인 파라미터
역색인 파라미터는 한 컬렉션 전체의 역색인 동작을 제어합니다. 이 값들은 검색 순위 알고리즘, null 값 처리, 타임스탬프 인덱싱에 영향을 줍니다.
bm25_b— BM25 랭킹에서 문서 길이에 의한 정규화 정도를 제어합니다. 0~1 값을 가지며, 0이면 길이 정규화 없음, 1이면 완전 정규화를 뜻합니다. 높을수록 짧은 문서에 유리하게 작용합니다.bm25_k1— BM25에서 용어 빈도 포화를 제어합니다. 높을수록 용어 빈도가 더 중요해지고, 낮추면 점수에 미치는 용어 빈도 영향이 줄어듭니다.index_null_state— null 값이 인덱싱되는지 결정합니다. 켜면 특정 속성에 null 값을 가진 객체를 필터할 수 있습니다.index_property_length— 텍스트 속성의 길이가 인덱싱되는지 제어합니다. 켜면 텍스트 길이 기반 필터링이 가능해지고 일부 랭킹 알고리즘이 개선됩니다.index_timestamps— 객체의 생성·수정 타임스탬프를 인덱싱해 필터·정렬을 가능하게 합니다.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
"Article",
# 다른 설정은 생략
inverted_index_config=Configure.inverted_index(
bm25_b=0.7,
bm25_k1=1.25,
index_null_state=True,
index_property_length=True,
index_timestamps=True,
),
)
역색인 삭제
속성에서 역색인을 삭제하는 것은 파괴적 작업입니다 — 인덱스 데이터가 디스크에서 제거되기 때문이에요. 다시 쓰려면 재생성해야 합니다. 삭제 가능한 인덱스 타입은 searchable, filterable, rangeFilters입니다.
collection = client.collections.get("Article")
# "title" 속성에서 searchable 역색인 삭제
collection.config.delete_property_index("title", "searchable")
# "title" 속성에서 filterable 역색인 삭제
collection.config.delete_property_index("title", "filterable")
# "chunk_number" 속성에서 범위 필터 인덱스 삭제
collection.config.delete_property_index("chunk_number", "rangeFilters")
토큰화 방법
토큰화는 텍스트 콘텐츠를 인덱싱·검색 가능한 개별 용어로 나누는 방식을 결정합니다. 각 속성에 토큰화 방법을 개별적으로 설정할 수 있어요.
word— 기본값. 공백과 문장부호로 텍스트를 나누고 소문자로 변환합니다. 개별 단어를 매칭하는 일반 텍스트 검색에 가장 적합합니다.lowercase— 공백으로만 나눈 뒤 각 토큰을 소문자화합니다.word토큰화가 제거할&,@,_같은 기호를 보존합니다. 코드 스니펫이나 이메일 주소처럼 문장부호가 의미 있는 대소문자 무시 매칭에 좋아요.whitespace— 공백 문자로만 나눠 문장부호와 대소문자를 보존합니다. 문장부호가 검색에 의미 있는 경우에 좋습니다.field— 속성 값 전체를 처리 없이 단일 토큰으로 취급합니다. ID, 이메일 주소, URL 같은 완전한 필드 값의 정확 매칭에 사용합니다.trigram— 텍스트를 겹치는 3글자 시퀀스로 나눕니다. 오타나 부분 매칭을 다루는 퍼지 매칭에 유용합니다.gse— 중국어·일본어 텍스트용 언어 인식 토큰화입니다. 기본 비활성이며ENABLE_TOKENIZER_GSE환경 변수로 켭니다. 한국어 텍스트는kagome_kr옵션을 씁니다.
지원되는 전체 토큰화 목록(kagome_ja, kagome_kr, 속성별 텍스트 분석기 옵션 포함)은 토큰화 레퍼런스에서 볼 수 있습니다.
from weaviate.classes.config import Configure, Property, DataType, Tokenization
client.collections.create(
"Article",
vector_config=Configure.Vectors.text2vec_cohere(),
properties=[
Property(
name="title",
data_type=DataType.TEXT,
tokenization=Tokenization.LOWERCASE, # "lowercase" 토큰화 사용
description="The title of the article.", # (선택) 설명
),
Property(
name="body",
data_type=DataType.TEXT,
tokenization=Tokenization.WHITESPACE, # "whitespace" 토큰화 사용
),
],
)