Tutorial: Use o REST e a IA para gerar conteúdo pesquisável em blobs do AzureTutorial: Use REST and AI to generate searchable content from Azure blobs

Se você tiver um texto não estruturado ou imagens no Armazenamento de Blobs do Azure, um pipeline de enriquecimento de IA poderá extrair informações e criar um conteúdo com base nos blobs que são úteis para cenários de pesquisa de texto completo ou mineração de conhecimento.If you have unstructured text or images in Azure Blob storage, an AI enrichment pipeline can extract information and create new content from blobs that are useful for full-text search or knowledge mining scenarios. Embora um pipeline possa processar imagens, este tutorial do REST concentra-se no texto, aplicando detecção de idioma e processamento de idioma natural para criar campos que você pode usar em consultas, facetas e filtros.Although a pipeline can process images, this REST tutorial focuses on text, applying language detection and natural language processing to create new fields that you can leverage in queries, facets, and filters.

Este tutorial usa o Postman e as APIs REST de Pesquisa para executar as seguintes tarefas:This tutorial uses Postman and the Search REST APIs to perform the following tasks:

  • Configurar serviços e uma coleção do Postman.Set up services and a Postman collection.
  • Criar um pipeline de enriquecimento que extrai texto, detecta o idioma, reconhece entidades e detecta frases-chave.Create an enrichment pipeline that extracts text, detects language, recognizes entities, and detects key phrases.
  • Criar um índice para armazenar a saída (conteúdo bruto, além de pares nome-valor gerados pelo pipeline).Create an index to store the output (raw content, plus pipeline-generated name-value pairs).
  • Executar o pipeline para executar transformações e a análise e para carregar o índice.Execute the pipeline to perform transformations and analysis, and to load the index.
  • Explore os resultados usando a pesquisa de texto completo e uma sintaxe de consulta avançada.Explore results using full text search and a rich query syntax.

Caso não tenha uma assinatura do Azure, abra uma conta gratuita antes de começar.If you don't have an Azure subscription, open a free account before you begin.

Visão geralOverview

Este tutorial usa C# e as APIs REST do Azure Cognitive Search para criar uma fonte de dados, um índice, um indexador e um conjunto de habilidades.This tutorial uses C# and the Azure Cognitive Search REST APIs to create a data source, index, indexer, and skillset. Você começará com documentos inteiros (texto não estruturado) como PDF, HTML, DOCX e PPTX no Armazenamento de Blobs do Azure e, em seguida, os executará por meio de um conjunto de habilidades para extrair entidades, frases-chave e outros tipos de texto nos arquivos de conteúdo.You'll start with whole documents (unstructured text) such as PDF, HTML, DOCX, and PPTX in Azure Blob storage, and then run them through a skillset to extract entities, key phrases, and other text in the content files.

Esse conjunto de habilidades usa habilidades internas baseadas na API de Serviços Cognitivos.This skillset uses built-in skills based on Cognitive Services APIs. As etapas no pipeline incluem a detecção de idioma em texto, extração de frases-chave e reconhecimento de entidades (organizações).Steps in the pipeline include language detection on text, key phrase extraction, and entity recognition (organizations). Novas informações são armazenadas em novos campos que você pode aproveitar em consultas, facetas e filtros.New information is stored in new fields that you can leverage in queries, facets, and filters.

Pré-requisitosPrerequisites

Observação

Use o serviço gratuito para este tutorial.You can use the free service for this tutorial. Um serviço de pesquisa gratuito limita você a três índices, três indexadores e três fontes de dados.A free search service limits you to three indexes, three indexers, and three data sources. Este tutorial cria um de cada.This tutorial creates one of each. Antes de começar, reserve um espaço no seu serviço para aceitar os novos recursos.Before starting, make sure you have room on your service to accept the new resources.

Baixar arquivosDownload files

  1. Abra esta pasta do OneDrive e, no canto superior esquerdo, clique em Baixar para copiar os arquivos para o computador.Open this OneDrive folder and on the top-left corner, click Download to copy the files to your computer.

  2. Clique com o botão direito do mouse no arquivo zip e selecione Extrair Tudo.Right-click the zip file and select Extract All. Há 14 arquivos de vários tipos.There are 14 files of various types. Você usará sete para este exercício.You'll use 7 for this exercise.

Opcionalmente, você também pode baixar o código-fonte, um arquivo de coleção do Postman, para este tutorial.Optionally, you can also download the source code, a Postman collection file, for this tutorial. O código-fonte pode ser encontrado em https://github.com/Azure-Samples/azure-search-postman-samples/tree/master/Tutorial.Source code can be found at https://github.com/Azure-Samples/azure-search-postman-samples/tree/master/Tutorial.

1 – Criar serviços1 - Create services

Este tutorial usa o Azure Cognitive Search para indexação e consultas, os Serviços Cognitivos no back-end para enriquecimento de IA e o Armazenamento de Blobs do Azure para fornecer os dados.This tutorial uses Azure Cognitive Search for indexing and queries, Cognitive Services on the backend for AI enrichment, and Azure Blob storage to provide the data. Este tutorial permanece sob a alocação gratuita de 20 transações por indexador por dia nos Serviços Cognitivos, de modo que os únicos serviços que você precisará criar são pesquisa e armazenamento.This tutorial stays under the free allocation of 20 transactions per indexer per day on Cognitive Services, so the only services you need to create are search and storage.

Se possível, crie os dois na mesma região e no mesmo grupo de recursos para facilitar a proximidade e a capacidade de gerenciamento.If possible, create both in the same region and resource group for proximity and manageability. Na prática, sua conta de armazenamento do Azure pode estar em qualquer região.In practice, your Azure Storage account can be in any region.

Começar com o Armazenamento do AzureStart with Azure Storage

  1. Entre no portal do Azure e clique em + Criar Recurso.Sign in to the Azure portal and click + Create Resource.

  2. Pesquise conta de armazenamento e selecione a oferta Conta de Armazenamento da Microsoft.Search for storage account and select Microsoft's Storage Account offering.

    Criar conta de armazenamentoCreate Storage account

  3. Na guia Informações Básicas, os itens a seguir são obrigatórios.In the Basics tab, the following items are required. Aceite os padrões para todo o restante.Accept the defaults for everything else.

    • Grupo de recursos.Resource group. Selecione um grupo existente ou crie um, mas use o mesmo grupo para todos os serviços, de modo que você possa gerenciá-los em conjunto.Select an existing one or create a new one, but use the same group for all services so that you can manage them collectively.

    • Nome da conta de armazenamento.Storage account name. Se acreditar que possa ter vários recursos do mesmo tipo, use o nome para desfazer a ambiguidade por tipo e região, por exemplo, blobstoragewestus.If you think you might have multiple resources of the same type, use the name to disambiguate by type and region, for example blobstoragewestus.

    • Local.Location. Se possível, escolha a mesma localização usada para a Pesquisa Cognitiva do Azure e os Serviços Cognitivos.If possible, choose the same location used for Azure Cognitive Search and Cognitive Services. Uma única localização anula os encargos de largura de banda.A single location voids bandwidth charges.

    • Tipo de Conta.Account Kind. Escolha o padrão, StorageV2 (Uso Geral v2) .Choose the default, StorageV2 (general purpose v2).

  4. Clique em Examinar + Criar para criar o serviço.Click Review + Create to create the service.

  5. Após a criação, clique em Ir para o recurso para abrir a página Visão Geral.Once it's created, click Go to the resource to open the Overview page.

  6. Clique em serviço Blobs.Click Blobs service.

  7. Clique em + Contêiner para criar um contêiner e nomeie-o cog-search-demo.Click + Container to create a container and name it cog-search-demo.

  8. Selecione cog-search-demo e, em seguida, clique em Upload para abrir a pasta em que você salvou os arquivos de download.Select cog-search-demo and then click Upload to open the folder where you saved the download files. Selecione todos os arquivos que não sejam de imagem.Select all of the non-image files. Você deve ter sete arquivos.You should have 7 files. Clique em OK para fazer upload deles.Click OK to upload.

    Carregar arquivos de exemploUpload sample files

  9. Antes de sair do Armazenamento do Azure, obtenha uma cadeia de conexão, de modo que você possa formular uma conexão na Pesquisa Cognitiva do Azure.Before you leave Azure Storage, get a connection string so that you can formulate a connection in Azure Cognitive Search.

    1. Navegue novamente até a página Visão Geral de sua conta de armazenamento (usamos blobstragewestus como exemplo).Browse back to the Overview page of your storage account (we used blobstragewestus as an example).

    2. No painel de navegação à esquerda, selecione Chaves de acesso e copie uma das cadeias de conexão.In the left navigation pane, select Access keys and copy one of the connection strings.

    A cadeia de conexão é uma URL semelhante ao seguinte exemplo:The connection string is a URL similar to the following example:

    DefaultEndpointsProtocol=https;AccountName=cogsrchdemostorage;AccountKey=<your account key>;EndpointSuffix=core.windows.net
    
  10. Salve a cadeia de conexão no Bloco de notas.Save the connection string to Notepad. Você precisará dela mais tarde ao configurar a conexão de fonte de dados.You'll need it later when setting up the data source connection.

Serviços CognitivosCognitive Services

O enriquecimento de IA é apoiado pelos Serviços Cognitivos, incluindo Análise de Texto e Pesquisa Visual Computacional para processamento de imagem e idioma natural.AI enrichment is backed by Cognitive Services, including Text Analytics and Computer Vision for natural language and image processing. Caso seu objetivo seja concluir um protótipo ou um projeto real, neste ponto, você poderá provisionar os Serviços Cognitivos (na mesma região da Pesquisa Cognitiva do Azure), de modo que você possa anexá-lo às operações de indexação.If your objective was to complete an actual prototype or project, you would at this point provision Cognitive Services (in the same region as Azure Cognitive Search) so that you can attach it to indexing operations.

Para este exercício, no entanto, ignore o provisionamento de recursos, porque Pesquisa Cognitiva do Azure pode se conectar aos Serviços Cognitivos nos bastidores e fornecer a você 20 transações gratuitas por execução de indexador.For this exercise, however, you can skip resource provisioning because Azure Cognitive Search can connect to Cognitive Services behind the scenes and give you 20 free transactions per indexer run. Como este tutorial usa sete transações, a alocação gratuita é suficiente.Since this tutorial uses 7 transactions, the free allocation is sufficient. Para projetos maiores, planeje o provisionamento dos Serviços Cognitivos no nível S0 pago conforme o uso.For larger projects, plan on provisioning Cognitive Services at the pay-as-you-go S0 tier. Para obter mais informações, confira Anexar Serviços Cognitivos.For more information, see Attach Cognitive Services.

O terceiro componente é a Pesquisa Cognitiva do Azure, que pode ser criada no portal.The third component is Azure Cognitive Search, which you can create in the portal. Use a Camada gratuita para concluir este passo a passo.You can use the Free tier to complete this walkthrough.

Assim como o Armazenamento de Blobs do Azure, reserve um momento para coletar a chave de acesso.As with Azure Blob storage, take a moment to collect the access key. Além disso, quando começar a estruturar as solicitações, você precisará fornecer a chave de API de administração e o ponto de extremidade usados para autenticar cada solicitação.Further on, when you begin structuring requests, you will need to provide the endpoint and admin api-key used to authenticate each request.

  1. Entre no portal do Azure e, na página Visão Geral do serviço de pesquisa, obtenha o nome de seu serviço de pesquisa.Sign in to the Azure portal, and in your search service Overview page, get the name of your search service. Você pode confirmar o nome do serviço examinando a URL do ponto de extremidade.You can confirm your service name by reviewing the endpoint URL. Se a URL do ponto de extremidade for https://mydemo.search.windows.net, o nome do serviço será mydemo.If your endpoint URL were https://mydemo.search.windows.net, your service name would be mydemo.

  2. Em Configurações > Chaves, obtenha uma chave de administração para adquirir todos os direitos sobre o serviço.In Settings > Keys, get an admin key for full rights on the service. Há duas chaves de administração intercambiáveis, fornecidas para a continuidade dos negócios, caso seja necessário sobrepor uma.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. É possível usar a chave primária ou secundária em solicitações para adicionar, modificar e excluir objetos.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

    Obtenha a chave de consulta também.Get the query key as well. É uma melhor prática para emitir solicitações de consulta com acesso somente leitura.It's a best practice to issue query requests with read-only access.

    Obter o nome do serviço e as chaves de consulta e de administrador

Todas as solicitações exigem uma api-key no cabeçalho de cada solicitação enviada a seu serviço.All requests require an api-key in the header of every request sent to your service. Uma chave válida estabelece a relação de confiança, para cada solicitação, entre o aplicativo que envia a solicitação e o serviço que a manipula.A valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

2 – Configurar o Postman2 - Set up Postman

Inicie o Postman e configure uma solicitação HTTP.Start Postman and set up an HTTP request. Se não estiver familiarizado com essa ferramenta, confira Explorar APIs REST do Azure Cognitive Search.If you are unfamiliar with this tool, see Explore Azure Cognitive Search REST APIs.

Os métodos de solicitação usados neste tutorial são POST, PUT e GET.The request methods used in this tutorial are POST, PUT, and GET. Você usará os métodos para fazer quatro chamadas à API ao serviço de pesquisa: criar uma fonte de dados, um conjunto de habilidades, um índice e um indexador.You'll use the methods to make four API calls to your search service: create a data source, a skillset, an index, and an indexer.

Em Cabeçalhos, defina "Content-Type" como application/json e api-key como a chave de API de administração do serviço da Pesquisa Cognitiva do Azure.In Headers, set "Content-type" to application/json and set api-key to the admin api-key of your Azure Cognitive Search service. Depois de definir os cabeçalhos, você poderá usá-los para cada solicitação neste exercício.Once you set the headers, you can use them for every request in this exercise.

URL e cabeçalho da solicitação do PostmanPostman request URL and header

3 – Criar o pipeline3 - Create the pipeline

No Azure Cognitive Search, o enriquecimento ocorre durante a indexação (ou a ingestão de dados).In Azure Cognitive Search, enrichment occurs during indexing (or data ingestion). Esta parte do passo a passo cria quatro objetos: fonte de dados, definição de índice, conjunto de habilidades e indexador.This part of the walkthrough creates four objects: data source, index definition, skillset, indexer.

Etapa 1: Criar uma fonte de dadosStep 1: Create a data source

Um objeto de fonte de dados fornece a cadeia de conexão ao contêiner de blob que contém os arquivos.A data source object provides the connection string to the Blob container containing the files.

  1. Use POST e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço.Use POST and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/datasources?api-version=2020-06-30
    
  2. No Corpo da solicitação, copie a definição JSON a seguir, substituindo a connectionString pela conexão real da conta de armazenamento.In request Body, copy the following JSON definition, replacing the connectionString with the actual connection of your storage account.

    Lembre-se de editar o nome do contêiner também.Remember to edit the container name as well. Sugerimos "cog-search-demo" para o nome do contêiner em uma etapa anterior.We suggested "cog-search-demo" for the container name in an earlier step.

    {
      "name" : "cog-search-demo-ds",
      "description" : "Demo files to demonstrate cognitive search capabilities.",
      "type" : "azureblob",
      "credentials" :
      { "connectionString" :
        "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-ACCOUNT-KEY>;"
      },
      "container" : { "name" : "<YOUR-BLOB-CONTAINER-NAME>" }
    }
    
  3. Enviar a solicitação.Send the request. Você deverá ver um código de status 201 confirmando o êxito.You should see a status code of 201 confirming success.

Se você receber um erro 403 ou 404, verifique a construção da solicitação: api-version=2020-06-30 deve ser no ponto de extremidade, api-key deve estar no cabeçalho após Content-Type, e seu valor deve ser válido para um serviço de pesquisa.If you got a 403 or 404 error, check the request construction: api-version=2020-06-30 should be on the endpoint, api-key should be in the Header after Content-Type, and its value must be valid for a search service. É recomendável executar o documento JSON por meio de um validador JSON online para verificar se a sintaxe está correta.You might want to run the JSON document through an online JSON validator to make sure the syntax is correct.

Etapa 2: Criar um conjunto de habilidadesStep 2: Create a skillset

Um objeto de conjunto de habilidades é um conjunto de etapas de enriquecimento aplicado ao conteúdo.A skillset object is a set of enrichment steps applied to your content.

  1. Use PUT e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/skillsets/cog-search-demo-sd?api-version=2020-06-30
    
  2. No Corpo da solicitação, copie a definição JSON abaixo.In request Body, copy the JSON definition below. Esse conjunto de habilidades consiste nas habilidades internas a seguir.This skillset consists of the following built-in skills.

    HabilidadeSkill DescriçãoDescription
    Reconhecimento de EntidadeEntity Recognition Extrai os nomes de pessoas, organizações e localizações do conteúdo no contêiner de blobs.Extracts the names of people, organizations, and locations from content in the blob container.
    Detecção de IdiomaLanguage Detection Detecta o idioma do conteúdo.Detects the content's language.
    Divisão de textoText Split Divide um conteúdo grande em partes menores antes de chamar a habilidade de extração de frases-chave.Breaks large content into smaller chunks before calling the key phrase extraction skill. Extração de frase-chave aceita entradas de 50.000 caracteres ou menos.Key phrase extraction accepts inputs of 50,000 characters or less. Alguns dos arquivos de exemplo precisam dividir para se ajustar dentro desse limite.A few of the sample files need splitting up to fit within this limit.
    Extração de Frases-chaveKey Phrase Extraction Extrai as principais frases-chave.Pulls out the top key phrases.

    Cada uma delas executa no conteúdo do documento.Each skill executes on the content of the document. Durante o processamento, a Pesquisa Cognitiva do Azure abre cada documento para ler o conteúdo de diferentes formatos de arquivo.During processing, Azure Cognitive Search cracks each document to read content from different file formats. Encontrado um texto de origem no arquivo de origem é colocado em um campo gerado content, uma para cada documento.Found text originating in the source file is placed into a generated content field, one for each document. Dessa forma, a entrada se torna "/document/content".As such, the input becomes "/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".For key phrase extraction, because we use the text splitter skill to break larger files into pages, the context for the key phrase extraction skill is "document/pages/*" (for each page in the document) instead of "/document/content".

    {
      "description": "Extract entities, detect language and extract key-phrases",
      "skills":
      [
        {
          "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
          "categories": [ "Person", "Organization", "Location" ],
          "defaultLanguageCode": "en",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "persons", "targetName": "persons" },
            { "name": "organizations", "targetName": "organizations" },
            { "name": "locations", "targetName": "locations" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "languageCode", "targetName": "languageCode" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "textSplitMode" : "pages",
          "maximumPageLength": 4000,
          "inputs": [
            { "name": "text", "source": "/document/content" },
            { "name": "languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "textItems", "targetName": "pages" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
          "context": "/document/pages/*",
          "inputs": [
            { "name": "text", "source": "/document/pages/*" },
            { "name":"languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "keyPhrases", "targetName": "keyPhrases" }
          ]
        }
      ]
    }
    

    Uma representação gráfica do conjunto de qualificações é mostrada abaixo.A graphical representation of the skillset is shown below.

    Entender um conjunto de habilidadesUnderstand a skillset

  3. Enviar a solicitação.Send the request. O Postman deverá retornar um código de status 201 confirmando o êxito.Postman should return a status code of 201 confirming success.

Observação

Saídas podem ser mapeadas para um índice usado como entrada para uma habilidade de downstream, ou ambos, como é o caso com o código de idioma.Outputs can be mapped to an index, used as input to a downstream skill, or both as is the case with language code. No índice, um código de idioma é útil para filtragem.In the index, a language code is useful for filtering. 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.As an input, language code is used by text analysis skills to inform the linguistic rules around word breaking. Para obter mais informações sobre conceitos básicos do conjunto de qualificações, consulte como definir um conjunto de qualificações.For more information about skillset fundamentals, see How to define a skillset.

Etapa 3: Crie um índiceStep 3: Create an index

Um índice fornece o esquema usado para criar a expressão física do conteúdo em índices invertidos e outros constructos na Pesquisa Cognitiva do Azure.An index provides the schema used to create the physical expression of your content in inverted indexes and other constructs in Azure Cognitive 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 os comportamentos na Pesquisa Cognitiva do Azure.The largest component of an index is the fields collection, where data type and attributes determine contents and behaviors in Azure Cognitive Search.

  1. Use PUT e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço, para nomear o índice.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your index.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx?api-version=2020-06-30
    
  2. No Corpo da solicitação, copie a definição JSON a seguir.In request Body, copy the following JSON definition. O campo content armazena o documento propriamente dito.The content field stores the document itself. Os campos adicionais para languageCode, keyPhrases e organizations representam novas informações (campos e valores) criadas pelo conjunto de habilidades.Additional fields for languageCode, keyPhrases, and organizations represent new information (fields and values) created by the skillset.

    {
      "fields": [
        {
          "name": "id",
          "type": "Edm.String",
          "key": true,
          "searchable": true,
          "filterable": false,
          "facetable": false,
          "sortable": true
        },
        {
          "name": "metadata_storage_name",
          "type": "Edm.String",
          "searchable": false,
          "filterable": false,
          "facetable": false,
          "sortable": false
        },
        {
          "name": "content",
          "type": "Edm.String",
          "sortable": false,
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "languageCode",
          "type": "Edm.String",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "keyPhrases",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "persons",
          "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": "locations",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        }
      ]
    }
    
  3. Enviar a solicitação.Send the request. O Postman deverá retornar um código de status 201 confirmando o êxito.Postman should return a status code of 201 confirming success.

Etapa 4: Criar e executar um indexadorStep 4: Create and run an indexer

Um Indexador conduz o pipeline.An Indexer drives the 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.The three components you have created thus far (data source, skillset, index) are inputs to an indexer. A criação do indexador na Pesquisa Cognitiva do Azure é o evento que coloca todo o pipeline em movimento.Creating the indexer on Azure Cognitive Search is the event that puts the entire pipeline into motion.

  1. Use PUT e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço, para nomear o indexador.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[servicename].search.windows.net/indexers/cog-search-demo-idxr?api-version=2020-06-30
    
  2. No Corpo da solicitação, copie a definição JSON abaixo.In request Body, copy the JSON definition below. Observe os elementos de mapeamento de campo; esses mapeamentos são importantes porque definem o fluxo de dados.Notice the field mapping elements; these mappings are important because they define the data flow.

    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.The fieldMappings are processed before the skillset, sending content from the data source to target fields in an index. Você usará mapeamentos de campo para enviar o conteúdo existente e não modificado ao índice.You'll use field mappings to send existing, unmodified content to the index. Se os tipos e os nomes do campo forem os mesmos em ambas as extremidades, nenhum mapeamento será necessário.If field names and types are the same at both ends, no mapping is required.

    Os outputFieldMappings destinam-se aos campos criados por habilidades e, portanto, são processados após a execução do conjunto de habilidades.The outputFieldMappings are for fields created by skills, and thus processed after the skillset has run. As referências a sourceFieldNames em outputFieldMappings não existirão enquanto a quebra de documento ou o enriquecimento não as criar.The references to sourceFieldNames in outputFieldMappings don't exist until document cracking or enrichment creates them. O targetFieldName é um campo em um índice, definido no esquema de índice.The targetFieldName is a field in an index, defined in the index schema.

    {
      "name":"cog-search-demo-idxr",
      "dataSourceName" : "cog-search-demo-ds",
      "targetIndexName" : "cog-search-demo-idx",
      "skillsetName" : "cog-search-demo-ss",
      "fieldMappings" : [
        {
          "sourceFieldName" : "metadata_storage_path",
          "targetFieldName" : "id",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "metadata_storage_name",
          "targetFieldName" : "metadata_storage_name",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "content",
          "targetFieldName" : "content"
        }
      ],
      "outputFieldMappings" :
      [
        {
          "sourceFieldName" : "/document/persons",
          "targetFieldName" : "persons"
        },
        {
          "sourceFieldName" : "/document/organizations",
          "targetFieldName" : "organizations"
        },
        {
          "sourceFieldName" : "/document/locations",
          "targetFieldName" : "locations"
        },
        {
          "sourceFieldName" : "/document/pages/*/keyPhrases/*",
          "targetFieldName" : "keyPhrases"
        },
        {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "languageCode"
        }
      ],
      "parameters":
      {
        "maxFailedItems":-1,
        "maxFailedItemsPerBatch":-1,
        "configuration":
        {
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default",
          "firstLineContainsHeaders": false,
          "delimitedTextDelimiter": ","
        }
      }
    }
    
  3. Enviar a solicitação.Send the request. O Postman deverá retornar um código de status 201 confirmando o processamento bem-sucedido.Postman should return a status code of 201 confirming successful processing.

    Espere essa ação levar vários minutos para ser concluída.Expect this step to take several minutes to complete. Embora o conjunto de dados é pequeno, capacidades analíticas são intensivas na computação.Even though the data set is small, analytical skills are computation-intensive.

Observação

Criar um indexador invoca o pipeline.Creating an indexer invokes the pipeline. Se houver problemas ao acessar os dados, as entradas de mapeamento e saídas ou ordem de operações, eles aparecem neste estágio.If there are problems reaching the data, mapping inputs and outputs, or order of operations, they appear at this stage. Para executar novamente o pipeline com as alterações de código ou script, você precisará primeiro descarte de objetos.To re-run the pipeline with code or script changes, you might need to drop objects first. Para saber mais, confira Reiniciar e Reexecutar.For more information, see Reset and re-run.

Sobre os parâmetros do indexadorAbout indexer parameters

O script define "maxFailedItems" como -1, que instrui o mecanismo de indexação para ignorar erros durante a importação de dados.The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. Isso é aceitável porque há poucos documentos na fonte de dados de demonstração.This is acceptable because there are so few documents in the demo data source. Para uma fonte de dados maior, você definirá o valor maior que 0.For a larger data source, you would set the value to greater than 0.

A instrução "dataToExtract":"contentAndMetadata" instrui o indexador a extrair automaticamente o conteúdo de diferentes formatos de arquivo, bem como os metadados relacionados a cada arquivo.The "dataToExtract":"contentAndMetadata" statement tells the indexer to automatically extract the content from different file formats as well as metadata related to each file.

Quando o conteúdo é extraído, você pode definir imageAction para extrair o texto da imagem foi encontrada na fonte de dados.When content is extracted, you can set imageAction to extract text from images found in the data source. 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.The "imageAction":"generateNormalizedImages" configuration, combined with the OCR Skill and Text Merge Skill, tells the indexer to extract text from the images (for example, the word "stop" from a traffic Stop sign), and embed it as part of the content field. 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.This behavior applies to both the images embedded in the documents (think of an image inside a PDF), as well as images found in the data source, for instance a JPG file.

4 – Monitorar a indexação4 - Monitor indexing

A indexação e o enriquecimento são iniciados assim que você envia a solicitação Criar Indexador.Indexing and enrichment commence as soon as you submit the Create Indexer request. Dependendo das habilidades cognitivas definidas, a indexação pode levar algum tempo.Depending on which cognitive skills you defined, indexing can take a while. Para descobrir se o indexador ainda está em execução, envie a solicitação a seguir para verificar o status do indexador.To find out whether the indexer is still running, send the following request to check the indexer status.

  1. Use GET e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço, para nomear o indexador.Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexers/cog-search-demo-idxr/status?api-version=2020-06-30
    
  2. Examine a resposta para saber se o indexador está em execução ou para exibir informações de erro e aviso.Review the response to learn whether the indexer is running, or to view error and warning information.

Se você estiver usando a Camada gratuita, a seguinte mensagem será esperada: "Não foi possível extrair o conteúdo nem os metadados do documento.If you are using the Free tier, the following message is expected: `"Could not extract content or metadata from your document. Texto extraído truncado para '32.768' caracteres".Truncated extracted text to '32768' characters". Essa mensagem é exibida porque a indexação de blob na Camada gratuita tem umlimite de 32 mil caracteres na extração de caracteres.This message appears because blob indexing on the Free tier has a32K limit on character extraction. Você não verá essa mensagem para esse conjunto de dados em camadas superiores.You won't see this message for this data set on higher tiers.

Observação

Os avisos são comuns em alguns cenários e nem sempre indicam um problema.Warnings are common in some scenarios and do not always indicate a problem. Por exemplo, se um contêiner de blobs incluir arquivos de imagem e o pipeline não tratar imagens, você receberá um aviso informando que as imagens não foram processadas.For example, if a blob container includes image files, and the pipeline doesn't handle images, you'll get a warning stating that images were not processed.

Agora que você criou campos e informações, vamos executar algumas consultas para entender o valor da pesquisa cognitiva, pois ela se relaciona a um cenário de pesquisa típico.Now that you've created new fields and information, let's run some queries to understand the value of cognitive search as it relates to a typical search scenario.

Lembre-se de que começamos com o conteúdo do blob, em que todo o documento é empacotado em um único campo content.Recall that we started with blob content, where the entire document is packaged into a single content field. Pesquise esse campo e encontre correspondências para as consultas.You can search this field and find matches to your queries.

  1. Use GET e a URL a seguir, substituindo NOME-DO-SERVIÇO pelo nome real do serviço, para pesquisar instâncias de um termo ou uma frase, retornando o campo content e uma contagem dos documentos correspondentes.Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to search for instances of a term or phrase, returning the content field and a count of the matching documents.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$count=true&$select=content&api-version=2020-06-30
    

    Os resultados dessa consulta retornam o conteúdo do documento, que é o mesmo resultado que você obterá se usar o indexador de blob sem o pipeline da pesquisa cognitiva.The results of this query return document contents, which is the same result you would get if used the blob indexer without the cognitive search pipeline. Esse campo é pesquisável, mas não funcionará se você quiser usar facetas, filtros ou o Preenchimento automático.This field is searchable, but unworkable if you want to use facets, filters, or autocomplete.

    Saída do campo de conteúdoContent field output

  2. Para a segunda consulta, retorne alguns dos campos criados pelo pipeline (pessoas, organizações, localizações e languageCode).For the second query, return some of the new fields created by the pipeline (persons, organizations, locations, languageCode). Estamos omitindo as keyPhrases por questões de brevidade, mas você deverá incluí-las se quiser ver esses valores.We're omitting keyPhrases for brevity, but you should include it if you want to see those values.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$count=true&$select=metadata_storage_name,persons,organizations,locations,languageCode&api-version=2020-06-30
    

    Os campos na instrução $select contêm informações criadas com base nas funcionalidades de processamento de idioma natural dos Serviços Cognitivos.The fields in the $select statement contain new information created from the natural language processing capabilities of Cognitive Services. Como você pode esperar, há algum ruído nos resultados e na variação entre documentos, mas, em muitas instâncias, os modelos analíticos produzem resultados precisos.As you might expect, there is some noise in the results and variation across documents, but in many instances, the analytical models produce accurate results.

    A imagem a seguir mostra os resultados da letra aberta de Satya Nadella depois de assumir o cargo de CEO na Microsoft.The following image shows results for Satya Nadella's open letter upon assuming the CEO role at Microsoft.

    Saída do pipelinePipeline output

  3. Para ver como você pode aproveitar esses campos, adicione um parâmetro de faceta para retornar uma agregação de documentos correspondentes por localização.To see how you might take advantage of these fields, add a facet parameter to return an aggregation of matching documents by location.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&facet=locations&api-version=2020-06-30
    

    Neste exemplo, para cada localização, há duas ou três correspondências.In this example, for each location, there are 2 or 3 matches.

    Saída da facetaFacet output

  4. Neste exemplo final, aplique um filtro na coleção de organizações, retornando duas correspondências para critérios de filtragem com base na NASDAQ.In this final example, apply a filter on the organizations collection, returning two matches for filter criteria based on NASDAQ.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$filter=organizations/any(organizations: organizations eq 'NASDAQ')&$select=metadata_storage_name,organizations&$count=true&api-version=2020-06-30
    

Essas consultas ilustram algumas das maneiras pelas quais você pode trabalhar com a sintaxe de consulta e os filtros em campos criados pela pesquisa cognitiva.These queries illustrate a few of the ways you can work with query syntax and filters on new fields created by cognitive 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.For more query examples, see Examples in Search Documents REST API, Simple syntax query examples, and Full Lucene query examples.

Redefinir e execute novamenteReset and rerun

Nos primeiros estágios experimentais de desenvolvimento, a abordagem mais prática para a iteração de design é excluir os objetos do Azure Cognitive Search e permitir que o código os recompile.In the early experimental stages of development, the most practical approach for design iteration is to delete the objects from Azure Cognitive Search and allow your code to rebuild them. Nomes de recurso são exclusivos.Resource names are unique. Excluir um objeto permite que você recriá-la usando o mesmo nome.Deleting an object lets you recreate it using the same name.

Use o portal para excluir índices, indexadores, fontes de dados e conjuntos de habilidades.You can use the portal to delete indexes, indexers, data sources, and skillsets. Ao excluir o indexador, também é possível excluir o índice, o conjunto de habilidades e a fonte de dados ao mesmo tempo.When you delete the indexer, you can optionally, selectively delete the index, skillset, and data source at the same time.

Excluir objetos de pesquisaDelete search objects

Ou então, use DELETE e forneça URLs para cada objeto.Or use DELETE and provide URLs to each object. O comando a seguir exclui um indexador.The following command deletes an indexer.

DELETE https://[YOUR-SERVICE-NAME].search.windows.net/indexers/cog-search-demo-idxr?api-version=2020-06-30

Código de status 204 é retornado na exclusão com êxito.Status code 204 is returned on successful deletion.

ObservaçõesTakeaways

Este tutorial demonstra as etapas básicas para a criação de um pipeline de indexação enriquecido durante a criação de componentes: uma fonte de dados, o conjunto de qualificações, o índice e o indexador.This tutorial demonstrates the basic steps for building an enriched indexing pipeline through the creation of component parts: a data source, skillset, index, and indexer.

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.Built-in skills were introduced, along with skillset definition and the mechanics of chaining skills together through inputs and outputs. Você também aprendeu que outputFieldMappings na definição do indexador é necessário para encaminhar valores enriquecidos do pipeline em um índice pesquisável em um serviço da Pesquisa Cognitiva do Azure.You also learned that outputFieldMappings in the indexer definition is required for routing enriched values from the pipeline into a searchable index on an Azure Cognitive Search service.

Por fim, você aprendeu como resultados de teste e reinicie o sistema para obter mais iterações.Finally, you learned how to test results and reset the system for further iterations. Você aprendeu que emitir consultas em relação ao índice retorna a saída criada pelo pipeline de indexação enriquecido.You learned that issuing queries against the index returns the output created by the enriched indexing pipeline.

Limpar os recursosClean up resources

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.When you're working in your own subscription, at the end of a project, it's a good idea to remove the resources that you no longer need. Recursos deixados em execução podem custar dinheiro.Resources left running can cost you money. Você pode excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.You can delete resources individually or delete the resource group to delete the entire set of resources.

Encontre e gerencie recursos no portal usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.You can find and manage resources in the portal, using the All resources or Resource groups link in the left-navigation pane.

Próximas etapasNext steps

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.Now that you're familiar with all of the objects in an AI enrichment pipeline, let's take a closer look at skillset definitions and individual skills.