Поделиться через


Создание или обновление набора навыков (предварительная версия REST API)

применимо к: 2023-07-01-Preview. Эта версия больше не поддерживается. немедленное обновление до более новой версии.

Важный

2023-07-01-Preview (без изменений).

2021-04-30-Preview добавляет поддержку управляемого удостоверения для подключений, связанных с набором навыков:

  • storageConnectionString в хранилище знаний принимает идентификатор ресурса Azure для проверки подлинности Azure AD.
  • "identity" принимает управляемое удостоверение, назначаемое пользователем. Это свойство находится в хранилище знаний. Он также находится в "encryptionKey" для получения ключа, управляемого клиентом, в Azure Key Vault.

Этот API предварительной версии также поддерживает подключение управляемого удостоверения из пользовательского навыка. Дополнительные сведения см. в справочнике по пользовательскому веб-API .

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

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

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

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

Для запросов на обновление используйте PUT и укажите имя набора навыков в URI.

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

HttpS требуется для всех запросов службы.

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

обновление набора навыков полностью перезаписывает существующий набор навыков с содержимым полезных данных запроса. Рекомендуется получить определение набора навыков с помощью GET, изменить его, а затем обновить с помощью PUT.

Заметка

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

Параметры URI

Параметр Описание
Имя службы Обязательно. Присвойте этому свойству уникальное, определяемое пользователем имя службы поиска.
Имя набора навыков Обязательный код ресурса (URI) при использовании PUT. Имя должно быть нижним регистром, начинаться с буквы или числа, не иметь косой черты или точки, а также быть менее 128 символов. После запуска имени с буквой или номером остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
версия API Обязательно. Дополнительные версии API см. в версиях API.
disableCacheReprocessingChangeDetection Необязательный (false по умолчанию). Применяется к сценариям обновления и использованию кэшированных обогащений во время выполнения набора навыков. Установите значение true, чтобы предотвратить обновление существующих документов на основе текущего действия, например, если вы хотите обновить набор навыков без запуска набора навыков. Дополнительные сведения см. в разделе Обход набора навыков.

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

В следующей таблице описаны обязательные и необязательные заголовки запросов.

Поля Описание
Тип контента Обязательно. Задайте для этого свойства значение application/json
api-key Необязательно, если вы используете роли Azure и маркер носителя предоставляется в запросе, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса в службе поиска. Запросы на создание должны содержать заголовок api-key, заданный для ключа администратора (в отличие от ключа запроса). Дополнительные сведения см. в статье Connect to Azure AI Search using key authentication.

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

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

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

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

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

Свойство Описание
имя Обязательно. Имя набора навыков. Имя должно быть нижним регистром, начинаться с буквы или числа, не иметь косой черты или точки, а также быть менее 128 символов. После запуска имени с буквой или номером остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
Навыки Массив навыков. Каждый навык имеет параметры odata.type, name, context и input и output. Справочник по навыкам можно найти в концептуальной документации. Массив может включать встроенные навыки и пользовательских навыков. Требуется по крайней мере один навык. Если вы используете хранилище знаний, добавьте навык фигуры, если вы не определяете фигуру данных в проекции.
CognitiveServices Все один ключ требуется для оплачиваемых навыков, которые вызывают API Cognitive Services более чем на 20 документов ежедневно на индексатор. Ключ должен быть для ресурса в том же регионе, что и служба поиска. Дополнительные сведения см. в разделе Присоединение ресурса Cognitive Services.

Можно опустить ключ и этот раздел, если набор навыков состоит только из пользовательских навыков, служебных навыков (условные, фигурные, слияние текста, разделение текста) или навыка извлечения документов .

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

Ответ

Для успешного запроса вы увидите код состояния "201 Создан".

По умолчанию текст ответа будет содержать JSON для созданного определения набора навыков. Однако если для заголовка запроса Prefer задано значение return=min, текст ответа будет пустым, а код состояния успешного выполнения будет иметь значение "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 и проекции, которые определяют, приземляется ли обогащенное содержимое в хранилище таблиц или 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": "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": { }
}

пример . Подключения с помощью управляемого удостоверения

Управляемые удостоверения можно использовать для подключений к хранилищу знаний и внешнему коду из пользовательского навыка. В этом примере показаны оба сценария. Для хранилища знаний дополнительное свойство identity указывает управляемое удостоверение, назначаемое пользователем службы поиска, которое Azure AD использует для проверки подлинности запроса. Если не указано "identity", используется управляемое удостоверение службы поиска, назначаемое системой. Чтобы Azure AD прошел проверку подлинности вызывающего объекта, служба поиска должна быть настроена для управляемого удостоверения. Удостоверение поиска должно иметь разрешения "Участник данных BLOB-объектов хранилища" для записи в службу хранилища Azure.

Пользовательский навык может использовать управляемое удостоверение для проверки подлинности в функции Azure или приложении, в котором размещен пользовательский код. Он включает свойство authResourceId, указывающее, что подключение проходит проверку подлинности с помощью управляемого удостоверения. Значение authResourceId — это идентификатор приложения, созданный поставщиком удостоверений Майкрософт. Это значение будет использоваться для проверки маркера проверки подлинности, полученного индексатором, и будет отправлен вместе с пользовательским запросом API веб-навыка.

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

пример : ключи шифрования

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

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

Определения

Связь Описание
knowledgeStore Настраивает подключение к хранилищу Azure и обогащенному содержимому проектов в виде объектов, файлов и таблиц для использования сценариев интеллектуального анализа знаний и обработки данных.
encryptionKey Настраивает подключение к Azure Key Vault для шифрования, управляемого клиентом.

knowledgeStore

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

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

Атрибут Описание
storageConnectionString Обязательно. Строка в одном из следующих форматов:

"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]/;"
тождество Необязательный. Он содержит userAssignedIdentity типа #Microsoft.Azure.Search.DataUserAssignedIdentity и указывает управляемое удостоверение, назначаемое пользователем, службы поиска. Это свойство зависит от storageConnectionString строки подключения, указывающей идентификатор ресурса учетной записи хранения.

Если свойство identity имеет значение NULL, подключение к идентификатору ресурса выполняется с помощью управляемого системой свойства.

Если это свойство назначается типу #Microsoft.Azure.Search.DataNoneIdentity, удаляется любое явное удостоверение, указанное ранее.
проекции Обязательно. Массив проекций, состоящий из tables, objects, files, которые указаны или имеют значение NULL.

Проекции

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

Атрибут Описание
Таблицы Проекты фигур данных в одну или несколько таблиц в хранилище таблиц Azure, где элементы из каждого документа проецируются в строки таблицы. Каждая таблица может иметь следующие три свойства.

Во-первых, name (обязательно) определяет таблицу для создания или использования в хранилище таблиц Azure.

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

В-третьих, source (обязательно) — это путь к узлу дерева обогащения, который предоставляет форму проекции. Обычно это выходные данные навыка фигуратора. Пути начинаются с /document/, представляющих корневой обогащенный документ, а затем расширяются до /document/<shaper-output>/или /document/content/или другого узла в дереве обогащения. Примеры: /document/countries/* (все страны) или /document/countries/*/states/* (все государства во всех странах).
Объектов Проекты документов в виде больших двоичных объектов в хранилище BLOB-объектов Azure. Каждый объект имеет два обязательных свойства.

Во-первых, storageContainer — это имя контейнера для создания или использования в хранилище BLOB-объектов Azure.

Во-вторых, source — это путь к узлу дерева обогащения, который предоставляет форму проекции. Он должен быть допустимым в формате JSON. Узел должен предоставить объект JSON либо из навыка, который выдает допустимый json, либо выходные данные навыка фигуры.
Файлы Каждая запись файла определяет хранилище двоичных образов в хранилище BLOB-объектов.

Проекции файлов имеют два обязательных свойства. Во-первых, storageContainer — это имя контейнера для создания или использования в хранилище BLOB-объектов Azure.

Во-вторых, source — это путь к узлу дерева обогащения, который является корнем проекции. Допустимое значение этого свойства "/document/normalized_images/*" для изображений, которые были созданы из хранилища BLOB-объектов.

encryptionKey

Настраивает подключение к Azure Key Vault для дополнительных ключей шифрования, управляемых клиентом (CMK),. Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных служб. Для платных служб она доступна только для служб поиска, созданных в 2019-01-01.01.

Подключение к хранилищу ключей должно пройти проверку подлинности. Для этой цели можно использовать "accessCredentials" или управляемое удостоверение.

Управляемые удостоверения могут быть системными или назначаемыми пользователем (предварительная версия). Если у службы поиска есть управляемое удостоверение, назначаемое системой, и назначение роли, которое предоставляет доступ на чтение к хранилищу ключей, можно пропустить как удостоверение, так и accessCredentials, а запрос будет проходить проверку подлинности с помощью управляемого удостоверения. Если служба поиска имеет назначаемое пользователем удостоверение и назначение ролей, задайте для свойства identity идентификатор ресурса этого удостоверения.

Атрибут Описание
keyVaultKeyName Обязательно. Имя ключа Azure Key Vault, используемого для шифрования.
keyVaultKeyVersion Обязательно. Версия ключа Azure Key Vault.
keyVaultUri Обязательно. URI Azure Key Vault (также называется DNS-именем), который предоставляет ключ. Пример URI может быть https://my-keyvault-name.vault.azure.net.
accessCredentials Опустить, если вы используете управляемое удостоверение. В противном случае свойства accessCredentials включают applicationId (идентификатор приложения Azure Active Directory, имеющий разрешения на доступ к указанному Хранилищу ключей Azure) и applicationSecret (ключ проверки подлинности указанного приложения Azure AD).
тождество Необязательно, если вы не используете управляемое удостоверение, назначаемое пользователем, для подключения службы поиска к Azure Key Vault. Формат "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

См. также