DiskBBQ est un type d'index pour les champs vectoriels. Les index standard et les Collections partagent la même configuration de champ bbq_disk. Lorsqu'un champ vectoriel de ce type est interrogé dans le périmètre d'une Slice au sein d'une Collection, Sliced DiskBBQ est utilisé et aucun jeu supplémentaire de paramètres Mapping n'est requis. Les sections suivantes décrivent la configuration du champ DiskBBQ et les paramètres des requêtes KNN, et expliquent comment lire les valeurs vectorielles à la demande. Pour commencer, suivez l'exemple complet pour un index standard. Le tableau ci-dessous offre une référence rapide aux endpoints de requête.
|
Opération |
Index standard |
Collection |
|
Ajouter un champ vectoriel |
|
|
|
Interroger les plus proches voisins |
|
|
Les dimensions des vecteurs de document et des vecteurs de requête doivent correspondre à dims. Les exemples des sections de référence suivantes ciblent une Collection ; si la cible est un index standard, utilisez le nom réel de l'index. Le paramètre _slice s'applique uniquement aux requêtes de Collection : utilisez _slice pour spécifier la Slice à interroger, ou laissez le périmètre être sélectionné automatiquement en fonction du mode de rappel du cluster vectoriel. L'exemple complet à la fin de cette rubrique utilise un index standard.
Pour en savoir plus sur les avantages, les scénarios et les compromis liés à la capacité à deux niveaux, consultez Capacité à deux niveaux DiskBBQ.
Configuration du champ et paramètres de requête
Configurer un mapping
Prise en main configure déjà DiskBBQ lors de la création d'une Collection. Pour les autres Collections qui ne disposent pas encore de champ vectoriel, utilisez l'API Mapping pour en ajouter un :
PUT /{collection}/_mapping
{
"properties": {
"embedding": {
"type": "dense_vector",
"dims": 4,
"index": true,
"similarity": "cosine",
"index_options": {
"type": "bbq_disk"
}
}
}
}Lorsque vous spécifiez explicitement "type": "bbq_disk", le serveur fournit les valeurs par défaut suivantes pour index_options. Ces valeurs par défaut sont indépendantes des dimensions du vecteur :
{
"index_options": {
"type": "bbq_disk",
"cluster_size": 384,
"flat_index_threshold": -1,
"default_visit_percentage": 0.0,
"rescore_vector": { "oversample": 3.0 },
"bits": 1
}
}default_visit_percentage représente la valeur par défaut au niveau du Mapping. Elle est utilisée lorsque visit_percentage n'est pas défini au niveau de la requête. Le paramètre au niveau de la requête est prioritaire. rescore_vector.oversample peut être remplacé dans une requête. cluster_size, flat_index_threshold et bits sont gérés par le serveur et ne nécessitent pas d'ajustement.
Maintenez la cohérence entre les dimensions du vecteur, la similarité et le modèle utilisé pour générer les vecteurs. Pour changer le type d'index d'un champ vectoriel existant, créez la Collection cible, configurez un nouveau Mapping, puis utilisez Reindex pour migrer les données et relancer l'évaluation.
Exécuter une requête KNN
Dans une requête, utilisez knn.field pour référencer le champ vectoriel configuré dans le Mapping. La requête suivante utilise visit_percentage pour ajuster le périmètre d'accès de DiskBBQ au sein de la Slice spécifiée :
POST /knowledge-chunks/_search?_slice=tenant-a
{
"knn": {
"field": "embedding",
"query_vector": [0.80, 0.12, 0.05, 0.03],
"k": 10,
"visit_percentage": 10.0
},
"_source": ["document_id", "title", "content"]
}|
Paramètre |
Description |
|
|
Le nombre de plus proches voisins sélectionnés globalement. Le nombre réel de résultats renvoyés est également limité par le paramètre |
|
|
Le pourcentage de vecteurs visités sur chaque shard. Valeurs valides : 0 à 100. Une valeur plus élevée améliore généralement le rappel, mais augmente également la charge de calcul et de lecture. Une valeur explicitement définie dans la requête remplace la valeur par défaut du Mapping. Lorsque la valeur effective finale est supérieure à |
|
|
Lorsque la valeur effective finale de |
|
|
Ajoute un filtrage structuré pour réduire le nombre de candidats non pertinents. |
|
|
Utilise les vecteurs d'origine pour recalculer le score des candidats renvoyés par la récupération quantifiée. Il peut remplacer la valeur par défaut de |
Par défaut, la valeur effective de visit_percentage est 0, donc num_candidates détermine le périmètre de visite des candidats. Pour contrôler le périmètre de visite par pourcentage, définissez default_visit_percentage dans le Mapping ou visit_percentage dans la requête. Lorsque vous utilisez le rappel de cluster vectoriel, vous devez également configurer le périmètre des Slices candidates. Pour plus d'informations, consultez Référence du rappel de cluster vectoriel.
Lire les valeurs vectorielles à la demande
Pour les recherches courantes, conservez le paramètre par défaut qui ne renvoie pas les vecteurs, et utilisez uniquement _source pour sélectionner les champs dont votre application a besoin, tels que le titre et le contenu dans l'exemple précédent. La récupération KNN et le recalcul des scores sont effectués sur le serveur, il n'est donc pas nécessaire de renvoyer les vecteurs à votre application.
Récupérez explicitement les champs requis uniquement lorsque vous devez vérifier ou exporter les valeurs vectorielles. Par exemple, lisez le champ embedding d'un document :
GET /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a&_source_exclude_vectors=falseUtilisez _source_exclude_vectors=false pour récupérer explicitement les vecteurs. Ce paramètre renvoie à la fois les champs métier et les vecteurs dans _source. Le renvoi des vecteurs augmente la charge de lecture des données, de reconstruction et de transmission réseau ; utilisez donc ce paramètre uniquement lorsque vous devez vérifier ou exporter des vecteurs.
Les valeurs renvoyées dépendent de la précision de stockage du champ vectoriel. L'exemple utilise par défaut float (float32). Des arrondis en virgule flottante peuvent se produire lors de la conversion des valeurs décimales écrites en float32, ainsi que pendant la normalisation et la restauration effectuées pour la similarité cosine. Si le champ utilise element_type: bfloat16, la précision de stockage est plus faible et l'erreur est plus visible qu'avec float32. Lorsque DiskBBQ récupère des vecteurs, il utilise les valeurs vectorielles conservées plutôt que de dériver les valeurs d'origine à partir de l'encodage quantifié. Si vous avez besoin de la sortie originale du modèle pour une vérification au niveau du bit ou une évaluation de la précision, stockez les vecteurs d'origine séparément.
Exemple complet pour un index standard
Votre compte doit disposer des permissions nécessaires pour créer des index et pour écrire et lire des données. Après avoir créé et connecté une instance Agent Engine Edition, exécutez les requêtes suivantes séquentiellement dans Kibana Dev Tools. Cet exemple utilise l'index standard vector-demo et des vecteurs à quatre dimensions construits manuellement uniquement pour vérifier la configuration et le flux de requête.
Étape 1 : Créer un index vectoriel
PUT /vector-demo
{
"settings": {
"number_of_shards": 1,
"number_of_replicas": 2
},
"mappings": {
"properties": {
"title": { "type": "text" },
"embedding": {
"type": "dense_vector",
"dims": 4,
"similarity": "cosine",
"index": true,
"index_options": { "type": "bbq_disk" }
}
}
}
}Utilisez un nom d'index qui n'existe pas encore. Dans les scénarios de production, maintenez la cohérence entre les dimensions du vecteur, la similarité et la sortie du modèle. Les valeurs de shard et de réplica de cet exemple sont fournies à titre de démonstration uniquement. Pour plus d'informations, consultez Paramètres de nœud et de réplica.
Étape 2 : Écrire des données et vérifier la visibilité des requêtes
POST /vector-demo/_bulk
{"index":{"_id":"1"}}
{"title":"Knowledge base search","embedding":[0.80,0.12,0.05,0.03]}
{"index":{"_id":"2"}}
{"title":"Product search","embedding":[0.10,0.75,0.10,0.05]}Pour les écritures courantes vers un index standard, ne passez pas refresh et n'appelez pas _refresh dans le code de votre application. Vérifiez que errors=false est renvoyé dans la réponse Bulk, puis attendez environ 5 secondes que l'actualisation automatique en arrière-plan rende les données interrogeables. Si les résultats ne contiennent pas encore les nouveaux documents, attendez un autre cycle d'actualisation automatique et réessayez. Pour connaître les conditions applicables à la vérification des écritures par ID et à l'attente synchrone, consultez Actualisation et visibilité des requêtes.
Étape 3 : Interroger des vecteurs similaires
POST /vector-demo/_search
{
"knn": {
"field": "embedding",
"query_vector": [0.80, 0.12, 0.05, 0.03],
"k": 2,
"visit_percentage": 10.0
},
"_source": ["title"]
}Vérifiez que timed_out=false et _shards.failed=0, et assurez-vous que hits.hits contient les deux documents intitulés « Knowledge base search » et « Product search ». Cet exemple vérifie uniquement le flux de requête. Évaluez le rappel et les performances en utilisant vos vecteurs réels, vos jeux de requêtes et vos charges concurrentes.