텍스트 입력란Compatible with Milvus 3.0.x

AI 검색 애플리케이션에서 벡터 검색은 의미적으로 유사한 엔티티를 찾는 데 도움이 되지만, 애플리케이션은 종종 각 일치 항목의 원본 텍스트도 필요로 합니다. LLM이나 에이전트는 해당 텍스트를 컨텍스트로 활용하여 내용을 읽거나, 인용하거나, 요약하거나, 프롬프트에 결과를 포함시킬 수 있습니다.

Milvus는 긴 원본 텍스트를 엔티티와 함께 직접 저장하기 위해 ` TEXT ` 스칼라 필드 유형을 제공합니다. 일반적인 값으로는 문장, 긴 문서, 기사 본문, 티켓 및 로그 등이 있습니다. 고정된 ` max_length`을 요구하는 ` VARCHAR`과 달리, ` TEXT `은 컬렉션 스키마에서 최대 바이트 길이를 설정할 필요가 없습니다.

TEXT 필드를 정의하려면 datatype 을 DataType.TEXT 로 설정하십시오.

common.storage.useLoonFFI 기본값은 false 이며, 이는 Storage V3가 기본적으로 비활성화되어 있음을 의미합니다. TEXT 필드가 포함된 컬렉션을 생성하기 전에 이 매개변수를 true 로 설정해야 합니다. 그렇지 않으면 Milvus가 컬렉션 스키마를 거부합니다.

schema.add_field(
    field_name="content",
    datatype=DataType.TEXT,
)

필드가 정의된 후에는 각 엔티티가 해당 필드에 문자열 값을 포함할 수 있습니다. TEXT 값은 다른 스칼라 필드와 마찬가지로 삽입할 수 있으며, output_fields 에 필드를 나열하여 쿼리 또는 검색 결과에서 반환할 수 있습니다.

제한 사항

• TEXT 필드는 기본 필드, 파티션 키 또는 클러스터링 키로 사용할 수 없습니다.
• TEXT ARRAY 필드의 요소 유형으로 사용할 수 없으며, 여기에는 내의 스칼라 하위 필드도 포함됩니다. StructArray
• Milvus 3.0.0에서 TEXT 필드는 기본값을 지원하지 않습니다.
• Milvus 3.0.0에서는 외부 컬렉션에서 TEXT 필드가 지원되지 않습니다.
• 사용자는 TEXT 필드에 스칼라 인덱스를 생성할 수 없습니다. enable_match=True 인 경우, Milvus는 텍스트 매칭을 위해 시스템에서 관리하는 텍스트 인덱스를 구축합니다. 이 내부 인덱스는 사용자가 생성한 스칼라 인덱스가 아닙니다.
• 일반 스칼라 필터 연산자는 TEXT 필드에 직접 적용할 수 없습니다. 여기에는 == 및 != 와 같은 비교 연산자, >, >=, <, <= 와 같은 범위 연산자, IN, LIKE, 정규식 연산자(=~ 및 !~), 그리고 IS NULL 또는 IS NOT NULL 가 포함됩니다. 분석된 용어로 필터링하려면 enable_analyzer=True 및 enable_match=True 를 사용하여 필드를 정의하고, TEXT_MATCH 또는 TEXT_MATCH_FUZZY 를 사용하십시오. 관련도 순위 기반 전체 텍스트 검색의 경우 BM25를 사용하십시오.
• Milvus 3.0.0에서는 컬렉션 생성 시 TEXT 필드를 입력으로 사용하는 BM25 또는 MinHash 함수를 반드시 정의해야 합니다. 기존 컬렉션이 비어 있더라도 add_function_field 또는 AlterCollectionSchema 를 통해 나중에 추가할 수 없습니다. Milvus는 저장된 TEXT 값을 기반으로 함수 출력을 소급 적용할 수 없기 때문입니다. 기존 컬렉션에 이러한 함수를 추가하려면 ‘ VARCHAR ’ 입력 필드를 사용하거나, 해당 함수가 스키마에 포함된 상태로 컬렉션을 다시 생성해야 합니다. 함수 및 생성된 벡터 필드 추가에 대한 자세한 내용은 ‘Alter Collection Schema’를 참조하십시오.
• 텍스트 임베딩 함수(Text Embedding Functions)도 컬렉션 생성 시 정의되어야 합니다. Milvus 3.0.0은 런타임 시 이러한 함수를 추가하는 기능을 지원하지 않습니다.

TEXT 또는 VARCHAR

TEXT VARCHAR 는 모두 문자열 값을 저장하지만, 지원하는 애플리케이션 요구 사항은 서로 다릅니다. 엔티티를 식별, 분류 또는 필터링하는 짧고 범위가 제한된 메타데이터에는 ` `를 사용하십시오. LLM이나 에이전트가 내용을 읽고, 인용하고, 요약하거나 프롬프트를 생성하는 데 충분한 맥락을 제공하는 긴 소스 콘텐츠에는 ` `를 사용하십시오. VARCHAR TEXT

측면	VARCHAR	TEXT
가장 적합한 용도	title, tag, category 또는 external_id 과 같이 엔티티를 식별, 분류 또는 필터링하는 데 사용되는 짧은 메타데이터.	content, passage, article_body, log_message 등과 같이 LLM 또는 에이전트 워크플로우에서 사용되는 긴 소스 콘텐츠.
길이 설정	max_length 가 필요하며, 이는 필드가 저장할 수 있는 최대 바이트 수를 정의합니다. 최대 값은 65,535 바이트입니다. 값이 이 한도를 초과할 수 있는 경우 TEXT 를 사용하십시오.	max_length 가 필요하지 않으므로, 스키마에 텍스트 값에 대한 고정된 바이트 제한을 지정할 필요가 없습니다.
저장 동작	각 값은 필드에 구성된 max_length 내에 저장됩니다.	크기가 더 큰 텍스트 값의 경우 자동 저장소 선택 기능을 사용합니다. 자세한 내용은 Milvus가 대용량 TEXT 값을 저장하는 방법을 참조하십시오.
기본 필드 지원	주 필드로 사용할 수 있습니다.	주 필드로 사용할 수 없습니다.
필터링	category == "news" 이나 tag in ["ai", "database"] 과 같이 필터 표현식에 포함되어야 하는 짧은 문자열 메타데이터에 사용합니다.	일반 스칼라 필터 연산자는 지원하지 않습니다. 분석된 용어 필터링의 경우 일치 기능이 활성화된 텍스트 연산자를 사용하거나, 관련도 순위가 매겨진 전체 텍스트 검색의 경우 BM25를 사용하십시오.

VARCHAR 필드에 대한 자세한 내용은 VarChar 필드를 참조하십시오.

Milvus가 대용량 TEXT 값을 저장하는 방법

확장하여 작동 방식 확인

엔티티를 삽입할 때, TEXT 필드에 입력한 문자열이 TEXT 값이 됩니다. Milvus는 해당 값의 크기를 dataNode.text.inlineThreshold(기본값은 65,536 바이트)와 비교한 다음, 두 가지 내부 저장 경로 중 하나를 선택합니다.

대용량 텍스트 저장

• 인라인 저장: TEXT 값이 dataNode.text.inlineThreshold 보다 작으면, Milvus는 원본 텍스트 값을 TEXT 필드의 data에 직접 저장합니다.
• LOB 저장: ` TEXT ` 값이 ` dataNode.text.inlineThreshold` 이상인 경우, Milvus는 해당 값을 대용량 객체로 간주하고 원본 텍스트를 MinIO와 같은 객체 저장소에 별도로 저장합니다. ` TEXT ` 필드 데이터에는 별도로 저장된 텍스트에 대한 내부 참조가 저장됩니다. 쿼리 또는 검색 결과에서 ` TEXT ` 필드가 요청되면, Milvus는 해당 참조를 사용하여 원본 텍스트를 검색하고 반환합니다.

이러한 스토리지 선택은 내부적으로 이루어집니다. Milvus가 어떤 스토리지 경로를 사용하든 상관없이 TEXT 필드에 대한 삽입, 쿼리 및 검색은 동일한 방식으로 수행됩니다. 임계값이나 관련 스토리지, 압축 및 가비지 컬렉션 동작을 조정하려면 dataNode 관련 구성 및 dataCoord 관련 구성을 참조하십시오.

배포 환경에서 오브젝트 스토리지를 사용하는 경우, 큰 TEXT 값은 lobs/... 와 같은 경로 아래에 Milvus가 관리하는 오브젝트로 표시될 수 있습니다. 이러한 오브젝트는 구현 세부 사항이므로 수동으로 이동, 복사 또는 삭제해서는 안 됩니다. 엔티티를 삭제하거나, 파티션을 드롭하거나, 데이터를 압축한 후에도, Milvus 가비지 컬렉션이 안전 기간이 지난 후 참조되지 않는 대용량 객체 데이터를 제거해야만 객체 스토리지 사용량이 감소할 수 있습니다.

TEXT 의 일반적인 용도는 BM25를 활용한 전체 텍스트 검색입니다. 이 패턴에서 TEXT 필드는 원본 소스 콘텐츠를 저장하며, BM25는 텍스트를 분석하여 키워드 기반 일치 항목을 순위 매기기 위한 스파스 벡터를 생성합니다. 그런 다음 검색 결과는 일치하는 TEXT 값을 LLM 또는 에이전트 워크플로우의 컨텍스트로 반환할 수 있습니다. 다음 예제는 TEXT 필드를 BM25의 입력 필드로 사용하는 방법을 보여줍니다. 전체 텍스트 검색 개념 및 쿼리 옵션에 대한 자세한 내용은 전체 텍스트 검색을 참조하십시오.

1단계: TEXT 필드가 포함된 컬렉션 생성

다음 예제는 소스 콘텐츠를 위한 TEXT 필드와 BM25에서 생성된 스파스 벡터를 위한 스파스 벡터 필드를 포함하는 컬렉션을 생성합니다. BM25 함수는 content 의 토큰화된 텍스트를 sparse 에 저장된 스파스 벡터로 변환합니다.

BM25 전체 텍스트 검색을 사용하려면 입력 TEXT 필드의 값을 enable_analyzer=True 로 설정해야 합니다.

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")
COLLECTION_NAME = "text_bm25_collection"

if client.has_collection(COLLECTION_NAME):
    client.drop_collection(COLLECTION_NAME)

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(
    field_name="content",
    datatype=DataType.TEXT,
    enable_analyzer=True,
)
schema.add_field(field_name="sparse", datatype=DataType.SPARSE_FLOAT_VECTOR)

bm25_function = Function(
    name="content_bm25",
    input_field_names=["content"],
    output_field_names=["sparse"],
    function_type=FunctionType.BM25,
)
schema.add_function(bm25_function)

2단계: 스파스 벡터 인덱스 생성

BM25 함수에 의해 생성된 스파스 벡터 필드에 인덱스를 생성합니다. 메트릭 유형은 BM25 로 설정되어야 합니다.

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="sparse",
    index_type="SPARSE_INVERTED_INDEX",
    metric_type="BM25",
    params={
        "inverted_index_algo": "DAAT_MAXSCORE",
        "bm25_k1": 1.2,
        "bm25_b": 0.75,
    },
)

client.create_collection(
    collection_name=COLLECTION_NAME,
    schema=schema,
    index_params=index_params,
)

3단계: TEXT 데이터 삽입

TEXT 필드에 텍스트를 직접 입력합니다. sparse 필드에는 값을 입력하지 마십시오. Milvus는 content 에 BM25 함수를 적용하여 내부적으로 스파스 벡터를 생성합니다.

data = [
    {
        "id": 1,
        "content": "Milvus stores vector embeddings and scalar fields in collections. It supports vector search, full text search, and metadata filtering for retrieval applications.",
    },
    {
        "id": 2,
        "content": "Long documents are often split into passages before embedding. Store each passage in a TEXT field so search results can return the source text.",
    },
    {
        "id": 3,
        "content": "Operational logs and support tickets often contain long natural-language text. TEXT fields can store these values without a fixed max_length setting.",
    },
]

client.insert(collection_name=COLLECTION_NAME, data=data)
client.load_collection(collection_name=COLLECTION_NAME)

4단계: BM25 전체 텍스트 검색 수행

원본 쿼리 텍스트를 검색 데이터로 사용하여 스파스 벡터 필드에 대해 검색합니다. Milvus는 쿼리 텍스트를 스파스 벡터로 변환하고, BM25를 사용하여 일치 항목을 순위 매긴 후, 요청된 TEXT 필드를 output_fields 에 반환합니다.

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["how does Milvus store source text for retrieval"],
    anns_field="sparse",
    limit=2,
    output_fields=["content"],
)

5단계: 반환된 TEXT 값 읽기

각 검색 결과에는 BM25 점수와 원본 TEXT 값이 포함됩니다.

for hit in results[0]:
    print(f"id: {hit['id']}, score: {hit['distance']}")
    print(hit["entity"]["content"])

BM25 함수, 스파스 벡터 인덱스 및 전체 텍스트 검색용 쿼리 구문에 대한 자세한 내용은 전체 텍스트 검색을 참조하십시오.