Hugging FaceCompatible with Milvus v2.6.20+

일반적으로 Hugging Face 임베딩 모델을 사용하려면 애플리케이션에서 자격 증명을 관리하고, 모델을 별도로 호출하며, 삽입된 데이터와 검색 쿼리에 대해 일관되게 임베딩을 생성해야 합니다. 텍스트 임베딩 기능을 사용하면 Milvus가 호스팅된 Hugging Face 추론 제공자를 호출하여 삽입 및 검색 시 원시 텍스트를 벡터로 변환합니다.

이 통합 기능은 호스팅된 Hugging Face 라우터를 사용합니다. Milvus를 별도로 배포된 텍스트 임베딩 추론(TEI) 서비스에 연결하려면 Hugging Face TEI를 참조하십시오.

제한 사항

• 함수 출력 필드는 ` FLOAT_VECTOR ` 데이터형을 사용해야 합니다. Milvus의 Hugging Face 임베딩은 ` INT8_VECTOR`, ` BINARY_VECTOR`, ` FLOAT16_VECTOR` 또는 ` BFLOAT16_VECTOR ` 출력 필드를 지원하지 않습니다.
• 'Function' 출력 필드의 차원은 선택한 모델의 출력 차원과 일치해야 합니다.

작동 원리

Hugging Face 텍스트 임베딩 워크플로우

이 워크플로는 세 단계로 구성됩니다.

1. 원본 텍스트 전송. 애플리케이션에서 삽입 또는 검색 요청을 통해 원본 텍스트를 제공합니다.
2. 임베딩 생성. 텍스트 임베딩 함수(Text Embedding Function)는 텍스트를 Hugging Face의 텍스트 임베딩 서비스( hf-inference )를 통해 Hugging Face의 텍스트 임베딩 파이프라인( feature-extraction )으로 전송합니다. 이 함수는 Hugging Face의 텍스트 임베딩 서비스( model_name )를 사용하여 모델을 선택하며, 정규화(normalization) 및 잘림(truncation)과 같은 지원되는 추론 옵션을 전달할 수 있습니다.
3. 임베딩을 사용합니다. Hugging Face는 입력 텍스트 하나당 하나의 부동 소수점 임베딩을 반환합니다. 삽입 시 Milvus는 이 벡터를 함수 출력 필드에 저장합니다. 검색 시 Milvus는 이 벡터를 쿼리 벡터로 사용합니다.

동일한 함수 구성을 통해 삽입과 검색을 모두 처리하므로, 두 작업 전반에 걸쳐 모델과 추론 매개변수가 일관되게 유지됩니다.

시작하기 전에

호스팅된 Hugging Face 텍스트 임베딩을 사용하기 전에 다음을 확인하십시오:

• 2.6 릴리스 계열의 Milvus 2.6.20 이상.
• PyMilvus 2.6.16 이상.
• 추론 제공자를 호출할 수 있는 Hugging Face 사용자 액세스 토큰.
• hf-inference 에서 현재 제공 중인, feature-extraction 해당 태스크에 대해 xml-ph-0000@deepl.internal에서 현재 제공 중인 모델.

이 예제에서는 sentence-transformers/all-MiniLM-L6-v2를 사용하며, 이 모델은 384차원 임베딩을 생성합니다. 이 모델은 구성 방법을 시연하기 위한 목적으로만 사용되며, Milvus의 권장 사항이나 인증을 의미하지는 않습니다.

인증 정보 구성

Milvus는 호스팅된 라우터를 호출하기 위해 Hugging Face 사용자 액세스 토큰이 필요합니다. 이 토큰은 milvus.yaml 에서 또는 환경 변수를 통해 구성할 수 있습니다.

인증 정보의 우선순위는 다음과 같습니다:

Function credential label -> provider credential label in milvus.yaml -> environment variable

옵션 1: 구성 파일

milvus.yaml 파일의 최상위 credential 섹션에 토큰을 정의한 다음, Hugging Face 임베딩 제공자를 해당 자격 증명 레이블로 지정합니다:

# milvus.yaml
credential:
  huggingface_apikey:
    apikey: <YOUR_HUGGING_FACE_TOKEN>

function:
  textEmbedding:
    providers:
      huggingface:
        credential: huggingface_apikey
        # url: https://router.huggingface.co

또한 함수 매개변수에서 ` credential `을 설정할 수도 있습니다. 이 값은 토큰 자체가 아니라 ` credential ` 섹션의 최상위 수준에서 정의된 레이블이어야 합니다. 함수 수준의 자격 증명 레이블은 제공자 수준의 레이블보다 우선합니다.

옵션 2: 환경 변수

Function이나 제공자 구성에서 자격 증명 레이블을 지정하지 않은 경우, Milvus는 MILVUS_HUGGINGFACE_API_KEY 에서 토큰을 읽습니다.

Docker Compose의 경우, Milvus 독립 실행형 서비스에서 다음 변수를 설정하십시오.

# docker-compose.yaml
standalone:
  environment:
    MILVUS_HUGGINGFACE_API_KEY: <YOUR_HUGGING_FACE_TOKEN>

Docker Compose 설정 적용에 대한 자세한 내용은 ‘Docker Compose를 사용하여 Milvus 구성’을 참조하십시오.

Hugging Face 텍스트 임베딩 사용

1단계: 텍스트 임베딩 함수가 포함된 컬렉션 생성

기본 필드, VARCHAR 입력 필드 및 FLOAT_VECTOR 출력 필드가 포함된 스키마를 생성합니다. 출력 차원은 선택한 모델과 일치해야 합니다.

from pymilvus import DataType, Function, FunctionType, MilvusClient

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

collection_name = "hugging_face_embedding_demo"
schema = client.create_schema()

schema.add_field(
    field_name="id",
    datatype=DataType.INT64,
    is_primary=True,
    auto_id=False,
)
schema.add_field(
    field_name="document",
    datatype=DataType.VARCHAR,
    max_length=9000,
)
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

` document `에서 ` dense`로 임베딩을 기록하는 ` TEXTEMBEDDING ` 함수를 정의합니다:

text_embedding_function = Function(
    name="hugging_face_embedding",
    input_field_names=["document"],
    output_field_names=["dense"],
    function_type=FunctionType.TEXTEMBEDDING,
    params={
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "credential": "huggingface_apikey",
        "normalize": "true",
        "truncate": "true",
        "max_client_batch_size": 128,
    },
)

schema.add_function(text_embedding_function)

프로바이더 수준 자격 증명이나 환경 변수만 사용하는 경우, 함수 매개변수에서 ` credential `를 생략하십시오.

출력 필드에 대한 인덱스를 구성한 다음 컬렉션을 생성하십시오:

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

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

다음 표는 Hugging Face 전용 함수 매개변수를 설명합니다:

매개변수	필수?	설명
provider	예	임베딩 모델 제공자입니다. 이 값을 ` huggingface`로 설정하십시오.
model_name	예	feature-extraction 작업에 대해 hf-inference 을 통해 제공되는 모델의 Hugging Face 모델 ID입니다.
hf_provider	아니요	Hugging Face 추론 제공자의 경로입니다. Milvus 2.6.20에서 기본값이자 유일하게 지원되는 값은 hf-inference 입니다.
credential	아니요	milvus.yaml 의 최상위 credential 섹션에 정의된 자격 증명의 레이블입니다. 이 값은 토큰 자체가 아닙니다.
normalize	아니요	Hugging Face가 정규화된 임베딩을 반환해야 하는지 여부입니다. 지원되는 값은 true 및 false 입니다. 생략할 경우, Milvus는 요청에 이 옵션을 설정하지 않습니다.
prompt_name	아니요	선택한 모델의 Sentence Transformers 구성에서 정의된 프롬프트의 이름입니다.
truncate	아니요	Hugging Face가 모델이 지원하는 길이를 초과하는 입력을 잘라내야 하는지 여부입니다. 지원되는 값은 true 및 false 입니다.
truncation_direction	아니요	Hugging Face가 입력 데이터를 어느 방향에서 잘라낼지 지정합니다. 지원되는 값은 ` left ` 및 ` right`입니다.
max_client_batch_size	없음	Hugging Face 요청 한 번에 전송되는 입력 텍스트의 최대 개수입니다. 기본값은 128 이며, 이 값은 0 보다 커야 합니다.

2단계: 원본 텍스트 삽입

벡터를 제공하지 않고 텍스트를 입력합니다. Milvus는 Hugging Face를 호출하고 생성된 임베딩을 dense 에 기록합니다.

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Milvus simplifies semantic search through embeddings.",
        },
        {
            "id": 2,
            "document": "Vector embeddings convert text into searchable numeric data.",
        },
        {
            "id": 3,
            "document": "Semantic search helps users find relevant information quickly.",
        },
    ],
)

3단계: 원본 텍스트로 검색

텍스트 쿼리로 검색합니다. Milvus는 벡터 검색을 실행하기 전에 동일한 함수 구성을 적용하여 쿼리 벡터를 생성합니다.

results = client.search(
    collection_name=collection_name,
    data=["How does Milvus handle semantic search?"],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    consistency_level="Strong",
)

print(results)

결과에는 쿼리 텍스트와 가장 관련성이 높은 문서가 코사인 유사도 순으로 포함됩니다.

문제 해결

모델을 사용하여 특징 추출을 수행할 수 없음

Hugging Face에서 모델 페이지를 열고 ‘Inference Providers’ 섹션을 확인하십시오. hf-inference 가 feature-extraction 에 대한 모델을 제공하는지 확인하십시오. 그렇지 않은 경우, 다른 모델을 선택하고 필요한 경우 벡터 필드 차원을 업데이트하십시오.

반환된 벡터 차원이 필드와 일치하지 않습니다

모델 출력 차원을 확인하고 ‘Function output’ 필드의 dim 와 비교하십시오. Milvus는 벡터 차원이 FLOAT_VECTOR 필드 차원과 다른 응답을 거부합니다.

Milvus에서 Hugging Face 자격 증명이 누락되었다고 보고합니다

최상위 ‘ credential ’ 섹션에 ‘Function’ 자격 증명 레이블이 존재하는지, 공급자 수준 레이블이 유효한지, 또는 Milvus 서비스 환경에 ‘ MILVUS_HUGGINGFACE_API_KEY ’가 존재하는지 확인하십시오.

다음 단계

• Function의 일반적인 개념 및 삽입/검색 동작에 대해서는 ‘임베딩 함수 개요’를 참조하십시오.
• 호스팅된 Hugging Face 문장 유사도 점수를 사용하여 벡터 검색 후보를 재순위 지정하려면 Hugging Face Ranker를 참조하십시오.