Hugging Face RankerCompatible with Milvus v2.6.20+

벡터 검색은 벡터 거리에 따라 결과를 정렬하지만, 초기 순서는 각 후보 텍스트가 쿼리에 얼마나 잘 부합하는지를 반영하지 못할 수 있습니다. Hugging Face Ranker는 쿼리와 후보 텍스트를 호스팅된 Hugging Face 추론 제공자(Inference Providers )로 전송하고, 벡터 유사도 점수( sentence-similarity )를 사용하여 Milvus가 반환한 후보들의 순서를 재정렬합니다.

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

제한 사항

• 이 함수는 input_field_names 에서 null이 허용되지 않는 VARCHAR 필드를 정확히 하나만 참조해야 합니다.
• queries 에 포함된 문자열의 개수는 검색 쿼리(nq)의 개수와 동일해야 합니다.

작동 방식

Hugging Face Ranker 워크플로우

Hugging Face Ranker는 초기 벡터 검색이 완료된 후 실행됩니다:

1. 후보 엔티티를 검색합니다. Milvus는 구성된 벡터 필드를 검색하여 후보 엔티티를 수집합니다.
2. 재순위를 위한 텍스트 준비. 이 함수는 params.queries 에서 쿼리 텍스트를, input_field_names 에 지정된 VARCHAR 필드에서 후보 텍스트를 읽어들입니다.
3. 유사도 점수 요청. Milvus는 hf-inference 를 통해 source_sentence 로 쿼리를, sentences 로 후보 텍스트를 Hugging Face sentence-similarity 파이프라인으로 전송합니다.
4. 후보 텍스트의 순위를 재조정합니다. Hugging Face는 후보 텍스트당 하나의 점수를 반환합니다. Milvus는 점수가 높은 순서대로 후보 텍스트를 정렬하여 재순위화된 결과를 반환합니다.

유사도 점수 계산 방식

Hugging Face Ranker가 유사도 점수를 계산하는 방식

Hugging Face 모델은 다음 세 단계에 걸쳐 점수를 계산합니다:

1. 텍스트 입력 데이터를 준비합니다. Ranker는 params.queries 에서 쿼리 텍스트를, 구성된 VARCHAR 필드에서 후보 텍스트를 읽어들입니다.
2. 별도의 모델 표현 생성. Milvus는 쿼리를 source_sentence 로, 후보 텍스트를 sentences 로 전송합니다. 모델은 내부적으로 쿼리와 각 후보를 별도로 인코딩합니다.
3. 점수를 비교하고 반환합니다. 모델은 쿼리 표현과 각 후보 표현을 비교하여 후보마다 하나의 유사도 점수를 반환합니다.

Hugging Face 모델이 사용하는 임베딩 또는 표현은 모델 처리 과정의 중간 단계입니다. Hugging Face는 벡터가 아닌 점수를 반환합니다. 따라서 초기 벡터 검색과 모델 재순위는 별도의 표현을 사용하며, 서로 다른 모델을 사용할 수도 있습니다.

시작하기 전에

Hugging Face Ranker를 사용하기 전에 다음을 확인하십시오:

• 2.6 릴리스 라인의 Milvus 2.6.20 이상.
• PyMilvus 2.6.16 이상.
• 추론 제공자(Inference Providers)를 호출할 수 있는 Hugging Face 사용자 액세스 토큰.
• hf-inference 에서 현재 sentence-similarity 해당 태스크에 대해 xml-ph-0000@deepl.internal에서 현재 제공 중인 모델.
• VARCHAR 의 null 허용되지 않는 필드에 후보 텍스트를 저장하는 컬렉션.

이 예제에서는 sentence-transformers/all-MiniLM-L6-v2 단순히 구성을 보여주기 위한 목적으로만 사용됩니다. 이 모델은 Milvus의 권장 사항이나 인증을 의미하지 않습니다.

인증 정보 구성

milvus.yaml 에서 또는 환경 변수를 통해 Hugging Face 사용자 액세스 토큰을 구성할 수 있습니다.

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

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

옵션 1: 구성 파일

credential 섹션의 최상위 수준에서 토큰을 정의한 다음, Hugging Face 랭커 제공자를 해당 자격 증명 레이블로 지정합니다:

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

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

함수(Function) 수준의 credential 매개변수는 제공자(provider) 수준의 레이블을 재정의할 수 있습니다. 이 매개변수의 값은 토큰 자체가 아니라 milvus.yaml 에 정의된 자격 증명 레이블이어야 합니다.

옵션 2: 환경 변수

함수나 제공자 구성 모두에서 자격 증명 레이블이 지정되지 않은 경우, Milvus 서비스 환경에서 ` MILVUS_HUGGINGFACE_API_KEY `을 설정하십시오:

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

Hugging Face Ranker 사용

Hugging Face Ranker는 검색 시점에 정의되고 적용됩니다. 컬렉션 스키마를 변경하지 않고도 각 검색마다 랭커를 변경하거나 생략할 수 있습니다.

1단계: 컬렉션 준비

다음 예제는 재순위를 위한 텍스트 필드와 초기 검색을 위한 벡터 필드가 포함된 컬렉션을 생성합니다:

from pymilvus import DataType, Function, FunctionType, MilvusClient

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

collection_name = "hugging_face_rerank_demo"
schema = client.create_schema()
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=1000)
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=4)

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,
)

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Recent renewable energy developments include improved solar efficiency.",
            "dense": [0.10, 0.20, 0.30, 0.40],
        },
        {
            "id": 2,
            "document": "Climate policy and carbon markets have evolved rapidly in recent years.",
            "dense": [0.11, 0.19, 0.28, 0.39],
        },
        {
            "id": 3,
            "document": "New battery technology helps stabilize wind and solar power generation.",
            "dense": [0.90, 0.10, 0.05, 0.02],
        },
        {
            "id": 4,
            "document": "Vector databases support similarity search for machine learning applications.",
            "dense": [0.01, 0.02, 0.03, 0.04],
        },
    ],
)

2단계: 재순위 지정 함수 정의

document 에서 후보 텍스트를 읽고 queries 의 쿼리 텍스트를 사용하는 RERANK 함수를 정의합니다:

hugging_face_ranker = Function(
    name="hugging_face_semantic_ranker",
    input_field_names=["document"],
    function_type=FunctionType.RERANK,
    params={
        "reranker": "model",
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "queries": ["renewable energy developments"],
        "credential": "huggingface_apikey",
        "max_client_batch_size": 32,
    },
)

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

다음 표는 Hugging Face Ranker 매개변수에 대해 설명합니다:

매개변수	필수?	설명
reranker	예	재순위 지정 구현. 이 값을 ` model`로 설정하십시오.
provider	예	모델 제공자입니다. 이 값을 huggingface 로 설정하십시오.
model_name	예	sentence-similarity 태스크를 위해 hf-inference 을 통해 제공되는 모델의 Hugging Face 모델 ID입니다.
queries	예	재순위 지정에 사용되는 쿼리 문자열입니다. 초기 검색에 쿼리 벡터가 사용되는 경우에도 검색 쿼리당 정확히 하나의 문자열을 제공해야 합니다.
hf_provider	아니요	Hugging Face 추론 제공자 경로입니다. Milvus 2.6.20에서 기본값이자 유일하게 지원되는 값은 hf-inference 입니다.
credential	아니요	milvus.yaml 의 최상위 credential 섹션에 정의된 자격 증명의 레이블입니다. 이 값은 토큰 자체가 아닙니다.
max_client_batch_size	아니요	Hugging Face 요청 한 번에 전송되는 후보 텍스트의 최대 개수입니다. 기본값은 32 이며, 이 값은 0 보다 커야 합니다.

3단계: 랭커를 사용하여 검색하기

search() 의 ranker 매개변수를 통해 함수를 전달합니다:

query_vector = [0.12, 0.21, 0.29, 0.41]

results = client.search(
    collection_name=collection_name,
    data=[query_vector],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    ranker=hugging_face_ranker,
    consistency_level="Strong",
)

print(results)

Milvus는 먼저 dense 에서 후보를 검색한 다음, queries 의 쿼리 텍스트와 document 의 후보 텍스트를 사용하여 문장 유사도 점수를 계산합니다. 반환된 후보는 Hugging Face 점수 순으로 정렬됩니다.

문제 해결

문장 유사도 모델 사용 불가

Hugging Face에서 모델 페이지를 열고 ‘Inference Providers’ 섹션을 확인하십시오. hf-inference 가 sentence-similarity 에 대한 모델을 제공하는지 확인하십시오. 그렇지 않은 경우, 해당 작업을 지원하는 다른 모델을 선택하십시오.

쿼리 문자열의 개수가 검색 요청과 일치하지 않습니다

queries 에 포함된 문자열의 개수는 검색 쿼리(nq)의 개수와 정확히 일치해야 합니다. 쿼리 벡터가 하나인 검색의 경우, 쿼리 문자열을 정확히 하나만 제공하십시오.

후보 텍스트가 누락되었거나 null 허용 값입니다

input_field_names 에 null이 허용되지 않는 VARCHAR 필드가 정확히 하나 포함되어 있는지, 그리고 모든 후보 엔티티가 해당 필드에 텍스트를 포함하고 있는지 확인하십시오.

Milvus에서 Hugging Face 자격 증명 누락 오류 보고

milvus.yaml 에 Function 자격 증명 레이블이 존재하는지, 공급자 수준 레이블이 유효한지, 또는 Milvus 서비스 환경에 MILVUS_HUGGINGFACE_API_KEY 가 존재하는지 확인하십시오.

다음 단계

• 모델 랭커의 동작 및 제한 사항에 대해서는 ‘모델 랭커 개요’를 참조하십시오.
• 호스팅된 Hugging Face 추론 제공자를 통해 임베딩을 생성하려면 Hugging Face를 참조하십시오.
• 랭커를 하이브리드 검색에 적용하려면 ‘다중 벡터 하이브리드 검색’을 참조하십시오.