Tutorial REST: Usar conjuntos de habilidades para gerar conteúdo pesquisável no Azure AI Search
Neste tutorial, saiba como chamar APIs REST que criam um pipeline de enriquecimento de IA para extração de conteúdo e transformações durante a indexação.
Os conjuntos de habilidades adicionam processamento de IA ao conteúdo bruto, tornando esse conteúdo mais uniforme e pesquisável. Depois de saber como os conjuntos de habilidades funcionam, você pode dar suporte a uma ampla gama de transformações: desde a análise de imagens até o processamento de linguagem natural e o processamento personalizado que você fornece externamente.
Este tutorial ajuda-o a aprender a:
- Defina objetos em um pipeline de enriquecimento.
- Construa um conjunto de habilidades. Invoque OCR, deteção de idioma, reconhecimento de entidade e extração de frases-chave.
- Execute o pipeline. Crie e carregue um índice de pesquisa.
- Verifique os resultados usando a pesquisa de texto completo.
Se você não tiver uma assinatura do Azure, abra uma conta gratuita antes de começar.
Descrição geral
Este tutorial usa um cliente REST e as APIs REST do Azure AI Search para criar uma fonte de dados, índice, indexador e conjunto de habilidades.
O indexador conduz cada etapa do pipeline, começando com a extração de conteúdo de dados de exemplo (texto e imagens não estruturados) em um contêiner de blob no Armazenamento do Azure.
Depois que o conteúdo é extraído, o conjunto de habilidades executa habilidades internas da Microsoft para encontrar e extrair informações. Essas habilidades incluem Reconhecimento Ótico de Caracteres (OCR) em imagens, deteção de linguagem em texto, extração de frases-chave e reconhecimento de entidades (organizações). Novas informações criadas pelo conjunto de habilidades são enviadas para campos em um índice. Depois que o índice for preenchido, você poderá usar os campos em consultas, facetas e filtros.
Pré-requisitos
Código do Visual Studio com um cliente REST
Nota
Você pode usar um serviço de pesquisa gratuito para este tutorial. A camada gratuita limita você a três índices, três indexadores e três fontes de dados. Este tutorial cria um de cada. Antes de começar, certifique-se de que tem espaço no seu serviço para aceitar os novos recursos.
Transferir ficheiros
Faça o download de um arquivo zip do repositório de dados de exemplo e extraia o conteúdo. Saiba como.
Carregar dados de exemplo para o Armazenamento do Azure
No Armazenamento do Azure, crie um novo contêiner e nomeie-o como cog-search-demo.
Carregue os arquivos de dados de exemplo.
Obtenha uma cadeia de conexão de armazenamento para que você possa formular uma conexão no Azure AI Search.
À esquerda, selecione Teclas de acesso.
Copie a cadeia de conexão para a tecla um ou para a chave dois. A cadeia de conexão é semelhante ao exemplo a seguir:
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
Serviços de IA do Azure
O enriquecimento de IA incorporado é apoiado pelos serviços de IA do Azure, incluindo o serviço de linguagem e o Azure AI Vision para processamento de imagem e linguagem natural. Para pequenas cargas de trabalho como este tutorial, você pode usar a alocação gratuita de vinte transações por indexador. Para cargas de trabalho maiores, anexe um recurso multirregional dos Serviços de IA do Azure a um conjunto de habilidades para preços pré-pagos.
Copiar um URL de serviço de pesquisa e uma chave de API
Para este tutorial, as conexões com o Azure AI Search exigem um ponto de extremidade e uma chave de API. Você pode obter esses valores no portal do Azure.
Entre no portal do Azure, navegue até a página Visão geral do serviço de pesquisa e copie a URL. Um ponto final de exemplo poderá ser parecido com
https://mydemo.search.windows.net.Em Teclas de Configurações>, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Existem duas chaves de administração intercambiáveis. Copie qualquer uma delas.
Configurar o arquivo REST
Inicie o Visual Studio Code e abra o arquivo skillset-tutorial.rest . Consulte Guia de início rápido: pesquisa de texto usando REST se precisar de ajuda com o cliente REST.
Forneça valores para as variáveis: ponto de extremidade do serviço de pesquisa, chave da API de administrador do serviço de pesquisa, um nome de índice, uma cadeia de conexão para sua conta de Armazenamento do Azure e o nome do contêiner de blob.
Criar o pipeline
O enriquecimento da IA é orientado pelo indexador. Esta parte do passo a passo cria quatro objetos: fonte de dados, definição de índice, conjunto de habilidades, indexador.
Passo 1: criar uma origem de dados
Chame Create Data Source para definir a cadeia de conexão para o contêiner Blob que contém os arquivos de dados de exemplo.
### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ds",
"description": null,
"type": "azureblob",
"subtype": null,
"credentials": {
"connectionString": "{{storageConnectionString}}"
},
"container": {
"name": "{{blobContainer}}",
"query": null
},
"dataChangeDetectionPolicy": null,
"dataDeletionDetectionPolicy": null
}
Etapa 2: Criar um conjunto de habilidades
Chame Create Skillset para especificar quais etapas de enriquecimento são aplicadas ao seu conteúdo. As habilidades são executadas em paralelo, a menos que haja uma dependência.
### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ss",
"description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
"cognitiveServices": null,
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"context": "/document/normalized_images/*",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name":"text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name":"offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName" : "merged_text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.SplitSkill",
"textSplitMode": "pages",
"maximumPageLength": 4000,
"defaultLanguageCode": "en",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "textItems",
"targetName": "pages"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"description": "If you have multilingual content, adding a language code is useful for filtering",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "languageName",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"context": "/document/pages/*",
"inputs": [
{
"name": "text",
"source": "/document/pages/*"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyPhrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Organization"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Location"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Person"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "persons",
"targetName": "persons"
}
]
}
]
}
Pontos principais:
O corpo da solicitação especifica as seguintes habilidades internas:
Competência Description Reconhecimento ótico de caracteres Reconhece texto e números em arquivos de imagem. Mesclagem de texto Cria "conteúdo mesclado" que recombina conteúdo separado anteriormente, útil para documentos com imagens incorporadas (PDF, DOCX e assim por diante). As imagens e o texto são separados durante a fase de quebra do documento. A habilidade de mesclagem os recombina inserindo qualquer texto reconhecido, legendas de imagem ou tags criadas durante o enriquecimento no mesmo local de onde a imagem foi extraída no documento. Quando você está trabalhando com conteúdo mesclado em um conjunto de habilidades, esse nó inclui todo o texto no documento, incluindo documentos somente texto que nunca passam por OCR ou análise de imagem. Deteção de Idioma Deteta o idioma e gera um nome ou código de idioma. Em conjuntos de dados multilingues, um campo de idioma pode ser útil para filtros. Reconhecimento de Entidades Extrai os nomes de pessoas, organizações e locais do conteúdo mesclado. Divisão de texto Quebra o conteúdo mesclado grande em partes menores antes de chamar a habilidade de extração de frase-chave. A extração de expressões-chave aceita entradas de 50 000 carateres ou menos. Alguns dos ficheiros de exemplo precisam de ser divididos para caberem dentro deste limite. Extração de Expressões-Chave Retira as principais frases-chave. Cada competência é executada no conteúdo do documento. Durante o processamento, o Azure AI Search quebra cada documento para ler conteúdo de diferentes formatos de arquivo. O texto encontrado proveniente do ficheiro de origem é colocado num campo
contentgerado (um para cada documento). Como tal, a entrada torna-se"/document/content".Para extração de frase-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 frase-chave é
"document/pages/*"(para cada página do documento) em vez de"/document/content".
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. No índice, o código de idioma é útil para a filtragem. Para obter mais informações acerca das noções básicas do conjunto de competências, veja Como definir um conjunto de competências.
Etapa 3: Criar um índice
Chame Create Index para fornecer o esquema usado para criar índices invertidos e outras construções no Azure AI Search.
O maior componente de um índice é a coleção de campos, onde o tipo de dados e os atributos determinam o conteúdo e o comportamento na Pesquisa de IA do Azure. Certifique-se de que tem campos para a saída recém-gerada.
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idx",
"defaultScoringProfile": "",
"fields": [
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "text",
"type": "Collection(Edm.String)",
"facetable": false,
"filterable": true,
"searchable": true,
"sortable": false
},
{
"name": "language",
"type": "Edm.String",
"searchable": false,
"sortable": true,
"filterable": true,
"facetable": false
},
{
"name": "keyPhrases",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "organizations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "persons",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "locations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "metadata_storage_path",
"type": "Edm.String",
"key": true,
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "metadata_storage_name",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
}
]
}
Etapa 4: Criar e executar um indexador
Chame Create Indexer para conduzir o pipeline. Os três componentes que você criou até agora (fonte de dados, conjunto de habilidades, índice) são entradas para um indexador. Criar o indexador no Azure AI Search é o evento que coloca todo o pipeline em movimento.
A conclusão deste passo demora vários minutos. Apesar de o conjunto de dados ser pequeno, as competências analíticas realizam um processo de computação intensa.
### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idxr",
"description": "",
"dataSourceName" : "cog-search-demo-ds",
"targetIndexName" : "cog-search-demo-idx",
"skillsetName" : "cog-search-demo-ss",
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "metadata_storage_path",
"mappingFunction" : { "name" : "base64Encode" }
},
{
"sourceFieldName": "metadata_storage_name",
"targetFieldName": "metadata_storage_name"
}
],
"outputFieldMappings" :
[
{
"sourceFieldName": "/document/merged_text",
"targetFieldName": "content"
},
{
"sourceFieldName" : "/document/normalized_images/*/text",
"targetFieldName" : "text"
},
{
"sourceFieldName" : "/document/organizations",
"targetFieldName" : "organizations"
},
{
"sourceFieldName": "/document/language",
"targetFieldName": "language"
},
{
"sourceFieldName" : "/document/persons",
"targetFieldName" : "persons"
},
{
"sourceFieldName" : "/document/locations",
"targetFieldName" : "locations"
},
{
"sourceFieldName" : "/document/pages/*/keyPhrases/*",
"targetFieldName" : "keyPhrases"
}
],
"parameters":
{
"batchSize": 1,
"maxFailedItems":-1,
"maxFailedItemsPerBatch":-1,
"configuration":
{
"dataToExtract": "contentAndMetadata",
"imageAction": "generateNormalizedImages"
}
}
}
Pontos principais:
O corpo da solicitação inclui referências aos objetos anteriores, propriedades de configuração necessárias para o processamento de imagens e dois tipos de mapeamentos de campo.
"fieldMappings"são processados antes do conjunto de habilidades, enviando conteúdo da fonte de dados para campos de destino em um índice. Você usa mapeamentos de campo para enviar conteúdo existente e não modificado para o índice. Se os nomes e tipos de campo forem os mesmos em ambas as extremidades, nenhum mapeamento será necessário."outputFieldMappings"são para campos criados por competências, após a execução de competências. As referências a inoutputFieldMappingsnão existem até que asourceFieldNamequebra ou enriquecimento de documentos as crie. OtargetFieldNameé um campo em um índice, definido no esquema de índice.O
"maxFailedItems"parâmetro é definido como -1, que instrui o mecanismo de indexação a ignorar erros durante a importação de dados. Isso é aceitável porque há tão poucos documentos na fonte de dados de demonstração. Para uma origem de dados maior, deve definir o valor com um número maior que 0.A
"dataToExtract":"contentAndMetadata"instrução diz ao indexador para extrair automaticamente os valores da propriedade content do blob e os metadados de cada objeto.O
imageActionparâmetro diz ao indexador para extrair texto de imagens encontradas na fonte de dados. A"imageAction":"generateNormalizedImages"configuração, combinada com a Habilidade OCR e a Habilidade de Mesclagem de Texto, diz ao indexador para extrair texto das imagens (por exemplo, a palavra "parar" de um sinal de parada de trânsito) e incorporá-lo como parte do campo de conteúdo. Esse comportamento se aplica a imagens incorporadas (pense em uma imagem dentro de um PDF) e arquivos de imagem autônomos, por exemplo, um arquivo JPG.
Nota
A criação de um indexador invoca o 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. Para executar novamente o pipeline com as alterações de código ou script, pode ter de remover primeiro os objetos. Para obter mais informações, veja Repor e executar novamente.
Monitorar indexação
A indexação e o enriquecimento começam assim que você envia a solicitação Criar indexador. Dependendo da complexidade do conjunto de habilidades e das operações, a indexação pode demorar um pouco.
Para saber se o indexador ainda está em execução, chame Obter Status do Indexador para verificar o status do indexador.
### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Pontos principais:
Os avisos são comuns em alguns cenários e nem sempre indicam um problema. Por exemplo, se um contêiner de blob incluir arquivos de imagem e o pipeline não manipular imagens, você receberá um aviso informando que as imagens não foram processadas.
Neste exemplo, há um arquivo PNG que não contém texto. Todas as cinco habilidades baseadas em texto (deteção de idioma, reconhecimento de entidade de locais, organizações, pessoas e extração de frases-chave) não são executadas neste arquivo. A notificação resultante aparece no histórico de execução.
Ver resultados
Agora que você criou um índice que contém conteúdo gerado por IA, chame Documentos de Pesquisa para executar algumas consultas e ver os resultados.
### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"select": "metadata_storage_name,language,organizations",
"count": true
}
Os filtros podem ajudá-lo a restringir os resultados a itens de interesse:
### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"filter": "organizations/any(organizations: organizations eq 'Microsoft')",
"select": "metadata_storage_name,organizations",
"count": true
}
Essas consultas ilustram algumas das maneiras como você pode trabalhar com sintaxe de consulta e filtros em novos campos criados pelo Azure AI Search. Para obter mais exemplos de consulta, consulte Exemplos na API REST de documentos de pesquisa, Exemplos de consulta de sintaxe simples e Exemplos de consulta Lucene completa.
Repor e executar novamente
Durante os estágios iniciais de desenvolvimento, a iteração sobre o design é comum. Redefinir e executar novamente ajuda na iteração.
Conclusões
Este tutorial demonstra as etapas básicas para usar as APIs REST para criar um pipeline de enriquecimento de IA: uma fonte de dados, conjunto de habilidades, índice e indexador.
Habilidades incorporadas foram introduzidas, juntamente com a definição de conjunto de habilidades que mostra a mecânica de encadear habilidades através de entradas e saídas. Você também aprendeu que outputFieldMappings , na definição do indexador, é necessário rotear valores enriquecidos do pipeline para um índice pesquisável em um serviço de Pesquisa do Azure AI.
Por fim, aprendeu como testar os resultados e repor o sistema para iterações futuras. Aprendeu que a emissão de consultas acerca do índice devolve o resultado criado pelo pipeline de indexação melhorado.
Clean up resources (Limpar recursos)
Quando estiver a trabalhar na sua própria subscrição, no final de um projeto, é uma boa ideia remover os recursos de que já não necessita. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.
Você pode encontrar e gerenciar recursos no portal, usando o link Todos os recursos ou Grupos de recursos no painel de navegação esquerdo.
Próximos passos
Agora que você está familiarizado com todos os objetos em um pipeline de enriquecimento de IA, dê uma olhada mais de perto nas definições do conjunto de habilidades e habilidades individuais.