Criar um índice na IA do Azure Search

Neste artigo, saiba quais são as etapas para definir um esquema para um índice de pesquisa e enviá-lo para um serviço Pesquisa. Criar um índice estabelece as estruturas de dados físicos no seu serviço de pesquisa. Depois que o índice for criado, carregue o índice como uma tarefa separada.

Pré-requisitos

• Permissões de gravação como um Colaborador do Serviço Pesquisa ou uma chave de API de administrador para autenticação baseada em chave.

• Uma compreensão dos dados extras do dispositivo que você quer importar. Um índice de pesquisa é baseado no conteúdo externo que você quer tornar pesquisável. O conteúdo pesquisável é armazenado como campos em um índice. Você deve ter uma ideia clara de quais campos de origem deseja tornar pesquisáveis, recuperáveis, filtrados, facetáveis e classificáveis na Pesquisa de IA do Azure. Consulte a lista de verificação de esquema para obter diretrizes.

• Um campo exclusivo nos dados de origem que possa ser usado como a chave (ou ID) do documento no índice.

• Um local de índice estável. Não há suporte para mover um índice existente para um serviço de pesquisa diferente. Revisite os requisitos do aplicativo e verifique se o serviço de pesquisa existente (capacidade e região) é suficiente para suas necessidades. Se você estiver usando uma dependência dos serviços de IA do Azure ou do OpenAI do Azure, escolha uma região que forneça todos os recursos necessários.

• Por fim, todas as camadas de serviço têm limites de índice no número de objetos que você pode criar. Por exemplo, se você estiver experimentando na camada Gratuita, só poderá ter três índices em um determinado momento. No próprio índice, há limites para vetores e limites de índice no número de campos simples e complexos.

Chaves de documentos

A criação do índice de pesquisa tem dois requisitos: um índice precisa ter um nome exclusivo no serviço de pesquisa e deve ter uma chave de documento. O atributo booliano key em um campo pode ser definido como true para indicar qual campo fornece a chave do documento.

Uma chave de documento é o identificador exclusivo de um documento de pesquisa, e um documento de pesquisa é uma coleção de campos que descreve completamente algo. Por exemplo, se você estiver indexando um conjunto de dados de filmes, um documento de pesquisa conterá o título, o gênero e a duração de um único filme. Os nomes de filmes são exclusivos neste conjunto de dados, portanto, você pode usar o nome do filme como a chave do documento.

Na Pesquisa de IA do Azure, uma chave de documento é uma cadeia de caracteres e precisa se originar de valores exclusivos na fonte de dados que está fornecendo o conteúdo a ser indexado. Como regra geral, um serviço de pesquisa não gera valores de chave, mas, em alguns cenários, (como o Indexador de Tabelas do Azure), sintetiza os valores existentes para criar uma chave exclusiva para os documentos que estão sendo indexados. Outro cenário é a indexação um-para-muitos para dados em partes ou particionados, nesse caso, as chaves de documento são geradas para cada parte.

Durante a indexação incremental, em que o conteúdo novo e atualizado é indexado, os documentos de entrada com novas chaves são adicionados, enquanto os documentos de entrada com chaves existentes são mesclados ou substituídos, dependendo se os campos de índice são nulos ou preenchidos.

Pontos importantes sobre chaves de documento incluem:

• O comprimento máximo dos valores em um campo de chave é de 1.024 caracteres.
• Exatamente um campo de nível superior em cada índice precisa ser escolhido como o campo de chave e precisa ser do tipo Edm.String.
• O padrão do atributo key é falso para campos simples e nulo para campos complexos.

Os campos-chave podem ser usados para pesquisar documentos diretamente e atualizar ou excluir documentos específicos. Os valores dos campos de chave são tratados de maneira diferenciada de maiúsculas de minúsculas ao pesquisar ou indexar documentos. Confira GET Documento (REST) e Index Documentos (REST) para obter detalhes.

Lista de verificação de esquema

Use esta lista de verificação para auxiliar as decisões de design do índice de pesquisa.

1. Examine as convenções de nomenclatura para que os nomes de índice e de campo esteja em conformidade com as regras de nomenclatura.

2. Examine tipos de dados com suporte. O tipo de dados afetará como o campo é usado. Por exemplo, o conteúdo numérico pode ser filtrado, mas não pesquisável por texto completo. O tipo de dados mais comum é Edm.String para texto pesquisável, que é tokenizado e consultado usando o mecanismo de pesquisa de texto completo. O tipo de dados mais comum para um campo vetorial é Edm.Single, mas você também pode usar outros tipos.

3. Identifique uma chave de documento. Uma chave de documento é um requisito de índice. É um campo único de cadeia de caracteres preenchido com base em um campo de dados de origem que contém valores exclusivos. Por exemplo, se você estiver indexando do Armazenamento de Blobs, o caminho de armazenamento de metadados geralmente será usado como a chave do documento porque identifica exclusivamente cada blob no contêiner.

4. Identifique os campos na sua fonte de dados que podem contribuir com conteúdo pesquisável no índice.

   O conteúdo não vetorial pesquisável inclui cadeias de caracteres curtas ou longas que são consultadas usando o mecanismo de pesquisa de texto completo. Se o conteúdo for detalhado (frases pequenas ou partes maiores), experimente analisadores diferentes para ver como o texto é tokenizado.

   O conteúdo vetorial pesquisável pode ser imagens ou texto (em qualquer idioma) que exista como uma representação matemática. Você pode usar tipos de dados estreitos ou compactação de vetores para diminuir o tamanho dos campos vetoriais.

   Atributos definidos em campos, como retrievable ou filterable, determinam tanto os comportamentos de pesquisa quanto a representação física do seu índice no serviço Pesquisa. Determinar como os campos devem ser especificados é um processo iterativo para muitos desenvolvedores. Para acelerar as iterações, comece com os dados de exemplo para que você possa remover e recriar com facilidade.

5. Identifique quais campos de origem podem ser usados como filtros. Conteúdo numérico e campos de texto curto, especialmente aqueles com valores repetidos, são boas opções. Ao trabalhar com filtros, lembre:

   • Os filtros podem ser usados em consultas vetoriais e não vetoriais, mas o filtro em si é aplicado a campos alfanuméricos (não vetoriais) em seu índice.

   • Opcionalmente, os campos filtráveis podem ser usados faceted navigation.

   • Campos filtráveis são retornados em ordem arbitrária e não passam por pontuação de relevância, portanto, considere torná-los classificáveis também.

6. Para campos vetoriais, especifique uma configuração de busca em vetores e os algoritmos usados para criar caminhos de navegação e preencher o espaço de inserção. Para obter mais informações, confira Adicionar campos vetoriais.

   Os campos vetoriais têm propriedades extras que os campos não vetoriais não têm, como os algoritmos a serem usados e a compactação de vetores.

   Os campos vetoriais omitem atributos que não são úteis em dados vetoriais, como classificação, filtragem e facetamento.

7. Para campos não vetoriais, determine se deve usar o analisador padrão ("analyzer": null) ou um analisador diferente. Os analisadores são usados para tokenizar campos de texto durante a indexação e a execução da consulta.

   Nas cadeias de caracteres multilíngues, considere um analisador de linguagem.

   Nas cadeias de caracteres hifenizadas ou caracteres especiais, considere analisadores especializados. Um exemplo é palavra-chave que trata todo o conteúdo de um campo como um único token. Esse comportamento é útil para os dados como CEP, IDs e alguns nomes de produto. Para obter mais informações, consulte Pesquisa de termo parcial e padrões com caracteres especiais.

Configurar definições de campo

A coleção de campos define a estrutura de um documento de pesquisa. Os campos têm um nome, atributos e um tipo de dados.

Definir um campo como pesquisável, filtrável, classificável ou facetável tem um efeito sobre o tamanho do índice e o desempenho da consulta. Não defina esses atributos em campos que não devem ser referenciados em expressões de consulta.

Se um campo não estiver definido como pesquisável, filtrável, classificável ou facetável, o campo não poderá ser referenciado em nenhuma expressão de consulta. Isso é desejável para campos que não são usados em consultas, mas são necessários nos resultados da pesquisa.

As APIs REST têm atribuição padrão com base nos tipos de dados, que também são usados pelos Assistentes de importação no portal do Azure. Os SDKs do Azure não têm padrões, mas têm subclasses de campo que incorporam propriedades e comportamentos como SearchableField para cadeias de caracteres e SimpleField para primitivos.

As atribuições de campo padrão para as APIs REST são resumidas na tabela a seguir.

Campos de cadeia de caracteres também podem ser associados opcionalmente a analisadores e mapas de sinônimos. Campos do tipo Edm.String que são filtráveis, classificáveis ou facetáveis podem ter, no máximo, 32 quilobytes de tamanho. Isso ocorre porque os valores desses campos são tratados como um termo de pesquisa único e o comprimento máximo de um termo na Pesquisa de IA do Azure é de 32 quilobytes. Se você precisar armazenar mais texto do que isso em apenas um campo de cadeia de caracteres, deverá definir explicitamente filtrável, classificável e facetável para false em sua definição de índice.

Os campos de vetor precisam ser associados a dimensões e perfis de vetor. O padrão recuperável será verdadeiro se você adicionar o campo de vetor usando o Assistente de importação e vetorização no portal, caso contrário, será falso se você usar a API REST.

Os atributos de campo são descritos na tabela a seguir.

Crie um índice

Quando você estiver pronto para criar o índice, use um cliente de pesquisa que possa enviar a solicitação. Você pode usar o portal do Azure ou as APIs REST para desenvolvimento inicial e testes de prova de conceito; caso contrário, é comum usar SDKs do Azure.

Durante o desenvolvimento, planeje recompilações frequentes. Como as estruturas físicas são criadas no serviço, é necessário remover e recriar índices para muitas modificações. Considere trabalhar com um subconjunto de seus dados para acelerar as recompilações.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Definir corsOptions para consultas entre origens

Esquemas de índice incluem uma seção para definir corsOptions. Por padrão, o JavaScript do lado do cliente não pode chamar as APIs porque os navegadores impedem todas as solicitações entre origens. Para permitir consultas entre origens pelo índice, habilite o Compartilhamento de Recursos entre Origens (CORS) definindo o atributo corsOptions. Por motivos de segurança, apenas as APIs de consulta dão suporte ao CORS.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

As seguintes propriedades podem ser definidas para o CORS:

• allowedOrigins (obrigatório): essa é uma lista de origens às quais será concedido acesso ao seu índice. O código JavaScript fornecido dessas origens tem permissão para consultar seu índice (supondo que o chamador forneça uma chave válida ou tenha permissões). Cada origem é tipicamente da forma, protocol://<fully-qualified-domain-name>:<port> embora <port> seja frequentemente omitida. Para obter mais informações, consulte compartilhamento de recursos entre origens (Wikipédia).

  Se você quiser permitir acesso a todas as origens, inclua * como um único item na matriz allowedOrigins. Essa não é uma prática recomendada para os serviços de pesquisa de produção, mas geralmente é útil para desenvolvimento e depuração.

• maxAgeInSeconds (opcional): navegadores usam esse valor para determinar a duração (em segundos) para respostas de simulação de CORS de cache. Esse deve ser um inteiro não negativo. Um período de cache mais longo oferece melhor desempenho, mas estende a quantidade de tempo que uma política CORS precisa para entrar em vigor. Se esse valor não for definido, será usada uma duração padrão de cinco minutos.

Atualizações permitidas em índices existentes

Criar Índice cria as estruturas de dados física (arquivos e índices invertidos) no serviço de pesquisa. Depois que o índice é criado, sua capacidade de efetuar alterações usando Criar ou Atualizar Índice depende do fato de suas modificações invalidarem essas estruturas físicas. A maioria dos atributos de campo não pode ser alterada depois que o campo é criado no índice.

Para minimizar a variação no código do aplicativo, você pode criar um alias de índice que serve como uma referência estável para o índice de pesquisa. Em vez de atualizar o seu código com nomes de índice, você pode atualizar um alias de índice para apontar para versões de índice mais recentes.

Para minimizar a rotatividade no processo de design, a tabela a seguir descreve quais elementos são fixos e flexíveis no esquema. Alterar um elemento fixo requer uma recompilação do índice, enquanto elementos flexíveis podem ser alterados a qualquer momento sem afetar a implementação física. Para obter mais informações, confira Atualizar ou recompilar um índice.

Próximas etapas

Use os seguintes links para saber mais sobre recursos especializados que podem ser adicionados a um índice:

• Adicionar campos de vetor e perfis de vetor
• Adicionar perfis de pontuação
• Adicionar classificação semântica
• Adicionar sugestores
• Adicionar mapas de sinônimos
• Adicionar analisadores
• Adicionar criptografia

Use estes links para carregar ou atualizar um índice:

• Visão geral da importação de dados
• Carregue os documentos
• Atualizar ou recompilar um índice