Créer une requête vectorielle dans Recherche Azure AI

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Si vous avez un index vectoriel dans Recherche Azure AI, cet article explique comment :

Cet article utilise REST pour l’illustration. Après avoir compris le flux de travail de base, poursuivez avec les exemples de code Kit de développement logiciel (SDK) Azure du dépôt azure-search-vector-samples, fournissant des solutions de bout en bout qui incluent des requêtes vectorielles.

Vous pouvez également utiliser Search Explorer dans le portail Azure.

Conditions préalables

Convertir une entrée de chaîne de requête en vecteur

Pour interroger un champ vectoriel, la requête elle-même doit être un vecteur.

Une approche pour convertir la chaîne de requête de texte d’un utilisateur en sa représentation vectorielle consiste à appeler une bibliothèque d’incorporation ou une API dans votre code d’application. En guise de bonne pratique, utilisez toujours les mêmes modèles d’incorporation utilisés pour générer des incorporations dans les documents sources. Vous trouverez des exemples de code montrant comment générer des embeddings dans le référentiel azure-search-vector-samples.

Une deuxième approche consiste à utiliser la vectorisation intégrée, désormais généralement disponible, pour que Recherche Azure AI gérer vos entrées et sorties de vectorisation de requête.

Voici un exemple d'API REST d'une chaîne de requête soumise à un déploiement d'un modèle d'incorporation OpenAI Azure :

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

La réponse attendue est 202 pour un appel réussi au modèle déployé.

Le embedding champ dans le corps de la réponse est la représentation vectorielle de la chaîne inputde requête . À des fins de test, vous pouvez copier la valeur du tableau embedding dans vectorQueries.vector dans une requête, à l’aide de la syntaxe indiquée dans les sections suivantes.

La réponse réelle à cet appel POST au modèle déployé comprend 1 536 incorporations. Pour une lisibilité, cet exemple affiche uniquement les premiers vecteurs.

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

Dans cette approche, votre code d’application est responsable de la connexion à un modèle, de la génération d’incorporations et de la gestion de la réponse.

Demande de requête vectorielle

Cette section présente la structure de base d’une requête vectorielle. Vous pouvez utiliser le portail Azure, les API REST ou le SDK Azure pour formuler une requête vectorielle.

Si vous migrez à partir de 2023-07-01-preview, il existe des changements cassants. Pour plus d’informations, consultez Mettre à niveau vers la dernière API REST.

La version stable prend en charge :

  • vectorQueries est la construction de la recherche vectorielle.
  • vectorQueries.kind défini sur vector pour un tableau de vecteurs ou text si l’entrée est une chaîne et si vous avez un vectoriseur.
  • vectorQueries.vector est la requête (représentation vectorielle du texte ou d’une image).
  • vectorQueries.exhaustive (facultatif) invoque un KNN exhaustif lors de la requête, même si le champ est indexé pour HNSW.
  • vectorQueries.fields (facultatif) cible des champs spécifiques pour l’exécution de requête (jusqu’à 10 par requête).
  • vectorQueries.weight (facultatif) spécifie le poids relatif de chaque requête vectorielle incluse dans les opérations de recherche. Pour plus d’informations, consultez Pondération des vecteurs.
  • vectorQueries.k est le nombre de correspondances à retourner.

Dans l’exemple suivant, le vecteur est une représentation de cette chaîne : "what Azure services support full text search". La requête cible le contentVector champ et retourne k les résultats. Le vecteur réel a 1 536 incorporations, qui sont découpées dans cet exemple pour la lisibilité.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

Réponse de requête vectorielle

Dans Recherche Azure AI, les réponses aux requêtes se composent de tous les champs retrievable par défaut. Toutefois, il est courant de limiter les résultats de recherche à un sous-ensemble de retrievable champs en les listant dans une select instruction.

Dans une requête vectorielle, déterminez soigneusement si vous devez vecteurr des champs dans une réponse. Les champs vectoriels ne sont pas lisibles par l’homme. Par conséquent, si vous envoyez une réponse à une page web, vous devez choisir des champs non vecteurs qui représentent le résultat. Par exemple, si la requête s’exécute sur contentVector, vous pouvez retourner content à la place.

Si vous souhaitez des champs vectoriels dans le résultat, voici un exemple de la structure de réponse. contentVector est un tableau de chaînes d'embeddings, qui sont troncés dans cet exemple pour la lisibilité. Le score de recherche indique la pertinence. D’autres champs non-vecteurs sont inclus pour le contexte.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

Points clés :

  • k détermine le nombre de résultats voisins les plus proches retournés, dans ce cas, trois. Les requêtes vectorielles retournent k toujours des résultats, en supposant qu’au moins k des documents existent, même si certains documents ont une mauvaise similarité. Cela est dû au fait que l’algorithme trouve n'importe quel k voisin le plus proche du vecteur de requête.

  • L’algorithme de recherche vectorielle détermine le @search.score.

  • Les champs dans les résultats de recherche sont soit tous les retrievable champs, soit des champs dans une clause select. Pendant l’exécution de requête vectorielle, la correspondance est effectuée uniquement sur les données vectorielles. Toutefois, une réponse peut inclure n’importe quel retrievable champ dans un index. Étant donné qu’il n’existe aucune possibilité de décoder un résultat de champ vectoriel, l’inclusion de champs de texte non vectoriels est utile pour leurs valeurs lisibles par l’homme.

Champs vectoriels multiples

Vous pouvez définir la vectorQueries.fields propriété sur plusieurs champs vectoriels. La requête vectorielle s’exécute sur chaque champ vectoriel que vous fournissez dans la fields liste. Vous pouvez spécifier jusqu’à 10 champs.

Lors de l’interrogation de plusieurs champs vectoriels, assurez-vous que chacun contient des incorporations à partir du même modèle d’incorporation. La requête doit également être générée à partir du même modèle d’incorporation.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

Requêtes vectorielles multiples

La recherche vectorielle à plusieurs requêtes envoie plusieurs requêtes sur plusieurs champs vectoriels dans votre index de recherche. Ce type de requête est couramment utilisé avec des modèles tels que CLIP pour la recherche modale, où le même modèle peut vectoriser à la fois du texte et des images.

L’exemple de requête suivant recherche la similarité tant dans myImageVector que dans myTextVector, et envoie deux vecteurs de requête respectifs, chacun s’exécutant en parallèle. Le résultat de cette requête est évalué à l’aide de la fusion de classement réciproque (RRF).

  • vectorQueries fournit un tableau de requêtes vectorielles.
  • vector contient les vecteurs d’image et les vecteurs de texte dans l’index de recherche. Chaque instance est une requête distincte.
  • fields spécifie le champ vecteur à cibler.
  • k est le nombre de correspondances voisines les plus proches à inclure dans les résultats.
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

Les index de recherche ne peuvent pas stocker d’images. En supposant que votre index inclut un champ pour le fichier image, les résultats de la recherche incluent une combinaison de texte et d’images.

Requête avec vectorisation intégrée

Cette section montre une requête vectorielle qui appelle la vectorisation intégrée pour convertir une requête de texte ou d’image en vecteur. Nous recommandons l’API REST stable 2026-04-01 API REST, l’Explorateur de recherche ou les packages Kit de développement logiciel (SDK) Azure plus récents pour cette fonctionnalité.

Un prérequis est un index de recherche qui a un vectoriseur configuré et affecté à un champ vectoriel. Le vectoriseur fournit des informations de connexion à un modèle d’incorporation utilisé au moment de la requête.

L’Explorateur de recherche prend en charge la vectorisation intégrée au moment de la requête. Si votre index contient des champs vectoriels et possède un vectoriseur, vous pouvez utiliser la conversion de texte en vecteur intégrée.

  1. Accédez à votre service de recherche dans le portail Azure.

  2. Dans le menu de gauche, sélectionnezIndex> recherche, puis sélectionnez votre index.

  3. Sélectionnez l’onglet Profils vectoriels pour confirmer que vous disposez d’un vectoriseur.

    Capture d’écran d’un paramètre vectoriseur dans un index de recherche.

  4. Sélectionnez l’onglet Explorateur de recherche . À l’aide de la vue de requête par défaut, vous pouvez entrer une chaîne de texte dans la barre de recherche. Le vectoriseur intégré convertit votre chaîne en vecteur, effectue la recherche et retourne les résultats.

    Vous pouvez également sélectionner Afficher>la vue JSON pour afficher ou modifier la requête. Si des vecteurs sont présents, l’Explorateur de recherche configure automatiquement une requête vectorielle. Vous pouvez utiliser la vue JSON pour sélectionner des champs à utiliser dans la recherche et la réponse, ajouter des filtres et construire des requêtes plus avancées, telles que des requêtes hybrides. Pour afficher un exemple JSON, sélectionnez l’onglet API REST dans cette section.

Nombre de résultats classés dans une réponse de requête vectorielle

Une requête vectorielle spécifie le k paramètre, qui détermine le nombre de correspondances retournées dans les résultats. Le moteur de recherche retourne toujours k le nombre de résultats. S’il k est supérieur au nombre de documents dans l’index, le nombre de documents détermine la limite supérieure de ce qui peut être retourné.

Si vous êtes familiarisé avec la recherche en texte intégral, vous savez s’attendre à zéro résultat si l’index ne contient pas de terme ou d’expression. Toutefois, dans la recherche vectorielle, l’opération de recherche identifie les voisins les plus proches et retourne k toujours les résultats, même si les voisins les plus proches ne sont pas aussi similaires. Il est possible d’obtenir des résultats pour les requêtes nonsensiques ou hors rubrique, en particulier si vous n’utilisez pas d’invites pour définir des limites. Les résultats moins pertinents ont un score de similarité pire, mais ils sont toujours les vecteurs les plus proches s’il n’y a rien de plus proche. Par conséquent, une réponse sans résultats significatifs peut toujours retourner k des résultats, mais le score de similarité de chaque résultat serait faible.

Une approche hybride qui inclut la recherche en texte intégral peut atténuer ce problème. Une autre solution consiste à définir un seuil minimal sur le score de recherche, mais uniquement si la requête est une requête à vecteur unique pure. Les requêtes hybrides ne sont pas propices aux seuils minimaux, car les plages RRF sont beaucoup plus petites et plus volatiles.

Les paramètres de requête qui affectent le nombre de résultats sont les suivants :

  • "k": n résultats pour les requêtes vectorielles uniquement.
  • "top": n résultats des requêtes hybrides qui incluent un search paramètre.

Les k et top sont facultatifs. Lorsqu’il n’est pas spécifié, le nombre par défaut de résultats dans une réponse est 50. Vous pouvez définir top et skip pour parcourir plus de résultats ou modifier la valeur par défaut.

Algorithmes de classement utilisés dans une requête vectorielle

Le classement des résultats est calculé par les deux :

  • Métrique de similarité.
  • RRF s’il existe plusieurs ensembles de résultats de recherche.

Métrique de similarité

Métrique de similarité spécifiée dans la section d’index vectorSearch pour une requête vectorielle uniquement. Les valeurs valides sont cosine, euclideanet dotProduct.

Les modèles d'incorporation Azure OpenAI utilisent la similarité cosinus, donc si vous utilisez les modèles d'incorporation Azure OpenAI, cosine est la métrique recommandée. Les autres métriques de classement prises en charge incluent euclidean et dotProduct.

RRF

Plusieurs jeux sont créés si la requête cible plusieurs champs vectoriels, exécute plusieurs requêtes vectorielles en parallèle ou est un hybride de recherche vectorielle et de recherche en texte intégral, avec ou sans classement sémantique.

Pendant l’exécution de la requête, une requête vectorielle ne peut cibler qu’un seul index vectoriel interne. Pour plusieurs champs vectoriels et plusieurs requêtes vectorielles, le moteur de recherche génère plusieurs requêtes qui ciblent les index vectoriels respectifs de chaque champ. La sortie est un ensemble de résultats classés pour chaque requête, qui sont fusionnés à l’aide de RRF. Pour plus d’informations, consultez Évaluation de la pertinence avec la fusion du classement réciproque.

Pondération de vecteurs

Ajoutez un weight paramètre de requête pour spécifier le poids relatif de chaque requête vectorielle incluse dans les opérations de recherche. Cette valeur est utilisée lors de la combinaison des résultats de plusieurs listes de classement produites par deux requêtes vectorielles ou plus dans la même requête, ou à partir de la partie vectorielle d’une requête hybride.

La valeur par défaut est 1.0 et la valeur doit être un nombre positif supérieur à zéro.

Les pondérations sont utilisées lors du calcul des scores RRF de chaque document. Le calcul est un multiplicateur de la weight valeur par rapport au score de classement du document dans son jeu de résultats respectif.

L’exemple suivant est une requête hybride avec deux chaînes de requête vectorielles et une chaîne de texte. Les pondérations sont affectées aux requêtes vectorielles. La première requête a un poids de 0,5, soit la moitié, ce qui réduit son importance dans la demande. La deuxième requête vectorielle est deux fois plus importante.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-04-01

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    }

La pondération des vecteurs s’applique uniquement aux vecteurs. La requête de texte dans cet exemple, "hello world"a un poids neutre implicite de 1,0. Toutefois, dans une requête hybride, vous pouvez augmenter ou diminuer l’importance des champs de texte en définissant maxTextRecallSize.

Définir des seuils pour exclure les résultats à faibles scores (aperçu)

Étant donné que la recherche du plus proche voisin retourne toujours les voisins demandés k, il est possible d’obtenir plusieurs correspondances de faible score pour satisfaire à l’exigence numérique k sur les résultats de la recherche. Pour exclure les résultats de recherche à faible score, vous pouvez ajouter un threshold paramètre de requête qui filtre les résultats en fonction d’un score minimal. Le filtrage se produit avant de fusionner les résultats de différents jeux de rappel.

Ce paramètre est en préversion. Nous vous recommandons la dernière version préliminaire de Documents - Recherche Post (API REST).

Dans cet exemple, toutes les correspondances dont le score est inférieur à 0,8 sont exclues des résultats de recherche vectorielle, même si le nombre de résultats tombe en dessous k.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-08-01-preview
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

Étapes suivantes

À l’étape suivante, passez en revue les exemples de code de requête vectorielle dans Python, C# ou JavaScript.

  • Last updated on