Hugging Face RankerCompatible with Milvus v2.6.20+

La búsqueda vectorial ordena los resultados según la distancia vectorial, pero es posible que el orden inicial no refleje en qué medida el texto de cada candidato responde a la consulta. Hugging Face Ranker envía la consulta y el texto de los candidatos a los proveedores de inferencia alojados de Hugging Face y utiliza puntuaciones de « sentence-similarity » para reordenar los candidatos devueltos por Milvus.

Esta integración utiliza el enrutador alojado de Hugging Face. Para volver a clasificar los resultados con un servicio de inferencia de incrustaciones de texto (TEI) implementado por separado, consulta TEI Ranker.

Límites

• La función debe hacer referencia exactamente a un campo « VARCHAR » no nulo en input_field_names.
• El número de cadenas en « queries » debe ser igual al número de consultas de búsqueda (nq).

Cómo funciona

Flujo de trabajo de Hugging Face Ranker

Hugging Face Ranker se ejecuta tras la búsqueda vectorial inicial:

1. Recupera las entidades candidatas. Milvus busca en el campo vectorial configurado y recopila las entidades candidatas.
2. Prepara el texto para la reclasificación. La función lee el texto de la consulta de params.queries y el texto de las entidades candidatas del campo VARCHAR especificado en input_field_names.
3. Solicita puntuaciones de similitud. Milvus envía la consulta como source_sentence y los textos candidatos como sentences a través de hf-inference al canal de procesamiento de Hugging Face sentence-similarity.
4. Reordenar los candidatos. Hugging Face devuelve una puntuación por candidato. Milvus ordena los candidatos de mayor a menor puntuación y devuelve los resultados reordenados.

Cómo se calculan las puntuaciones de similitud

Cómo calcula Hugging Face Ranker las puntuaciones de similitud

El modelo de Hugging Face calcula las puntuaciones en tres etapas:

1. Prepara las entradas de texto. El Ranker lee el texto de la consulta desde params.queries y el texto de los candidatos desde el campo VARCHAR configurado.
2. Creación de representaciones de modelo independientes. Milvus envía la consulta como source_sentence y los textos candidatos como sentences. El modelo codifica internamente la consulta y cada candidato por separado.
3. Compara y devuelve puntuaciones. El modelo compara la representación de la consulta con la de cada candidato y devuelve una puntuación de similitud por candidato.

Las incrustaciones o representaciones utilizadas por el modelo de Hugging Face son parte del procesamiento interno del modelo. Hugging Face devuelve puntuaciones, no vectores. Por lo tanto, la recuperación inicial de vectores y la reclasificación del modelo utilizan representaciones independientes y pueden emplear modelos diferentes.

Antes de empezar

Antes de utilizar Hugging Face Ranker, 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é siendo servido por hf-inference para la sentence-similarity tarea.
• Una colección que almacena el texto candidato en un campo de VARCHAR que no admite valores nulos.

Los ejemplos utilizan sentence-transformers/all-MiniLM-L6-v2 solo para mostrar la configuración. El modelo no supone una recomendación ni una certificación por parte de Milvus.

Configurar las credenciales

Puede configurar el token de acceso de usuario de Hugging Face 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 » y, a continuación, asigne al proveedor de clasificación de Hugging Face la etiqueta de credencial:

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

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

Un parámetro de « credential » a nivel de función puede anular la etiqueta a nivel de proveedor. Su valor debe ser una etiqueta de credencial definida en milvus.yaml, no el propio token.

Opción 2: Variable de entorno

Si ni la función ni la configuración del proveedor especifican una etiqueta de credencial, configura ` MILVUS_HUGGINGFACE_API_KEY ` en el entorno del servicio Milvus:

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

Utilizar Hugging Face Ranker

Hugging Face Ranker se define y se aplica en el momento de la búsqueda. Puedes cambiar u omitir el clasificador para cada búsqueda sin modificar el esquema de la colección.

Paso 1: Preparar una colección

El siguiente ejemplo crea una colección con un campo de texto para la reordenación y un campo vectorial para la recuperación inicial:

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

Paso 2: Definir la función de reordenación

Define una función « RERANK » que lea el texto candidato de document y utilice el texto de la consulta de 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,
    },
)

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

La siguiente tabla describe los parámetros de Hugging Face Ranker:

Parámetro	¿Es obligatorio?	Descripción
reranker	Sí	La implementación de la reclasificación. Establece este valor en « model ».
provider	Sí	El proveedor del modelo. 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 « sentence-similarity ».
queries	Sí	Cadenas de consulta utilizadas para la reclasificación. Proporcione exactamente una cadena por cada consulta de búsqueda, incluso cuando la recuperación inicial utilice vectores de consulta.
hf_provider	No	La ruta del proveedor de inferencia de Hugging Face. El valor predeterminado y ú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í.
max_client_batch_size	No	El número máximo de textos candidatos enviados en una sola solicitud a Hugging Face. El valor por defecto es 32, y el valor debe ser mayor que 0.

Paso 3: Realizar la búsqueda con el clasificador

Pasa la función a través del parámetro ranker de 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 recupera primero los candidatos de dense y, a continuación, utiliza el texto de la consulta de queries y el texto de los candidatos de document para calcular las puntuaciones de similitud entre frases. Los candidatos devueltos se ordenan según las puntuaciones de Hugging Face.

Solución de problemas

El modelo no está disponible para la similitud de frases

Abre la página del modelo en Hugging Face y comprueba la sección «Inference Providers ». Confirma que hf-inference aloja el modelo para sentence-similarity. Si no es así, selecciona otro modelo que admita la tarea.

El número de cadenas de consulta no coincide con la solicitud de búsqueda

El número de cadenas en queries debe ser igual al número de consultas de búsqueda (nq). Para una búsqueda con un vector de consulta, proporciona exactamente una cadena de consulta.

Falta el texto del candidato o es de tipo nulo

Asegúrate de que input_field_names contenga exactamente un campo VARCHAR no nulo y de que cada entidad candidata contenga texto en ese campo.

Milvus informa de que faltan las credenciales de Hugging Face

Comprueba que la etiqueta de credenciales «Function» existe en milvus.yaml, que la etiqueta a nivel de proveedor es válida o que MILVUS_HUGGINGFACE_API_KEY está presente en el entorno de servicio de Milvus.

Próximos pasos

• Para conocer el comportamiento y los límites del clasificador de modelos compartido, consulta la Descripción general del clasificador de modelos.
• Para generar incrustaciones a través de los proveedores de inferencia alojados de Hugging Face, consulte Hugging Face.
• Para aplicar el clasificador a la búsqueda híbrida, consulta «Búsqueda híbrida multivectorial».