Hugging FaceCompatible with Milvus v2.6.20+

Обычно для использования модели встраивания Hugging Face вашему приложению необходимо управлять учетными данными, отдельно вызывать модель и последовательно генерировать встраивания для вставляемых данных и поисковых запросов. С помощью функции встраивания текста Milvus вызывает размещенные на хостинге провайдеры инференции Hugging Face для преобразования необработанного текста в векторы во время вставки и поиска.

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

Ограничения

• Поле вывода функции должно использовать тип данных « FLOAT_VECTOR ». Встраивание Hugging Face в Milvus не поддерживает поля вывода типа « INT8_VECTOR », « BINARY_VECTOR », « FLOAT16_VECTOR » или « BFLOAT16_VECTOR ».
• Размерность поля вывода функции должна соответствовать размерности вывода выбранной модели.

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

Рабочий процесс встраивания текста Hugging Face

Рабочий процесс состоит из трех этапов:

1. Отправка исходного текста. Ваше приложение предоставляет исходный текст в запросе на вставку или поиск.
2. Генерация вложения. Функция «Text Embedding» отправляет текст через « hf-inference » в конвейер Hugging Face « feature-extraction ». Функция использует « model_name » для выбора модели и может передавать поддерживаемые параметры инференса, такие как нормализация и усечение.
3. Используйте вложение. Hugging Face возвращает одно вложение с плавающей запятой на каждый входной текст. При вставке Milvus сохраняет вектор в поле вывода функции. При поиске Milvus использует вектор в качестве вектора запроса.

Одна и та же конфигурация функции обрабатывает как вставку, так и поиск, обеспечивая согласованность модели и параметров инференса для обеих операций.

Перед началом

Перед использованием хостируемого текстового вложения Hugging Face убедитесь, что у вас есть:

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

В примерах используется 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: Файл конфигурации

Определите токен в разделе верхнего уровня credential файла milvus.yaml, а затем укажите провайдеру вложений 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: Переменная среды

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

Для Docker Compose установите переменную в автономном сервисе Milvus:

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

Подробнее о применении настроек Docker Compose см. в разделе «Настройка Milvus с помощью Docker Compose».

Использование текстового вложения 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,
)

Определите функцию « TEXTEMBEDDING », которая записывает вложения из « document » в « dense »:

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	Да	Идентификатор модели Hugging Face для модели, предоставляемой через hf-inference для задачи « feature-extraction ».
hf_provider	Нет	Маршрут поставщика инференции Hugging Face. Значением по умолчанию и единственным поддерживаемым значением в Milvus 2.6.20 является hf-inference.
credential	Нет	Метка учетных данных, определённая в разделе верхнего уровня credential файла milvus.yaml. Это значение не является самим токеном.
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 ». Если это не так, выберите другую модель и, при необходимости, обновите размерность векторного поля.

Размерность возвращаемого вектора не соответствует полю

Проверьте размерность выходных данных модели и сравните её с dim в поле «Выходные данные функции». Milvus отклоняет ответ, размерность вектора которого отличается от размерности поля FLOAT_VECTOR.

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

Убедитесь, что метка «Учетные данные функции» (Function credential) присутствует в разделе верхнего уровня «Учетные данные» ( credential ), что метка на уровне провайдера действительна или что «Учетные данные Hugging Face» ( MILVUS_HUGGINGFACE_API_KEY ) присутствуют в среде службы Milvus.

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

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