Criar um índice na Pesquisa de IA do Azure
No Azure AI Search, as solicitações de consulta direcionam o texto pesquisável em um índice de pesquisa.
Neste artigo, aprenda as etapas para definir e publicar um índice de pesquisa. A criação de um índice estabelece as estruturas de dados físicos no seu serviço de pesquisa. Uma vez que a definição de índice existe, o carregamento do índice segue como uma tarefa separada.
Pré-requisitos
Permissões de gravação. A permissão pode ser concedida por meio de uma chave de API de administrador na solicitação. Como alternativa, se você estiver usando o controle de acesso baseado em função, envie uma solicitação como membro da função de Colaborador de Pesquisa.
Uma compreensão dos dados que você deseja indexar. Criar um índice é um exercício de definição de esquema, portanto, você deve ter uma ideia clara de quais campos de origem deseja tornar pesquisáveis, recuperáveis, filtráveis, compatíveis e classificáveis (consulte a lista de verificação de esquema para obter orientação).
Você também deve ter um campo exclusivo nos dados de origem que possa ser usado como a chave do documento (ou ID) no índice.
Uma localização de índice estável. Não há suporte imediato para mover um índice existente para um serviço de pesquisa diferente. Reveja os requisitos da aplicação e certifique-se de que o serviço de pesquisa existente, a sua capacidade e localização, são suficientes para as suas necessidades.
Finalmente, todas as camadas de serviço têm limites de índice para o número de objetos que você pode criar. Por exemplo, se você estiver experimentando no nível Gratuito, só poderá ter três índices a qualquer momento. Dentro do próprio índice, há limites para o número de campos e coleções complexas.
Chaves do documento
Um índice de pesquisa tem um campo obrigatório: uma chave de documento. Uma chave de documento é o identificador exclusivo de um documento de pesquisa. Na Pesquisa de IA do Azure, ela deve ser uma cadeia de caracteres e deve ser originada de valores exclusivos na fonte de dados que está fornecendo o conteúdo a ser indexado. 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.
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.
Lista de verificação do esquema
Use esta lista de verificação para ajudar nas decisões de design para seu índice de pesquisa.
Revise as convenções de nomenclatura para que os nomes de índice e campo estejam em conformidade com as regras de nomenclatura.
Analise os tipos de dados suportados. O tipo de dados afeta a forma como o campo é usado. 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.Stringpara texto pesquisável, que é tokenizado e consultado usando o mecanismo de pesquisa de texto completo.Identifique uma chave de documento. Uma chave de documento é um requisito de índice. É um único campo de cadeia de caracteres e é preenchido a partir de um campo de dados de origem que contém valores exclusivos. Por exemplo, se você estiver indexando a partir do Armazenamento de Blobs, o caminho de armazenamento de metadados geralmente é usado como a chave do documento porque identifica exclusivamente cada blob no contêiner.
Identifique os campos em sua fonte de dados que contribuem com conteúdo pesquisável no índice. O conteúdo 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 pedaços maiores), experimente diferentes analisadores para ver como o texto é tokenizado.
As atribuições de atributos de campo determinam os comportamentos de pesquisa e a representação física do seu índice no serviço de pesquisa. Determinar como os campos devem ser especificados é um processo iterativo para muitos clientes. Para acelerar iterações, comece com dados de exemplo para que você possa soltar e reconstruir facilmente.
Identifique quais campos de origem podem ser usados 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:
Opcionalmente, podem ser utilizados campos filtráveis na navegação facetada.
Os campos filtráveis são retornados em ordem arbitrária, portanto, considere torná-los classificáveis também.
Determine se o analisador padrão (
"analyzer": null) deve ser usado ou um analisador diferente. Os analisadores são usados para tokenizar campos de texto durante a indexação e a execução da consulta.Para strings multilíngues, considere um analisador de linguagem.
Para cadeias de caracteres hifenizadas ou caracteres 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, consulte Pesquisa parcial de termos e padrões com caracteres especiais.
Nota
A pesquisa de texto completo é realizada sobre termos que são tokenizados durante a indexação. Se suas consultas não retornarem os resultados esperados, teste a tokenização para verificar se a cadeia de caracteres realmente existe. Você pode tentar diferentes analisadores em strings para ver como os tokens são produzidos para vários analisadores.
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.
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.
O design de índice por meio do portal impõe requisitos e regras de esquema para tipos de dados específicos, como não permitir recursos de pesquisa de texto completo em campos numéricos.
Inicie sessão no portal do Azure.
Na página Visão geral do serviço de pesquisa, escolha uma das opções para criar um índice de pesquisa:
- Adicionar índice, um editor incorporado para especificar um esquema de índice
- Assistente de importação de dados
O assistente é um fluxo de trabalho de ponta a ponta que cria um indexador, uma fonte de dados e um índice concluído. Ele também carrega os dados. Se isso for mais do que o desejado, use Adicionar índice .
A captura de tela a seguir destaca onde Adicionar índice e Importar dados aparecem na barra de comandos. Depois que um índice é criado, você pode encontrá-lo novamente na guia Índices .
Gorjeta
Depois de criar um índice no portal, você pode copiar a representação JSON e adicioná-la ao código do aplicativo.
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 você quiser permitir o acesso a todas as origens, inclua
*como um único item na matriz 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 esse valor para determinar a duração (em segundos) para armazenar em cache as respostas de comprovação 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.
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 o Update Index depende 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.
Como alternativa, você pode criar um alias de índice que sirva como uma referência estável no código do aplicativo. Em vez de atualizar seu código, 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.
| Elemento | Pode ser atualizado? |
|---|---|
| Nome | Não |
| Chave | Não |
| Nomes e tipos de campos | Não |
| Atributos de campo (pesquisável, filtrável, facial, classificável) | Não |
| Atributo de campo (recuperável) | Sim |
| Analisador | Você pode adicionar e modificar analisadores personalizados no índice. Em relação às atribuições do analisador em campos de cadeia de caracteres, você só pode modificar searchAnalyzero . Todas as outras atribuições e modificações requerem uma reconstrução. |
| Perfis de classificação | Sim |
| Sugestões | Não |
| compartilhamento de recursos entre origens (CORS) | Sim |
| Encriptação | Sim |
Próximos passos
Use os links a seguir para se familiarizar com o carregamento de um índice com dados ou a extensão de um índice com um mapa de sinônimos.