허깅 페이스 TEICompatible with Milvus 2.6.x

Hugging Face 텍스트 임베딩 추론(TEI) 은 텍스트 임베딩 모델을 위해 특별히 설계된 고성능 추론 서버입니다. 이 가이드는 효율적인 텍스트 임베딩 생성을 위해 Milvus와 함께 Hugging Face TEI를 사용하는 방법을 설명합니다.

TEI는 다음과 같은 허깅 페이스 허브의 다양한 텍스트 임베딩 모델과 함께 작동합니다:

• BAAI/bge-* 시리즈

• 문장 트랜스포머/* 시리즈

• E5 모델

• GTE 모델

• 그리고 더 많은 모델

TEI 배포

Milvus에 TEI 기능을 구성하기 전에 TEI 서비스가 실행 중이어야 합니다. Milvus는 TEI 배포를 위해 두 가지 접근 방식을 지원합니다:

표준 배포(외부)

Hugging Face의 공식 방법을 사용하여 독립형 서비스로 TEI를 배포할 수 있습니다. 이 접근 방식을 사용하면 TEI 서비스를 최대한 유연하게 제어할 수 있습니다.

Docker 또는 기타 방법을 사용하여 TEI를 배포하는 방법에 대한 자세한 지침은 Hugging Face 텍스트 임베딩 추론 공식 문서를 참조하세요.

배포 후에는 Milvus에서 TEI 기능을 사용할 때 필요하므로 TEI 서비스 엔드포인트(예: http://localhost:8080)를 기록해 두세요.

Milvus 헬름 차트 배포(통합)

쿠버네티스 환경의 경우, Milvus는 헬름 차트를 통해 통합 배포 옵션을 제공합니다. 이렇게 하면 Milvus와 함께 TEI를 배포하고 구성하여 프로세스를 간소화할 수 있습니다.

밀버스 헬름 배포에서 TEI를 활성화하려면 다음과 같이 하세요:

1. TEI를 사용하도록 values.yaml을 구성한다:

   tei:
     enabled: true
     image:
       repository: ghcr.io/huggingface/text-embeddings-inference
       tag: "1.7" # Modify based on hardware
     model: "BAAI/bge-large-en-v1.5" # Modify based on requirements
     # revision: "main"
     # hfTokenSecretName: "my-huggingface-token-secret"
     # apiKey: "your_secure_api_key"
     # apiKeySecret:
     #   name: "my-tei-api-key-secret"
     #   key: "api-key"
     resources:
       requests:
         cpu: "1"
         memory: "4Gi"
         # nvidia.com/gpu: "1" # For GPU
       limits:
         cpu: "2"
         memory: "8Gi"
         # nvidia.com/gpu: "1" # For GPU
     extraArgs: []
   
   

2. Milvus 배포 또는 업그레이드:

   helm install my-release milvus/milvus -f values.yaml -n <your-milvus-namespace>
   # or
   helm upgrade my-release milvus/milvus -f values.yaml --reset-then-reuse-values -n <your-milvus-namespace>
   

   헬름 차트 배포를 사용하는 경우, TEI 서비스는 쿠버네티스 클러스터 내에서 http://my-release-milvus-tei:80 (릴리스 이름 사용)에서 액세스할 수 있습니다. 이것을 TEI 함수 구성의 엔드포인트로 사용하세요.

Milvus에서 구성

TEI 서비스를 배포한 후, TEI 임베딩 함수를 정의할 때 해당 엔드포인트를 제공해야 합니다. 대부분의 경우 Milvus에서 TEI는 기본적으로 활성화되어 있으므로 추가 구성이 필요하지 않습니다.

그러나 API 키 인증(--api-key 플래그)을 사용하여 TEI 서비스를 배포한 경우에는 이 키를 사용하도록 Milvus를 구성해야 합니다:

1. credential 섹션에서 API 키를 정의하세요:

   # milvus.yaml
   credential:
     tei_key:  # You can use any label name
       apikey: <YOUR_TEI_API_KEY>
   

2. milvus.yaml에서 자격 증명을 참조합니다:

   function:
     textEmbedding:
       providers:
         tei:
           credential: tei_key      # ← choose any label you defined above
           enable: true # enabled by default. no action required.
   

임베딩 기능 사용

TEI 서비스가 구성되면 다음 단계에 따라 임베딩 함수를 정의하고 사용하세요.

1단계: 스키마 필드 정의

임베딩 함수를 사용하려면 특정 스키마로 컬렉션을 만듭니다. 이 스키마에는 최소 3개의 필수 필드가 포함되어야 합니다:

• 컬렉션의 각 엔티티를 고유하게 식별하는 기본 필드.

• 임베드할 원시 데이터를 저장하는 스칼라 필드.

• 함수가 스칼라 필드에 대해 생성할 벡터 임베딩을 저장하기 위해 예약된 벡터 필드.

다음 예에서는 텍스트 데이터를 저장하는 스칼라 필드( "document" ) 1개와 함수 모듈에서 생성할 임베딩을 저장하는 벡터 필드( "dense_vector" ) 1개가 있는 스키마를 정의합니다. 선택한 임베딩 모델의 출력과 일치하도록 벡터 차원(dim)을 설정하는 것을 잊지 마세요.

from pymilvus import MilvusClient, DataType, Function, FunctionType, CollectionSchema, FieldSchema

# Assume you have connected to Milvus
# client = MilvusClient(uri="http://localhost:19530")

# 1. Create Schema
schema = MilvusClient.create_schema()

# 2. Add fields
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=9000) # Store text data
# IMPORTANT: Set dim to exactly match the TEI model's output dimension
schema.add_field("dense_vector", DataType.FLOAT_VECTOR, dim=1024) # Store embedding vectors (example dimension)

2단계: 스키마에 임베딩 함수 추가하기

Milvus의 함수 모듈은 스칼라 필드에 저장된 원시 데이터를 임베딩으로 자동 변환하여 명시적으로 정의된 벡터 필드에 저장합니다.

아래 예는 스칼라 필드 "document" 를 임베딩으로 변환하여 결과 벡터를 앞서 정의한 "dense_vector" 벡터 필드에 저장하는 함수 모듈(tei_func)을 추가한 것입니다.

임베딩 함수를 정의한 후에는 컬렉션 스키마에 추가합니다. 이렇게 하면 Milvus가 지정된 임베딩 함수를 사용하여 텍스트 데이터의 임베딩을 처리하고 저장하도록 지시합니다.

# 3. Define TEI embedding function
text_embedding_function = Function(
    name="tei_func",                            # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,   # Indicates a text embedding function
    input_field_names=["document"],             # Scalar field(s) containing text data to embed
    output_field_names=["dense_vector"],        # Vector field(s) for storing embeddings
    params={                                    # TEI specific parameters (function-level)
        "provider": "TEI",                      # Must be set to "TEI"
        "endpoint": "http://your-tei-service-endpoint:80", # Required: Points to your TEI service address
        # Optional parameters:
        # "truncate": "true",                   # Optional: Whether to truncate long input (default false)
        # "truncation_direction": "right",      # Optional: Truncation direction (default right)
        # "max_client_batch_size": 64,          # Optional: Client max batch size (default 32)
        # "ingestion_prompt": "passage: ",      # Optional: (Advanced) Ingestion phase prompt
        # "search_prompt": "query: "            # Optional: (Advanced) Search phase prompt
    }
)

# Add the configured embedding function to your existing collection schema
schema.add_function(text_embedding_function)

파라미터	필수?	설명	예제 값
provider	예	임베딩 모델 공급자입니다. "TEI"로 설정합니다.	"TEI"
endpoint	예	배포된 TEI 서비스를 가리키는 네트워크 주소. 밀버스 헬름 차트를 통해 배포된 경우 일반적으로 내부 서비스 주소입니다.	"http://localhost:8080", "http://my-release-milvus-tei:80"
truncate	No	모델의 최대 길이를 초과하는 입력 텍스트를 잘라낼지 여부입니다. 기본값은 false입니다.	"true"
truncation_direction	아니요	잘라내기가 참이면 유효합니다. 왼쪽에서 잘라낼지 오른쪽에서 잘라낼지 지정합니다. 기본값은 오른쪽입니다.	"left"
max_client_batch_size	아니요	Milvus 클라이언트가 TEI로 전송하는 최대 배치 크기입니다. 기본값은 32입니다.	64
prompt_name	아니요	(고급) 문장 변환기 구성 프롬프트 사전에서 키를 지정합니다. 특정 프롬프트 형식이 필요한 특정 모델에 사용됩니다. TEI 지원은 제한될 수 있으며 허브의 모델 구성에 따라 달라질 수 있습니다.	"YOUR_PROMPT_KEY"
ingestion_prompt	아니요	(고급) 데이터 삽입(수집) 단계에서 사용할 프롬프트를 지정합니다. 사용되는 TEI 모델에 따라 다르며, 모델은 프롬프트를 지원해야 합니다.	"passage: "
search_prompt	아니요	(고급) 검색 단계에서 사용할 프롬프트를 지정합니다. 사용되는 TEI 모델에 따라 다르며, 해당 모델은 프롬프트를 지원해야 합니다.	"쿼리: "

다음 단계

임베딩 기능을 구성한 후 기능 개요에서 인덱스 구성, 데이터 삽입 예제 및 시맨틱 검색 작업에 대한 추가 지침을 참조하세요.