Atualizar para a API REST mais recente na Pesquisa de IA do Azure

Artigo
06/24/2024

Use este artigo para migrar chamadas de plano de dados para versões mais recentes das APIs REST de pesquisa.

2023-11-01 é a versão estável mais recente.
2024-05-01-preview é a versão mais recente da API de visualização.

As instruções de atualização se concentram nas alterações de código que ajudam você a quebrar as alterações das versões anteriores para que o código existente seja executado da mesma forma que antes, mas na versão mais recente da API. Quando o código estiver em funcionamento, você poderá decidir se deseja adotar recursos mais recentes. Para saber mais sobre os recursos de visualização, consulte Exemplos de código vetorial 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 para suporte vetorial. Não use esta versão da API. Agora ele foi preterido e você deve migrar para APIs REST de visualização estáveis ou mais recentes imediatamente.

Nota

Os documentos de referência da API REST agora estão versionados. Para conteúdo específico da versão, abra uma página de referência e use o seletor localizado à direita, acima do índice, para escolher sua versão.

Quando atualizar

O Azure AI Search quebra a compatibilidade com versões anteriores como último recurso. A atualização é necessária quando:

Seu código faz referência a uma versão de API desativada ou não suportada e está sujeito a uma ou mais alterações de quebra. Você deve abordar as alterações de quebra se o seu código tiver como destino 2023-07-10-preview vetores, 2020-06-01-preview classificação semântica e 2019-05-06 habilidades obsoletas e soluções alternativas.
Seu código falha quando propriedades não reconhecidas são retornadas em uma resposta de API. Como prática recomendada, seu aplicativo deve ignorar propriedades que não compreende.
Seu código persiste as solicitações de API e tenta reenviá-las para a nova versão da API. Por exemplo, isso pode acontecer se seu aplicativo persistir tokens de continuação retornados da API de Pesquisa (para obter mais informações, procure @search.nextPageParameters na Referência da API de Pesquisa).

Alteração de quebra para o código do cliente que lê informações de conexão

Em vigor a partir de 29 de março de 2024 e aplicável a todas as APIs REST suportadas:

GET Skillset, GET Index e GET Indexer não retornam mais chaves ou propriedades de conexão em uma resposta. Esta é uma alteração significativa se você tiver um código downstream que lê chaves ou conexões (dados confidenciais) de uma resposta GET.
Se você precisar recuperar chaves de API de administrador ou consulta para seu serviço de pesquisa, use as APIs REST de gerenciamento.
Se você precisar recuperar cadeias de conexão de outro recurso do Azure, como o Armazenamento do Azure ou o Azure Cosmos DB, use as APIs desse recurso e as diretrizes publicadas para obter as informações.

Mudança significativa para classificação semântica

A classificação semântica está geralmente disponível em 2023-11-01. Aqui estão as principais alterações para classificação semântica de 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 em 14 de julho de 2023 para os modelos semânticos hospedados pela Microsoft tornaram o ranking semântico agnóstico à linguagem, desativando efetivamente a queryLanguage propriedade. Não há "alteração de quebra" no código, mas a propriedade é ignorada.

Consulte Migrar da versão de pré-visualização para fazer a transição do seu código para utilizar semanticConfiguration.

Atualize para 2024-05-01-preview

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

Se você estiver atualizando do , a habilidade AzureOpenAIEmbedding agora requer um nome de modelo e uma propriedade de 2024-03-01-previewdimensões.

Pesquise sua base de código para referências AzureOpenAIEmbedding .
Defina modelName como "text-embedding-ada-002" e definido dimensions como "1536".

Atualize para 2024-03-01-preview

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

Se você estiver atualizando a partir do 2023-10-01-preview, não há alterações ininterruptas. No entanto, há uma diferença de comportamento: para 2023-11-01 visualizações mais recentes, o vectorFilterMode padrão mudou de pós-filtro para pré-filtro para expressões de filtro.

Pesquise referências na vectorFilterMode sua base de código.
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 desejar filtragem pós-consulta, defina vectorFilterMode explicitamente como postfilter para manter o comportamento antigo.

Atualize para 2023-10-01-preview

2023-10-01-preview foi a primeira versão de visualização a adicionar fragmentação e vetorização de dados internos durante a indexação e vetorização de consulta interna. Ele também suporta indexação vetorial e consultas da versão anterior.

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

Atualize a partir de 2023-07-01-preview

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

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

Atualização do portal para índices vetoriais

O portal do Azure dá suporte a um caminho de atualização com um clique para 2023-07-01-preview índices. Ele deteta campos vetoriais 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 vetorial e configurações de algoritmo de pesquisa vetorial.
As atualizações são unidirecionais. Não é possível reverter a atualização. Depois que o índice for atualizado, você deverá usá-lo 2024-05-01-preview ou posteriormente para consultá-lo.

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

Antes de selecionar Migrar, selecione Editar JSON para revisar o esquema atualizado primeiro. Você deve encontrar um esquema que esteja em conformidade com as alterações descritas na seção de atualização de código. A migração do portal lida apenas com índices com uma configuração de algoritmo de pesquisa vetorial. Ele cria um perfil padrão que mapeia para o 2023-07-01-preview algoritmo de pesquisa vetorial. Índices com várias configurações de pesquisa vetorial exigem migração manual.

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

O suporte à pesquisa vetorial foi introduzido no Create or Update Index (2023-07-01-preview).

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

Renomeando e reestruturando a configuração vetorial no índice
Reescrevendo suas consultas vetoriais

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

Chame Get Index para recuperar a definição existente.

Modifique a configuração da pesquisa vetorial. 2023-11-01e versões posteriores introduzem o conceito de perfis vetoriais que agrupam configurações relacionadas a vetores sob um nome. As versões mais recentes também mudam o nome algorithmConfigurations para algorithms.

Mudar o nome de algorithmConfigurations para algorithms. Esta é apenas uma renomeação da matriz. O conteúdo é compatível com versões anteriores. Isso significa que seus parâmetros de configuração HNSW existentes podem ser usados.
Adicione profiles, dando um nome e uma configuração de algoritmo para cada um.

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

Modificar definições de campo vetorial, substituindo vectorSearchConfiguration por vectorSearchProfile. Verifique se o nome do perfil é resolvido para uma nova definição de perfil vetorial, e não para o nome da configuração do algoritmo. Outras propriedades do campo vetorial permanecem inalteradas. Por exemplo, eles não podem ser filtráveis, classificáveis ou facialmente, 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"
  }

Depois (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"
  }

Chame Criar ou Atualizar Índice para postar as alterações.

Modifique o POST de pesquisa para alterar a sintaxe da consulta. Essa alteração de API permite o suporte para tipos de consulta vetorial polimórfica.

Mudar o nome de vectors para vectorQueries.
Para cada consulta vetorial, adicione kind, definindo-a como vector.
Para cada consulta vetorial, renomeie value para vector.
Opcionalmente, adicione vectorFilterMode se estiver usando expressões de filtro. O padrão é pré-filtro para índices criados após 2023-10-01. Os índices criados antes dessa data suportam apenas o 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"
}

Depois (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"
}

Estas etapas concluem a migração para 2023-11-01 a versão estável da API ou para versões mais recentes da API de visualização.

Atualizar para 2020-06-30

Nesta versão, há uma mudança de rutura e várias diferenças comportamentais. Os recursos geralmente disponíveis incluem:

Armazenamento de conhecimento, armazenamento persistente de conteúdo enriquecido criado através de conjuntos de habilidades, criado para análise downstream e processamento através de outros aplicativos. Um repositório de conhecimento é criado por meio das APIs REST do Azure AI Search, mas reside no Armazenamento do Azure.

Quebrando a mudança

O código escrito em versões anteriores da API é interrompido e 2020-06-30 posterior se o código contiver a seguinte funcionalidade:

Quaisquer Edm.Date literais (uma data composta de ano-mês-dia, como 2020-12-12) em expressões de filtro devem seguir o Edm.DateTimeOffset formato: 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 algoritmo de classificação anterior por uma tecnologia mais recente. Os serviços criados após 2019 utilizam este algoritmo automaticamente. Para serviços mais antigos, você deve definir parâmetros para usar o novo algoritmo.
Os resultados ordenados para valores nulos foram alterados nesta versão, com valores nulos aparecendo primeiro se a classificação for asc e por último se a classificação for desc. Se você escreveu código para manipular como os valores nulos são classificados, esteja ciente dessa alteração.

Atualize para 2019-05-06

Os recursos que se tornaram geralmente disponíveis nesta versão da API incluem:

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

Alterações interruptivas

O código escrito em uma versão anterior da API é interrompido e 2019-05-06 posterior se contiver a seguinte funcionalidade:

Propriedade Type para Azure Cosmos DB. Para indexadores direcionados a uma fonte de dados da API do Azure Cosmos DB para NoSQL, altere "type": "documentdb" para "type": "cosmosdb".
Se o tratamento de erros do status indexador incluir referências à propriedade, você deverá removê-la. Removemos o status da resposta de erro porque ele não estava fornecendo informações úteis.
As cadeias de conexão da fonte de dados não são mais retornadas na resposta. A partir das versões 2019-05-06 2019-05-06-Preview da API, a API da fonte de dados não retorna mais cadeias de conexão na resposta de qualquer operação REST. Em versões anteriores da API, para fontes de dados criadas usando POST, a Pesquisa de IA do Azure retornava 201 seguida pela resposta OData, que continha a cadeia de conexão em texto sem formatação.
A habilidade cognitiva de Reconhecimento de Entidade Nomeada é aposentada. Se você chamou a habilidade de 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 suportada.

Atualizando tipos complexos

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

Os limites da profundidade dos subcampos e do número de coleções complexas por índice foram reduzidos. Se você criou índices que excedem esses limites usando as versões de api de visualização, 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á redesenhar seu esquema para caber dentro dos novos limites e, em seguida, reconstruir seu índice.
Há um novo limite a partir da versão 2019-05-06 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 de api de visualização, qualquer tentativa de reindexar esses dados usando a versão 2019-05-06 de api falhará. Se você se encontrar nessa situação, precisará reduzir o número de elementos de coleta complexos por documento antes de reindexar seus dados.

Para obter mais informações, consulte Limites de serviço para o Azure AI Search.

Como atualizar uma antiga estrutura de tipo complexo

Se o seu 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 novo formato semelhante a uma árvore para definir campos de índice foi introduzido na versão 2017-11-11-Previewda API. No novo formato, cada campo complexo tem uma coleção de campos onde seus subcampos são definidos. Na versão API 2019-05-06, este novo formato é usado exclusivamente e a tentativa de criar ou atualizar um índice usando o formato antigo falhará. Se você tiver índices criados usando o formato antigo, precisará 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 versão da API 2019-05-06.

Você pode atualizar índices simples para o novo formato com as seguintes etapas usando a versão 2017-11-11-Previewda API:

Execute uma solicitação GET para recuperar seu índice. Se já estiver no novo formato, está feito.
Traduza o índice do formato simples para o novo formato. Você tem que escrever código para esta tarefa, uma vez que não há nenhum código de exemplo disponível no momento em que este artigo foi escrito.
Execute uma solicitação PUT para atualizar o índice para o novo formato. Evite alterar quaisquer outros detalhes do índice, como a capacidade de pesquisa/filtragem de campos, porque as alterações que afetam a expressão física do índice existente não são permitidas pela API de Índice de Atualização.