Criar ou atualizar conjunto de habilidades (Versão prévia da API REST)
Aplica-se a: 2023-07-01-Preview, 2021-04-30-Preview
Importante
2023-07-01-Preview (sem alterações).
2021-04-30-Preview adiciona suporte de identidade gerenciada para conexões relacionadas ao conjunto de habilidades:
- "storageConnectionString" no repositório de conhecimento aceita uma ID de recurso do Azure para autenticação Azure AD.
- A "identidade" aceita uma identidade gerenciada atribuída pelo usuário. Essa propriedade está no repositório de conhecimento. Ele também está em "encryptionKey" para recuperar uma chave gerenciada pelo cliente no Azure Key Vault.
Essa API de visualização também dá suporte a uma conexão de identidade gerenciada de uma habilidade personalizada. Confira Referência de API Web personalizada para obter detalhes.
Um conjunto de habilidades é uma coleção de habilidades cognitivas usadas para enriquecimento de IA, com a opção de também criar um repositório de conhecimento externo no Armazenamento do Azure. As habilidades invocam o processamento de linguagem natural e outros processos de aprendizado de máquina, como reconhecimento de entidade, extração de frases-chave, agrupamento de texto em páginas lógicas, entre outros.
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 o enriquecimento e enviar a 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 referenciá-lo em vários indexadores.
Você pode usar POST ou PUT em uma solicitação de criação. Para qualquer um deles, o corpo da solicitação fornece a definição do objeto.
POST https://[service name].search.windows.net/skillsets?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Para solicitações de atualização, use PUT e especifique o nome do conjunto de habilidades no URI.
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.
A criação de um conjunto de habilidades o adiciona ao serviço de pesquisa.
Atualizar um conjunto de habilidades substitui totalmente um conjunto de habilidades existente pelo conteúdo do conteúdo da solicitação. Uma prática recomendada para atualizações é recuperar a definição do conjunto de habilidades com um GET, modificá-la e, em seguida, atualizá-la com PUT.
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, anexe um recurso faturável dos Serviços Cognitivos.
Parâmetros de URI
| Parâmetro | Descrição |
|---|---|
| nome do serviço | Obrigatórios. Defina essa propriedade 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. Depois de iniciar o nome com uma letra ou número, 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. A versão prévia atual é 2023-07-01-Preview. Confira Versões de API para obter mais versões. |
| disableCacheReprocessingChangeDetection | Opcional (false por padrão). Aplica-se a cenários de atualização e ao uso de enriquecimentos armazenados em cache durante a execução do conjunto de habilidades. Defina como true para evitar atualizações em documentos existentes com base na ação atual, por exemplo, se você quiser atualizar um conjunto de habilidades sem executar o conjunto de habilidades. Para obter mais informações, consulte Ignorar a avaliação do conjunto de habilidades. |
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 essa propriedade 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. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. 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á nenhum limite teórico no número máximo de habilidades, mas as 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. Depois de iniciar o nome com uma letra ou número, 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 referência de habilidades pode ser encontrada na documentação conceitual. 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 do 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. Você pode omitir a chave e esta 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ê 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. |
| 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. |
| encryptionKey | Opcional. Usado para criptografar dados confidenciais em uma definição de conjunto de habilidades com suas próprias chaves, gerenciadas no Key Vault do Azure. Para saber mais, confira Criptografia do Azure AI Search usando chaves gerenciadas pelo cliente no Azure Key Vault. |
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. Porém, se o cabeçalho da solicitação preferido for definido como retorno=mínimo , o corpo da resposta estará vazio e o código de status de êxito será "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 com acesso completo cadeia de conexão e entradas formadas
Um repositório de conhecimento requer uma cadeia de conexão a 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).
Projeções, especialmente projeções de tabela, 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. Em uma projeção de tabela, os nós na habilidade do shaper determinam os campos na tabela.
{
"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": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Exemplo: conexões usando uma identidade gerenciada
As identidades gerenciadas podem ser usadas em conexões com um repositório de conhecimento e com o código externo de uma habilidade personalizada. Este exemplo demonstra os dois cenários. Para o repositório de conhecimento, a propriedade "identity" adicional especifica uma identidade gerenciada atribuída pelo usuário do serviço de pesquisa que Azure AD usa para autenticar a solicitação. Se você omitir "identidade", a identidade gerenciada atribuída pelo sistema do serviço de pesquisa será usada. Para que Azure AD autentique o chamador, o serviço de pesquisa deve ser configurado para identidade gerenciada. A identidade de pesquisa deve ter permissões de "Colaborador de Dados de Blob de Armazenamento" para gravar no Armazenamento do Azure.
Uma habilidade personalizada pode usar uma identidade gerenciada para autenticação na função ou aplicativo do Azure que hospeda seu código personalizado. Ele inclui uma propriedade "authResourceId" para indicar que a conexão é autenticada usando uma identidade gerenciada. O valor de "authResourceId" é a ID do aplicativo criada pelo provedor de Identidade da Microsoft. Esse valor será usado para validar o token de autenticação recuperado pelo indexador e será enviado junto com a solicitação de API de habilidade da Web personalizada.
{
"name": "reviews-ss",
"description": "A short description",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"name": "sampleCustomSkill",
"description": "A custom skill that requests an access token for the application ID specified in authResourceID",
"context": "/document",
"uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
"authResourceId": "api://xyz*****-****-****-****-********9876",
"batchSize": 4,
"degreeOfParallelism": null,
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "language",
"source": "/document/languageCode"
},
{
"name": "phraseList",
"source": "/document/keyphrases"
}
],
"outputs": [
{
"name": "<customSkillOutput>"
}
]
}
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [ ... ],
"outputs": [ ...]
}
],
"cognitiveServices": { ... },
"knowledgeStore": {
"storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
"projections": [
{
"tables": [ ],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Exemplo: chaves de criptografia
Chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia suplementar 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)"}
}
}
Definições
| Link | Descrição |
|---|---|
| knowledgeStore | Configura uma conexão com o Armazenamento do Azure e projeta conteúdo enriquecido na forma de objetos, arquivos e tabelas para usar cenários de mineração de conhecimento e processamento de dados. |
| encryptionKey | Configura uma conexão com o Azure Key Vault para criptografia gerenciada pelo cliente. |
knowledgeStore
Um repositório de conhecimento é um repositório de dados enriquecidos que criou um conjunto de habilidades e um pipeline de enriquecimento de IA. Ele reside no Armazenamento do Azure e consiste em projeções de dados na forma de objetos, arquivos e tabelas. Ele é usado para cenários que não são de pesquisa, como mineração de conhecimento, exploração de dados no Power BI ou como um coletor de dados para processamento mais downstream por outros aplicativos.
A conexão com o Armazenamento do Azure é uma cadeia de conexão de acesso completo que inclui uma chave ou a ID do recurso de armazenamento fornecida que o serviço de pesquisa é executado em uma identidade gerenciada e tem uma atribuição de função do Azure que concede acesso de gravação ao ponto de extremidade do repositório de conhecimento.
| Atributo | Descrição |
|---|---|
| storageConnectionString | Obrigatórios. Uma cadeia de caracteres em um destes formatos:"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net""ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;" |
| identidade | Opcional. Ele contém um userAssignedIdentity do tipo #Microsoft.Azure.Search.DataUserAssignedIdentity e especifica a identidade gerenciada atribuída pelo usuário do serviço de pesquisa. Essa propriedade depende storageConnectionString de ter o cadeia de conexão que especifica uma ID de recurso da sua conta de armazenamento. Se a identity propriedade for nula, a conexão com uma ID de recurso será feita usando a propriedade gerenciada pelo sistema. Se essa propriedade for atribuída ao tipo #Microsoft.Azure.Search.DataNoneIdentity, qualquer identidade explícita especificada anteriormente será desmarcada. |
| projections | Obrigatórios. Uma matriz de projeções que consiste em tables, objects, filesque são especificadas ou nulas. |
Projeções
Projeções são definições das estruturas de dados em um repositório de conhecimento. Todos os nomes são definidos pelo usuário. Você pode adotar uma convenção de nomenclatura que ajuda a identificar conteúdo relacionado no Armazenamento do Azure.
| Atributo | Descrição |
|---|---|
| tabelas | Projeta formas de dados em uma ou mais tabelas no Armazenamento de Tabelas do Azure, em que os elementos de cada documento são projetados em linhas em uma tabela. Cada tabela pode ter as três propriedades a seguir. Primeiro, name (obrigatório) determina a tabela a ser criada ou usada no Armazenamento de Tabelas do Azure. Segundo, generatedKeyName (opcional) é o nome de uma coluna que identifica exclusivamente um documento. Os valores dessa coluna serão gerados durante o enriquecimento. Se você omitir, o serviço de pesquisa criará uma coluna de chave padrão com base no nome da tabela. Terceiro, source (obrigatório) é o caminho para um nó da árvore de enriquecimento que fornece a forma da projeção. Geralmente, é a saída de uma habilidade do Shaper. Os caminhos começam com /document/, representando o documento enriquecido raiz e, em seguida, são estendidos para /document/<shaper-output>/, ou /document/content/ou outro nó dentro da árvore de enriquecimento. Exemplos: /document/countries/* (todos os países) ou /document/countries/*/states/* (todos os estados em todos os países). |
| objetos | Projeta documentos como blobs no Armazenamento de Blobs do Azure. Cada objeto tem duas propriedades necessárias. Primeiro, storageContainer é o nome do contêiner a ser criado ou usado em Armazenamento de Blobs do Azure. Em segundo lugar, source é o caminho para o nó da árvore de enriquecimento que fornece a forma da projeção. Ele deve ser JSON válido. O nó deve fornecer um objeto JSON, seja de uma habilidade que emita JSON válido ou da saída de uma habilidade shaper. |
| 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. Primeiro, storageContainer é o nome do contêiner a ser criado ou usado em Armazenamento de Blobs do Azure. Segundo, source é o caminho para o nó da árvore de enriquecimento que é a raiz da projeção. Um valor válido para essa propriedade é "/document/normalized_images/*" para imagens que foram originadas do Armazenamento de Blobs. |
encryptionKey
Configura uma conexão com o Azure Key Vault para CMK (chaves de criptografia gerenciadas pelo cliente) complementares. A criptografia com chaves gerenciadas pelo cliente não está disponível para serviços gratuitos. Para serviços faturáveis, ele só está disponível para serviços de pesquisa criados em ou após 01/01/2019.
Uma conexão com o cofre de chaves deve ser autenticada. Você pode usar "accessCredentials" ou uma identidade gerenciada para essa finalidade.
As identidades gerenciadas podem ser atribuídas pelo sistema ou pelo usuário (versão prévia). Se o serviço de pesquisa tiver uma identidade gerenciada atribuída pelo sistema e uma atribuição de função que conceda acesso de leitura ao cofre de chaves, você poderá omitir "identidade" e "accessCredentials", e a solicitação será autenticada usando a identidade gerenciada. Se o serviço de pesquisa tiver atribuição de função e identidade atribuída pelo usuário, defina a propriedade "identity" como a ID do recurso dessa identidade.
| Atributo | Descrição |
|---|---|
| keyVaultKeyName | Obrigatórios. Nome da chave de Key Vault do Azure usada para criptografia. |
| keyVaultKeyVersion | Obrigatórios. Versão da chave de Key Vault do Azure. |
| keyVaultUri | Obrigatórios. URI do Azure Key Vault (também conhecido como nome DNS) que fornece a chave. Um URI de exemplo pode ser https://my-keyvault-name.vault.azure.net. |
| accessCredentials | Omita se você estiver usando uma identidade gerenciada. Caso contrário, as propriedades de incluem applicationId (uma ID de accessCredentials Aplicativo do Azure Active Directory que tem permissões de acesso para o Azure Key Vault especificado) e applicationSecret (a chave de autenticação do aplicativo Azure AD especificado). |
| identidade | Opcional, a menos que você esteja usando uma identidade gerenciada atribuída pelo usuário para a conexão do serviço de pesquisa com o Azure Key Vault. O formato é "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]". |