Resolução de erros e avisos comuns de indexadores no Pesquisa de IA do Azure

Este artigo fornece informações e soluções para erros e avisos comuns que possa encontrar durante a indexação e o enriquecimento de IA no Pesquisa de IA do Azure.

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

Se quiser que os indexadores ignorem estes erros (e saltem "documentos falhados"), considere atualizar o maxFailedItems e maxFailedItemsPerBatch conforme descrito aqui.

A informação sobre erros neste artigo pode 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. Se agirás ou não depende dos dados e do teu cenário.

Onde pode encontrar erros específicos do indexador?

Para verificar o estado de um indexador e identificar erros:

1. Vá ao seu serviço de pesquisa no portal Azure.

2. À esquerda, expanda Gestão de Pesquisa>Indexadores e selecione um indexador.

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

4. Se houver um erro, passe o rato sobre a mensagem de erro. Um painel aparece no lado direito do ecrã a mostrar informações detalhadas sobre o erro.

Erros transitórios

Por várias razões, como interrupções transitórias na comunicação da rede, timeouts de processos de longa duração ou nuances específicas de documentos, é comum encontrar erros transitórios ou avisos durante execuções do indexador. No entanto, estes erros são temporários e devem ser resolvidos em execuções subsequentes do indexador.

Para gerir estes erros de forma eficaz, recomendamos que coloque o seu indexador num calendário, por exemplo, para correr a cada cinco minutos, onde a próxima corrida começa cinco minutos após concluir a primeira, respeitando o limite máximo de tempo de execução do seu serviço. Execuções programadas regularmente ajudam a corrigir erros ou avisos transitórios.

Se um erro persistir em várias execuções de indexadores, provavelmente não é 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 conseguiu ler o documento da fonte de dados. Isto pode acontecer devido a:

Error: Could not extract content or metadata from your document

O indexador com uma fonte de dados Blob não conseguia extrair o conteúdo ou metadados do documento (por exemplo, um ficheiro PDF). Isto pode acontecer devido a:

Error: Could not parse document

O indexador leu o documento a partir da fonte de dados, mas houve um problema ao converter o conteúdo do documento para o esquema de mapeamento de campos especificado. Isto pode acontecer 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 estás a usar. Por exemplo, aplicar Base64Encode uma função de mapeamento em dados binários geraria este erro. Para resolver o problema, reexecute o indexador sem especificar a função de mapeamento ou garanta que a função de mapeamento seja compatível com o tipo de dados do campo de saída. Consulte Mapeamento de campo de saída para detalhes.

Error: Could not execute skill

O indexador não foi capaz 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 à Web API falhou. Normalmente, este tipo de falha ocorre quando são usadas competências personalizadas, caso em que é necessário depurar o seu código personalizado para resolver o problema. Se, em vez disso, a falha for causada por uma competência incorporada, consulte a mensagem de erro para obter ajuda a corrigir o problema.

Ao depurar este problema, certifique-se de prestar atenção a quaisquer alertas de entrada de competência para esta competência. O endpoint da tua Web API pode estar a falhar porque o indexador lhe está a passar uma entrada inesperada.

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

A execução da skill falhou porque a chamada à Web API devolveu uma resposta inválida. Normalmente, este tipo de falha ocorre quando são usadas competências personalizadas, caso em que é necessário depurar o seu código personalizado para resolver o problema. Se, em vez disso, a falha for causada por uma competência incorporada, abre um pedido 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 sua fonte de dados tiver um campo com um tipo de dado diferente do campo que está a tentar mapear no seu índice, pode encontrar este erro. Verifique os tipos de dados do campo da sua fonte de dados e certifique-se de que estão corretamente mapeados para os tipos de dados do seu índice.

Error: Skill did not execute within the time limit

Existem dois casos em que pode encontrar esta mensagem de erro, cada um dos quais deve ser tratado de forma diferente. Siga as instruções abaixo dependendo da habilidade que devolveu este erro para si.

Competências integradas nas Ferramentas de Fundição

Muitas das competências cognitivas incorporadas, como deteção de linguagem, reconhecimento de entidades ou OCR, são apoiadas por um endpoint da API das Foundry Tools. Por vezes, há problemas transitórios com estes endpoints e um pedido expira. Para questões transitórias, não há solução além de esperar e tentar novamente. Como medida de mitigação, considere definir o seu indexador para correr num calendário. A indexação programada continua de onde parou. Assumindo que os problemas transitórios são resolvidos, a indexação e o processamento de competências cognitivas poderão continuar na próxima execução agendada.

Se continuares a ver este erro no mesmo documento para uma competência cognitiva incorporada, abre um ticket de suporte para obter assistência, pois isso não é esperado.

Competências personalizadas

Se encontrares um erro de timeout numa skill personalizada, há algumas coisas que podes tentar. Primeiro, revê a tua habilidade personalizada e certifica-te de que não fica presa num ciclo infinito e que está a devolver um resultado de forma consistente. Depois de confirmar que um resultado foi devolvido, verifique a duração da execução. Se não definiste explicitamente um timeout valor na definição da tua habilidade personalizada, então o padrão timeout é 30 segundos. Se 30 segundos não forem tempo suficiente para a tua habilidade executar, podes especificar um valor maior timeout na definição da tua habilidade personalizada. Aqui está um exemplo de uma definição personalizada de habilidade onde o timeout é definido para 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 podes definir para o timeout parâmetro é 230 segundos. Se a sua habilidade personalizada não conseguir ser executada de forma consistente em 230 segundos, pode considerar reduzir batchSize a sua habilidade personalizada para que tenha menos documentos para processar numa única execução. Se já definiu a sua batchSize para 1, precisa de reescrever a habilidade para conseguir executar em menos de 230 segundos, ou então dividi-la em múltiplas habilidades personalizadas para que o tempo de execução de qualquer habilidade individual seja no máximo 230 segundos. Consulte a documentação de competências personalizadas para mais informações.

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

O documento foi lido e processado, mas o indexador não conseguiu adicioná-lo ao índice de pesquisa. Isto pode acontecer devido a:

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

O documento era lido e processado pelo indexador, mas devido a uma incompatibilidade na configuração dos campos do índice e dos dados extraídos e processados pelo indexador, não podia ser adicionado ao índice de pesquisa. Isto pode acontecer devido a:

Em todos estes casos, consulte Tipos de Dados Suportados e Mapa de Tipos de Dados para indexadores para garantir que constrói corretamente o esquema do índice e configurou os mapeamentos adequados dos campos do indexador. A mensagem de erro inclui detalhes que podem ajudar a identificar a origem da incompatibilidade.

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

Isto aplica-se a tabelas SQL e geralmente acontece quando a chave está definida como chave composta ou quando a tabela definiu um único índice agrupado (como num índice SQL, não num índice Azure Search). A principal razão é que o atributo chave é modificado para ser uma chave primária composta num único índice agrupado. Nesse caso, certifique-se de que a sua tabela SQL não tem um índice cluster único, ou que mapeia o campo chave para um campo que garantisse que não tenha valores duplicados.

Error: Could not process document within indexer max run time

Este erro ocorre quando o indexador não consegue terminar o processamento de um único documento da fonte de dados dentro do tempo de execução permitido. O tempo máximo de execução é mais curto quando se usam conjuntos de habilidades. Quando este erro ocorre, se tiver o maxFailedItems definido para um valor diferente de 0, o indexador contorna o documento em execuções futuras para que a indexação possa progredir. Se não puder saltar nenhum documento, ou se estiver a ver este erro de forma consistente, considere dividir documentos em documentos mais pequenos para que se possa fazer progresso parcial numa única execução do indexador.

Error: Could not project document

Este erro ocorre quando o indexador tenta projetar dados num armazenamento de conhecimento e houve uma falha na tentativa. Esta falha pode ser consistente e solucionável, ou pode ser uma falha transitória com o sumidouro de saída de projeção que poderá ter de esperar 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 skill não teve sucesso porque a chamada para a Foundry Tools foi controlada. Normalmente, esta classe de falhas ocorre quando demasiadas competências são executadas em paralelo. Se estiver a usar a biblioteca de cliente Microsoft.Search.Documents para executar o indexador, pode usar o SearchIndexingBufferedSender para obter uma repetição automática em passos falhados. Caso contrário, pode reiniciar e voltar a executar o indexador.

Error: Expected IndexAction metadata

Um erro de 'Metadados de Indexação Esperados' significa que, quando o indexador tentou ler o documento para identificar qual ação deve ser tomada, não encontrou quaisquer metadados correspondentes no documento. Normalmente, este erro ocorre quando o indexador tem uma cache de anotações adicionada ou removida sem reiniciar o indexador. Para resolver isto, deves reiniciar e voltar a executar o indexador.

Warning: Skill input was invalid

Faltava uma entrada para a habilidade, tinha o tipo errado ou, de outra forma, era inválida. Pode ver a seguinte informação:

• Could not execute skill

• Skill executed but may have unexpected results

As competências cognitivas têm inputs necessários e opcionais. Por exemplo, a habilidade de extração de palavras-chave tem duas entradas textobrigatórias , languageCode, e nenhuma entrada opcional. Entradas de habilidades personalizadas são todas consideradas opcionais.

Se faltarem entradas necessárias ou se a entrada não for do tipo correto, a habilidade é ignorada e gera um aviso. As competências ignoradas não geram resultados. Se as habilidades subsequentes consumirem os resultados da habilidade ignorada, poderão gerar outros avisos.

Se falta uma entrada opcional, a habilidade continua a correr, mas pode produzir uma saída inesperada devido à ausência da entrada.

Em ambos os casos, este aviso deve-se à forma dos seus dados. Por exemplo, se tiver um documento contendo informações sobre pessoas com os campos firstName, , e middleName, pode ter alguns documentos que não têm uma entrada para lastNamemiddleName. Se passares middleName como input para uma skill no pipeline, espera-se que essa entrada de skill esteja em falta por vezes. Precisa de avaliar os seus dados e cenário para determinar se é necessária alguma ação em decorrência deste aviso.

Se quiseres fornecer um valor predefinido para uma entrada em falta, podes usar a habilidade Condicional para gerar um valor predefinido e depois usar a saída da habilidade Condicional como entrada da 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.

Um ou mais dos valores passados para a entrada opcional languageCode de uma habilidade a jusante não são suportados. Isto pode acontecer se estiver a passar a saída da LanguageDetectionSkill para competências subsequentes, e a saída consiste em mais linguagens do que as suportadas nessas competências posteriores.

Note que também pode receber um aviso semelhante caso uma entrada inválida countryHint seja enviada para o LanguageDetectionSkill. Se isso acontecer, valide que o campo que está a usar da sua fonte de dados para essa entrada contém códigos de país válidos ISO 3166-1 alpha-2 de duas letras. Se algumas forem válidas e outras inválidas, continue com as seguintes orientações mas substitua languageCode por countryHint e defaultLanguageCode por defaultCountryHint para corresponder ao seu caso de uso.

Se souber que o seu conjunto de dados está todo numa única língua, deve remover o LanguageDetectionSkill e a languageCode entrada da skill e usar o defaultLanguageCode parâmetro da skill, assumindo que a língua é suportada para essa skill.

Se souber que o seu conjunto de dados contém várias línguas e, por isso, precisa da LanguageDetectionSkill e do languageCode input, considere adicionar uma ConditionalSkill para filtrar o texto em línguas não suportadas antes de passar o texto para a skill posterior. Aqui está um exemplo de como isto pode ser para a EntidadRecognitionSkill:

{
    "@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 das linguagens atualmente suportadas para cada uma das competências que podem produzir esta mensagem de erro:

• Linguagens suportadas pela EntityRecognitionSkill
• Linguagens suportadas pela EntityLinkingSkill
• Linguagens suportadas por KeyPhraseExtractionSkill
• Linguagens suportadas pelo LanguageDetectionSkill
• Linguagens suportadas por PIIDetectionSkill
• Linguagens suportadas pela SentimentSkill
• Linguagens suportadas por tradutor
• Linguagens suportadas pelo Text SplitSkills : da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

As competências cognitivas limitam o comprimento do texto que pode ser analisado de uma só vez. Se a entrada de texto ultrapassar o limite, o texto é truncado antes de ser enriquecido. A capacidade executa, mas não sobre todos os seus dados.

No exemplo LanguageDetectionSkill abaixo, o 'text' campo de entrada pode disparar este aviso se a entrada ultrapassar o limite de caracteres. Os limites de entrada podem ser encontrados na documentação de referência de competências.

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

Se quiseres garantir que todo o texto é analisado, considera usar a habilidade Split.

Warning: Web API skill response contains warnings

O indexador executou a skill no conjunto de competências, mas a resposta do pedido da Web API indica que existem avisos. Reveja os avisos para perceber como os seus dados são afetados e se é necessária uma ação adicional.

Warning: The current indexer configuration does not support incremental progress

Este 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 limite de tempo de execução, o indexador possa retomar de onde ficou na próxima execução, em vez de ter de reindexar toda a coleção do zero. Isto é especialmente importante ao indexar grandes coleções.

A capacidade de retomar um trabalho de indexação inacabado baseia-se em ter documentos ordenados pela _ts coluna. O indexador usa o carimbo temporal para determinar qual o documento a seguir. Se a _ts coluna estiver em falta ou se o indexador não conseguir determinar se uma consulta personalizada está ordenada por ela, o indexador começa do início e verá este aviso.

É possível sobrepor este comportamento, permitindo progresso incremental e suprimindo este aviso usando a assumeOrderByHighWaterMarkColumn propriedade de configuração.

Para 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 de Armazenamento de Tabelas tem limites quanto ao tamanho das propriedades das entidades . As cadeias podem ter 32.000 caracteres ou menos. Se uma linha com uma propriedade de cadeia superior a 32.000 caracteres estiver a ser projetada, apenas os primeiros 32.000 caracteres são preservados. Para contornar este problema, evite projetar linhas com propriedades de string superiores a 32.000 caracteres.

Warning: Truncated extracted text to X characters

Os indexadores limitam a quantidade de texto que pode ser extraída de um único documento. Este limite depende do escalão de preço: 32.000 caracteres para o nível Gratuito, 64.000 para o Básico, 4 milhões para o Standard, 8 milhões para o Standard S2 e 16 milhões para o Standard S3. O texto que foi truncado não será indexado. Para evitar este aviso, tente dividir documentos com grandes quantidades de texto em vários documentos mais pequenos.

Para mais informações, veja Limites do Indexador.

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

Mapeamentos de campo de saída que referenciam dados inexistentes/nulos gerarão avisos para cada documento e resultarão num campo de índice vazio. Para contornar este problema, verifique novamente os seus percursos de mapeamento de campo de saída para possíveis erros tipográficos, ou defina um valor padrão usando a função Condicional. Consulte Mapeamento de campo de saída para detalhes.

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

As políticas de deteção de alterações de dados têm requisitos específicos para as colunas que utilizam para detetar mudanças. Um destes requisitos é que esta coluna seja atualizada sempre que o item de origem for alterado. Outro requisito é que o novo valor desta coluna seja maior do que o valor anterior. As colunas-chave não cumprem este requisito porque não mudam em todas as atualizações. Para contornar este problema, selecione uma coluna diferente para a política de deteçã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 de saber como o texto é codificado antes de o analisar. As duas formas mais comuns de codificar texto são UTF-16 e UTF-8. UTF-8 é uma codificação de comprimento variável onde cada carácter tem entre 1 e 4 bytes de comprimento. UTF-16 é uma codificação de comprimento fixo onde cada carácter tem 2 bytes. O UTF-16 tem duas variantes diferentes, big endian e little endian. A codificação de texto é determinada por um byte order mark, uma série de bytes antes do texto.

Se não houver marca de ordem de bytes, assume-se que o texto está codificado como UTF-8.

Para contornar este aviso, determine qual é a codificação de texto para essa mancha e adicione a marca de ordem dos 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 preguiçosas não podem ser consultadas de forma consistente, o que resulta na falta de dados do seu indexador. Para contornar este aviso, altere a 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 é transmitido pelo serviço de Linguagem da Foundry Tools. Em alguns casos, é seguro ignorar este aviso, por exemplo, se a string longa for apenas um URL longo. Tenha em atenção que, quando uma palavra tem mais de 64 caracteres, é truncada para 64 caracteres, o que pode afetar as previsões do modelo.

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

Os indexadores têm limites de tamanho dos documentos. Certifique-se de que os documentos na sua fonte de dados são inferiores ao 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.

Este erro normalmente acontece nos indexadores SQL do Azure quando o tipo de coluna de origem usado para dataChangeDetectionPolicy não corresponde ao que o indexador espera, especialmente se convertHighWaterMarkToRowVersion estiver ativado.

Por exemplo, se a coluna usada para deteção de alterações for do tipo datetime, mas o indexador esperar um tipo rowversion porque a função convertHighWaterMarkToRowVersion está ativada, a incompatibilidade causará um erro.

Verifique o tipo de dados da coluna 'High Watermark' na fonte e atualize a configuração do indexador em conformidade. Depois de verificado e atualizado, reinicie e execute novamente o indexador para processar os valores das colunas.

Error: Access denied to Virtual Network/Firewall rules.

Este erro ocorre tipicamente devido a uma das seguintes situações:

• Restrições de firewall nos recursos Azure exigidas pelo seu indexador, dependendo da sua configuração. Estes recursos podem incluir: a fonte de dados, a conta Armazenamento do Azure (usada para sessões de depuração, enriquecimento incremental ou armazenamento de conhecimento), Azure Function (usada para competências personalizadas da API web) ou implementações Microsoft Foundry usadas durante o enriquecimento de IA.
• Configurações de endpoints privados que bloqueiam o acesso do indexador a esses recursos.

Assegure que o indexador tem acesso aos seus componentes de configuração ao rever as configurações dos seus recursos para confirmar que permitem tráfego para todos os serviços necessários:

• Firewall e definições de restrição de IP
• Configuração de ligação privada partilhada

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

Este erro ocorre quando o indexador Pesquisa de IA do Azure não consegue autenticar-se usando a cadeia de ligação fornecida ou tem problemas no acesso à conta de armazenamento para verificar as credenciais.

Error: Error detecting index schema from data source

A experiência do portal Azure usada para configurar o indexador não conseguiu recuperar a informação do esquema da fonte de dados. Isto pode acontecer devido a problemas de conectividade transitória ou restrições de configuração de rede que impedem o Pesquisa de IA do Azure de aceder à fonte.