Compartilhar via

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

  • Artigo

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

As instruções de atualização se concentram nas alterações de código que o ajudam a superar as alterações das versões anteriores, de modo que o código existente seja executado da mesma forma que antes, mas na versão mais recente da API. Quando seu código estiver funcionando, você poderá decidir se quer adotar recursos mais recentes. Para saber mais sobre os novos recursos, consulte exemplos de código de vetor e Novidades.

Recomendamos atualizar as versões da API sucessivamente, trabalhando em cada versão até chegar à mais recente.

2023-07-01-preview foi a primeira API REST com suporte a vetores. Não use essa versão da API. Agora ela foi preterida e você deve migrar imediatamente para uma versão prévia mais recente ou estável das APIs REST.

Observação

Os documentos de referência da API REST agora têm controle de versão. Para conteúdo específico das versões, abra uma página de referência e use o seletor localizado à direita, acima do sumário, para escolher sua versão.

Quando atualizar

A Pesquisa de IA do Azure interrompe a compatibilidade com versões anteriores como um último recurso. Um upgrade será necessário quando:

  • Seu código faz referência a uma versão de API desativada ou sem suporte e está sujeito a uma ou mais alterações de interrupção. Você deve lidar com alterações interruptivas se seus destinos de código 2023-07-10-preview para vetores, 2020-06-01-preview para classificador semântico e 2019-05-06 para habilidades e soluções alternativas obsoletas.

  • 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).

Como atualizar

  1. Examine as notas sobre a versão de cada versão da API.

  2. Atualize o parâmetro api-version, especificado no cabeçalho da solicitação, para uma versão mais recente.

    No código do seu aplicativo que faz chamadas diretas para as APIs REST, procure todas as instâncias da versão existente e substitua-as pela nova versão. Para obter mais informações sobre como estruturar uma chamada REST, veja Início Rápido: usando REST.

    Se estiver a utilizar um SDK do Azure, esses pacotes destinam-se a versões específicas da API REST. As atualizações de pacote podem coincidir com uma atualização da API REST, mas cada SDK tem um cronograma de lançamento próprio, enviado independentemente das versões da API REST da Pesquisa de IA do Azure. Verifique o log de alterações do seu pacote SDK para determinar se uma versão do pacote é direcionada à versão mais recente da API REST.

  3. Examine as alterações interruptivas documentadas neste artigo e implemente as soluções alternativas. Comece com a versão usada pelo código e resolva qualquer alteração significativa para cada versão mais recente da API até chegar à versão mais recente estável ou de versão prévia.

Alteração interruptiva para o código do cliente que faz a leitura das informações de conexão

Em vigor a partir de 29 de março de 2024 e aplica-se a todas as APIs REST com suporte:

  • GET Skillset, GET Index e GET Indexer, não retornam mais chaves ou propriedades de conexão em uma resposta. Esta será uma alteração interruptiva, caso tenha um código downstream que faz a leitura das chaves ou conexões (dados confidenciais) de uma resposta GET.

  • Caso precise recuperar as chaves de API de administrador ou de consulta para seu serviço de pesquisa, use as APIs REST de Gerenciamento.

  • Caso precise recuperar cadeias de conexão de outro recurso do Azure, como o Armazenamento do Microsoft Azure ou o Azure Cosmos DB, use as APIs desse recurso e as diretrizes publicadas para obter as informações.

Alteração interruptiva para o classificador semântico

O classificador semântico está em disponibilidade geral no 2023-11-01. Aqui estão as alterações interruptivas para o classificador semântico das versões anteriores:

  • Em todas as versões após 2020-06-01-preview: semanticConfiguration substitui searchFields como o mecanismo para especificar quais campos usar para a classificação L2.

  • Para todas as versões da API, as atualizações de 14 de julho de 2023 para os modelos semânticos hospedados pela Microsoft tornaram o classificador semântico independente da linguagem, desativando efetivamente a propriedade queryLanguage. Não há nenhuma "alteração interruptiva" no código, mas a propriedade é ignorada.

Consulte Migrar da versão prévia para fazer a transição do código para usar semanticConfiguration.

Fazer upgrade para 2024-11-01-preview

Reescrita de consulta de 2024-11-01-preview, habilidade de Layout de Documento, cobrança sem chave para processamento de habilidades, modo de análise Markdown e opções de nova pontuação para vetores compactados.

Se você estiver atualizando de 2024-09-01-preview, poderá usar as novas APIs em versão prévia sem nenhuma alteração no código existente.

No entanto, a nova versão apresenta alterações de sintaxe ao vectorSearch.compressions:

  • Substitui rerankWithOriginalVectors por enableRescoring
  • Move defaultOversampling para um novo objeto de propriedade rescoringOptions

A compatibilidade com versões anteriores é preservada devido a um mapeamento de API interno, mas recomendamos alterar a sintaxe se você adotar a nova versão prévia. Para ver uma comparação da sintaxe, consulte Compactar vetores usando compartimentalização escalar ou binária.

Fazer o upgrade para 2024-09-01-preview

2024-09-01-preview adiciona a compactação MRL (Matryoshka Representation Learning) para modelos text-embedding-3, filtragem de vetor direcionada para consultas híbridas, detalhes de subestação de vetor para depuração e agrupamento de token para habilidade de Divisão de Texto.

Se você estiver atualizando de 2024-05-01-preview, poderá usar as novas APIs em versão prévia sem nenhuma alteração no código existente.

Atualizar para 2024-07-01

2024-07-01 é uma versão geral. As versões prévias de recurso anteriores agora estão em disponibilidade geral: agrupamento integrado e vetorização (habilidade de Divisão de Texto, habilidade AzureOpenAIEmbedding), vetorizador de consulta com base no AzureOpenAIEmbedding, compactação de vetor (quantização escalar, quantização binária, propriedade armazenada, tipos de dados estreitos).

Não haverá alterações significativas se você atualizar de 2024-05-01-preview para estável. Para usar a nova versão estável, altere a versão da API e teste seu código.

Haverá alterações significativas se você atualizar diretamente de 2023-11-01. Siga as etapas descritas para cada versão prévia mais recente a ser migrada de 2023-11-01 para 2024-07-01.

Fazer o upgrade para 2024-05-01-preview

2024-05-01-preview adiciona o índice OneLake, suporte para vetores binários e suporte para mais modelos de inserção.

Se você estiver atualizando da 2024-03-01-preview, a habilidade AzureOpenAIEmbedding agora exigirá uma propriedade nome do modelo e uma propriedade dimensões.

  1. Pesquise em sua base de código referências a AzureOpenAIEmbedding.

  2. Defina modelName como "text-embedding-ada-002" e defina dimensions como "1536".

Fazer o upgrade para 2024-03-01-preview

2024-03-01-preview adiciona tipos de dados estreitos, quantização escalar e opções de armazenamento de vetor.

Se você estiver atualizando da 2023-10-01-preview, não haverá alterações interruptivas. No entanto, há uma diferença de comportamento: para 2023-11-01 e versões prévias mais recentes, o vectorFilterMode padrão foi alterado de pós-filtro para pré-filtro para expressões de filtro.

  1. Pesquise referências a vectorFilterMode na base de código.

  2. Se a propriedade estiver definida explicitamente, nenhuma ação será necessária. Se você usou o padrão, lembre-se de que o novo comportamento padrão é filtrar antes da execução da consulta. Se você quiser filtragem pós-consulta, defina vectorFilterMode explicitamente como pós-filtro para manter o comportamento antigo.

Atualizar para a 2023-11-01

2023-11-01 é uma versão geral. As versões prévias do recurso anteriores agora estão em disponibilidade geral: classificador semântico, índice de vetor e suporte à consulta.

Não há alterações significativas de 2023-10-01-preview, mas há várias alterações significativas de 2023-07-01-preview para 2023-11-01. Para obter mais informações, consulte Atualizar de 2023-07-01-preview.

Para usar a nova versão estável, altere a versão da API e teste seu código.

Fazer o upgrade para 2023-10-01-preview

2023-10-01-preview foi a primeira versão de visualização a adicionar agrupamento e vetorização interna de dados durante a indexação e vetorização interna de consulta. Ela também dá suporte à indexação de vetor e consultas da versão anterior.

Se você estiver atualizando da versão anterior, a próxima seção terá as etapas.

Atualização de 2023-07-01-preview

Não use esta versão da API. Ela implementa uma sintaxe de consulta vetorial incompatível com qualquer versão mais recente da API.

2023-07-01-preview agora está preterida, portanto, você não deve basear o novo código nessa versão, nem deve atualizar para essa versão em nenhuma circunstância. Esta seção explica o caminho de migração da 2023-07-01-preview para qualquer versão mais recente da API.

Atualização do portal para índices de vetor

O portal do Azure dá suporte a um caminho de atualização de um clique para índices da 2023-07-01-preview. Ele detecta campos de vetor e fornece um botão Migrar.

  • O caminho de migração é de 2023-07-01-preview para 2024-05-01-preview.
  • As atualizações são limitadas a definições de campo de vetor e configurações de algoritmo de pesquisa de vetor.
  • As atualizações são unidirecionais. Não é possível reverter a atualização. Depois que o índice for atualizado, você deverá usar a versão 2024-05-01-preview ou versões posteriores para consultar o índice.

Não há nenhuma migração de portal para atualizar a sintaxe da consulta de vetor. Consulte atualizações de código para obter alterações da sintaxe de consulta.

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 na seção atualização de código. A migração do portal manipula apenas índices com uma configuração de algoritmo de pesquisa de vetor. Ela cria um perfil padrão que mapeia para o algoritmo de busca em vetores da 2023-07-01-preview. Índices com várias configurações de pesquisa de vetor exigem migração manual.

Atualização de código dos índices vetoriais e consultas

Suporte de busca em vetores foi introduzido no Criar ou Atualizar índice (2023-07-01-preview).

A atualização de 2023-07-01-preview para qualquer versão mais recente estável ou de versão prévia requer:

  • Renomeando e reestruturando a configuração de vetor no índice
  • Reescrever suas consultas de vetor

Use as instruções nesta seção para migrar campos de vetor, configuração e consultas de 2023-07-01-preview.

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

  2. Modifique a configuração de busca em vetores. 2023-11-01 e versões posteriores introduzem o conceito dos perfis de vetor que agrupam as configurações relacionadas a vetores em um único nome. As versões mais recentes também renomeiam 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": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

  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-o como vector.
    • 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 de API estável 2023-11-01 ou versões mais recentes da API da versão prévia.

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. Um repositório de conhecimento é criado por meio de APIs REST da Pesquisa de IA do Azure, mas reside no Armazenamento do Microsoft Azure.

Alterações da falha

O código gravado em versões anteriores da API será interrompido em 2020-06-30 e posteriormente se o código contiver a seguinte funcionalidade:

  • Todos os 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

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 da falha

O código gravado em uma versão da API anterior será interrompido em 2019-05-06 e posteriormente se ele contiver a seguinte funcionalidade:

  1. Propriedade de Tipo para o Azure Cosmos DB. Para os indexadores direcionados a uma fonte de dados da API do Azure Cosmos DB for NoSQL, altere "type": "documentdb" para "type": "cosmosdb".

  2. Se o tratamento de erros do seu indexador incluir referências à propriedade status, você deverá removê-la. Removemos o status da resposta de erro porque não estava fornecendo informações úteis.

  3. As cadeias de conexão da fonte de dados não são mais retornadas na resposta. A partir das versões de API 2019-05-06 e 2019-05-06-Preview, a API da 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.

  4. A habilidade cognitiva de Reconhecimento de Entidade Nomeada foi desativada. 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 da API 2019-05-06 adicionou suporte formal para tipos complexos. Se o código implementou recomendações anteriores para equivalência de tipo complexo em 2017-11-11-Preview ou 2016-09-01-Preview, há alguns limites novos e alterados a partir da versão 2019-05-06 sobre os 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ê criou índices que excedem 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 começando na versão 2019-05-06 da API no número de elementos de coleções complexas por documento. Se você criou índices com documentos que excedem esses limites usando as versões prévias da API, qualquer tentativa de reindexar esses dados 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 semelhante ao de árvore para definir campos de índice foi introduzido na versão da API 2017-11-11-Preview. 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 usando o formato antigo, será necessário usar a versão 2017-11-11-Preview da API para atualizá-los para o novo formato antes que eles possam ser gerenciados usando a API versão 2019-05-06.

Você pode atualizar índices simples para o novo formato com as seguintes etapas usando 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.

Referência da API REST do serviço Search