Requête vectorielle - OpenSearch - Centre de documentation Alibaba Cloud

Envoyez un vecteur à OpenSearch Vector Search Edition et récupérez les documents les plus similaires de votre index. Si vous ne disposez pas de modèle vectoriel, utilisez les fonctionnalités de vectorisation d'images ou vectorisation de texte pour générer des vecteurs à l'aide de modèles intégrés, puis exécutez des requêtes basées sur la prédiction.

Endpoint

POST /vector-service/query

Protocole : HTTP Format : JSON

Remarque : Le chemin de l'endpoint omet l'URL de base de votre application OpenSearch ainsi que les en-têtes de requête. Consultez la section Signature de requête pour plus de détails sur l'authentification.

Signature de requête

L'en-tête authorization contient une chaîne encodée en Base64 au format username:password. Retrouvez vos identifiants dans la section API Endpoint de la page Instance Details.

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {

    public static void main(String[] args) throws Exception {
        String accessUserName = "username";
        String accessPassWord = "password";
        String realmStr = "" + accessUserName + ":" + accessPassWord + "";
        String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
        System.out.println(authorization);
    }
}

La valeur encodée se présente comme suit :

cm9vdDp******mdhbA==

Définissez cet en-tête dans chaque requête :

authorization: Basic cm9vdDp******mdhbA==

Paramètres de requête

Par défaut, la réponse inclut uniquement id et score, sans les valeurs des champs ni les données vectorielles. Définissez outputFields et includeVector pour inclure des données supplémentaires.

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`tableName`	STRING	Oui	—	Nom de la table à interroger.
`vector`	LIST[FLOAT]	Oui	—	Vecteur de requête. Pour plusieurs vecteurs, concaténez-les dans un seul tableau et définissez `vectorCount`.
`vectorCount`	INT	Non	`1`	Nombre de vecteurs dans le tableau `vector`.
`namespace`	STRING	Non	`""`	Espace de noms des données vectorielles. Si un espace de noms est configuré sur l'index vectoriel, ce champ est obligatoire.
`topK`	INT	Non	`100`	Nombre maximal de résultats à renvoyer.
`includeVector`	BOOLEAN	Non	`false`	Indique s'il faut renvoyer le vecteur brut dans chaque résultat. Définissez cette option sur `true` uniquement si vous avez besoin des valeurs du vecteur ; son omission réduit la taille de la réponse et la latence.
`outputFields`	LIST[STRING]	Non	`[]`	Noms des champs à inclure dans chaque résultat. Omettez ce paramètre pour renvoyer uniquement `id` et `score`.
`order`	STRING	Non	`ASC`	Sens de tri pour le tri principal. Valeurs valides : `ASC`, `DESC`.
`searchParams`	STRING	Non	`""`	Configuration du chercheur encodée en JSON. Prend en charge les paramètres QcSearcher et HnswSearcher.
`filter`	STRING	Non	`""`	Expression de filtre pour affiner les résultats avant le classement.
`scoreThreshold`	FLOAT	Non	—	Seuil de score pour filtrer les résultats. Pour la distance euclidienne au carré, seuls les documents dont le score est inférieur au seuil sont renvoyés. Pour le produit scalaire, seuls les documents dont le score est supérieur au seuil sont renvoyés.
`sort`	STRING	Non	`""`	Expression de tri permettant de combiner la similarité vectorielle avec d'autres champs. Utilisez `_vs_vector_score` pour inclure le score vectoriel, par exemple : `-create_gmt;+_vs_vector_score`.
`sorts`	LIST[Sort]	Non	`[]`	Tri multidimensionnel. Lorsqu'il est défini, le `score` dans les résultats reflète les dimensions de tri configurées.

Objet Sort

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`order`	STRING	Non	`""`	Sens de tri. Valeurs valides : `ASC` (croissant), `DESC` (décroissant).
`expression`	STRING	Non	`""`	Expression utilisée pour le tri.

Exemples

Requête à vecteur unique

Requête :

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Réponse :

{
    "result": [
        {"id": 1, "score": 1.0508723258972169, "vector": [0.1, 0.2, 0.3]},
        {"id": 2, "score": 1.0329746007919312, "vector": [0.2, 0.2, 0.3]},
        {"id": 3, "score": 0.980593204498291,  "vector": [0.3, 0.2, 0.3]}
    ],
    "totalCount": 3,
    "totalTime": 2.943
}

Requête basée sur l'espace de noms

Les espaces de noms partitionnent un index vectoriel en sous-ensembles isolés. Si un espace de noms est configuré sur l'index, vous devez l'inclure dans chaque requête.

{
    "tableName": "gist",
    "namespace": "space_b",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Requête sur plusieurs espaces de noms

Utilisez le tableau queries pour rechercher dans plusieurs espaces de noms via une seule requête. OpenSearch fusionne et classe les résultats, puis renvoie les K meilleurs résultats.

{
    "tableName": "gist",
    "queries": [
        {"vector": [0.1, 0.2, 0.3], "namespace": "space_a"},
        {"vector": [0.4, 0.5, 0.6], "namespace": "space_b"}
    ],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Requête avec conditions de filtre

Utilisez une expression de filtre pour restreindre les candidats avant le classement. Combinez-la avec outputFields pour contrôler les champs renvoyés.

{
    "tableName": "gist",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "filter": "a > 10",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Requête multi-vecteurs

Concaténez tous les vecteurs dans le tableau vector et définissez vectorCount sur le nombre de vecteurs. OpenSearch fusionne et classe les résultats de tous les vecteurs, puis renvoie les K meilleurs résultats. L'exemple ci-dessous interroge deux vecteurs 2D :

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3, 0.4],
    "vectorCount": 2,
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Paramètres de réponse

Paramètre	Type	Description
`result`	LIST[Item]	Liste classée des documents correspondants.
`totalCount`	INT	Nombre de résultats renvoyés.
`totalTime`	FLOAT	Latence de la requête en millisecondes.
`errorCode`	INT	Code d'erreur. Présent uniquement en cas d'échec de la requête.
`errorMsg`	STRING	Message d'erreur. Présent uniquement en cas d'échec de la requête.

Item

Paramètre	Type	Description
`id`	FieldType	Clé primaire du document.
`score`	FLOAT	Score de similarité. La direction dépend de la métrique de distance : pour la distance euclidienne au carré, un score plus faible indique une similarité plus élevée ; pour le produit scalaire, un score plus élevé indique une similarité plus élevée.
`fields`	MAP	Les champs et leurs valeurs correspondantes.
`vector`	LIST[FLOAT]	La valeur du vecteur.
`namespace`	STRING	Espace de noms du document. Renvoyé uniquement si un espace de noms est configuré.