Google Gemini

Utilizzate un modello di incorporamento di Google Gemini con Milvus scegliendo un modello e configurando Milvus con la vostra chiave API Gemini.

Scegliere un modello di incorporamento

Milvus supporta i modelli di incorporamento forniti da Google Gemini. Di seguito sono riportati i modelli di incorporamento Gemini attualmente disponibili per un rapido riferimento:

Nome del modello	Dimensioni	Gettoni massimi	Descrizione
gemini-embedding-001	Predefinito: 3.072 (consigliato: 768, 1.536 o 3.072)	8,192	Modello di incorporamento del testo con dimensioni flessibili, addestrato con Matryoshka Representation Learning (MRL).
gemini-embedding-2	Predefinito: 3.072 (consigliato: 768, 1.536 o 3.072)	8,192	Il primo modello di incorporamento multimodale di Google, che supporta testo, immagini, video, audio e documenti in uno spazio di incorporamento unificato.

Entrambi i modelli sono addestrati con la tecnica Matryoshka Representation Learning (MRL), che consente dimensioni di output flessibili tramite il parametro dim. Si consiglia di iniziare con 768 dimensioni e di scalare fino a 1.536 o 3.072 se necessario. Per maggiori dettagli, consultare i modelli di incorporazione Gemini.

I modelli di incorporazione Gemini supportano anche un parametro di tipo di compito che ottimizza le incorporazioni per casi d'uso specifici. Milvus imposta automaticamente il tipo di attività in base all'operazione:

• Insert / Upsert: RETRIEVAL_DOCUMENT

• Ricerca: RETRIEVAL_QUERY

È possibile sovrascrivere questa impostazione specificando esplicitamente un parametro task (ad esempio, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING).

Configurare le credenziali

Milvus deve conoscere la chiave API Gemini prima di poter richiedere le incorporazioni. Milvus offre due metodi per configurare le credenziali:

• File di configurazione (consigliato): Memorizzare la chiave API in milvus.yaml in modo che ogni riavvio e nodo la rilevi automaticamente.

• Variabili d'ambiente: Iniettare la chiave al momento della distribuzione, ideale per Docker Compose.

Scegliete uno dei due metodi seguenti: il file di configurazione è più facile da mantenere su macchine virtuali e bare-metal, mentre la via delle variabili d'ambiente si adatta ai flussi di lavoro dei container.

Se una chiave API per lo stesso provider è presente sia nel file di configurazione che in una variabile d'ambiente, Milvus utilizza sempre il valore in milvus.yaml e ignora la variabile d'ambiente.

Opzione 1: File di configurazione (consigliata e con priorità più alta)

Mantenere le chiavi API in milvus.yaml; Milvus le legge all'avvio e sovrascrive qualsiasi variabile d'ambiente per lo stesso provider.

1. Dichiarare le chiavi sotto credenziali:

   Si possono elencare una o più chiavi API, dando a ciascuna un'etichetta inventata e a cui si farà riferimento in seguito.

   # milvus.yaml
   credential:
     apikey_dev:            # dev environment
       apikey: <YOUR_DEV_KEY>
     apikey_prod:           # production environment
       apikey: <YOUR_PROD_KEY>    
   

   Mettere le chiavi API in questo punto le rende persistenti tra i vari riavvii e consente di cambiare le chiavi semplicemente cambiando l'etichetta.

2. Indicare a Milvus quale chiave usare per le chiamate a Gemini

   Nello stesso file, si indica al provider Gemini l'etichetta che si desidera utilizzare.

   function:
     textEmbedding:
       providers:
         gemini:
           credential: apikey_dev      # ← choose any label you defined above
   

   Questo vincola una chiave specifica a ogni richiesta che Milvus invia all'endpoint Gemini embeddings.

Opzione 2: variabile d'ambiente

Utilizzate questo metodo quando eseguite Milvus con Docker Compose e preferite tenere i segreti fuori dai file e dalle immagini.

Milvus ricorre alla variabile d'ambiente solo se non viene trovata alcuna chiave per il provider in milvus.yaml.

Variabile	Richiesto	Descrizione
MILVUS_GEMINI_API_KEY	Sì	Rende disponibile la chiave Gemini all'interno di ogni contenitore Milvus (ignorata se esiste una chiave per Gemini in milvus.yaml).

Nel file docker-compose.yaml, impostare la variabile d'ambiente MILVUS_GEMINI_API_KEY.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Gemini API key inside the container
    MILVUS_GEMINI_API_KEY: <YOUR_GEMINI_API_KEY>

Il blocco environment: inietta la chiave solo nel contenitore Milvus, lasciando inalterato il sistema operativo host. Per maggiori dettagli, consultare Configurazione di Milvus con Docker Compose.

Passo 1: Creare una collezione con una funzione di incorporamento del testo

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 VARCHAR che memorizza i dati grezzi da incorporare.

• Un campo vettoriale riservato per memorizzare le incorporazioni vettoriali dense che la funzione di incorporazione del testo genererà per il campo VARCHAR.

L'esempio seguente definisce uno schema con un campo scalare "document" per memorizzare i dati testuali e un campo vettoriale "dense" 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

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, Gemini's gemini-embedding-001 model outputs 3072-dimensional vectors by default,
# but can be shortened to 768 or 1536 dimensions.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=768)

Definire la funzione di incorporazione del testo

La funzione di incorporazione del testo converte automaticamente i dati grezzi memorizzati in un campo VARCHAR in embeddings e li memorizza nel campo vettoriale esplicitamente definito.

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

# Define embedding function (example: Gemini provider)
text_embedding_function = Function(
    name="gemini_embedding",                        # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,       # Type of embedding function
    input_field_names=["document"],                 # Scalar field to embed
    output_field_names=["dense"],                   # Vector field to store embeddings
    params={                                        # Provider-specific configuration (highest priority)
        "provider": "gemini",                       # Embedding model provider
        "model_name": "gemini-embedding-001",       # Embedding model
        # Optional parameters:
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "768",                             # Optional: Output vector dimension (default 3072)
        # "task": "RETRIEVAL_DOCUMENT",             # Optional: Task type for embedding optimization
    }
)

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

Tipi di task supportati per il parametro task:

• RETRIEVAL_DOCUMENT - Ottimizza gli embeddings per l'indicizzazione dei documenti (predefinito per insert/upsert).

• RETRIEVAL_QUERY - Ottimizza gli embeddings per il recupero delle query (default per la ricerca).

• SEMANTIC_SIMILARITY - Ottimizza gli embeddings per la misurazione della similarità del testo.

• CLASSIFICATION - Ottimizza le incorporazioni per la classificazione del testo.

• CLUSTERING - Ottimizza le incorporazioni per il clustering.

Quando non è impostato esplicitamente, Milvus utilizza automaticamente RETRIEVAL_DOCUMENT durante l'inserimento/aggiornamento e RETRIEVAL_QUERY durante la ricerca.

Configurare l'indice

Dopo aver definito lo schema con i campi necessari e la funzione incorporata, configurare l'indice per la collezione. Per semplificare questo processo, utilizzare AUTOINDEX come index_type, un'opzione che consente a Milvus di scegliere e configurare il tipo di indice più adatto in base alla struttura dei dati.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

Creare la collezione

Creare ora la collezione utilizzando lo schema e i parametri dell'indice definiti.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

Fase 2: inserimento dei dati

Dopo aver configurato la collezione e l'indice, si è pronti a inserire i dati grezzi. In questo processo, è sufficiente fornire il testo grezzo. Il modulo Function, definito in precedenza, genera automaticamente il vettore sparse corrispondente per ogni voce di testo.

# Insert sample documents
client.insert('demo', [
    {'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.'},
])

Fase 3: Ricerca con il testo

Dopo l'inserimento dei dati, è possibile eseguire una ricerca semantica utilizzando il testo grezzo della query. Milvus converte automaticamente la query in un vettore di incorporamento, recupera i documenti pertinenti in base alla somiglianza e restituisce i risultati più corrispondenti.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

Per ulteriori informazioni sulle operazioni di ricerca e interrogazione, consultare Ricerca vettoriale e interrogazione di base.