Criar ou atualizar índice (API REST de visualização)

Aplica-se a: 2023-07-01-Preview. Esta versão não é mais suportada. Atualize imediatamente para uma versão mais recente.

Um índice especifica o esquema de índice, incluindo a coleção de campos (nomes de campos, tipos de dados e atributos), mas também outras construções (sugestões, perfis de pontuação e configuração de CORS) que definem outros comportamentos de pesquisa.

Você pode usar POST ou PUT em uma solicitação de criação. Para qualquer um deles, o corpo da solicitação fornece a definição do objeto.

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

Para solicitações de atualização, use PUT e especifique o nome do índice no URI.

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

HTTPS é necessário para todas as solicitações de serviço. Se o índice não existir, ele será criado. Se já existir, é atualizado para a nova definição.

Criação de um índice estabelece o esquema e os metadados. Preencher o índice é uma operação separada. Para esta etapa, você pode usar um indexador (consulte Indexer operations, disponível para fontes de dados suportadas) ou Adicionar, atualizar ou excluir documentos. O número máximo de índices que você pode criar varia de acordo com a camada de preço. Dentro de cada índice, há limites para elementos individuais. Para obter mais informações, consulte Limites de serviço para o Azure AI Search.

Atualizar um índice existente deve incluir a definição completa do esquema, incluindo quaisquer definições originais que você deseja preservar. Em geral, o melhor padrão para atualizações é recuperar a definição de índice com um GET, modificá-lo e, em seguida, atualizá-lo com PUT.

Como um índice existente contém conteúdo, muitas modificações de índice exigem uma queda de índice e uma reconstrução. As seguintes alterações de esquema são uma exceção a esta regra:

• Adicionar novos campos

• Adicionar ou alterar perfis de pontuação

• Adicionando ou alterando configurações semânticas

• Alterar as opções do CORS

• Alterar campos existentes com qualquer uma das três modificações a seguir:

  • Mostrar ou ocultar campos (retrievable: true | false)
  • Alterar o analisador usado no momento da consulta (searchAnalyzer)
  • Adicionar ou editar o sinônimoMapa usado no momento da consulta (synonymMaps)

Para fazer qualquer uma das alterações de esquema acima em um índice existente, especifique o nome do índice no URI da solicitação e inclua uma definição de índice totalmente especificada com os elementos novos ou alterados.

Quando um novo campo é adicionado, todos os documentos existentes no índice têm automaticamente um valor nulo para esse campo. Nenhum espaço de armazenamento extra é consumido até que uma de duas coisas ocorra: um valor é fornecido para o novo campo (usando mesclagem) ou novos documentos são adicionados.

As atualizações de um suggester têm restrições semelhantes: novos campos podem ser adicionados a um suggester ao mesmo tempo em que campos são adicionados, mas os campos existentes não podem ser removidos nem adicionados a suggesters sem uma reconstrução de índice.

Atualizações para um analisador, um tokenizador, um filtro de token ou um filtro de caracteres não são permitidas. Novas podem ser criadas com as alterações desejadas, mas você deve colocar o índice offline ao adicionar as novas definições do analisador. Definir o sinalizador allowIndexDowntime como true na solicitação de atualização de índice coloca o índice offline:

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

Essa operação coloca o índice offline por pelo menos alguns segundos, o que significa que as solicitações de indexação e consulta falham até que o índice esteja online novamente e pronto para lidar com solicitações.

Parâmetros de URI

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Órgão do Pedido

O corpo da solicitação contém uma definição de esquema, que inclui a lista de campos de dados em documentos que são alimentados nesse índice.

O JSON a seguir é uma representação de alto nível de um esquema que oferece suporte à pesquisa vetorial. Um esquema requer um campo chave, e esse campo-chave pode ser pesquisável, filtrável, classificável e facial.

Um campo de pesquisa vetorial é do tipo Collection(Edm.Single). Como os campos vetoriais não são textuais, um campo vetorial não pode ser usado como chave e não aceita analisadores, normalizadores, sugestões ou sinônimos. Ele deve ter uma propriedade "dimensions" e uma propriedade "vectorSearchConfiguration".

Um esquema que suporta pesquisa vetorial também pode suportar a pesquisa por palavra-chave. Outros campos não vetoriais no índice podem usar quaisquer analisadores, sinônimos e perfis de pontuação que você incluir no í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) { }  
}  

Request contém as seguintes propriedades:

Resposta

Para uma solicitação de criação bem-sucedida, você verá o código de status "201 Criado". Por padrão, o corpo da resposta contém o JSON para a definição de índice que foi criada. No entanto, se o cabeçalho da solicitação Preferir estiver definido como return=minimal, o corpo da resposta estará vazio e o código de status de êxito será "204 Sem Conteúdo" em vez de "201 Criado". Isso é verdade independentemente de PUT ou POST ser usado para criar o índice.

Para uma solicitação de atualização bem-sucedida, você deve ver "204 Sem conteúdo". Por padrão, o corpo da resposta está vazio. No entanto, se o cabeçalho da solicitação Prefer estiver definido como return=representation, o corpo da resposta conterá o JSON para a definição de índice que foi atualizada. Nesse caso, o código de status de sucesso é "200 OK".

Exemplos

Exemplo: Vetor

A pesquisa vetorial é implementada no nível do campo. Esta definição coloca o foco nos campos vetoriais. Os campos vetoriais devem ser do tipo Collection(Edm.Single) usados para armazenar valores de ponto flutuante de precisão única. Os campos vetoriais têm uma propriedade "dimensions" que contém o número de dimensões de saída suportadas pelo modelo de aprendizado de máquina usado para gerar incorporações. Por exemplo, se você estiver usando text-embedding-ada-002, o número máximo de dimensões de saída será 1536 por este documento. O "algorithmConfiguration" é definido como o nome da configuração "vectorSearch" no seu índice. Você pode definir vários no índice e, em seguida, especificar um por campo.

Muitos atributos se aplicam apenas a campos não vetoriais. Atributos como "filtrável", "classificável", "facetable", "analisador", "normalizador" e "synonymMaps" são ignorados para campos vetoriais. Da mesma forma, se você definir propriedades somente vetoriais, como "dimensions" ou "vectorSearchConfiguration" no campo que contém conteúdo alfanumérico, esses atributos serão ignorados.

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

Exemplo: coleções de campos com campos vetoriais e não vetoriais

A pesquisa vetorial é implementada no nível do campo. Para dar suporte a cenários de consulta híbrida, crie pares de campos para consultas vetoriais e não vetoriais. Os campos "title", "titleVector", "content", "contentVector" seguem esta convenção. Se você também quiser usar a pesquisa semântica, deverá ter campos de texto não vetoriais para esses comportamentos.

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

Exemplo: Um esquema de índice com campos simples e complexos

O primeiro exemplo mostra um esquema de índice completo com campos simples e complexos. Pelo menos um campo de cadeia de caracteres deve ter "key" definido como 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": [ ]
}  

Exemplo: Sugestões

Um sugestão definição deve especificar campos de cadeia de caracteres "pesquisáveis" e "recuperáveis" (nas APIs REST, todos os campos simples são "retrievable": true por padrão). Depois que um sugeridor é definido, você pode fazer referência a ele pelo nome em solicitações de consulta que usam o da API de Sugestões ou API de Preenchimento Automático, dependendo se você deseja retornar uma correspondência ou o restante de um termo 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"]  
    } 
  ]
} 

Exemplo: Analisadores e normalizadores

Analisadores e normalizadores são referenciados em definições de campo e podem ser predefinidos ou personalizados. Se você estiver usando analisadores ou normalizadores personalizados, especifique-os no índice nas seções "analisadores" e "normalizadores".

O exemplo a seguir ilustra analisadores e normalizadores personalizados para "Tags". Ele também demonstra um normalizador predefinido (padrão) e analisador (en.microsoft) para "HotelName" e "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" ]
    }
  ]
}  

Exemplo: Semelhança para relevância de pesquisa

Esta propriedade define o algoritmo de classificação usado para criar uma pontuação de relevância nos resultados de pesquisa de uma consulta de pesquisa de texto completo. Em serviços criados após 15 de julho de 2020, essa propriedade é ignorada porque o algoritmo de semelhança é sempre BM25. Para serviços existentes criados antes 15 de julho de 2020, você pode optar pelo BM25 definindo essa construção da seguinte maneira:

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

Exemplo: Opções CORS

O JavaScript do lado do cliente não pode chamar nenhuma API por padrão, pois o navegador impede todas as solicitações de origem cruzada. Para permitir consultas de origem cruzada ao seu índice, habilite CORS (Cross-origin resource sharing (Wikipedia)) definindo o atributo corsOptions. Por motivos de segurança, apenas as APIs de consulta suportam 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)  
     }
}

Exemplo: chaves de criptografia com credenciais de acesso

As chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia extra. Para obter mais informações, consulte Criptografia usando chaves gerenciadas pelo cliente no 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)"
        }
    }
} 

Exemplo: chaves de criptografia com identidade gerenciada

Você pode autenticar no Cofre da Chave do Azure usando uma identidade gerenciada atribuída pelo sistema ou pelo usuário (visualização). Nesse caso, omita as credenciais de acesso ou defina como null. O exemplo a seguir mostra uma identidade gerenciada atribuída pelo usuário. Para usar uma identidade gerenciada atribuída pelo sistema, omita credenciais de acesso e identidade. Desde que a identidade do sistema do seu serviço de pesquisa tenha permissões no Cofre da Chave do Azure, a solicitação de conexão deverá ser bem-sucedida.

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

Exemplo: Pontuação de perfis

Um perfil de pontuação é uma seção do esquema que define comportamentos de pontuação personalizados que permitem influenciar quais documentos aparecem mais acima nos resultados da pesquisa. Os perfis de pontuação são compostos por pesos de campo e funções. Para usá-los, especifique um perfil por nome na cadeia de caracteres de consulta. Para obter mais informações, consulte Adicionar perfis de pontuação a um índice de pesquisa (Azure AI Search REST API) obter detalhes.

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

Exemplo: Configurações semânticas

Uma configuração semântica é uma parte de uma definição de índice usada para configurar quais campos são utilizados pela pesquisa semântica para classificação, legendas, destaques e respostas. Para usar a pesquisa semântica, você deve especificar o nome de uma configuração semântica no momento da consulta. Para obter mais informações, consulte Criar uma 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"
             }
           ]
         }
       }
     ]
   }
}

Definições

corsOpções

O JavaScript do lado do cliente não pode chamar nenhuma API por padrão, pois o navegador impede todas as solicitações de origem cruzada. Para permitir consultas de origens cruzadas ao seu índice, habilite o CORS (Cross-Origin Resource Sharing) definindo o atributo "corsOptions". Por motivos de segurança, apenas as APIs de consulta suportam CORS.

defaultScoringProfile

Opcional. Uma cadeia de caracteres que é o nome de um perfil de pontuação personalizado definido no índice. Um perfil padrão é invocado sempre que um perfil personalizado não é explicitamente especificado na cadeia de caracteres de consulta. Para obter mais informações, consulte Adicionar perfis de pontuação a um índice de pesquisa.

encryptionKey [en]

Configura uma conexão com o Cofre de Chaves do Azure para chaves de criptografia (CMK) suplementares gerenciadas pelo cliente. Disponível para serviços de pesquisa faturáveis criados a partir de 1 de janeiro de 2019.

Uma conexão com o cofre de chaves deve ser autenticada. Você pode usar "accessCredentials" ou uma identidade gerenciada para essa finalidade.

As identidades gerenciadas podem ser atribuídas pelo sistema ou pelo usuário (visualização). Se o serviço de pesquisa tiver uma identidade gerenciada atribuída pelo sistema e uma atribuição de função que conceda acesso de leitura ao cofre de chaves, você poderá omitir "identity" e "accessCredentials", e a solicitação será autenticada usando a identidade gerenciada. Se o serviço de pesquisa tiver identidade atribuída pelo usuário e atribuição de função, defina a propriedade "identity" como a ID de recurso dessa identidade.

campos

Contém informações sobre atributos em uma definição de campo.

normalizadores

Define um normalizador personalizado que tem uma combinação definida pelo usuário de filtros de caracteres e filtros de token. Depois de definir um normalizador personalizado no índice, você pode especificá-lo pelo nome em uma definição de campo .

pontuaçãoPerfis

Os perfis de pontuação aplicam-se à pesquisa de texto completo. Um perfil é definido em um índice e especifica a lógica personalizada que pode atribuir pontuações de pesquisa mais altas a documentos correspondentes que atendem aos critérios definidos no perfil. Você pode criar vários perfis de pontuação e, em seguida, atribuir o que deseja a uma consulta.

Se você criar um perfil personalizado, poderá torná-lo padrão definindo defaultScoringProfile. Para obter mais informações, consulte Adicionar perfis de pontuação a um índice de pesquisa.

semântica

Uma configuração semântica é uma parte de uma definição de índice usada para configurar quais campos são utilizados pela pesquisa semântica para classificação, legendas, destaques e respostas. As configurações semânticas são compostas por um campo de título, campos de conteúdo priorizado e campos de palavra-chave priorizados. Pelo menos um campo precisa ser especificado para cada uma das três subpropriedades (titleField, priorizdKeywordsFields e priorizdContentFields). Qualquer campo do tipo Edm.String ou Collection(Edm.String) pode ser usado como parte de uma configuração semântica.

Para usar a pesquisa semântica, você deve especificar o nome de uma configuração semântica no momento da consulta. Para obter mais informações, consulte Criar uma 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": "..."
             }
           ]
         }
       }
     ]
   }
}

semelhança

Propriedade opcional que se aplica a serviços criados antes de 15 de julho de 2020. Para esses serviços, você pode definir essa propriedade para usar o algoritmo de classificação BM25 que foi introduzido em julho de 2020. Os valores válidos incluem "#Microsoft.Azure.Search.ClassicSimilarity" (o padrão anterior) ou "#Microsoft.Azure.Search.BM25Similarity".

Para todos os serviços criados após julho de 2020, a definição desta propriedade não tem efeito. Todos os serviços mais recentes usam o BM25 como o único algoritmo de classificação para pesquisa de texto completo. Para obter mais informações, consulte Algoritmos de classificação no Azure AI Search.

sugestões

Especifica uma construção que armazena prefixos para correspondência em consultas parciais, como preenchimento automático e sugestões.

pesquisa vetorial

O objeto vectorSearch permite a configuração de propriedades de pesquisa vetorial. Apenas as configurações de algoritmo podem ser configuradas atualmente. Isso permite a configuração do tipo de algoritmo e parâmetros de algoritmo usados para campos vetoriais. Você pode ter várias configurações. Quaisquer configurações referenciadas por um campo vetorial não podem ser modificadas nem excluídas. Quaisquer configurações que não sejam referenciadas podem ser modificadas ou excluídas. Uma definição de campo vetorial (na coleção fields) deve especificar qual configuração do algoritmo de pesquisa vetorial (através da propriedade vectorSearchConfiguration) que o campo está usando.

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

hnswParâmetros

Este objeto contém as personalizações para hnsw parâmetros de algoritmo. Todas as propriedades são opcionais e os valores padrão são usados se algum for omitido.

Como efSearch é um parâmetro de tempo de consulta, esse valor pode ser atualizado mesmo se um campo existente estiver usando uma configuração de algoritmo.

Ver também

• códigos de status HTTP
• Adicionar perfis de pontuação a um índice de pesquisa
• API de Pesquisa de Documentos
• Tipos de dados suportados
• Analisadores lexicais
• Criar um índice de Pesquisa de IA do Azure no portal
• Criar uma configuração semântica