Atualizar para a API REST mais recente na IA do Azure Search

Use este artigo para migrar chamadas de plano de dados para versões de estáveis mais recentes da API REST de Pesquisa.

Observação

Os documentos de referência da API agora estão em versão. Para obter o conteúdo certo, abra uma página de referência e aplique o filtro específico à versão localizado acima do sumário.

Como atualizar

O Pesquisa de IA do Azure busca compatibilidade com versões anteriores. Para atualizar e continuar com a funcionalidade existente, você geralmente pode apenas alterar o número de versão da API. Por outro lado, as situações que exigem códigos de alteração incluem:

  • O código falha quando propriedades não reconhecidas são retornadas em uma resposta da API. Como prática recomendada, seu aplicativo deve ignorar as propriedades que ele não entende.

  • O código persiste solicitações de API e tenta reenviá-las à nova versão da API. Por exemplo, isso poderá acontecer se o aplicativo persistir tokens de continuação retornados da API de Pesquisa (para obter mais informações, procure @search.nextPageParameters na Referência de API de Pesquisa).

  • Seu código faz referência a uma versão da API que antecede a 2019-05-06 e está sujeito a uma ou mais das alterações interruptivas nessa versão. A seção Atualizar para a 2019-05-06 fornece mais detalhes.

Se qualquer uma dessas situações se aplicar a você, altere seu código para manter a funcionalidade existente. Caso contrário, nenhuma alteração será necessária, mas recomendamos começar a usar os novos recursos da versão mais recente.

Atualizar para a 2023-11-01

Esta versão tem alterações significativas e diferenças comportamentais para suporte semântico de classificação e busca em vetores.

  • Classificação semântica não usa mais queryLanguage. Ele também requer uma definição de semanticConfiguration. Se você estiver migrando de 2020-06-30-preview, uma configuração semântica substituirá searchFields. Consulte Migrar da versão prévia para obter as etapas.

  • Suporte de busca em vetores foi introduzido no Criar ou Atualizar índice (2023-07-01-preview). Se você estiver migrando dessa versão, haverá novas opções e várias alterações significativas. As novas opções incluem o modo de filtro de vetor, perfis de vetor e um algoritmo de vizinhos K-mais próximos exaustivo e um sinalizador k-NN exaustivo de tempo de consulta. Alterações significativas incluem renomeação e reestruturação da configuração de vetor no índice e sintaxe de consulta vetor.

Se você adicionou suporte a vetor usando 2023-10-01-preview, não haverá alterações significativas, mas há uma diferença de comportamento: o padrão de vectorFilterMode alterado de pós-filtro para pré-filtro para expressões de filtro. O padrão é o pré-filtro para índices criados após 2023-10-01. Os índices criados antes dessa data só dão suporte ao pós-filtro, independentemente de como você define o modo de filtro.

Dica

O portal do Azure dá suporte a um caminho de atualização de um clique para índices 2023-07-01-preview. O portal detecta índices 2023-07-01-preview e fornece um botão Migrar. Antes de selecionar Migrar, selecione Editar JSON para examinar o esquema atualizado primeiro. Você deve encontrar um esquema que esteja em conformidade com as alterações descritas nesta seção. A migração do portal manipula apenas índices com uma configuração de algoritmo de busca em vetores, criando um perfil padrão que mapeia para o algoritmo. Índices com várias configurações exigem migração manual.

Estas são as etapas para migrar de 2023-07-01-preview:

  1. Chame Obter Índice para recuperar a definição existente.

  2. Modifique a configuração de busca em vetores. Essa API apresenta o conceito de "perfis de vetor" que agrupa configurações relacionadas a vetores em um único nome. Ele também renomeia algorithmConfigurations para algorithms.

    • Renomeie algorithmConfigurations para algorithms. Isso é apenas uma renomeação da matriz. O conteúdo é compatível com versões anteriores. Isso significa que os parâmetros de configuração HNSW existentes podem ser usados.

    • Adicione profiles, dando um nome e uma configuração de algoritmo para cada um deles.

    Antes da migração (2023-07-01-preview):

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

    Após a migração (2023-11-01):

      "vectorSearch": {
        "profiles": [
          {
            "name": "myHnswProfile",
            "algorithm": "myHnswConfig"
          }
        ],
        "algorithms": [
          {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
              "m": 4,
              "efConstruction": 400,
              "efSearch": 500,
              "metric": "cosine"
            }
          }
        ]
      }
    
  3. Modificar definições de campo de vetor, substituindo vectorSearchConfiguration por vectorSearchProfile. Verifique se o nome do perfil é resolvido para uma nova definição de perfil de vetor e não para o nome de configuração do algoritmo. Outras propriedades de campo de vetor permanecem inalteradas. Por exemplo, eles não podem ser filtrados, classificáveis ou facetáveis, nem usar analisadores ou normalizadores ou mapas de sinônimos.

    Antes (2023-07-01-preview):

      {
          "name": "contentVector",
          "type": "Collection(Edm.Single)",
          "key": false,
          "searchable": true,
          "retrievable": true,
          "filterable": false,  
          "sortable": false,  
          "facetable": false,
          "analyzer": "",
          "searchAnalyzer": "",
          "indexAnalyzer": "",
          "normalizer": "",
          "synonymMaps": "", 
          "dimensions": 1536,
          "vectorSearchConfiguration": "myHnswConfig"
      }
    

    Após (2023-11-01):

      {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": true,
        "filterable": false,  
        "sortable": false,  
        "facetable": false,
        "analyzer": "",
        "searchAnalyzer": "",
        "indexAnalyzer": "",
        "normalizer": "",
        "synonymMaps": "", 
        "dimensions": 1536,
        "vectorSearchProfile": "myHnswProfile"
      }
    
  4. Chame Criar ou Atualizar Índice para postar as alterações.

  5. Modifique Pesquisar POST para alterar a sintaxe da consulta. Essa alteração de API permite suporte para tipos de consulta de vetor polimórfico.

    • Renomeie vectors para vectorQueries.
    • Para cada consulta de vetor, adicione kind, definindo-a como "vetor".
    • Para cada consulta de vetor, renomeie value como vector.
    • Opcionalmente, adicione vectorFilterMode se estiver usando expressões de filtro . O padrão é o pré-filtro para índices criados após 2023-10-01. Os índices criados antes dessa data só dão suporte ao pós-filtro, independentemente de como você define o modo de filtro.

    Antes (2023-07-01-preview):

    {
        "search": (this parameter is ignored in vector search),
        "vectors": [
          {
            "value": [
                0.103,
                0.0712,
                0.0852,
                0.1547,
                0.1183
            ],
            "fields": "contentVector",
            "k": 5
          }
        ],
        "select": "title, content, category"
    }
    

    Após (2023-11-01):

    {
      "search": "(this parameter is ignored in vector search)",
      "vectorQueries": [
        {
          "kind": "vector",
          "vector": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
          ],
          "fields": "contentVector",
          "k": 5
        }
      ],
      "vectorFilterMode": "preFilter",
      "select": "title, content, category"
    }
    

Essas etapas concluem a migração para a versão da API 2023-11-01.

Atualizar para a 2020-06-30

Nesta versão, há uma alteração significativa e várias diferenças comportamentais. Os recursos disponíveis em geral incluem:

  • Armazenamento de conhecimento, um armazenamento persistente de conteúdo enriquecido que é criado por meio de conjuntos de habilidades para análises de downstream e processamento por meio de outros aplicativos. Existe um repositório de conhecimento no Armazenamento do Microsoft Azure, que você provisiona e fornece detalhes de conexão a um conjunto de habilidades. Com essa funcionalidade, um pipeline de enriquecimento de IA orientado por indexador pode preencher um armazenamento de conhecimento, além de um índice de pesquisa. A versão desse recurso com disponibilidade geral é equivalente à versão prévia. A única alteração de código necessária é modificar a versão da API.

Alterações da falha

Os códigos existentes escritos em versões anteriores da API serão pausados em api-version=2020-06-30 e mais recente se contiverem a seguinte funcionalidade:

  • Quaisquer literais Edm.Date (uma data composta por ano-mês-dia, como 2020-12-12) em expressões de filtro devem seguir o formato Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Essa alteração foi necessária para lidar com resultados de consulta incorretos ou inesperados devido a diferenças de fuso horário.

Alterações de comportamento

  • O algoritmo de classificação BM25 substitui o anterior por uma tecnologia mais nova. Os serviços criados após 2019 usam esse algoritmo automaticamente. Para serviços mais antigos, você deve definir parâmetros para usar o novo algoritmo.

  • A ordem dos resultados de valores nulos foi alterada nesta versão, com esses valores aparecendo primeiro quando a classificação é asc e por último quando ela é desc. Se você tiver escrito algum código para lidar com a classificação de valores nulos, lembre-se dessa alteração.

Atualizar para a 2019-05-06

A versão 2019-05-06 é a nova versão da API REST com disponibilidade geral. Os recursos que agora têm disponibilidade geral nesta versão da API incluem:

  • O preenchimento automático é um recurso de digitação antecipada que completa uma entrada de termo parcialmente especificada.
  • Os tipos complexos fornecem suporte nativo para dados de objeto estruturado no índice de pesquisa.
  • Os modos de análise de JsonLines, parte da Indexação de blobs do Azure, criam um documento de pesquisa por entidade JSON que é separado por uma nova linha.
  • O enriquecimento de IA fornece uma indexação que usa os mecanismos de enriquecimento de IA dos serviços de IA do Azure.

Alterações de quebra

Os códigos existentes escritos em versões anteriores da API serão pausados em api-version=2019-05-06 e mais recente se contiverem a seguinte funcionalidade:

A fonte de dados do indexador para Azure Cosmos DB agora é "type": "cosmosdb"

Para usar um indexador do Azure Cosmos DB, altere "type": "documentdb" para "type": "cosmosdb".

Os erros de resultado de execução do indexador não têm mais status

A estrutura de erros da execução do indexador tinha anteriormente um elemento status. Ele foi removido porque não estava fornecendo informações úteis.

A API de fonte de dados do indexador não retorna mais cadeias de conexão

A partir das versões 2019-05-06 e 2019-05-06-Preview, a API de fonte de dados não retorna mais cadeias de conexão na resposta de qualquer operação REST. Nas versões anteriores da API, para fontes de dados criadas usando POST, a IA do Azure Search retornava 201 seguido pela resposta do OData, que continha a cadeia de conexão em texto sem formatação.

A habilidade cognitiva de Reconhecimento de Entidade Nomeada agora está descontinuada

Se você chamou a habilidade Reconhecimento de Entidade de Nome em seu código, a chamada falhará. A funcionalidade de substituição é a Habilidade de Reconhecimento de Entidade (V3). Siga as recomendações em Habilidades preteridas para migrar para uma habilidade compatível.

Atualizando tipos complexos

A versão 2019-05-06 da API adicionou suporte formal para tipos complexos. Se seu código tiver implementado recomendações anteriores para equivalência de tipo complexo na 2017-11-11-Preview ou na 2016-09-01-Preview, haverá alguns limites novos e alterados a partir da versão 2019-05-06 dos quais você precisa estar ciente:

  • Os limites de profundidade de sub-campos e de número de coleções complexas por índice foram diminuídos. Se você tiver criado índices que excedam esses limites usando as versões prévias da API, qualquer tentativa de atualizá-los ou recriá-los usando a versão 2019-05-06 da API falhará. Se você se encontrar nessa situação, precisará reprojetar seu esquema para se ajustar aos novos limites e, em seguida, recompilar o índice.

  • Há um novo limite a partir da versão 2019-05-06 da API com relação ao número de elementos de coleções complexas por documento. Se você tiver criado índices que excedam esses limites usando as versões prévias de API, qualquer tentativa de atualizá-los ou recriá-los usando a versão 2019-05-06 da API falhará. Se você se encontrar nessa situação, precisará reduzir o número de elementos de coleção complexos por documento antes de reindexar seus dados.

Para obter mais informações, confira Limites de serviço para a IA do Azure Search.

Como atualizar uma estrutura de tipo complexo antiga

Se o código estiver usando tipos complexos com uma das versões mais antigas da API de visualização, você pode estar usando um formato de definição de índice semelhante a este:

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}  

Um formato mais recente do tipo árvore para definir campos de índice foi introduzido na versão 2017-11-11-Preview da API. No novo formato, cada campo complexo tem uma coleção de campos em que seus sub-campos são definidos. Na versão 2019-05-06 da API, esse novo formato é usado de forma exclusiva e a tentativa de criar ou atualizar um índice usando o formato antigo falhará. Se você tiver índices criados com o formato antigo, precisará usar a versão 2017-11-11-Preview da API para atualizá-los para o novo formato a fim de gerenciá-los com a versão 2019-05-06.

É possível atualizar índices "simples" para o novo formato seguindo as etapas a seguir com a versão 2017-11-11-Preview da API:

  1. Execute uma solicitação GET para recuperar o índice. Caso ele já esteja no novo formato, tudo pronto.

  2. Traduza o índice do formato "simples" para o novo. Você precisa escrever código para essa tarefa, pois não há nenhum código de exemplo disponível no momento desta gravação.

  3. Execute uma solicitação PUT para atualizar o índice para o novo formato. Evite alterar qualquer outro detalhe do índice, como a pesquisabilidade/filtrabilidade dos campos, pois alterações que afetam a expressão física do índice existente não são permitidas pela API de Atualização de Índice.

Observação

Não é possível gerenciar índices criados com o antigo formato "simples" no portal do Azure. Atualize seus índices da representação "simples" para a representação de "árvore" assim que possível.

Próximas etapas

Examine a documentação de referência da API REST do Search. Se encontrar problemas, peça ajuda no Stack Overflow ou contate o suporte.