Effectuer une mise à niveau vers la dernière API REST dans Recherche Azure AI

Article
05/21/2024

Utilisez cet article pour migrer les appels du plan de données vers des versions plus récentes des API REST de recherche.

2023-11-01 est la version stable la plus récente. Le classement sémantique ainsi que la prise en charge de l’indexation et des requêtes vectorielles sont généralement disponibles dans cette version.

Si vous effectuez une mise à niveau de la version 2023-10-01-preview à la version 2023-11-01, il n’existe aucun changement cassant. Toutefois, il existe une différence de comportement : la valeur par défaut de vectorFilterMode est passée de postfilter à prefilter pour les expressions de filtre. Si le code de la version 2023-10-01-preview ne définit pas explicitement vectorFilterMode, vérifiez que vous comprenez le nouveau comportement par défaut ou affectez explicitement la valeur postfilter à vectorFilterMode pour conserver l’ancien comportement.
2024-05-01-preview est la préversion d’API la plus récente. Elle ajoute un type de données binaire pour les champs vectoriels, des propriétés de pertinence pour générer de meilleurs résultats de recherche, l’indexeur de fichiers OneLake, d’autres vectoriseurs et d’autres compétences d’incorporation. La compétence AzureOpenAIEmbedding est mise à jour pour inclure les propriétés dimensions et modelName. La seule différence en termes de compatibilité descendante entre cette préversion et les deux préversions précédentes est que modelName est désormais obligatoire.
La préversion 2024-03-01-preview ajoute de nouveaux types de données et de nouvelles propriétés pour la compression, mais elle offre une compatibilité descendante complète avec 2023-10-01-preview. Aucune instruction de mise à niveau n’est fournie pour utiliser cette préversion.
2023-10-01-preview est la première préversion qui ajoute la vectorisation de requête intégrée, la vectorisation et la segmentation de données intégrées pendant l’indexation (utilise les compétences Fractionnement de texte et Incorporation d’Azure OpenAI). Elle introduit des changements cassants dans la configuration vectorielle au niveau des requêtes d’index et de vecteur.
2023-07-01-preview a constitué la première API REST pour la prise en charge de vecteurs. Elle est désormais déconseillée et vous devez immédiatement migrer vers 2023-11-01 ou l’une des API REST en préversion plus récentes.

Remarque

Les documents relatifs à la référence API REST sont désormais versionnés. Pour obtenir le contenu approprié, ouvrez une page de référence, puis filtrez par région en utilisant le sélecteur situé au-dessus de la table des matières.

Quand mettre à niveau

Recherche Azure AI arrête la compatibilité descendante en dernier ressort. La mise à niveau est requise dans le cas suivant :

Votre code fait référence à une version d’API mise hors service ou déconseillée et est soumis à un ou plusieurs changements cassants. Les versions d’API qui appartiennent à cette catégorie incluent la version 2023-07-10-preview pour les vecteurs et la version 2019-05-06 pour les compétences et solutions de contournement obsolètes.
Lorsque votre code échoue, car des propriétés non reconnues sont renvoyées dans une réponse de l’API. La meilleure pratique consiste à ce que votre application ignore les propriétés qu'elle ne comprend pas.
Votre code conserve des demandes d’API et tente de les renvoyer à la nouvelle version de l’API. Par exemple, cela peut se produire si votre application conserve les jetons de continuation renvoyés par l’API Recherche (pour plus d’informations, recherchez @search.nextPageParameters dans les références sur l’API Recherche).

Changement cassant pour le code client qui lit les informations de connexion

À compter du 29 mars 2024 et s’applique à toutes les API REST prises en charge :

get Skillset, GET Indexet GET Indexer ne retourne plus de clés ni de propriétés de connexion dans une réponse. Il s’agit d’une modification cassant si vous avez du code en aval qui lit des clés ou des connexions (données sensibles) à partir d’une réponse GET.
Si vous devez récupérer des clés API d’administrateur ou de requête pour votre service de recherche, utilisez les API REST de gestion.
Si vous devez récupérer des chaînes de connexion d’une autre ressource Azure telle que Stockage Azure ou Azure Cosmos DB, utilisez les API de cette ressource et des instructions publiées pour obtenir les informations.

Changement cassant pour le classement sémantique

Le classement sémantique sera en disponibilité générale à partir de la version 2023-11-01. Contrairement aux versions précédentes de l’API REST, cette version n’utilise plus la propriété queryLanguage. Elle nécessite également une définition semanticConfiguration qui remplace searchFields dans les versions antérieures. Consultez Migrer à partir de la préversion pour passer de votre code à la version en disponibilité générale ou une version plus récente.

Mise à niveau à partir de 2023-07-01-preview

Cette section explique le chemin de migration entre la version 2023-07-01-preview et toute version plus récente de l’API. Il existe plusieurs changements cassants entre la version 2023-07-01-preview et les versions plus récentes, mais les versions d’API ultérieures ne présentent que des problèmes de compatibilité mineurs entre elles.

Les instructions de mise à niveau portent sur les modifications de code à effectuer pour tenir compte des changements cassants apportés aux versions précédentes et faire en sorte que le code s’exécute de la même façon sur la version d’API plus récente. Une fois que votre code se trouve dans un état opérationnel, vous pouvez décider d’adopter ou non des fonctionnalités plus récentes. Pour en savoir plus sur les fonctionnalités en préversion, consultez les exemples de code vectoriel et les nouveautés.

Mise à niveau du portail pour les index vectoriels

Le portail Azure prend en charge un chemin d'accès de mise à niveau en un clic pour les index de version préliminaire 2023-07-01. Le portail détecte les champs vectoriels de la version 2023-07-01-preview, et fournit un bouton Migrer.

Le chemin de migration va de la version 2023-07-01-preview à la version 2023-10-01-preview.
Les mises à jour sont limitées aux définitions de champ vectoriel et aux configurations d’algorithme de recherche vectorielle.
Les mises à jour sont unidirectionnelles. Vous ne pouvez pas inverser la mise à niveau. Une fois l’index mis à niveau, vous devez utiliser la version 2023-10-01-preview ou une version ultérieure pour interroger l’index.

Il n’existe aucune migration du portail pour la mise à niveau de la syntaxe de requête vectorielle. Consultez la mise à niveau vers la version 2023-11-01 pour connaître les changements apportés à la syntaxe de requête.

Avant de sélectionner Effectuer une migration, sélectionnez Modifier JSON pour passer en revue le schéma mis à jour en premier. Vous trouverez un schéma conforme aux modifications décrites dans la section Mise à niveau du code. La migration du portail gère uniquement les index ayant une seule configuration d’algorithme de recherche vectorielle. Elle crée un profil par défaut, qui est mappé à l’algorithme de recherche vectorielle de la version 2023-07-01-preview. Les index avec plusieurs configurations de recherche vectorielle nécessitent une migration manuelle.

Mise à niveau du code pour les requêtes et les index vectoriels

La prise en charge de Recherche vectorielle a été introduite dans Créer ou mettre à jour un index (version préliminaire 2023-07-01).

La mise à niveau à partir de 2023-07-01-preview vers une version stable ou une préversion plus récente nécessite les opérations suivantes :

Renommage et restructuration de la configuration vectorielle dans l’index
Réécriture de vos requêtes vectorielles

Utilisez les instructions de cette section pour migrer les champs vectoriels, la configuration et les requêtes à partir de 2023-07-01-preview.

Appelez Obtenir l'index pour récupérer la définition existante.

Modifiez la configuration de recherche vectorielle. Les versions 2023-11-01 et ultérieures introduisent le concept de profils vectoriels qui regroupent les configurations liées aux vecteurs sous un seul nom. Dans les versions plus récentes, algorithmConfigurations est également renommé algorithms.

Renommez algorithmConfigurations en algorithms. Il s'agit uniquement d'un changement de nom du tableau. Le contenu est rétrocompatible. Les paramètres de configuration existants de HNSW peuvent donc être utilisés.
Ajoutez profiles, en donnant un nom et une configuration d'algorithme pour chacun d'eux.

Avant la migration (version préliminaire 2023-07-01) :

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

Après la migration (2023-11-01) :

  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

Modifiez les définitions de champ vectoriel, en remplaçant vectorSearchConfiguration qui devient vectorSearchProfile. Assurez-vous que le nom du profil se réfère à une nouvelle définition de profil vectoriel et non au nom de la configuration de l'algorithme. Les autres propriétés de champ vectoriel restent inchangées. Par exemple, ils ne peuvent pas être filtrables, triables ou à facettes, ni utiliser des analyseurs, des normalisateurs ou des mappages de synonymes.

Avant (version préliminaire 2023-07-01) :

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

Après (2023-11-01) :

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

Appelez Créer ou mettre à jour l'index pour publier les modifications.
Modifier Publication Recherche pour changer la syntaxe de la requête. Cette modification d'API permet la prise en charge des types de requêtes vectorielles polymorphes.
- Renommez vectors en vectorQueries.
- Pour chaque requête vectorielle, ajoutez kind, en lui affectant la valeur vector.
- Pour chaque requête vectorielle, renommez value qui devient vector.
- Vous pouvez éventuellement ajouter vectorFilterMode si vous utilisez des expressions de filtre. La valeur par défaut est préfiltre pour les index créés après la version 2023-10-01. Les index créés avant cette date prennent uniquement en charge le postfiltre, quelle que soit la manière dont vous définissez le mode de filtrage.
Avant (version préliminaire 2023-07-01) :
```
{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}
```
Après (2023-11-01) :
```
{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}
```

Ces étapes permettent d’effectuer la migration vers la version d’API stable 2023-11-01 ou les préversions d’API plus récentes.

Mise à niveau vers la version 2020-06-30

Dans cette version, on observe un changement radical et plusieurs différences de comportement. Les fonctionnalités généralement disponibles sont les suivantes :

La base de connaissances, un stockage persistant de contenu enrichi créé via des ensembles de compétences, pour l’analyse et le traitement en aval par le biais d’autres applications. Une base de connaissances est créée via des API REST Recherche Azure AI, mais elle réside dans Stockage Azure.

Modification critique

Le code écrit pour des versions d’API antérieures casse dans 2020-06-30 et les versions ultérieures, s’il contient les fonctionnalités suivantes :

Les littéraux Edm.Date (date avec la combinaison année-mois-jour, par exemple 2020-12-12) dans les expressions de filtre doivent respecter le format Edm.DateTimeOffset : 2020-12-12T00:00:00Z. Cette modification était nécessaire pour gérer les résultats de requête erronés ou inattendus en raison de différences entre les fuseaux horaires.

Changements de comportement

L’algorithme de classement BM25 remplace l’algorithme de classement précédent par une technologie plus récente. Les services créés après 2019 utilisent automatiquement cet algorithme. Pour les services existants, vous devez définir des paramètres pour utiliser le nouvel algorithme.
Les résultats ordonnés pour les valeurs null ont été modifiés dans cette version ; les valeurs null apparaissent en premier si le tri est asc et en dernier si le tri est desc. Si vous avez écrit du code pour gérer le mode de tri des valeurs null, tenez compte de cette modification.

Mise à niveau vers la version 2019-05-06

Les fonctionnalités désormais en disponibilité générale dans cette version de l’API sont notamment :

L’autocomplétion est une fonctionnalité prédictive qui complète une entrée de terme partiellement saisie.
Les types complexes assurent la prise en charge native des données d’objet structurées dans un index de recherche.
Les modes d’analyse JsonLines, inclus dans l’indexation des objets Blob Azure, créent un document de recherche par entité JSON, séparé par un saut de ligne.
L’enrichissement par IA assure une indexation qui utilise les moteurs d’enrichissement IA des services Azure AI.

Dernières modifications

Le code écrit pour une version d’API antérieure casse dans 2019-05-06 et les versions ultérieures, s’il contient les fonctionnalités suivantes :

Propriété de type pour Azure Cosmos DB. Pour des indexeurs ciblant une source de données d’API Azure Cosmos DB for NoSQL, remplacez "type": "documentdb" par "type": "cosmosdb".
Si la gestion des erreurs de votre indexeur comprend des références à la propriété status, vous devez la supprimer. Nous avons supprimé l’état dans la réponse d’erreur, car il ne fournissait aucune information utile.
Les chaînes de connexion de source de données ne sont plus renvoyées dans la réponse. À partir des versions d’API 2019-05-06 et 2019-05-06-Preview, l’API de source de données ne retourne plus de chaînes de connexion dans la réponse d’une opération REST. Dans les versions d’API précédentes, pour les sources de données créées à l’aide de POST, Recherche Azure AI retournait 201, suivi de la réponse OData, qui contenait la chaîne de connexion en texte brut.
La compétence cognitive Reconnaissance d’entité nommée est mise hors service. Si vous avez appelé la compétence Reconnaissance d'entité nommée dans votre code, l'appel échoue. La fonctionnalité de remplacement est Compétence de reconnaissance d’entité (V3). Suivez les recommandations de la page Compétences déconseillées pour migrer vers une compétence prise en charge.

Mise à niveau des types complexes

La version d’API 2019-05-06 contient désormais une prise en charge formelle des types complexes. Si votre code implémente les recommandations précédentes pour l’équivalence des types complexes dans la version 2017-11-11-Preview ou 2016-09-01-Preview, vous devez prendre en compte certaines limites, nouvelles ou changées, à partir de la version 2019-05-06 :

Les limites relatives à la profondeur des sous-champs et au nombre de collections complexes par index ont été réduites. Si vous avez créé des index qui dépassent ces limites à l’aide de versions d’API en préversion, toute tentative de mise à jour ou de recréation de ces index avec la version d’API 2019-05-06 échouera. Si vous vous trouvez dans une telle situation, vous devez reconcevoir votre schéma de sorte qu'il respecte les nouvelles limites, puis reconstruire votre index.
Il existe une nouvelle limite à partir de la version d’API 2019-05-06 concernant le nombre d’éléments de collections complexes par document. Si vous avez créé des index avec des documents qui dépassent ces limites à l’aide d’API en préversion, toute tentative de réindexation de ces données avec la version d’API 2019-05-06 échouera. Si vous vous trouvez dans cette situation, vous devez réduire le nombre d'éléments de collections complexes par document avant de réindexer vos données.

Pour plus d’informations, consultez Limites de service pour Recherche Azure AI.

Comment mettre à niveau une ancienne structure de type complexe

Si votre code utilise des types complexes avec l'une des anciennes versions d'API en version préliminaire, vous utilisez peut-être un format de définition d'index qui se présente ainsi :

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

Un format plus récent de type arborescence pour la définition des champs d’index a été introduit dans la version d’API 2017-11-11-Preview. Avec le nouveau format, chaque champ complexe dispose d’une collection de champs dont les sous-champs sont définis. Dans la version d’API 2019-05-06, ce nouveau format est utilisé exclusivement. Toute tentative de création ou de mise à jour d’un index à l’aide de l’ancien format échouera. Si vous avez créé des index à l’aide de l’ancien format, vous devez utiliser la version d’API 2017-11-11-Preview pour les mettre à jour vers le nouveau format afin qu’ils puissent être gérés avec la version d’API 2019-05-06.

Vous pouvez mettre à jour des index plats vers le nouveau format en suivant les étapes ci-dessous avec la version d’API 2017-11-11-Preview :

Effectuez une requête GET pour récupérer votre index. S’il est déjà au nouveau format, vous avez terminé.
Traduisez l’index à partir du format « plat » vers le nouveau format. Vous devez écrire du code pour cette tâche. En effet, aucun exemple de code n'est disponible au moment de la rédaction de ce document.
Effectuez une requête PUT pour mettre à jour l’index vers le nouveau format. Veillez à ne modifier aucune autre information de l’index, telle que la possibilité de filtrer ou d’effectuer des recherches dans les champs, car les modifications qui affectent l’expression physique de l’index existant ne sont pas autorisées par l’API Update Index.