Aperçu de la fonction d'intégrationCompatible with Milvus 2.6.x

Le module Function de Milvus vous permet de transformer des données textuelles brutes en embeddings vectoriels en appelant automatiquement des fournisseurs de services d'embedding externes (comme OpenAI, AWS Bedrock, Google Vertex AI, etc.). Avec le module Function, vous n'avez plus besoin de vous interfacer manuellement avec les API d'intégration - Milvus prend en charge l'ensemble du processus d'envoi des demandes aux fournisseurs, de réception des intégrations et de leur stockage dans vos collections. Pour la recherche sémantique, vous ne devez fournir que des données de requête brutes, et non un vecteur de requête. Milvus génère le vecteur de requête avec le même modèle que celui utilisé pour l'ingestion, le compare aux vecteurs stockés et renvoie les résultats les plus pertinents.

Limites

• Tout champ d'entrée que le module Function intègre doit toujours contenir une valeur ; si une valeur nulle est fournie, le module génère une erreur.

• Le module Function ne traite que les champs explicitement définis dans le schéma de la collection ; il ne génère pas d'intégration pour les champs dynamiques.

• Les champs d'entrée à intégrer doivent être de type VARCHAR.

• Le module Function peut intégrer un champ d'entrée à :

  • FLOAT_VECTOR

  • INT8_VECTOR

  Les conversions vers BINARY_VECTOR, FLOAT16_VECTOR ou BFLOAT16_VECTOR ne sont pas prises en charge.

Fournisseurs de services d'intégration pris en charge

Fournisseur	Modèles typiques	Type d'intégration	Méthode d'authentification
OpenAI	texte-embedding-3-*	FLOAT_VECTOR	Clé API
Azure OpenAI	Basé sur le déploiement	FLOAT_VECTOR	Clé API
DashScope	text-embedding-v3	FLOAT_VECTOR	Clé API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Paire AK/SK
Vertex AI	texte-embedding-005	FLOAT_VECTOR	Identifiant JSON du compte de service GCP
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Clé API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Clé API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	Clé API
Visage étreint	Tout modèle desservi par le TEI	FLOAT_VECTOR	Clé API optionnelle

Fonctionnement

Le diagramme suivant montre comment la fonction fonctionne dans Milvus.

1. Texte d'entrée: Les utilisateurs insèrent des données brutes (par exemple des documents) dans Milvus.

2. Générer des embeddings: Le module Function de Milvus appelle automatiquement le fournisseur de modèle configuré pour convertir les données brutes en embeddings vectoriels.

3. Stocker les embeddings: Les embeddings résultants sont stockés dans des champs vectoriels explicitement définis dans les collections Milvus.

4. Interroger le texte: Les utilisateurs soumettent des requêtes textuelles à Milvus.

5. Recherche sémantique: Milvus convertit en interne les requêtes en intégrations vectorielles, effectue des recherches de similarité par rapport aux intégrations stockées et récupère les résultats pertinents.

6. Renvoi des résultats: Milvus renvoie les meilleurs résultats à l'application.

Présentation de la fonction d'intégration

Configuration des informations d'identification

Avant d'utiliser une fonction d'intégration avec Milvus, configurez les informations d'identification du service d'intégration pour l'accès à Milvus.

Milvus vous permet de fournir des informations d'identification de service d'intégration de deux manières :

• Fichier de configuration (milvus.yaml) :

  L'exemple de cette rubrique présente la configuration recommandée à l'aide de milvus.yaml.

• Variables d'environnement:

  Pour plus de détails sur la configuration des informations d'identification via les variables d'environnement, voir la documentation du fournisseur du service d'intégration (par exemple, OpenAI ou Azure OpenAI).

Le diagramme suivant illustre le processus de configuration des informations d'identification via le fichier de configuration Milvus (milvus.yaml), puis l'appel de la fonction dans Milvus.

Débordement de la configuration des informations d'identification

Étape 1 : Ajouter les informations d'identification au fichier de configuration Milvus

Dans votre fichier milvus.yaml, modifiez le bloc credential avec des entrées pour chaque fournisseur auquel vous devez accéder :

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

Etape 2 : Configurer les paramètres du fournisseur

Dans le même fichier de configuration (milvus.yaml), modifiez le bloc function pour indiquer à Milvus la clé à utiliser pour intégrer les appels de service :

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

Pour plus d'informations sur l'application de la configuration de Milvus, voir Configurer Milvus à la volée.

Utiliser la fonction d'intégration

Une fois les informations d'identification configurées dans votre fichier de configuration Milvus, suivez ces étapes pour définir et utiliser les fonctions d'intégration.

Etape 1 : Définir les champs du schéma

Pour utiliser une fonction d'intégration, créez une collection avec un schéma spécifique. Ce schéma doit comprendre au moins trois champs nécessaires :

• Le champ primaire qui identifie de manière unique chaque entité d'une collection.

• Un champ scalaire qui stocke les données brutes à intégrer.

• Un champ vectoriel réservé au stockage des intégrations vectorielles que la fonction générera pour le champ scalaire.

L'exemple suivant définit un schéma avec un champ scalaire "document" pour stocker les données textuelles et un champ vectoriel "dense" pour stocker les embeddings qui seront générés par le module Function. N'oubliez pas de définir la dimension du vecteur (dim) pour qu'elle corresponde à la sortie du modèle d'intégration que vous avez choisi.

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

Étape 2 : Ajouter la fonction d'intégration au schéma

Le module Function de Milvus convertit automatiquement les données brutes stockées dans un champ scalaire en embeddings et les stocke dans le champ vectoriel explicitement défini.

L'exemple ci-dessous ajoute un module Function (openai_embedding) qui convertit le champ scalaire "document" en embeddings, en stockant les vecteurs résultants dans le champ vectoriel "dense" défini précédemment.

# 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

Paramètre	Paramètre Description	Exemple Valeur
name	Identifiant unique de la fonction d'intégration dans Milvus.	"openai_embedding"
function_type	Type de fonction utilisée. Pour l'incorporation de texte, définir la valeur sur FunctionType.TEXTEMBEDDING. Remarque: Milvus accepte les valeurs FunctionType.BM25 (pour la transformation d'intégration éparse) et FunctionType.RERANK (pour le reranking) pour ce paramètre. Pour plus de détails, reportez-vous à la section Recherche dans le texte intégral et à l'aperçu du classificateur de décroissance.	FunctionType.TEXTEMBEDDING
input_field_names	Champ scalaire contenant les données brutes à intégrer. Actuellement, ce paramètre n'accepte qu'un seul nom de champ.	["document"]
output_field_names	Champ vectoriel pour le stockage des données intégrées générées. Actuellement, ce paramètre n'accepte qu'un seul nom de champ.	["dense"]
params	Dictionnaire contenant les configurations d'intégration. Remarque : les paramètres de params varient en fonction des fournisseurs de modèles d'intégration.	{...}
provider	Le fournisseur du modèle d'intégration.	"openai"
model_name	Spécifie le modèle d'intégration à utiliser.	"text-embedding-3-small"
credential	L'étiquette d'un titre défini dans la section de haut niveau credential: de milvus.yaml. Lorsqu'il est fourni, Milvus récupère la paire de clés ou le jeton API correspondant et signe la demande côté serveur. En cas d'omission (None), Milvus se rabat sur l'accréditation explicitement configurée pour le fournisseur de modèle cible dans milvus.yaml. Si l'étiquette est inconnue ou si la clé référencée est manquante, l'appel échoue.	"apikey1"
dim	Le nombre de dimensions pour les encastrements de sortie. Pour les modèles de troisième génération d'OpenAI, vous pouvez raccourcir le vecteur complet pour réduire le coût et la latence sans perte significative d'informations sémantiques. Pour plus d'informations, reportez-vous à l'article de blog sur l'annonce d'OpenAI. Remarque : si vous réduisez la dimension du vecteur, assurez-vous que la valeur dim spécifiée dans la méthode add_field du schéma pour le champ vectoriel correspond à la dimension de sortie finale de votre fonction d'intégration.	"1536"
user	Un identifiant au niveau de l'utilisateur pour le suivi de l'utilisation de l'API.	"user123"

Étape 3 : configuration de l'index

Après avoir défini le schéma avec les champs nécessaires et la fonction intégrée, configurez l'index de votre collection. Pour simplifier ce processus, utilisez AUTOINDEX comme index_type, une option qui permet à Milvus de choisir et de configurer le type d'index le plus approprié en fonction de la structure de vos données.

# 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

Étape 4 : Création de la collection

Créez maintenant la collection à l'aide des paramètres de schéma et d'index définis.

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

// java

// nodejs

// go

# restful

Étape 5 : Insérer des données

Après avoir configuré votre collection et votre index, vous êtes prêt à insérer vos données brutes. Dans ce processus, il vous suffit de fournir le texte brut. Le module Function que nous avons défini précédemment génère automatiquement le vecteur sparse correspondant pour chaque entrée de texte.

# 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

Étape 6 : Effectuer une recherche vectorielle

Après l'insertion des données, effectuez une recherche sémantique à l'aide du texte brut de la requête. Milvus convertit automatiquement votre requête en un vecteur d'intégration, récupère les documents pertinents sur la base de la similarité et renvoie les meilleurs résultats.

# 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

Pour plus d'informations sur les opérations de recherche et d'interrogation, reportez-vous à la section Recherche et interrogation vectorielles de base.

FAQ

Quelle est la différence entre la configuration des informations d'identification dans milvus.yaml et les variables d'environnement ?

Les deux méthodes fonctionnent, mais l'utilisation de milvus.yaml est l'approche recommandée car elle permet une gestion centralisée des informations d'identification et une dénomination cohérente des informations d'identification pour tous les fournisseurs. Lors de l'utilisation de variables d'environnement, les noms de variables varient en fonction du fournisseur de services d'intégration, il faut donc se référer à la page dédiée de chaque fournisseur pour comprendre les noms de variables d'environnement spécifiques requis (par exemple, OpenAI ou Azure OpenAI).

Que se passe-t-il si je ne spécifie pas de paramètre d'identification dans la définition de la fonction ?

Milvus suit cet ordre de résolution des informations d'identification :

1. Tout d'abord, il recherche l'identifiant par défaut configuré pour ce fournisseur dans le fichier milvus.yaml
2. Si aucun identifiant par défaut n'existe dans milvus.yaml, il se rabat sur les variables d'environnement (si elles sont configurées).
3. Si ni les informations d'identification milvus.yaml ni les variables d'environnement ne sont configurées, Milvus génère une erreur.

Comment puis-je vérifier que les embeddings sont générés correctement ?

Vous pouvez le vérifier en

1. En interrogeant votre collection après l'insertion pour voir si le champ vectoriel contient des données.
2. Vérifier que la longueur du champ vectoriel correspond aux dimensions attendues
3. En effectuant une simple recherche de similarité pour vérifier que les embeddings produisent des résultats significatifs.

Lorsque j'effectue une recherche de similarité, puis-je utiliser un vecteur de requête plutôt que du texte brut ?

Oui, vous pouvez utiliser des vecteurs de requête précalculés au lieu de texte brut pour la recherche de similarités. Bien que le module Function convertisse automatiquement les requêtes de texte brut en embeddings, vous pouvez également fournir directement des données vectorielles au paramètre data dans votre opération de recherche. Remarque: la taille du vecteur de requête fourni doit correspondre à la taille du vecteur d'intégration généré par votre module Function.

Exemple:

# 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