Creación o actualización del índice (API REST de versión preliminar)

se aplica a: 2023-07-01-Preview. Esta versión ya no se admite. Actualizar inmediatamente a una versión más reciente.

Un índice especifica el esquema de índice, incluida la colección de campos (nombres de campo, tipos de datos y atributos), pero también otras construcciones (proveedores de sugerencias, perfiles de puntuación y configuración de CORS) que definen otros comportamientos de búsqueda.

Puede usar POST o PUT en una solicitud de creación. Para cualquiera de ellas, el cuerpo de la solicitud proporciona la definición del objeto.

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

Para las solicitudes de actualización, use PUT y especifique el nombre del índice en el URI.

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

HTTPS es necesario para todas las solicitudes de servicio. Si el índice no existe, se crea. Si ya existe, se actualiza a la nueva definición.

Crear un índice establece el esquema y los metadatos. Rellenar el índice es una operación independiente. Para este paso, puede usar un indexador (consulte operaciones de indexador, disponible para orígenes de datos compatibles) o Agregar, actualizar o eliminar documentos. El número máximo de índices que puede crear varía según el plan de tarifa. Dentro de cada índice, hay límites en elementos individuales. Para más información, consulte límites del servicio para Azure AI Search.

Actualizar un índice existente debe incluir la definición de esquema completa, incluidas las definiciones originales que desee conservar. En general, el mejor patrón para las actualizaciones es recuperar la definición de índice con get, modificarla y, a continuación, actualizarla con PUT.

Dado que un índice existente contiene contenido, muchas modificaciones de índice requieren una eliminación de índice y recompilar. Los siguientes cambios de esquema son una excepción a esta regla:

• Agregar nuevos campos

• Agregar o cambiar perfiles de puntuación de

• Agregar o cambiar configuraciones semánticas de

• Cambio de las opciones de CORS

• Cambiar los campos existentes con cualquiera de las tres modificaciones siguientes:

  • Mostrar u ocultar campos (retrievable: true | false)
  • Cambiar el analizador usado en el momento de la consulta (searchAnalyzer)
  • Agregue o edite el objeto synonymMap usado en el momento de la consulta (synonymMaps)

Para realizar cualquiera de los cambios de esquema anteriores en un índice existente, especifique el nombre del índice en el URI de solicitud y, a continuación, incluya una definición de índice totalmente especificada con los elementos nuevos o modificados.

Cuando se agrega un nuevo campo, todos los documentos existentes del índice tienen automáticamente un valor NULL para ese campo. No se consume ningún espacio de almacenamiento adicional hasta que se produce una de estas dos cosas: se proporciona un valor para el nuevo campo (mediante la combinación) o se agregan nuevos documentos.

Actualizaciones de un suggester tienen restricciones similares: se pueden agregar nuevos campos a un suggester al mismo tiempo, pero los campos existentes no se pueden quitar ni agregar a suggesters sin volver a generar un índice.

no se permiten actualizaciones de un analizador, un tokenizador, un filtro de tokens o un filtro char. Se pueden crear nuevos con los cambios que desee, pero debe desconectar el índice al agregar las nuevas definiciones del analizador. Al establecer la marca allowIndexDowntime en true en la solicitud de actualización de índice, el índice se desconecta:

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

Esta operación desconecta el índice durante al menos unos segundos, lo que significa que la indexación y las solicitudes de consulta producen un error hasta que el índice vuelve a estar en línea y listo para controlar las solicitudes.

Parámetros de URI

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene una definición de esquema, que incluye la lista de campos de datos dentro de los documentos que se introducen en este índice.

El siguiente JSON es una representación de alto nivel de un esquema que admite la búsqueda vectorial. Un esquema requiere un campo de clave y ese campo de clave puede ser de búsqueda, filtrable, ordenable y facetable.

Un campo de búsqueda vectorial es de tipo Collection(Edm.Single). Dado que los campos vectoriales no son textuales, no se puede usar un campo vectorial como clave y no acepta analizadores, normalizadores, proveedores de sugerencias ni sinónimos. Debe tener una propiedad "dimensions" y una propiedad "vectorSearchConfiguration".

Un esquema que admita la búsqueda vectorial también puede admitir la búsqueda de palabras clave. Otros campos no vectores del índice pueden usar los analizadores, sinónimos y perfiles de puntuación que incluya en el índice.

{  
  "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 solicitud contiene las siguientes propiedades:

Respuesta

Para obtener una solicitud de creación correcta, debería ver el código de estado "201 Created". De forma predeterminada, el cuerpo de la respuesta contiene el JSON para la definición de índice que se creó. Sin embargo, si el encabezado preferir solicitud está establecido en return=minimal, el cuerpo de la respuesta está vacío y el código de estado correcto es "204 Sin contenido" en lugar de "201 Creado". Esto es cierto independientemente de si se usa PUT o POST para crear el índice.

Para obtener una solicitud de actualización correcta, debería ver "204 Sin contenido". De forma predeterminada, el cuerpo de la respuesta está vacío. Sin embargo, si el encabezado de solicitud de Prefer está establecido en return=representation, el cuerpo de la respuesta contiene el JSON para la definición de índice que se actualizó. En este caso, el código de estado correcto es "200 OK".

Ejemplos

Ejemplo de : vectorial

La búsqueda vectorial se implementa en el nivel de campo. Esta definición coloca el foco en los campos vectoriales. Los campos vectoriales deben ser de tipo Collection(Edm.Single) se usan para almacenar valores de punto flotante de precisión única. Los campos vectoriales tienen una propiedad "dimensiones" que contiene el número de dimensiones de salida admitidas por el modelo de aprendizaje automático que se usa para generar incrustaciones. Por ejemplo, si usa text-embeding-ada-002, el número máximo de dimensiones de salida es 1536 por este documento. "algorithmConfiguration" se establece en el nombre de la configuración "vectorSearch" en el índice. Puede definir varios en el índice y, a continuación, especificar uno por campo.

Muchos atributos solo se aplican a campos no vectores. Los atributos como "filterable", "sortable", "facetable", "analyzer", "normalizer" y "synonymMaps" se omiten para los campos vectoriales. Del mismo modo, si establece propiedades de solo vector como "dimensiones" o "vectorSearchConfiguration" en el campo que contiene contenido alfanumérico, se omiten esos atributos.

{
    "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"
                }
            }
        ]
    }
}

ejemplo: colecciones de campos con campos vectoriales y no vectoriales

La búsqueda vectorial se implementa en el nivel de campo. Para admitir escenarios de consulta híbrida, cree pares de campos para consultas vectoriales y no vectores. Los campos "title", "titleVector", "content", "contentVector" siguen esta convención. Si también desea usar la búsqueda semántica, debe tener campos de texto novector para esos comportamientos.

{
    "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"
                        }
                    ]
                }
            }
        ]
    }
}

ejemplo: un esquema de índice con campos simples y complejos

En el primer ejemplo se muestra un esquema de índice completo con campos simples y complejos. Al menos un campo de cadena debe tener "key" establecido en 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": [ ]
}  

Ejemplo de : sugerencias

Un definición del proveedor de sugerencias debe especificar campos de cadena "buscables" y "recuperables" (en las API REST, todos los campos simples se "retrievable": true de forma predeterminada). Después de definir un proveedor de sugerencias, puede hacer referencia a él por su nombre en las solicitudes de consulta que usan la API de sugerencias de o API de Autocompletar, dependiendo de si desea devolver una coincidencia o el resto de un término de consulta.

{
  "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"]  
    } 
  ]
} 

ejemplo de : analizadores y normalizadores

Analizadores y normalizadores se hace referencia a ellos en las definiciones de campo y pueden ser predefinidos o personalizados. Si usa analizadores o normalizadores personalizados, especifíquelos en el índice en las secciones "analizadores" y "normalizadores".

En el ejemplo siguiente se muestran analizadores y normalizadores personalizados para "Etiquetas". También muestra un normalizador predefinido (estándar) y un analizador (en.microsoft) para "HotelName" y "Description", respectivamente.

{
  "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" ]
    }
  ]
}  

ejemplo de : similitud de la relevancia de búsqueda

Esta propiedad establece el algoritmo de clasificación usado para crear una puntuación de relevancia en los resultados de búsqueda de una consulta de búsqueda de texto completo. En los servicios creados después de 15 de julio de 2020, esta propiedad se omite porque el algoritmo de similitud siempre es BM25. Para los servicios existentes creados antes de 15 de julio de 2020, puede participar en BM25 estableciendo esta construcción de la siguiente manera:

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

ejemplo de : opciones de CORS

JavaScript del lado cliente no puede llamar a ninguna API de forma predeterminada, ya que el explorador impide todas las solicitudes entre orígenes. Para permitir consultas entre orígenes en el índice, habilite CORS (uso compartido de recursos entre orígenes (Wikipedia)) estableciendo el atributo corsOptions. Por motivos de seguridad, solo las API de consulta admiten 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)  
     }
}

ejemplo de : claves de cifrado con credenciales de acceso

Las claves de cifrado son claves administradas por el cliente que se usan para el cifrado adicional. Para más información, consulte Cifrado mediante claves administradas por el cliente en 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)"
        }
    }
} 

ejemplo de : claves de cifrado con de identidad administrada

Puede autenticarse en Azure Key Vault mediante una identidad administrada asignada por el sistema o asignada por el usuario (versión preliminar). En este caso, omita las credenciales de acceso o establezca en NULL. En el ejemplo siguiente se muestra una identidad administrada asignada por el usuario. Para usar una identidad administrada asignada por el sistema, omita las credenciales de acceso y la identidad. Siempre que la identidad del sistema del servicio de búsqueda tenga permisos en Azure Key Vault, la solicitud de conexión debe realizarse correctamente.

{
  "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]"
          }
    }
} 

Ejemplo de : perfiles de puntuación

Un perfil de puntuación es una sección del esquema que define comportamientos de puntuación personalizados que permiten influir en qué documentos aparecen más altos en los resultados de búsqueda. Los perfiles de puntuación se componen de pesos y funciones de campo. Para usarlos, especifique un perfil por nombre en la cadena de consulta. Para más información, consulte Adición de perfiles de puntuación a un índice de búsqueda (API REST de Azure AI Search) para más información.

{
   "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"  
       }  
 ]
}

Ejemplo de : configuraciones semánticas

Una configuración semántica forma parte de una definición de índice que se usa para configurar qué campos se usan en la búsqueda semántica de clasificación, títulos, resaltados y respuestas. Para usar la búsqueda semántica, debe especificar el nombre de una configuración semántica en el momento de la consulta. Para obtener más información, vea Crear una consulta semántica.

{
   "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"
             }
           ]
         }
       }
     ]
   }
}

Definiciones

corsOptions

JavaScript del lado cliente no puede llamar a ninguna API de forma predeterminada, ya que el explorador impide todas las solicitudes entre orígenes. Para permitir consultas entre orígenes en el índice, habilite CORS (uso compartido de recursos entre orígenes) estableciendo el atributo "corsOptions". Por motivos de seguridad, solo las API de consulta admiten CORS.

defaultScoringProfile

Opcional. Cadena que es el nombre de un perfil de puntuación personalizado definido en el índice. Se invoca un perfil predeterminado cada vez que no se especifica explícitamente un perfil personalizado en la cadena de consulta. Para obtener más información, vea Agregar perfiles de puntuación a un índice de búsqueda.

encryptionKey

Configura una conexión a Azure Key Vault para claves de cifrado administradas por el cliente (CMK) complementarias. Disponible para los servicios de búsqueda facturables creados el 1 de enero de 2019 o después.

Se debe autenticar una conexión al almacén de claves. Puede usar "accessCredentials" o una identidad administrada para este propósito.

Las identidades administradas pueden ser asignadas por el sistema o por el usuario (versión preliminar). Si el servicio de búsqueda tiene una identidad administrada asignada por el sistema y una asignación de roles que concede acceso de lectura al almacén de claves, puede omitir "identity" y "accessCredentials" y la solicitud se autenticará mediante la identidad administrada. Si el servicio de búsqueda tiene la identidad asignada por el usuario y la asignación de roles, establezca la propiedad "identity" en el identificador de recurso de esa identidad.

Campos

Contiene información sobre los atributos de una definición de campo.

normalizadores

Define un normalizador personalizado que tiene una combinación definida por el usuario de filtros de caracteres y filtros de token. Después de definir un normalizador personalizado en el índice, puede especificarlo por nombre en una definición de campo de .

scoringProfiles

Los perfiles de puntuación se aplican a la búsqueda de texto completo. Un perfil se define en un índice y especifica la lógica personalizada que puede conceder mayores puntuaciones de búsqueda a los documentos coincidentes que cumplen los criterios definidos en el perfil. Puede crear varios perfiles de puntuación y, a continuación, asignar el que desea realizar una consulta.

Si crea un perfil personalizado, puede convertirlo en el valor predeterminado estableciendo defaultScoringProfile. Para obtener más información, vea Agregar perfiles de puntuación a un índice de búsqueda.

semántica

Una configuración semántica forma parte de una definición de índice que se usa para configurar qué campos se usan en la búsqueda semántica de clasificación, títulos, resaltados y respuestas. Las configuraciones semánticas se componen de un campo de título, campos de contenido con prioridad y campos de palabra clave con prioridad. Debe especificarse al menos un campo para cada una de las tres subpropiedades (titleField, priorizadoKeywordsFields y priorizadoContentFields). Cualquier campo de tipo Edm.String o Collection(Edm.String) se puede usar como parte de una configuración semántica.

Para usar la búsqueda semántica, debe especificar el nombre de una configuración semántica en el momento de la consulta. Para obtener más información, vea Crear una consulta semántica.

{
   "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": "..."
             }
           ]
         }
       }
     ]
   }
}

similitud

Propiedad opcional que se aplica a los servicios creados antes del 15 de julio de 2020. Para esos servicios, puede establecer esta propiedad para usar el algoritmo de clasificación BM25 que se introdujo en julio de 2020. Los valores válidos incluyen "#Microsoft.Azure.Search.ClassicSimilarity" (valor predeterminado anterior) o "#Microsoft.Azure.Search.BM25Similarity".

Para todos los servicios creados después de julio de 2020, establecer esta propiedad no tiene ningún efecto. Todos los servicios más recientes usan BM25 como único algoritmo de clasificación para la búsqueda de texto completo. Para más información, consulte Algoritmos de clasificación en Azure AI Search.

proveedores de sugerencias

Especifica una construcción que almacena prefijos para buscar coincidencias en consultas parciales, como autocompletar y sugerencias.

vectorSearch

El objeto vectorSearch permite la configuración de las propiedades de búsqueda vectorial. Actualmente solo se pueden configurar configuraciones de algoritmo. Esto permite la configuración del tipo de algoritmo y los parámetros de algoritmo usados para los campos vectoriales. Puede tener varias configuraciones. Las configuraciones a las que hace referencia un campo vectorial no se pueden modificar ni eliminar. Las configuraciones a las que no se hace referencia se pueden modificar o eliminar. Una definición de campo vectorial (en la colección fields) debe especificar qué configuración del algoritmo de búsqueda vectorial (a través de la propiedad vectorSearchConfiguration) que usa el campo.

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

hnswParameters

Este objeto contiene las personalizaciones para hnsw parámetros de algoritmo. Todas las propiedades son opcionales y se usan valores predeterminados si se omite alguno.

Dado que efSearch es un parámetro en tiempo de consulta, este valor se puede actualizar incluso si un campo existente usa una configuración de algoritmo.

Consulte también

• códigos de estado HTTP
• Agregar perfiles de puntuación a un índice de búsqueda
• Search Documents API
• tipos de datos admitidos
• analizadores léxicos
• Creación de un índice de Azure AI Search en el portal
• Crear una configuración semántica