Criar conjunto de habilidades (API REST do Azure AI Search)
Um conjunto de habilidades é uma coleção de habilidades cognitivas usadas para enriquecimento de IA, com uma especificação opcional para criar um repositório de conhecimento externo no Armazenamento do Azure. As habilidades invocam o processamento de linguagem natural e outras transformações, como reconhecimento de entidade, extração de frases-chave, agrupamento de texto em páginas lógicas, entre outras.
Um conjunto de habilidades é anexado a um indexador. Para usar o conjunto de habilidades, faça referência a ele em um indexador e execute o indexador para importar dados, invocar transformações e enriquecimento e mapear os campos de saída para um índice. Um conjunto de habilidades é um recurso de alto nível, mas está operacional apenas no processamento do indexador. Como um recurso de alto nível, você pode criar um conjunto de qualificações uma vez e, em seguida, referenciá-lo em vários indexadores.
Você pode usar POST ou PUT na solicitação. Para qualquer um deles, o documento JSON no corpo da solicitação fornece a definição de objeto.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS é necessário para todas as solicitações de serviço. Se o conjunto de habilidades não existir, ele será criado. Se ele já existir, ele será atualizado para a nova definição.
Observação
Os conjuntos de habilidades são a base do enriquecimento de IA. Um recurso gratuito está disponível para processamento limitado, mas para cargas de trabalho maiores ou mais frequentes, um recurso de Serviços Cognitivos faturável é necessário.
Parâmetros de URI
| Parâmetro | Descrição |
|---|---|
| nome do serviço | Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa. |
| nome do conjunto de habilidades | Necessário no URI se estiver usando PUT. O nome deve ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 caracteres. O nome deve começar com uma letra ou número, mas o restante do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos. |
| api-version | Obrigatórios. Confira Versões de API para obter uma lista de versões com suporte. |
Cabeçalhos de solicitação
A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais
| Campos | Descrição |
|---|---|
| Tipo de conteúdo | Obrigatórios. Defina-o como application/json |
| chave de API | Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. As solicitações de criação devem incluir um api-key cabeçalho definido como sua chave de administrador (em vez de uma chave de consulta). Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes. |
Corpo da solicitação
O corpo da solicitação contém a definição do conjunto de habilidades. As habilidades são autônomas ou encadeadas por meio de associações de entrada/saída, em que a saída de uma transformação se torna entrada para outra. Um conjunto de qualificações precisa ter pelo menos uma habilidade. Não há limite teórico no número máximo de habilidades, mas três a cinco é uma configuração comum.
O JSON a seguir é uma representação de alto nível das partes main da definição.
{
"name" : (optional on PUT; required on POST) "Name of the skillset",
"description" : (optional) "Anything you want, or nothing at all",
"skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "Optional. Anything you want, or null",
"key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
},
"knowledgeStore": (optional) { ... },
"encryptionKey": (optional) { }
}
A contém as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
| name | Obrigatórios. O nome do conjunto de habilidades. O nome deve ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 caracteres. O nome deve começar com uma letra ou número, mas o restante do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos. |
| habilidades | Uma matriz de habilidades. Cada habilidade tem um odata.type, nome, contexto e parâmetros de entrada e saída. A matriz pode incluir habilidades internas e habilidades personalizadas. Pelo menos uma habilidade é necessária. Se você estiver usando um repositório de conhecimento, inclua uma habilidade de Shaper , a menos que esteja definindo a forma de dados dentro da projeção. |
| cognitiveServices | Uma chave all-in-one é necessária para habilidades faturáveis que chamam API de Serviços Cognitivos em mais de 20 documentos diariamente, por indexador. A chave deve ser para um recurso na mesma região que o serviço de pesquisa. Para obter mais informações, consulte Anexar um recurso dos Serviços Cognitivos. Se você estiver usando a habilidade pesquisa de entidade personalizada , inclua esta seção e uma chave para habilitar transações além de 20 transações diárias por indexador. Você não precisa da Chave dos Serviços Cognitivos e, portanto, pode excluir cognitiveServices a seção se o conjunto de habilidades consistir apenas em habilidades personalizadas, habilidades de utilitário (Condicional, Shaper, Mesclagem de Texto, Divisão de Texto) ou a habilidade extração de documentos. Se você quiser remover o recurso de serviço cognitivo anexado de um conjunto de habilidades (para reverter usar os limites "padrão") especifique @odata.type como #Microsoft.Azure.Search.DefaultCognitiveServices, consulte este exemplo para obter mais informações. |
| knowledgeStore | Opcional. Destino da saída de enriquecimento para o Armazenamento do Azure. Requer uma cadeia de conexão para uma conta e projeções do Armazenamento do Azure.
storageConnectionString (obrigatório) Uma cadeia de caracteres neste formato: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".
projections (obrigatório) Uma matriz de objetos de tablesprojeção que consiste em , objects, filesque são especificados ou nulos.
tables
Cria uma ou mais tabelas no Armazenamento de Tabelas do Azure, projetando conteúdo de cada documento como linhas em uma tabela. Cada tabela pode ter as três propriedades a seguir:
objects
Projeta documentos como blobs no Armazenamento de Blobs do Azure. Cada objeto tem duas propriedades necessárias:
files
Cada entrada de arquivo define o armazenamento de imagens binárias no Armazenamento de Blobs. As projeções de arquivo têm duas propriedades necessárias:
|
| encryptionKey | Opcional. Usado para criptografar uma definição de conjunto de habilidades em repouso com suas próprias chaves, gerenciadas no Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou após 01-01/2019.
Uma encryptionKey seção contém um definido keyVaultKeyName pelo usuário (obrigatório), um gerado pelo keyVaultKeyVersion sistema (obrigatório) e um keyVaultUri que fornece a chave (obrigatório, também conhecido como nome DNS). Um exemplo de URI pode ser "https://my-keyvault-name.vault.azure.net".
Opcionalmente, você pode especificar accessCredentials se não está usando uma identidade do sistema gerenciado. Propriedades de accessCredentials include applicationId (Microsoft Entra ID ID do aplicativo que recebeu permissões de acesso para o Key Vault do Azure especificado) e applicationSecret (chave de autenticação do aplicativo registrado). Um exemplo na próxima seção ilustra a sintaxe. |
Resposta
Para uma solicitação bem-sucedida, você deverá ver o código de status “201 (Criado)”.
Por padrão, o corpo da resposta conterá o JSON para a definição de índice que foi criado. No entanto, se o cabeçalho da Prefer solicitação estiver definido como return=minimal, o corpo da resposta estará vazio e o êxito status código for "204 Sem Conteúdo" em vez de "201 Criado". Isso ocorre independentemente de PUT ou POST ter sido usado para criar o conjunto de qualificações.
Exemplos
Exemplo: Conjunto de habilidades que reconhece entidades de negócios e sentimento nas revisões do cliente
Esse conjunto de habilidades usa duas habilidades de maneira assíncrona, processando /document/content independentemente como duas transformações diferentes. As habilidades são Reconhecimento de Entidade e Sentimento. Na árvore de enriquecimento, /document/content fornece o conteúdo (ou revisões do cliente) da fonte de dados externa.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"context": "/document/content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "companyName"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "languageCode",
"source": "/document/languageCode"
}
],
"outputs": [
{
"name": "sentiment",
"targetName": "reviewSentiment"
},
{
"name": "confidenceScores",
"targetName": "sentimentScore"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": { },
"encryptionKey": { }
}
Exemplo: repositório de conhecimento
Opcionalmente, um conjunto de habilidades pode enviar saída para o repositório de conhecimento no Armazenamento do Azure. Ele requer uma cadeia de conexão para uma conta de Armazenamento do Azure e projeções que determinam se o conteúdo enriquecido chega no armazenamento de blobs ou tabela (como objetos ou arquivos). As projeções geralmente exigem uma habilidade upstream Shaper que coleta nós de uma árvore de enriquecimento como entrada, gerando uma única forma que pode ser passada para projeção. Normalmente, um shaper é a última habilidade a ser processada.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [
{
"name": "Company",
"source": "/document/content/companyName"
},
{
"name": "Sentiment_Score",
"source": "/document/content/sentimentScore"
},
{
"name": "Sentiment_Label",
"source": "/document/content/reviewSentiment"
}
],
"outputs": [
{
"name": "output",
"targetName": "shapeCustomerReviews"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": {
"storageConnectionString": "<your storage account connection string>",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Exemplo: chaves de criptografia
Chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia adicional de conteúdo confidencial. Este exemplo mostra como especificar a criptografia gerenciada pelo cliente em um conjunto de habilidades.
{
"name": "reviews-ss",
"description": "A brief description of the skillset",
"skills": [ omitted for brevity ],
"cognitiveServices": { omitted for brevity },
"knowledgeStore": { omitted for brevity },
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": (optional, only if not using managed system identity) {
"applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
"applicationSecret": "Authentication key of the specified Azure AD application)"}
}
}