Tutorial: Use REST e IA para gerar conteúdo pesmável a partir de bolhas AzureTutorial: Use REST and AI to generate searchable content from Azure blobs

Se tiver texto ou imagens não estruturados no armazenamento do Azure Blob, um gasoduto de enriquecimento de IA pode extrair informações e criar novos conteúdos a partir de bolhas que são úteis para pesquisas de texto completo ou cenários de 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 REST foca-se no texto, aplicando a deteção de linguagem e processamento de linguagem natural para criar novos campos que você pode alavancar 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 utiliza o Carteiro e as APIs search REST para executar as seguintes tarefas:This tutorial uses Postman and the Search REST APIs to perform the following tasks:

  • Crie serviços e uma coleção de Carteiro.Set up services and a Postman collection.
  • Criar um oleoduto de enriquecimento que extraia texto, deteta linguagem, reconhece entidades e deteta frases-chave.Create an enrichment pipeline that extracts text, detects language, recognizes entities, and detects key phrases.
  • Crie um índice para armazenar a saída (conteúdo bruto, mais pares de valor-nome gerados pelo gasoduto).Create an index to store the output (raw content, plus pipeline-generated name-value pairs).
  • Execute o oleoduto para realizar transformações e análises, e para carregar o índice.Execute the pipeline to perform transformations and analysis, and to load the index.
  • Explore resultados utilizando a pesquisa completa por texto e uma sintaxe de consulta rica.Explore results using full text search and a rich query syntax.

Se não tiver uma subscrição 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.

Descrição GeralOverview

Este tutorial utiliza C# e o Azure Cognitive Search REST APIs para criar uma fonte de dados, índice, indexante e skillset.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 Azure Blob, e depois executá-los através de um skillset para extrair entidades, frases-chave e outro texto nos ficheiros 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.

Este skillset usa habilidades incorporadas baseadas em APIs de Serviços Cognitivos.This skillset uses built-in skills based on Cognitive Services APIs. As etapas no oleoduto incluem a deteção de linguagem 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 pode alavancar em consultas, facetas e filtros.New information is stored in new fields that you can leverage in queries, facets, and filters.

Pré-requisitosPrerequisites

Nota

Você pode usar o serviço gratuito para este tutorial.You can use the free service for this tutorial. Um serviço de pesquisa gratuito limita-o a três índices, três indexantes 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, certifique-se de ter 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.

Transferir ficheirosDownload files

  1. Abra esta pasta OneDrive e no canto superior esquerdo, clique em Baixar para copiar os ficheiros para o seu 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 no ficheiro zip e selecione Extract All.Right-click the zip file and select Extract All. Existem 14 ficheiros de vários tipos.There are 14 files of various types. Vais usar 7 para este exercício.You'll use 7 for this exercise.

Opcionalmente, também pode descarregar o código fonte, um ficheiro de recolha do Carteiro, 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 a Azure Cognitive Search para indexar e consultas, Serviços Cognitivos no backend para enriquecimento de IA, e armazenamento Azure Blob 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 fica sob a alocação gratuita de 20 transações por indexante por dia em Serviços Cognitivos, pelo que os únicos serviços que precisa de criar são a 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 tanto na mesma região como no grupo de recursos para proximidade e gestão.If possible, create both in the same region and resource group for proximity and manageability. Na prática, a sua conta de Armazenamento Azure pode estar em qualquer região.In practice, your Azure Storage account can be in any region.

Comece com o armazenamento AzureStart with Azure Storage

  1. Inscreva-se no portal Azure e clique + Criar Recurso.Sign in to the Azure portal and click + Create Resource.

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

    Criar conta de ArmazenamentoCreate Storage account

  3. No separador Básicos, são necessários os seguintes itens.In the Basics tab, the following items are required. Aceite os incumprimentos para tudo o resto.Accept the defaults for everything else.

    • Grupo de recursos.Resource group. Selecione um existente ou crie um novo, mas use o mesmo grupo para todos os serviços para que possa geri-los coletivamente.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 acha que pode ter múltiplos recursos do mesmo tipo, use o nome para desambiguar 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.

    • Localização.Location. Se possível, escolha o mesmo local utilizado para a Azure Cognitive Search and Cognitive Services.If possible, choose the same location used for Azure Cognitive Search and Cognitive Services. Um único local anula as cargas de largura de banda.A single location voids bandwidth charges.

    • Tipo de Conta.Account Kind. Escolha o predefinido, StorageV2 (finalidade geral v2).Choose the default, StorageV2 (general purpose v2).

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

  5. Uma vez criado, clique em Ir ao recurso para abrir a página 'Vista Geral'.Once it's created, click Go to the resource to open the Overview page.

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

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

  8. Selecione a demonstração de pesquisa de cog e, em seguida, clique em Upload para abrir a pasta onde guardou os ficheiros de descarregamento.Select cog-search-demo and then click Upload to open the folder where you saved the download files. Selecione todos os ficheiros de não imagem.Select all of the non-image files. Devia ter 7 ficheiros.You should have 7 files. Clique em OK para carregar.Click OK to upload.

    Carregar ficheiros de amostrasUpload sample files

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

    1. Procure de volta à página geral da 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 esquerdo, selecione as teclas de acesso e copie uma das cordas de ligação.In the left navigation pane, select Access keys and copy one of the connection strings.

    A cadeia de ligação é um 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. Guarde o fio de ligação para o Bloco de Notas.Save the connection string to Notepad. Vai precisar mais tarde ao configurar a ligação à fonte de dados.You'll need it later when setting up the data source connection.

Serviços CognitivosCognitive Services

O enriquecimento de IA é apoiado por Serviços Cognitivos, incluindo Análise de Texto e Visão Computacional para o processamento de linguagem natural e imagem.AI enrichment is backed by Cognitive Services, including Text Analytics and Computer Vision for natural language and image processing. Se o seu objetivo fosse completar um protótipo ou projeto real, você iria neste momento providenciar Serviços Cognitivos (na mesma região que a Azure Cognitive Search) para que você possa anexá-lo a 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, você pode ignorar o fornecimento de recursos porque a Azure Cognitive Search pode ligar-se aos Serviços Cognitivos nos bastidores e dar-lhe 20 transações gratuitas por indexer executado.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. Uma vez que este tutorial utiliza 7 transações, a atribuição gratuita é suficiente.Since this tutorial uses 7 transactions, the free allocation is sufficient. Para projetos maiores, planeie o fornecimento de Serviços Cognitivos no nível S0 pay-as-you-go.For larger projects, plan on provisioning Cognitive Services at the pay-as-you-go S0 tier. Para obter mais informações, consulte Os Serviços Cognitivos anexados.For more information, see Attach Cognitive Services.

O terceiro componente é Azure Cognitive Search, que pode criar no portal.The third component is Azure Cognitive Search, which you can create in the portal. Pode utilizar o nível Free para completar este walkthrough.You can use the Free tier to complete this walkthrough.

Tal como acontece com o armazenamento da Azure Blob, aproveite um momento para recolher a chave de acesso.As with Azure Blob storage, take a moment to collect the access key. Mais à frente, quando iniciar os pedidos estruturantes, terá de fornecer o ponto final e a tecla api de administração utilizada para autenticar cada pedido.Further on, when you begin structuring requests, you will need to provide the endpoint and admin api-key used to authenticate each request.

  1. Inscreva-se no portal Azure,e na página de Visão Geral do seu serviço de pesquisa, obtenha o nome do 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. Pode confirmar o seu nome de serviço revendo o URL do ponto final.You can confirm your service name by reviewing the endpoint URL. Se o seu URL de ponto final https://mydemo.search.windows.net fosse, o seu nome de serviço seria mydemo .If your endpoint URL were https://mydemo.search.windows.net, your service name would be mydemo.

  2. Em Definições > Teclas, obtenha uma chave de administração para todos os direitos sobre o serviço.In Settings > Keys, get an admin key for full rights on the service. Existem duas chaves de administração intercambiáveis, previstas para a continuidade do negócio, caso precise de rolar uma.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Pode utilizar a tecla primária ou secundária nos pedidos de adição, modificação e eliminação de objetos.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

    Pegue a chave de consulta também.Get the query key as well. É uma boa prática emitir pedidos de consulta com acesso apenas de leitura.It's a best practice to issue query requests with read-only access.

    Obtenha o nome de serviço e as chaves de administração e consulta

Todos os pedidos requerem uma chave API no cabeçalho de cada pedido enviado ao seu serviço.All requests require an api-key in the header of every request sent to your service. Uma chave válida estabelece confiança, por pedido, entre o pedido de envio do pedido e o serviço que o trata.A valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

2 - Configurar carteiro2 - Set up Postman

Inicie o Postman e configure um pedido de HTTP.Start Postman and set up an HTTP request. Se não estiver familiarizado com esta ferramenta, consulte As APIs de Pesquisa Cognitiva explore Azure.If you are unfamiliar with this tool, see Explore Azure Cognitive Search REST APIs.

Os métodos de pedido utilizados neste tutorial são POST, PUT e GET.The request methods used in this tutorial are POST, PUT, and GET. Utilizará os métodos para fazer quatro chamadas API para o seu serviço de pesquisa: criar uma fonte de dados, um skillset, um índice e um indexante.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, desconfie "Content-type" application/json e desaver-se api-key com a chave api de administração do seu serviço de Pesquisa Cognitiva Azure.In Headers, set "Content-type" to application/json and set api-key to the admin api-key of your Azure Cognitive Search service. Uma vez definidos os cabeçalhos, pode usá-los para todos os pedidos neste exercício.Once you set the headers, you can use them for every request in this exercise.

Carteiro solicita URL e cabeçalhoPostman request URL and header

3 - Criar o gasoduto3 - Create the pipeline

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

Passo 1: criar uma origem de dadosStep 1: Create a data source

Um objeto de origem de dados fornece o fio de ligação ao recipiente Blob que contém os ficheiros.A data source object provides the connection string to the Blob container containing the files.

  1. Utilize o POST e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu 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. A pedido Body, copie a seguinte definição JSON, substituindo a connectionString com a ligação real da sua 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 recipiente também.Remember to edit the container name as well. Sugerimos "cog-search-demo" para o nome do contentor num passo 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. Envie o pedido.Send the request. Deve ver um código de estado de 201 confirmando o sucesso.You should see a status code of 201 confirming success.

Se obtiver um erro 403 ou 404, verifique a construção do pedido: api-version=2020-06-30 deve estar no ponto final, api-key deve estar no Cabeçalho após Content-Type e o 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. É melhor executar o documento JSON através de um validador JSON online para se certificar de que a sintaxe está correta.You might want to run the JSON document through an online JSON validator to make sure the syntax is correct.

Passo 2: Criar um skillsetStep 2: Create a skillset

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

  1. Utilize o PUT e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu 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. A pedido Body, copie a definição JSON abaixo.In request Body, copy the JSON definition below. Esta habilidade consiste nas seguintes competências incorporadas.This skillset consists of the following built-in skills.

    HabilidadeSkill DescriptionDescription
    Reconhecimento de entidadeEntity Recognition Extrai os nomes de pessoas, organizações e locais de conteúdo no recipiente blob.Extracts the names of people, organizations, and locations from content in the blob container.
    Deteção de IdiomaLanguage Detection Deteta a linguagem do conteúdo.Detects the content's language.
    Divisão de TextoText Split Quebra o conteúdo grande em pedaços menores antes de chamar a habilidade de extração da frase-chave.Breaks large content into smaller chunks before calling the key phrase extraction skill. A extração de expressões-chave aceita entradas de 50 000 carateres ou menos.Key phrase extraction accepts inputs of 50,000 characters or less. Alguns dos ficheiros de exemplo precisam de ser divididos para caberem dentro deste limite.A few of the sample files need splitting up to fit within this limit.
    Extração de Expressões-ChaveKey Phrase Extraction Tira as frases-chave de topo.Pulls out the top key phrases.

    Cada competência é executada no conteúdo do documento.Each skill executes on the content of the document. Durante o processamento, a Azure Cognitive Search quebra cada documento para ler conteúdo de diferentes formatos de ficheiros.During processing, Azure Cognitive Search cracks each document to read content from different file formats. O texto encontrado proveniente do ficheiro de origem é colocado num campo content gerado (um para cada documento).Found text originating in the source file is placed into a generated content field, one for each document. Como tal, a entrada torna-se "/document/content" .As such, the input becomes "/document/content".

    Para a extração de frases-chave, porque utilizamos a habilidade do separador de texto para dividir ficheiros 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" }
          ]
        }
      ]
    }
    

    Veja a seguir uma representação gráfica do conjunto de competências.A graphical representation of the skillset is shown below.

    Compreender um skillsetUnderstand a skillset

  3. Envie o pedido.Send the request. O carteiro deve devolver um código de estado de 201 confirmando o sucesso.Postman should return a status code of 201 confirming success.

Nota

As saídas podem ser mapeadas para um índice, utilizadas como entradas para uma competência a jusante ou ambas, como é o caso do 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, o código de idioma é útil para a filtragem.In the index, a language code is useful for filtering. Como entrada, o código de idioma é utilizado pelas competências de análise de texto para informar sobre as regras linguísticas em torno da separação 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 acerca das noções básicas do conjunto de competências, veja Como definir um conjunto de competências.For more information about skillset fundamentals, see How to define a skillset.

Passo 3: Criar um índiceStep 3: Create an index

Um índice fornece o esquema usado para criar a expressão física do seu conteúdo em índices invertidos e outras construções em Azure Cognitive Search.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 recolha de campos, onde o tipo de dados e os atributos determinam conteúdos e comportamentos na Pesquisa Cognitiva 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. Utilize o PUT e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu serviço, para nomear o seu í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. A pedido Body, copiar a seguinte definição JSON.In request Body, copy the following JSON definition. O content campo armazena o documento em si.The content field stores the document itself. Campos adicionais languageCode keyPhrases para, e organizations representam novas informações (campos e valores) criadas pelo skillset.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. Envie o pedido.Send the request. O carteiro deve devolver um código de estado de 201 confirmando o sucesso.Postman should return a status code of 201 confirming success.

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

Um Indexer conduz o oleoduto.An Indexer drives the pipeline. Os três componentes que criou até agora (fonte de dados, skillset, índice) são entradas para um indexante.The three components you have created thus far (data source, skillset, index) are inputs to an indexer. Criar o indexante na Azure Cognitive Search é o evento que coloca todo o oleoduto em movimento.Creating the indexer on Azure Cognitive Search is the event that puts the entire pipeline into motion.

  1. Utilize o PUT e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu serviço, para nomear o seu indexante.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. A pedido Body, copie a definição JSON abaixo.In request Body, copy the JSON definition below. Note os elementos de mapeamento de campo; estes 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 skillset, enviando conteúdo da fonte de dados para campos-alvo num í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 conteúdo existente e não modificado para o índice.You'll use field mappings to send existing, unmodified content to the index. Se os nomes e tipos de campo forem os mesmos em ambas as extremidades, não é necessário mapear.If field names and types are the same at both ends, no mapping is required.

    São outputFieldMappings para campos criados por competências, e assim processados após a corrida do skillset.The outputFieldMappings are for fields created by skills, and thus processed after the skillset has run. As referências ao sourceFieldNames in outputFieldMappings não existem até que o documento de rachadura ou enriquecimento as crie.The references to sourceFieldNames in outputFieldMappings don't exist until document cracking or enrichment creates them. É targetFieldName um campo num í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. Envie o pedido.Send the request. O carteiro deve devolver um código de estado de 201 confirmando o processamento bem sucedido.Postman should return a status code of 201 confirming successful processing.

    A conclusão deste passo demora vários minutos.Expect this step to take several minutes to complete. Apesar de o conjunto de dados ser pequeno, as competências analíticas realizam um processo de computação intensa.Even though the data set is small, analytical skills are computation-intensive.

Nota

A criação de um indexador invoca o pipeline.Creating an indexer invokes the pipeline. Se houver problemas em atingir os dados, com o mapeamento de entradas e saídas ou com a ordem das operações, estes vão surgir nesta fase.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, pode ter de remover primeiro os objetos.To re-run the pipeline with code or script changes, you might need to drop objects first. Para obter mais informações, veja Repor e executar novamente.For more information, see Reset and re-run.

Sobre os parâmetros indexantesAbout indexer parameters

O script define "maxFailedItems" como -1, o que indica ao motor de indexação para ignorar os erros durante a importação de dados.The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. Isto é aceitável porque há tão 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 origem de dados maior, deve definir o valor com um número maior que 0.For a larger data source, you would set the value to greater than 0.

A "dataToExtract":"contentAndMetadata" declaração diz ao indexante para extrair automaticamente o conteúdo de diferentes formatos de ficheiros, bem como metadados relacionados com cada ficheiro.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, pode definir imageAction para extrair texto das imagens existentes na origem de dados.When content is extracted, you can set imageAction to extract text from images found in the data source. A "imageAction":"generateNormalizedImages" configuração, combinada com a Habilidade de Fusão de OCR e A Capacidade de Fusão de Texto, diz ao indexante para extrair texto das imagens (por exemplo, a palavra "parar" de um sinal de stop de tráfego), e incorporá-lo 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. Este comportamento aplica-se tanto às imagens incorporadas nos documentos (tal como uma imagem num PDF) como às imagens existentes na origem de dados, por exemplo, um ficheiro 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 - Monitorização da indexação4 - Monitor indexing

A indexação e enriquecimento começam assim que submeter o pedido de 'Criar Indexer'.Indexing and enrichment commence as soon as you submit the Create Indexer request. Dependendo das capacidades cognitivas que definiu, a indexação pode demorar um pouco.Depending on which cognitive skills you defined, indexing can take a while. Para saber se o indexador ainda está em execução, envie o seguinte pedido para verificar o estado do indexador.To find out whether the indexer is still running, send the following request to check the indexer status.

  1. Utilize o GET e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu serviço, para nomear o seu indexante.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. Reveja a resposta para saber se o indexante está em funcionamento ou para ver informações de erro e aviso.Review the response to learn whether the indexer is running, or to view error and warning information.

Se estiver a utilizar o nível Free, espera-se a seguinte mensagem: "Não foi possível extrair conteúdo ou metadados do seu documento.If you are using the Free tier, the following message is expected: `"Could not extract content or metadata from your document. Texto truncado extraído para caracteres '32768'".Truncated extracted text to '32768' characters". Esta mensagem aparece porque a indexação de blob no nível Livre tem umlimite de 32K na extração de caracteres.This message appears because blob indexing on the Free tier has a32K limit on character extraction. Não verá esta mensagem para este conjunto de dados em níveis mais altos.You won't see this message for this data set on higher tiers.

Nota

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 recipiente de bolhas incluir ficheiros de imagem e o pipeline não manusear imagens, receberá um aviso indicando 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 criou novos campos e informações, vamos fazer algumas perguntas para entender o valor da pesquisa cognitiva, uma vez que se relaciona com um cenário típico de pesquisa.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 que começamos com conteúdo blob, onde todo o documento é embalado em um único content campo.Recall that we started with blob content, where the entire document is packaged into a single content field. Pode pesquisar neste campo e encontrar correspondências para as suas consultas.You can search this field and find matches to your queries.

  1. Utilize o GET e o seguinte URL, substituindo o SEU NOME DE SERVIÇO pelo nome real do seu serviço, para procurar casos de um termo ou frase, devolvendo o content campo 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 deste conteúdo do documento de devolução de consultas, que é o mesmo resultado que obteria se usasse o indexante blob sem o pipeline de 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. Este campo é pesquisável, mas inviável se quiser utilizar facetas, filtros ou precontos automáticos.This field is searchable, but unworkable if you want to use facets, filters, or autocomplete.

    Saída de campo de conteúdoContent field output

  2. Para a segunda consulta, devolva alguns dos novos campos criados pelo oleoduto (pessoas, organizações, localizações, languageCode).For the second query, return some of the new fields created by the pipeline (persons, organizations, locations, languageCode). Estamos a omitir as palavras-chave para a brevidade, mas deve incluí-la 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 da declaração $select contêm novas informações criadas a partir das capacidades naturais de processamento de linguagem dos Serviços Cognitivos.The fields in the $select statement contain new information created from the natural language processing capabilities of Cognitive Services. Como seria de esperar, há algum ruído nos resultados e variações entre documentos, mas em muitos casos, 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 que se segue mostra os resultados da carta aberta de Satya Nadella ao assumir o papel 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 gasodutoPipeline output

  3. Para ver como pode tirar partido destes campos, adicione um parâmetro faceta para devolver 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 local, existem 2 ou 3 partidas.In this example, for each location, there are 2 or 3 matches.

    Saída facetaFacet output

  4. Neste exemplo final, aplique um filtro na recolha das organizações, devolvendo dois fósforos para critérios de filtro baseados no 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
    

Estas consultas ilustram algumas das formas de trabalhar com sintaxe de consulta e filtros em novos 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, consulte Exemplos em Documentos de Busca REST API, exemplos simples de consulta de sintaxee exemplos de consulta de Lucene Completo.For more query examples, see Examples in Search Documents REST API, Simple syntax query examples, and Full Lucene query examples.

Repor e executar novamenteReset and rerun

Nas fases experimentais iniciais de desenvolvimento, a abordagem mais prática para a iteração de design é eliminar os objetos da Azure Cognitive Search e permitir que o seu código os reconstrua.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. Os nomes dos recursos são exclusivos.Resource names are unique. Quando elimina um objeto, pode recriá-lo com o mesmo nome.Deleting an object lets you recreate it using the same name.

Pode utilizar o portal para eliminar índices, indexadores, fontes de dados e skillsets.You can use the portal to delete indexes, indexers, data sources, and skillsets. Quando elimina o indexador, pode, opcionalmente, eliminar seletivamente o índice, o skillset 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.

Eliminar objetos de pesquisaDelete search objects

Ou use DELETE e forneça URLs a cada objeto.Or use DELETE and provide URLs to each object. O seguinte comando elimina um indexante.The following command deletes an indexer.

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

O código de estado 204 é devolvido após uma eliminação com êxito.Status code 204 is returned on successful deletion.

ConclusõesTakeaways

Este tutorial demonstra os passos básicos para criar um pipeline de indexação melhorado através da criação de partes do componente: uma origem de dados, um conjunto de competências, um índice e um 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.

Foram introduzidas competências incorporadas, juntamente com a definição de skillset e a mecânica das habilidades de acorrentamento em conjunto através 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. Também aprendeu que outputFieldMappings na definição do indexante é necessário encaminhar valores enriquecidos do pipeline para um índice pesmável num serviço de Pesquisa Cognitiva 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, aprendeu como testar os resultados e repor o sistema para iterações futuras.Finally, you learned how to test results and reset the system for further iterations. Aprendeu que a emissão de consultas acerca do índice devolve o resultado criado pelo pipeline de indexação melhorado.You learned that issuing queries against the index returns the output created by the enriched indexing pipeline.

Limpar os recursosClean up resources

Quando se está a trabalhar na sua própria subscrição, no final de um projeto, é uma boa ideia remover os recursos de que já não precisa.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. Os recursos que deixar em execução podem custar-lhe dinheiro.Resources left running can cost you money. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.You can delete resources individually or delete the resource group to delete the entire set of resources.

Pode encontrar e gerir recursos no portal, utilizando a ligação de 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.

Passos seguintesNext steps

Agora que está familiarizado com todos os objetos num oleoduto de enriquecimento de IA, vamos olhar mais de perto as definições de skillset e 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.