Hugging FaceCompatible with Milvus v2.6.20+

El uso de un modelo de incrustación de Hugging Face suele requerir que tu aplicación gestione las credenciales, llame al modelo por separado y genere incrustaciones de forma coherente para los datos insertados y las consultas de búsqueda. Con una función de incrustación de texto, Milvus llama a los proveedores de inferencia alojados de Hugging Face para convertir el texto sin procesar en vectores durante la inserción y la búsqueda.

Esta integración utiliza el enrutador alojado de Hugging Face. Para conectar Milvus a un servicio de inferencia de incrustaciones de texto (TEI) implementado por separado, consulta Hugging Face TEI.

Límites

• El campo de salida de la función debe utilizar el tipo de datos « FLOAT_VECTOR ». La incrustación de Hugging Face en Milvus no admite los campos de salida « INT8_VECTOR », « BINARY_VECTOR », « FLOAT16_VECTOR » ni « BFLOAT16_VECTOR ».
• La dimensión del campo de salida «Function» debe coincidir con la dimensión de salida del modelo seleccionado.

Cómo funciona

Flujo de trabajo de incrustación de texto de Hugging Face

El flujo de trabajo consta de tres etapas:

1. Enviar texto sin procesar. Tu aplicación proporciona texto sin procesar en una solicitud de inserción o búsqueda.
2. Generar una incrustación. La función «Text Embedding» envía el texto a través de hf-inference al canal de procesamiento « feature-extraction » de Hugging Face. La función utiliza model_name para seleccionar el modelo y puede pasar opciones de inferencia compatibles, como la normalización y el truncamiento.
3. Utilizar la representación. Hugging Face devuelve una representación de punto flotante por cada texto de entrada. Durante la inserción, Milvus almacena el vector en el campo de salida de la función. Durante la búsqueda, Milvus utiliza el vector como vector de consulta.

La misma configuración de la función gestiona tanto la inserción como la búsqueda, manteniendo la coherencia del modelo y los parámetros de inferencia en ambas operaciones.

Antes de empezar

Antes de utilizar la incrustación de texto alojada de Hugging Face, asegúrate de que dispones de:

• Milvus 2.6.20 o posterior de la línea de versiones 2.6.
• PyMilvus 2.6.16 o posterior.
• Un token de acceso de usuario de Hugging Face que pueda llamar a los proveedores de inferencia.
• Un modelo que actualmente esté disponible en hf-inference para la feature-extraction tarea.

Los ejemplos utilizan sentence-transformers/all-MiniLM-L6-v2, que genera incrustaciones de 384 dimensiones. El modelo se utiliza únicamente para mostrar la configuración y no constituye una recomendación ni una certificación por parte de Milvus.

Configurar las credenciales

Milvus requiere un token de acceso de usuario de Hugging Face para llamar al enrutador alojado. Puede configurar el token en milvus.yaml o mediante una variable de entorno.

El orden de prioridad de las credenciales es el siguiente:

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

Opción 1: Archivo de configuración

Defina el token en la sección de nivel superior « credential » de milvus.yaml y, a continuación, asigne el proveedor de incrustaciones de Hugging Face a esa etiqueta de credencial:

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

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

También puede establecer « credential » en los parámetros de la función. El valor debe ser la etiqueta definida en la sección de nivel superior « credential », no el token en sí. Una etiqueta de credencial a nivel de función tiene prioridad sobre la etiqueta a nivel de proveedor.

Opción 2: Variable de entorno

Si ni la función ni la configuración del proveedor especifican una etiqueta de credencial, Milvus lee el token desde MILVUS_HUGGINGFACE_API_KEY.

Para Docker Compose, configura la variable en el servicio independiente de Milvus:

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

Para obtener más información sobre cómo aplicar la configuración de Docker Compose, consulta «Configurar Milvus con Docker Compose».

Utilizar la incrustación de texto de Hugging Face

Paso 1: Crear una colección con una función de incrustación de texto

Crea un esquema con un campo primario, un campo de entrada « VARCHAR » y un campo de salida « FLOAT_VECTOR ». La dimensión de salida debe coincidir con el modelo seleccionado.

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

Define una función « TEXTEMBEDDING » que escriba las representaciones de « document » en « 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)

Si solo utilizas la credencial a nivel de proveedor o la variable de entorno, omite « credential » de los parámetros de la función.

Configure un índice para el campo de salida y, a continuación, cree la colección:

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

La siguiente tabla describe los parámetros de la función específicos de Hugging Face:

Parámetro	¿Es obligatorio?	Descripción
provider	Sí	El proveedor del modelo de incrustación. Establece este valor en huggingface.
model_name	Sí	El ID del modelo de Hugging Face para un modelo servido a través de hf-inference para la tarea « feature-extraction ».
hf_provider	No	La ruta del proveedor de inferencia de Hugging Face. El valor predeterminado y el único admitido en Milvus 2.6.20 es hf-inference.
credential	No	La etiqueta de una credencial definida en la sección de nivel superior credential de milvus.yaml. Este valor no es el token en sí.
normalize	No	Indica si Hugging Face debe devolver representaciones normalizadas. Los valores admitidos son true y false. Si se omite, Milvus no establece esta opción en la solicitud.
prompt_name	No	El nombre de un prompt definido en la configuración de Sentence Transformers del modelo seleccionado.
truncate	No	Si Hugging Face debe truncar una entrada que supere la longitud admitida por el modelo. Los valores admitidos son « true » y « false ».
truncation_direction	No	La dirección desde la que Hugging Face trunca una entrada. Los valores admitidos son « left » y « right ».
max_client_batch_size	No	El número máximo de textos de entrada enviados en una sola solicitud a Hugging Face. El valor por defecto es 128, y el valor debe ser mayor que 0.

Paso 2: Insertar texto sin procesar

Inserta texto sin proporcionar vectores. Milvus llama a Hugging Face y escribe las incrustaciones generadas en 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.",
        },
    ],
)

Paso 3: Buscar con texto sin procesar

Realiza una búsqueda con una consulta de texto. Milvus aplica la misma configuración de la función para crear el vector de consulta antes de ejecutar la búsqueda vectorial.

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)

El resultado contiene los documentos más relevantes para el texto de la consulta, ordenados por similitud coseno.

Solución de problemas

El modelo no está disponible para la extracción de características

Abre la página del modelo en Hugging Face y comprueba la sección «Inference Providers ». Confirma que « hf-inference » aloja el modelo para « feature-extraction ». Si no es así, selecciona otro modelo y actualiza la dimensión del campo vectorial si es necesario.

La dimensión del vector devuelta no coincide con el campo

Comprueba la dimensión de salida del modelo y compárala con la de dim en el campo «Salida de la función». Milvus rechaza cualquier respuesta cuya dimensión vectorial difiera de la dimensión del campo FLOAT_VECTOR.

Milvus informa de que faltan credenciales de Hugging Face

Comprueba que la etiqueta de credenciales de la función exista en la sección de nivel superior « credential », que la etiqueta a nivel de proveedor sea válida o que « MILVUS_HUGGINGFACE_API_KEY » esté presente en el entorno de servicio de Milvus.

Próximos pasos

• Para conocer los conceptos generales de Function y el comportamiento de inserción y búsqueda, consulta la Descripción general de Embedding Function.
• Para volver a clasificar los candidatos de la búsqueda vectorial con puntuaciones de similitud de frases de Hugging Face alojadas, consulta «Hugging Face Ranker».