Hugging FaceCompatible with Milvus v2.6.20+

L'utilizzo di un modello di embedding di Hugging Face richiede normalmente che l'applicazione gestisca le credenziali, chiami il modello separatamente e generi embedding in modo coerente per i dati inseriti e le query di ricerca. Con una funzione di embedding testuale, Milvus chiama i provider di inferenza Hugging Face ospitati per convertire il testo grezzo in vettori durante l'inserimento e la ricerca.

Questa integrazione utilizza il router Hugging Face ospitato. Per collegare Milvus a un servizio di inferenza di embedding testuale (TEI) distribuito separatamente, consultare Hugging Face TEI.

Limiti

• Il campo di output della funzione deve utilizzare il tipo di dati ` FLOAT_VECTOR `. L’embedding di Hugging Face in Milvus non supporta i campi di output ` INT8_VECTOR`, ` BINARY_VECTOR`, ` FLOAT16_VECTOR` o ` BFLOAT16_VECTOR `.
• La dimensione del campo di output della funzione deve corrispondere alla dimensione di output del modello selezionato.

Come funziona

Flusso di lavoro dell’embedding testuale di Hugging Face

Il flusso di lavoro prevede tre fasi:

1. Invio del testo grezzo. L’applicazione fornisce il testo grezzo in una richiesta di inserimento o di ricerca.
2. Generazione di un embedding. La funzione "Text Embedding" invia il testo tramite hf-inference alla pipeline " feature-extraction " di Hugging Face. La funzione utilizza model_name per selezionare il modello e può passare opzioni di inferenza supportate, quali la normalizzazione e il troncamento.
3. Utilizza l’embedding. Hugging Face restituisce un embedding in virgola mobile per ogni testo in ingresso. Durante l’inserimento, Milvus memorizza il vettore nel campo di output della funzione. Durante la ricerca, Milvus utilizza il vettore come vettore di query.

La stessa configurazione della Funzione gestisce sia l’inserimento che la ricerca, mantenendo il modello e i parametri di inferenza coerenti in entrambe le operazioni.

Prima di iniziare

Prima di utilizzare l’embedding di testo ospitato da Hugging Face, assicurarsi di disporre di:

• Milvus 2.6.20 o versioni successive della linea di rilascio 2.6.
• PyMilvus 2.6.16 o versione successiva.
• Un token di accesso utente Hugging Face in grado di richiamare i provider di inferenza.
• Un modello attualmente fornito d hf-inference per il feature-extraction attività.

Gli esempi utilizzano sentence-transformers/all-MiniLM-L6-v2, che produce embedding a 384 dimensioni. Il modello viene utilizzato solo per illustrare la configurazione e non costituisce una raccomandazione né una certificazione da parte di Milvus.

Configurazione delle credenziali

Milvus richiede un token di accesso utente Hugging Face per richiamare il router ospitato. È possibile configurare il token su milvus.yaml o tramite una variabile d’ambiente.

L’ordine di priorità delle credenziali è il seguente:

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

Opzione 1: File di configurazione

Definire il token nella sezione di primo livello credential di milvus.yaml, quindi indirizzare il provider di embedding di Hugging Face a tale etichetta di credenziale:

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

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

È inoltre possibile impostare ` credential ` nei parametri della funzione. Il valore deve corrispondere all’etichetta definita nella sezione di primo livello ` credential `, non al token stesso. Un’etichetta di credenziale a livello di funzione ha la precedenza su quella a livello di provider.

Opzione 2: Variabile d’ambiente

Se né la configurazione della Funzione né quella del provider specificano un'etichetta delle credenziali, Milvus legge il token da ` MILVUS_HUGGINGFACE_API_KEY`.

Per Docker Compose, impostare la variabile nel servizio Milvus standalone:

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

Per i dettagli sull’applicazione delle impostazioni di Docker Compose, consultare Configurare Milvus con Docker Compose.

Utilizzare l’embedding testuale di Hugging Face

Passaggio 1: Creare una raccolta con una funzione di embedding testuale

Creare uno schema con un campo primario, un campo di input VARCHAR e un campo di output FLOAT_VECTOR. La dimensione di output deve corrispondere al modello selezionato.

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

Definire una funzione " TEXTEMBEDDING " che scriva gli embedding da " document " a " 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)

Se si utilizzano solo le credenziali a livello di provider o la variabile d’ambiente, omettere credential dai parametri della funzione.

Configurare un indice per il campo di output, quindi creare la raccolta:

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 tabella seguente descrive i parametri della funzione specifici di Hugging Face:

Parametro	Obbligatorio?	Descrizione
provider	Sì	Il provider del modello di embedding. Impostare questo valore su huggingface.
model_name	Sì	L'ID del modello Hugging Face per un modello fornito tramite hf-inference per il task " feature-extraction ".
hf_provider	No	Il percorso del provider di inferenza di Hugging Face. Il valore predefinito e l'unico supportato in Milvus 2.6.20 è hf-inference.
credential	No	L'etichetta di una credenziale definita nella sezione di primo livello credential di milvus.yaml. Questo valore non è il token stesso.
normalize	No	Indica se Hugging Face deve restituire embedding normalizzati. I valori supportati sono true e false. Se omesso, Milvus non imposta questa opzione nella richiesta.
prompt_name	No	Il nome di un prompt definito nella configurazione "Sentence Transformers" del modello selezionato.
truncate	No	Se Hugging Face debba troncare un input che supera la lunghezza supportata dal modello. I valori supportati sono true e false.
truncation_direction	No	La direzione in cui Hugging Face tronca un input. I valori supportati sono left e right.
max_client_batch_size	No	Il numero massimo di testi di input inviati in una singola richiesta a Hugging Face. Il valore predefinito è 128 e il valore deve essere maggiore di 0.

Passaggio 2: Inserire il testo grezzo

Inserisci il testo senza fornire vettori. Milvus chiama Hugging Face e scrive gli embedding generati su 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.",
        },
    ],
)

Passaggio 3: Ricerca con testo grezzo

Effettua una ricerca con una query testuale. Milvus applica la stessa configurazione della funzione per creare il vettore di query prima di eseguire la ricerca vettoriale.

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)

Il risultato contiene i documenti più pertinenti al testo della query, ordinati in base alla similarità coseno.

Risoluzione dei problemi

Il modello non è disponibile per l’estrazione delle caratteristiche

Apri la pagina del modello su Hugging Face e controlla la sezione "Inference Providers ". Verifica che hf-inference fornisca il modello per feature-extraction. In caso contrario, seleziona un altro modello e, se necessario, aggiorna la dimensione del campo vettoriale.

La dimensione del vettore restituito non corrisponde al campo

Controlla la dimensione dell’output del modello e confrontala con quella indicata su dim nel campo “Function output”. Milvus rifiuta una risposta la cui dimensione del vettore differisce da quella del campo “ FLOAT_VECTOR ”.

Milvus segnala la mancanza delle credenziali Hugging Face

Verifica che l’etichetta delle credenziali della Funzione esista nella sezione di primo livello “ credential ”, che l’etichetta a livello di provider sia valida o che “ MILVUS_HUGGINGFACE_API_KEY ” sia presente nell’ambiente di servizio di Milvus.

Prossimi passi

• Per i concetti generali relativi alle Funzioni e al comportamento di inserimento/ricerca, consultare Panoramica sulle Funzioni di embedding.
• Per ricalcolare il ranking dei candidati della ricerca vettoriale utilizzando i punteggi di similarità delle frasi di Hugging Face ospitati, consultare Hugging Face Ranker.