Partager via

Démarrage rapide : Recherche vectorielle à l’aide de REST

  • Article

Découvrez comment utiliser les API Search REST pour créer, charger et interroger des vecteurs dans la Recherche Azure AI.

Dans Recherche Azure AI, un magasin de vecteurs comprend un schéma d’index qui définit des champs vectoriels et non vectoriels, une configuration de recherche vectorielle pour les algorithmes qui créent l’espace d’incorporation ainsi que des paramètres sur les définitions des champs vectoriels qui sont évalués au moment de la requête. L’API REST Créer un index crée le magasin de vecteurs.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Remarque

Ce démarrage rapide omet l’étape de vectorisation et fournit des incorporations dans les exemples de documents. Si vous souhaitez ajouter la segmentation et la vectorisation des données intégrées sur votre contenu, essayez l’Assistant Importation et vectorisation des données pour découvrir une procédure pas à pas de bout en bout.

Prérequis

Récupérer des informations sur les ressources

Les demandes effectuées au point de terminaison de recherche doivent être authentifiées et autorisées. Vous pouvez utiliser des clés d’API ou des rôles pour cette tâche. Nous vous recommandons de à l’aide d’une connexion sans clé via Microsoft Entra ID.

Sélectionnez l’onglet correspondant à votre méthode d’authentification préférée. Utilisez la même méthode pour toutes les requêtes de ce guide de démarrage rapide.

  1. Connectez-vous au Portail Azure, puis trouvez votre service de recherche.

  2. Dans la page d’accueil Vue d’ensemble, recherchez l’URL. Voici un exemple de point de terminaison : https://mydemo.search.windows.net.

    Capture d’écran de la propriété URL sur la page de présentation.

  3. Suivez les étapes de la démarrage rapide sans clé pour obtenir votre jeton Microsoft Entra.

    Vous obtenez le jeton lorsque vous exécutez la commande az account get-access-token à l’étape 3 du guide de démarrage rapide précédent.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Créer ou télécharger le fichier de code

Vous utilisez un fichier .rest ou .http pour exécuter toutes les requêtes de ce guide de démarrage rapide. Vous pouvez télécharger le fichier REST qui contient le code de ce guide de démarrage rapide, ou vous pouvez créer un fichier dans Visual Studio Code et copier le code dans celui-ci.

  1. Dans Visual Studio Code, créez un nouveau fichier avec une extension de fichier .rest ou .http. Par exemple : az-search-vector-quickstart.rest. Copiez et collez le contenu brut de l' Azure-Samples/azure-search-rest-samples/blob/main/Quickstart-vectors/az-search-vector-quickstart.rest fichier dans ce nouveau fichier.

  2. En haut du fichier, remplacez la valeur d’espace réservé pour @baseUrl par l’URL de votre service de recherche. Consultez la section Récupérer les informations de ressource pour obtenir des instructions sur la recherche de l’URL de votre service de recherche.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE

  3. En haut du fichier, remplacez la valeur d’espace réservé pour l’authentification. Consultez la section Récupérer les informations de ressource pour obtenir des instructions sur l’obtention de votre jeton Microsoft Entra ou de votre clé API.

    Pour l'authentification sans clé recommandée via Microsoft Entra ID, vous devez remplacer @apiKey par la variable @token.

    @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE

    Si vous préférez utiliser une clé API, remplacez @apiKey par la clé que vous avez copiée à partir du portail Azure.

    @apiKey = PUT-YOUR-ADMIN-KEY-HERE

  4. Pour l'authentification sans clé recommandée via Microsoft Entra ID, vous devez remplacer api-key: {{apiKey}} par Authorization: Bearer {{token}} dans les en-têtes de la requête. Remplacez toutes les instances de api-key: {{apiKey}} que vous trouvez dans le fichier.

Créer un index vectoriel

Vous utilisez l'API REST Create Index pour créer un index vectoriel et configurer les structures de données physiques sur votre service de recherche.

Le schéma d’index dans cet exemple est organisé autour du contenu d’hôtel. Les exemples de données se composent de noms et de descriptions vectoriels et non vectoriels d’hôtels fictifs. Ce schéma inclut des configurations pour l’indexation et les requêtes vectorielles, ainsi que pour le classement sémantique.

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Create a new index dans le fichier. Ce bloc contient la requête de création de l’index hotels-vector-quickstart sur votre service de recherche.

    ### Create a new index
POST  {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-vector-quickstart",
    "fields": [
        {
            "name": "HotelId", 
            "type": "Edm.String",
            "searchable": false, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false,
            "key": true
        },
        {
            "name": "HotelName", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": false
        },
        {
            "name": "HotelNameVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        {
            "name": "Description", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false
        },
        {
            "name": "DescriptionVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
                {
            "name": "Description_fr", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false,
            "analyzer": "en.microsoft"
        },
        {
            "name": "Description_frvector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        {
            "name": "Category", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": true
        },
        {
            "name": "Tags",
            "type": "Collection(Edm.String)",
            "searchable": true,
            "filterable": true,
            "retrievable": true,
            "sortable": false,
            "facetable": true
        },
                {
            "name": "ParkingIncluded",
            "type": "Edm.Boolean",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "LastRenovationDate",
            "type": "Edm.DateTimeOffset",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "Rating",
            "type": "Edm.Double",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "Address", 
            "type": "Edm.ComplexType",
            "fields": [
                {
                    "name": "StreetAddress", "type": "Edm.String",
                    "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false
                },
                {
                    "name": "City", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "StateProvince", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "PostalCode", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "Country", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                }
            ]
        },
        {
            "name": "Location",
            "type": "Edm.GeographyPoint",
            "searchable": false, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": false
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "my-hnsw-vector-config-1",
                "kind": "hnsw",
                "hnswParameters": 
                {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            },
            {
                "name": "my-hnsw-vector-config-2",
                "kind": "hnsw",
                "hnswParameters": 
                {
                    "m": 4,
                    "metric": "euclidean"
                }
            },
            {
                "name": "my-eknn-vector-config",
                "kind": "exhaustiveKnn",
                "exhaustiveKnnParameters": 
                {
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [      
            {
                "name": "my-vector-profile",
                "algorithm": "my-hnsw-vector-config-1"
            }
      ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "HotelName"
                    },
                    "prioritizedContentFields": [
                        { "fieldName": "Description" }
                    ],
                    "prioritizedKeywordsFields": [
                        { "fieldName": "Category" }
                    ]
                }
            }
        ]
    }
}

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 201 Created.

Le corps de la réponse doit inclure la représentation JSON du schéma d’index.

{
    "@odata.context": "https://my-demo-search.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag": "\"0x8DD2E70E6C36D8E\"",
    "name": "hotels-vector-quickstart",
    "defaultScoringProfile": null,
    "fields": [
    {
        "name": "HotelId",
        "type": "Edm.String",
        "searchable": false,
        "filterable": true,
        "retrievable": true,
        "sortable": false,
        "facetable": false,
        "key": true,
        "indexAnalyzer": null,
        "searchAnalyzer": null,
        "analyzer": null,
        "dimensions": null,
        "vectorSearchProfile": null,
        "synonymMaps": []
    },
    [MORE FIELD DEFINITIONS OMITTED FOR BREVITY]
    ],
    "scoringProfiles": [],
    "corsOptions": null,
    "suggesters": [],
    "analyzers": [],
    "tokenizers": [],
    "tokenFilters": [],
    "charFilters": [],
    "encryptionKey": null,
    "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity",
    "k1": null,
    "b": null
    },
    "vectorSearch": {
    "algorithms": [
        {
        "name": "my-hnsw-vector-config-1",
        "kind": "hnsw",
        "hnswParameters": {
            "metric": "cosine",
            "m": 4,
            "efConstruction": 400,
            "efSearch": 500
        },
        "exhaustiveKnnParameters": null
        },
        {
        "name": "my-hnsw-vector-config-2",
        "kind": "hnsw",
        "hnswParameters": {
            "metric": "euclidean",
            "m": 4,
            "efConstruction": 400,
            "efSearch": 500
        },
        "exhaustiveKnnParameters": null
        },
        {
        "name": "my-eknn-vector-config",
        "kind": "exhaustiveKnn",
        "hnswParameters": null,
        "exhaustiveKnnParameters": {
            "metric": "cosine"
        }
        }
    ],
    "profiles": [
        {
        "name": "my-vector-profile",
        "algorithm": "my-hnsw-vector-config-1"
        }
    ]
    },
    "semantic": {
    "defaultConfiguration": null,
    "configurations": [
        {
        "name": "my-semantic-config",
        "prioritizedFields": {
            "titleField": {
            "fieldName": "HotelName"
            },
            "prioritizedContentFields": [
            {
                "fieldName": "Description"
            }
            ],
            "prioritizedKeywordsFields": [
            {
                "fieldName": "Category"
            }
            ]
        }
        }
    ]
    }
}

Points clés sur l’API REST Créer un index :

  • La collection fields inclut un champ de clé obligatoire, du texte et des champs vectoriels (tels que Description, DescriptionVector) pour la recherche de textes et de vecteurs. La colocalisation de champs vectoriels et non vectoriels dans le même index permet d’effectuer des requêtes hybrides. Par instance, vous pouvez combiner des filtres, une recherche de texte avec un classement sémantique et des vecteurs en une seule opération de requête.

  • Les champs vectoriels doivent être type: Collection(Edm.Single) avec les propriétés dimensions et vectorSearchProfile.

  • La section vectorSearch est un tableau de configurations et de profils d’algorithme approximatif voisin le plus proche. Les algorithmes pris en charge comprennent le petit monde navigable hiérarchique et le k-voisin le plus proche exhaustif. Pour plus d’informations, voir l’évaluation de la pertinence dans la recherche vectorielle.

  • La configuration semantic facultative permet de reclasser les résultats de la recherche. Vous pouvez reclasser les résultats dans des requêtes de type semantic pour les champs de chaîne spécifiés dans la configuration. Pour en savoir plus, voir Aperçu du classement sémantique.

Chargement de documents

La création et le chargement de l’index sont des étapes distinctes. Vous avez créé le schéma d’index à l’étape précédente. Vous devez maintenant charger des documents dans l’index.

Dans Recherche Azure AI, l’index contient toutes les données pouvant faire l’objet d’une recherche et les requêtes s’exécutent sur le service de recherche. Pour les appels REST, les données sont fournies sous forme de documents JSON. Utilisez Documents – API REST d’index pour cette tâche. L’URL est étendue pour inclure la collection docs et l’opération index.

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Upload documents dans le fichier. Ce bloc contient la requête de charger des documents sur l’index hotels-vector-quickstart sur votre service de recherche.

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart-vectors/docs/index?api-version=2023-11-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The hotel is ideally located on the main commercial artery of the city 
                in the heart of New York.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "pool",
                "air conditioning",
                "concierge"
            ],
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "2",
            "HotelName": "Old Century Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The hotel is situated in a  nineteenth century plaza, which has been 
                expanded and renovated to the highest architectural standards to create a modern, 
                functional and first-class hotel in which art and unique historical elements 
                coexist with the most modern comforts.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "pool",
                "air conditioning",
                "free wifi",
                "concierge"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "3",
            "HotelName": "Gastronomic Landscape Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The Hotel stands out for its gastronomic excellence under the management of 
                William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Resort and Spa",
            "Tags": [
                "air conditioning",
                "bar",
                "continental breakfast"
            ]
        }
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "4",
            "HotelName": "Sublime Palace Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Sublime Palace Hotel is located in the heart of the historic center of 
                Sublime in an extremely vibrant and lively area within short walking distance to 
                the sites and landmarks of the city and is surrounded by the extraordinary beauty 
                of churches, buildings, shops and monuments. 
                Sublime Palace is part of a lovingly restored 1800 palace.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "concierge",
                "view",
                "24-hour front desk service"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "13",
            "HotelName": "Luxury Lion Resort",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury 
                accommodations. Moments from the stadium, we feature the best in comfort",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Resort and Spa",
            "Tags": [
                "view",
                "free wifi",
                "pool"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "48",
            "HotelName": "Nordick's Valley Motel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Only 90 miles (about 2 hours) from the nation's capital and nearby 
                most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring 
                the caverns?  It's all nearby and we have specially priced packages to help make 
                our B&B your home base for fun while visiting the valley.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "continental breakfast",
                "air conditioning",
                "free wifi"
            ],
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "49",
            "HotelName": "Swirling Currents Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Spacious rooms, glamorous suites and residences, rooftop pool, walking 
                access to shopping, dining, entertainment and the city center.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Luxury",
            "Tags": [
                "air conditioning",
                "laundry service",
                "24-hour front desk service"
            ]
        }
    ]
}

    Important

    Le code de cet exemple n’est pas exécutable. Plusieurs caractères ou lignes sont supprimés pour la concision. Utilisez le code dans votre fichier az-search-vector-quickstart.rest pour exécuter la requête.

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 200 OK. Le corps de la réponse doit inclure la représentation JSON des documents de recherche.

Points clés sur les documents - Requête de l’API REST d’index :

  • Les documents de la charge utile se composent de champs définis dans le schéma d’index.

  • Les champs vectoriels contiennent des valeurs à virgule flottante. L’attribut dimensions a un minimum de 2 et un maximum de 3,072 valeurs à virgule flottante chacun. Ce guide de démarrage rapide définit l’attribut dimensions sur 1,536, car il s’agit de la taille des incorporations générées par le modèle text-embedding-ada-002 d’Azure OpenAI.

Exécuter des requêtes

Maintenant que des documents sont chargés, vous pouvez émettre des requêtes vectorielles les concernant à l’aide de Documents – Rechercher des publications (REST).

Dans les sections suivantes, nous exécutons des requêtes sur l’index hotels-vector-quickstart. Les requêtes incluent :

L’exemple des requêtes vectorielles sont basés sur deux chaînes :

  • Rechercher une chaîne : historic hotel walk to restaurants and shopping
  • Chaîne de requête Vector (vectorisée en représentation mathématique) : classic lodging near running trails, eateries, retail

La chaîne de requête vectorielle est sémantiquement similaire à la chaîne de recherche, mais contient des termes qui n’existent pas dans l’index de recherche. Si vous effectuez une recherche par mot clé pour classic lodging near running trails, eateries, retail, les résultats sont nuls. Cet exemple est utilisé pour montrer comment obtenir des résultats pertinents même s’il n’existe aucun terme correspondant.

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Run a single vector query dans le fichier. Ce bloc contient la requête d’interrogation de l’index de recherche.

    ### Run a single vector query
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

    {
        "count": true,
        "select": "HotelId, HotelName, Description, Category",
        "vectorQueries": [
            {
                "vector"": [0.01944167, 0.0040178085
                    . . .  TRIMMED FOR BREVITY
                    010858015, -0.017496133],
                "k": 7,
                "fields": "DescriptionVector",
                "kind": "vector",
                "exhaustive": true
            }
        ]
    }

    Cette requête vectorielle est raccourcie pour la concision. Le vectorQueries.vector contient le texte vectorisé de l’entrée de requête, fields détermine les champs vectoriels recherchés et k spécifie le nombre des plus proches voisins à retourner.

    La chaîne de requête vectorielle est classic lodging near running trails, eateries, retail, qui est vectorisée en 1,536 incorporations pour cette requête.

    Important

    Le code de cet exemple n’est pas exécutable. Plusieurs caractères ou lignes sont supprimés pour la concision. Utilisez le code dans votre fichier az-search-vector-quickstart.rest pour exécuter la requête.

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 200 OK. Le corps de la réponse doit inclure la représentation JSON des résultats de recherche.

La réponse du vecteur équivalent de classic lodging near running trails, eateries, retail comprend sept résultats. Chaque résultat donne un score de recherche et les champs répertoriés dans select. Dans une recherche de similarité, la réponse inclut toujours les résultats k classés par ordre de similarité de la valeur.

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 7,
  "value": [
    {
      "@search.score": 0.85773647,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8399132,
      "HotelId": "49",
      "HotelName": "Old Carrabelle Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
      "Category": "Luxury"
    },
    {
      "@search.score": 0.83839583,
      "HotelId": "13",
      "HotelName": "Historic Lion Resort",
      "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
      "Category": "Resort and Spa"
    },
    {
      "@search.score": 0.82543474,
      "HotelId": "4",
      "HotelName": "Sublime Cliff Hotel",
      "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.82380104,
      "HotelId": "1",
      "HotelName": "Secret Point Hotel",
      "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8151413,
      "HotelId": "2",
      "HotelName": "Twin Dome Hotel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8133767,
      "HotelId": "3",
      "HotelName": "Triple Landscape Hotel",
      "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel\u2019s restaurant services.",
      "Category": "Resort and Spa"
    }
  ]
}

Recherche vectorielle unique avec filtre

Vous pouvez ajouter des filtres, mais les filtres sont appliqués au contenu non vectoriel de votre index. Dans cet exemple, le filtre s’applique au champ Tags pour filtrer les hôtels qui ne fournissent pas de wifi gratuit.

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Run a vector query with a filter dans le fichier. Ce bloc contient la requête d’interrogation de l’index de recherche.

    ### Run a vector query with a filter
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

    {
        "count": true,
        "select": "HotelId, HotelName, Category, Tags, Description",
        "filter": "Tags/any(tag: tag eq 'free wifi')",
        "vectorFilterMode": "postFilter",
        "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED ],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        },
    ]
}

    Important

    Le code de cet exemple n’est pas exécutable. Plusieurs caractères ou lignes sont supprimés pour la concision. Utilisez le code dans votre fichier az-search-vector-quickstart.rest pour exécuter la requête.

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 200 OK. Le corps de la réponse doit inclure la représentation JSON des résultats de recherche.

La requête est la même que dans l'exemple précédent de recherche vectorielle unique, mais elle inclut un filtre d'exclusion post-traitement et ne renvoie que les trois hôtels disposant d'une connexion Wi-Fi gratuite.

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 0.85773647,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Tags": [
        "continental breakfast",
        "air conditioning",
        "free wifi"
      ]
    },
    {
      "@search.score": 0.83839583,
      "HotelId": "13",
      "HotelName": "Historic Lion Resort",
      "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
      "Category": "Resort and Spa",
      "Tags": [
        "view",
        "free wifi",
        "pool"
      ]
    },
    {
      "@search.score": 0.8151413,
      "HotelId": "2",
      "HotelName": "Twin Dome Hotel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "air conditioning",
        "concierge"
      ]
    }
  ]
}

La recherche hybride se compose de requêtes par mot clé et de requêtes vectorielles dans une seule requête de recherche. Cet exemple exécute simultanément la requête vectorielle et la recherche de texte intégral :

  • Rechercher une chaîne : historic hotel walk to restaurants and shopping
  • Chaîne de requête Vector (vectorisée en représentation mathématique) : classic lodging near running trails, eateries, retail

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Run a hybrid query dans le fichier. Ce bloc contient la requête d’interrogation de l’index de recherche.

    ### Run a hybrid query
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description",
    "top": 7,
    "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

    Important

    Le code de cet exemple n’est pas exécutable. Plusieurs caractères ou lignes sont supprimés pour la concision. Utilisez le code dans votre fichier az-search-vector-quickstart.rest pour exécuter la requête.

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 200 OK. Le corps de la réponse doit inclure la représentation JSON des résultats de recherche.

Étant donné qu’il s’agit d’une requête hybride, les résultats sont classés par fusion de rang réciproque (RRF). RRF évalue les scores de plusieurs résultats de recherche, prend l’inverse, puis fusionne et trie les résultats combinés. top est le nombre de résultats retournés.

Passer en revue la réponse :

{
    "@odata.count": 7,
    "value": [
        {
            "@search.score": 0.03279569745063782,
            "HotelName": "Luxury Lion Resort",
            "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort"
        },
        {
            "@search.score": 0.03226646035909653,
            "HotelName": "Sublime Palace Hotel",
            "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
        },
        {
            "@search.score": 0.03226646035909653,
            "HotelName": "Swirling Currents Hotel",
            "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center."
        },
        {
            "@search.score": 0.03205128386616707,
            "HotelName": "Nordick's Valley Motel",
            "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley."
        },
        {
            "@search.score": 0.03128054738044739,
            "HotelName": "Gastronomic Landscape Hotel",
            "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services."
        },
        {
            "@search.score": 0.03100961446762085,
            "HotelName": "Old Century Hotel",
            "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
        },
        {
            "@search.score": 0.03077651560306549,
            "HotelName": "Stay-Kay City Hotel",
            "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York."
        }
    ]
}

Étant donné que RRF fusionne les résultats, il permet de passer en revue les entrées. Les résultats suivants proviennent uniquement de la requête de texte intégral. Les deux premiers résultats sont Sublime Palace Hotel et History Lion Resort. Le Sublime Palace Hotel a un meilleur score de pertinence BM25.

{
    "@search.score": 2.2626662,
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
},
{
    "@search.score": 0.86421645,
    "HotelName": "Luxury Lion Resort",
    "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort"
},

Dans la requête vectorielle seule, qui utilise HNSW pour trouver des correspondances, l’hôtel Sublime Palace tombe en quatrième position. Historic Lion, qui était en deuxième position dans la requête de texte intégral et en troisième position dans la recherche vectorielle, ne connaît pas la même amplitude de fluctuation, de sorte qu’il apparaît en tête de liste dans un ensemble de résultats homogénéisés.

"value": [
    {
        "@search.score": 0.857736,
        "HotelId": "48",
        "HotelName": "Nordick's Valley Motel",
        "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.8399129,
        "HotelId": "49",
        "HotelName": "Swirling Currents Hotel",
        "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
        "Category": "Luxury"
    },
    {
        "@search.score": 0.8383954,
        "HotelId": "13",
        "HotelName": "Luxury Lion Resort",
        "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
        "Category": "Resort and Spa"
    },
    {
        "@search.score": 0.8254346,
        "HotelId": "4",
        "HotelName": "Sublime Palace Hotel",
        "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.82380056,
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.81514084,
        "HotelId": "2",
        "HotelName": "Old Century Hotel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.8133763,
        "HotelId": "3",
        "HotelName": "Gastronomic Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa"
    }
]

Recherche hybride sémantique avec un filtre

Voici la dernière requête de la collection. Cette requête hybride avec classement sémantique est filtrée pour n’afficher que les hôtels situés dans un rayon de 500 kilomètres autour de Washington D.C. Vous pouvez définir vectorFilterMode sur null, ce qui équivaut à la valeur par défaut (preFilter pour les index plus récents et les postFilter pour les anciens).

  1. Dans Visual Studio Code, ouvrez le fichier az-search-vector-quickstart.rest que vous avez créé précédemment .

  2. Recherchez le bloc de code ### Run a hybrid query with semantic reranking dans le fichier. Ce bloc contient la requête d’interrogation de l’index de recherche.

    ### Run a hybrid query with semantic reranking
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Description,Address/City, Address/StateProvince",
    "filter": "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 500",
    "vectorFilterMode": null,
    "facets": [ "Address/StateProvince"],
    "top": 7,
    "queryType": "semantic",
    "answers": "extractive|count-3",
    "captions": "extractive|highlight-true",
    "semanticConfiguration": "my-semantic-config",
    "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED ],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

    Important

    Le code de cet exemple n’est pas exécutable. Plusieurs caractères ou lignes sont supprimés pour la concision. Utilisez le code dans votre fichier az-search-vector-quickstart.rest pour exécuter la requête.

  3. Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 200 OK. Le corps de la réponse doit inclure la représentation JSON des résultats de recherche.

Vérifiez la réponse. La réponse est constituée de trois hôtels, qui sont filtrés par emplacement et facettés par StateProvince et sémantiquement reclassés pour promouvoir les résultats les plus proches de la chaîne de recherche (historic hotel walk to restaurants and shopping).

L’hôtel Swirling Currents occupe désormais la première place. Sans classement sémantique, le Nordick's Valley est le numéro 1. Avec le classement sémantique, les modèles de compréhension automatique reconnaissent qu’il historic s’agit d’un « hôtel situé à proximité de restaurants et de magasins ».

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 2,
  "@search.facets": {
    "Address/StateProvince": [
      {
        "count": 1,
        "value": "VA"
      }
    ]
  },
  "@search.answers": [],
  "value": [
    {
      "@search.score": 0.03306011110544205,
      "@search.rerankerScore": 2.8773112297058105,
      "HotelId": "49",
      "HotelName": "Old Carrabelle Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
      "Category": "Luxury",
      "Address": {
        "City": "Arlington",
        "StateProvince": "VA"
      }
    },
    {
      "@search.score": 0.03306011110544205,
      "@search.rerankerScore": 2.1703834533691406,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Address": {
        "City": "Washington D.C.",
        "StateProvince": null
      }
    }
  ]
}

Points clés sur les documents - Rechercher une API REST post- :

  • La recherche vectorielle est spécifiée par le biais de la propriété de vectors.value. La recherche par mot-clé est spécifiée par le biais de la propriété search.

  • Dans une recherche hybride, vous pouvez intégrer la recherche vectorielle à la requête de texte intégral par mots-clés. Les filtres, le contrôle orthographique et le classement sémantique s’appliquent uniquement au contenu textuel, et non aux vecteurs. Dans cette dernière requête, answer n’inclut pas la sémantique, car le système n’en a pas produit une qui était suffisamment forte.

  • Les résultats réels incluent plus de détails, notamment les textes de légendes sémantiques et les mises en surbrillance. Les résultats ont été modifiés pour des raisons de lisibilité. Pour obtenir la structure complète de la réponse, exécutez la requête dans le client REST.

Nettoyage

Lorsque vous travaillez dans votre propre abonnement, il est recommandé, à la fin de chaque projet, de déterminer si vous avez toujours besoin des ressources que vous avez créées. Les ressources laissées en cours d’exécution peuvent vous coûter de l’argent. Vous pouvez supprimer les ressources individuellement, ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

Vous pouvez rechercher et gérer des ressources dans le portail Azure avec les liens Toutes les ressources ou Groupes de ressources situés dans le volet le plus à gauche.

Si vous souhaitez conserver le service de recherche, mais supprimer l’index et les documents, vous pouvez utiliser la commande DELETE dans le client REST. Cette commande (à la fin de votre fichier az-search-vector-quickstart.rest ) supprime l’index hotels-vector-quickstart :

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-vector-quickstart?api-version=2023-11-01 HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

Étapes suivantes

À l’étape suivante, nous vous recommandons d’apprendre à appeler des appels d’API REST sans clés API.

Vous pouvez également passer en revue le code de démonstration pour Python, C# ou JavaScript.