Hugging Face TEICompatible with Milvus 2.6.x

Hugging Face Text Embeddings Inference (TEI) è un server di inferenza ad alte prestazioni progettato specificamente per i modelli di incorporazione del testo. Questa guida spiega come utilizzare Hugging Face TEI con Milvus per una generazione efficiente di incorporazioni di testo.

TEI funziona con molti modelli di text embedding di Hugging Face Hub, tra cui:

• serie BAAI/bge-*

• serie sentence-transformers/*

• Modelli E5

• Modelli GTE

• E molti altri

Distribuzione TEI

Prima di configurare Milvus con la funzione TEI, è necessario disporre di un servizio TEI funzionante. Milvus supporta due approcci per la distribuzione TEI:

Distribuzione standard (esterna)

È possibile distribuire TEI come servizio autonomo utilizzando i metodi ufficiali di Hugging Face. Questo approccio offre la massima flessibilità e controllo sul servizio TEI.

Per istruzioni dettagliate sulla distribuzione di TEI utilizzando Docker o altri metodi, consultare la documentazione ufficiale di Hugging Face Text Embeddings Inference.

Dopo la distribuzione, prendere nota dell'endpoint del servizio TEI (ad esempio, http://localhost:8080), in quanto sarà necessario quando si utilizzerà la funzione TEI in Milvus.

Distribuzione di Milvus Helm Chart (integrato)

Per gli ambienti Kubernetes, Milvus offre un'opzione di distribuzione integrata attraverso il grafico Helm. Questo semplifica il processo di distribuzione e configurazione di TEI insieme a Milvus.

Per abilitare TEI nella distribuzione di Milvus Helm:

1. Configurare values.yaml per abilitare TEI:

   tei:
     enabled: true
     image:
       repository: ghcr.io/huggingface/text-embeddings-inference
       tag: "1.7" # Modify based on hardware
     model: "BAAI/bge-large-en-v1.5" # Modify based on requirements
     # revision: "main"
     # hfTokenSecretName: "my-huggingface-token-secret"
     # apiKey: "your_secure_api_key"
     # apiKeySecret:
     #   name: "my-tei-api-key-secret"
     #   key: "api-key"
     resources:
       requests:
         cpu: "1"
         memory: "4Gi"
         # nvidia.com/gpu: "1" # For GPU
       limits:
         cpu: "2"
         memory: "8Gi"
         # nvidia.com/gpu: "1" # For GPU
     extraArgs: []
   
   

2. Distribuire o aggiornare Milvus:

   helm install my-release milvus/milvus -f values.yaml -n <your-milvus-namespace>
   # or
   helm upgrade my-release milvus/milvus -f values.yaml --reset-then-reuse-values -n <your-milvus-namespace>
   

   Quando si utilizza il deployment grafico Helm, il servizio TEI sarà accessibile all'interno del cluster Kubernetes all'indirizzo http://my-release-milvus-tei:80 (utilizzando il nome della release). Utilizzare questo come endpoint nella configurazione della funzione TEI.

Configurazione in Milvus

Dopo aver distribuito il servizio TEI, è necessario fornire il suo endpoint quando si definisce una funzione di incorporamento TEI. Nella maggior parte dei casi, non è necessaria alcuna configurazione aggiuntiva, poiché TEI è abilitato per impostazione predefinita in Milvus.

Tuttavia, se il servizio TEI è stato distribuito con l'autenticazione della chiave API (flag--api-key ), è necessario configurare Milvus per utilizzare questa chiave:

1. Definire le chiavi API nella sezione credential:

   # milvus.yaml
   credential:
     tei_key:  # You can use any label name
       apikey: <YOUR_TEI_API_KEY>
   

2. Fare riferimento alla credenziale in milvus.yaml:

   function:
     textEmbedding:
       providers:
         tei:
           credential: tei_key      # ← choose any label you defined above
           enable: true # enabled by default. no action required.
   

Utilizzare la funzione di incorporamento

Una volta configurato il servizio TEI, seguire questi passaggi per definire e utilizzare le funzioni di incorporamento.

Passo 1: Definire i campi dello schema

Per utilizzare una funzione di incorporamento, creare una raccolta con uno schema specifico. Questo schema deve includere almeno tre campi necessari:

• Il campo primario che identifica in modo univoco ogni entità della raccolta.

• Un campo scalare che memorizza i dati grezzi da incorporare.

• Un campo vettoriale riservato a memorizzare le incorporazioni vettoriali che la funzione genererà per il campo scalare.

L'esempio seguente definisce uno schema con un campo scalare "document" per memorizzare i dati testuali e un campo vettoriale "dense_vector" per memorizzare le incorporazioni che saranno generate dal modulo Function. Ricordarsi di impostare la dimensione del vettore (dim) in modo che corrisponda all'output del modello di embedding scelto.

from pymilvus import MilvusClient, DataType, Function, FunctionType, CollectionSchema, FieldSchema

# Assume you have connected to Milvus
# client = MilvusClient(uri="http://localhost:19530")

# 1. Create Schema
schema = MilvusClient.create_schema()

# 2. Add fields
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=9000) # Store text data
# IMPORTANT: Set dim to exactly match the TEI model's output dimension
schema.add_field("dense_vector", DataType.FLOAT_VECTOR, dim=1024) # Store embedding vectors (example dimension)

Passo 2: Aggiungere la funzione di embedding allo schema

Il modulo Function di Milvus converte automaticamente i dati grezzi memorizzati in un campo scalare in embedding e li memorizza nel campo vettoriale esplicitamente definito.

L'esempio seguente aggiunge un modulo Function (tei_func) che converte il campo scalare "document" in embedding, memorizzando i vettori risultanti nel campo vettoriale "dense_vector" definito in precedenza.

Una volta definita la funzione di embedding, aggiungerla allo schema della collezione. In questo modo si indica a Milvus di utilizzare la funzione di embedding specificata per elaborare e memorizzare gli embeddings dei dati di testo.

# 3. Define TEI embedding function
text_embedding_function = Function(
    name="tei_func",                            # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,   # Indicates a text embedding function
    input_field_names=["document"],             # Scalar field(s) containing text data to embed
    output_field_names=["dense_vector"],        # Vector field(s) for storing embeddings
    params={                                    # TEI specific parameters (function-level)
        "provider": "TEI",                      # Must be set to "TEI"
        "endpoint": "http://your-tei-service-endpoint:80", # Required: Points to your TEI service address
        # Optional parameters:
        # "truncate": "true",                   # Optional: Whether to truncate long input (default false)
        # "truncation_direction": "right",      # Optional: Truncation direction (default right)
        # "max_client_batch_size": 64,          # Optional: Client max batch size (default 32)
        # "ingestion_prompt": "passage: ",      # Optional: (Advanced) Ingestion phase prompt
        # "search_prompt": "query: "            # Optional: (Advanced) Search phase prompt
    }
)

# Add the configured embedding function to your existing collection schema
schema.add_function(text_embedding_function)

Parametro	Richiesto?	Descrizione	Esempio Valore
provider	Sì	Il fornitore del modello di incorporazione. Impostare su "TEI".	"TEI"
endpoint	Sì	L'indirizzo di rete che punta al servizio TEI distribuito. Se distribuito tramite Milvus Helm Chart, di solito è l'indirizzo interno del servizio.	"http://localhost:8080", "http://my-release-milvus-tei:80"
truncate	No	Se troncare o meno i testi in ingresso che superano la lunghezza massima del modello. L'impostazione predefinita è false.	"true"
truncation_direction	No	Efficace quando truncate è true. Specifica se troncare da sinistra o da destra. L'impostazione predefinita è destra.	"sinistra"
max_client_batch_size	No	La dimensione massima del batch che il client Milvus invia a TEI. L'impostazione predefinita è 32.	64
prompt_name	No	(Avanzato) Specifica una chiave nel dizionario dei prompt della configurazione dei trasformatori di frasi. Si usa per alcuni modelli che richiedono formati di prompt specifici. Il supporto TEI potrebbe essere limitato e dipende dalla configurazione del modello sull'Hub.	"la_tua_chiave_di_prompt"
ingestion_prompt	No	(Avanzato) Specifica il prompt da usare durante la fase di inserimento dei dati (ingestion). Dipende dal modello TEI utilizzato; il modello deve supportare i prompt.	"passage: "
search_prompt	No	(Avanzato) Specifica il prompt da usare durante la fase di ricerca. Dipende dal modello TEI utilizzato; il modello deve supportare i prompt.	"query: "

Passi successivi

Dopo aver configurato la funzione di incorporamento, consultare la Panoramica della funzione per ulteriori indicazioni sulla configurazione dell'indice, sugli esempi di inserimento dei dati e sulle operazioni di ricerca semantica.