Azure OpenAICompatible with Milvus 2.6.x

Questo argomento descrive come configurare e utilizzare le funzioni di incorporamento di Azure OpenAI in Milvus.

Scegliere un modello di incorporamento

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

Modello	Dimensioni	Gettoni massimi	Descrizione
testo-embedding-3-piccolo	Predefinito: 1.536 (può essere ridotto a una dimensione inferiore a 1536)	8,191	Ideale per la ricerca semantica scalabile e sensibile ai costi, offre prestazioni elevate a un prezzo inferiore.
testo-embedding-3-grande	Predefinito: 3.072 (riconducibile a una dimensione inferiore a 3072)	8,191	Ideale per le applicazioni che richiedono una maggiore precisione di recupero e rappresentazioni semantiche più ricche.
testo-embedding-ada-002	Fisso: 1.536 (non supporta il troncamento)	8,191	Un modello di generazione precedente adatto a pipeline legacy o a scenari che richiedono compatibilità con il passato.

I modelli di incorporazione di terza generazione(text-embedding-3) supportano la riduzione delle dimensioni dell'incorporazione tramite un parametro dim. In genere le incorporazioni più grandi sono più costose dal punto di vista del calcolo, della memoria e dello storage. La possibilità di regolare il numero di dimensioni permette di controllare meglio i costi e le prestazioni complessive. Per maggiori dettagli su ciascun modello, consultare Embeddings.

Configurare le credenziali

Milvus deve conoscere la chiave API Azure OpenAI prima di poter richiedere gli embeddings. 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.

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 in credential:

   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 utilizzare per le chiamate ad Azure OpenAI

   Nello stesso file, indicare al provider Azure OpenAI l'etichetta che si desidera utilizzare.

   function:
     textEmbedding:
       providers:
         azure_openai:
           credential: apikey_dev      # ← choose any label you defined above
           resource_name:  # Your azure openai resource name
           # url: # Your azure openai embedding url
   

   In questo modo si lega una chiave specifica a ogni richiesta che Milvus invia all'endpoint Azure OpenAI embeddings.

Opzione 2: Variabili 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
MILVUSAI_AZURE_OPENAI_API_KEY	Sì	Rende disponibile la chiave di Azure OpenAI all'interno di ogni contenitore Milvus (ignorata se esiste una chiave per Azure OpenAI in milvus.yaml ).
MILVUSAI_AZURE_OPENAI_RESOURCE_NAME	Sì	Il nome della risorsa Azure OpenAI definito al momento della creazione della risorsa del servizio Azure OpenAI.

Nel file docker-compose.yaml, impostare le variabili d'ambiente.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Azure OpenAI API key inside the container
    MILVUSAI_AZURE_OPENAI_API_KEY: <MILVUSAI_AZURE_OPENAI_API_KEY>
    MILVUSAI_AZURE_OPENAI_RESOURCE_NAME: <MILVUSAI_AZURE_OPENAI_RESOURCE_NAME>

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.

Utilizzare la funzione di incorporamento

Una volta configurate le credenziali, 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 gli embeddings che saranno generati 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.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

Passo 2: Aggiungere la funzione di embedding allo schema

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

# Define embedding function specifically for Azure OpenAI provider
text_embedding_function = Function(
    name="azopenai",                                # 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 field(s) for storing embeddings
    params={                                        # Provider-specific embedding parameters
        "provider": "azure_openai",                 # Embedding provider name (must be "azure_openai")
        "model_name": "zilliz-text-embedding-3-small",      # Model should be set to the deployment name you chose when you deployed the embedding model
        # Optional parameters (only specify if necessary):
        # "url": "https://{resource_name}.openai.azure.com/" # Optional: Your Azure OpenAI service endpoint
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "1536",                            # Optional: Shorten the output vector dimension
        # "user": "user123",                        # Optional: identifier for API tracking
    }
)

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

Passi successivi

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