Создание набора навыков (REST API поиска ИИ Azure)

Набор навыков — это набор когнитивных навыков , используемых для обогащения ИИ, с необязательной спецификацией для создания внешнего хранилища знаний в службе хранилища Azure. Навыки вызывают обработку естественного языка и другие преобразования, такие как распознавание сущностей, извлечение ключевых фраз, разделение текста на логические страницы и т. д.

Набор навыков присоединяется к индексатору. Чтобы использовать набор навыков, ссылайтесь на него в индексаторе, а затем запустите индексатор для импорта данных, вызова преобразований и обогащения, а также сопоставления полей выходных данных с индексом. Набор навыков — это ресурс высокого уровня, но он работает только при обработке индексатора. Как высокоуровневый ресурс набор навыков можно разработать один раз, а затем ссылаться на него в нескольких индексаторах.

Для запроса можно использовать POST или PUT. Для любого из них документ JSON в тексте запроса предоставляет определение объекта.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json  
  api-key: [admin key]  

Все запросы к службе отправляются по протоколу HTTPS. Если набор навыков не существует, он создается. Если он уже существует, он обновляется до нового определения.

Примечание

Наборы навыков являются основой обогащения на основе ИИ. Бесплатный ресурс доступен для ограниченной обработки, но для больших или частых рабочих нагрузок требуется оплачиваемый ресурс Cognitive Services .

Параметры URI

Параметр	Описание
имя службы	Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска.
имя набора навыков	Требуется для URI, если используется PUT. Имя должно быть строчным, начинаться с буквы или цифры, не содержать косых черт или точек и содержать менее 128 символов. Имя должно начинаться с буквы или цифры, но остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
api-version	Обязательный. Список поддерживаемых версий см. в разделе Версии API.

Заголовки запросов

Таблица ниже содержит обязательные и необязательные заголовки запроса.

Поля	Описание
Content-Type	Обязательный. Для этого заголовка необходимо задать значение application/json
api-key	Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Запросы на создание должны включать заголовок, заданный api-key для ключа администратора (в отличие от ключа запроса). Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу .

Текст запроса

Текст запроса содержит определение набора навыков. Навыки являются автономными или связаны друг с другом через связи "вход-вывод", где выходные данные одного преобразования становятся входными данными другого. В наборе навыков должен быть хотя бы один навык. Теоретических ограничений на максимальное количество навыков нет, но от трех до пяти — это общая конфигурация.

Следующий код JSON представляет собой общее представление main частей определения.

{   
  "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) { }
} 

Запрос содержит следующие свойства.

Свойство	Описание
name	Обязательный. Имя набора навыков. Имя должно быть строчным, начинаться с буквы или цифры, не содержать косых черт или точек и содержать менее 128 символов. Имя должно начинаться с буквы или цифры, но остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
навыки	Массив навыков. Каждый навык имеет odata.type, имя, контекст, а также входные и выходные параметры. Массив может включать встроенные навыки и пользовательские навыки. Требуется по крайней мере один навык. Если вы используете хранилище знаний, добавьте навык формировщика , если вы не определяете фигуру данных в проекции.
cognitiveServices	Ключ "все в одном" требуется для оплачиваемых навыков, которые вызывают API-интерфейсы Cognitive Services в более чем 20 документах в день на индексатор. Ключ должен быть для ресурса в том же регионе, что и служба поиска. Дополнительные сведения см. в статье Присоединение ресурса Cognitive Services. Если вы используете навык пользовательского поиска сущностей , включите этот раздел и ключ, чтобы включить транзакции, превышающие 20 транзакций в день на индексатор. Вам не нужен ключ Cognitive Services, поэтому можно исключить cognitiveServices раздел, если набор навыков состоит только из пользовательских навыков, служебных навыков (условные навыки, формировщик, объединение текста, разделение текста) или навык извлечения документов. Если вы хотите удалить подключенный ресурс когнитивной службы из набора навыков (для отменить изменения использования ограничений по умолчанию) укажите @odata.type как #Microsoft.Azure.Search.DefaultCognitiveServices, дополнительные сведения см. в этом примере.
knowledgeStore	Необязательный элемент. Назначение для вывода обогащения в службу хранилища Azure. Требуется строка подключения к учетной записи хранения Azure и проекциям. storageConnectionString (обязательно) Строка в следующем формате: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections (обязательно) Массив объектов проекции, состоящий из tables, objects, filesкоторые либо заданы, либо имеют значение NULL. tables Создает одну или несколько таблиц в хранилище таблиц Azure, проецируя содержимое из каждого документа в виде строк в таблице. Каждая таблица может иметь следующие три свойства: name (обязательно) определяет таблицу для создания или использования в хранилище таблиц Azure. generatedKeyName (необязательно) — имя столбца, который однозначно идентифицирует документ. Значения для этого столбца будут создаваться во время обогащения. Если опустить его, служба поиска создаст ключевой столбец по умолчанию на основе имени таблицы. source (обязательно) — это путь к узлу дерева обогащения, который предоставляет форму проекции. Обычно это выходные данные навыка формировщика. Пути начинаются с /document/, представляющего корневой обогащенный документ, а затем расширяются до /document/<shaper-output>/, или /document/content/или другого узла в дереве обогащения. Примеры: /document/countries/* (все страны) или /document/countries/*/states/* (все государства во всех странах). objects Проекты документов в виде больших двоичных объектов в Хранилище BLOB-объектов Azure. Каждый объект имеет два обязательных свойства: storageContainer— это имя контейнера для создания или использования в Хранилище BLOB-объектов Azure. source — это путь к узлу дерева обогащения, который предоставляет форму проекции. Это должен быть допустимый код JSON. Узел должен предоставить объект JSON либо из навыка, который выдает допустимый КОД JSON, либо выходные данные навыка Формировщика. files Каждая запись файла определяет хранение двоичных образов в хранилище BLOB-объектов. Проекции файлов имеют два обязательных свойства: storageContainer— это имя контейнера для создания или использования в Хранилище BLOB-объектов Azure. source — это путь к узлу дерева обогащения, который является корнем проекции. Допустимое значение для этого свойства — "/document/normalized_images/*" для образов, полученных из хранилища BLOB-объектов.
encryptionKey	Необязательный элемент. Используется для шифрования определения неактивного набора навыков с помощью собственных ключей, управляемых в Key Vault Azure. Доступно для оплачиваемых служб поиска, созданных в 01.01.2019 или позже. Раздел encryptionKey содержит определяемые keyVaultKeyName пользователем (обязательные), созданные keyVaultKeyVersion системой (обязательные) и предоставляющие keyVaultUri ключ (обязательный, также называемый DNS-именем). Примером URI может быть "https://my-keyvault-name.vault.azure.net". При необходимости можно указать accessCredentials , используется ли управляемое системное удостоверение. accessCredentials Свойства include applicationId (Microsoft Entra ID идентификатор приложения, которому были предоставлены разрешения на доступ к указанному Key Vault Azure) и applicationSecret (ключ проверки подлинности зарегистрированного приложения). Пример в следующем разделе иллюстрирует синтаксис .

Ответ

При успешном выполнении запроса возвращается код состояния 201 (создан).

По умолчанию текст ответа содержит объект JSON для созданного определения набора данных. Однако если для заголовка Prefer запроса задано значение return=minimal, текст ответа пуст, а код состояния успешного выполнения — "204 No Content" вместо "201 Created". При этом не играет роли, какой запрос (PUT или POST) используется для создания набора навыков.

Примеры

Пример. Набор навыков, который распознает бизнес-сущности и тональность в отзывах клиентов

Этот набор навыков использует два навыка асинхронно, независимо обрабатывая /document/content как два разных преобразования. К навыкам относятся распознавание сущностей и тональность. В дереве /document/content обогащения предоставляет содержимое (или отзывы клиентов) из внешнего источника данных.

{
  "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": { }
}

Пример: хранилище знаний

Набор навыков может при необходимости отправлять выходные данные в хранилище знаний в службе хранилища Azure. Для этого требуется строка подключения к учетной записи хранения Azure и проекции, которые определяют, попадает ли обогащенное содержимое в таблицу или хранилище BLOB-объектов (в виде объектов или файлов). Для проекций обычно требуется навык вышестоящий формировщика, который собирает узлы из дерева обогащения в качестве входных данных, выводя одну фигуру, которую можно передать в проекцию. Как правило, формировщик является последним навыком для обработки.

{
  "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": { }
}

Пример. Ключи шифрования

Ключи шифрования — это управляемые клиентом ключи, используемые для дополнительного шифрования конфиденциального содержимого. В этом примере показано, как указать управляемое клиентом шифрование в наборе навыков.

{
    "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)"}
    }
}

См. также раздел

• Определение набора навыков
• Общие сведения об обогащении с помощью ИИ
• Обзор набора навыков
• Обзор хранилища знаний
• Общие сведения о проекции
• Руководство. Использование REST и искусственного интеллекта для создания содержимого, доступных для поиска, из blob-объектов
• Встроенные навыки