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

Article
10/01/2024

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

2024-07-01 est la version stable la plus récente.
2024-09-01-preview est la préversion d’API la plus récente.

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 découvrir plus d’informations sur les nouvelles fonctionnalités, consultez les exemples de code vectoriel et les Nouveautés.

Nous recommandons de mettre à niveau les versions d’API successivement, en utilisant chaque version jusqu’à la plus récente.

2023-07-01-preview était la première API REST à prendre en charge les vecteurs. N’utilisez pas cette version d’API. Elle est désormais déconseillée et vous devez immédiatement migrer vers des API REST stables ou leur plus récente préversion.

Remarque

Les documents relatifs à la référence API REST sont désormais versionnés. Pour obtenir un contenu spécifique à la version, ouvrez une page de référence, puis utilisez le sélecteur situé à droite, au-dessus de la table des matières, pour choisir votre version.

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 non prise en charge et est soumis à un ou plusieurs changements cassants. Vous devez gérer les changements cassants si votre code cible 2023-07-10-preview pour les vecteurs, 2020-06-01-preview pour le classeur sémantique et 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).

Mise à niveau

Passez en revue les notes de publication pour chaque version d’API.
Mettez à jour le paramètre api-version, spécifié dans l’en-tête de demande, vers une version plus récente.

Dans le code de votre application qui effectue des appels directs aux API REST, recherchez toutes les instances de la version existante et remplacez-la par la nouvelle version. Pour plus d’informations sur la structuration d’un appel REST, consultez Démarrage rapide : utilisation de REST.

Si vous utilisez un Kit de développement logiciel (SDK) Azure, ces packages ciblent des versions spécifiques de l’API REST. Les mises à jour de package peuvent coïncider avec une mise à jour de l’API REST, mais chaque Kit de développement logiciel (SDK) suit son propre calendrier de mise en production, indépendamment des versions de l’API REST de Recherche Azure AI. Vérifiez le journal des modifications de votre package SDK pour déterminer si une version du package cible la dernière version de l’API REST.
Passez en revue les changements cassants documentés dans cet article et implémentez les solutions de contournement. Commencez par la version utilisée par votre code et résolvez les changements cassants pour chaque version d’API plus récente jusqu’à ce que vous obteniez la mise en production stable ou de préversion la plus récente.

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

Effectifs à compter du 29 mars 2024 et applicables à 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 classeur sémantique

Le Classeur sémantique est en disponibilité générale le 2023-11-01. Voici les changements cassants du classeur sémantique des versions antérieures :

Dans toutes les versions ultérieures à la version 2020-06-01-preview: semanticConfiguration remplace searchFields comme mécanisme permettant de spécifier les champs à utiliser dans le classement L2.
Pour toutes les versions d’API, les mises à jour du 14 juillet 2023 aux modèles sémantiques hébergés par Microsoft ont rendu le classeur sémantique indépendant de la langue, désaffectant efficacement la propriété queryLanguage. Il n’y a aucun « changement cassant » dans le code, mais la propriété est ignorée.

Consultez Migrer à partir d’une préversion pour faire la transition de votre code afin d’utiliser semanticConfiguration.

Mettre à niveau vers la préversion 2024-09-01-preview

2024-09-01-preview ajoute la compression MRL (Matrioshka Representation Learning) pour les modèles text-embedding-3, le filtrage vectoriel ciblé pour les requêtes hybrides, les détails du sous-score vectoriel pour le débogage ainsi que la segmentation de jetons pour la compétence Fractionnement de texte.

Si vous effectuez une mise à niveau à partir de 2024-05-01-preview, vous pouvez utiliser les nouvelles API en préversion sans changer le code existant.

Mise à niveau vers 2024-07-01

2024-07-01 est une mise en production générale. Les fonctionnalités en préversion précédentes sont en disponibilité générale : vectorisation et segmentation intégrées (compétence Fractionnement de texte, compétence AzureOpenAIEmbedding), vectoriseur de requête basé sur AzureOpenAIEmbedding, compression vectorielle (quantification scalaire, quantification binaire, propriété stockée, types de données étroits).

Il n’y a aucun changement cassant si vous effectuez une mise à niveau de 2024-05-01-preview vers stable. Pour utiliser la nouvelles version stable, modifiez la version d’API et testez votre code.

Il a des changements cassants si vous effectuez une mise à niveau directement à partir de 2023-11-01. Suivez les étapes présentées pour chaque préversion plus récente pour migrer de 2023-11-01 vers 2024-07-01.

Mettre à niveau vers 2024-05-01-préversion

2024-05-01-preview ajoute l’index OneLake, la prise en charge des vecteurs binaires et de modèles d’incorporation supplémentaires.

Si vous mettez à niveau à partir de la version 2024-03-01-preview, la compétence AzureOpenAIEmbedding nécessite désormais un nom de modèle et une propriété de dimensions.

Recherchez des références AzureOpenAIEmbedding dans votre codebase.
Définissez modelName sur « text-embedding-ada-002 » et dimensions sur « 1536 ».

Mettre à niveau vers 2024-03-01-préversion

2024-03-01-preview ajoute des types de données étroits, une quantification scalaire et des options de stockage vectoriel.

Si vous mettez à niveau à partir de 2023-10-01-preview, il n’y a aucun changement cassant. Cependant, il y a une différence de comportement : dans la version 2023-11-01 et les préversions les plus récentes, la valeur par défaut vectorFilterMode passe de postfiltre à préfiltre pour les expressions de filtre.

Recherchez des références vectorFilterMode dans votre codebase.
Si la propriété est définie explicitement, aucune action n’est requise. Si vous avez utilisé la valeur par défaut, sachez que le nouveau comportement par défaut consiste à filtrer avant l’exécution de la requête. Si vous souhaitez un filtrage post-requête, définissez explicitement vectorFilterMode sur postfiltre pour conserver l’ancien comportement.

Mettre à niveau vers la version 2023-11-01

2023-11-01 est une mise en production générale. Les fonctionnalités de préversion précédentes sont désormais en disponibilité générale : classeur sémantique, index vectoriel et prise en charge des requêtes.

Il n’y a aucun changement cassant à partir de 2023-10-01-preview, mais il en existe plusieurs à partir de 2023-07-01-preview vers 2023-11-01. Pour obtenir plus d’informations, consultez Mise à niveau à partir de 2023-07-01-preview.

Pour utiliser la nouvelles version stable, modifiez la version d’API et testez votre code.

Mise à niveau vers 2023-10-01-preview

2023-10-01-preview était la première préversion permettant d’ajouter une segmentation et une vectorisation de données intégrées lors de l’indexation et une vectorisation de requête intégrée. Elle prend également en charge l’indexation vectorielle et les requêtes de la version précédente.

Si vous mettez à niveau à partir de la version précédente, la section suivante comporte les étapes à suivre.

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

N’utilisez pas cette version d’API. Elle implémente une syntaxe de requête vectorielle incompatible avec une version d’API plus récente.

2023-07-01-preview est déconseillé, donc ne basez pas de nouveau code sur cette version et ne procédez pas non plus à une mise à niveau vers cette version. Cette section explique le chemin de migration de la version 2023-07-01-preview vers une version d’API plus récente.

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 des index 2023-07-01-preview. Il détecte les champs vectoriels et fournit un bouton Migrer.

Le chemin de migration fait passer de la version 2023-07-01-preview à la version 2024-05-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 2024-05-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 mappe à 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 de la version 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

Suivez les instructions contenues dans cette section pour migrer les champs, la configuration et les requêtes vectoriels de la version 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 effectuent la migration vers une version d’API stable 2023-11-01 ou les dernières préversions d’API.

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 échoue. 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.