Hugging Face RankerCompatible with Milvus v2.6.20+

Векторный поиск сортирует результаты по векторному расстоянию, но исходный порядок может не отражать, насколько хорошо текст каждого кандидата соответствует запросу. Hugging Face Ranker отправляет запрос и текст кандидатов в хостируемые провайдеры инференции Hugging Face и использует оценки « sentence-similarity » для переупорядочения кандидатов, возвращаемых Milvus.

В данной интеграции используется размещённый на хостинге маршрутизатор Hugging Face. Чтобы выполнить переранжирование с помощью отдельно развернутого сервиса Text Embeddings Inference (TEI), см. TEI Ranker.

Ограничения

• Функция должна ссылаться ровно на одно поле VARCHAR, не допускающее нулевых значений, в input_field_names.
• Количество строк в queries должно равняться количеству поисковых запросов (nq).

Как это работает

Рабочий процесс Hugging Face Ranker

Hugging Face Ranker запускается после первоначального векторного поиска:

1. Извлечение кандидатов-сущностей. Milvus выполняет поиск по настроенному векторному полю и собирает кандидатов-сущности.
2. Подготовка текста для повторного ранжирования. Функция считывает текст запроса из params.queries и текст кандидатов из поля VARCHAR, указанного в input_field_names.
3. Запрос оценок схожести. Milvus отправляет запрос как source_sentence, а тексты кандидатов как sentences через hf-inference в конвейер 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 убедитесь, что у вас установлена:

• Milvus 2.6.20 или более поздней версии из линейки релизов 2.6.
• PyMilvus 2.6.16 или более поздней версии.
• Токен доступа пользователя Hugging Face, позволяющий вызывать провайдеры инференции.
• Модель, которая в данный момент обслуживается hf-inference для sentence-similarity задачи.
• Коллекция, в которой хранится текст-кандидат в поле VARCHAR, не допускающем нулевых значений.

В примерах используется sentence-transformers/all-MiniLM-L6-v2 используются исключительно для демонстрации конфигурации. Модель не является рекомендацией или сертификатом со стороны Milvus.

Настройка учетных данных

Вы можете настроить токен доступа пользователя Hugging Face на сайте milvus.yaml или с помощью переменной среды.

Приоритет учетных данных следующий:

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

Параметр « credential » на уровне функции может переопределить метку на уровне провайдера. Его значением должна быть метка учетных данных, определённая в milvus.yaml, а не сам токен.

Вариант 2: Переменная среды

Если ни в конфигурации функции, ни в конфигурации провайдера не указан лейбл учетных данных, установите значение MILVUS_HUGGINGFACE_API_KEY в среде службы Milvus:

# 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: Определение функции переранжирования

Определите функцию « RERANK », которая считывает текст кандидатов из document и использует текст запроса из queries:

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	Да	Идентификатор модели Hugging Face для модели, предоставляемой через hf-inference для задачи « sentence-similarity ».
queries	Да	Строки запроса, используемые для повторного ранжирования. Укажите ровно одну строку на каждый поисковый запрос, даже если при первоначальном извлечении используются векторы запросов.
hf_provider	Нет	Маршрут провайдера инференции Hugging Face. По умолчанию и единственное поддерживаемое значение в Milvus 2.6.20 — hf-inference.
credential	Нет	Метка учетных данных, определённая в разделе верхнего уровня credential файла milvus.yaml. Это значение не является самим токеном.
max_client_batch_size	Нет	Максимальное количество текстов-кандидатов, отправляемых в одном запросе Hugging Face. Значение по умолчанию — 32, и оно должно быть больше, чем 0.

Шаг 3: Поиск с помощью ранжера

Передайте функцию через параметр ranker на сайте search():

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 содержит ровно одно поле VARCHAR, не допускающее нулевого значения, и что каждая сущность-кандидат содержит текст в этом поле.

Milvus сообщает об отсутствии учетных данных Hugging Face

Убедитесь, что в файле ` milvus.yaml` присутствует метка учетных данных `Function`, что метка на уровне провайдера действительна или что ` MILVUS_HUGGINGFACE_API_KEY ` присутствует в среде службы Milvus.

Следующие шаги

• Информацию о поведении и ограничениях общего доступа к ранжерам моделей см. в разделе «Обзор ранжеров моделей».
• Чтобы сгенерировать вложения с помощью размещенных провайдеров инференса Hugging Face, см. раздел «Hugging Face».
• Чтобы применить ранжировщик к гибридному поиску, см. раздел «Гибридный поиск с несколькими векторами».