Criar um índice na Pesquisa de IA do Azure

Neste artigo, aprenda as etapas para definir um esquema para um índice de pesquisa e enviá-lo por push para um serviço de pesquisa. A criação de um índice estabelece as estruturas de dados físicos no seu serviço de pesquisa. Quando o índice existir, carregue-o como uma tarefa separada.

Pré-requisitos

• Uma assinatura do Azure. Crie um gratuitamente.

• Um serviço Pesquisa de IA do Azure, de qualquer região e nível, mas deve ser um nível faturável (Básico ou superior) para acesso baseado em funções.

• Permissões para criar um índice: Função de Contribuidor de Serviço de Pesquisa ou uma chave API de administrador para autenticação baseada em chaves.

• Um campo único nos seus dados de origem que pode ser usado como chave do documento no índice.

• Uma compreensão do seu esquema de dados. Consulte a lista de verificação do esquema para orientações de concepção sobre como tornar campos pesquisáveis, recuperáveis, filtráveis, facetáveis e ordenáveis.

Criar um índice

Quando 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 APIs REST para desenvolvimento inicial e testes de prova de conceito, caso contrário, é comum usar os SDKs do Azure.

Durante o desenvolvimento, planeje reconstruções frequentes. Como as estruturas físicas são criadas no serviço, descartar e recriar índices é necessário para muitas modificações. Você pode considerar trabalhar com um subconjunto de seus dados para tornar as reconstruções mais rápidas.

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)[ ... ]
}

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

// 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);

Verificar criação de índice

Depois de criar um índice, verifique se existe listando os índices no seu serviço de pesquisa.

GET https://[servicename].search.windows.net/indexes?api-version=[api-version]

// List all indexes to verify creation
var indexNames = indexClient.GetIndexNames();
foreach (var name in indexNames)
{
    Console.WriteLine(name);
}

Chaves do documento

A criação do índice de pesquisa tem dois requisitos: um índice deve ter um nome exclusivo no serviço de pesquisa e deve ter uma chave de documento. O atributo booleano 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.

No Pesquisa de IA do Azure, uma chave de documento é uma cadeia de caracteres e deve ser originada 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 tabela do Azure) sintetiza 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 fragmentados ou particionados, caso em que as chaves de identificação do documento são geradas para cada fragmento.

Durante a indexação incremental, onde 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 deve ser escolhido como o campo chave e deve ser do tipo Edm.String.
• O padrão do key atributo é false para campos simples e null para campos complexos.

Os campos-chave podem ser usados para pesquisar documentos diretamente e atualizar ou excluir documentos específicos. Os valores dos campos-chave são tratados com distinção entre maiúsculas e minúsculas ao pesquisar ou indexar documentos. Consulte GET Document (REST) e Index Documents (REST) para obter detalhes.

Lista de verificação do esquema

Utilize esta lista de verificação para ajudar nas decisões de design para o índice de pesquisa.

1. Veja as convenções de nomenclatura para que os nomes de índices e campos estejam em conformidade com as regras de nomenclatura.

2. Veja Tipos de dados suportados. O tipo de dados afeta a forma como o campo é utilizado. Por exemplo, o conteúdo numérico é filtrável, mas não pode ser pesquisado em texto completo. O tipo de dados mais comum é Edm.String para texto pesquisável, que é tokenizado e consultado com o motor de busca de texto completo. O tipo de dados mais comum para um campo vetorial é, Edm.Single mas você também pode usar outros tipos.

3. Forneça uma descrição do índice, máximo de 4.000 caracteres. Este texto legível por humanos é inestimável quando um sistema tem de aceder a vários índices e tomar uma decisão com base na descrição. Considere um servidor MCP (Model Context Protocol) que deve escolher o índice correto em tempo de execução. A decisão pode basear-se na descrição e não apenas no nome do índice.

4. Identifique uma chave de documento. Uma chave de documento é um requisito de índice. É um único campo de cadeia de caracteres preenchido a partir de um campo de dados de origem que contém valores exclusivos. Por exemplo, se estiver a indexar a partir do Armazenamento de Blobs, o caminho de armazenamento de metadados é utilizado geralmente como a chave do documento, porque identifica exclusivamente cada blob no contentor.

5. Identifique os campos na origem de dados que contribuem 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 verboso (frases pequenas ou partes maiores), experimente diferentes analisadores para ver como o texto é atomizado.

   O conteúdo vetorial pesquisável pode ser imagens ou texto (em qualquer idioma) que existe como uma representação matemática. Você pode usar tipos de dados estreitos ou compactação de vetor para tornar os campos vetoriais menores.

   Os atributos definidos em campos, como retrievable ou filterable, determinam os comportamentos de pesquisa e a representação física do índice no serviço de pesquisa. Determinar como os campos devem ser atribuídos é um processo iterativo para muitos desenvolvedores. Para acelerar as iterações, comece com dados de exemplo para que possa excluir e reconstruir facilmente.

6. Identifique os campos de origem que podem ser utilizados como filtros. Conteúdo numérico e campos de texto curtos, particularmente aqueles com valores repetidos, são boas escolhas. Ao trabalhar com filtros, lembre-se do seguinte:

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

   • Opcionalmente, os campos filtráveis podem ser utilizados na navegação por facetas.

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

7. Para campos vetoriais, especifique uma configuração de pesquisa vetorial e os algoritmos usados para criar caminhos de navegação e preencher o espaço de incorporação. Para obter mais informações, consulte Adicionar campos vetoriais.

   Os campos vetoriais têm propriedades extras que os campos não vetoriais não têm, como quais algoritmos usar e compactação vetorial.

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

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

   Para cadeias multilíngues, considere um analisador de linguagem.

   Para cadeias hifenizadas ou de carateres especiais, considere analisadores especializados. Um exemplo é a palavra-chave que trata todo o conteúdo de um campo como um único token. Esse comportamento é útil para dados como códigos postais, IDs e alguns nomes de produtos. Para obter mais informações, veja Pesquisa parcial de termos e padrões com carateres especiais.

Configurar definições de campo

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

Definir um campo como pesquisável, filtrável, classificável ou facetable tem um efeito no tamanho do índice e no 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 para ser 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 baseada nos tipos de dados, que também é usada pelo assistente de Importação de dados no portal 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.

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

Os campos vetoriais devem ser associados a dimensões e perfis vetoriais. A opção Retrievable está ativada por defeito se o campo vetorial for adicionado usando o assistente Importar dados no portal Azure. Se você usar a API REST, ela é falsa.

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

Atualizações permitidas em índices existentes

Criar índice cria as estruturas de dados físicos (arquivos e índices invertidos) em seu serviço de pesquisa. Depois que o índice é criado, sua capacidade de efetuar alterações usando Criar ou Atualizar Índice depende se suas modificações invalidam 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 rotatividade no código do aplicativo, você pode criar um alias de índice que sirva como uma referência estável para o índice de pesquisa. Em vez de atualizar 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. A alteração de um elemento fixo requer uma reconstrução do índice, enquanto os elementos flexíveis podem ser alterados a qualquer momento sem afetar a implementação física. Para obter mais informações, consulte Atualizar ou reconstruir um índice.

Definir corsOptions para consultas de origem cruzada

Os esquemas de índice incluem uma seção para a configuração corsOptions. Por padrão, o JavaScript do lado do cliente não pode chamar nenhuma API porque os navegadores impedem todas as solicitações de origem cruzada. Para permitir consultas entre origens até o índice, habilite o CORS (Cross-Origin Resource Sharing) definindo o atributo corsOptions . Por motivos de segurança, apenas as APIs de consulta suportam CORS.

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

As seguintes propriedades podem ser definidas para CORS:

• allowedOrigins (obrigatório): Esta é uma lista de origens que têm acesso permitido ao seu índice. O código JavaScript servido a partir 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> muitas vezes seja omitida. Para obter mais informações, consulte Compartilhamento de recursos entre origens (Wikipedia).

  Se tu quiseres permitir o acesso a todas as origens, inclui * como um único item no vetor allowedOrigins. Essa não é uma prática recomendada para serviços de pesquisa de produção, mas geralmente é útil para desenvolvimento e depuração.

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

Próximos passos

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

• Adicionar campos vetoriais e perfis vetoriais
• Adicionar perfis de pontuação
• Adicionar classificação semântica
• Adicionar sugestões
• Adicionar mapas de sinónimos
• Adicionar analisadores
• Adicionar encriptação

Use estes links para carregar ou atualizar um índice:

• Descrição geral da importação de dados
• Carregar documentos
• Atualizar ou reconstruir um índice