Criar ou Atualizar Conjunto de Competências (API REST de Pré-visualização)
Aplica-se a: 2023-07-01-Preview, 2021-04-30-Preview
Importante
07-2023-01-Preview (sem alterações).
2021-04-30-Preview adiciona suporte de identidade gerida para ligações relacionadas com conjuntos de competências:
- "storageConnectionString" no arquivo de conhecimento aceita um ID de recurso do Azure para autenticação Azure AD.
- A "identidade" aceita uma identidade gerida atribuída pelo utilizador. Esta propriedade está no arquivo de conhecimento. Também está em "encryptionKey" para obter uma chave gerida pelo cliente no Azure Key Vault.
Esta API de pré-visualização também suporta uma ligação de identidade gerida a partir de uma competência personalizada. Veja Referência da API Web Personalizada para obter detalhes.
Um conjunto de competências é uma coleção de competências cognitivas utilizadas para o melhoramento de IA, com a opção de criar também um arquivo de conhecimento externo no Armazenamento do Azure. As competências invocam o processamento de linguagem natural e outros processos de machine learning, como o reconhecimento de entidades, extração de expressões-chave, segmentação de texto em páginas lógicas, entre outros.
Um conjunto de competências está anexado a um indexador. Para utilizar o conjunto de competências, referencie-o num indexador e, em seguida, execute o indexador para importar dados, invocar o melhoramento e enviar a saída para um índice. Um conjunto de competências é um recurso de alto nível, mas está operacional apenas no processamento do indexador. Como um recurso de alto nível, pode referenciá-lo em vários indexadores.
Pode utilizar POST ou PUT num pedido de criação. Para qualquer um deles, o corpo do pedido 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 pedidos de atualização, utilize PUT e especifique o nome do conjunto de competências no URI.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
O HTTPS é necessário para todos os pedidos de serviço.
Criar um conjunto de competências adiciona-o ao seu serviço de pesquisa.
Atualizar um conjunto de competências substitui totalmente um conjunto de competências existente pelo conteúdo do payload do pedido. Uma melhor prática para atualizações é obter a definição do conjunto de competências com um GET, modificá-lo e, em seguida, atualizar com PUT.
Nota
Os conjuntos de competências são a base do melhoramento de IA. Está disponível um recurso gratuito para processamento limitado, mas para cargas de trabalho maiores ou mais frequentes, anexe um recurso dos Serviços Cognitivos faturável.
Parâmetros do URI
| Parâmetro | Description |
|---|---|
| nome do serviço | Obrigatório. Defina esta propriedade como o nome exclusivo definido pelo utilizador do seu serviço de pesquisa. |
| nome do conjunto de competências | Necessário no URI se estiver a utilizar PUT. O nome tem de ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. Depois de iniciar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e travessões, desde que os traços não sejam consecutivos. |
| api-version | Obrigatório. A versão de pré-visualização atual é 2023-07-01-Preview. Veja Versões da API para obter mais versões. |
| disableCacheReprocessingChangeDetection | Opcional (false por predefinição). Aplica-se a cenários de atualização e à utilização de melhoramentos em cache durante a execução do conjunto de competências. Defina como true para impedir atualizações a documentos existentes com base na ação atual, por exemplo, se quiser atualizar um conjunto de competências sem executar o conjunto de competências. Para obter mais informações, veja Ignorar avaliação de conjuntos de competências. |
Cabeçalhos de Pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.
| Campos | Description |
|---|---|
| Content-Type | Obrigatório. Defina esta propriedade como application/json |
| api-key | Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Uma chave de API é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. A opção Criar pedidos tem de incluir um api-key cabeçalho definido para a chave de administrador (em oposição a uma chave de consulta). Veja Connect to Azure AI Search using key authentication (Ligar à Pesquisa de IA do Azure com a autenticação de chaves ) para obter detalhes. |
Corpo do Pedido
O corpo do pedido contém a definição do conjunto de competências. As competências são autónomas ou agrupadas através de associações de entrada-saída, em que a saída de uma transformação torna-se entrada noutra. Um conjunto de habilidades deve ter pelo menos uma habilidade. Não existe um limite teórico para o número máximo de competências, mas três a cinco é uma configuração comum.
O seguinte JSON é uma representação de alto nível das partes principais 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) { }
}
O pedido contém as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
| name | Obrigatório. O nome do conjunto de competências. O nome tem de ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. Depois de iniciar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e travessões, desde que os traços não sejam consecutivos. |
| competências | Uma variedade de competências. Cada competência tem um parâmetro odata.type, nome, contexto e entrada e saída. A referência de competências pode ser encontrada na documentação conceptual. A matriz pode incluir competências incorporadas e competências personalizadas. Pelo menos uma habilidade é necessária. Se estiver a utilizar um arquivo de conhecimento, inclua uma competência shaper , a menos que esteja a definir a forma de dados na projeção. |
| cognitiveServices | É necessária uma chave tudo-em-um para as competências faturáveis que chamam APIs Serviços Cognitivos em mais de 20 documentos por dia, por indexador. A chave tem de ser para um recurso na mesma região que o serviço de pesquisa. Para obter mais informações, veja Anexar um recurso dos Serviços Cognitivos. Pode omitir a chave e esta secção se o conjunto de competências consistir apenas em competências personalizadas, competências de utilidade (Condicional, Formador, Impressão em Série, Divisão de Texto) ou na competência Extração de Documentos. Se estiver a utilizar a competência Pesquisa de Entidades Personalizadas , inclua esta secção e uma chave para ativar transações para além de 20 transações diárias por indexador. |
| knowledgeStore | Opcional. Destino da saída de melhoramento para o Armazenamento do Azure. Requer uma cadeia de ligação para uma conta de Armazenamento do Azure e projeções. |
| encryptionKey | Opcional. Utilizado para encriptar dados confidenciais numa definição de conjunto de competências com as suas próprias chaves, geridas no seu Key Vault do Azure. Para saber mais, veja Encriptação da Pesquisa de IA do Azure com chaves geridas pelo cliente no Azure Key Vault. |
Resposta
Para um pedido bem-sucedido, deverá ver o código de estado "201 Criado".
Por predefinição, o corpo da resposta irá conter o JSON para a definição do conjunto de competências que foi criada. No entanto, se o cabeçalho do pedido Prefer estiver definido como return=minimal, o corpo da resposta estará vazio e o código de estado de êxito será "204 Sem Conteúdo" em vez de "201 Criado". Isto acontece independentemente de PUT ou POST ser utilizado para criar o conjunto de competências.
Exemplos
Exemplo: Conjunto de competências que reconhece entidades empresariais e sentimentos nas revisões de clientes
Este conjunto de competências utiliza duas competências de forma assíncrona, o processamento /document/content independente como duas transformações diferentes. As competências são o Reconhecimento de Entidades e o Sentimento. Na árvore de melhoramento, /document/content fornece o conteúdo (ou revisões do cliente) da origem 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: arquivo de conhecimentos com acesso total cadeia de ligação e entradas em forma de
Um arquivo de conhecimento requer um cadeia de ligação para uma conta de Armazenamento do Azure e projeções que determinam se o conteúdo melhorado chega ao armazenamento de tabelas ou blobs (como objetos ou ficheiros).
As projeções, especialmente as projeções de tabelas, requerem uma competência do Shaper a montante que recolhe nós de uma árvore de melhoramento como entrada, gerando uma única forma que pode ser transmitida à projeção. Normalmente, um formador é a última competência a ser processada. Numa projeção de tabela, os nós na competência do formador 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: Ligações com uma identidade gerida
As identidades geridas podem ser utilizadas em ligações a um arquivo de conhecimento e a código externo a partir de uma competência personalizada. Este exemplo demonstra ambos os cenários. Para o arquivo de conhecimento, a propriedade "identidade" adicional especifica uma identidade gerida atribuída pelo utilizador do serviço de pesquisa que Azure AD utiliza para autenticar o pedido. Se omitir "identidade", é utilizada a identidade gerida atribuída pelo sistema do serviço de pesquisa. Para que Azure AD a autenticação do autor da chamada, o serviço de pesquisa tem de ser configurado para a identidade gerida. A identidade de pesquisa tem de ter permissões de "Contribuidor de Dados do Blob de Armazenamento" para escrever no Armazenamento do Azure.
Uma competência personalizada pode utilizar uma identidade gerida para autenticação na função ou aplicação do Azure que aloja o código personalizado. Inclui uma propriedade "authResourceId" para indicar que a ligação é autenticada com uma identidade gerida. O valor de "authResourceId" é o ID da aplicação criado pelo fornecedor de Identidade da Microsoft. Este valor será utilizado para validar o token de autenticação obtido pelo indexador e será enviado juntamente com o pedido de API de competência Web personalizado.
{
"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 encriptação
As chaves de encriptação são chaves geridas pelo cliente utilizadas para encriptação suplementar de conteúdo confidencial. Este exemplo mostra como especificar a encriptação gerida pelo cliente num conjunto de competências.
{
"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
| Ligação | Description |
|---|---|
| knowledgeStore | Configura uma ligação ao Armazenamento do Azure e os projetos enriqueceram o conteúdo sob a forma de objetos, ficheiros e tabelas para utilizar cenários de extração de conhecimentos e processamento de dados. |
| encryptionKey | Configura uma ligação ao Azure Key Vault para encriptação gerida pelo cliente. |
knowledgeStore
Um arquivo de conhecimento é um repositório de dados melhorados que criou um conjunto de competências e um pipeline de melhoramento de IA. Reside no Armazenamento do Azure e consiste em projeções de dados sob a forma de objetos, ficheiros e tabelas. É utilizado para cenários de não pesquisa, como extração de conhecimentos, exploração de dados no Power BI ou como um sink de dados para processamento mais a jusante por outras aplicações.
A ligação ao Armazenamento do Microsoft Azure é um cadeia de ligação de acesso total que inclui uma chave ou o ID do recurso de armazenamento, desde que o serviço de pesquisa seja executado numa identidade gerida e tenha uma atribuição de função do Azure que conceda acesso de escrita ao ponto final do arquivo de conhecimento.
| Atributo | Descrição |
|---|---|
| storageConnectionString | Obrigatório. Uma cadeia num 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. Contém um userAssignedIdentity tipo #Microsoft.Azure.Search.DataUserAssignedIdentity e especifica a identidade gerida atribuída pelo utilizador do serviço de pesquisa. Esta propriedade depende de storageConnectionString ter o cadeia de ligação que especifica um ID de Recurso da sua conta de armazenamento. Se a identity propriedade for nula, a ligação a um ID de recurso é efetuada com a propriedade gerida pelo sistema. Se esta propriedade estiver atribuída ao tipo #Microsoft.Azure.Search.DataNoneIdentity, qualquer identidade explícita especificada anteriormente será desmarcada. |
| projeções | Obrigatório. Uma matriz de projeções que consiste em tables, objects, files, que são especificadas ou nulas. |
Projeções
As projeções são definições das estruturas de dados num arquivo de conhecimento. Todos os nomes são definidos pelo utilizador. Pode adotar uma convenção de nomenclatura que o ajuda a identificar conteúdos relacionados no Armazenamento do Microsoft Azure.
| Atributo | Descrição |
|---|---|
| Tabelas | Projeta formas de dados numa ou mais tabelas no Armazenamento de Tabelas do Azure, onde os elementos de cada documento são projetados em linhas numa tabela. Cada tabela pode ter as seguintes três propriedades. Primeiro, name (obrigatório) determina a tabela a criar ou utilizar no Armazenamento de Tabelas do Azure. Em segundo lugar, generatedKeyName (opcional) é o nome de uma coluna que identifica exclusivamente um documento. Os valores desta coluna serão gerados durante o melhoramento. Se omitir, o serviço de pesquisa criará uma coluna de chave predefinida com base no nome da tabela. Em terceiro lugar, source (obrigatório) é o caminho para um nó da árvore de melhoramento que fornece a forma da projeção. Normalmente, é a saída de uma competência do Shaper. Os caminhos começam com /document/, representando o documento melhorado de raiz e, em seguida, são expandidos para /document/<shaper-output>/, ou /document/content/ou outro nó dentro da árvore de melhoramento. 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. Em primeiro lugar, storageContainer é o nome do contentor a criar ou utilizar no Armazenamento de Blobs do Azure. Em segundo lugar, source é o caminho para o nó da árvore de melhoramento que fornece a forma da projeção. Tem de ser um JSON válido. O nó tem de fornecer um objeto JSON, seja a partir de uma competência que emita JSON válido ou a saída de uma competência shaper. |
| ficheiros | Cada entrada de ficheiro define o armazenamento de imagens binárias no Armazenamento de Blobs. As projeções de ficheiros têm duas propriedades necessárias. Em primeiro lugar, storageContainer é o nome do contentor a criar ou utilizar no Armazenamento de Blobs do Azure. Em segundo lugar, source é o caminho para o nó da árvore de melhoramento que é a raiz da projeção. Um valor válido para esta propriedade é "/document/normalized_images/*" para imagens que foram provenientes do Armazenamento de Blobs. |
encryptionKey
Configura uma ligação ao Azure Key Vault para chaves de encriptação (CMK) suplementares geridas pelo cliente. A encriptação com chaves geridas pelo cliente não está disponível para serviços gratuitos. Para serviços faturáveis, só está disponível para serviços de pesquisa criados em ou depois de 2019-01-01.
Uma ligação ao cofre de chaves tem de ser autenticada. Pode utilizar "accessCredentials" ou uma identidade gerida para esta finalidade.
As identidades geridas podem ser atribuídas pelo sistema ou pelo utilizador (pré-visualização). Se o serviço de pesquisa tiver uma identidade gerida atribuída pelo sistema e uma atribuição de função que conceda acesso de leitura ao cofre de chaves, pode omitir "identidade" e "accessCredentials" e o pedido será autenticado com a identidade gerida. Se o serviço de pesquisa tiver a identidade e a atribuição de função atribuídas pelo utilizador, defina a propriedade "identity" como o ID de recurso dessa identidade.
| Atributo | Descrição |
|---|---|
| keyVaultKeyName | Obrigatório. Nome da chave de Key Vault do Azure utilizada para encriptação. |
| keyVaultKeyVersion | Obrigatório. Versão da chave de Key Vault do Azure. |
| keyVaultUri | Obrigatório. 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 | Omitir se estiver a utilizar uma identidade gerida. Caso contrário, as propriedades de incluir applicationId (um ID de accessCredentials Aplicação do Azure Active Directory que tenha permissões de acesso ao Azure Key Vault especificado) e applicationSecret (a chave de autenticação da aplicação Azure AD especificada). |
| identidade | Opcional, a menos que esteja a utilizar uma identidade gerida atribuída pelo utilizador para a ligação do serviço de pesquisa ao Azure Key Vault. O formato é "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]". |