Panoramica della funzione di incorporamentoCompatible with Milvus 2.6.x

Il modulo Function di Milvus consente di trasformare i dati di testo grezzi in embedding vettoriali chiamando automaticamente i fornitori esterni di servizi di embedding (come OpenAI, AWS Bedrock, Google Vertex AI, ecc.). Con il modulo Function, non è più necessario interfacciarsi manualmente con le API di embedding: Milvus gestisce l'intero processo di invio delle richieste ai provider, la ricezione degli embedding e la loro memorizzazione nelle collezioni. Per la ricerca semantica, è necessario fornire solo i dati grezzi della query, non un vettore di query. Milvus genera il vettore di query con lo stesso modello utilizzato per l'ingestion, lo confronta con i vettori memorizzati e restituisce i risultati più rilevanti.

Limiti

• Qualsiasi campo di input che il modulo Function incorpora deve sempre contenere un valore; se viene fornito un null, il modulo lancia un errore.

• Il modulo Function elabora solo i campi definiti esplicitamente nello schema della collezione; non genera incorporazioni per i campi dinamici.

• I campi di input da incorporare devono essere del tipo VARCHAR.

• Il modulo Function può incorporare un campo di input in:

  • FLOAT_VECTOR

  • INT8_VECTOR

  Non sono supportate le conversioni in BINARY_VECTOR, FLOAT16_VECTOR o BFLOAT16_VECTOR.

Fornitori di servizi di incorporamento supportati

Fornitore	Modelli tipici	Tipo di incorporamento	Metodo di autenticazione
OpenAI	testo-incorporamento-3-*	FLOAT_VECTOR	Chiave API
Azure OpenAI	Basato sulla distribuzione	FLOAT_VECTOR	Chiave API
DashScope	testo-embedding-v3	FLOAT_VECTOR	Chiave API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Coppia AK/SK
Vertice AI	testo-embedding-005	FLOAT_VECTOR	Credenziale JSON dell'account del servizio GCP
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Chiave API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Chiave API
SiliconFlow	BAAI/bge-grande-zh-v1.5	FLOAT_VECTOR	Chiave API
Faccia da abbracciare	Qualsiasi modello servito da TEI	FLOAT_VECTOR	Chiave API opzionale

Come funziona

Il diagramma seguente mostra il funzionamento della funzione in Milvus.

1. Testo in ingresso: Gli utenti inseriscono in Milvus i dati grezzi (ad esempio i documenti).

2. Generazione degli embeddings: Il modulo Function di Milvus chiama automaticamente il fornitore di modelli configurato per convertire i dati grezzi in embeddings vettoriali.

3. Memorizzare gli embeddings: Gli embeddings risultanti vengono memorizzati in campi vettoriali esplicitamente definiti all'interno delle collezioni di Milvus.

4. Interrogazione del testo: Gli utenti inviano query testuali a Milvus.

5. Ricerca semantica: Milvus converte internamente le query in embeddings vettoriali, effettua ricerche di somiglianza con gli embeddings memorizzati e recupera i risultati rilevanti.

6. Restituzione dei risultati: Milvus restituisce all'applicazione i risultati migliori.

Panoramica delle funzioni di incorporamento

Configurazione delle credenziali

Prima di utilizzare una funzione di embedding con Milvus, configurare le credenziali del servizio di embedding per l'accesso a Milvus.

Milvus consente di fornire le credenziali del servizio di embedding in due modi:

• File di configurazione (milvus.yaml):

  L'esempio di questo argomento mostra la configurazione consigliata utilizzando milvus.yaml.

• Variabili d'ambiente:

  Per informazioni dettagliate sulla configurazione delle credenziali tramite variabili d'ambiente, consultare la documentazione del fornitore del servizio di embedding (ad esempio, OpenAI o Azure OpenAI).

Il diagramma seguente mostra il processo di configurazione delle credenziali tramite il file di configurazione di Milvus (milvus.yaml) e quindi il richiamo della Funzione all'interno di Milvus.

Overflow della configurazione delle credenziali

Passo 1: Aggiungere le credenziali al file di configurazione di Milvus

Nel file milvus.yaml, modificare il blocco credential con le voci per ogni provider a cui si deve accedere:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

Passo 2: Configurare le impostazioni del provider

Nello stesso file di configurazione (milvus.yaml), modificare il blocco function per indicare a Milvus quale chiave utilizzare per incorporare le chiamate di servizio:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Per ulteriori informazioni su come applicare la configurazione di Milvus, fate riferimento a Configurare Milvus al volo.

Utilizzare la funzione di incorporamento

Una volta configurate le credenziali nel file di configurazione di Milvus, seguite 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" 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, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

Passo 2: Aggiungere la funzione di incorporamento 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 (openai_embedding) che converte il campo scalare "document" in embedding, memorizzando i vettori risultanti nel campo vettoriale "dense" definito in precedenza.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_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": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

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

// java

// nodejs

// go

# restful

Parametro	Descrizione	Esempio Valore
name	Identificatore univoco della funzione di embedding all'interno di Milvus.	"openai_embedding"
function_type	Tipo di funzione utilizzata. Per l'incorporazione del testo, impostare il valore su FunctionType.TEXTEMBEDDING. Nota: Milvus accetta FunctionType.BM25 (per la trasformazione sparse-embedding) e FunctionType.RERANK (per il reranking) per questo parametro. Per maggiori dettagli, consultare la sezione Ricerca di testi completi e Panoramica del Decay Ranker.	FunctionType.TEXTEMBEDDING
input_field_names	Campo scalare contenente i dati grezzi da incorporare. Attualmente, questo parametro accetta solo un nome di campo.	["document"]
output_field_names	Campo vettoriale per la memorizzazione delle incorporazioni generate. Attualmente, questo parametro accetta solo un nome di campo.	["dense"]
params	Dizionario contenente le configurazioni di incorporamento. Nota: i parametri di params variano a seconda dei fornitori di modelli di incorporazione.	{...}
provider	Il fornitore del modello di incorporamento.	"openai"
model_name	Specifica quale modello di incorporamento utilizzare.	"text-embedding-3-small"
credential	L'etichetta di una credenziale definita nella sezione di primo livello credential: di milvus.yaml. Se fornita, Milvus recupera la coppia di chiavi o il token API corrispondente e firma la richiesta sul lato server. Se omesso (None), Milvus ricorre alla credenziale esplicitamente configurata per il fornitore del modello di destinazione in milvus.yaml. Se l'etichetta è sconosciuta o la chiave di riferimento è mancante, la chiamata fallisce.	"apikey1"
dim	Il numero di dimensioni per gli embeddings in uscita. Per i modelli di terza generazione di OpenAI, è possibile accorciare il vettore completo per ridurre i costi e la latenza senza una perdita significativa di informazioni semantiche. Per ulteriori informazioni, consultare il post di annuncio di OpenAI. Nota: se si accorcia la dimensione del vettore, assicurarsi che il valore dim specificato nel metodo add_field dello schema per il campo vettoriale corrisponda alla dimensione finale della funzione di incorporamento.	"1536"
user	Un identificatore a livello utente per tracciare l'uso dell'API.	"user123"

Passo 3: Configurare l'indice

Dopo aver definito lo schema con i campi necessari e la funzione incorporata, impostare l'indice per la raccolta. 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" 
)

// java

// nodejs

// go

# restful

Passo 4: Creare la collezione

Ora si crea 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
)

// java

// nodejs

// go

# restful

Passo 5: Inserire i dati

Dopo aver impostato 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.'},
])

// java

// nodejs

// go

# restful

Passo 6: Eseguire la ricerca vettoriale

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)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

// java

// nodejs

// go

# restful

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

DOMANDE FREQUENTI

Qual è la differenza tra la configurazione delle credenziali in milvus.yaml e le variabili d'ambiente?

Entrambi i metodi funzionano, ma l'uso di milvus.yaml è l'approccio consigliato, in quanto fornisce una gestione centralizzata delle credenziali e una denominazione coerente delle credenziali tra tutti i provider. Quando si usano le variabili d'ambiente, i nomi delle variabili variano a seconda del fornitore del servizio di embedding, quindi si consiglia di consultare la pagina dedicata di ciascun fornitore per capire i nomi specifici delle variabili d'ambiente richiesti (ad esempio, OpenAI o Azure OpenAI).

Cosa succede se non si specifica un parametro di credenziale nella definizione della funzione?

Milvus segue questo ordine di risoluzione delle credenziali:

1. Per prima cosa, cerca la credenziale predefinita configurata per quel provider nel file milvus.yaml.
2. Se non esistono credenziali predefinite in milvus.yaml, si ricorre alle variabili d'ambiente (se configurate).
3. Se non sono configurate né le credenziali di milvus.yaml né le variabili d'ambiente, Milvus lancia un errore.

Come posso verificare che gli embeddings siano generati correttamente?

È possibile verificare

1. interrogando la collezione dopo l'inserimento per vedere se il campo vettoriale contiene dei dati
2. verificando che la lunghezza del campo vettoriale corrisponda alle dimensioni previste
3. Eseguendo una semplice ricerca di similarità per verificare che le incorporazioni producano risultati significativi.

Quando eseguo una ricerca di similarità, posso usare un vettore di query invece del testo grezzo?

Sì, è possibile utilizzare vettori di query precalcolati invece di testo grezzo per la ricerca di similarità. Mentre il modulo Function converte automaticamente le query di testo grezzo in embedding, è possibile fornire direttamente i dati vettoriali al parametro data nelle operazioni di ricerca. Nota: la dimensione del vettore di query fornito deve essere coerente con la dimensione delle incorporazioni vettoriali generate dal modulo Function.

Esempio:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

// java

// nodejs

// go

# restful