Home
Blog
Introduzione alla funzione di incorporazione: Come Milvus 2.6 semplifica la vettorizzazione e la ricerca semantica

Introduzione alla funzione di incorporazione: Come Milvus 2.6 semplifica la vettorizzazione e la ricerca semantica

Engineering

December 03, 2025

Xuqi Yang

Se avete mai costruito un'applicazione di ricerca vettoriale, conoscete già un po' troppo bene il flusso di lavoro. Prima che i dati possano essere memorizzati, devono essere trasformati in vettori utilizzando un modello di incorporamento, puliti e formattati e infine inseriti nel database vettoriale. Anche ogni query passa attraverso lo stesso processo: incorporare l'input, eseguire una ricerca di somiglianza, quindi mappare gli ID risultanti ai documenti o ai record originali. Funziona, ma crea un groviglio distribuito di script di preelaborazione, pipeline di incorporamento e codice collante da mantenere.

Milvus, un database vettoriale open-source ad alte prestazioni, compie ora un importante passo avanti verso la semplificazione di tutto questo. Milvus 2.6 introduce la funzione Data-in, Data-out (nota anche come Embedding Function), una funzionalità di embedding integrata che si collega direttamente ai principali fornitori di modelli come OpenAI, AWS Bedrock, Google Vertex AI e Hugging Face. Invece di gestire la vostra infrastruttura di incorporamento, Milvus può ora chiamare questi modelli per voi. È inoltre possibile inserire e interrogare il testo grezzo - e presto anche altri tipi di dati - mentre Milvus gestisce automaticamente la vettorizzazione in fase di scrittura e di interrogazione.

Nel resto del post, vedremo più da vicino come funziona Data-in, Data-out, come configurare i provider e le funzioni di incorporamento e come utilizzarli per ottimizzare i flussi di lavoro di ricerca vettoriale end-to-end.

Che cos'è Data-in, Data-out?

Data-in, Data-out in Milvus 2.6 si basa sul nuovo modulo Function, un framework che consente a Milvus di gestire la trasformazione dei dati e la generazione di incorporazioni internamente, senza servizi di preelaborazione esterni. (Con questo modulo, Milvus può prendere i dati di input grezzi, chiamare direttamente un fornitore di incorporazioni e scrivere automaticamente i vettori risultanti nella collezione.

Ad alto livello, il modulo Function trasforma la generazione di incorporazioni in una funzionalità nativa del database. Invece di eseguire pipeline di incorporamento separate, lavoratori in background o servizi di reranker, Milvus invia ora le richieste al provider configurato, recupera gli embedding e li memorizza insieme ai dati, il tutto all'interno del percorso di ingestione. In questo modo si elimina l'onere operativo di gestire la propria infrastruttura di incorporamento.

Data-in, Data-out introduce tre importanti miglioramenti al flusso di lavoro di Milvus:

Inserimento diretto di dati grezzi - È ora possibile inserire testi, immagini o altri tipi di dati non elaborati direttamente in Milvus. Non è necessario convertirli in vettori in anticipo.
Configurazione di una funzione di incorporazione - Una volta configurato un modello di incorporazione in Milvus, questo gestisce automaticamente l'intero processo di incorporazione. Milvus si integra perfettamente con una serie di fornitori di modelli, tra cui OpenAI, AWS Bedrock, Google Vertex AI, Cohere e Hugging Face.
Interrogazione con input grezzi - È ora possibile eseguire ricerche semantiche utilizzando testo grezzo o altre query basate sul contenuto. Milvus utilizza lo stesso modello configurato per generare embeddings al volo, eseguire ricerche di similarità e restituire risultati pertinenti.

In breve, Milvus ora incorpora automaticamente i dati e, facoltativamente, li riorganizza. La vettorizzazione diventa una funzione integrata del database, eliminando la necessità di servizi di embedding esterni o di logiche di preelaborazione personalizzate.

Come funziona Data-in, Data-out

Il diagramma seguente illustra il funzionamento di Data-in, Data-out all'interno di Milvus.

Il flusso di lavoro Data-in, Data-out può essere suddiviso in sei fasi principali:

Dati in ingresso - L'utente inserisce i dati grezzi - come testo, immagini o altri tipi di contenuto - direttamente in Milvus senza eseguire alcuna pre-elaborazione esterna.
Generare embeddings - Il modulo Function richiama automaticamente il modello di embedding configurato attraverso la sua API di terze parti, convertendo l'input grezzo in embeddings vettoriali in tempo reale.
Memorizza gli embeddings - Milvus scrive gli embeddings generati nel campo vettoriale designato all'interno della collezione, dove diventano disponibili per le operazioni di ricerca per similarità.
Invia una query - L'utente invia a Milvus una query di testo grezzo o basata sul contenuto, proprio come nella fase di input.
Ricerca semantica - Milvus incorpora la query utilizzando lo stesso modello configurato, esegue una ricerca di similarità sui vettori memorizzati e determina le corrispondenze semantiche più vicine.
Restituzione dei risultati - Milvus restituisce direttamente all'applicazione i risultati top-k più simili, mappati ai dati originali.

Come configurare Data-in, Data-out

Prerequisiti

Installare l'ultima versione di Milvus 2.6.
Preparare la chiave API di incorporamento da un provider supportato (ad esempio, OpenAI, AWS Bedrock o Cohere). In questo esempio, utilizzeremo Cohere come fornitore di embedding.

Modificare la configurazione di `milvus.yaml`

Se si esegue Milvus con Docker Compose, è necessario modificare il file milvus.yaml per abilitare il modulo Function. Per una guida si può fare riferimento alla documentazione ufficiale: Configurazione di Milvus con Docker Compose (qui si trovano anche le istruzioni per altri metodi di distribuzione).

Nel file di configurazione, individuare le sezioni credential e function.

Quindi, aggiornare i campi apikey1.apikey e providers.cohere.

...
credential:
  aksk1:
    access_key_id:  # Your access_key_id
    secret_access_key:  # Your secret_access_key
  apikey1:
    apikey: "***********************" # Edit this section
  gcp1:
    credential_json:  # base64 based gcp credential data
# Any configuration related to functions
function:
  textEmbedding:
    providers:
                        ...
      cohere: # Edit the section below
        credential:  apikey1 # The name in the crendential configuration item
        enable: true # Whether to enable cohere model service
        url:  "https://api.cohere.com/v2/embed" # Your cohere embedding url, Default is the official embedding url
      ...
...

Una volta apportate queste modifiche, riavviare Milvus per applicare la configurazione aggiornata.

Come utilizzare la funzione Data-in, Data-out

1. Definire lo schema della raccolta

Per abilitare la funzione di incorporamento, lo schema della raccolta deve includere almeno tre campi:

Campo chiave primaria (id ) - Identifica in modo univoco ogni entità della raccolta.
Campo scalare (document ) - Memorizza i dati grezzi originali.
Campo vettore (dense ) - Memorizza le incorporazioni vettoriali generate.

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) # Set dim according to the embedding model you use.

2. Definire la funzione di incorporazione

Definire quindi la funzione di incorporamento nello schema.

name - Un identificatore unico per la funzione.
function_type - Impostare FunctionType.TEXTEMBEDDING per le incorporazioni di testo. Milvus supporta anche altri tipi di funzione, come FunctionType.BM25 e FunctionType.RERANK. Per maggiori dettagli, si veda la sezione Ricerca di testi completi e Panoramica del Decay Ranker.
input_field_names - Definisce il campo di ingresso per i dati grezzi (document).
output_field_names - Definisce il campo di uscita in cui saranno memorizzate le incorporazioni vettoriali (dense).
params - Contiene i parametri di configurazione della funzione di embedding. I valori di provider e model_name devono corrispondere alle voci corrispondenti nel file di configurazione milvus.yaml.

Nota: Ogni funzione deve avere un unico name e output_field_names per distinguere le diverse logiche di trasformazione ed evitare conflitti.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="cohere_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": "cohere",                 # Embedding model provider
        "model_name": "embed-v4.0",     # 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)

3. Configurare l'indice

Una volta definiti i campi e le funzioni, creare un indice per la collezione. Per semplicità, si utilizza il tipo AUTOINDEX come esempio.

# 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" 
)

4. Creare la raccolta

Utilizzare lo schema e l'indice definiti per creare una nuova collezione. In questo esempio, creeremo una collezione chiamata Demo.

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

5. Inserire i dati

Ora è possibile inserire i dati grezzi direttamente in Milvus, senza dover generare embeddings manualmente.

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

6. Eseguire la ricerca vettoriale

Dopo aver inserito i dati, è possibile eseguire ricerche direttamente con query di testo grezzo. Milvus converte automaticamente la query in un embedding, esegue una ricerca di somiglianza con i vettori memorizzati e restituisce le migliori corrispondenze.

# 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.'}}]"]

Per maggiori dettagli sulla ricerca vettoriale, vedere: Ricerca vettoriale di base e Query API.

Iniziare con Milvus 2.6

Con Data-in, Data-out, Milvus 2.6 porta la semplicità della ricerca vettoriale a un livello superiore. Integrando le funzioni di embedding e reranking direttamente all'interno di Milvus, non è più necessario gestire una preelaborazione esterna o mantenere servizi di embedding separati.

Pronti a provarlo? Installate oggi stesso Milvus 2.6 e sperimentate voi stessi la potenza di Data-in, Data-out.

Avete domande o volete un approfondimento su una qualsiasi funzione? Unitevi al nostro canale Discord o inviate problemi su GitHub. È anche possibile prenotare una sessione individuale di 20 minuti per ottenere approfondimenti, indicazioni e risposte alle vostre domande tramite Milvus Office Hours.