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

Artigo
05/06/2024

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

2023-11-01 é a versão estável mais recente. A classificação semântica e o suporte para indexação vetorial e consultas estão geralmente disponíveis nesta versão.
2023-10-01-preview é a versão de pré-visualização mais recente. Os recursos de visualização incluem vetorização de consulta interna, fragmentação de dados interna e vetorização durante a indexação (usa a habilidade Divisão de Texto e a habilidade Incorporação do Azure OpenAI).
2023-07-01-preview foi a primeira API REST para suporte vetorial. Agora ele foi preterido e você deve migrar para 2023-11-01 ou 2023-10-01-preview imediatamente.

Nota

Os documentos de referência da API REST agora estão versionados. Para obter o conteúdo certo, abra uma página de referência e, em seguida, filtre por versão, usando o seletor localizado acima do índice.

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 preterida e está sujeito a uma ou mais das alterações de quebra. As versões de API que se enquadram nesta categoria incluem 2023-07-10-preview para vetores e 2019-05-06.
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 aplica-se 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.

Atualize para 2023-10-01-preview

Esta seção explica o caminho de migração de 2023-07-01-preview para 2023-10-01-preview. Você deve migrar para 2023-10-01-preview se quiser usar recursos de vetor que ainda estão em visualização pública. Se você não precisar dos recursos de visualização, recomendamos atualizar para a versão estável, 2023-11-01.

As funcionalidades de pré-visualização incluem:

Como esses recursos não existiam em versões anteriores da API, não há um caminho de migração. Para saber como adicionar esses recursos ao seu código, consulte exemplos de código e instruções passo a passo.

Em contraste, as definições de campo vetorial, a configuração do algoritmo de pesquisa vetorial e a sintaxe de consulta vetorial que foram introduzidas pela primeira vez em 2023-07-01-preview foram alteradas. A sintaxe 2023-10-01-preview para campos vetoriais, algoritmos e consultas vetoriais é idêntica à sintaxe 2023-11-01. As etapas de migração para essas construções vetoriais são explicadas na atualização para 2023-11-01.

Atualização do portal para índices vetoriais

O portal do Azure suporta um caminho de atualização com um clique para índices de pré-visualização 2023-07-01. O portal deteta campos vetoriais 2023-07-01-preview e fornece um botão Migrar .

O caminho de migração é de 2023-07-01-preview a 2023-10-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á usar 2023-10-01-preview ou posterior para consultar o índice.

Não há migração de portal para atualizar a sintaxe de consulta vetorial. Consulte atualizar para 2023-11-01 para obter alterações na sintaxe da 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 em atualizar para 2023-11-01. 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 algoritmo de pesquisa vetorial 2023-07-01-preview. Índices com várias configurações de pesquisa vetorial exigem migração manual.

Atualize para 2023-11-01

Esta versão tem mudanças de quebra e diferenças comportamentais para classificação semântica e suporte de pesquisa vetorial.

O ranking semântico está disponível em 2023-11-01. Ele não usa mais o queryLanguage imóvel. Requer também uma semanticConfiguration definição. A semanticConfiguration substitui searchFields em versões anteriores. Consulte Migrar da versão de visualização para conhecer as etapas.
O suporte à pesquisa vetorial foi introduzido no Create or Update Index (2023-07-01-preview). A atualização de 2023-07-01-preview requer renomear e reestruturar a configuração do vetor no índice. Também requer a reescrita de suas consultas vetoriais. Use as instruções nesta seção para migrar campos vetoriais, configuração e consultas.

Se você estiver atualizando de 2023-10-01-preview para 2023-11-01, não há alterações de quebra, mas há uma diferença de comportamento: o vectorFilterMode padrão mudou de postfilter para prefilter para expressões de filtro. Se o código de pré-visualização 2023-10-01 não estiver definido vectorFilterMode explicitamente, certifique-se de que compreende o novo comportamento predefinido ou defina explicitamente vectorFilterMode como pós-filtro para manter o comportamento antigo.

Aqui estão as etapas para migrar de 2023-07-01-preview para 2023-11-01:

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

Modifique a configuração da pesquisa vetorial. 2023-11-01 introduz o conceito de perfis vetoriais que agrupam configurações relacionadas a vetores sob um nome. Também muda 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 a versão 2023-11-01 da API.

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-062019-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.