Elasticsearch:Vector cluster recall mode

Enregistrer un centroïde de slice unique

La demande suivante enregistre le centroïde du slice cluster-a :

PUT /_slice_collection/products/slices/cluster-a
{
  "vector": [0.9, 0.1]
}

Une réponse HTTP réussie ne garantit pas que le centroïde a été créé. Comme décrit dans Vérifier les résultats d'enregistrement (unique et par lot), vérifiez le champ errors de premier niveau et le result de chaque élément dans items.

Enregistrer des centroïdes de slice par lots

Une tâche de clustering hors ligne génère généralement plusieurs centroïdes de clusters vectoriels simultanément. Utilisez l'API par lot pour les enregistrer en une seule demande :

PUT /_slice_collection/products/slices
{
  "slices": [
    { "slice": "cluster-b", "vector": [0.1, 0.9] },
    { "slice": "cluster-c", "vector": [0.6, 0.4] }
  ]
}

Le nom de slice de chaque élément peut être spécifié par slice ou slice_id, mais un seul d'entre eux peut apparaître dans le même élément. Vous pouvez enregistrer jusqu'à 20 480 slices dans une seule demande, et les noms de slice doivent être uniques au sein de la demande.

Vérifier les résultats d'enregistrement (unique et par lot)

L'API d'enregistrement unique et l'API d'enregistrement par lot peuvent signaler des erreurs au niveau des éléments dans une réponse HTTP 200, y compris une incompatibilité entre les dimensions du centroïde et config.vector_dims. Une demande HTTP réussie ne signifie pas que tous les clusters vectoriels ont été enregistrés avec succès. En plus de gérer les réponses non-2xx, vérifiez le champ errors de premier niveau et, pour chaque élément dans items, son result : created indique que le centroïde a été créé, updated indique que le centroïde a été mis à jour, noop indique que le contenu n'a pas changé, et failed indique un échec. Un élément ayant échoué contient un champ error de type chaîne et ne contient pas le champ backing_index présent dans un élément réussi.

{
  "acknowledged": true,
  "errors": false,
  "items": [
    {
      "slice_id": "cluster-b",
      "result": "created",
      "backing_index": ".sc-products-...-00000"
    },
    {
      "slice_id": "cluster-c",
      "result": "created",
      "backing_index": ".sc-products-...-00001"
    }
  ]
}

Les dimensions de chaque centroïde doivent correspondre à config.vector_dims. Un slice sans centroïde peut toujours être accédé explicitement, mais il ne participe pas à la sélection automatique des slices candidates. Lorsque vous enregistrez à nouveau un slice avec le même nom, updated est renvoyé si le centroïde a changé, et noop est renvoyé s'il n'a pas changé. Dans les deux cas, les documents déjà écrits ne sont pas déplacés.

Écrire des documents avec routing_field

Après avoir configuré routing_field, le système lit le slice à partir d'un champ de premier niveau du document, et vous n'avez plus besoin de passer _slice :

PUT /products/_doc/product-1
{
  "cluster_id": "cluster-a",
  "name": "example-product",
  "embedding": [0.92, 0.08]
}

Vous pouvez également fournir explicitement _slice=cluster-a, et les API compatibles acceptent également routing=cluster-a. Si vous spécifiez explicitement un slice, la valeur doit correspondre à la valeur du champ de document spécifié par routing_field (cluster_id dans cet exemple). Sinon, une erreur HTTP 400 est renvoyée.

Mettre à jour des documents

Après avoir configuré routing_field, les mises à jour scriptées ne sont pas prises en charge. Pour modifier uniquement certains champs, utilisez l'API _update avec un corps de demande doc et portez explicitement un _slice correspondant. Si une nouvelle valeur doit être calculée à partir d'une ancienne valeur, lisez l'ancienne valeur dans votre application, calculez la nouvelle valeur et réécrivez-la. Utilisez if_seq_no et if_primary_term pour le contrôle de concurrence afin d'éviter que votre mise à jour n'écrase les mises à jour d'autres demandes.

Réécrire des documents après Copy ou Branch

Les fonctionnalités Copy et Branch conservent toutes deux la valeur routing_field dans un document. Lorsque vous réécrivez ultérieurement un document dans le slice de destination, spécifiez explicitement la destination et assurez-vous que le champ de routage dans le document écrit correspond à la destination. Cela empêche le document d'être réécrit dans le slice source ou de déclencher une erreur de validation. Pour plus d'informations, consultez Sémantique de copie des données.

Écrire des documents sans routing_field

Si routing_field n'est pas configuré, les données sont écrites de la même manière qu'en mode namespace : chaque demande d'écriture ou élément Bulk doit spécifier explicitement _slice. Pour les autres comportements d'écriture, tels que Bulk, la visibilité Refresh, _update_by_query et _delete_by_query, consultez Opérations d'écriture, de lecture et de requête de documents.

Exécuter une requête

Utilisez un vecteur de requête pour sélectionner automatiquement les slices candidates :

POST /products/_search?query_slice_count=2
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.91, 0.09],
    "k": 10,
    "num_candidates": 100
  }
}

Vérifiez que timed_out=false et _shards.failed=0, et que hits.hits contient product-1 écrit dans cet exemple.

Le tableau suivant décrit les paramètres de sélection automatique des slices candidates :

Une demande utilise uniquement le vecteur de requête sélectionné par le chemin configuré pour déterminer les slices candidates de l'ensemble de la demande. Plusieurs clauses KNN ne sélectionnent pas les slices séparément puis ne prennent pas l'union des ensembles de slices sélectionnés. Les autres clauses de requête KNN ou hybrides sont également limitées à cet ensemble de slices candidates.

Si query_slice_count est explicitement défini sur une valeur non nulle, la valeur doit se situer dans la plage de 1 à max_query_slice_count. Sinon, une erreur HTTP 400 est renvoyée.

Si la demande spécifie explicitement _slice ou le paramètre compatible routing, la requête s'exécute dans la portée spécifiée, que ces slices aient ou non enregistré des centroïdes. L'exigence de centroïde s'applique uniquement à la sélection automatique des slices candidates : seules les slices ayant un centroïde enregistré sont prises en compte.

Lorsque le paramètre de cluster apack.slice_collection.search.default_to_all_slices est désactivé, ce qui est le cas par défaut, une erreur HTTP 400 est renvoyée si le chemin configuré n'a pas de vecteur de requête. Dans ce cas, spécifiez explicitement _slice. Après avoir activé ce paramètre, un vecteur de requête manquant revient à interroger toutes les slices. Pour les requêtes de production régulières, conservez ce paramètre désactivé et ne comptez pas sur le repli sur toutes les slices. Un chemin invalide, l'utilisation de query_vector_builder pour fournir le vecteur de requête, ou des dimensions de vecteur de requête qui ne correspondent pas à vector_dims renvoient toujours une erreur HTTP 400, et ce paramètre ne peut pas contourner ces erreurs. Pour plus d'informations sur le paramètre, consultez Spécifier la portée de la requête.

Le corps de la demande de l'API Count (_count) ne contient pas le vecteur de requête en ligne requis pour la sélection automatique de slice, donc le slice ne peut pas être sélectionné automatiquement. Tant que le repli sur toutes les slices reste désactivé par défaut, vous devez fournir explicitement _slice. Les autres requêtes qui ne contiennent pas de vecteur de requête doivent également spécifier explicitement la portée.

Préchauffer les slices candidates connues (facultatif)

Si vous pouvez prédire quels clusters seront accessibles, préchauffez-les d'abord pour réduire la latence de la première requête sur des données froides. Dans cet exemple, un seul document est écrit dans cluster-a, vous pouvez donc le préchauffer une fois :

POST /products/_warm_slice?_slice=cluster-a&wait_for_completion=true&timeout=60s

Vérifiez que la demande aboutit et que _shards.failed=0. Si _shards.total=0, vérifiez d'abord que les shards de requête sont disponibles et utilisez une requête réelle pour confirmer que les données sont consultables, puis réessayez le préchauffage si nécessaire. Des données ont déjà été écrites dans cet exemple. L'attente synchrone est utilisée uniquement pour vérifier cet exemple. Dans un environnement de production, préchauffez une portée d'accès prévisible de manière asynchrone à l'avance et contrôlez la concurrence. N'itérez pas et ne préchauffez pas tous les clusters avant chaque requête de sélection automatique de cluster. Pour plus d'informations, consultez Mettre en cache le slice.