Dicas para o enriquecimento de ia no Azure Pesquisa CognitivaTips for AI enrichment in Azure Cognitive Search

Este artigo contém uma lista de dicas e truques para manter você mudando à medida que começar a usar os recursos de enriquecimento de ia no Azure Pesquisa Cognitiva.This article contains a list of tips and tricks to keep you moving as you get started with AI enrichment capabilities in Azure Cognitive Search.

Se você ainda não fez isso, percorra o tutorial: saiba como chamar APIs de enriquecimento de ai para praticar na aplicação de aprimoramentos de ai a uma fonte de dados de BLOB.If you have not done so already, step through the Tutorial: Learn how to call AI enrichment APIs for practice in applying AI enrichments to a blob data source.

Dica 1: comece com um conjunto de dados pequenoTip 1: Start with a small dataset

A melhor maneira de encontrar problemas rapidamente é aumentar a velocidade com que você pode corrigi-los.The best way to find issues quickly is to increase the speed at which you can fix issues. A melhor maneira de reduzir o tempo de indexação é reduzindo o número de documentos a serem indexados.The best way to reduce the indexing time is by reducing the number of documents to be indexed.

Comece criando uma fonte de dados com apenas alguns registros/documentos.Start by creating a data source with just a handful of documents/records. O documento de amostra deve ser uma boa representação da variedade de documentos que serão indexados.Your document sample should be a good representation of the variety of documents that will be indexed.

Execute seu documento de amostra no pipeline de ponta a ponta e verifique se os resultados atendem às suas necessidades.Run your document sample through the end-to-end pipeline and check that the results meet your needs. Quando estiver satisfeito com os resultados, você poderá adicionar mais arquivos à sua fonte de dados.Once you are satisfied with the results, you can add more files to your data source.

Dica 2: verifique se as credenciais da fonte de dados estão corretasTip 2: Make sure your data source credentials are correct

A conexão da fonte de dados não é validada até que você defina um indexador que a utiliza.The data source connection is not validated until you define an indexer that uses it. Se encontrar erros indicando que o indexador não pode acessar os dados, verifique se:If you see any errors mentioning that the indexer cannot get to the data, make sure that:

  • Sua cadeia de conexão está correta.Your connection string is correct. Especialmente quando você estiver criando tokens SAS, certifique-se de usar o formato esperado pelo Azure Pesquisa Cognitiva.Specially when you are creating SAS tokens, make sure to use the format expected by Azure Cognitive Search. Consulte a seção Como especificar credenciais para saber mais sobre os diferentes formatos compatíveis.See How to specify credentials section to learn about the different formats supported.
  • O nome do contêiner no indexador está correto.Your container name in the indexer is correct.

Dica 3: veja o que funciona mesmo que haja algumas falhasTip 3: See what works even if there are some failures

Às vezes, uma pequena falha interrompe o funcionamento de um indexador.Sometimes a small failure stops an indexer in its tracks. Isso não é um problema se você planeja corrigir os problemas um a um.That is fine if you plan to fix issues one by one. No entanto, talvez você queira ignorar um determinado tipo de erro, permitindo que o indexador continue para que você possa ver quais fluxos estão funcionando.However, you might want to ignore a particular type of error, allowing the indexer to continue so that you can see what flows are actually working.

Nesse caso, convém orientar o indexador a ignorar erros.In that case, you may want to tell the indexer to ignore errors. Faça isso definindo maxFailedItems e maxFailedItemsPerBatch como -1 como parte da definição do indexador.Do that by setting maxFailedItems and maxFailedItemsPerBatch as -1 as part of the indexer definition.

{
  "// rest of your indexer definition
   "parameters":
   {
      "maxFailedItems":-1,
      "maxFailedItemsPerBatch":-1
   }
}

Observação

Como prática recomendada, defina maxFailedItems, maxFailedItemsPerBatch como 0 para cargas de trabalho de produçãoAs a best practice, set the maxFailedItems, maxFailedItemsPerBatch to 0 for production workloads

Dica 4: usar sessões de depuração para identificar e resolver problemas com seu qualificableTip 4: Use Debug sessions to identify and resolve issues with your skillset

As Sessões de depuração são um editor visual que funciona com um conjunto de habilidades existente no portal do Azure.Debug sessions is a visual editor that works with an existing skillset in the Azure portal. Em uma sessão de depuração, você pode identificar e resolver erros, validar alterações e confirmar alterações em um confirmante de produção no pipeline de enriquecimento de ia.Within a debug session you can identify and resolve errors, validate changes, and commit changes to a production skillset in the AI enrichment pipeline. Este é um recurso de visualização Leia a documentação.This is a preview feature read the documentation. Para obter mais informações sobre conceitos e introdução, consulte depurar sessões.For more information about concepts and getting started, see Debug sessions.

As sessões de depuração funcionam em um único documento são uma ótima maneira de Compilar iterativamente pipelines de enriquecimento mais complexos.Debug sessions work on a single document are a great way for you to iteratively build more complex enrichment pipelines.

Dica 5: examinando os documentos aprimorados nos bastidoresTip 5: Looking at enriched documents under the hood

Documentos enriquecidos são estruturas temporárias criadas durante enriquecimento e, em seguida, excluídos quando o processo é concluído.Enriched documents are temporary structures created during enrichment, and then deleted when processing is complete.

Para capturar um instantâneo do documento enriquecido criado durante a indexação, adicione um campo chamado enriched ao índice.To capture a snapshot of the enriched document created during indexing, add a field called enriched to your index. O indexador despeja automaticamente no campo uma representação de cadeia de caracteres de todos os enriquecimentos do documento.The indexer automatically dumps into the field a string representation of all the enrichments for that document.

O campo enriched conterá uma cadeia de caracteres que é uma representação lógica do documento enriquecido na memória em JSON.The enriched field will contain a string that is a logical representation of the in-memory enriched document in JSON. No entanto, o valor do campo é um documento JSON válido.The field value is a valid JSON document, however. As aspas são de escape, de modo que você precisará substituir \" por " para ver o documento como JSON formatado.Quotes are escaped so you'll need to replace \" with " in order to view the document as formatted JSON.

O campo enriquecido tem finalidade apenas de depuração, para ajudá-lo a entender a forma lógica do conteúdo no qual as expressões estão sendo avaliadas.The enriched field is intended for debugging purposes only, to help you understand the logical shape of the content that expressions are being evaluated against. Não dependa desse campo para fins de indexação.You should not depend on this field for indexing purposes.

Adicione um campo enriched como parte da definição do índice para fins de depuração:Add an enriched field as part of your index definition for debugging purposes:

Sintaxe de Corpo da SolicitaçãoRequest Body Syntax

{
  "fields": [
    // other fields go here.
    {
      "name": "enriched",
      "type": "Edm.String",
      "searchable": false,
      "sortable": false,
      "filterable": false,
      "facetable": false
    }
  ]
}

Dica 6: falha na exibição do conteúdo esperadoTip 6: Expected content fails to appear

A falta de conteúdo pode ser resultado da remoção de documentos durante a indexação.Missing content could be the result of documents getting dropped during indexing. As camadas Básica e Gratuita têm limites baixos de tamanho do documento.Free and Basic tiers have low limits on document size. Qualquer arquivo que ultrapassar o limite será removido durante a indexação.Any file exceeding the limit is dropped during indexing. Você pode verificar se há documentos removidos no portal do Azure.You can check for dropped documents in the Azure portal. No painel do serviço de pesquisa, clique duas vezes no bloco Indexadores.In the search service dashboard, double-click the Indexers tile. Examine a proporção de documentos indexados com êxito.Review the ratio of successful documents indexed. Se ela não for de 100%, você poderá clicar nela para obter mais detalhes.If it is not 100%, you can click the ratio to get more detail.

Se o problema estiver relacionado ao tamanho do arquivo, você poderá ver um erro como este: "o blob <file-name> " tem o tamanho de <file-size> bytes, que excede o tamanho máximo para extração de documentos para sua camada de serviço atual. "If the problem is related to file size, you might see an error like this: "The blob <file-name>" has the size of <file-size> bytes, which exceeds the maximum size for document extraction for your current service tier." Para obter mais informações sobre os limites de indexador, confira Limites de serviço.For more information on indexer limits, see Service limits.

Um segundo motivo para o conteúdo não aparecer pode ser a presença de erros de mapeamento de entrada/saída.A second reason for content failing to appear might be related input/output mapping errors. Por exemplo, o nome da saída de destino é "People", mas o nome do campo de índice é "people", com letras minúsculas.For example, an output target name is "People" but the index field name is lower-case "people". O sistema pode retornar mensagens de êxito 201 para todo o pipeline, o que levará você a achar que a indexação foi bem-sucedida, quando na verdade um campo está vazio.The system could return 201 success messages for the entire pipeline so you think indexing succeeded, when in fact a field is empty.

Dica 7: estender o processamento além do tempo de execução máximo (janela de 24 horas)Tip 7: Extend processing beyond maximum run time (24-hour window)

A análise de imagem faz uso intensivo de computação até mesmo em casos simples, de modo que quando as imagens são especialmente grandes ou complexas, os tempos de processamento podem ultrapassar o tempo máximo permitido.Image analysis is computationally-intensive for even simple cases, so when images are especially large or complex, processing times can exceed the maximum time allowed.

O tempo de execução máximo varia por camada: vários minutos na Camada gratuita, indexação de 24 horas nas camadas faturáveis.Maximum run time varies by tier: several minutes on the Free tier, 24-hour indexing on billable tiers. Se o processamento não for concluído em um período de 24 horas para o processamento sob demanda, use uma agenda para que o indexador retome o processamento de onde parou.If processing fails to complete within a 24-hour period for on-demand processing, switch to a schedule to have the indexer pick up processing where it left off.

Para indexadores agendados, a indexação é retomada de acordo com a agenda no último documento bem-sucedido.For scheduled indexers, indexing resumes on schedule at the last known good document. Com o uso de um agenda recorrente, o indexador pode percorrer a lista de pendências de imagem ao longo de várias horas ou vários dias, até que todas as imagens não processadas sejam processadas.By using a recurring schedule, the indexer can work its way through the image backlog over a series of hours or days, until all un-processed images are processed. Para obter mais informações sobre a sintaxe de agendamento, consulte agendar um indexador.For more information on schedule syntax, see Schedule an indexer.

Observação

Se um indexador for definido como um determinado agendamento, mas falhar repetidamente no mesmo documento repetidamente, sempre que for executado, o indexador começará a ser executado em um intervalo menos frequente (até o máximo de pelo menos uma vez a cada 24 horas) até que ele faça o progresso com êxito novamente.If an indexer is set to a certain schedule but repeatedly fails on the same document over and over again each time it runs, the indexer will begin running on a less frequent interval (up to the maximum of at least once every 24 hours) until it successfully makes progress again. Se acreditar que você corrigiu qualquer problema que estava fazendo com que o indexador fosse paralisado em um determinado ponto, você poderá executar uma execução sob demanda do indexador e, se isso fizer o progresso com êxito, o indexador retornará ao seu intervalo de agendamento definido novamente.If you believe you have fixed whatever the issue that was causing the indexer to be stuck at a certain point, you can perform an on demand run of the indexer, and if that successfully makes progress, the indexer will return to its set schedule interval again.

Para a indexação baseada em portal (conforme descrita no guia de início rápido), escolher a opção "Executar uma vez" do indexador limita o processamento a 1 hora ("maxRunTime": "PT1H").For portal-based indexing (as described in the quickstart), choosing the "run once" indexer option limits processing to 1 hour ("maxRunTime": "PT1H"). Você talvez queira estender a janela de processamento para um período mais longo.You might want to extend the processing window to something longer.

Dica 8: aumentar a taxa de transferência de indexaçãoTip 8: Increase indexing throughput

Para a indexação paralela, coloque os dados em vários contêineres ou várias pastas virtuais dentro do mesmo contêiner.For parallel indexing, place your data into multiple containers or multiple virtual folders inside the same container. Em seguida, crie vários pares de fonte de dados e indexador.Then create multiple data source and indexer pairs. Todos os indexadores podem usar o mesmo conjunto de habilidades e gravar no mesmo índice de pesquisa de destino, de modo que seu aplicativo de pesquisa não precisa estar ciente desse particionamento.All indexers can use the same skillset and write into the same target search index, so your search app doesn’t need to be aware of this partitioning.

Veja tambémSee also