Créer ou mettre à jour un index (API REST en préversion)
S’applique à : 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview
Important
2023-07-01-Preview ajoute la recherche vectorielle.
- Objet « vectorSearch », une configuration des paramètres de recherche vectorielle. S’applique uniquement aux algorithmes de recherche vectorielle.
- Type de données « Collection(Edm.Single) », requis pour un champ vectoriel. Représente un nombre à virgule flottante simple précision comme type primitif.
- Propriété « dimensions », requise pour un champ vectoriel. Représente la dimensionnalité de vos incorporations vectorielles.
- Propriété « vectorSearchConfiguration », requise pour un champ vectoriel. Sélectionne la configuration de l’algorithme pour ce champ.
2021-04-30-Preview ajoute :
- « semanticConfiguration » permet d’étendre le classement sémantique à des champs spécifiques.
- « identity », sous « encryptionKey », utilisé pour récupérer une clé de chiffrement gérée par le client à partir d’Azure Key Vault à l’aide d’une identité managée affectée par l’utilisateur.
2020-06-30-Preview ajoute :
- « normaliseurs », utilisés pour l’insensibilité à la casse sur les tris et les filtres.
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 demande fournit la définition de l’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 d’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]
Le protocole HTTPS est requis pour toutes les requêtes 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.
La création d’un index établit le schéma et les métadonnées. Le remplissage de l'index est une opération distincte. Pour cette étape, vous pouvez utiliser un indexeur (voir Opérations de l’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 en fonction du niveau de tarification. Dans chaque index, il existe des limites sur des éléments individuels. Pour plus d’informations, consultez Limites de service pour Azure AI Search.
La mise à jour d’un index existant doit inclure la définition de schéma complète, y compris toutes 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, à la modifier, puis à la mettre à jour avec PUT.
Étant donné qu’un index existant contient du contenu, de nombreuses modifications d’index nécessitent une suppression et une reconstruction d’index. Les modifications de schéma suivantes constituent 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)
- Afficher ou masquer les champs (
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 dans l’index ont automatiquement une valeur null pour ce champ. Aucun espace de stockage supplémentaire n’est consommé tant que l’une des deux opérations suivantes n’est pas effectuée : une valeur est fournie pour le nouveau champ (à l’aide de la fusion), ou de nouveaux documents sont ajoutés.
Mises à jour d’un ont des suggester contraintes similaires : de nouveaux champs peuvent être ajoutés à un suggester en même temps que des champs sont ajoutés, mais les champs existants ne peuvent pas être supprimés ni ajoutés à suggesters sans reconstruction d’index.
Mises à jour à un analyseur, un générateur de jetons, un filtre de jeton ou un filtre de caractères ne sont pas autorisés. Vous pouvez en créer de nouveaux 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 demandes.
Paramètres URI
| Paramètre | Description |
|---|---|
| nom du service | Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche. |
| nom de l'index | Obligatoire sur l’URI si vous utilisez PUT. Le nom doit être en minuscules, commencer par une lettre ou un chiffre, ne comporter ni barres obliques ni points et comporter moins de 128 caractères. Les tirets ne peuvent pas être consécutifs. |
| api-version | Obligatoire. La préversion actuelle est 2023-07-23-preview. Pour plus d’informations sur les versions, consultez Versions de l’API . |
| allowIndexDowntime | facultatif. False par défaut. Définissez sur true pour certaines mises à jour, telles que l’ajout ou la modification d’un analyseur, d’un générateur de jetons, d’un filtre de jetons, d’un filtre char ou d’une propriété de similarité. L’index est mis hors connexion pendant la mise à jour, généralement pas plus de quelques secondes. |
En-têtes de requête
Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.
| Champs | Description |
|---|---|
| Content-Type | Obligatoire. Définissez cette valeur sur application/json |
| api-key | Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la demande auprès de votre service de recherche. Les demandes de création doivent inclure un api-key en-tête défini sur votre clé d’administration (par opposition à une clé de requête). Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé . |
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 recherché, 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. Il 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 mot clé recherche. D’autres champs non vecteurs dans 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 peut contenir les propriétés suivantes :
| Propriété | Description |
|---|---|
| name | Obligatoire. Nom de l’index. Un nom d’index doit contenir uniquement des lettres minuscules, des chiffres ou des tirets, ne peut pas commencer ou se terminer par des tirets et est limité à 128 caractères. |
| description | Description facultative. |
| fields | Collection de champs pour cet index, où chaque champ a un nom, un type de données pris en charge conforme au modèle de données d’entité (EDM) et des attributs qui définissent des actions autorisées sur ce champ. La collection fields doit avoir un champ de type Edm.String avec « key » défini sur « true ». Ce champ représente l’identificateur unique, parfois appelé ID de document, pour chaque document stocké avec l’index. La collection fields accepte désormais les champs vectoriels. |
| similarity | facultatif. Pour les services créés avant le 15 juillet 2020, définissez cette propriété pour choisir l’algorithme de classement BM25. |
| suggesteurs | Spécifie une construction qui stocke des préfixes pour la correspondance sur des requêtes partielles telles que la saisie semi-automatique et les suggestions. |
| scoringProfiles | facultatif. Utilisé pour le réglage de la pertinence pour les requêtes de texte intégral. |
| sémantique | facultatif. Définit les paramètres d’un index de recherche qui influencent les fonctionnalités de recherche sémantique. Une configuration sémantique est requise pour les requêtes sémantiques. Pour plus d’informations, consultez Créer une requête sémantique. |
| vectorSearch | facultatif. Configure différents paramètres de recherche vectorielle. Seuls les algorithmes de recherche vectorielle peuvent être configurés. |
| normaliseurs | facultatif. Normalise l’ordre lexicographique des chaînes, en produisant un tri et un filtrage non respectant la casse. |
| analyseurs, charFilters, générateurs de jetons, tokenFilters | facultatif. Spécifiez ces sections de l’index si vous définissez des analyseurs personnalisés. Par défaut, ces sections sont null. |
| defaultScoringProfile | Nom d’un profil de scoring personnalisé qui remplace les comportements de scoring par défaut. |
| corsOptions | facultatif. Utilisé pour les requêtes d’origine croisée sur votre index. |
| encryptionKey | facultatif. Utilisé pour le chiffrement supplémentaire de l’index, via des clés de chiffrement gérées par le client (CMK) dans Azure Key Vault. Disponible pour les services de recherche facturables créés le ou après le 01/01/01/2019. |
response
Pour qu’une demande de création réussisse, vous devez voir status code « 201 Créé ». Par défaut, le corps de la réponse contient le JSON de la définition d’index qui a été créée. Toutefois, si l’en-tête de requête Prefer est défini sur return=minimal, le corps de la réponse est vide et le code de réussite status est « 204 Aucun contenu » au lieu de « 201 Créé ». Cela est vrai, que la méthode utilisée pour créer l'index soit PUT ou POST.
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 Prefer de requête est défini sur return=representation, le corps de la réponse contient le JSON de la définition d’index qui a été mise à jour. Dans ce cas, la réussite status code est « 200 OK ».
Exemples
Exemple : Vector
La recherche vectorielle est implémentée au niveau du champ. Cette définition met l’accent sur les champs vectoriels. Les champs vectoriels doivent être de type Collection(Edm.Single) utilisé 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 pour ce document. « 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 un 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 disposer de 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 « key » définie sur 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
Une définition de suggesteur doit spécifier les champs de chaîne « pouvant faire l’objet d’une recherche » et « récupérable » (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 son nom sur les demandes de requête qui utilisent l’API Suggestions ou l’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
Les analyseurs et lesnormaliseurs sont référencés sur des définitions de champ et peuvent être prédéfinis ou personnalisés. Si vous utilisez des analyseurs ou des normaliseurs personnalisés, spécifiez-les dans l’index des sections « analyseurs » et « normaliseurs ».
L’exemple suivant illustre des analyseurs et des normaliseurs personnalisés pour les « 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 le 15 juillet 2020, cette propriété est ignorée, car l’algorithme de similarité est toujours BM25. Pour les services existants créés avant le 15 juillet 2020, vous pouvez choisir 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 (Cross-origin resource sharing (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 des 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 Chiffrement à 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 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 les informations d’identification d’accès ou définissez sur 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 les informations d’identification d’accès 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 aboutir.
{
"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 calcul de score sont constitués de pondérations et de fonctions de champ. Pour les utiliser, vous spécifiez un profil par nom dans 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 surbrillances 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
| Lien | Description |
|---|---|
| corsOptions | Répertorie les domaines ou origines qui sont accordés à votre index. |
| defaultScoringProfile | Nom d’un profil de scoring personnalisé qui remplace les comportements de scoring par défaut. |
| encryptionKey | Configure une connexion à Azure Key Vault pour le chiffrement géré par le client. |
| fields | Définit les définitions et les attributs d’un champ dans un index de recherche. |
| normaliseurs | Configure un normaliseur personnalisé. Normalise l’ordre lexicographique des chaînes, en produisant un tri, des facettes et un filtrage non respectant la casse. |
| sémantique | Configure les champs utilisés par la recherche sémantique pour le classement, les légendes, les surbrillances et les réponses. |
| scoringProfiles | Utilisé pour le réglage de la pertinence pour les requêtes de texte intégral. |
| Similitude | |
| suggesteurs | Configure le stockage de préfixes interne pour la correspondance sur les requêtes partielles telles que la saisie semi-automatique et les suggestions. |
| vectorSearch | Configure l’algorithme utilisé pour les champs vectoriels. |
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 d’origine croisée à votre index, activez CORS (Cross-Origin Resource Sharing) en définissant l’attribut « corsOptions ». Pour des raisons de sécurité, seules les API de requête prennent en charge CORS.
| Attribut | Description |
|---|---|
| allowedOrigins | Obligatoire. Liste délimitée par des virgules d’origines auxquelles l’accès est accordé à votre index, où chaque origine est généralement de la forme protocol://< nom-domaine> qualifié :<port> (bien que le <port> soit souvent omis). Cela signifie que tout code JavaScript fourni à partir de ces origines est autorisé à interroger votre index (en supposant qu’il fournit une clé API valide). Si vous souhaitez autoriser l’accès à toutes les origines, spécifiez * comme un seul élément dans le tableau « allowedOrigins ». Cela n’est pas recommandé pour la production, mais peut être utile pour le développement ou le débogage. |
| maxAgeInSeconds | facultatif. les navigateurs utilisent cette valeur pour déterminer la durée (en secondes) de mise en cache des réponses CORS préliminaires. Il doit s'agir d'un entier non négatif. Les performances s’améliorent si cette valeur est supérieure, mais ces gains sont compensés par le temps nécessaire pour que les modifications de stratégie CORS prennent effet. S’il n’est pas défini, une durée par défaut de 5 minutes est utilisée. |
defaultScoringProfile
facultatif. 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 explicitement spécifié 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 les clés de chiffrement supplémentaires gérées par le client (CMK). Disponible pour les services de recherche facturables créés à partir du 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 à la fois 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 « identity » et « accessCredentials », et la demande s’authentifiera à l’aide de l’identité managée. Si le service de recherche dispose d’une identité et d’une attribution de rôle attribuées par l’utilisateur, définissez la propriété « identity » sur l’ID de ressource de cette identité.
| Attribut | Description |
|---|---|
| keyVaultKeyName | Obligatoire. Nom de la clé azure Key Vault utilisée pour le chiffrement. |
| keyVaultKeyVersion | Obligatoire. Version de la clé Azure Key Vault. |
| keyVaultUri | Obligatoire. URI d’Azure Key Vault (également appelé nom DNS) qui fournit la clé. Un exemple d’URI peut être https://my-keyvault-name.vault.azure.net |
| accessCredentials | facultatif. Omettez cette propriété si vous utilisez une identité managée. Sinon, les propriétés de « accessCredentials » sont les suivantes : « applicationId » (un ID d’application Azure Active Directory disposant d’autorisations d’accès à votre Key Vault Azure spécifié). « applicationSecret » (clé d’authentification de l’application Azure AD spécifiée). |
| identité | Facultatif, sauf si vous utilisez une identité managée affectée par l’utilisateur pour la connexion du service de recherche à Azure Key Vault. Le format est "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]". |
fields
Contient des informations sur les attributs d’une définition de champ.
| Attribut | Description |
|---|---|
| name | Obligatoire. Définit le nom du champ, qui doit être unique dans la collection fields de l’index ou du champ parent. |
| type | Obligatoire. Spécifie le type de données pour le champ. Les champs peuvent être simples ou complexes. Les champs simples sont de types primitifs, comme Edm.String pour le texte ou Edm.Int32 pour les entiers. Les champs complexes peuvent avoir des sous-champs qui sont eux-mêmes simples ou complexes. Cela vous permet de modéliser des objets et des tableaux d’objets, ce qui vous permet à son tour de charger la plupart des structures d’objets JSON dans votre index. Collection(Edm.Single) prise en charge des valeurs à virgule flottante à précision unique. Il est utilisé uniquement pour les champs vectoriels, et il est obligatoire. Pour obtenir la liste complète des types pris en charge, consultez Types de données pris en charge. |
| key | Obligatoire. Définissez cet attribut sur true pour indiquer que les valeurs d’un champ identifient de manière unique les documents de l’index. La longueur maximale des valeurs dans un champ de clé est de 1 024 caractères. Exactement un champ de niveau supérieur dans chaque index doit être choisi comme champ de clé et il doit être de type Edm.String. La valeur par défaut est false pour les champs simples et null pour les champs complexes. Les champs clés peuvent être utilisés pour rechercher directement des documents et mettre à jour ou supprimer des documents spécifiques. Les valeurs des champs clés sont gérées de manière à respecter la casse lors de la recherche ou de l’indexation de documents. Pour plus d’informations , consultez Rechercher un document et Ajouter, mettre à jour ou supprimer des documents . |
| Récupérable | Indique si le champ peut être retourné dans un résultat de recherche. Définissez cet attribut false sur si vous souhaitez utiliser un champ (par exemple, une marge) comme filtre, tri ou mécanisme de scoring, mais ne souhaitez pas que le champ soit visible pour l’utilisateur final. Cet attribut doit être true destiné aux champs clés et null aux champs complexes. Cet attribut peut être modifié sur les champs existants. La définition de récupérable true sur n’entraîne pas d’augmentation des exigences de stockage d’index. La valeur par défaut est true pour les champs simples et null pour les champs complexes. |
| peut faire l’objet d’une recherche | Indique si le champ peut faire l’objet d’une recherche en texte intégral et peut être référencé dans les requêtes de recherche. Cela signifie qu’il subit une analyse lexicale telle que la coupure de mots lors de l’indexation. Si vous définissez un champ pouvant faire l’objet d’une recherche sur une valeur telle que « Jour ensoleillé », il est normalisé en interne en jetons individuels « sunny » et « day ». Cela permet d'effectuer des recherches en texte intégral de ces termes. Les champs de type Edm.String ou Collection(Edm.String) peuvent faire l’objet d’une recherche par défaut. Cet attribut doit être false destiné aux champs simples d’autres types de données non-chaînes, et il doit être null destiné aux champs complexes. Un champ pouvant faire l’objet d’une recherche consomme de l’espace supplémentaire dans votre index, car Azure AI Search traite le contenu de ces champs et les organise dans des structures de données auxiliaires pour une recherche performante. Si vous souhaitez économiser de l’espace dans votre index et que vous n’avez pas besoin d’inclure un champ dans les recherches, définissez pouvant faire l’objet d’une recherche sur false. Pour plus d’informations, consultez Fonctionnement de la recherche en texte intégral dans Recherche Azure AI . |
| filterable | Indique s’il faut activer le champ à référencer dans $filter les requêtes. Le filtre diffère de l’objet de recherche dans la façon dont les chaînes sont gérées. Les champs de type Edm.String ou Collection(Edm.String) filtrables ne font pas l’objet d’une analyse lexicale. Les comparaisons sont donc destinées uniquement aux correspondances exactes. Par exemple, si vous définissez un tel champ f sur « Jour ensoleillé », $filter=f eq 'sunny' ne trouve aucune correspondance, mais $filter=f eq 'Sunny day' le fera. Cet attribut doit être null pour les champs complexes. La valeur par défaut est true pour les champs simples et null pour les champs complexes. Pour réduire la taille de l’index, définissez cet attribut false sur sur les champs sur lesquels vous ne filtrez pas. |
| sortable | Indique s’il faut activer la référence du champ dans les $orderby expressions. Par défaut, Azure AI Search trie les résultats par score, mais dans de nombreuses expériences, les utilisateurs souhaitent trier par champs dans les documents. Un champ simple peut être triable uniquement s’il a une valeur unique (il a une seule valeur dans l’étendue du document parent). Les champs de collection simples ne peuvent pas être triables, car ils sont à valeurs multiples. Les sous-champs simples de collections complexes sont également à valeurs multiples et ne peuvent donc pas être triables. Cela est vrai, qu’il s’agisse d’un champ parent immédiat ou d’un champ ancêtre, il s’agit de la collection complexe. Les champs complexes ne peuvent pas être triables et l’attribut triable doit être null pour ces champs. La valeur par défaut de triable est true pour les champs simples à valeur unique, false pour les champs simples à valeurs multiples et null pour les champs complexes. |
| facetable | Indique si le champ doit être référencé dans les requêtes à facettes. Généralement utilisé dans une présentation des résultats de recherche qui inclut le nombre d’accès par catégorie (par exemple, rechercher des appareils photo numériques et voir les résultats par marque, par mégapixels, par prix, etc.). Cet attribut doit être null pour les champs complexes. Les champs de type Edm.GeographyPoint ou Collection(Edm.GeographyPoint) ne peuvent pas être facetables. La valeur par défaut est true pour tous les autres champs simples. Pour réduire la taille de l’index, définissez cet attribut false sur sur les champs sur lesquels vous n’aurez pas de facettes. |
| Analyseur | Définit l’analyseur lexical pour la tokenisation des chaînes pendant les opérations d’indexation et de requête. Les valeurs valides pour cette propriété incluent les analyseurs de langage, les analyseurs intégrés et les analyseurs personnalisés. Par défaut, il s’agit de standard.lucene. Cet attribut ne peut être utilisé qu’avec des champs pouvant faire l’objet d’une recherche et ne peut pas être défini avec searchAnalyzer ou indexAnalyzer. Une fois l’analyseur choisi et le champ créé dans l’index, il ne peut pas être modifié pour le champ. Doit être null pour les champs complexes. |
| searchAnalyzer | Définissez cette propriété avec indexAnalyzer pour spécifier différents analyseurs lexicals pour l’indexation et les requêtes. Si vous utilisez cette propriété, définissez analyzer sur null et assurez-vous que indexAnalyzer est défini sur une valeur autorisée. Les valeurs valides pour cette propriété incluent les analyseurs intégrés et lesanalyseurs personnalisés. Cet attribut ne peut être utilisé qu’avec des champs pouvant faire l’objet d’une recherche. L’analyseur de recherche peut être mis à jour sur un champ existant, car il est utilisé uniquement au moment de la requête. Doit être null pour les champs complexes. |
| indexAnalyzer | Définissez cette propriété avec searchAnalyzer pour spécifier différents analyseurs lexicals pour l’indexation et les requêtes. Si vous utilisez cette propriété, définissez analyzer sur null et assurez-vous que searchAnalyzer est défini sur une valeur autorisée. Les valeurs valides pour cette propriété incluent les analyseurs intégrés et lesanalyseurs personnalisés. Cet attribut ne peut être utilisé qu’avec des champs pouvant faire l’objet d’une recherche. Une fois l’analyseur d’index choisi, il ne peut pas être modifié pour le champ. Doit être null pour les champs complexes. |
| Normalizer | Définit le normaliseur pour les opérations de filtrage, de tri et de facettes. Il peut s’agir du nom d’un normaliseur prédéfini ou d’un normaliseur personnalisé défini dans l’index. La valeur par défaut est null, ce qui entraîne une correspondance exacte sur le texte détaillé et non analysé. Cet attribut ne peut être utilisé qu’avec Edm.String les champs et Collection(Edm.String) dont au moins l’un des champs filtrables, triables ou facetables est défini sur true. Un normaliseur peut uniquement être défini sur le champ lorsqu’il est ajouté à l’index et ne peut pas être modifié ultérieurement. Doit être null pour les champs complexes. Les valeurs valides pour un normaliseur prédéfini sont les suivantes : standard- En minuscules le texte suivi d’asciifolding. lowercase- Transforme les caractères en minuscules. uppercase - Transforme les caractères en majuscules. asciifolding - Transforme les caractères qui ne se trouvent pas dans le bloc Unicode latin de base en leur équivalent ASCII, le cas échéant. Par exemple, en remplaçant « à » par « a ». elision- Supprime l’élision du début des jetons. |
| synonymMaps | Liste des noms des mappages de synonymes à associer à ce champ. Cet attribut ne peut être utilisé qu’avec des champs pouvant faire l’objet d’une recherche. Actuellement, une seule carte de synonymes par champ est prise en charge. L’affectation d’un mappage de synonymes à un champ garantit que les termes de requête ciblant ce champ sont développés au moment de la requête à l’aide des règles du mappage de synonymes. Cet attribut peut être modifié sur les champs existants. Doit être null ou une collection vide pour les champs complexes. |
| fields | Liste de sous-champs s’il s’agit d’un champ de type Edm.ComplexType ou Collection(Edm.ComplexType). Doit être null ou vide pour les champs simples. Pour plus d’informations sur la façon et le moment d’utiliser des sous-champs, consultez Comment modéliser des types de données complexes dans Azure AI Search . |
| dimensions | Entier. Obligatoire pour les champs vectoriels. **Cela doit correspondre à la taille d’incorporation de sortie de votre modèle d’incorporation. Par exemple, pour un modèle text-embedding-ada-002Azure OpenAI populaire, ses dimensions de sortie sont 1536. Il s’agit donc des dimensions à définir pour ce champ vectoriel. L’attribut dimensions a un minimum de 2 et un maximum de 2 048 valeurs à virgule flottante chacun. |
| vectorSearchConfiguration | Obligatoire pour les définitions de champ vectoriel. Spécifie le nom de la configuration de l’algorithme « vectorSearch » utilisée par le champ vectoriel. Une fois le champ créé, vous ne pouvez pas modifier le nom de vectorSearchConfiguration, mais vous pouvez modifier les propriétés de la configuration de l’algorithme dans l’index. Cela permet d’ajuster le type et les paramètres de l’algorithme. |
Notes
Les champs de type Edm.String qui peuvent être filtrés, triables ou facetables peuvent avoir une longueur maximale de 32 kilo-octets. Cela est dû au fait que les valeurs de ces champs sont traitées comme un seul terme de recherche et que la longueur maximale d’un terme dans Recherche Azure AI est de 32 kilo-octets. Si vous devez stocker plus de texte que celui-ci dans un champ de chaîne unique, vous devez définir explicitement la valeur filtrable, triable et facetable dans votre définition d’index false .
La définition d’un champ comme pouvant faire l’objet d’une recherche, d’un filtre, d’un tri ou d’une facetable a un impact sur la taille de l’index et les performances des requêtes. Ne définissez pas ces attributs sur des champs qui ne sont pas destinés à être référencés dans les expressions de requête.
Si un champ n’est pas défini comme pouvant faire l’objet d’une recherche, d’un filtre, d’un tri ou d’une facetable, le champ ne peut pas être référencé dans une expression de requête. Cela est utile pour les champs qui ne sont pas utilisés dans les requêtes, mais qui sont nécessaires dans les résultats de la recherche.
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 nom sur une définition de champ.
| Attribut | Description |
|---|---|
| name | Obligatoire. Champ de chaîne qui spécifie un normaliseur personnalisé défini par l’utilisateur. |
| charFilters | Utilisé dans un normaliseur personnalisé. Il peut s’agir d’un ou plusieurs filtres de caractères disponibles pris en charge pour une utilisation dans un normaliseur personnalisé : mappage pattern_replace |
| tokenFilters | Utilisé dans un normaliseur personnalisé. Il peut s’agir d’un ou plusieurs des inclinateurs de jetons disponibles pris en charge dans un normaliseur personnalisé : arabic_normalization asciifolding cjk_width l’élision german_normalization hindi_normalization indic_normalization persian_normalization scandinavian_normalization scandinavian_folding sorani_normalization minuscules majuscules |
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 en faire la valeur 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 surbrillances 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 mot clé hiérarchisés. Au moins un champ doit être spécifié pour chacune des trois sous-propriétés (titleField, priordKeywordsFields et priordContentFields). 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": "..."
}
]
}
}
]
}
}
| Attribut | Description |
|---|---|
| name | Obligatoire. Nom de la configuration sémantique. |
| priordFields | Obligatoire. Décrit les champs titre, contenu et mot clé à utiliser pour le classement sémantique, les légendes, les surligneurs et les réponses. Au moins l’une des trois sous-propriétés (titleField, priordKeywordsFields et priordContentFields) doit être définie. |
| prioritizedFields.titleField | Définit le champ de titre à utiliser pour le classement sémantique, les légendes, les surbrillances et les réponses. Si vous n’avez pas de champ de titre dans votre index, laissez ce champ vide. |
| prioritizedFields.prioritizedContentFields | Définit les champs de contenu à utiliser pour le classement sémantique, les légendes, les surbrillances et les réponses. Pour obtenir un résultat optimal, les champs sélectionnés doivent contenir du texte en langage naturel. L’ordre des champs dans le tableau représente leur priorité. Les champs de priorité inférieure peuvent être tronqués si le contenu est long. |
| prioritizedFields.prioritizedKeywordsFields | Définit les champs mot clé à utiliser pour le classement sémantique, les légendes, les surbrillances et les réponses. Pour obtenir un résultat optimal, les champs sélectionnés doivent contenir une liste de mots clés. L’ordre des champs dans le tableau représente leur priorité. Les champs de priorité inférieure peuvent être tronqués si le contenu est long. |
similarity
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 introduit en juillet 2020. Les valeurs valides sont "#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 des préfixes pour la correspondance sur des requêtes partielles telles que la saisie semi-automatique et les suggestions.
| Attribut | Description |
|---|---|
| name | Obligatoire. Nom du suggesteur. |
| sourceFields | Obligatoire. Un ou plusieurs champs de chaîne pour lesquels vous activez la saisie semi-automatique ou les résultats suggérés. |
| searchMode | Obligatoire, et toujours défini sur analyzingInfixMatching. Il spécifie que la correspondance se produit sur n’importe quel terme dans la chaîne de requête. |
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. 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 fields) doit spécifier la configuration de l’algorithme de recherche vectorielle (via la vectorSearchConfiguration propriété) utilisée par le champ.
"vectorSearch": {
"algorithmConfigurations": [
{
"name": "my-vector-config",
"kind": "hnsw",
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
]
}
| Attribut | Description |
|---|---|
| name | Obligatoire. Nom de la configuration de l’algorithme. |
| kind | Type d’algorithme à utiliser. Seul « hnsw » est pris en charge, c’est-à-dire l’algorithme HNSW (Hierarchical Navigable Small World). |
| hnswParameters | facultatif. Paramètres de l’algorithme « hnsw ». Si cet objet est omis, les valeurs par défaut sont utilisées. |
hnswParameters
Cet objet contient les personnalisations des paramètres d’algorithme hnsw . Toutes les propriétés sont facultatives et les valeurs par défaut sont utilisées le cas échéant.
| Attribut | Description |
|---|---|
| Métrique | Chaîne. Métrique de similarité à utiliser pour les comparaisons de vecteurs. Pour hnsw, les valeurs autorisées sont « cosinus », « euclidien » et « dotProduct ». La valeur par défaut est « cosinus ». |
| m | Entier. Nombre de liens bidirectionnels créés pour chaque nouvel élément pendant la construction. Valeur par défaut : 4. La plage autorisée est de 4 à 10. Les valeurs plus grandes conduisent à des graphiques plus denses, améliorant les performances des requêtes, mais nécessitent plus de mémoire et de calcul. |
| efConstruction | Entier. Taille de la liste dynamique pour les voisins les plus proches utilisés lors de l’indexation. La valeur par défaut est 400. La plage autorisée est de 100 à 1 000.Les valeurs plus grandes conduisent à une meilleure qualité d’index, mais nécessitent plus de mémoire et de calcul. |
| efSearch | Entier. Taille de la liste dynamique contenant les voisins les plus proches, qui est utilisée pendant le temps de recherche. La valeur par défaut est 500. La plage autorisée est comprise entre 100 et 1 000. L’augmentation de ce paramètre peut améliorer les résultats de recherche, mais elle ralentit les performances des requêtes. |
Étant donné qu’il efSearch s’agit d’un paramètre de temps de requête, cette valeur peut être mise à jour même si un champ existant utilise une configuration d’algorithme.