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

  • Статья

indexer stages

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

В этой статье объясняется, как создать набор навыков с помощью REST API, но те же понятия и шаги применяются к другим языкам программирования.

Ниже указаны правила определения набора навыков:

  • Уникальное имя в коллекции наборов навыков. Набор навыков — это ресурс верхнего уровня, который может использоваться любым индексатором.
  • По крайней мере один навык. Три–пять навыков являются типичными. Максимальное значение — 30.
  • В наборе навыков могут повторяться навыки одного и того же типа (например, несколько навыков Shaper).
  • Набор навыков поддерживает цепочки операций, циклов и ветвления.

Индексаторы управляют выполнением набора навыков. Перед тестированием набора навыков требуется индексатор, источник данных и индекс .

Совет

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

Добавление определения набора навыков

Начните с базовой структуры. В REST API создания набора навыков текст запроса создается в ФОРМАТЕ JSON и содержит следующие разделы:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

После имени и описания в наборе навыков указаны четыре основных свойства.

  • skills массив, неупорядоченная коллекция навыков. Навыки могут быть служебными (например, разделение текста), преобразование (на основе ИИ из служб ИИ Azure) или пользовательские навыки, предоставляемые вами. Пример массива навыков представлен в следующем разделе.

  • cognitiveServices используется для оплачиваемых навыков , которые вызывают API служб искусственного интеллекта Azure. Удалите этот раздел, если вы не используете навыки, по которым можно выставлять счета, или пользовательский поиск сущностей. В противном случае подключите какой-либо ресурс.

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

  • encryptionKey(необязательно) указывает Azure Key Vault и ключи, управляемые клиентом, используемые для шифрования конфиденциального содержимого (описания, строка подключения ключей, ключей) в определении набора навыков. Удалите это свойство, если вы не используете шифрование, управляемое клиентом.

Добавление навыков

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

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

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

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

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

Примечание.

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

Настройка контекста навыка

Каждый навык имеет свойство контекста, определяющее уровень, на котором выполняются операции. Если свойство context не задано явным образом, по умолчанию "/document"используется контекст целиком (навык вызывается один раз для каждого документа).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Контекст обычно задан в одном из следующих примеров:

Пример контекста Description
"context": "/document" (по умолчанию) Входные данные и выходные данные находятся на уровне документа.
"context": "/document/pages/*" Некоторые навыки, такие как анализ тональности, выполняются лучше по сравнению с меньшими фрагментами текста. Если вы разбиваете большое поле содержимого на страницы или предложения, контекст должен находиться над каждой частью компонента.
"context": "/document/normalized_images/*" Для содержимого изображения входные и выходные данные — один на изображение в родительском документе.

Контекст также определяет, где выходные данные создаются в дереве обогащения. Например, навык распознавания сущностей возвращает свойство с именем "organizations", записанное как orgs. Если контекст имеет "/document"значение, то узел "организации" добавляется в качестве дочернего "/document"элемента. Если вы хотите ссылаться на этот узел в нисходящих навыках, путь будет."/document/orgs"

Определение входных данных

Навыки чтения из и записи в обогащенный документ. Входные данные навыка указывают источник входящих данных. Часто это корневой узел обогащенного документа. Для больших двоичных объектов типичные входные данные навыка — это свойство содержимого документа.

Справочная документация по навыкам для каждого навыка описывает входные данные, которые он может использовать. Каждый входной код имеет "имя", определяющее определенные входные данные, и "источник", указывающий расположение данных в обогащенном документе. Ниже приведен пример навыка распознавания сущностей:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

  • Навыки могут иметь несколько входных данных. Имя — это определенные входные данные. Для распознавания сущностей определенные входные данные — text и languageCode.

  • Свойство source указывает, какое поле или строку предоставляет обрабатываемое содержимое. Для навыков на основе текста источник — это поле в документе или строке, предоставляющей текст. Для навыков на основе изображений узел, предоставляющий входные данные, нормализуется изображения.

    Пример источника Description
    Source: "/document" Для табличного набора данных документ соответствует строке.
    Source: "/document/content" Для больших двоичных объектов источник обычно является свойством содержимого большого двоичного объекта.
    "source": "/document/some-named-field" Для навыков на основе текста, таких как распознавание сущностей или извлечение ключевых фраз, источник должен быть полем, содержащим достаточное количество текста для анализа, например "описание" или "сводка".
    Source: "/document/normalized_images/*" Для содержимого изображения источник — это изображение, нормализуемое во время взлома документа.

Если навык выполняет итерацию по массиву, контекст и источник входных данных должны включаться /* в правильные позиции.

Определение выходных данных

Каждый навык предназначен для создания определенных типов выходных данных, на которые можно ссылаться по имени в наборе навыков. Выходные данные навыка имеют имя и необязательное значение targetName.

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

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

  • Навыки могут иметь несколько выходных данных. Имя определяет определенный выходной результат. Например, для распознавания сущностей выходные данные могут быть "лица", "расположения", "организации", а также другие.

  • TargetName указывает имя, которое должен иметь этот узел в обогащенном документе. Это полезно, если выходные данные навыка имеют то же имя. Если у вас несколько навыков, возвращающих одинаковые выходные данные, используйте "targetName" для диамбигуации имени в путях узла обогащения. Если целевое имя не указано, свойство name используется для обоих.

В некоторых ситуациях требуется ссылаться на каждый элемент массива отдельно. Предположим, что нужно отдельно передать каждый элемент"/document/orgs" в другой навык. Для этого добавьте звездочку в путь: "/document/orgs/*"

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

Добавление настраиваемого навыка

В этом разделе приведен пример пользовательского навыка. URI указывает на функцию Azure, которая, в свою очередь, вызывает предоставленную вами модель или преобразование. Дополнительные сведения см. в статье о настройке пользовательского интерфейса.

Несмотря на то что пользовательский навык — это выполняемый код, который является внешним по отношению к конвейеру, в массиве навыков это всего лишь еще один навык. Подобно встроенным навыкам он имеет тип, контекст, входные и выходные данные. Он считывает и записывает данные в дерево обогащения так же, как и встроенные навыки. Обратите внимание, что в поле context задается значение "/document/orgs/*" со звездочкой. Это означает, что этап обогащения вызывается для каждой организации из "/document/orgs".

Выходные данные, такие как описание компании в этом примере, создаются для каждой организации, которая идентифицируется. При обращении к узлу на нижнем шаге (например, в извлечении ключевых фраз) вы будете использовать путь "/document/orgs/*/companyDescription" для этого.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Отправка выходных данных в место назначения

Хотя выходные данные навыка можно кэшировать при необходимости для повторного использования, обычно это временно и существует только во время выполнения навыка.

  • Чтобы отправить выходные данные в какое-либо поле в индексе поиска, создайте сопоставление поля выходных данных в индексаторе.

  • Чтобы отправить выходные данные в хранилище знаний, создайте проекцию.

  • Чтобы отправить выходные данные в подчиненный навык, наведите ссылку на выходные данные по имени узла, например "/document/organization"в свойстве источника входного источника нижестоящего навыка. Примеры см. в статье "Ссылка на заметку ".

Советы по созданию первого набора навыков

  • Попробуйте мастер импорта данных.

    Мастер автоматизирует несколько шагов, которые могут быть сложными в первый раз. Он определяет набор навыков, индекс и индексатор, включая сопоставления полей и сопоставления выходных полей. Он также определяет проекции в хранилище знаний, если вы используете его. Для некоторых навыков, таких как анализ OCR или изображения, мастер добавляет служебные навыки, которые объединяют содержимое изображения и текста, разделенное во время взлома документов.

    После запуска мастера можно открыть каждый объект в портал Azure, чтобы просмотреть его определение JSON.

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

Следующие шаги

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

Ссылки на аннотации в наборе навыков Когнитивного поиска Azure