Criar Conjunto de Competências (API REST do Azure AI Search)
Um conjunto de competências é uma coleção de competências cognitivas utilizadas para o melhoramento de IA, com uma especificação opcional para criar um arquivo de conhecimento externo no Armazenamento do Azure. As competências invocam o processamento de linguagem natural e outras transformações, como o reconhecimento de entidades, a extração de expressões-chave, a segmentação de texto em páginas lógicas, entre outras.
Um conjunto de competências é anexado a um indexador. Para utilizar o conjunto de competências, referencie-o num indexador e, em seguida, execute o indexador para importar dados, invoque transformações e melhoramento e mapeie os campos de saída para um índice. Um conjunto de competências é um recurso de alto nível, mas está operacional apenas no processamento de indexador. Como um recurso de alto nível, pode criar um conjunto de competências uma vez e, em seguida, referenciar o mesmo em vários indexadores.
Pode utilizar POST ou PUT no pedido. Para qualquer um deles, o documento JSON no corpo do pedido fornece a definição do objeto.
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. Se o conjunto de competências não existir, será criado. Se já existir, será atualizado para a nova definição.
Nota
Os conjuntos de competências são a base do melhoramento da IA. Está disponível um recurso gratuito para processamento limitado, mas para cargas de trabalho maiores ou mais frequentes, é necessário um recurso dos Serviços Cognitivos faturável .
Parâmetros do URI
| Parâmetro | Description |
|---|---|
| nome do serviço | Obrigatório. Defina-o como o nome exclusivo e definido pelo utilizador do seu serviço de pesquisa. |
| nome do conjunto de competências | Necessário no URI se utilizar PUT. O nome tem de ser minúscula, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. O nome tem de começar com uma letra ou número, mas o resto do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos. |
| api-version | Obrigatório. Veja Versões da API para obter uma lista de versões suportadas. |
Cabeçalhos do Pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.
| Campos | Description |
|---|---|
| Content-Type | Obrigatório. Defina esta opção 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. Criar pedidos tem de incluir um api-key cabeçalho definido para a sua chave de administrador (em oposição a uma chave de consulta). Veja 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 acorrentados 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 competências deve ter pelo menos uma habilidade. Não há 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úscula, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. O nome tem de começar com uma letra ou número, mas o resto do nome pode incluir qualquer letra, número e traços, 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 matriz pode incluir competências incorporadas e competências personalizadas. Pelo menos é necessária uma competência. Se estiver a utilizar um arquivo de conhecimento, inclua uma competência do 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. Se estiver a utilizar a competência de 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. Não precisa da Chave dos Serviços Cognitivos, pelo que pode excluir cognitiveServices a secção se o conjunto de competências consistir apenas em competências personalizadas, competências de utilidade (Condicional, Shaper, Impressão em Série de Texto, Divisão de Texto) ou a competência de Extração de Documentos. Se quiser remover o recurso do serviço cognitivo anexado de um conjunto de competências (para reverter para a utilização dos limites "predefinidos"), especifique @odata.type como #Microsoft.Azure.Search.DefaultCognitiveServices, consulte este exemplo para obter mais informações. |
| knowledgeStore | Opcional. Destino para a 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. storageConnectionString (obrigatório) Uma cadeia neste formato: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections (obrigatório) Uma matriz de objetos de projeção compostos por tables, objects, files, que são especificados ou nulos. tablesCria uma ou mais tabelas no Armazenamento de Tabelas do Azure, projetando conteúdos de cada documento como linhas numa tabela. Cada tabela pode ter as seguintes três propriedades:
objectsProjeta documentos como blobs no Armazenamento de Blobs do Azure. Cada objeto tem duas propriedades necessárias:
filesCada 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:
|
| encryptionKey | Opcional. Utilizado para encriptar uma definição de conjunto de competências inativo com as suas próprias chaves, gerida no seu Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou depois de 2019-01-01. Uma encryptionKey secção contém uma definição do keyVaultKeyName utilizador (necessária), uma gerada pelo keyVaultKeyVersion sistema (necessária) e uma keyVaultUri chave fornecida (necessária, também referida como nome DNS). Um URI de exemplo pode ser "https://my-keyvault-name.vault.azure.net". Opcionalmente, pode especificar accessCredentials se não está a utilizar uma identidade de sistema gerida. Propriedades de accessCredentials include applicationId (Microsoft Entra ID ID da aplicação a quem foram concedidas permissões de acesso ao seu Key Vault do Azure especificado) e applicationSecret (chave de autenticação da aplicação registada). Um exemplo na secção seguinte ilustra a sintaxe. |
Resposta
Para um pedido com êxito, 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 Prefer pedido estiver definido como return=minimal, o corpo da resposta está vazio e o código de estado de êxito é "204 Sem Conteúdo" em vez de "201 Criado". Isto é verdade 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 Reconhecimento de Entidades e 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 conhecimento
Opcionalmente, um conjunto de competências pode enviar saída para o arquivo de conhecimentos no Armazenamento do Azure. Requer uma cadeia de ligação para uma conta de Armazenamento do Azure e projeções que determinam se os conteúdos melhorados aterram no armazenamento de tabelas ou blobs (como objetos ou ficheiros). Normalmente, as projeções requerem uma competência do Shaper a montante que recolhe nós de uma árvore de melhoramento como entrada, o que resulta numa única forma que pode ser transmitida à projeção. Normalmente, um shaper é a última competência 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 encriptação
As chaves de encriptação são chaves geridas pelo cliente utilizadas para encriptação adicional de conteúdo confidencial. Este exemplo mostra-lhe 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)"}
}
}