Créer ou mettre à jour un index (API REST en préversion)

s’applique à: 2023-07-01-Preview. Cette version n’est plus prise en charge. mettre à niveau immédiatement vers une version plus récente.

Un index spécifie le schéma d’index, y compris la collection de champs (noms de champs, types de données et attributs), mais également d’autres constructions (suggesteurs, profils de scoring et configuration CORS) qui définissent d’autres comportements de recherche.

Vous pouvez utiliser POST ou PUT sur une demande de création. Pour l’une ou l’autre, le corps de la requête fournit la définition d’objet.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version]  
  Content-Type: application/json
  api-key: [admin key]  

Pour les demandes de mise à jour, utilisez PUT et spécifiez le nom de l’index sur l’URI.

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

HTTPS est requis pour toutes les demandes de service. Si l’index n’existe pas, il est créé. S’il existe déjà, il est mis à jour vers la nouvelle définition.

Création d’un index établit le schéma et les métadonnées. Remplir l’index est une opération distincte. Pour cette étape, vous pouvez utiliser un indexeur (voir opérations d’indexeur, disponibles pour les sources de données prises en charge) ou Ajouter, mettre à jour ou supprimer des documents. Le nombre maximal d’index que vous pouvez créer varie selon le niveau tarifaire. Dans chaque index, il existe des limites sur des éléments individuels. Pour plus d’informations, consultez Limites du service pour azure AI Search.

La mise à jour d’un index existant doit inclure la définition complète du schéma, y compris les définitions d’origine que vous souhaitez conserver. En général, le meilleur modèle pour les mises à jour consiste à récupérer la définition d’index avec un GET, à le modifier, puis à le mettre à jour avec PUT.

Étant donné qu’un index existant contient du contenu, de nombreuses modifications d’index nécessitent une suppression d’index et regénérer. Les modifications de schéma suivantes sont une exception à cette règle :

• Ajout de nouveaux champs

• Ajout ou modification de profils de scoring

• Ajout ou modification de configurations sémantiques

• Modification des options CORS

• Modification des champs existants avec l’une des trois modifications suivantes :

  • Afficher ou masquer les champs (retrievable: true | false)
  • Modifier l’analyseur utilisé au moment de la requête (searchAnalyzer)
  • Ajouter ou modifier le synonymMap utilisé au moment de la requête (synonymMaps)

Pour apporter l’une des modifications de schéma ci-dessus à un index existant, spécifiez le nom de l’index sur l’URI de requête, puis incluez une définition d’index entièrement spécifiée avec les éléments nouveaux ou modifiés.

Lorsqu’un nouveau champ est ajouté, tous les documents existants de l’index ont automatiquement une valeur Null pour ce champ. Aucun espace de stockage supplémentaire n’est consommé jusqu’à ce que l’une des deux choses se produise : une valeur est fournie pour le nouveau champ (à l’aide de fusion), ou de nouveaux documents sont ajoutés.

Mises à jour d’un suggester ont des contraintes similaires : de nouveaux champs peuvent être ajoutés à un suggester en même temps que les champs sont ajoutés, mais les champs existants ne peuvent pas être supprimés ni ajoutés à suggesters sans regénération d’index.

Mises à jour d’un analyseur, d’un tokenizer, d’un filtre de jeton ou d’un filtre char ne sont pas autorisées. Les nouvelles peuvent être créées avec les modifications souhaitées, mais vous devez mettre l’index hors connexion lors de l’ajout des nouvelles définitions d’analyseur. La définition de l’indicateur allowIndexDowntime sur true dans la demande de mise à jour d’index met l’index hors connexion :

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Cette opération met votre index hors connexion pendant au moins quelques secondes, ce qui signifie que l’indexation et les requêtes échouent jusqu’à ce que l’index soit de nouveau en ligne et prêt à gérer les requêtes.

Paramètres d’URI

En-têtes de requête

Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs.

Corps de la demande

Le corps de la requête contient une définition de schéma, qui inclut la liste des champs de données dans les documents qui sont alimentés dans cet index.

Le code JSON suivant est une représentation générale d’un schéma qui prend en charge la recherche vectorielle. Un schéma nécessite un champ de clé et ce champ de clé peut être accessible à la recherche, filtrable, triable et facetable.

Un champ de recherche vectorielle est de type Collection(Edm.Single). Étant donné que les champs vectoriels ne sont pas textuels, un champ vectoriel ne peut pas être utilisé comme clé et n’accepte pas les analyseurs, les normaliseurs, les suggesteurs ou les synonymes. Elle doit avoir une propriété « dimensions » et une propriété « vectorSearchConfiguration ».

Un schéma qui prend en charge la recherche vectorielle peut également prendre en charge la recherche par mot clé. D’autres champs non-vecteurs de l’index peuvent utiliser tous les analyseurs, synonymes et profils de scoring que vous incluez dans votre index.

{  
  "name": (optional on PUT; required on POST) "Name of the index",
  "description": (optional) "Description of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Single) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
      "synonymMaps": [ "name_of_synonym_map" ], (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ], (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
      "dimensions": 1234, (required for vector field definitions. Prohibited for non-vector fields. Integer specifying the dimensionality of the embeddings generated by a machine learning model)
      "vectorSearchConfiguration": "name_of_algorithm_config" (required for vector field definitions. Prohibited for non-vector fields. This should reference an algorithm configuration.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "semantic": (optional) { },
  "vectorSearch": (optional) {
    "algorithmConfigurations": [
        {
            "name": "name_of_algorithm_config",
            "kind": "hnsw" (algorithm type. Only "hnsw" is supported currently.),
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]},
  "normalizers":(optional) [ ... ],
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}  

La requête contient les propriétés suivantes :

Réponse

Pour une demande de création réussie, vous devez voir le code d’état « 201 Créé ». Par défaut, le corps de la réponse contient le json de la définition d’index créée. Toutefois, si l’en-tête Prefer request est défini sur return=minimal, le corps de la réponse est vide et le code d’état de réussite est « 204 No Content » au lieu de « 201 Created ». Cela est vrai, que PUT ou POST soit utilisé pour créer l’index.

Pour une demande de mise à jour réussie, vous devez voir « 204 Aucun contenu ». Par défaut, le corps de la réponse est vide. Toutefois, si l’en-tête de requête Prefer est défini sur return=representation, le corps de la réponse contient le json de la définition d’index mise à jour. Dans ce cas, le code d’état de réussite est « 200 OK ».

Exemples

exemple : vectoriel

La recherche vectorielle est implémentée au niveau du champ. Cette définition met le focus sur les champs vectoriels. Les champs vectoriels doivent être de type Collection(Edm.Single) utilisés pour stocker des valeurs à virgule flottante à précision unique. Les champs vectoriels ont une propriété « dimensions » qui contient le nombre de dimensions de sortie prises en charge par le modèle Machine Learning utilisé pour générer des incorporations. Par exemple, si vous utilisez text-embedding-ada-002, le nombre maximal de dimensions de sortie est de 1536 par ce document. Le paramètre « algorithmConfiguration » est défini sur le nom de la configuration « vectorSearch » dans votre index. Vous pouvez définir plusieurs dans l’index, puis en spécifier un par champ.

De nombreux attributs s’appliquent uniquement aux champs non-vecteurs. Les attributs tels que « filtrable », « triable », « facetable », « analyzer », « normalizer » et « synonymMaps » sont ignorés pour les champs vectoriels. De même, si vous définissez des propriétés vectorielles uniquement telles que « dimensions » ou « vectorSearchConfiguration » sur le champ contenant du contenu alphanumérique, ces attributs sont ignorés.

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "searchable": true,
            "retrievable": true,
            "filterable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "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": "my-vector-config"
        }
    ],
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    }
}

Exemple : collections de champs avec des champs vectoriels et non vectoriels

La recherche vectorielle est implémentée au niveau du champ. Pour prendre en charge les scénarios de requête hybride, créez des paires de champs pour les requêtes vectorielles et non vectorielles. Les champs « title », « titleVector », « content », « contentVector » suivent cette convention. Si vous souhaitez également utiliser la recherche sémantique, vous devez avoir des champs de texte non vecteurs pour ces comportements.

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "category",
            "type": "Edm.String",
            "filterable": true,
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "corsOptions": {
        "allowedOrigins": [
            "*"
        ],
        "maxAgeInSeconds": 60
    },
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "title"
                    },
                    "prioritizedContentFields": [
                        {
                            "fieldName": "content"
                        }
                    ],
                    "prioritizedKeywordsFields": [
                        {
                            "fieldName": "category"
                        }
                    ]
                }
            }
        ]
    }
}

Exemple : schéma d’index avec des champs simples et complexes

Le premier exemple montre un schéma d’index complet avec des champs simples et complexes. Au moins un champ de chaîne doit avoir la valeur true .

{
  "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", "normalizer": "tagsNormalizer" },
    { "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", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true, "normalizer": "lowercase" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "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)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" }
        ]
    }
  ],
  "suggesters": [ ],
  "analyzers": [ ],
  "normalizers": [ ],
  "encryptionKey": [ ]
}  

exemple : suggesteurs

Un suggesteur définition doit spécifier des champs de chaîne « pouvant faire l’objet d’une recherche » et « récupérables » (dans les API REST, tous les champs simples sont "retrievable": true par défaut). Une fois qu’un suggesteur est défini, vous pouvez le référencer par nom sur les demandes de requête qui utilisent l’API suggestions ou API de saisie semi-automatique, selon que vous souhaitez retourner une correspondance ou le reste d’un terme de requête.

{
  "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "suggesters": [
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": ["HotelName", "Category", "Tags"]  
    } 
  ]
} 

exemple : analyseurs et normaliseurs

Analyseurs et normaliseurs sont référencés sur les définitions de champ et peuvent être prédéfinis ou personnalisés. Si vous utilisez des analyseurs personnalisés ou des normaliseurs, spécifiez-les dans l’index dans les sections « analyseurs » et « normaliseurs ».

L’exemple suivant illustre les analyseurs personnalisés et les normaliseurs pour « Balises ». Il illustre également un normaliseur prédéfini (standard) et un analyseur (en.microsoft) pour « HotelName » et « Description », respectivement.

{
  "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, "normalizer": standard  },
    { "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ],
  "normalizers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
      "name": "tagsNormalizer",
      "tokenFilters": [ "asciifolding", "lowercase" ]
    }
  ]
}  

exemple : Similarité pour la pertinence de la recherche

Cette propriété définit l’algorithme de classement utilisé pour créer un score de pertinence dans les résultats de recherche d’une requête de recherche en texte intégral. Dans les services créés après 15 juillet 2020, cette propriété est ignorée, car l’algorithme de similarité est toujours BM25. Pour les services existants créés avant 15 juillet 2020, vous pouvez opter pour BM25 en définissant cette construction comme suit :

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

exemple : options CORS

JavaScript côté client ne peut pas appeler d’API par défaut, car le navigateur empêche toutes les demandes d’origine croisée. Pour autoriser les requêtes inter-origines à votre index, activez CORS (partage de ressources inter-origines (Wikipédia)) en définissant l’attribut corsOptions. Pour des raisons de sécurité, seules les API de requête prennent en charge CORS.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

exemple : Clés de chiffrement avec informations d’identification d’accès

Les clés de chiffrement sont des clés gérées par le client utilisées pour un chiffrement supplémentaire. Pour plus d’informations, consultez Encryption à l’aide de clés gérées par le client dans Azure Key Vault.

{
    "name": "hotels",  
    "fields": [ omitted for brevity ],
    "suggesters": [ omitted for brevity ],
    "analyzers": [ omitted for brevity ],
    "encryptionKey": (optional) { 
       "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
       "keyVaultKeyVersion": "Version of the Azure Key Vault key",
       "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
       "accessCredentials": (optional, only if not using managed system identity) {
          "applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
          "applicationSecret": "Authentication key of the specified AAD application)"
        }
    }
} 

exemple : Clés de chiffrement avec d’identité managée

Vous pouvez vous authentifier auprès d’Azure Key Vault à l’aide d’une identité managée affectée par le système ou affectée par l’utilisateur (préversion). Dans ce cas, omettez d’accéder aux informations d’identification ou définissez la valeur Null. L’exemple suivant montre une identité managée affectée par l’utilisateur. Pour utiliser une identité managée affectée par le système, omettez d’accéder aux informations d’identification et à l’identité. Tant que l’identité système de votre service de recherche dispose d’autorisations dans Azure Key Vault, la demande de connexion doit réussir.

{
  "name": "hotels",  
  "fields": [ omitted for brevity ],
  "suggesters": [ omitted for brevity ],
  "analyzers": [ omitted for brevity ],
  "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": null,
          "identity" : { 
              "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
              "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
          }
    }
} 

exemple : profils de scoring

Un profil de scoring est une section du schéma qui définit des comportements de scoring personnalisés qui vous permettent d’influencer les documents qui apparaissent plus haut dans les résultats de recherche. Les profils de scoring sont constitués de poids et de fonctions de champ. Pour les utiliser, vous spécifiez un profil par nom sur la chaîne de requête. Pour plus d’informations, consultez Ajouter des profils de scoring à un index de recherche (API REST Recherche Azure AI) pour plus d’informations.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

exemple : configurations sémantiques

Une configuration sémantique fait partie d’une définition d’index utilisée pour configurer les champs utilisés par la recherche sémantique pour le classement, les légendes, les mises en surbrillance et les réponses. Pour utiliser la recherche sémantique, vous devez spécifier le nom d’une configuration sémantique au moment de la requête. Pour plus d’informations, consultez Créer une requête sémantique.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "my-semantic-config",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "hotelName"
               },
           "prioritizedContentFields": [
             {
               "fieldName": "description"
             },
             {
               "fieldName": "description_fr"
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "tags"
             },
             {
               "fieldName": "category"
             }
           ]
         }
       }
     ]
   }
}

Définitions

corsOptions

JavaScript côté client ne peut pas appeler d’API par défaut, car le navigateur empêche toutes les demandes d’origine croisée. Pour autoriser les requêtes cross-origin à votre index, activez CORS (partage de ressources cross-origin) en définissant l’attribut « corsOptions ». Pour des raisons de sécurité, seules les API de requête prennent en charge CORS.

defaultScoringProfile

Optionnel. Chaîne qui est le nom d’un profil de scoring personnalisé défini dans l’index. Un profil par défaut est appelé chaque fois qu’un profil personnalisé n’est pas spécifié explicitement sur la chaîne de requête. Pour plus d’informations, consultez Ajouter des profils de scoring à un index de recherche.

encryptionKey

Configure une connexion à Azure Key Vault pour des clés de chiffrement gérées par le client (CMK) supplémentaires. Disponible pour les services de recherche facturables créés le 1er janvier 2019.

Une connexion au coffre de clés doit être authentifiée. Vous pouvez utiliser « accessCredentials » ou une identité managée à cet effet.

Les identités managées peuvent être affectées par le système ou par l’utilisateur (préversion). Si le service de recherche a une identité managée affectée par le système et une attribution de rôle qui accorde l’accès en lecture au coffre de clés, vous pouvez omettre à la fois « identité » et « accessCredentials », et la demande s’authentifie à l’aide de l’identité managée. Si le service de recherche a une identité affectée par l’utilisateur et une attribution de rôle, définissez la propriété « identity » sur l’ID de ressource de cette identité.

champs

Contient des informations sur les attributs d’une définition de champ.

normaliseurs

Définit un normaliseur personnalisé qui a une combinaison définie par l’utilisateur de filtres de caractères et de filtres de jetons. Après avoir défini un normaliseur personnalisé dans l’index, vous pouvez le spécifier par son nom sur une définition de champ .

scoringProfiles

Les profils de scoring s’appliquent à la recherche en texte intégral. Un profil est défini dans un index et spécifie une logique personnalisée qui peut attribuer des scores de recherche plus élevés aux documents correspondants qui répondent aux critères définis dans le profil. Vous pouvez créer plusieurs profils de scoring, puis affecter celui que vous souhaitez à une requête.

Si vous créez un profil personnalisé, vous pouvez le faire par défaut en définissant defaultScoringProfile. Pour plus d’informations, consultez Ajouter des profils de scoring à un index de recherche.

sémantique

Une configuration sémantique fait partie d’une définition d’index utilisée pour configurer les champs utilisés par la recherche sémantique pour le classement, les légendes, les mises en surbrillance et les réponses. Les configurations sémantiques sont constituées d’un champ de titre, de champs de contenu hiérarchisés et de champs de mot clé hiérarchisés. Au moins un champ doit être spécifié pour chacun des trois sous-propriétés (titleField, hiérarchiséKeywordsFields et hiérarchiséContentFields). Tout champ de type Edm.String ou Collection(Edm.String) peut être utilisé dans le cadre d’une configuration sémantique.

Pour utiliser la recherche sémantique, vous devez spécifier le nom d’une configuration sémantique au moment de la requête. Pour plus d’informations, consultez Créer une requête sémantique.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "name of the semantic configuration",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "..."
               },
           "prioritizedContentFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ]
         }
       }
     ]
   }
}

similitude

Propriété facultative qui s’applique aux services créés avant le 15 juillet 2020. Pour ces services, vous pouvez définir cette propriété pour utiliser l’algorithme de classement BM25 qui a été introduit en juillet 2020. Les valeurs valides incluent "#Microsoft.Azure.Search.ClassicSimilarity" (la valeur par défaut précédente) ou "#Microsoft.Azure.Search.BM25Similarity".

Pour tous les services créés après juillet 2020, la définition de cette propriété n’a aucun effet. Tous les services plus récents utilisent BM25 comme seul algorithme de classement pour la recherche en texte intégral. Pour plus d’informations, consultez algorithmes de classement dans azure AI Search.

suggesteurs

Spécifie une construction qui stocke les préfixes pour la correspondance sur des requêtes partielles telles que la saisie semi-automatique et les suggestions.

vectorSearch

L’objet vectorSearch permet la configuration des propriétés de recherche vectorielle. Seules les configurations d’algorithme peuvent être configurées actuellement. Cela permet la configuration du type d’algorithme et des paramètres d’algorithme utilisés pour les champs vectoriels. Vous pouvez avoir plusieurs configurations. Toutes les configurations référencées par un champ vectoriel ne peuvent pas être modifiées ni supprimées. Toutes les configurations qui ne sont pas référencées peuvent être modifiées ou supprimées. Une définition de champ vectoriel (dans la collection de champs) doit spécifier la configuration de l’algorithme de recherche vectorielle (via la propriété vectorSearchConfiguration) utilisée par le champ.

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

hnswParameters

Cet objet contient les personnalisations pour hnsw paramètres d’algorithme. Toutes les propriétés sont facultatives et les valeurs par défaut sont utilisées si elles sont omises.

Étant donné que efSearch est un paramètre au moment de la requête, cette valeur peut être mise à jour même si un champ existant utilise une configuration d’algorithme.

Voir aussi

• codes d’état HTTP
• Ajouter des profils de scoring à un index de recherche
• 'API Rechercher des documents
• types de données pris en charge
• analyseurs lexicals
• Créer un index Recherche Azure AI dans le portail
• Créer une de configuration sémantique