QueryVectors - Object Storage Service - Centre de documentation Alibaba Cloud

Utilisez l'opération QueryVectors pour rechercher des vecteurs similaires.

Remarque

L'opération QueryVectors recherche des vecteurs similaires dans les index en mode Standard. Pour les index en mode Fusion, utilisez l'opération QueryVectorsFusion. Par rétrocompatibilité, si le schéma d'un index en mode Fusion ne définit qu'un seul champ vectoriel nommé float32, vous pouvez continuer à utiliser l'opération QueryVectors.

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations, contrairement aux utilisateurs et rôles RAM. Le propriétaire du compte ou un administrateur doit accorder les autorisations via une politique RAM ou une politique de bucket.

API

Action

Description

QueryVectors

oss:QueryVectors

Interroge les données vectorielles.

Syntaxe de la requête

Le taux de rappel des appels QueryVectors peut être faible pendant les 30 secondes suivant la création d'un index vectoriel. Les données écrites via l'opération PutVectors sont interrogables après environ 2 à 3 secondes.

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "string",
   "queryVector": {
       "float32":[float]
    },
   "returnDistance": boolean,
   "returnMetadata": boolean,
   "topK": int
}

En-têtes de requête

Cette opération n'utilise que des en-têtes de requête communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Paramètres de requête

Paramètre	Type	Obligatoire	Exemple	Description
indexName	String	Oui	vectorindex1	Nom de l'index vectoriel.
queryVector	Container	Oui	N/A	Vecteur de requête. Sa dimension doit correspondre à celle de l'index vectoriel.
filter	Container	Non	N/A	Filtre les données selon les métadonnées. Limites des filtres de métadonnées : La taille totale des métadonnées d'un filtre ne doit pas dépasser 20 Ko. Le nombre d'éléments de métadonnées d'un filtre ne doit pas dépasser 1 024. Les conditions de filtrage peuvent être imbriquées sur 8 niveaux maximum.
returnDistance	Boolean	Non	false	Indique si la distance de similarité est renvoyée. Valeurs possibles : true false (par défaut)
returnMetadata	Boolean	Non	false	Indique si les métadonnées sont renvoyées. Valeurs possibles : true false (par défaut)
topK	Number	Oui	10	Nombre de résultats les plus similaires à renvoyer. La valeur doit être un entier compris entre 1 et 500.

Opérateurs de filtrage

Opérateur

Type

Description

$eq

String, Number, Boolean

Correspondance exacte (pour une valeur unique). Sur des métadonnées de type tableau, l'opérateur renvoie true si la valeur correspond à au moins un élément du tableau.

$ne

String, Number, Boolean

Correspond aux valeurs différentes de la valeur spécifiée.

$gt

Number

Supérieur à.

$gte

Number

Supérieur ou égal à.

$lt

Number

Inférieur à.

$lte

Number

Inférieur ou égal à.

$in

Tableau non vide de primitives

Correspond à toute valeur présente dans un tableau (similaire à l'opérateur SQL IN)

$nin

Tableau non vide de primitives

Ne correspond à aucune valeur du tableau (similaire à l'opérateur SQL NOT IN).

$exists

Boolean

Vérifie l'existence d'une clé de métadonnée.

$and

Tableau non vide de filtres

Applique un ET logique à un tableau de conditions de filtrage.

$or

Tableau non vide de filtres

Applique un OU logique à un tableau de conditions de filtrage.

$nor

Tableau non vide de filtres

Applique un NOR logique à un tableau de conditions de filtrage.

Exemples de filtres

Voici des exemples courants d'expressions de filtre. Si l'opérateur est omis, $eq est utilisé par défaut.

// Simple equality (uses $eq by default when the operator is omitted)
{"category": "finance"}

// Explicit equality / inequality
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// Numeric comparison
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// Array matching
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// Existence check
{"author": {"$exists": true}}

// Logical combination
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// Multiple conditions on the same field (range)
{"score": {"$gte": 0.6, "$lte": 0.95}}

En-têtes de réponse

Cette opération n'utilise que des en-têtes de réponse communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Éléments de réponse

Paramètre

Type

Exemple

Description

vectors

Array of objects

Liste des résultats de la recherche vectorielle.

key

String

doc-001

Clé primaire du vecteur.

Nœud parent : vectors

distance

float32

0,25

Distance de similarité entre le vecteur renvoyé et le vecteur de requête. Plus la valeur est faible, plus la similarité est élevée. Ce paramètre n'est renvoyé que si returnDistance est défini sur true.

Nœud parent : vectors

metadata

Object

Métadonnées complètes du vecteur. Ce paramètre n'est renvoyé que si returnMetadata est défini sur true.

Nœud parent : vectors

Exemples

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}

Exemple de réponse

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      },
      { 
         "distance": 0.25,
         "key": "doc-003",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations",
             "year": "2020"
         }
      }
   ]
}

SDK

L'opération QueryVectors est disponible dans les SDK suivants :

CLI ossutil

Utilisez la commande query-vectors de l'outil de ligne de commande ossutil pour effectuer cette opération.

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
VectorIndexParameterInvalid	400	La requête contient des paramètres d'index vectoriel non valides.
MalformedJson	400	Le format JSON du corps de la requête est incorrect.
AccessDenied	403	Causes possibles de cette erreur : La requête ne contient pas d'informations d'authentification utilisateur. Vous ne disposez pas des autorisations requises pour l'opération.
NoSuchVectorIndex	404	L'index vectoriel spécifié n'existe pas.
QpsLimitExceeded	503	Le débit de requêtes a dépassé la limite QPS. Vos requêtes sont limitées (throttling).