Hugging Face TEI

원문 보기 위키 갱신 2026.10.08

Milvus 2.6.x와 호환돼요.

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

TEI는 Hugging Face Hub의 많은 텍스트 임베딩 모델과 함께 동작해요. 다음을 포함해요.

BAAI/bge-* 시리즈
sentence-transformers/* 시리즈
E5 모델
GTE 모델
그 외 더 많은 모델

지원되는 모델의 최신 목록은 TEI GitHub 저장소와 Hugging Face Hub를 참고하세요.

출처: Milvus 문서

본문

TEI 배포 (TEI deployment)

Milvus에서 TEI 함수를 구성하기 전에 실행 중인 TEI 서비스가 있어야 해요. Milvus는 두 가지 TEI 배포 방식을 지원해요.

표준 배포 (외부)

Hugging Face의 공식 방법을 사용해 TEI를 독립 서비스로 배포할 수 있어요. 이 방식은 TEI 서비스를 최대한 유연하게 제어할 수 있게 해 줘요.

Docker나 다른 방법으로 TEI를 배포하는 자세한 지침은 Hugging Face Text Embeddings Inference 공식 문서를 참고하세요.

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

Milvus Helm Chart 배포 (통합)

Kubernetes 환경에서 Milvus는 Helm Chart를 통해 통합 배포 옵션을 제공해요. 이 방식은 Milvus와 함께 TEI를 배포하고 구성해 과정을 단순화해요.

Milvus Helm 배포에서 TEI를 활성화하려면:

values.yaml을 구성해 TEI를 활성화해요.

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_..."
  # 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: []

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>

Helm Chart 배포를 사용할 때 TEI 서비스는 Kubernetes 클러스터 안에서 http://my-release-milvus-tei:80(자신의 릴리스 이름 사용)으로 접근할 수 있어요. TEI 함수 구성에서 이 값을 엔드포인트로 사용하세요.

Milvus에서의 구성 (Configuration in Milvus)

TEI 서비스를 배포한 뒤 TEI 임베딩 함수를 정의할 때 그 엔드포인트를 제공해야 해요. 대부분의 경우 TEI는 Milvus에서 기본적으로 활성화되어 있어 추가 구성이 필요 없어요.

TEI 서비스가 API 키 인증(--api-key 플래그)으로 배포되었다면 Milvus가 이 키를 사용하도록 구성해야 해요.

credential 섹션에 API 키를 정의해요.

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

milvus.yaml에서 자격 증명을 참조해요.

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

임베딩 함수 사용 (Use embedding function)

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

1단계: 스키마 필드 정의

임베딩 함수를 사용하려면 특정 스키마로 컬렉션을 만들어요. 이 스키마에는 최소 세 가지 필드가 필요해요.

컬렉션의 각 엔티티를 고유하게 식별하는 기본 필드
임베딩할 원본 데이터를 저장하는 스칼라 필드
함수가 스칼라 필드에 대해 생성한 벡터 임베딩을 저장하기 위해 예약된 벡터 필드

다음 예시는 텍스트 데이터를 저장할 스칼라 필드 "document" 하나와 Function 모듈이 생성할 임베딩을 저장할 벡터 필드 "dense_vector" 하나를 가진 스키마를 정의해요. 벡터 차원(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의 Function 모듈은 스칼라 필드에 저장된 원본 데이터를 자동으로 임베딩으로 변환하고, 명시적으로 정의된 벡터 필드에 저장해요.

아래 예시는 스칼라 필드 "document"를 임베딩으로 변환하고, 결과 벡터를 앞서 정의한 "dense_vector" 벡터 필드에 저장하는 Function 모듈(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`	Yes	임베딩 모델 제공자예요. "TEI"로 설정해요.	"TEI"
`endpoint`	Yes	배포한 TEI 서비스를 가리키는 네트워크 주소예요. Milvus Helm Chart로 배포했다면 보통 내부 Service 주소예요.	"http://localhost:8080", "http://my-release-milvus-tei:80"
`truncate`	No	모델의 최대 길이를 초과하는 입력 텍스트를 잘라낼지 여부예요. 기본값은 false예요.	"true"
`truncation_direction`	No	truncate가 true일 때 유효해요. 왼쪽에서 또는 오른쪽에서 잘라낼지 지정해요. 기본값은 right예요.	"left"
`max_client_batch_size`	No	Milvus 클라이언트가 TEI에 보내는 최대 배치 크기예요. 기본값은 32예요.	64
`prompt_name`	No	(고급) sentence-transformers 설정 prompts 딕셔너리에서 키를 지정해요. 특정 프롬프트 형식이 필요한 일부 모델에 사용돼요. TEI 지원은 제한적일 수 있고 Hub에서 모델의 구성에 따라 달라져요.	"your_prompt_key"
`ingestion_prompt`	No	(고급) 데이터 삽입(ingestion) 단계에서 사용할 프롬프트를 지정해요. 사용하는 TEI 모델에 따라 달라지며, 모델이 프롬프트를 지원해야 해요.	"passage: "
`search_prompt`	No	(고급) 검색 단계에서 사용할 프롬프트를 지정해요. 사용하는 TEI 모델에 따라 달라지며, 모델이 프롬프트를 지원해야 해요.	"query: "

다음 단계 (Next steps)

임베딩 함수를 구성한 뒤에는 Function Overview를 참고해 인덱스 구성, 데이터 삽입 예시, 시맨틱 검색 연산에 대한 추가 지침을 확인해요.

더 알아보기 (Learn more)

Hugging Face Text Embeddings Inference 문서 — TEI 서비스 소개와 배포
TEI GitHub 저장소 — 지원 모델 목록
Embedding Function Overview — 임베딩 함수 구성과 사용