Tutorial: Conjuntos de habilidades no Azure AI Search

Saiba como usar o SDK do Azure para .NET para criar um pipeline de enriquecimento de IA para extração de conteúdo e transformações durante a indexação.

Os conjuntos de habilidades adicionam o processamento de IA ao conteúdo bruto, tornando-o mais uniforme e pesquisável. Depois de saber como os conjuntos de habilidades funcionam, você pode dar suporte a uma ampla variedade de transformações, desde a análise de imagem até o processamento de linguagem natural até o processamento personalizado que você fornece externamente.

Neste tutorial, você:

Overview

Este tutorial usa C# e a biblioteca de clientes Azure.Search.Documents para criar uma fonte de dados, índice, indexador e conjunto de habilidades.

O indexador orienta cada etapa do pipeline, começando com a extração de conteúdo de dados de exemplo (texto e imagens não estruturados) em um contêiner de blob no Armazenamento do Microsoft Azure.

Depois que o conteúdo é extraído, o conjunto de habilidades executa habilidades integradas da Microsoft para localizar e extrair informações. Essas habilidades incluem OCR (reconhecimento óptico de caracteres) em imagens, detecção de idioma em texto, extração de frases-chave e reconhecimento de entidades (organizações). Novas informações criadas pelo conjunto de habilidades são enviadas para campos em um índice. Depois que o índice for preenchido, você poderá usar os campos em consultas, facetas e filtros.

Prerequisites

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Armazenamento do Azure.

• Pesquisa de IA do Azure.

• Pacote Azure.Search.Documents.

• Visual Studio.

Baixar arquivos

• Baixe um arquivo zip do repositório de dados de exemplo e extraia o conteúdo. Saiba como.

• Baixe os arquivos de dados de exemplo (mídia mista)

Carregar dados de exemplo para o Armazenamento do Microsoft Azure

1. No Armazenamento do Azure, crie um novo contêiner e nomeie-o em tipos de conteúdo misto.

2. Carregue os arquivos de dados de exemplo.

3. Obtenha uma cadeia de conexão de armazenamento para que você possa formular uma conexão na Pesquisa de IA do Azure.

   1. À esquerda, selecione Teclas de acesso.

   2. Copie a cadeia de conexão para a chave um ou para a chave dois. A cadeia de conexão é semelhante ao seguinte exemplo:

      DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
      

Serviços de IA do Azure

O enriquecimento interno de IA é apoiado pelos serviços de IA do Azure, incluindo o serviço de linguagem e a Visão de IA do Azure para processamento de imagens e linguagem natural. Para pequenas cargas de trabalho como esse tutorial, você pode usar a alocação gratuita de 20 transações por indexador. Para cargas de trabalho maiores, anexe um recurso de várias regiões dos Serviços de IA do Azure a um conjunto de habilidades para preços Standard.

Copiar uma URL do serviço de pesquisa e uma chave de API

Para este tutorial, as conexões com o Azure AI Search exigem um endpoint e uma chave de API. Você pode obter esses valores no portal do Azure.

1. Entre no portal do Azure, navegue até a página Visão geral do serviço de pesquisa e copie a URL. Um exemplo de endpoint pode ter a seguinte aparência: https://mydemo.search.windows.net.

2. Em Configurações>Chaves, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas.

Configure seu ambiente

Comece abrindo o Visual Studio e criando um novo projeto de Aplicativo de Console.

Instalar o Azure.Search.Documents

O SDK do .NET da IA do Azure Search consiste de uma biblioteca de clientes que permite que você gerencie seus índices, fontes de dados, indexadores e conjuntos de habilidades, carregue e gerencie documentos e execute consultas, sem precisar lidar com os detalhes de HTTP e JSON. Essa biblioteca de clientes é distribuída como um pacote NuGet.

Para este projeto, instale a versão 11 ou posterior do Azure.Search.Documents e a versão mais recente do Microsoft.Extensions.Configuration.

1. No Visual Studio, selecione Ferramentas>Gerenciador de Pacotes NuGet>Gerenciar Pacotes NuGet para a Solução...

2. Procure por Azure.Search.Document.

3. Selecione a versão mais recente e selecione Instalar.

4. Repita as etapas anteriores para instalar Microsoft.Extensions.Configuration e Microsoft.Extensions.Configuration.Json.

Adicionar informações de conexão de serviço

1. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Adicionar>Novo Item....

2. Nomeie o arquivo appsettings.json e selecione Adicionar.

3. Inclua esse arquivo no diretório de saída.

   1. Clique com o botão direito do mouse em appsettings.json e selecione Propriedades.
   2. Altere o valor de Copiar para Diretório de Saída para Copiar se for o mais recente.

4. Copie o JSON abaixo em seu novo arquivo JSON.

   {
     "SearchServiceUri": "<YourSearchServiceUri>",
     "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>",
     "SearchServiceQueryApiKey": "<YourSearchServiceQueryApiKey>",
     "AzureAIServicesKey": "<YourMultiRegionAzureAIServicesKey>",
     "AzureBlobConnectionString": "<YourAzureBlobConnectionString>"
   }
   

Adicione as informações do seu serviço de pesquisa e da conta de armazenamento de blobs. Lembre-se de que você pode obter essas informações nas etapas de provisionamento do serviço indicadas na seção anterior.

Para SearchServiceUri, insira a URL completa.

Adicionar namespaces

Em Program.cs, adicione os namespaces a seguir.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Microsoft.Extensions.Configuration;
using System;
using System.Collections.Generic;
using System.Linq;

namespace EnrichwithAI

Criar um cliente

Crie uma instância de um SearchIndexClient e um SearchIndexerClient em Main.

public static void Main(string[] args)
{
    // Create service client
    IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
    IConfigurationRoot configuration = builder.Build();

    string searchServiceUri = configuration["SearchServiceUri"];
    string adminApiKey = configuration["SearchServiceAdminApiKey"];
    string azureAiServicesKey = configuration["AzureAIServicesKey"];

    SearchIndexClient indexClient = new SearchIndexClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));
    SearchIndexerClient indexerClient = new SearchIndexerClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));
}

Adicionar uma função para sair do programa durante a falha

Este tutorial pretende ajudar você a entender cada etapa do pipeline de indexação. Se houver um problema crítico que impeça o programa de criar a fonte de dados, o conjunto de habilidades, o índice ou o indexador, o programa produzirá a mensagem de erro e será fechado, de modo que o problema possa ser compreendido e resolvido.

Adicione ExitProgram a Main para processar cenários que exigem o fechamento do programa.

private static void ExitProgram(string message)
{
    Console.WriteLine("{0}", message);
    Console.WriteLine("Press any key to exit the program...");
    Console.ReadKey();
    Environment.Exit(0);
}

Criar o pipeline

Na IA do Azure Search, o processamento de IA ocorre durante a indexação (ou a ingestão de dados). Esta parte do passo a passo cria quatro objetos: fonte de dados, definição de índice, conjunto de habilidades e indexador.

Etapa 1: Criar uma fonte de dados

SearchIndexerClient tem uma propriedade DataSourceName que pode ser definida como um objeto SearchIndexerDataSourceConnection. Esse objeto fornece todos os métodos necessários para criar, listar, atualizar ou excluir fontes de dados da IA do Azure Search.

Crie uma nova instância SearchIndexerDataSourceConnection chamando indexerClient.CreateOrUpdateDataSourceConnection(dataSource). O código a seguir cria uma fonte de dados do tipo AzureBlob.

private static SearchIndexerDataSourceConnection CreateOrUpdateDataSource(SearchIndexerClient indexerClient, IConfigurationRoot configuration)
{
    SearchIndexerDataSourceConnection dataSource = new SearchIndexerDataSourceConnection(
        name: "demodata",
        type: SearchIndexerDataSourceType.AzureBlob,
        connectionString: configuration["AzureBlobConnectionString"],
        container: new SearchIndexerDataContainer("mixed-content-type"))
    {
        Description = "Demo files to demonstrate Azure AI Search capabilities."
    };

    // The data source does not need to be deleted if it was already created
    // since we are using the CreateOrUpdate method
    try
    {
        indexerClient.CreateOrUpdateDataSourceConnection(dataSource);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to create or update the data source\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without a data source");
    }

    return dataSource;
}

Para uma solicitação bem-sucedida, o método retornará a fonte de dados que foi criada. Se houver um problema com a solicitação, como um parâmetro inválido, o método gerará uma exceção.

Agora, adicione uma linha à Main para chamar a função CreateOrUpdateDataSource recém-adicionada.

// Create or Update the data source
Console.WriteLine("Creating or updating the data source...");
SearchIndexerDataSourceConnection dataSource = CreateOrUpdateDataSource(indexerClient, configuration);

Compile e execute a solução. Como esta é sua primeira solicitação, verifique o portal do Azure para confirmar a fonte de dados foi criado na IA do Azure Search. Na página de visão geral do serviço de pesquisa, verifique se a lista de Fontes de Dados tem um novo item. Talvez seja necessário aguardar alguns minutos para que a página do portal do Azure seja atualizada.

Etapa 2: Criar um conjunto de habilidades

Nesta seção, você deve definir um conjunto de etapas de enriquecimento que você deseja aplicar aos seus dados. Cada etapa de enriquecimento é chamada de habilidade, e o conjunto de etapas de enriquecimento é um conjunto de habilidades. Este tutorial usa habilidades internas do conjunto de habilidades:

• A qualificação OCR (Reconhecimento Óptico de Caracteres) reconhece textos impressos e manuscritos em arquivos de imagem.

• Fusão de Texto para consolidar o texto de uma coleção de campos em um único campo de "conteúdo mesclado".

• A detecção de idioma para identificar o idioma do conteúdo.

• Reconhecimento de entidade para extrair os nomes das organizações de conteúdo no contêiner de blobs.

• A Divisão de Texto divide o conteúdo grande em partes menores antes de chamar a habilidade de extração de frase-chave e a habilidade de reconhecimento de entidade. A extração de frase-chave e o reconhecimento de entidade aceitam entradas de 50 mil caracteres ou menos. Alguns dos arquivos de exemplo precisam ser divididos para caber dentro desse limite.

• Extração de frase chave para destacar as principais frases-chave.

Durante o processamento inicial, a IA do Azure Search abre os documentos para extrair o conteúdo dos diferentes formatos de arquivo. O texto originário do arquivo de origem é colocado em um campo content gerado, um para cada documento. Assim, defina a entrada como "/document/content" para usar esse texto. O conteúdo de imagem é colocado em um campo normalized_images gerado, especificado em um conjunto de habilidades como /document/normalized_images/*.

Resultados podem ser mapeados para um índice, usados como entrada para uma funcionalidade subsequente, ou ambos, como é o caso com o código de idioma. No índice, um código de idioma é útil para filtragem. Como uma entrada, o código de idioma é usado por habilidades de análise de texto para informar as regras linguísticas em torno de quebra de palavras.

Para obter mais informações sobre conceitos básicos do conjunto de qualificações, consulte como definir um conjunto de qualificações.

Habilidade OCR

O OcrSkill extrai texto de imagens. Essa habilidade presume que um campo de imagens normalizado existe. Para gerar este campo, mais adiante no tutorial, definiremos a configuração "imageAction" na definição do indexador para "generateNormalizedImages".

private static OcrSkill CreateOcrSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("image")
    {
        Source = "/document/normalized_images/*"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("text")
    {
        TargetName = "text"
    });

    OcrSkill ocrSkill = new OcrSkill(inputMappings, outputMappings)
    {
        Description = "Extract text (plain and structured) from image",
        Context = "/document/normalized_images/*",
        DefaultLanguageCode = OcrSkillLanguage.En,
        ShouldDetectOrientation = true
    };

    return ocrSkill;
}

Competência de mesclagem

Nesta seção, você cria uma MergeSkill que mescla o campo de conteúdo do documento com o texto produzido pela habilidade do OCR.

private static MergeSkill CreateMergeSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/content"
    });
    inputMappings.Add(new InputFieldMappingEntry("itemsToInsert")
    {
        Source = "/document/normalized_images/*/text"
    });
    inputMappings.Add(new InputFieldMappingEntry("offsets")
    {
        Source = "/document/normalized_images/*/contentOffset"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("mergedText")
    {
        TargetName = "merged_text"
    });

    MergeSkill mergeSkill = new MergeSkill(inputMappings, outputMappings)
    {
        Description = "Create merged_text which includes all the textual representation of each image inserted at the right ___location in the content field.",
        Context = "/document",
        InsertPreTag = " ",
        InsertPostTag = " "
    };

    return mergeSkill;
}

Habilidade de detecção de idioma

O LanguageDetectionSkill detecta o idioma do texto de entrada e relata um único código de idioma para cada documento enviado na solicitação. Usaremos a saída da habilidade Detecção de Idioma como parte da entrada para a habilidade Divisão de Texto.

private static LanguageDetectionSkill CreateLanguageDetectionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/merged_text"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("languageCode")
    {
        TargetName = "languageCode"
    });

    LanguageDetectionSkill languageDetectionSkill = new LanguageDetectionSkill(inputMappings, outputMappings)
    {
        Description = "Detect the language used in the document",
        Context = "/document"
    };

    return languageDetectionSkill;
}

Habilidade de divisão de texto

A SplitSkill abaixo dividirá o texto por páginas e limitará o tamanho da página a 4 mil caracteres, conforme medido por String.Length. O algoritmo tentará dividir o texto em blocos com no máximo maximumPageLength de tamanho. Nesse caso, o algoritmo fará o possível para quebrar a frase em um limite de orações, de modo que o tamanho da parte possa ser um pouco menor que maximumPageLength.

private static SplitSkill CreateSplitSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/merged_text"
    });
    inputMappings.Add(new InputFieldMappingEntry("languageCode")
    {
        Source = "/document/languageCode"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("textItems")
    {
        TargetName = "pages",
    });

    SplitSkill splitSkill = new SplitSkill(inputMappings, outputMappings)
    {
        Description = "Split content into pages",
        Context = "/document",
        TextSplitMode = TextSplitMode.Pages,
        MaximumPageLength = 4000,
        DefaultLanguageCode = SplitSkillLanguage.En
    };

    return splitSkill;
}

Habilidade de reconhecimento de entidade

Esta instância EntityRecognitionSkill está configurada para reconhecer o tipo de categoria organization. O EntityRecognitionSkill também pode reconhecer tipos de categoria person e ___location.

Observe que o campo "context" está definido como "/document/pages/*" com um asterisco, o que significa que a etapa de enriquecimento é chamada para cada página em "/document/pages".

private static EntityRecognitionSkill CreateEntityRecognitionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/pages/*"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("organizations")
    {
        TargetName = "organizations"
    });

    // Specify the V3 version of the EntityRecognitionSkill
    var skillVersion = EntityRecognitionSkill.SkillVersion.V3;

    var entityRecognitionSkill = new EntityRecognitionSkill(inputMappings, outputMappings, skillVersion)
    {
        Description = "Recognize organizations",
        Context = "/document/pages/*",
        DefaultLanguageCode = EntityRecognitionSkillLanguage.En
    };
    entityRecognitionSkill.Categories.Add(EntityCategory.Organization);
    return entityRecognitionSkill;
}

Habilidade de extração de frase-chave

Assim como a instância EntityRecognitionSkill recém-criada, o KeyPhraseExtractionSkill é chamado para cada página do documento.

private static KeyPhraseExtractionSkill CreateKeyPhraseExtractionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/pages/*"
    });
    inputMappings.Add(new InputFieldMappingEntry("languageCode")
    {
        Source = "/document/languageCode"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("keyPhrases")
    {
        TargetName = "keyPhrases"
    });

    KeyPhraseExtractionSkill keyPhraseExtractionSkill = new KeyPhraseExtractionSkill(inputMappings, outputMappings)
    {
        Description = "Extract the key phrases",
        Context = "/document/pages/*",
        DefaultLanguageCode = KeyPhraseExtractionSkillLanguage.En
    };

    return keyPhraseExtractionSkill;
}

Construir e criar o conjunto de habilidades

Construa o SearchIndexerSkillset usando as habilidades que você criou.

private static SearchIndexerSkillset CreateOrUpdateDemoSkillSet(SearchIndexerClient indexerClient, IList<SearchIndexerSkill> skills,string azureAiServicesKey)
{
    SearchIndexerSkillset skillset = new SearchIndexerSkillset("demoskillset", skills)
    {
        // Azure AI services was formerly known as Cognitive Services.
        // The APIs still use the old name, so we need to create a CognitiveServicesAccountKey object.
        Description = "Demo skillset",
        CognitiveServicesAccount = new CognitiveServicesAccountKey(azureAiServicesKey)
    };

    // Create the skillset in your search service.
    // The skillset does not need to be deleted if it was already created
    // since we are using the CreateOrUpdate method
    try
    {
        indexerClient.CreateOrUpdateSkillset(skillset);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the skillset\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without a skillset");
    }

    return skillset;
}

Adicione as linhas a seguir a Main.

// Create the skills
Console.WriteLine("Creating the skills...");
OcrSkill ocrSkill = CreateOcrSkill();
MergeSkill mergeSkill = CreateMergeSkill();
EntityRecognitionSkill entityRecognitionSkill = CreateEntityRecognitionSkill();
LanguageDetectionSkill languageDetectionSkill = CreateLanguageDetectionSkill();
SplitSkill splitSkill = CreateSplitSkill();
KeyPhraseExtractionSkill keyPhraseExtractionSkill = CreateKeyPhraseExtractionSkill();

// Create the skillset
Console.WriteLine("Creating or updating the skillset...");
List<SearchIndexerSkill> skills = new List<SearchIndexerSkill>();
skills.Add(ocrSkill);
skills.Add(mergeSkill);
skills.Add(languageDetectionSkill);
skills.Add(splitSkill);
skills.Add(entityRecognitionSkill);
skills.Add(keyPhraseExtractionSkill);

SearchIndexerSkillset skillset = CreateOrUpdateDemoSkillSet(indexerClient, skills, azureAiServicesKey);

Etapa 3: Crie um índice

Nesta seção, você define o esquema de índice especificando quais campos serão incluídos no índice de pesquisa e os atributos de pesquisa para cada campo. Campos têm um tipo e podem levar a atributos que determinam como o campo é usado (pesquisável, classificável e assim por diante). Nomes de campos em um índice não são necessários para corresponder de modo idêntico aos nomes de campos na fonte. Em uma etapa posterior, você deve adicionar mapeamentos de campo em um indexador para conectar-se campos de origem-destino. Nesta etapa, defina o índice usando as convenções de nomenclatura de campo relevantes para o aplicativo de pesquisa.

Este exercício usa os seguintes campos e tipos de campo:

Nomes de campo	Tipos de campo
id	Edm.String
content	Edm.String
languageCode	Edm.String
keyPhrases	List<Edm.String>
organizations	List<Edm.String>

Criar classe DemoIndex

Os campos para este índice são definidos usando uma classe de modelo. Cada propriedade da classe de modelo tem atributos que determinam os comportamentos relacionados à pesquisa do campo de índice correspondente.

Vamos adicionar a classe de modelo a um novo arquivo C#. Clique com o botão direito do mouse em seu projeto e selecione Adicionar>Novo Item..., selecione "Classe" e nomeie o arquivo DemoIndex.cs, depois selecione Adicionar.

Certifique-se de indicar que você deseja usar os tipos dos namespaces Azure.Search.Documents.Indexes e System.Text.Json.Serialization.

Adicione a definição de classe de modelo abaixo a DemoIndex.cs e inclua-a no mesmo namespace onde você criará o índice.

using Azure.Search.Documents.Indexes;
using System.Text.Json.Serialization;

namespace EnrichwithAI
{
    // The SerializePropertyNamesAsCamelCase is currently unsupported as of this writing. 
    // Replace it with JsonPropertyName
    public class DemoIndex
    {
        [SearchableField(IsSortable = true, IsKey = true)]
        [JsonPropertyName("id")]
        public string Id { get; set; }

        [SearchableField]
        [JsonPropertyName("content")]
        public string Content { get; set; }

        [SearchableField]
        [JsonPropertyName("languageCode")]
        public string LanguageCode { get; set; }

        [SearchableField]
        [JsonPropertyName("keyPhrases")]
        public string[] KeyPhrases { get; set; }

        [SearchableField]
        [JsonPropertyName("organizations")]
        public string[] Organizations { get; set; }
    }
}

Agora que você definiu uma classe de modelo, em Program.cs você pode criar uma definição de índice com bastante facilidade. O nome desse índice será demoindex. Se já existir um índice com esse nome, ele será excluído.

private static SearchIndex CreateDemoIndex(SearchIndexClient indexClient)
{
    FieldBuilder builder = new FieldBuilder();
    var index = new SearchIndex("demoindex")
    {
        Fields = builder.Build(typeof(DemoIndex))
    };

    try
    {
        indexClient.GetIndex(index.Name);
        indexClient.DeleteIndex(index.Name);
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        //if the specified index not exist, 404 will be thrown.
    }

    try
    {
        indexClient.CreateIndex(index);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the index\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without an index");
    }

    return index;
}

Durante os testes, você poderá constatar que está tentando criar o índice mais de uma vez. Por isso, verifique se o índice que você está prestes a criar já existe antes de tentar criá-lo.

Adicione as linhas a seguir a Main.

// Create the index
Console.WriteLine("Creating the index...");
SearchIndex demoIndex = CreateDemoIndex(indexClient);

Adicione a instrução using a seguir para resolver a referência de desambiguação.

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

Para saber mais sobre os conceitos de índice, confira Criar índice (API REST).

Etapa 4: Criar e executar um indexador

Até agora, você criou uma fonte de dados, um conjunto de qualificações e um índice. Esses três componentes se tornam parte de um indexador que reúne cada item em uma única operação de várias fases. Para unir esses em um indexador, você deve definir mapeamentos de campo.

• Os fieldMappings são processados antes do conjunto de habilidades, mapeando campos de origem da fonte de dados para campos de destino em um índice. Se os tipos e os nomes do campo forem os mesmos em ambas as extremidades, nenhum mapeamento será necessário.

• Os outputFieldMappings são processados depois do conjunto de habilidades, fazendo referência a sourceFieldNames que não existem até a decodificação de documentos ou até que o enriquecimento os crie. O targetFieldName é um campo em um índice.

Além de conectar entradas a saídas, você também pode usar mapeamentos de campo para mesclar estruturas de dados. Para obter mais informações, consulte Como mapear campos enriquecidos para um índice pesquisável.

private static SearchIndexer CreateDemoIndexer(SearchIndexerClient indexerClient, SearchIndexerDataSourceConnection dataSource, SearchIndexerSkillset skillSet, SearchIndex index)
{
    IndexingParameters indexingParameters = new IndexingParameters()
    {
        MaxFailedItems = -1,
        MaxFailedItemsPerBatch = -1,
    };
    indexingParameters.Configuration.Add("dataToExtract", "contentAndMetadata");
    indexingParameters.Configuration.Add("imageAction", "generateNormalizedImages");

    SearchIndexer indexer = new SearchIndexer("demoindexer", dataSource.Name, index.Name)
    {
        Description = "Demo Indexer",
        SkillsetName = skillSet.Name,
        Parameters = indexingParameters
    };

    FieldMappingFunction mappingFunction = new FieldMappingFunction("base64Encode");
    mappingFunction.Parameters.Add("useHttpServerUtilityUrlTokenEncode", true);

    indexer.FieldMappings.Add(new FieldMapping("metadata_storage_path")
    {
        TargetFieldName = "id",
        MappingFunction = mappingFunction

    });
    indexer.FieldMappings.Add(new FieldMapping("content")
    {
        TargetFieldName = "content"
    });

    indexer.OutputFieldMappings.Add(new FieldMapping("/document/pages/*/organizations/*")
    {
        TargetFieldName = "organizations"
    });
    indexer.OutputFieldMappings.Add(new FieldMapping("/document/pages/*/keyPhrases/*")
    {
        TargetFieldName = "keyPhrases"
    });
    indexer.OutputFieldMappings.Add(new FieldMapping("/document/languageCode")
    {
        TargetFieldName = "languageCode"
    });

    try
    {
        indexerClient.GetIndexer(indexer.Name);
        indexerClient.DeleteIndexer(indexer.Name);
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        //if the specified indexer not exist, 404 will be thrown.
    }

    try
    {
        indexerClient.CreateIndexer(indexer);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the indexer\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without creating an indexer");
    }

    return indexer;
}

Adicione as linhas a seguir a Main.

// Create the indexer, map fields, and execute transformations
Console.WriteLine("Creating the indexer and executing the pipeline...");
SearchIndexer demoIndexer = CreateDemoIndexer(indexerClient, dataSource, skillset, demoIndex);

Espere que o processamento do indexador leve algum tempo para ser concluído. Embora o conjunto de dados seja pequeno, as habilidades analíticas exigem muita computação. Algumas técnicas, como a análise de imagem, são demoradas.

Explorar a criação do indexador

O código define "maxFailedItems" como -1, que instrui o mecanismo de indexação para ignorar erros durante a importação de dados. Isso é útil porque há portanto alguns documentos na fonte de dados de demonstração. Para uma fonte de dados maior, você definirá o valor maior que 0.

Observe também que "dataToExtract" está definido como "contentAndMetadata". Essa instrução informa o indexador para extrair automaticamente o conteúdo de diferentes formatos de arquivo, como também os metadados relacionados a cada arquivo.

Quando o conteúdo é extraído, você pode definir imageAction para extrair o texto da imagem foi encontrada na fonte de dados. A configuração "imageAction" definida como "generateNormalizedImages", combinada com a habilidade de OCR e a habilidade de Mesclagem de Texto, instrui o indexador a extrair o texto das imagens (por exemplo, a palavra "pare" de uma placa de trânsito "Pare") e inseri-la como parte do campo de conteúdo. Esse comportamento se aplica a ambas as imagens inseridas nos documentos (imagine uma imagem dentro de um PDF), bem como imagens encontradas na fonte de dados, por exemplo um arquivo JPG.

Monitorar a indexação

Depois que o indexador for definido, ele é executado automaticamente quando você enviar a solicitação. Dependendo de quais habilidades cognitivas você definiu, a indexação pode demorar mais do que o esperado. Para descobrir se o indexador ainda está em execução, use o método GetStatus.

private static void CheckIndexerOverallStatus(SearchIndexerClient indexerClient, SearchIndexer indexer)
{
    try
    {
        var demoIndexerExecutionInfo = indexerClient.GetIndexerStatus(indexer.Name);

        switch (demoIndexerExecutionInfo.Value.Status)
        {
            case IndexerStatus.Error:
                ExitProgram("Indexer has error status. Check the Azure Portal to further understand the error.");
                break;
            case IndexerStatus.Running:
                Console.WriteLine("Indexer is running");
                break;
            case IndexerStatus.Unknown:
                Console.WriteLine("Indexer status is unknown");
                break;
            default:
                Console.WriteLine("No indexer information");
                break;
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to get indexer overall status\n Exception message: {0}\n", ex.Message);
    }
}

demoIndexerExecutionInfo representa o status atual e o histórico de execução de um indexador.

Os avisos são comuns com algumas combinações de arquivo de origem e habilidade e nem sempre indicam um problema. Neste tutorial, os avisos são benignos (por exemplo, nenhuma entrada de texto dos arquivos JPEG).

Adicione as linhas a seguir a Main.

// Check indexer overall status
Console.WriteLine("Check the indexer overall status...");
CheckIndexerOverallStatus(indexerClient, demoIndexer);

Pesquisa

Nos aplicativos de console do tutorial da IA do Azure Search, normalmente adicionamos um atraso de 2 segundos antes de executarmos consultas que retornam resultados, mas como o enriquecimento leva vários minutos para ser concluído, fecharemos o aplicativo de console e usaremos outra abordagem.

A opção mais fácil é o Search Explorer no portal do Azure. Você pode executar primeiro uma consulta vazia que retorna todos os documentos ou uma pesquisa mais direcionada que retorna o conteúdo de campo criado pelo pipeline.

1. No portal do Azure, nas páginas do serviço de pesquisa, expanda Gerenciamento de Pesquisa>Índices.

2. Localize demoindex na lista. Ele deve ter 14 documentos. Quando a contagem de documentos é zero, o indexador ainda está em execução ou a página ainda não foi atualizada.

3. Selecione demoindex. O Explorador de Pesquisas é a primeira guia.

4. O conteúdo fica pesquisável assim que o primeiro documento é carregado. Para verificar se o conteúdo existe, execute uma consulta não especificada clicando em Pesquisar. Essa consulta retorna todos os documentos indexados atualmente, dando a você uma ideia do que o índice contém.

5. Para obter resultados mais gerenciáveis, alterne para a exibição JSON e defina parâmetros para selecionar os campos:

   {
       "search": "*",
       "count": true,
       "select": "id, languageCode, organizations"
   }
   

Redefina e execute novamente

Nos primeiros estágios experimentais de desenvolvimento, a abordagem mais prática para iterações de design é excluir os objetos da IA do Azure Search e permitir que seu código os reconstrua. Os nomes dos recursos são únicos. Excluir um objeto permite que você recriá-la usando o mesmo nome.

O código de exemplo deste tutorial verifica se há objetos existentes e os exclui, de modo que você possa executar novamente o código. Use também o portal do Azure para excluir índices, indexadores, fontes de dados e conjuntos de habilidades.

Takeaways

Este tutorial demonstrou as etapas básicas para a criação de um pipeline de indexação enriquecido durante a criação de partes dos componentes: uma fonte de dados, o conjunto de qualificações, o índice e o indexador.

Habilidades internas foram introduzidas, junto com a definição de conjunto de qualificações e a mecânica de encadear habilidades por meio de entradas e saídas. Você também aprendeu que outputFieldMappings na definição do indexador é necessário para rotear valores enriquecidos do pipeline para um índice pesquisável em um serviço da IA do Azure Search.

Finalmente, você aprendeu como testar os resultados e reiniciar o sistema para mais iterações. Você aprendeu que emitir consultas em relação ao índice retorna a saída criada pelo pipeline de indexação enriquecido. Você também aprendeu como verificar o status do indexador e quais objetos a serem excluídos antes de executar novamente um pipeline.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é uma boa ideia remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. Você pode excluir recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no portal do Azure usando o link "Todos os recursos" ou "Grupos de recursos" no painel de navegação do lado esquerdo.

Próximas etapas

Agora que você está familiarizado com todos os objetos de um pipeline de enriquecimento de IA, vamos examinar mais de perto as definições de conjunto de habilidades e as habilidades individuais.

Saiba como chamar APIs REST que criam um pipeline de enriquecimento de IA para extração de conteúdo e transformações durante a indexação.

Os conjuntos de habilidades adicionam o processamento de IA ao conteúdo bruto, tornando-o mais uniforme e pesquisável. Depois de saber como os conjuntos de habilidades funcionam, você pode dar suporte a uma ampla variedade de transformações, desde a análise de imagem até o processamento de linguagem natural até o processamento personalizado que você fornece externamente.

Neste tutorial, você:

Overview

Esse tutorial usa um cliente REST e as APIs REST do IA do Azure Search para criar uma fonte de dados, um índice, um indexador e um conjunto de habilidades.

O indexador orienta cada etapa do pipeline, começando com a extração de conteúdo de dados de exemplo (texto e imagens não estruturados) em um contêiner de blob no Armazenamento do Microsoft Azure.

Depois que o conteúdo é extraído, o conjunto de habilidades executa habilidades integradas da Microsoft para localizar e extrair informações. Essas habilidades incluem OCR (reconhecimento óptico de caracteres) em imagens, detecção de idioma em texto, extração de frases-chave e reconhecimento de entidades (organizações). Novas informações criadas pelo conjunto de habilidades são enviadas para campos em um índice. Depois que o índice for preenchido, você poderá usar os campos em consultas, facetas e filtros.

Prerequisites

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Azure Storage

• Pesquisa de IA do Azure

• Visual Studio Code com um cliente REST

Baixar arquivos

Baixe um arquivo zip do repositório de dados de exemplo e extraia o conteúdo. Saiba como.

• Arquivos de dados de exemplo (mídia mista).

• Exemplo de arquivo REST

Carregar dados de exemplo para o Armazenamento do Microsoft Azure

1. No Armazenamento do Microsoft Azure, crie um contêiner e nomeie-o cog-search-demo.

2. Faça upload dos arquivos de dados de amostra.

3. Obtenha uma cadeia de conexão de armazenamento para que você possa formular uma conexão na Pesquisa de IA do Azure.

   1. À esquerda, selecione Teclas de acesso.

   2. Copie a cadeia de conexão para a chave um ou para a chave dois. A cadeia de conexão é semelhante ao seguinte exemplo:

      DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
      

Serviços de IA do Azure

O enriquecimento interno de IA é apoiado pelos serviços de IA do Azure, incluindo o serviço de linguagem e a Visão de IA do Azure para processamento de imagens e linguagem natural. Para pequenas cargas de trabalho como esse tutorial, você pode usar a alocação gratuita de vinte transações por indexador. Para cargas de trabalho maiores, anexe um recurso de várias regiões dos Serviços de IA do Azure a um conjunto de habilidades para preços Standard.

Copiar uma URL do serviço de pesquisa e uma chave de API

Para este tutorial, as conexões com o Azure AI Search exigem um endpoint e uma chave de API. Você pode obter esses valores no portal do Azure.

1. Entre no portal do Azure, navegue até a página Visão geral do serviço de pesquisa e copie a URL. Um exemplo de endpoint pode ter a seguinte aparência: https://mydemo.search.windows.net.

2. Em Configurações>Chaves, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas.

   

Configure seu arquivo REST

1. Inicie o Visual Studio Code e abra o arquivo killset-tutorial.rest. Confira o Início Rápido: Pesquisa de texto completo se você precisar de ajuda com o cliente REST.

2. Forneça valores para as variáveis: ponto final do serviço de pesquisa, chave API de administração do serviço de pesquisa, um nome de índice, uma cadeia de ligação à sua conta de Armazenamento do Microsoft Azure e o nome do contêiner de blob.

Criar o pipeline

O enriquecimento de IA é orientado pelo indexador. Esta parte do passo a passo cria quatro objetos: fonte de dados, definição de índice, conjunto de habilidades e indexador.

Etapa 1: Criar uma fonte de dados

Chame Criar fonte de dados para configurar a cadeia de conexão para o contêiner de blob que contém os arquivos de dados de exemplo.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Etapa 2: Criar um conjunto de habilidades

Chame Criar Skillset para especificar quais etapas de enriquecimento são aplicadas ao seu conteúdo. As habilidades são executadas em paralelo, a menos que haja uma dependência.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-ss",
        "description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
        "cognitiveServices": null,
        "skills":
        [
            {
            "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
            "context": "/document/normalized_images/*",
            "defaultLanguageCode": "en",
            "detectOrientation": true,
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                }
            ],
            "outputs": [
                {
                    "name": "text"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
            "description": "Create merged_text, which includes all the textual representation of each image inserted at the right ___location in the content field. This is useful for PDF and other file formats that supported embedded images.",
            "context": "/document",
            "insertPreTag": " ",
            "insertPostTag": " ",
            "inputs": [
                {
                    "name":"text", 
                    "source": "/document/content"
                },
                {
                    "name": "itemsToInsert", 
                    "source": "/document/normalized_images/*/text"
                },
                {
                    "name":"offsets", 
                    "source": "/document/normalized_images/*/contentOffset" 
                }
            ],
            "outputs": [
                {
                    "name": "mergedText", 
                    "targetName" : "merged_text"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
            "textSplitMode": "pages",
            "maximumPageLength": 4000,
            "defaultLanguageCode": "en",
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "textItems",
                    "targetName": "pages"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
            "description": "If you have multilingual content, adding a language code is useful for filtering",
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "languageName",
                    "targetName": "language"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
            "context": "/document/pages/*",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/pages/*"
                }
            ],
            "outputs": [
                {
                    "name": "keyPhrases",
                    "targetName": "keyPhrases"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Organization"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "organizations",
                    "targetName": "organizations"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Location"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "locations",
                    "targetName": "locations"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Person"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "persons",
                    "targetName": "persons"
                }
            ]
            }
        ]
    }

Pontos principais:

• O corpo da solicitação especifica as seguintes funções incorporadas:

  Skill	Description
  Reconhecimento óptico de caracteres	Reconhece texto e números em arquivos de imagem.
  Mesclar Texto	Cria um "conteúdo mesclado" que recombina o conteúdo separado anteriormente, útil para documentos com imagens incorporadas (PDF, DOCX e assim por diante). Imagens e texto são separados na fase de quebra de documento. A habilidade de mesclagem os recombina, inserindo qualquer texto reconhecido, legendas de imagem ou marcas criadas pelo enriquecimento no mesmo local em que a imagem foi extraída no documento. Quando você trabalha com conteúdo mesclado em uma coleção de habilidades, este nó abrange todo o texto do documento, incluindo documentos que são somente texto e que nunca passam por OCR ou análise de imagem.
  Detecção de Idioma	Detecta o idioma e gera um nome ou código de idioma. Em conjuntos de dados multilíngues, um campo de idioma pode ser útil para filtros.
  Reconhecimento de entidade	Extrai os nomes de pessoas, organizações e localizações do conteúdo mesclado.
  Divisão de Texto	Divide um conteúdo mesclado grande em partes menores antes de chamar a habilidade de extração de frases-chave. Extração de frase-chave aceita entradas de 50.000 caracteres ou menos. Alguns dos arquivos de exemplo precisam ser divididos para caber dentro desse limite.
  Extração de Frases-chave	Extrai as principais frases-chave.

• Cada habilidade é executada no conteúdo do documento. Durante o processamento, o Azure AI Search quebra cada documento para ler conteúdo de diferentes formatos de arquivo. O texto encontrado originado no arquivo de origem é colocado em um campo content gerado, um para cada documento. Dessa forma, a entrada se torna "/document/content".

• Para a extração de frases-chave, como usamos a habilidade de divisor de texto para dividir arquivos maiores em páginas, o contexto para a habilidade de extração de frases-chave é "document/pages/*" (para cada página no documento) em vez de "/document/content".

Etapa 3: Crie um índice

Chame Criar Índice para fornecer o esquema usado para criar índices invertidos e outros constructos no Azure AI Search.

O maior componente de um índice é a coleção de campos, em que o tipo de dados e os atributos determinam o conteúdo e o comportamento no Azure AI Search. Verifique se você tem campos para a saída recém-gerada.

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-idx",
        "defaultScoringProfile": "",
        "fields": [
            {
                "name": "content",
                "type": "Edm.String",
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            },
            {
                "name": "text",
                "type": "Collection(Edm.String)",
                "facetable": false,
                "filterable": true,
                "searchable": true,
                "sortable": false
            },
            {
                "name": "language",
                "type": "Edm.String",
                "searchable": false,
                "sortable": true,
                "filterable": true,
                "facetable": false
            },
            {
                "name": "keyPhrases",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "organizations",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "persons",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "locations",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "metadata_storage_path",
                "type": "Edm.String",
                "key": true,
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            },
            {
                "name": "metadata_storage_name",
                "type": "Edm.String",
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            }
        ]
    }

Etapa 4: Criar e executar um indexador

Chame Criar indexador para conduzir o pipeline. Os três componentes que você criou até o momento (fonte de dados, conjunto de habilidades e índice) são entradas para um indexador. Criar o indexador no Azure AI Search é o evento que coloca todo o pipeline em movimento.

Espere essa ação levar vários minutos para ser concluída. Embora o conjunto de dados seja pequeno, as habilidades analíticas exigem muita computação.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-idxr",
        "description": "",
        "dataSourceName" : "cog-search-demo-ds",
        "targetIndexName" : "cog-search-demo-idx",
        "skillsetName" : "cog-search-demo-ss",
        "fieldMappings" : [
            {
                "sourceFieldName" : "metadata_storage_path",
                "targetFieldName" : "metadata_storage_path",
                "mappingFunction" : { "name" : "base64Encode" }
            },
            {
                "sourceFieldName": "metadata_storage_name",
                "targetFieldName": "metadata_storage_name"
            }
        ],
        "outputFieldMappings" : 
        [
            {
                "sourceFieldName": "/document/merged_text",
                "targetFieldName": "content"
            },
            {
                "sourceFieldName" : "/document/normalized_images/*/text",
                "targetFieldName" : "text"
            },
            {
                "sourceFieldName" : "/document/organizations", 
                "targetFieldName" : "organizations"
            },
            {
                "sourceFieldName": "/document/language",
                "targetFieldName": "language"
            },
            {
                "sourceFieldName" : "/document/persons", 
                "targetFieldName" : "persons"
            },
            {
                "sourceFieldName" : "/document/locations", 
                "targetFieldName" : "locations"
            },
            {
                "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
                "targetFieldName" : "keyPhrases"
            }
        ],
        "parameters":
        {
        "batchSize": 1,
        "maxFailedItems":-1,
        "maxFailedItemsPerBatch":-1,
        "configuration": 
            {
                "dataToExtract": "contentAndMetadata",
                "imageAction": "generateNormalizedImages"
            }
        }
    }

Pontos principais:

• O corpo da solicitação inclui referências aos objetos anteriores, as propriedades de configuração necessárias para o processamento de imagens e dois tipos de mapeamentos de campo.

• Os "fieldMappings" são processados antes do conjunto de habilidades, enviando o conteúdo da fonte de dados para os campos de destino em um índice. Você usa mapeamentos de campo para enviar conteúdo existente e não modificado para o índice. Se os tipos e os nomes do campo forem os mesmos em ambas as extremidades, nenhum mapeamento será necessário.

• "outputFieldMappings" são para campos criados por habilidades, após a execução do conjunto de habilidades. As referências a sourceFieldName em outputFieldMappings não existirão enquanto a quebra de documento ou o enriquecimento não as criar. O targetFieldName é um campo em um índice, definido no esquema de índice.

• O parâmetro "maxFailedItems" é definido como -1, que instrui o mecanismo de indexação a ignorar erros durante a importação de dados. Isso é aceitável porque há poucos documentos na fonte de dados de demonstração. Para uma fonte de dados maior, você definirá o valor maior que 0.

• A instrução "dataToExtract":"contentAndMetadata" indica ao indexador para que ele extraia automaticamente da propriedade de conteúdo do blob os valores e os metadados de cada objeto.

• O parâmetro imageAction orienta o indexador a extrair texto das imagens encontradas na fonte de dados. A configuração "imageAction":"generateNormalizedImages", combinada com a habilidade de OCR e a habilidade de mesclagem de texto, instrui o indexador a extrair o texto das imagens (por exemplo, a palavra "pare" de uma placa de trânsito "Pare") e inseri-la como parte do campo de conteúdo. Esse comportamento se aplica às imagens inseridas (imagine uma imagem em um PDF) e aos arquivos de imagens autônomos, por exemplo, um arquivo JPG.

Monitorar a indexação

A indexação e o enriquecimento são iniciados assim que você envia a solicitação Criar Indexador. Dependendo da complexidade e das operações do conjunto de habilidades, a indexação pode demorar um pouco.

Para descobrir se o indexador ainda está em execução, chame Obter status do indexador a fim de verificar o status do indexador.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

Pontos principais:

• Os avisos são comuns em alguns cenários e nem sempre indicam um problema. Por exemplo, se um contêiner de blob incluir arquivos de imagem e o pipeline não lidar com imagens, você receberá um aviso informando que as imagens não foram processadas.

• Nesse exemplo, há um arquivo PNG que não contém texto. As cinco habilidades baseadas em texto (detecção de idioma, reconhecimento de entidades de locais, organizações, pessoas e extração de frases-chave) falham ao executar nesse arquivo. A notificação resultante é exibida no histórico de execução.

Verificar os resultados

Agora que você criou um índice com conteúdo gerado por IA, chame Pesquisar documentos para executar algumas consultas e ver os resultados.

### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "metadata_storage_name,language,organizations",
    "count": true
  }

Os filtros podem ajudá-lo a restringir os resultados a itens de interesse:

### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "filter": "organizations/any(organizations: organizations eq 'Microsoft')",
    "select": "metadata_storage_name,organizations",
    "count": true
  }

Essas consultas ilustram algumas das maneiras pelas quais você pode trabalhar com sintaxe de consulta e filtros em novos campos criados pelo Azure AI Search. Para obter mais exemplos de consulta, confira Exemplos em documentos de pesquisa da API REST, Exemplos de consulta de sintaxe simples e Exemplos de consulta completas do Lucene.

Redefina e execute novamente

Nas fases iniciais do desenvolvimento, a iteração no design é comum. Redefinir e executar novamente ajuda na iteração.

Takeaways

Esse tutorial demonstra as etapas básicas para usar as APIs REST para criar um pipeline de enriquecimento de IA: uma fonte de dados, um conjunto de habilidades, um índice e um indexador.

Habilidades integradas foram introduzidas, juntamente com a definição do conjunto de habilidades que mostra a mecânica do encadeamento de habilidades por meio de entradas e saídas. Você também aprendeu que outputFieldMappings na definição do indexador é necessário para rotear valores enriquecidos do pipeline para um índice pesquisável em um serviço da IA do Azure Search.

Finalmente, você aprendeu como testar os resultados e reiniciar o sistema para mais iterações. Você aprendeu que emitir consultas em relação ao índice retorna a saída criada pelo pipeline de indexação enriquecido.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é uma boa ideia remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. Você pode excluir recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no portal do Azure usando o link "Todos os recursos" ou "Grupos de recursos" no painel de navegação do lado esquerdo.

Próximas etapas

Agora que você está familiarizado com todos os objetos em um pipeline de enriquecimento de IA, observe mais de perto as definições de conjuntos de habilidades e as habilidades individuais.