Solução de problemas de erros e avisos comuns do indexador no Azure AI Search

Este artigo fornece informações e soluções para erros e avisos comuns que você pode encontrar durante a indexação e o enriquecimento de IA no Azure AI Search.

A indexação é interrompida quando a contagem de erros excede 'maxFailedItems'.

Se você quiser que os indexadores ignorem esses erros (e ignorem "documentos com falha"), considere atualizar o maxFailedItems e maxFailedItemsPerBatch conforme descrito aqui.

As informações de erro neste artigo podem ajudá-lo a resolver erros, permitindo que a indexação continue.

Os avisos não param de indexar, mas indicam condições que podem resultar em resultados inesperados. A decisão de agir ou não agir depende dos dados e do seu cenário.

Onde você pode encontrar erros específicos do indexador?

Para verificar o status de um indexador e identificar erros no portal do Azure, siga as etapas abaixo:

1. Entre no portal do Azure e localize seu serviço de pesquisa.

2. À esquerda, expanda Gerenciamento de Pesquisa>Indexadores e selecione um indexador.

3. Em Histórico de Execução, selecione o status. Todos os status, incluindo Êxito, têm detalhes sobre a execução.

4. Se houver um erro, passe o mouse sobre a mensagem de erro. Um painel aparece no lado direito da tela exibindo informações detalhadas sobre o erro.

Erros transitórios

Por vários motivos, como interrupções transitórias de comunicação de rede, tempos limite de processos de longa execução ou nuances de documentos específicos, é comum encontrar erros transitórios ou avisos durante as execuções do indexador. No entanto, esses erros são temporários e devem ser resolvidos em execuções subsequentes do indexador.

Para gerenciar esses erros efetivamente, recomendamos colocar o indexador em um agendamento, por exemplo, para ser executado a cada cinco minutos, em que a próxima execução começa cinco minutos depois de concluir a primeira execução, aderindo ao limite máximo de runtime em seu serviço. Execuções agendadas regularmente ajudam a corrigir erros ou avisos transitórios.

Se um erro persistir em várias execuções de indexador, provavelmente não será um problema transitório. Nesses casos, consulte a lista abaixo para possíveis soluções.

Propriedades de erro

Error: Could not read document

O indexador não pôde ler o documento da fonte de dados. Isso pode ocorrer devido a:

Error: Could not extract content or metadata from your document

O indexador com uma fonte de dados blob não pôde extrair o conteúdo ou os metadados do documento (por exemplo, um arquivo PDF). Isso pode ocorrer devido a:

Error: Could not parse document

O indexador leu o documento da fonte de dados, mas houve um problema ao converter o conteúdo do documento no esquema de mapeamento de campo especificado. Isso pode ocorrer devido a:

Error: Could not map output field 'xyz' to search index due to deserialization problem while applying mapping function 'abc'

O mapeamento de saída pode ter falhado porque os dados de saída estão no formato errado para a função de mapeamento que você está usando. Por exemplo, aplicar a função de Base64Encode mapeamento em dados binários geraria esse erro. Para resolver o problema, execute novamente o indexador sem especificar a função de mapeamento ou verifique se a função de mapeamento é compatível com o tipo de dados do campo de saída. Consulte o mapeamento de campo de saída para obter detalhes.

Error: Could not execute skill

O indexador não pôde executar uma habilidade no conjunto de habilidades.

Error: Could not execute skill because the Web API request failed

A execução da habilidade falhou porque a chamada à API Web falhou. Normalmente, essa classe de falha ocorre quando habilidades personalizadas são usadas, nesse caso, você precisa depurar seu código personalizado para resolver o problema. Se, em vez disso, a falha for de uma habilidade interna, consulte a mensagem de erro para obter ajuda para corrigir o problema.

Ao depurar esse problema, preste atenção aos avisos de entrada de habilidade para essa habilidade. O ponto de extremidade da API Web pode estar falhando porque o indexador está passando por uma entrada inesperada.

Error: Could not execute skill because Web API skill response is invalid

A execução da habilidade falhou porque a chamada à API Web retornou uma resposta inválida. Normalmente, essa classe de falha ocorre quando habilidades personalizadas são usadas, nesse caso, você precisa depurar seu código personalizado para resolver o problema. Se, em vez disso, a falha for de uma habilidade interna, registre um tíquete de suporte para obter assistência.

Error: Type of value has a mismatch with column type. Couldn't store in 'xyz' column. Expected type is 'abc'

Se a fonte de dados tiver um campo com um tipo de dados diferente do campo que você está tentando mapear em seu índice, você poderá encontrar esse erro. Verifique os tipos de dados do campo da fonte de dados e verifique se eles estão mapeados corretamente para os tipos de dados de índice.

Error: Skill did not execute within the time limit

Há dois casos nos quais você pode encontrar essa mensagem de erro, cada um deles deve ser tratado de forma diferente. Siga as instruções abaixo, dependendo de qual habilidade retornou esse erro para você.

Habilidades internas das Foundry Tools

Muitas das habilidades cognitivas internas, como detecção de idioma, reconhecimento de entidade ou OCR, são suportadas por um endpoint da API das Ferramentas Foundry. Às vezes, há problemas transitórios com esses pontos de extremidade e uma solicitação vai acabar. Para problemas transitórios, não há nenhum remédio a não ser esperar e tentar novamente. Para reduzir o problema, a indexação deve ser agendada. A indexação agendada continua de onde parou. Supondo que problemas transitórios sejam resolvidos, a indexação e o processamento de habilidades cognitivas devem ser capazes de continuar na próxima execução agendada.

Se você continuar a ver esse erro no mesmo documento para uma habilidade cognitiva interna, registre um tíquete de suporte para obter assistência, pois isso não é esperado.

Habilidades personalizadas

Se houver um erro de tempo limite com uma habilidade personalizada, tente tomar uma das medidas abaixo. Primeiro, examine sua habilidade personalizada e verifique se ela não está ficando presa em um loop infinito e que ela está retornando um resultado de forma consistente. Depois de confirmar que um resultado foi retornado, verifique a duração da execução. Se você não definiu explicitamente um timeout valor em sua definição de habilidade personalizada, o padrão timeout é 30 segundos. Se 30 segundos não forem longos o suficiente para sua habilidade ser executada, você poderá especificar um valor mais alto timeout em sua definição de habilidade personalizada. Aqui está um exemplo de uma definição de habilidade personalizada em que o tempo limite é definido como 90 segundos:

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "uri": "<your custom skill uri>",
        "batchSize": 1,
        "timeout": "PT90S",
        "context": "/document",
        "inputs": [
          {
            "name": "input",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "output",
            "targetName": "output"
          }
        ]
      }

O valor máximo que você pode definir para o timeout parâmetro é 230 segundos. Se sua habilidade personalizada não puder ser executada consistentemente em até 230 segundos, você poderá considerar reduzir batchSize da sua habilidade personalizada de modo que tenha menos documentos a serem processados em uma única execução. Se você já tiver definido o seu batchSize como 1, precisará reescrever a habilidade para ser capaz de executar em menos de 230 segundos ou dividi-la em várias habilidades personalizadas para que o tempo de execução de qualquer habilidade personalizada seja de no máximo 230 segundos. Examine a documentação de habilidades personalizadas para obter mais informações.

Error: Could not 'MergeOrUpload' | 'Delete' document to the search index

O documento foi lido e processado, mas o indexador não pôde adicioná-lo ao índice de pesquisa. Isso pode ocorrer devido a:

Error: Could not index document because some of the document's data was not valid

O documento foi lido e processado pelo indexador, mas devido a uma incompatibilidade na configuração dos campos de índice e dos dados extraídos e processados pelo indexador, ele não pôde ser adicionado ao índice de pesquisa. Isso pode ocorrer devido a:

Em todos esses casos, consulte os tipos de dados compatíveis e o mapa de tipos de dados para indexadores para garantir que você crie o esquema de índice corretamente e configure os mapeamentos de campo do indexador apropriados. A mensagem de erro inclui detalhes que podem ajudar a rastrear a origem da incompatibilidade.

Error: Integrated change tracking policy cannot be used because table has a composite primary key

Isso se aplica a tabelas SQL e geralmente acontece quando a chave é definida como uma chave composta ou, quando a tabela define um índice clusterizado exclusivo (como em um índice SQL, não um índice do Azure Search). O principal motivo é que o atributo de chave é modificado para ser uma chave primária composta em um índice clusterizado exclusivo. Nesse caso, certifique-se de que sua tabela SQL não tenha um índice clusterizado exclusivo ou que você mapeie o campo de chave para um campo que tem a garantia de não ter valores duplicados.

Error: Could not process document within indexer max run time

Esse erro ocorre quando o indexador não consegue concluir o processamento de um único documento da fonte de dados dentro do tempo de execução permitido. O tempo máximo de execução é menor quando os conjuntos de habilidades são usados. Quando esse erro ocorre, se você tiver maxFailedItems definido como um valor diferente de 0, o indexador ignorará o documento em execuções futuras para que a indexação possa progredir. Se você não puder se dar ao luxo de ignorar nenhum documento ou se estiver vendo esse erro de forma consistente, considere dividir documentos em documentos menores para que o progresso parcial possa ser feito dentro de uma única execução do indexador.

Error: Could not project document

Esse erro ocorre quando o indexador está tentando projetar dados em um repositório de conhecimento e houve uma falha na tentativa. Essa falha pode ser consistente e corrigível, ou uma falha transitória com o coletor de saída de projeção, e talvez seja necessário aguardar e tentar novamente para resolver. Aqui está um conjunto de estados de falha conhecidos e possíveis resoluções.

Error: The cognitive service for skill '<skill-name>' has been throttled

A execução da habilidade falhou porque a chamada para as Foundry Tools foi limitada. Normalmente, essa classe de falha ocorre quando muitas habilidades estão sendo executadas em paralelo. Se você estiver usando a biblioteca de clientes Microsoft.Search.Documents para executar o indexador, poderá usar o SearchIndexingBufferedSender para tentar novamente automaticamente em etapas com falha. Caso contrário, você poderá redefinir e executar novamente o indexador.

Error: Expected IndexAction metadata

Um erro "Metadados esperados do IndexAction" significa que quando o indexador tentou ler o documento para identificar qual ação deve ser tomada, ele não encontrou nenhum metadado correspondente no documento. Normalmente, esse erro ocorre quando o indexador tem um cache de anotação adicionado ou removido sem redefinir o indexador. Para resolver isso, você deve redefinir e executar novamente o indexador.

Warning: Skill input was invalid

Uma entrada para a habilidade estava ausente, tem o tipo errado ou é, de alguma forma, inválida. Você pode ver as seguintes informações:

• Could not execute skill

• Skill executed but may have unexpected results

As habilidades cognitivas têm entradas necessárias e entradas opcionais. Por exemplo, a habilidade de extração de frases-chave tem duas entradas necessárias textlanguageCodee nenhuma entrada opcional. Todas as entradas personalizadas de habilidades são consideradas opcionais.

Se as entradas necessárias estiverem ausentes ou se a entrada não for o tipo certo, a habilidade será ignorada e gerará um aviso. As habilidades ignoradas não geram saídas. Se as habilidades downstream consumirem as saídas da habilidade ignorada, elas poderão gerar outros avisos.

Se uma entrada opcional estiver ausente, a habilidade ainda será executada, mas poderá produzir uma saída inesperada devido à entrada ausente.

Em ambos os casos, esse aviso é devido ao formato dos seus dados. Por exemplo, se você tiver um documento contendo informações sobre pessoas com os campos firstNamemiddleNameelastName, talvez, tenha alguns documentos que não tenham uma entrada para middleName. Se você transmitir middleName como uma entrada para uma habilidade no pipeline, espera-se que essa entrada de habilidade esteja ausente durante algum tempo. Você precisa avaliar seus dados e cenário para determinar se qualquer ação é necessária ou não como resultado desse aviso.

Se você quiser fornecer um valor padrão para uma entrada ausente, poderá usar a habilidade condicional para gerar um valor padrão e, em seguida, usar a saída da habilidade condicional como entrada de habilidade.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'en'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

Warning: Skill input 'languageCode' has the following language codes 'X,Y,Z', at least one of which is invalid.

Não há suporte para um ou mais valores transmitidos para a entrada languageCode opcional de uma habilidade de downstream. Isso pode ocorrer se você estiver transmitindo a saída do LanguageDetectionSkill para as habilidades subsequentes, e a saída consistir em mais idiomas do que o suportado nessas habilidades de downstream.

Observe que você também pode obter um aviso semelhante a este se uma entrada inválida countryHint for passada para o LanguageDetectionSkill. Se isso acontecer, valide se o campo que você está usando da fonte de dados para essa entrada contém códigos de país de duas letras iso 3166-1 alfa-2 válidos. Se alguns forem válidos e outros inválidos, continue com as diretrizes a seguir, mas substitua languageCode por countryHint e defaultLanguageCode por defaultCountryHint para corresponder ao seu caso de uso.

Se você souber que seu conjunto de dados está tudo em um idioma, remova o LanguageDetectionSkill e a languageCode entrada de habilidade e use o defaultLanguageCode parâmetro de habilidade para essa habilidade, supondo que o idioma tenha suporte para essa habilidade.

Se você sabe que seu conjunto de dados contém vários idiomas e, portanto, precisa da entrada LanguageDetectionSkill e languageCode, considere adicionar uma ConditionalSkill para filtrar o texto com idiomas que não têm suporte antes de passar o texto para a habilidade downstream. Aqui está um exemplo de como isso pode ser para o EntityRecognitionSkill:

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'de' || $(/document/language) == 'en' || $(/document/language) == 'es' || $(/document/language) == 'fr' || $(/document/language) == 'it'" },
        { "name": "whenTrue", "source": "/document/content" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "supportedByEntityRecognitionSkill" } ]
}

Aqui estão algumas referências para os idiomas com suporte no momento para cada uma das habilidades que podem produzir esta mensagem de erro:

• Idiomas compatíveis com EntityRecognitionSkill
• Idiomas compatíveis com EntityLinkingSkill
• Idiomas compatíveis com KeyPhraseExtractionSkill
• Idiomas compatíveis com LanguageDetectionSkill
• Idiomas compatíveis com PIIDetectionSkill
• Idiomas compatíveis com SentimentSkill
• Idiomas compatíveis com o tradutor
• Idiomas com suporte para SplitSkill de texto:da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

As habilidades cognitivas limitam o comprimento do texto que pode ser analisado ao mesmo tempo. Se a entrada de texto exceder o limite, o texto será truncado antes de ser enriquecido. A habilidade é executada, mas não sobre todos os dados.

No exemplo LanguageDetectionSkill abaixo, o 'text' campo de entrada poderá disparar esse aviso se a entrada estiver acima do limite de caracteres. Os limites de entrada podem ser encontrados na documentação de referência de habilidades.

 {
    "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
    "inputs": [
      {
        "name": "text",
        "source": "/document/text"
      }
    ],
    "outputs": [...]
  }

Se você quiser garantir que todo o texto seja analisado, considere usar a habilidade Dividir.

Warning: Web API skill response contains warnings

O indexador executou a habilidade no conjunto de habilidades, mas a resposta da solicitação da API da Web indica que há avisos. Examine os avisos para entender como seus dados são afetados e se novas ações são necessárias.

Warning: The current indexer configuration does not support incremental progress

Esse aviso ocorre apenas para fontes de dados do Azure Cosmos DB.

O progresso incremental durante a indexação garante que, se a execução do indexador for interrompida por falhas transitórias ou um limite de tempo de execução, o indexador poderá continuar de onde parou na próxima vez que for executado, em vez de ter que reindexar toda a coleção do zero. Isso é especialmente importante ao indexar grandes coleções.

A capacidade de retomar um trabalho de indexação inacabada baseia-se em ter documentos ordenados pela _ts coluna. O indexador usa o carimbo de data/hora para determinar qual documento deve ser selecionado em seguida. Se a _ts coluna estiver ausente ou se o indexador não puder determinar se uma consulta personalizada é ordenada por ela, o indexador começa no início e você verá esse aviso.

É possível substituir esse comportamento, habilitando o progresso incremental e suprimindo esse aviso usando a assumeOrderByHighWaterMarkColumn propriedade de configuração.

Para obter mais informações, consulte progresso incremental e consultas personalizadas.

Warning: Some data was lost during projection. Row 'X' in table 'Y' has string property 'Z' which was too long.

O serviço Armazenamento de Tabelas tem limites de quão grandes propriedades de entidade podem ser. Cadeias de caracteres podem ter 32.000 caracteres ou menos. Se uma linha com uma propriedade de cadeia de caracteres com mais de 32.000 caracteres estiver sendo projetada, somente os primeiros 32.000 caracteres serão preservados. Para contornar esse problema, evite projetar linhas com propriedades de strings com mais de 32.000 caracteres.

Warning: Truncated extracted text to X characters

Os indexadores limitam a quantidade de texto que pode ser extraída de qualquer documento. Esse limite depende do tipo de preço: 32.000 caracteres para a camada Gratuita, 64.000 para Basic, 4 milhões para Standard, 8 milhões para Standard S2 e 16 milhões para Standard S3. O texto truncado não será indexado. Para evitar esse aviso, tente separar documentos com grandes quantidades de texto em vários documentos menores.

Para obter mais informações, consulte os limites do Indexador.

Warning: Could not map output field 'X' to search index

Mapeamentos de campo de saída que fazem referência a dados inexistentes/nulos produzirão avisos para cada documento e resultarão em um campo de índice vazio. Para contornar esse problema, verifique novamente os caminhos de origem de mapeamento de campo de saída para possíveis erros de digitação ou defina um valor padrão usando a habilidade condicional. Consulte o mapeamento de campo de saída para obter detalhes.

Warning: The data change detection policy is configured to use key column 'X'

As políticas de detecção de alteração de dados têm requisitos específicos para as colunas que usam para detectar alterações. Um desses requisitos é que essa coluna seja atualizada sempre que o item de origem for alterado. Outro requisito é que o novo valor dessa coluna seja maior que o valor anterior. As colunas de chave não atendem a esse requisito porque não são alteradas em todas as atualizações. Para contornar esse problema, selecione uma coluna diferente para a política de detecção de alterações.

Warning: Document text appears to be UTF-16 encoded, but is missing a byte order mark

Os modos de análise do indexador precisam saber como o texto é codificado antes de analisá-lo. As duas maneiras mais comuns de codificar texto são UTF-16 e UTF-8. UTF-8 é uma codificação de comprimento variável em que cada caractere tem entre 1 byte e 4 bytes de comprimento. UTF-16 é uma codificação de comprimento fixo em que cada caractere tem 2 bytes de comprimento. UTF-16 tem duas variantes big endian diferentes e little endian. A codificação do texto é determinada por um byte order mark, uma série de bytes antes do texto.

Se nenhuma marca de ordem de byte estiver presente, o texto será considerado codificado como UTF-8.

Para contornar esse aviso, determine qual é a codificação de texto para esse blob e adicione a marca de ordem de bytes apropriada.

Warning: Azure Cosmos DB collection 'X' has a Lazy indexing policy. Some data may be lost

Coleções com políticas de indexação lentas não podem ser consultadas consistentemente, resultando em dados ausentes do indexador. Para contornar esse aviso, altere sua política de indexação para Consistente.

Warning: The document contains very long words (longer than 64 characters). These words may result in truncated and/or unreliable model predictions.

Este aviso é passado pelo serviço de linguagem das Foundry Tools. Em alguns casos, é seguro ignorar esse aviso, por exemplo, se a cadeia de caracteres longa for apenas uma URL longa. Lembre-se de que quando uma palavra tem mais de 64 caracteres, ela é truncada para 64 caracteres, o que pode afetar previsões de modelo.

Error: Cannot write more bytes to the buffer than the configured maximum buffer size

Os indexadores têm limites de tamanho de documento. Verifique se os documentos na fonte de dados são menores que o limite de tamanho suportado, conforme documentado para o seu nível de serviço.

Error: Failed to compare value 'X' of type M to value 'Y' of type N.

Esse erro geralmente ocorre em indexadores SQL do Azure quando o tipo de coluna de origem usado dataChangeDetectionPolicy não corresponde ao que o indexador espera, especialmente se convertHighWaterMarkToRowVersion estiver ativado.

Por exemplo, se a coluna usada para detecção de alterações for do tipo datetime, mas o indexador espera um tipo rowversion porque convertHighWaterMarkToRowVersion está habilitado, essa incompatibilidade causará um erro.

Verifique o tipo de dados para a coluna 'High Water Mark' na fonte e atualize a configuração do indexador adequadamente. Depois de verificado e atualizado, redefina e execute novamente o indexador para processar os valores da coluna.

Error: Access denied to Virtual Network/Firewall rules.

Esse erro normalmente ocorre devido a um dos seguintes:

• Restrições de firewall nos recursos do Azure exigidos pelo indexador, dependendo da configuração. Esses recursos podem incluir: a fonte de dados, a conta de Armazenamento do Azure (usada para sessões de depuração, enriquecimento incremental ou repositório de conhecimento), a Função do Azure (usada para habilidades personalizadas da API Web) ou as implantações do Microsoft Foundry usadas durante o enriquecimento de IA.
• Configurações de ponto de extremidade privado que bloqueiam o acesso do indexador a esses recursos.

Verifique se o indexador tem acesso aos componentes de instalação examinando as configurações de recursos para confirmar se eles permitem o tráfego para todos os serviços necessários:

• Configurações de restrição de IP e firewall
• Configuração de link privado compartilhado

Error: Credentials provided in the connection string are invalid or have expired.

Esse erro ocorre quando o indexador do Azure AI Search não pode se autenticar usando a cadeia de conexão fornecida ou tem problemas ao acessar a conta de armazenamento para verificar as credenciais.